ab-finishing-a-development-branch

Finishing a Development Branch

Bring finished work to a clean end: verify tests → audit the plan → present options → execute the choice → clean up. Done when the chosen option has run, or the gate blocked it, and the report names the branch and the worktree’s state.

Announce at start: “I’m using the ab-finishing-a-development-branch skill to complete this work.”

Working folder. Blueprint working files live under .agent-blueprint/ in the project root. Before the first write there, make sure .agent-blueprint/.gitignore exists and lists run/, team/, review-runs/, cache/ and .gitignore, so run state and the ignore file itself stay out of commits while plans and notes stay tracked.

Provenance record. Before any other work, run this as written from the project root: mkdir -p .agent-blueprint/run/provenance && date -u +'{"skill": "ab-finishing-a-development-branch", "version": "4.2.0", "started_at": "%Y-%m-%dT%H:%M:%SZ", "helper_steps": []}' > .agent-blueprint/run/provenance/ab-finishing-a-development-branch.json. It replaces any older record, and the Working folder step above has already made sure of .agent-blueprint/.gitignore. Each Helper step adds {step, path: helper|inline} to helper_steps. The record tells a run, and the smoke test, which skill ran and how; it is not a security control.

Step 1: Verify Tests

Run the project’s test suite (npm test, cargo test, pytest, go test ./..., or the one in docs/context/CONVENTIONS.md). A merge or PR on failing tests hands broken code on, so on any failure stop and report:

Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.

Step 2: Determine Base Branch

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

With neither main nor master, use the remote’s default branch (git symbolic-ref --short refs/remotes/origin/HEAD). Name the base in your report instead of asking.

Step 3: Plan Audit

Before any option, a fresh read-only helper classifies every plan item against the branch diff. This step owns the audit procedure; ab-pr-workflow renders the result, and ab-executing-plans and ab-subagent-driven-development pass the plan path.

Find the plan and identify its items per references/plan-audit.md § Plan path. No plan file, or one with no items, reports NO PLAN: show that line, skip the table and go on to Step 4, since a missing plan never blocks.

Helper step. Start a helper (subagent) for this step if you can, with the prompt file named below (its absolute path when the helper can read it, else its full text) and the listed inputs; leave its model and effort at the session’s. If you cannot start one, follow the prompt file yourself. Either way, return its Output section, and note which path ran in the run’s provenance record if there is one.

Prompt: references/agents/code-reviewer.md, in a fresh helper. Inputs: the request in references/plan-audit.md § Audit request, filled in, and nothing else; its task and output rules replace the prompt file’s review. The states are in references/plan-audit.md § States.

The gate. Any NOT DONE or PARTIAL row blocks Options 1 and 2, since merging or opening a PR would call the branch finished with planned work missing: show those rows and offer Option 3 only. DONE, CHANGED, DEFERRED, UNVERIFIABLE and NO PLAN never block. Keep the table and the unplanned-work list for Option 2.

Autonomous runs (ab-autonomous-loop, ab-ship-pipeline): a blocked gate stops the run. Report in ab-autonomous-loop’s escalation format (what I was trying / what I tried / what I think / what I need), set the run state’s status to blocked with that report as its reason if a run state exists, and open no PR.

Step 4: Present Options

Asking the user. Ask with your question tool if you have one, offering at most three options; otherwise ask in plain text with a numbered list. In a headless or unattended run nobody will answer: take the default named below, say so in your output, and log it in the run state’s decisions if there is a run state.

If the user’s own messages already chose merge, PR or keep, carry out that choice after the gates pass; do not ask again. Otherwise offer the three below: a structured choice gets a clear answer where “what now?” does not. When Step 3 blocked, mark 1 and 2 (blocked by plan audit) and accept only 3. Default when nobody answers: 3, keep the branch; 2 when the calling pipeline asked for a PR and the audit did not block.

Implementation complete. What would you like to do?
1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)

Discarding the branch is not on the menu: it deletes commits and a worktree for good, and a menu slot invites an accidental pick. Run it only when the user explicitly asks, following references/discarding-work.md.

Step 5: Execute Choice

No-commit mode. If the user says not to commit, AGENT_BLUEPRINT_GIT_WRITABLE is 0, or .git is read-only, make no commits: leave changes in the working tree and add the intended message to .agent-blueprint/run/commit-msg.md. With AGENT_BLUEPRINT_GIT_WRITABLE=0, the ship runner commits after the session, so it is not for work the user wants uncommitted. Reviews use the working tree and untracked files against the merge base instead of a commit range.

A merge is a commit, so in this mode Option 1 cannot run: say so and keep the branch (Option 3). Option 2 leaves uncommitted work and its message as above.

Option 1: Merge Locally

From the main checkout, merge <feature-branch> into an updated <base-branch> and rerun the tests on the result. Only if they pass, remove the worktree and then delete the branch (git branch -d), as references/merge-locally.md § Merge sequence lists; a refused removal follows Step 6.

Option 2: Push and Create PR

Use the ab-pr-workflow skill, passing the Step 3 table and unplanned-work list (or the NO PLAN line) for its ## Plan audit section; it audits itself only when it gets no table. Force-push only on the user’s explicit request, since it rewrites history others may hold. Keep the worktree for review fixes.

In a runner-driven run (AGENT_BLUEPRINT_RUNNER is 1), push nothing and open no PR: write the PR body, with that ## Plan audit section, to .agent-blueprint/run/pr-body.md; the runner scans for secrets, pushes and opens the PR, because host sandboxes may block the network and one publish step is easier to trust.

Option 3: Keep As-Is

Report “Keeping branch <name>. Worktree preserved at <path>.” and leave the worktree.

Step 6: Cleanup Worktree

For Option 1: confirm nothing is left (references/merge-locally.md § Confirm the cleanup).

Leave out the force flag, because a forced removal deletes uncommitted work (the ab-using-git-worktrees skill’s “Removing a Worktree” owns that rule). If git refuses, keep the branch and the worktree and report the dirty state (Option 3 behaviour).

For Options 2 and 3: keep the worktree. Discard path: its own Step 4 removes the worktree under the same rule.

Quick reference, common mistakes, red flags and callers: references/summary.md.