Run an Autonomous Mission
Who is this for (1)
- Stakeholder Persona: External Tech Lead Evaluator — Written for the External Tech Lead Evaluator reader.
Use this guide when an agent or external orchestrator runs a Spec Kitty mission end to end from a local checkout.
Prerequisites
spec-kittyis installed and authenticated for any services your run uses- The repository checkout is clean before starting
- The intended target branch is known, usually
main - Agent CLIs or orchestrator providers are installed
1. Create the Mission
Start from the intake prompt:
/spec-kitty.specify @start-here.mdConfirm the generated mission slug and target branch before continuing.
2. Plan the Mission
/spec-kitty.plan @start-here.mdReview the plan for scope, branch intent, and known risks. Keep unrelated CLI or documentation improvements out of the mission unless they are part of the spec.
3. Generate and Finalize Tasks
/spec-kitty.tasks @start-here.mdIf you are operating from a terminal, finalize tasks explicitly:
spec-kitty agent mission finalize-tasks --mission <mission-slug>Check lanes.json and WP prompt frontmatter before implementation starts.
4. Run Implementation and Review
Use the normal implement-review loop:
/spec-kitty-implement-reviewOr drive each WP through the CLI:
spec-kitty agent action implement WP01 --mission <mission-slug> --agent <agent>cd <workspace path printed by the command># implement, test, commitspec-kitty agent tasks move-task WP01 --to for_review --mission <mission-slug> --note "Ready for review"spec-kitty agent action review WP01 --mission <mission-slug> --agent <reviewer>Continue until every WP is approved.
5. Accept the Mission
/spec-kitty.acceptOr:
spec-kitty accept --mission <mission-slug>Acceptance verifies mission readiness. It does not replace merge pre-flight validation.
6. Preview the Merge
Before mutating the target branch, run:
spec-kitty merge --mission <mission-slug> --dry-runFix dirty worktrees, missing worktrees, and unresolved WP states before trying a real merge.
7. Handle TARGET_BRANCH_NOT_SYNCHRONIZED
Autonomous local runs can accumulate many local commits on main, including
planning artifacts, status events, review notes, and orchestration commits.
When that happens, spec-kitty merge may stop before mutating merge state:
Error: Target branch is not synchronized with its tracking branch. diagnostic_code: TARGET_BRANCH_NOT_SYNCHRONIZED branch_or_work_package: main violated_invariant: local_target_branch_must_match_tracking_branchDo not reset, rebase, force-push, or push local main just to clear this
pre-flight. Those operations can discard or publish unrelated local history.
First inspect the divergence:
git fetch origin maingit log --oneline --left-right --cherry-pick main...origin/maingit diff --name-only origin/main...mainIf every local commit is intentionally ready for main, a maintainer can decide
to publish it. Otherwise, use a focused PR.
Direct Mission-Branch PR
Use this path when kitty/mission-<mission-slug> already contains the approved
mission result:
git push -u origin kitty/mission-<mission-slug>gh pr create --base main --head kitty/mission-<mission-slug> --fillThis was the successful path for the autonomous run behind PR #1251: the PR
surface was the mission result, not the local orchestration history on main.
Dedicated Focused PR Branch
Use this path when you want the PR branch name to be separate from the mission branch:
git switch -c kitty/pr/<mission-slug>-to-main kitty/mission-<mission-slug>git push -u origin kitty/pr/<mission-slug>-to-maingh pr create --base main --head kitty/pr/<mission-slug>-to-main --fillPrefer squash-merge for autonomous runs with large orchestration commit piles:
gh pr merge --auto # queues it; the merge queue rebase-merges once the required checks pass8. Run Mission Review
After the PR lands, update your local checkout and run:
git fetch origin maingit switch maingit pull --ff-only origin mainspec-kitty agent mission review --mission <mission-slug>Mission review verifies requirement coverage and drift after landing.
9. Run the Retrospective Loop
Verify the retrospective record and inspect synthesis proposals:
spec-kitty retrospect create --mission <mission-slug>spec-kitty retrospect summaryspec-kitty agent retrospect synthesize --mission <mission-slug>Apply an individual proposal only after review:
spec-kitty agent retrospect synthesize --mission <mission-slug> --apply <proposal-id>