spec-kitty-implement-review

# 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 feature 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 <your-name>
spec-kitty agent action review WP01 --agent <reviewer-name>
```

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

---

## The Mandatory Workflow Pattern

Every WP MUST follow this state flow:

```
planned --> [workflow implement] --> in_progress --> [agent works] --> for_review --> [review] --> approved or planned
```

After review rejection (WP moves back to `planned` with `review_status: has_feedback`):

```
planned --> [workflow implement] --> in_progress --> [agent fixes] --> for_review --> [review] --> approved or planned
```

After ALL WPs are approved: run `spec-kitty accept --mission <slug>` first as
the mission-readiness nudge. If acceptance passes, run
`spec-kitty merge --mission <slug>` 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 feature merge.

To determine what to do next, always run:

```bash
spec-kitty next --agent <your-name> --mission <mission-slug>
```

> **Note:** `--feature` is the hidden deprecated alias for `--mission`.
> Always use `--mission` in new scripts.

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 <slug> --agent <tool>:<model>:<profile>:<role> 2>&1)
```

**Agent identity** — always provide the full compact form so the WP records who is working:

```
--agent <tool>:<model>:<profile>:<role>
```

Examples:
- `--agent opencode:o3:python-pedro:implementer`
- `--agent claude:sonnet:implementer:implementer`
- `--agent codex:gpt-4o:python-pedro:implementer`

Partial compact strings are accepted (missing fields default to `unknown`).
You may also use explicit flags instead:
- `--tool <tool>` — agent key (e.g. `opencode`, `claude`)
- `--model <model>` — AI model identifier (e.g. `o3`, `gpt-4o`)
- `--profile <profile-id>` — doctrine profile (e.g. `python-pedro`)
- `--role <role>` — role label (e.g. `implementer`, `reviewer`)

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 <path>`
- **Prompt file**: line containing `cat <path>`

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

```pytho