sartoris-digital/finishing-a-development-branch

Finishing a Development Branch

Overview

Guide completion of development work by presenting clear options and handling the chosen workflow.

Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.

Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

The Process

Step 1: Verify Tests

Before presenting options, verify tests pass:

# Run project's test suite
npm test / cargo test / pytest / go test ./...

If tests fail:

Tests failing (<N> failures). Must fix before completing:

[Show failures]

Cannot proceed with merge/PR until tests pass.

Stop. Don't proceed to Step 2.

If tests pass: Continue to Step 2.

Step 2: Detect Environment

Determine workspace state before presenting options:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "in a linked worktree," verify the agent is not in a submodule:

# If this returns a path, the agent is in a submodule — treat as a normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

This determines which menu to show and how cleanup works:

| State | Menu | Cleanup | |-------|------|---------| | GIT_DIR == GIT_COMMON (normal repo or submodule) | Standard 4 options | No worktree to clean up | | GIT_DIR != GIT_COMMON, named branch | Standard 4 options | Provenance-based (see Step 6) | | GIT_DIR != GIT_COMMON, detached HEAD | Reduced 2 options (no merge, no separate keep) | No cleanup (externally managed) |

Step 3: Determine Base Branch

# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main — is that correct?"

Step 4: Present Options

Normal repo and named-branch worktree — present exactly these 4 options:

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)
4. Discard this work

Which option?

Detached HEAD — present exactly these 2 options:

The workspace is externally managed and there is no branch to merge from, so the menu collapses:

Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as new branch and create a Pull Request
2. Discard this work

Which option?

Don't add explanation — keep options concise.

Step 5: Execute Choice

Option 1: Merge Locally

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first — verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>

Then: Cleanup worktree (Step 6), then delete branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

# Push branch
git push -u origin <feature-branch>

# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"

Do NOT clean up worktree — user needs it alive to iterate on PR feedback.

Option 3: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

Don't cleanup worktree.

Option 4: Discard

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation.

If confirmed:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

Then: Cleanup worktree (Step 6), then force-delete branch:

git branch -D <feature-branch>

Step 6: Cleanup Workspace (Provenance-Confined)

Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

If GIT_DIR == GIT_COMMON: Normal repo, no worktree to clean up. Done.

Otherwise — provenance check: The skill only removes worktrees it (or using-git-worktrees) created. Everything else is left alone.

Authoritative source for cleanup decisions is git worktree list --porcelain — nothing else. Do not infer ownership from filesystem walks, environment variables, or other heuristics. The provenance rules below are strict and non-negotiable.

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
WORKTREES_DIR="$MAIN_ROOT/.worktrees"

# Enumerate registered worktrees from git's authoritative source
git -C "$MAIN_ROOT" worktree list --porcelain

Apply all of these checks against the candidate worktree path before removing:

1. Listed by git: The path must appear in git worktree list --porcelain output. If git does not know about it, do not touch it.
2. realpath resolution: Resolve the candidate with realpath (or readlink -f / pwd -P). Compare the resolved path, not the raw string.
3. Direct child of <repo>/.worktrees/: The resolved path must be exactly one directory below <MAIN_ROOT>/.worktrees/. Nested deeper, no.
4. No symlinks in the path components: Reject any candidate whose path traversed a symlink during resolution.
5. No .. traversal: Reject any candidate whose original (pre-realpath) path contains ...

If all five checks pass: the skill owns this worktree.

git -C "$MAIN_ROOT" worktree remove "$WORKTREE_PATH"

• Use only git worktree remove. No rm -rf fallback ever. If git worktree remove fails, surface the error to the user and stop — do not try to clean up with shell file removal.
• After removal, run git worktree prune to clear any stale registrations git noticed. Stale metadata (unreferenced entries that git worktree prune would remove) is logged but not auto-removed without consent — print the prune dry-run output, ask the user before applying, and only apply on explicit approval.

git -C "$MAIN_ROOT" worktree prune --dry-run --verbose
# If stale entries exist, ask the user before running:
# git -C "$MAIN_ROOT" worktree prune --verbose

Otherwise (any check fails): The host environment (harness, the user, another tool) owns this workspace. Do NOT remove it. If the harness provides a workspace-exit tool, use it. Otherwise, leave the workspace in place and report.

Quick Reference

| Option | Merge | Push | Keep Worktree | Cleanup Branch | |--------|-------|------|---------------|----------------| | 1. Merge locally | yes | - | - | yes | | 2. Create PR | - | yes | yes | - | | 3. Keep as-is | - | - | yes | - | | 4. Discard | - | - | - | yes (force) |

Common Mistakes

Skipping test verification

• Problem: Merge broken code, create failing PR
• Fix: Always verify tests before offering options

Open-ended questions

• Problem: "What should I do next?" is ambiguous
• Fix: Present exactly 4 structured options (or 2 for detached HEAD)

Cleaning up worktree for Option 2

• Problem: Remove worktree user needs for PR iteration
• Fix: Only cleanup for Options 1 and 4

Deleting branch before removing worktree

• Problem: git branch -d fails because worktree still references the branch
• Fix: Merge first, remove worktree, then delete branch

Running git worktree remove from inside the worktree

• Problem: Command fails silently when CWD is inside the worktree being removed
• Fix: Always cd to main repo root before git worktree remove

Cleaning up worktrees the skill did not create

• Problem: Removing a harness-owned or user-managed worktree causes phantom state and data loss
• Fix: Provenance check — git worktree list --porcelain is the only authority; require realpath-resolved direct child of <repo>/.worktrees/, no symlinks, no ..

Using rm -rf to force-clean a worktree

• Problem: Bypasses git's bookkeeping, corrupts the main repo's worktree metadata, can wipe unrelated files if path resolution is wrong
• Fix: Only git worktree remove. No rm -rf fallback ever. If git worktree remove fails, stop and surface the error.

Auto-pruning stale metadata

• Problem: git worktree prune removes registrations the user might still expect
• Fix: Log prune candidates from --dry-run, do not apply without consent

No confirmation for discard

• Problem: Accidentally delete work
• Fix: Require typed "discard" confirmation

Red Flags

Never:

• Proceed with failing tests
• Merge without verifying tests on result
• Delete work without confirmation
• Force-push without explicit request
• Remove a worktree before confirming merge success
• Clean up worktrees the skill did not create (provenance check)
• Treat anything other than git worktree list --porcelain as authoritative for ownership
• Run git worktree remove from inside the worktree
• Fall back to rm -rf when git worktree remove fails
• Auto-apply git worktree prune without user consent

Always:

• Verify tests before offering options
• Detect environment before presenting menu
• Apply the submodule guard during environment detection
• Present exactly 4 options (or 2 for detached HEAD)
• Get typed confirmation for Option 4
• Clean up worktree for Options 1 and 4 only
• cd to main repo root before worktree removal
• realpath candidate paths, reject symlinks and .., require direct child of <repo>/.worktrees/
• Use only git worktree remove (no rm -rf)
• Report stale prune candidates and ask before applying

Pi Platform Notes

Pi has no native worktree tool. The bundled @mariozechner/pi-coding-agent tool registry and the pi-superpowers extension surface (bootstrap, subagent, state-manager, persistence-engine, orchestrator) do not expose any worktree, EnterWorktree, or ExitWorktree primitive. All cleanup runs through git worktree remove invoked via bash.

The provenance rules (Step 6) are enforced through bash invocations of git worktree list --porcelain, realpath, and git worktree remove. If a future Pi extension registers a workspace-exit tool, this skill should defer to it after the provenance check passes; for now, the bash path is the only path.