Completing Task

Key behavior: Always ask before closing parents. Always check PR on feature branches. Always clean up plan files. Always run bd sync. Offer cleanup after sync.

Workflow

Follow these steps in order. Do not skip steps.

1. Check Git Branch (MANDATORY FIRST STEP)

git branch --show-current

If generic branch (main, master, develop, trunk): Continue to step 2.

If feature branch detected (feature/*, fix/*, chore/*, or any non-generic):

Check if PR exists for current branch:

gh pr view --json state,url 2>/dev/null || echo "NO_PR"

If NO PR exists:

STOP and inform user:

"You're on feature branch {branch-name} with no PR.

Use superpowers:finishing-a-development-branch to properly complete this work (handles merge/PR/cleanup and task closure together)."

Then exit. Do not continue workflow.

If PR exists (any state: open, merged, closed):

ASK user:

"You're on feature branch {branch-name}.

PR exists: {url} (state: {state})

Proceed to close task on this branch? (yes/no)"

• If yes: Continue to step 2.
• If no: Stop and suggest superpowers:finishing-a-development-branch if needed.

2. Find In-Progress Leaf Task

bd list --status=in_progress

Filter for leaf tasks (no open children).

If multiple found: Ask which task is complete. If none found: Inform "No in_progress leaf tasks. Check with bd list --status=in_progress"

3. Close Task

bd close {task-id}

Use bd close. Do NOT use direct SQL.

Confirm task closed.

4. Plan Cleanup

After closing the task, check if an implementation plan file exists and offer to clean it up.

4.1. Find Plan File

Two sources, check in order:

Source A — task description link:

bd show {task-id}

Look for Plan: line in description. If found, extract the file path.

Source B — untracked/modified files in docs/plans/:

If no Plan: link in description, search for untracked or unstaged plan files:

git ls-files --others --modified -- 'docs/plans/'

Filter results:

• File name contains "impl" or "plan" (case-insensitive)
• File name semantically matches the task title (shared keywords)

If multiple candidates found: Show the list and ask user which file (or "none").

If no plan file found (neither source): Skip to step 5. Do NOT inform — silent skip.

4.2. Ask User: Delete / Archive / Keep

Always ask. Never auto-delete.

Plan file found: {path}

What to do with it?

1. Delete
2. Archive (move to docs/archive/)
3. Keep as is

4.3. Execute User's Choice

If delete:

rm {path}

If archive:

mkdir -p docs/archive
mv {path} docs/archive/

If keep: Do nothing, proceed to step 5.

4.4. Remove Plan Link from Description

Only if task description contained a Plan: line AND user chose delete or archive:

Get current description, remove the Plan: line, update:

bd update {task-id} --description="{description-without-plan-line}"

Do NOT commit the file deletion/move. The branch cleanup in step 8 or the user's next workflow will handle git state.

5. Check Parent Recursively (with Confirmation)

After closing task, check if it has a parent:

bd show {task-id}

Look for parent relationship.

If task has parent:

bd show {parent-id}

Count open children.

If parent has NO open children (all closed):

Ask user:

"Parent task {parent-id} now has all children closed.

Close it too? (yes/no)"

If user says yes:

• Close parent with bd close {parent-id}
• Set current task to parent
• Repeat step 5 (recurse up)

If user says no:

• Stop recursion
• Proceed to step 7

If parent has open children:

• Stop recursion (parent cannot be closed yet)
• Proceed to step 7

If task has no parent:

• Proceed to step 7

6. Repeat Recursion

Continue checking grandparents, great-grandparents, etc. until:

• User says "no" to closing a parent, OR
• Parent has open children, OR
• No more parents exist

Always ask at each level. Do NOT auto-close parents.

7. Run bd sync (MANDATORY)

bd sync

Always run at end, regardless of how many tasks closed.

Confirm sync completed.

8. Cleanup Branch and Worktree

Non-blocking: If cleanup fails, the task is already closed and synced. Cleanup failure is not critical.

8.1. Validate current branch matches the task

CURRENT_BRANCH=$(git branch --show-current)

Check if $CURRENT_BRANCH contains the closed task's ID. If not — skip cleanup silently. The user ran flow:done from an unrelated branch (e.g. master).

8.2. Detect what exists

Gather cleanup targets:

• Worktree: pwd | grep -q "\.worktrees/" — are we in a worktree?
• Remote branch: git branch -r | grep "$CURRENT_BRANCH" — does remote branch exist?
• Local branch is always present (we're on it).

8.3. Show branch name and ask once

Display the current branch explicitly and list what will be deleted:

You are on branch `feature/claude-tools-elf.6-delete-branches-worktrees`.

Delete branch and associated resources?
  - Worktree: .worktrees/feature-claude-tools-elf.6-delete-branches-worktrees
  - Local branch: feature/claude-tools-elf.6-delete-branches-worktrees
  - Remote branch: origin/feature/claude-tools-elf.6-delete-branches-worktrees

(yes/no)

Show only items that exist. If no worktree, omit the worktree line. If no remote branch, omit the remote line.

8.4. If yes — execute in order

1. If in worktree: cd to the main repo root (parent of .worktrees/)
2. Remove worktree: git worktree remove <path> (if in worktree)
3. Detect default branch:

   DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||')
   

   Fallback: try master, then main.
4. Switch to default branch: git checkout $DEFAULT_BRANCH
5. Pull merged changes: git pull
6. Delete local branch: git branch -d <branch> (safe delete; use -D only if PR confirmed merged)
7. Delete remote branch: git push origin --delete <branch> (if remote exists)

Error handling:

• Worktree remove fails (uncommitted changes): Show error, suggest git worktree remove --force or manual cleanup. Don't block.
• Remote branch already deleted (GitHub auto-delete): Catch the error and continue.
• Branch delete fails (unmerged changes): git branch -d will refuse. Show warning. Offer git branch -D only if PR state is MERGED.

8.5. If no — skip, done

No cleanup performed. User can clean up manually later.

Scope Boundaries

This Skill DOES:

✅ Check git branch ✅ Find in_progress leaf task ✅ Close task with bd close ✅ Find plan file (linked in description OR untracked in docs/plans/) ✅ Ask user: delete / archive / keep plan file ✅ Remove Plan: link from description after delete/archive ✅ Check parents recursively ✅ Ask before closing each parent ✅ Run bd sync at end ✅ Offer to clean up branch and worktree (Step 8) ✅ Delete local branch, remote branch, worktree (after confirmation) ✅ Switch to default branch and pull after cleanup

This Skill Does NOT:

❌ Git operations unrelated to cleanup (commit, push, merge, etc.) ❌ Create branches ❌ Start next task (use flow:start) ❌ Update PRs or issues ❌ Run tests or builds ❌ Auto-close parents without asking ❌ Auto-proceed on feature branches without asking ❌ Force-delete without confirmation ❌ Search for branches beyond the current one ❌ Clean up branches for parent tasks (cascade closures) ❌ Block task closure if cleanup fails

Scope note: On feature branches without PR, this skill STOPS and refers to finishing-a-development-branch. On feature branches WITH PR, it asks user before proceeding. Cleanup (Step 8) is non-blocking and only applies when the current branch matches the closed task.

Red Flags - STOP

If you're thinking any of these, STOP and follow the workflow:

• "All children closed → close parent"
• "Branch check unnecessary"
• "bd sync is obvious (skip it)"
• "Use SQL for efficiency"
• "Parent obviously should close"
• "Being helpful by auto-closing cascade"
• "Feature branch → always block"
• "PR exists → auto-proceed"
• "Cleanup is obvious, just delete everything"
• "Skip cleanup, user can do it manually"
• "Branch doesn't match but I'll clean up anyway"
• "Force-delete is fine, PR was merged"
• "Plan cleanup is not part of the workflow"
• "No Plan: link → no plan to clean up"
• "Auto-delete the plan, user obviously doesn't need it"
• "Plan file is outside my scope"

All of these mean: Follow workflow. Check branch AND PR. Ask before proceeding. Always check for plan files (linked AND unlinked). Run bd sync. Offer cleanup only if branch matches task.

Common Rationalizations

Examples

❌ BAD: Auto-close parent

User: "Task done, flow:done"
Agent: [Closes task]
       [Checks parent, sees all children closed]
       [Automatically closes parent without asking]
       Done!

Problems:

• Didn't check branch
• Auto-closed parent without asking
• Didn't run bd sync

✅ GOOD: Ask before closing parent

User: "Task done, flow:done"
Agent: [Checks branch: master, OK to proceed]
       [Closes task claude-tools-abc.3]

       Parent task claude-tools-abc now has all children closed.

       Close it too? (yes/no)

User: yes
Agent: [Closes parent]
       [Runs bd sync]

       ✓ Closed claude-tools-abc.3
       ✓ Closed claude-tools-abc (parent)
       ✓ Synced with remote

       Done.

Correct because:

• Checked branch first
• Asked before closing parent
• Ran bd sync
• Clear confirmation

❌ BAD: Auto-delete plan without asking

User: "flow:done"
Agent: [Closes task]
       [Sees Plan: link in description]
       [Deletes plan file automatically]
       [Removes Plan: link from description]
       Done!

Problems:

• Didn't ask user what to do with plan
• No archive option offered
• Violated consultation principle

❌ BAD: Ignores untracked plan file

User: "flow:done"
Agent: [Closes task]
       [No Plan: link in description → skips plan cleanup entirely]
       [Doesn't check docs/plans/ for untracked files]
       Done!

Problem: Plan file exists as untracked in docs/plans/ but agent only checked description.

✅ GOOD: Plan cleanup with linked plan

User: "flow:done"
Agent: [Checks branch: master, OK]
       [Closes task claude-tools-abc]

       Plan file found: `docs/plans/2026-02-06-abc-impl-plan.md`

       What to do with it?
       1. Delete
       2. Archive (move to docs/archive/)
       3. Keep as is

User: 2
Agent: [Moves to docs/archive/]
       [Removes Plan: link from description]
       [Checks parent, has open children]
       [Runs bd sync]

       ✓ Closed claude-tools-abc
       ✓ Plan archived to docs/archive/
       ✓ Synced with remote

       Done.

Correct because:

• Found plan via description link
• Asked user before acting
• Offered all three options
• Updated description after archive

✅ GOOD: Plan cleanup with unlinked plan

User: "flow:done"
Agent: [Checks branch: master, OK]
       [Closes task claude-tools-xyz "Quota module"]
       [No Plan: link in description]
       [Checks docs/plans/ for untracked files]
       [Finds: quota-module-impl-plan.md (untracked, matches task title)]

       Plan file found: `docs/plans/quota-module-impl-plan.md`

       What to do with it?
       1. Delete
       2. Archive (move to docs/archive/)
       3. Keep as is

User: 1
Agent: [Deletes file]
       [Checks parent, has open children]
       [Runs bd sync]

       ✓ Closed claude-tools-xyz
       ✓ Plan deleted
       ✓ Synced with remote

       Done.

Correct because:

• No link in description but still searched docs/plans/
• Found untracked file matching task title
• Asked user before deleting
• No description update needed (wasn't linked)

❌ BAD: Feature branch proceed without checking PR

User: "Done with this feature, flow:done"
Agent: [On feature/add-auth branch]
       [Closes task without checking for PR]

Problem: Proceeded on feature branch without checking PR status.

✅ GOOD: Feature branch with no PR

User: "Done with this feature, flow:done"
Agent: [Checks branch: feature/add-auth]
       [Checks PR: no PR exists]

       You're on feature branch `feature/add-auth` with no PR.

       Use `superpowers:finishing-a-development-branch` to properly
       complete this work (handles merge/PR/cleanup and task closure together).

Correct because:

• Checked branch
• Checked PR status
• Stopped when no PR exists
• Suggested correct workflow

✅ GOOD: Feature branch with PR exists

User: "PR merged, flow:done"
Agent: [Checks branch: feature/add-auth]
       [Checks PR: exists, merged]

       You're on feature branch `feature/add-auth`.

       PR exists: https://github.com/org/repo/pull/123 (state: MERGED)

       Proceed to close task on this branch? (yes/no)

User: yes
Agent: [Continues to step 2, finds task, closes it]
       [Runs bd sync]

       ✓ Closed claude-tools-xyz
       ✓ Synced with remote

       Done.

Correct because:

• Checked branch
• Checked PR status
• Asked user before proceeding
• User confirmed, so continued workflow
• Did not assume - asked first

✅ GOOD: Cleanup after task close

User: "PR merged, flow:done"
Agent: [Checks branch: feature/claude-tools-elf.6-delete-branches-worktrees]
       [Checks PR: exists, merged]
       [Asks user, user says yes]
       [Closes task claude-tools-elf.6]
       [Checks parent: has open children, skip]
       [Runs bd sync]

       You are on branch `feature/claude-tools-elf.6-delete-branches-worktrees`.

       Delete branch and associated resources?
         - Worktree: .worktrees/feature-claude-tools-elf.6-delete-branches-worktrees
         - Local branch: feature/claude-tools-elf.6-delete-branches-worktrees
         - Remote branch: origin/feature/claude-tools-elf.6-delete-branches-worktrees

       (yes/no)

User: yes
Agent: [cd to main repo root]
       [git worktree remove .worktrees/feature-...]
       [git checkout master]
       [git pull]
       [git branch -d feature/claude-tools-elf.6-...]
       [git push origin --delete feature/claude-tools-elf.6-...]

       ✓ Worktree removed
       ✓ Switched to master
       ✓ Local branch deleted
       ✓ Remote branch deleted

       Done.

Correct because:

• Checked branch matches task ID
• Listed all cleanup targets
• Asked before deleting
• Executed in correct order (worktree → checkout → delete)

❌ BAD: Auto-cleanup without asking

Agent: [Closes task]
       [Runs bd sync]
       [Immediately deletes branch and worktree]

Problem: Didn't ask before cleanup. User might want to keep the branch.

✅ GOOD: Branch doesn't match — skip cleanup silently

Agent: [On master branch]
       [Closes task claude-tools-elf.6]
       [Runs bd sync]

       ✓ Closed claude-tools-elf.6
       ✓ Synced with remote

       Done.

Correct because: Branch "master" doesn't contain task ID "elf.6", so cleanup is silently skipped.

❌ BAD: Skip bd sync

User: "flow:done"
Agent: [Closes task]
       [Asks about parent, closes]
       Done!

Problem: Skipped bd sync at end.

✅ GOOD: Always bd sync

User: "flow:done"
Agent: [Checks branch]
       [Closes task]
       [Asks about parent, closes if yes]
       [Runs bd sync]

       ✓ Synced with remote

       Done.

Correct because:

• bd sync always run at end
• Explicit confirmation

Edge Cases

Multiple In-Progress Tasks

Found 2 in_progress leaf tasks:
1. claude-tools-abc: Feature X
2. claude-tools-def: Feature Y

Which task is complete? (enter 1 or 2, or task ID)

No In-Progress Tasks

No in_progress leaf tasks found.

Check task status with:
  bd list --status=in_progress

Plan File Linked but Already Deleted

Task description has Plan: docs/plans/old-plan.md
File does not exist on disk.

Plan file referenced in description not found: docs/plans/old-plan.md
(already deleted or moved)

Removing stale Plan: link from description.

Multiple Untracked Plan Files Match

Found multiple plan file candidates in docs/plans/:
1. quota-module-impl-plan.md (untracked)
2. quota-implementation-plan.md (untracked)

Which file is the implementation plan for this task? (1, 2, or "none")

Deep Hierarchy (3 levels)

Closed claude-tools-abc.2.1

Parent claude-tools-abc.2 now has all children closed.
Close it too? (yes/no)

[User: yes]

Closed claude-tools-abc.2

Parent claude-tools-abc now has all children closed.
Close it too? (yes/no)

[User: yes]

Closed claude-tools-abc

No more parents. Running bd sync...

Parent Has Open Sibling

Closed claude-tools-abc.1

Parent claude-tools-abc still has open children:
- claude-tools-abc.2 (open)

Not asking to close parent (has open children).

Running bd sync...

Cleanup: Worktree Remove Fails

git worktree remove .worktrees/feature-claude-tools-abc-login
Error: '.worktrees/feature-claude-tools-abc-login' contains modified or
untracked files, use --force to delete.

⚠️ Worktree has uncommitted changes. You can:
  - git worktree remove --force .worktrees/feature-...
  - Or clean up manually later.

Continuing with branch deletion...

Cleanup: Remote Branch Already Deleted

git push origin --delete feature/claude-tools-abc-login