specpilot.implement

/specpilot.implement

Implement the next ticket from the Ready column and ship it.

Works with tickets created by either /specpilot.refine (board-first) or /specpilot.specify (spec-first) — both land in Ready with a linked spec branch.

Arguments

$ARGUMENTS may contain:

• --once — process one ticket then stop
• --dry-run — show which ticket would be picked, do nothing
• --from <step> — resume from a specific step: implement, review, test, ship, merge

Steps

0. Load config

Read .specpilot.json from the project root. If missing, tell the user to run /specpilot.setup first and stop.

From config, identify:

• Spec location: the repo/folder with role: "spec" — read-only during implement
• Feature repos: all repos with role: "feature" — implement, test, build, and ship these
• Per repo: check implement, test, build, and waitForCI flags

1. Pick ticket

• Query the GitHub Project for the next ticket in the Ready column: gh project item-list <projectNumber> --owner <owner> --format json
• Filter items where status exactly matches config.statuses.ready (read from .specpilot.json — do NOT hardcode "Ready" or any other string)
• If assignee is set in config, additionally filter by that assignee
• If no tickets found, say "No tickets in Ready. All done!" and stop
• If --dry-run, print the ticket title and stop
• Move the ticket to In Progress (use config.statuses.inProgress value)
• Assign the ticket to config.github.assignee using gh project item-edit with the assignee field (if assignee is set in config)

2. Read spec

• Find the open PR (or branch) in the spec location for this ticket (e.g. branch 012-feature-name)
• Check out that branch in the spec location
• Locate the spec directory: check both the root of specsDir and any app subfolders (e.g. specsDir/member/012-feature-name/, specsDir/012-feature-name/). Use whichever location contains the spec files.
• Read spec.md, plan.md, and tasks.md
• The spec location is read-only at this stage — do not commit yet

3. Checkout feature branches

For each feature repo (role: "feature"):

• git checkout main && git pull origin main
• git checkout -b <branch-name> (same branch name as the spec branch)

4. Implement

Run /speckit.implement <branch-name> from speckit.workspaceDir. Only repos with implement: true (default) receive code changes. Repos with implement: false still get a PR but no speckit changes.

5. Code review

Review changes in each feature repo for:

• Correctness against spec requirements
• Adherence to project constitution (if .specify/memory/constitution.md exists in the spec location)
• Test coverage
• No obvious bugs or security issues

Apply any fixes found.

6. Test and build

For each feature repo:

• If test is set → run it (up to 3 attempts, apply fixes on failure)
• If build is set → run it (up to 3 attempts, apply fixes on failure)
• If still failing after 3 attempts, report the error and stop

7. Ship — commit, push, open PRs

For each feature repo with changes:

• git add -A && git commit -m "<ticket title>"
• git push origin <branch-name>
• gh pr create --title "<ticket title>" --body "Closes #<issue-number>"

8. Confirm testing approach

PRs are now open. Ask the user before proceeding:

"PRs are ready. Would you like to: 1. Test it yourself first (I'll wait) 2. I'll test it for you using Playwright 3. Proceed directly to CI check and merge"

• Option 1: Wait for the user to confirm testing is done, then proceed to Step 9.
• Option 2: Use Playwright MCP tools to test the changes against the running app. Report results. If tests fail, fix and re-push (up to 2 attempts). When done, proceed to Step 9.
• Option 3: Proceed to Step 9 immediately.

9. Wait for CI

For each open PR:

• If waitForCI: false → skip, proceed to merge

• If waitForCI: true → actively monitor CI status:

  1. Run gh pr checks <pr-number> --repo <owner>/<repo> to get the current status
  2. If all checks pass → proceed to merge
  3. If any check fails → attempt to fix the code and push again (up to 2 attempts)
  4. If checks are still pending/in progress → tell the user the current status, wait 30 seconds, then check again. Repeat this loop up to 60 times (30 min total).
  5. If no checks are reported after the first poll → treat as pass and continue
  6. If still running after 30 min → ask: "CI is still running. Wait longer or merge anyway?"

  Do NOT stop or hang after pushing. You must actively run the gh pr checks command repeatedly until you get a definitive result (pass or fail).

10. Merge all PRs

Merge feature repos first, then spec location last:

• gh pr merge <number> --squash --delete-branch

If spec is a folder inside the project (not a separate repo), commit and push directly to main instead.

11. Add comment to issue

Post a comment on the GitHub Issue:

PRs merged:
- [repo-name#N](url)
- [spec-repo#N](url)

12. Move ticket to Done

• Update ticket status to the value of config.statuses.done in the GitHub Project
• Ensure config.github.assignee is still assigned to the ticket

13. Continue or stop

• If --once, stop
• Otherwise ask: "Implement next ticket? (yes/no)"
• If yes, go to Step 1. If no, stop.

Error handling

• If any step fails, report clearly with the step name and error
• Do not move to Done unless all PRs are merged
• On CI failure: attempt fix and repush before giving up
• On merge conflict: pull latest main, rebase the feature branch, then retry