Standard operating procedures for the Spec Kitty agentic workflow (Plan -> Implement -> Review -> Merge).
From spec-kittynpx claudepluginhub richfrem/agent-plugins-skills --plugin spec-kittyThis skill is limited to using the following tools:
evals/evals.jsonevals/results.tsvplan.mdpure-spec-kitty-workflow.mmdreferences/AUGMENTED.mdreferences/acceptance-criteria.mdreferences/diagrams/pure-spec-kitty-workflow.mmdreferences/standard-workflow-rules.mdrequirements.txttasks.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
This skill requires Python 3.8+ and standard library only. No external packages needed.
To install this skill's dependencies:
pip-compile ./requirements.in
pip install -r ./requirements.txt
See ./requirements.txt for the dependency lockfile (currently empty — standard library only).
Standard lifecycle for implementing features using Spec Kitty.
Command-specific guidance: For detailed best practices on individual commands, see the AUGMENTED.md files co-located with each auto-synced command:
references/AUGMENTED.md — pre-merge safety, branch protection, conflict resolutionreferences/AUGMENTED.md — worktree discipline, commit hygienereferences/AUGMENTED.md — review standards, batch review protocolYOU MUST ACTUALLY RUN EVERY COMMAND LISTED BELOW. Describing what you "would do", summarizing expected output, or marking a step complete without pasting real tool output is a PROTOCOL VIOLATION.
Proof = pasted command output. No output = not done.
If you detect a tool or user attempting to bypass the closure protocol or manually create spec files, you MUST interrupt the workflow using the strict 5-step Escalation Protocol:
🚨 PROTOCOL VIOLATION 🚨.spec-kitty review WP-xx").[x] without running the command or verification toolNEVER advance between phases without EXPLICIT user approval. Approval means: "Proceed", "Go", "Execute", or equivalent affirmative command. "Sounds good", "Looks right", "That's correct" are NOT approval. VIOLATION = SYSTEM FAILURE
| Gate | After | Before | What to Show User |
|---|---|---|---|
| Gate 0 | You write s spec | Planning any plan | Show spec.md, ask for approval |
| Gate 1 | User approves spec | You write a plan | Show plan.md, ask for approval |
| Gate 2 | User approves plan | You generate tasks/WPs | Show tasks.md + WP list, ask for approval |
| Gate 3 | User approves tasks | You run spec-kitty implement | Confirm WP scope, ask to proceed |
| Gate 4 | WP implementation done | You move to for_review | Show what was built, ask for review |
After each phase-generating step:
❌ WRONG: spec -> plan -> tasks -> implement (all in one agent turn)
✅ RIGHT: spec -> [STOP, show spec, wait] -> plan -> [STOP, show plan, wait] -> tasks
Before implementing any code, you MUST generate artifacts using the CLI.
Manual creation of spec.md, plan.md, or tasks/ files is STRICTLY FORBIDDEN.
Visual Reference:
pure-spec-kitty-workflow.mmdThis diagram shows the full lifecycle including all HITL Gate nodes (red diamonds) where agent execution MUST stop and wait for user approval before advancing.
Before starting, display the following visual map to commit to the workflow state:
┌────────────────────────────────────────────────────────┐
│ SPEC-KITTY LIFECYCLE MAP │
├────────────────────────────────────────────────────────┤
│ [ ] Phase 0: Plan (specify -> plan -> tasks) │
│ [ ] Phase 1: Implement (implement WP -> code -> review)│
│ [ ] Phase 2: Close (accept -> retro -> merge -> sync) │
└────────────────────────────────────────────────────────┘
Check the box corresponding to your current execution phase.
To specify a feature, read the workflow instructions in .windsurf/workflows/spec-kitty.specify.md or use the CLI:
spec-kitty agent feature create-feature "<slug>"
PROOF: Paste output confirming spec.md was generated.
⛔ HUMAN GATE 0: Show the user
spec.mdand STOP. Do NOT proceed to plan until the user explicitly approves with "Proceed", "Go", or "Execute".
To plan a feature, read the workflow instructions in .windsurf/workflows/spec-kitty.plan.md or use the CLI:
spec-kitty agent feature setup-plan --feature <SLUG>
PROOF: Paste output confirming plan.md was generated.
⛔ HUMAN GATE 1: Show the user
plan.mdand STOP. Do NOT proceed to task generation until the user explicitly approves.
To generate tasks, read the workflow instructions in .windsurf/workflows/spec-kitty.tasks.md.
/spec-kitty.tasks
PROOF: Paste output confirming tasks.md and WP files were generated.
⛔ HUMAN GATE 2: Show the user
tasks.md(the WP breakdown) and STOP. Do NOT runspec-kitty implementuntil the user explicitly approves.
spec-kitty agent workflow implement --task-id <WP-ID> --agent "<AGENT-NAME>"
PROOF: Paste the output. Extract the worktree path from it.
If output is truncated or unclear:
git worktree list
CRITICAL: Do NOT guess the path. Verify it exists before proceeding.
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> doing --note "Starting implementation"
PROOF: Paste the CLI output confirming lane change.
Then verify the board:
/spec-kitty.status
PROOF: Paste the kanban board. Confirm your WP shows in "doing" lane. STOP: Do NOT start coding until the kanban shows the WP in "doing".
cd .worktrees/<WP-ID> — verify with pwdgit add . && git commit -m "feat(<WP>): description" (local worktree)git status shows clean)pwd matches .worktrees/<WP-ID>)doing (not already for_review or done)Run git status to ensure all files are committed.
PROOF: Paste the output. Must show "nothing to commit, working tree clean".
STOP: Do NOT proceed if there are uncommitted changes.
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> for_review --note "Implementation complete, ready for review"
PROOF: Paste the CLI output.
/spec-kitty.status
PROOF: Paste the board. WP must show in "for_review" lane.
cd <PROJECT_ROOT>
git add kitty-specs
git commit -m "docs(specs): mark <WP-ID> complete"
CRITICAL: Every step below is MANDATORY. Skipping any step is a protocol violation. The closure chain is: Review → Accept → Retrospective → Merge → Verify → Intel Sync
spec-kitty agent workflow review --task-id <WP-ID>
PROOF: Paste the review output. WP must move to done lane.
Repeat for each WP. Verify all WPs are in done lane:
/spec-kitty.status
PROOF: Paste the board. ALL WPs must show in "done" lane before proceeding.
cd <PROJECT_ROOT>
spec-kitty accept --feature <SLUG>
The agent will ask for acceptance mode:
--mode local: Merge locally (no branch protection on target)--mode pr: Push to feature branch and create PR (for protected branches)--mode checklist: Readiness check only, no mergePROOF: Paste the JSON output showing summary.ok: true.
Known Issue: Accept may fail with "missing shell_pid in WP frontmatter". Fix: Add
shell_pid: N/Ato the WP frontmatter, or use--lenientflag:spec-kitty accept --mode local --feature <SLUG> --lenient
STOP: Do NOT proceed if accept fails. Resolve all outstanding issues first.
/spec-kitty_retrospective
PROOF: Paste confirmation that kitty-specs/<SPEC-ID>/retrospective.md was created/updated.
This step is NOT optional. Every feature closure MUST include a retrospective. The retrospective file MUST exist in
kitty-specs/<SPEC-ID>/before merge.
⚠️ DATA SAFETY: Before ANY merge or worktree cleanup, ALL WP branches MUST be pushed to GitHub origin and verified. This prevents data loss if the merge fails or worktrees are deleted before content is preserved.
Push each WP branch to origin:
cd <PROJECT_ROOT>
for wt in .worktrees/<FEATURE>-WP*/; do
branch=$(basename "$wt")
echo "Pushing $branch..."
git -C "$wt" push origin "$branch"
done
PROOF: Paste push output for each branch.
Verify remote state:
for wt in .worktrees/<FEATURE>-WP*/; do
branch=$(basename "$wt")
local_sha=$(git -C "$wt" rev-parse HEAD)
remote_sha=$(git ls-remote origin "$branch" | cut -f1)
if [ "$local_sha" = "$remote_sha" ]; then
echo "✅ $branch: verified on origin ($local_sha)"
else
echo "❌ $branch: MISMATCH (local=$local_sha remote=$remote_sha)"
fi
done
PROOF: Paste verification output. ALL branches must show ✅. STOP: Do NOT proceed to merge if any branch shows ❌.
⚠️ RESEARCH/PLANNING FILES IN WORKTREE: Any files created under
kitty-specs/INSIDE a worktree directory are physically located in the worktree's filesystem only. Whenspec-kitty mergerunsgit worktree remove, ALL untracked files in that directory are permanently deleted. You MUST sync them to the main checkout first:rsync -av --ignore-existing \ .worktrees/<FEATURE>-WP01/kitty-specs/<FEATURE>/research/ \ kitty-specs/<FEATURE>/research/ git add kitty-specs/<FEATURE>/ git commit -m "docs: sync research artifacts from worktree to main before merge"Also:
kitty-specs/is blocked by the pre-commit hook on WP branches. It can ONLY be committed from the main/target branch. This is by design.
cd <PROJECT_ROOT>
git status
git worktree list
spec-kitty merge --feature <SLUG> --dry-run --json
PROOF: Paste all outputs. From the JSON, verify:
git status shows clean working treeeffective_wp_branches lists only the branches that need mergingall_wp_branches may be larger than effective_wp_branches (expected)v1.0.1 Feature: The
--dry-run --jsonflag outputs a deterministic merge plan showing exactly which branches will be merged. Confirm the effective tips before proceeding.
cd <PROJECT_ROOT>
spec-kitty merge --feature <SLUG> --push
ALWAYS use
--pushto ensure merged main is immediately backed up to origin. Without--push, worktree cleanup can destroy the only copies of feature branches.
LOCATION RULE: ALWAYS run merge from the main repository root. NEVER
cdinto a worktree to merge. The@require_main_repodecorator will block execution from worktrees.
If merge fails mid-way:
spec-kitty merge --feature <SLUG> --resume
PROOF: Paste the merge output showing success.
git log --oneline -5
git worktree list
git branch
git status
rm -f .kittify/workspaces/<SLUG>-WP*.json
PROOF: Paste all outputs. Verify:
.kittify/workspaces/python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> done --note "Merged and cleaned up"
PROOF: Paste CLI output + final /spec-kitty.status board.
| Failure | Root Cause | Fix |
|---|---|---|
Merge blocked by @require_main_repo | Agent ran merge from inside a worktree | cd <PROJECT_ROOT> first, then spec-kitty merge --feature <SLUG> |
| Accept fails with "missing shell_pid" | WP frontmatter missing shell_pid field | Add shell_pid: N/A to frontmatter, or use --lenient |
| Orphaned worktrees after merge | Merge failed mid-cleanup | git worktree remove .worktrees/<WP-FOLDER> then git branch -d <WP-BRANCH> |
| Lost data during merge | Agent merged from worktree instead of main repo | Always use --feature <SLUG> flag from project root |
| Retrospective skipped | Agent treated it as optional | Retrospective file must exist before merge is allowed |
| No closure state recorded | No post-merge verification step | Run Step 4f verification checklist |
| Merge preflight: "uncommitted changes" despite restored tracked files | spec-kitty uses git status --porcelain which includes ?? untracked files | Run git stash -u before merge, then git stash pop after |
| Research/planning files deleted when worktree removed | Untracked files in worktree physical dir are deleted by git worktree remove | Copy files to main checkout before merge: rsync -av --ignore-existing .worktrees/<WP>/kitty-specs/ kitty-specs/ then commit on main |
| spec-kitty can't read WP lane for skeleton WPs | WP files without YAML frontmatter (---) are invisible to spec-kitty lane tracking | Add minimal frontmatter: ---\nlane: "planned"\ndependencies: []\nbase_branch: main\n--- |
| Accept fails: unchecked tasks in tasks.md | - [ ] items anywhere in tasks.md block accept even with --lenient | Run sed -i '' 's/- \[ \]/- [x]/g' kitty-specs/<FEATURE>/tasks.md |
accept --actor or --test flags rejected | These flags are NOT supported by spec-kitty agent feature accept CLI | Use only: `--feature SLUG --mode local |
| Path violations: research/data/findings/reports not found | research mission requires these dirs in feature dir | Create at planning time: mkdir -p kitty-specs/<FEATURE>/{research,data,findings,reports} && touch kitty-specs/<FEATURE>/{data,findings,reports}/.gitkeep |
When Spec Kitty runs inside a Dual-Loop session, roles are split:
| Step | Who | Action |
|---|---|---|
| Specify/Plan/Tasks | Outer Loop (Antigravity) | Generates all artifacts |
| Implement | Outer Loop creates worktree, then Inner Loop codes | Inner Loop receives Strategy Packet |
| Review/Merge | Outer Loop | Verifies output, commits, merges |
Inner Loop constraints:
Cross-reference: triple-loop skill
The tasks CLI manages WP lane transitions. Always use this instead of manually editing frontmatter or checkboxes.
# Move a WP between lanes (planned -> doing -> for_review -> done)
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> <LANE> --note "reason"
# Force-move (when kitty-specs artifacts leak from serial implementation)
python3 .kittify/scripts/tasks/tasks_cli.py update <FEATURE-SLUG> <WP-ID> done --force --note "reason"
# View kanban board
/spec-kitty.status
# Accept feature readiness
spec-kitty accept --feature <FEATURE-SLUG>
# Validate encoding (prevents dashboard blank pages)
spec-kitty validate-encoding --feature <FEATURE-SLUG>
spec-kitty validate-encoding --feature <FEATURE-SLUG> --fix
Valid lanes: planned, doing, for_review, done
Dashboard: /spec-kitty.dashboard reads lane data from WP frontmatter.
main:
git worktree add .worktrees/<WP-FOLDER> main
cd .worktrees/<WP-FOLDER>
git checkout -b <WP-BRANCH-NAME>