--- name: Spec Kitty Implement Review slug: spec-kitty-implement-review category: AI Engineering description: Spec Kitty Implement Review orchestrates the implement-review loop for Spec Kitty work packages using any configured coding agent. Use it to dispatch implementation and review tasks, handle rejection cycles, and sequence work packages by dependency. github: "https://github.com/Priivacy-ai/spec-kitty/tree/main/src/doctrine/skills/spec-kitty-implement-review" language: Python stars: 1521 forks: 147 install: "npx degit https://github.com/Priivacy-ai/spec-kitty/tree/main/src/doctrine/skills/spec-kitty-implement-review ~/.claude/skills/spec-kitty-implement-review" installs_to: ~/.claude/skills/spec-kitty-implement-review source_path: src/doctrine/skills/spec-kitty-implement-review/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/Priivacy-ai/spec-kitty" added: 2026-08-19T07:26:36.582Z last_synced: 2026-08-19T07:26:36.582Z canonical_url: "https://dirskills.com/skills/spec-kitty-implement-review" --- # Spec Kitty Implement Review Spec Kitty Implement Review orchestrates the implement-review loop for Spec Kitty work packages using any configured coding agent. Use it to dispatch implementation and review tasks, handle rejection cycles, and sequence work packages by dependency. **Install:** ```bash npx degit https://github.com/Priivacy-ai/spec-kitty/tree/main/src/doctrine/skills/spec-kitty-implement-review ~/.claude/skills/spec-kitty-implement-review ``` ## README # spec-kitty-implement-review Orchestrate the implement-review loop for Spec Kitty work packages. This skill teaches any agent how to dispatch implementation and review to the configured agents, handle rejection loops, enforce cycle limits, and sequence WPs by dependency graph. ## When to Use This Skill - Implement one or more WPs through the full implement-review cycle - Coordinate cross-agent workflows (different agents for implement vs review) - Handle rejection feedback loops with cycle tracking - Run a full mission sprint (WP01 through WP_N) ## Core Concepts ### Agent Selection Spec-kitty selects agents from `.kittify/config.yaml`: ```yaml agents: available: [claude, codex, opencode] auto_commit: true ``` The orchestrator does NOT hardcode agent names. Instead: ```bash # Check which agents are configured spec-kitty agent config list # The workflow commands handle agent selection internally spec-kitty agent action implement WP01 --agent --profile spec-kitty agent action review WP01 --agent --profile ``` ### Agent Capabilities Not all agents can be dispatched the same way. The dispatch method depends on the agent's CLI capabilities: | Agent | Config Key | CLI Dispatch | Can Run move-task | Tier | |-------|-----------|--------------|-------------------|------| | Claude Code | `claude` | `claude -p "prompt" --output-format json` | Yes | 1 | | GitHub Codex | `codex` | `codex exec --sandbox danger-full-access -C -` (stdin) | Yes | 1 | | Google Gemini | `gemini` | `gemini -p "prompt" --yolo --output-format json` | Yes | 1 | | GitHub Copilot | `copilot` | `copilot -p "prompt" --yolo --silent` | Yes | 1 | | OpenCode | `opencode` | `opencode run "prompt" --format json` | Yes | 1 | | Qwen Code | `qwen` | `qwen -p "prompt" --yolo --output-format json` | Yes | 1 | | Kilocode | `kilocode` | `kilocode -a --yolo -j "prompt"` | Yes | 1 | | Augment Code | `auggie` | `auggie --acp "prompt"` | Yes | 1 | | Cursor | `cursor` | `timeout 300 cursor agent -p --force "prompt"` | Yes (may hang) | 2 | | Windsurf | `windsurf` | GUI only | No (orchestrator must) | 3 | | Roo Cline | `roo` | No official CLI | No (orchestrator must) | 3 | | Amazon Q | `q` | Transitioning | No (orchestrator must) | 3 | | Antigravity | `antigravity` | Google agent framework | Varies | 1 | **Tier 1**: Full headless CLI. Orchestrator dispatches and agent runs autonomously. **Tier 2**: CLI exists but needs workarounds (timeout wrappers, retry). **Tier 3**: GUI-only or no stable CLI. Orchestrator must run `move-task` after the agent completes, because the agent cannot run shell commands. ### Context Boundaries Keep implement-review sessions narrowly scoped. Compact after task pivots and avoid combining architecture, debugging, and implementation in one long session. If the work changes mode, preserve the current status and start a fresh compacted context before continuing. Use subagents whenever a task can be done in an isolated context, even if the work is not part of a large parallel sprint. Good candidates include one WP in a separate worktree, a review pass against a fixed diff, a focused debugging investigation, or validation that can run independently from the orchestrator's next scheduling decision. ### Sleep Protection (Unattended Runs) Unattended implement-review runs are long-lived: a dispatched implementation agent can run for many minutes between the short-lived `spec-kitty` CLI calls that claim and move WPs. None of those CLI calls hold the host machine awake by themselves — only a process that stays alive for the whole session can. If the host sleeps mid-dispatch (default laptop power settings on macOS), the dispatched agent is silently killed or its connection drops, and nothing in the mission state records why. The failure then looks identical to a flaky or stalled agent (see the **Stale WP** entry under Troubleshooting). Before dispatching the first agent, hold a keep-awake assertion for the session and release it when the loop ends: ```bash # macOS: idle-sleep assertion tied to this shell's own PID, backgrounded so # it does not block. Does NOT prevent lid-close sleep -- for a fully # unattended run, also disable lid-close sleep while plugged in, or keep # the lid open. caffeinate -i -w $$ & CAFFEINATE_PID=$! ``` Release it after Step 6 (accept/merge) or whenever the loop is explicitly halted: ```bash kill "$CAFFEINATE_PID" 2>/dev/null || true ``` **Linux (systemd distros — the large majority):** `systemd-inhibit` is the equivalent, and its `tail --pid` form self-releases when the process dies, mirroring `caffeinate -w` (no polling): ```bash systemd-inhibit --what=idle:sleep --why="spec-kitty implement-review" \ tail --pid $$ -f /dev/null & INHIBIT_PID=$! # release: kill "$INHIBIT_PID" 2>/dev/null || true ``` Non-systemd Linux (Alpine, minimal containers) has no standard primitive — it no-ops; rely on the host not sleeping. **Windows:** there is no shell one-liner. The keep-awake primitive is the Win32 `SetThreadExecutionState` API (callable from `ctypes`, no extra dependency), so it must be held by a live process, not a command — run under `spec-kitty-orchestrator` (below), or accept that an unattended Windows session can sleep. **Canonical cross-platform home.** When `spec-kitty-orchestrator` (the standalone binary, not an agent-harness session following this skill) drives the run, skip all of the above: it holds the idle-sleep assertion for the duration of `orchestrate`/`resume` (on by default; `--no-caffeinate` to opt out — see its README) behind a single no-op-safe `prevent_idle_sleep()` seam, which is the intended home for this handling across platforms. That coverage is internal to the binary and does not extend to an agent-harness session following this skill directly — which is exactly why the per-platform guidance above exists. --- ## The Mandatory Workflow Pattern Every WP MUST follow this state flow: ``` planned --> claimed --> [workflow implement] --> in_progress --> [agent works] --> for_review --> in_review --> approved or planned ``` After review rejection (WP moves back to `planned` with `review_status: has_feedback`): ``` planned --> claimed --> [workflow implement] --> in_progress --> [agent fixes] --> for_review --> in_review --> approved or planned ``` After ALL WPs are approved: run `spec-kitty accept --mission ` first as the mission-readiness nudge. If acceptance passes, run `spec-kitty merge --mission ` to merge everything and move WPs to `done`. **`approved` unblocks dependents immediately.** Do NOT wait for `done` before starting dependent WPs. The `done` lane is only reached via mission merge. To determine what to do next, always run: ```bash spec-kitty next --agent --mission ``` > **Note:** `--mission` is the canonical selector. The legacy `--feature` alias > has been removed from the internal/agent commands (e.g. `agent action implement`, > `agent action review`); always use `--mission`. This reads the dependency graph and current lane state and returns the exact command. Do NOT reason about lane transitions yourself. --- ## Step 1: Dispatch Implementation Implementation is a two-step process: claim the workspace, then dispatch an agent to do the work. ### Step 1a: Claim the Workspace ```bash OUTPUT=$(spec-kitty agent action implement WP## --mission --agent --profile 2>&1) ``` **Resolved dispatch identity** — pass the values selected by the dispatcher so the claim records what actually ran, rather than copying the authored frontmatter recommendation: ``` --agent --profile [--model --invocation-id ] ``` Examples: - `--agent claude --profile python-pedro` - `--agent claude --profile implementer-ivan` - `--agent claude --model claude-haiku-4-5 --profile reviewer-renata --invocation-id ` Pass `--model` only with a correlated `--invocation-id`. The durable Op's mission identity, WP, action, profile, and catalog-winning model must match the claim; missing, malformed, or mismatched evidence fails closed. A direct `--profile` is resolved through the canonical profile registry. A bare `--agent` claim remains allowed, but records explicit absence for model/profile instead of fabricating values from frontmatter. This command: - Moves WP from `planned` to `in_progress` - Creates or re-enters the worktree workspace - Generates the implementation prompt file Capture from output: - **Workspace path**: line containing `Workspace: cd ` - **Prompt file**: line containing `cat ` ```bash WORKSPACE=$(echo "$OUTPUT" | grep 'Workspace: cd ' | sed 's/.*Workspace: cd //') PROMPT_FILE=$(echo "$OUTPUT" | grep 'cat ' | sed 's/.*cat //') ``` ### Step 1b: Dispatch the Implementing Agent How you dispatch depends on your execution context. **If you are a Claude Code agent orchestrating via subagents (Task tool):** ```python Task( subagent_type="general-purpose", description="Implement WP##", prompt=f"""You are implementing WP## for mission . **CRITICAL: Work in the worktree directory:** cd {WORKSPACE} **Read the full implementation prompt:** cat {PROMPT_FILE} The prompt contains all context, acceptance criteria, and review feedback (if re-implementing after rejection). **Your task:** 1. Read the implementation prompt (contains all details) 2. If re-implementing: Read review feedback, update review_status: "acknowledged" 3. Read existing code paths BEFORE implementing 4. Implement all subtasks 5. Write tests that verify the contract (what the spec says) 6. Integration verification (MANDATORY before moving to for_review): - Verify new code is ACTUALLY CALLED from live entry points (not just defined) - Grep for imports of your new module in the files that should call it - If you created a new function/class, grep the codebase for callers — zero callers means the capability is dead code - Verify old code paths are removed or redirected - Grep for old function/class names to confirm removal CRITICAL: A module with passing tests but no callers is NOT implemented. The most common review failure is dead code — tests pass but the capability is never invoked from the live command path. 7. Run the project's declared validation command before handoff 8. **Diff-scoped lint sweep (MANDATORY before move-task to for_review)**: Catches lint regressions before they reach the cycle-1 reviewer — unused-import or formatting violations introduced by a WP should be caught here, scoped to the diff only so the implementer does not drown in pre-existing warnings owned by other WPs. Use the project's declared linter (see charter / project README for the configured command and source-file extension). ```bash # Replace `` with the project's source-file extension (e.g. py, ts, rs, go) # and `` with the project's configured linter invocation. CHANGED_SRC=$(git diff --name-only --diff-filter=AMR HEAD | rg '\.$' || true) if [ -n "$CHANGED_SRC" ]; then $CHANGED_SRC fi ``` - The command MUST exit 0. If it does not, fix or run the linter's autofix mode and re-run. - Paste the final command + exit code into the handoff note (e.g. `" diff-scoped check: 0 issues, exit 0"`). - On cycle-N re-implementation, use the WP's planning base instead of `HEAD`: `git diff --name-only $(git merge-base HEAD main)`. 9. Commit: git add -A && git commit -m "feat(WP##): " 10. Mark subtasks done: spec-kitty agent tasks mark-status T001 T002 ... --status done 11. Move to for_review: spec-kitty agent tasks move-task WP## --to for_review --note "Ready for review" """, run_in_background=True ) ``` **If you are dispatching to an external CLI agent (Tier 1):** Build a prompt file and pipe to the agent CLI: ```bash # Read the generated prompt PROMPT_CONTENT=$(cat "$PROMPT_FILE") # Dispatch to configured agent (examples for each CLI) # Claude Code: claude -p "$PROMPT_CONTENT" --output-format json -C "$WORKSPACE" # GitHub Codex: # move-task writes git/status locks and may touch local sync state; workspace-write/full-auto is too narrow. printf '%s' "$PROMPT_CONTENT" | codex exec --sandbox danger-full-access -C "$WORKSPACE" - # Google Gemini: gemini -p "$PROMPT_CONTENT" --yolo --output-format json -C "$WORKSPACE" # OpenCode: opencode run "$PROMPT_CONTENT" --format json -C "$WORKSPACE" # Qwen Code: qwen -p "$PROMPT_CONTENT" --yolo --output-format json -C "$WORKSPACE" # Kilocode: kilocode -a --yolo -j "$PROMPT_CONTENT" -C "$WORKSPACE" # Augment Code: auggie --acp "$PROMPT_CONTENT" -C "$WORKSPACE" # Cursor (Tier 2 -- needs timeout wrapper): timeout 600 cursor agent -p --force --output-format json "$PROMPT_CONTENT" -C "$WORKSPACE" ``` **If the agent is Tier 3 (GUI-only):** The orchestrator cannot dispatch automatically. Instead: 1. Print the workspace path and prompt file for the human operator 2. Wait for the human to run the agent manually in the workspace 3. After the agent finishes, the orchestrator runs `move-task` on behalf of the agent (since GUI agents cannot execute CLI commands) ```bash echo "Manual dispatch required for agent: " echo "Workspace: cd $WORKSPACE" echo "Prompt: cat $PROMPT_FILE" echo "After agent completes, run:" echo " spec-kitty agent tasks move-task WP## --to for_review --note 'Ready'" ``` --- ## Step 2: Monitor Progress Check WP status at any time: ```bash spec-kitty agent tasks status ``` This shows: - Kanban board with WPs in lanes: planned, claimed, in_progress, for_review, in_review, approved, done - Progress bar showing completion percentage - Which WPs are ready for review, in progress, and planned Use this frequently between dispatch and review steps. --- ## Step 3: Dispatch Review When a WP reaches `for_review`, dispatch a review agent. ### Step 3a: Claim the Review ```bash OUTPUT=$(spec-kitty agent action review WP## --mission --agent --profile 2>&1) REVIEW_PROMPT=$(echo "$OUTPUT" | grep -o '/var/folders[^ ]*/spec-kitty-review-WP[0-9]*.md' || echo "$OUTPUT" | grep 'cat ' | sed 's/.*cat //') WORKTREE=$(echo "$OUTPUT" | grep 'Workspace: cd ' | sed 's/.*Workspace: cd //') ``` ### Step 3b: Dispatch the Review Agent **If you are a Claude Code agent (Task tool):** ```python Task( subagent_type="general-purpose", description="Review WP##", prompt=f"""You are reviewing WP## for mission . **CRITICAL: Work in the worktree directory:** cd {WORKTREE} **Read the full review prompt:** cat {REVIEW_PROMPT} The review prompt contains: - Acceptance criteria for this WP - Git diff commands with the correct base branch - Dependency warnings for downstream WPs - Completion instructions (approve/reject commands) **Your task:** 1. Read the review prompt (it is the source of truth) 2. Run the git diff commands listed in the prompt 3. Check each acceptance criterion against the diff 4. Check for unrelated changes outside WP scope 5. Issue exactly one verdict: **If ALL acceptance criteria met:** spec-kitty agent tasks move-task WP## --to approved --note "Review passed: " **If criteria NOT met:** Write structured feedback to a temp file, then: spec-kitty agent tasks move-task WP## --to planned --force --review-feedback-file """, run_in_background=True ) ``` **If dispatching to an external CLI agent:** Build a combined prompt and pipe to the agent. The mandatory instruction ensures the agent runs the `move-task` command after reviewing. ```bash # Build combined prompt with mandatory instruction. # Scope temp paths by so concurrent missions sharing a WP id (e.g. # two missions both with WP01) do not collide on the same /tmp file (#1831). printf 'IMPORTANT: After reviewing, you MUST execute the appropriate spec-kitty agent tasks move-task command shown at the bottom of this prompt.\n---\n' > /tmp/review-prompt--WP##.md cat "$REVIEW_PROMPT" >> /tmp/review-prompt--WP##.md # Dispatch to configured reviewer (same CLI patterns as Step 1b) # Example for codex: cat /tmp/review-prompt--WP##.md | codex exec --sandbox danger-full-access \ -C "$WORKTREE" --add-dir "$(pwd)" \ -o "/tmp/review-result--WP##.md" - # Example for claude: claude -p "$(cat /tmp/review-prompt--WP##.md)" --output-format json -C "$WORKTREE" # Example for gemini: gemini -p "$(cat /tmp/review-prompt--WP##.md)" --yolo --output-format json -C "$WORKTREE" ``` Capture the reviewer command exit status. If the configured/chosen reviewer fails, do not silently approve and do not fall back to the implementing agent. Print a structured error and halt in unattended/noninteractive mode: ```text ERROR: Configured reviewer '' failed (). Options: a) Retry with '' after fixing the error b) Switch reviewer: spec-kitty agent action review WP## --mission --agent c) Proceed with self-review -- WARNING: no independent review ``` Self-review fallback is only allowed after an explicit operator decision. The approval command must preserve the failure metadata: ```bash spec-kitty agent tasks move-task WP## --to approved --force \ --self-review-fallback \ --intended-reviewer \ --reviewer-failure-reason "" \ --note "Self-review fallback after reviewer failure: " ``` **If the reviewer is Tier 3 (GUI-only) or cannot run move-task:** After the reviewer completes, the orchestrator must: 1. Read the reviewer's output to determine pass/fail 2. Run `move-task` on behalf of the reviewer ```bash # Read reviewer output, then: # If approved: spec-kitty agent tasks move-task WP## --to approved --note "Review passed (by ): " # If rejected: spec-kitty agent tasks move-task WP## --to planned --force \ --review-feedback-file /tmp/feedback--WP##.md ``` ### Step 3c: Verify the Outcome After review completes: ```bash # Check the WP lane spec-kitty agent tasks status # If reviewer output was captured to a file: cat /tmp/review-result--WP##.md ``` Before final approval, if `spec.md` references GitHub issues, ensure `issue-matrix.json` (JSON-first canonical artifact; legacy `issue-matrix.md` missions are read via failover, never re-authored) exists and every referenced issue has a verdict: `fixed`, `verified-already-fixed`, a documented follow-up (`deferred-with-followup`), or `in-mission` (being closed by a later WP in this same mission). `unknown`/empty verdicts block approval. The CLI enforces this guard on `move-task --to approved/done`. An `in-mission` verdict passes per-WP `approved` (so a dependency chain is not blocked on its own downstream WPs) but is **rejected on `done`** — resolve every `in-mission` row to a terminal verdict before the mission merges. --- ## Step 4: Handle Review Rejection When a reviewer moves a WP back to `planned` with feedback, the orchestrator must re-dispatch implementation. ### What Happens on Rejection 1. The reviewer runs `move-task WP## --to planned --force --review-feedback-file ` 2. The event log records the lane transition and review-feedback reference; the WP planning file remains byte-stable. ### Re-Implementation Steps 1. **Re-dispatch implementation** using the same two-step pattern from Step 1: ```bash OUTPUT=$(spec-kitty agent action implement WP## --mission --agent --profile 2>&1) WORKSPACE=$(echo "$OUTPUT" | grep 'Workspace: cd ' | sed 's/.*Workspace: cd //') PROMPT_FILE=$(echo "$OUTPUT" | grep 'cat ' | sed 's/.*cat //') ``` Then dispatch the implementing agent (Step 1b). The prompt file now includes the review feedback. 2. **Wait for re-implementation to complete** (WP reaches `for_review`) 3. **Re-dispatch review** (Step 3) 4. **Trac