BUCKYVERSE

Command: work-complete (iterate → isolate → plan → execute → squash merge → housekeeping → confirm)

Use for: work complete:, work complete (optionally with a ## heading, file/line reference, **Id:** ITER-N, or a pasted block that matches one section in work/ITERATION.md)

Prerequisites: Read ../bootstrap.md and ../rules.md first. This command implements product/repo changes—not "record only."

Source file (only): work/ITERATION.md

Workflow

  1. Migrate and bootstrap work/ files as needed.

  2. Identify the section in work/ITERATION.md per ../procedures/section-disambiguation.md (scope: work/ITERATION.md, id format: ITER-N).
    Then backfill missing entry ids in work/ITERATION.md per ../id-prefixes.md (Backfill) before editing the section.

  3. Snapshot the block — Copy the full section text exactly as queued (from the ## line through the content up to but not including the next --- or the next ## at the same level—same boundary rules as pluck). Keep this copy for the final commit body. Also capture the Source and Source id fields from the iteration entry for provenance.

  4. Isolate feature work — Before implementation begins, ensure work will happen on a feature branch in a managed worktree.

    4a. Detect the base branch using this three-tier fallback (reuse this value for the rest of the run, including step 10):

    1. git config --get git-town.main-branch
    2. git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||'
    3. Fallback to main
    BASE_BRANCH=$(git config --get git-town.main-branch 2>/dev/null || \
  git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || \
  echo "main")

    Follow ../procedures/worktree-setup.md with branch-prefix iter/. BASE_BRANCH was detected in step 4a above. If the procedure's "Decide" step (b) finds the current branch is already a non-base branch, skip to the planning mode gate (step 5).

Planning mode gate (mandatory — do not skip)

  1. If the user already declared a mode in the same message, treat it as their choice and go to step 6. Accept plain-language equivalents, for example:

    • Native / Plan → Native planning (see below).
    • Brainstorm / superpowers → superpowers:brainstorming.
      If there is no such declaration, you must obtain a choice before any implementation work:
    • Stop after step 4. Do not read the codebase for implementation, do not write or change product code, and do not run tool calls whose purpose is to implement the item.
    • Your next message to the user must present only the planning-mode question (optional: one short line naming the section you identified). Prefer a multiple-choice UI when the product supports it (e.g. the product's question UI with exactly two options) so the user must pick before you continue.
    • Offer exactly two options (same meaning every time):
      • Native planning — Use the product's built-in planning UI so a written plan exists and is visible to the user before coding. If a planning UI is not available, post a short bullet plan in chat and wait for explicit approval (e.g. "proceed," "looks good," or thumbs-up) before writing implementation code.
      • superpowers:brainstorming — Run the superpowers:brainstorming flow first, then implement.
    • Wait for the user's reply that selects one option. Do not assume defaults.

  2. Hand off to the chosen planner — Read ../templates/work-complete-planner-brief.md and give the planner explicit instructions that it must:

    • Follow the squash-merge path and produce two commits on the base branch: one feature delivery commit (step 10) and one housekeeping commit (step 14).
    • Do NOT use superpowers:finishing-a-development-branch for the merge step — the squash-merge procedure in step 10 replaces it.
    • Complete all implementation on the feature branch before merging.

  3. Execute on the feature branch — All non-work/ changes for the iteration item are made on the feature branch. Follow the selected planning mode: native planning means a visible plan first (Plan mode or chat plan + approval), then implement; superpowers:brainstorming means that flow first, then implement.

    7a. Checkpoint 1 — commit approved spec artifact: When the superpowers:brainstorming flow completes and the user approves the written spec, check whether the spec file has uncommitted changes before invoking superpowers:writing-plans:

    git status --porcelain -- <spec-path>
    • If empty: the spec is clean. Continue to superpowers:writing-plans.
    • If dirty: stage only the spec file and commit:
      git add -- <spec-path>
git commit -m "docs: incorporate user revisions to <spec-filename>"
      where <spec-filename> is the basename of the spec path.
    • If staging or committing fails, stop before superpowers:writing-plans. Do not continue with an approved-but-uncommitted spec revision.
    • Do not broaden this commit to other dirty files — checkpoint 1 is scoped to the approved spec artifact only.

    By the end of this step the feature branch contains the commits whose messages will later be harvested into the feature delivery commit body. If the implementation produces no meaningful diff relative to the base branch, stop and do not continue to merge.

7b. Checkpoint 2 — commit outstanding changes before verification: Before verification runs, ensure the feature branch is fully committed so verification operates on the exact tree that will later be merged.

7b.1 Entry conditions:

  1. The current branch must be the feature branch, not BASE_BRANCH.
  2. The working tree must have no unresolved merge conflicts.

If any entry condition fails, stop and report the condition.

7b.2 Dirty detection:

git status --porcelain

7b.3 Commit behavior:

  1. Stage all tracked, untracked, and deleted changes:
    git add -A
  2. Commit:
    git commit -m "chore: commit outstanding changes before squash merge"
  3. Continue to step 8 only after the commit succeeds.

7b.4 Failure handling:

  1. Pre-merge verification — Determine the repo's canonical verification command and run it on the feature branch.

    • If verification fails, stop on the feature branch. Do not begin squash merge. Fix the issue and rerun verification before proceeding.
    • If the repo has no discoverable verification command, stop and ask the user rather than guessing.

  2. Squash merge to the base branch — Execute these sub-steps in order:

    1. Reuse the base branch detected in step 4a (BASE_BRANCH). Do not re-detect.
    2. Read the current feature branch name:
      FEATURE_BRANCH=$(git branch --show-current)
    3. Assert FEATURE_BRANCH != BASE_BRANCH. If they are equal, stop — the workflow lost its isolation guarantee.
    4. Collect all commit messages on the feature branch that are not on the base branch:
      git log ${BASE_BRANCH}..${FEATURE_BRANCH} --format="%B" > /tmp/work-complete-squash-msg-$$.txt
    5. Switch to the base branch and update from upstream when an upstream exists. If no upstream exists, skip the pull step and note that fact in the final summary.
      git checkout ${BASE_BRANCH} && git pull
    6. Ensure the base branch checkout is clean before merging. If it is not clean, stop and ask the user to resolve it. Do not auto-stash, auto-reset, or silently mix unrelated changes.
    7. Run the squash merge:
      git merge --squash ${FEATURE_BRANCH}
    8. If the squash merge conflicts, stop. Do not yank the iteration item, do not create the housekeeping commit, and do not delete the feature branch or worktree.
    9. Stage the merged implementation changes and CHANGELOG.md when updated. Do not stage work/ files.
    10. Commit with this structure:
      <concise summary of what shipped>

From work/ITERATION.md (ITER-N):
<snapshot block from step 3>

Original source: <Source field> (<Source id> if present)

Commits from <feature-branch>:
<collected commit messages>

  3. Post-merge verification — Run the same verification command on the base branch after the feature delivery commit.

    • If verification passes, continue to cleanup (step 11).
    • If verification fails, stop before cleanup and before yanking the iteration item. Preferred recovery: fix the problem on the feature branch and repeat the merge path so the delivered feature remains one reviewable commit.

10a. Ship Proof gate (conditional) — Follow ../procedures/ship-proof-gate.md with:

  1. Clean up branch and worktree — Only after step 10 passes:

    1. Delete the local feature branch: git branch -D <feature-branch>
    2. If a worktree was used, remove it using the exact path recorded in step 4f: git worktree remove <recorded-worktree-path>
    3. If the feature branch was pushed, delete the remote branch (best-effort): git push origin --delete <feature-branch>

    Remote branch deletion is best-effort. If it fails, report it but do not roll back a successful local merge.

  2. Human verification gate — Follow ../procedures/human-verification-gate.md with:

    • source: ITERATION.md
    • source-id: the iteration section's **Id:** ITER-N

    Continue to step 13 whether or not an ACC-N entry was created.

  3. Yank + housekeeping commit — Remove the entire iteration section from work/ITERATION.md (same boundaries as step 3). If step 12a ran, include the new ACCEPTANCE.md entry in the same commit.

    Rules:

    • Only stage work/ files that changed.
    • Subject: xp_work: yank ITER-N from ITERATION
    • Mention ACC-N in the subject or body when acceptance was queued.
    • Do not include feature code, test changes, or CHANGELOG.md in this commit.
    • Do not change ITERATION.md's **Last id:** counter when yanking. The counter is monotonic — once an id has been assigned and yanked, the next entry recorded must get the next number, never reuse the yanked one.

  4. CHANGELOG — If CHANGELOG.md exists and the change is worth recording, update it as part of the feature delivery commit (step 9), not the housekeeping commit. Add one sentence summarizing what shipped or changed, matching the file's existing structure (e.g. Keep a Changelog ## [Unreleased]). Do not include the entry id (e.g. ITER-3, IMP-7) in the CHANGELOG line — entry ids are per-file and not unique across time; describe the change in plain language. The snapshot in the commit body preserves the id for traceability.

  5. Confirm — Return a short summary including:

    • Iteration item: ITER-N and section title
    • Original source and source id (provenance)
    • Planning mode used
    • Feature delivery commit hash (from step 9)
    • Housekeeping commit hash (from step 13)
    • Whether CHANGELOG.md was updated
    • Whether ACC-N was created (and if so, note that accept: / xp_work accept should be used after the human verifies)
    • Whether ship-proof ran (spec-driven or ad-hoc fallback), passed, or was skipped — and why (spec row matched, no spec found, not in spec requirements, no UI changes). Include artifact location when it ran: docs/features_proof/<ITER-N>-<slug>/
    • Whether base-branch pull was skipped (no upstream)
    • Whether remote branch deletion was skipped or failed
    • Whether Workbench workspace archive was triggered or skipped (no Workbench MCP)

  6. Workbench workspace archive (conditional) — If the mcp__workbench__archive_workspace tool is available, the session is running inside a Workbench workspace. Call mcp__workbench__archive_workspace to archive the workspace. This must be the absolute last action — after the confirm summary has been returned to the user. The tool is irreversible: it stops processes, removes the worktree, and preserves chat history. If the tool is not available, skip this step entirely.

See ../format-guidelines.md for template paths.