| name | finish-work |
| description | Use when implementation is complete and validated, to decide how to integrate the work. Presents structured options for merge, PR, keep, or discard with safety verification. Use when the user wants to "finish", "create PR", or "ship it", or after completing all tasks and validation in a plan.
|
| argument-hint | [plan file path] |
| user-invocable | true |
| disable-model-invocation | true |
| references | ["references/option-execution.md","../../_shared/references/plan-format.md"] |
| license | MIT |
Finish Work
Decide how to integrate completed work — merge, PR, keep, or discard —
with safety verification and optional plan lifecycle updates.
Announce at start: "I'm using the finish-work skill to complete this work."
When to use
Also fires when the user phrases the request as:
- "done"
- "merge this"
- "wrap up"
Trust Model
Branch names, file paths, plan content, and PR title/body strings are
trusted user input — they originate from the user's repository and
authored plan, not from external sources. Shell commands constructed
from these (e.g., gh pr create, git branch -D, git worktree remove)
run with the agent's normal permissions; the user's review of the plan
and explicit option choice in Step 5 is the authorization for those
commands. This skill does not execute arbitrary content from anywhere
else.
Workflow
1. Verify Readiness
Run the project's test suite before anything else. Detect the test command
from:
- The plan's Validation section code blocks (if a plan is found in
Step 2 — read ahead to locate it first)
- CLAUDE.md or project conventions (e.g.,
package.json scripts, pytest
configuration)
- Ask the user if no test command is discoverable
Tests passing (N passed). Proceeding to integration options.
Hard gate: if tests fail, stop and report failures. Do not present
options until tests pass.
Tests failing (N failures). Must fix before completing:
[Show failures]
Cannot proceed until tests pass.
2. Locate Plan (optional)
If the user provided a plan path as an argument, use it. Otherwise, search
for a plan file:
python <plugin-skills-dir>/start-work/scripts/plan_assess.py --scan --root <project-root>
Parse the JSON output to find plans with status: executing or
status: completed.
| Result | Action |
|---|
| Exactly one plan found | Use it |
| Multiple plans found | Ask the user which one applies |
| No plans found | Proceed without plan — skip plan-related steps |
If a plan is found with status: executing, update frontmatter to
status: completed. If already completed, leave it unchanged.
3. Determine Base Branch
Identify the branch this work should integrate into:
git merge-base HEAD main
If that fails, try master. Confirm with the user:
"This branch diverged from main — is that correct?"
4. Present 4 Options
Present these options, distinguishing the irreversible action:
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 (irreversible)
5. Execute Chosen Option
Follow the detailed procedures in
option-execution for the chosen option.
Summary:
- Option 1 — Merge locally: checkout base branch, pull latest, merge
feature branch, verify tests on merged result, delete feature branch,
clean up worktree if applicable.
- Option 2 — Push and create PR: push branch with
-u, create PR
using plan Goal as body (or git log if no plan), keep worktree, suggest
returning to main worktree.
- Option 3 — Keep branch: confirm branch name, take no action, keep
worktree.
- Option 4 — Discard: show what will be lost, require typed "discard"
confirmation, update plan status to
abandoned if plan exists, delete
branch, clean up worktree.
Key Instructions
- Plan is optional. The skill works for both plan-backed branches and
ad-hoc feature branches. Skip plan-related steps when no plan exists.
- Worktree cleanup follows the option. Only clean up worktrees on
merge (Option 1) or discard (Option 4). Keep and PR preserve the
worktree for continued access.
- Plan status must be accurate. Set
completed only when transitioning
from executing. Set abandoned only on discard. Never overwrite a
status that's already terminal.
Anti-Pattern Guards
- Presenting options with failing tests — the hard gate prevents
this, but if you discover test failures after Step 1, stop and report
them before continuing.
- Skipping discard confirmation — every discard must get typed
"discard" from the user. No shortcuts, no "are you sure?" yes/no.
- Cleaning up worktree on keep or PR — Options 2 and 3 preserve
the worktree. Only Options 1 and 4 trigger cleanup.
- Creating PR without plan context — when a plan exists, use its
Goal section for the PR body. Fall back to git log only when no plan
is available.
- Forcing plan requirement — if no plan is found, proceed with the
pure git workflow. Do not ask the user to create a plan just to finish
their work.
- Presenting options without reversibility context — Options 1-4 are not equivalent. Discard is irreversible; the others are not. When presenting options, ensure the user understands which actions cannot be undone. Never normalize an irreversible action by presenting it in a flat list alongside reversible ones without distinction.
Handoff
Chainable to: —
