/spec-kitty-implement-review

name: spec-kitty-implement-review
description: >-
  Orchestrate the implement-review loop for Spec Kitty work packages using any
  configured agent. Covers agent dispatch, state transitions, rejection cycles,
  arbiter escalation, and dependency-aware sequencing across all 13 supported
  coding agents.
  Triggers: "implement and review WPs", "run the implement-review loop",
  "orchestrate WP implementation", "dispatch agents for WPs",
  "coordinate implement and review", "sprint through WPs".
  Does NOT handle: specify/plan/tasks phases, setup or repair, glossary
  maintenance, or direct code editing by the orchestrator.
argument-hint: "[WP_ID or 'all' for full mission sprint]"

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`:

agents:
  available: [claude, codex, opencode]
  auto_commit: true

The orchestrator does NOT hardcode agent names. Instead:

# Check which agents are configured
spec-kitty agent config list

# The workflow commands handle agent selection internally
spec-kitty agent action implement WP01 --agent <tool> --profile <profile>
spec-kitty agent action review WP01 --agent <tool> --profile <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 <dir> -` (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:

# 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:

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):

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.**