Video-Tree-TRM5/.claude/skills/subagent-driven-development/SKILL.md

---
name: subagent-driven-development
description: Execute an implementation plan by delegating each task to a Claude Code subagent (spawned with the Agent tool) and reviewing its work with three-stage Codex reviews — spec compliance, functional quality, then code style.
---

# Subagent-Driven Development

## Overview

Execute a plan by delegating each task to a **Claude Code subagent** (spawned with the `Agent` tool, `subagent_type=general-purpose`) and reviewing every result with three stages of independent **Codex** review: **spec compliance** first, then **functional quality**, then **code style**.

**Why a cross-provider split:** Claude Code is the controller. A Claude Code subagent is the implementer. Codex sessions are the reviewers. The implementer and the reviewers come from different model families and different providers — code is never graded by the same model that wrote it. This eliminates the self-evaluation blind spot that single-model loops suffer from, and it gives the controller a clean, isolated context per task (each implementer subagent works in its own context) without spending the controller's own context window on implementation details.

**Core principle:** Fresh Claude subagent per task + three-stage Codex review (spec, functional quality, style) = high quality, fast iteration.

**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete.

## When to use

```
digraph when_to_use {
  "Have an implementation plan?" [shape=diamond];
  "Tasks mostly independent?"    [shape=diamond];
  "subagent-driven-development"  [shape=box style=filled fillcolor=lightgreen];
  "Brainstorm or decompose first" [shape=box];

  "Have an implementation plan?" -> "Tasks mostly independent?" [label="yes"];
  "Have an implementation plan?" -> "Brainstorm or decompose first" [label="no"];
  "Tasks mostly independent?"   -> "subagent-driven-development"  [label="yes"];
  "Tasks mostly independent?"   -> "Brainstorm or decompose first" [label="no — tightly coupled"];
}
```

This skill assumes you are running inside **Claude Code** with the `codex-plugin-cc` plugin installed (Codex runs the three review stages). It is the only supported harness.

## Prerequisites

Before invoking this skill, verify the Codex plugin is installed and ready — Codex runs the three review stages:

```
/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup
```

`/codex:setup` will report "Codex is ready" when authentication and the local Codex CLI are good to go. If it is not ready, stop and tell the user — this skill cannot run its review stages without a working Codex plugin.

### Recommended Codex configuration

Drop a `.codex/config.toml` at the repository root (or in `~/.codex/config.toml` for user-level defaults) so every dispatched Codex **review** session uses the strongest model and the highest reasoning effort:

```toml
# .codex/config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
```

You can still override per-dispatch with `--model` and `--effort` flags if a specific review genuinely warrants a different setting, but the default for this skill's reviews is **gpt-5.4 at high effort**. Review quality is what protects the codebase across the loop; do not save tokens here.

## tmux execution policy

Any command expected to take longer than 30 seconds (e.g. a slow test suite in the automated quality gate) **must** be executed inside a tmux session. This is purely an engineering convenience: it lets the human operator attach and watch progress at any time instead of staring at a blocked foreground shell.

**Naming convention**: `sdd-task<N>-<short-description>` (e.g., `sdd-task3-tests`, `sdd-task5-gate`)

**How to run**:
```bash
# Create a tmux session and run the command
tmux new-session -d -s sdd-task<N>-<name> "<command>; echo '=== DONE ==='; sleep 86400"

# Poll for status
tmux capture-pane -t sdd-task<N>-<name> -p | tail -20

# Human attaches to inspect
tmux attach -t sdd-task<N>-<name>
```

**Scope — when tmux is required**:
- pytest execution in the automated quality gate (Step 4.5) when tests are expected to exceed 30 seconds
- Any other command a task triggers that is expected to run longer than 30 seconds

**Forbidden**: Running long-lived commands directly in the foreground shell without tmux.

## Workflow

```
digraph workflow {
  "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
  "Build/update knowledge graph\n(/graphify . --update)" [shape=box];

  "Dispatch Claude subagent implementer (Agent tool, ./claude-implementer-prompt.md), record agentId" [shape=box];
  "Implementer subagent reports STATUS"   [shape=diamond];
  "Provide missing context, continue via SendMessage(to: agentId)" [shape=box];
  "Escalate / re-plan / spawn fresh subagent with more guidance" [shape=box];

  "Dispatch Codex spec reviewer (/codex:rescue --fresh --wait, ./spec-reviewer-prompt.md)" [shape=box];
  "Spec reviewer approves?" [shape=diamond];
  "Fix spec gaps via SendMessage(to: agentId)" [shape=box];

  "Dispatch Codex code quality reviewer (/codex:rescue --fresh --wait, ./code-quality-reviewer-prompt.md)" [shape=box];
  "Quality reviewer approves?" [shape=diamond];
  "Fix quality issues via SendMessage(to: agentId)" [shape=box];

  "Dispatch Codex code style reviewer (/codex:rescue --fresh --wait, ./code-style-reviewer-prompt.md)" [shape=box];
  "Style reviewer approves?" [shape=diamond];
  "Fix style issues via SendMessage(to: agentId)" [shape=box];

  "Mark task complete in TodoWrite" [shape=box];
  "More tasks remain?" [shape=diamond];

  "Dispatch Codex final whole-implementation reviewer (/codex:rescue --fresh --wait)" [shape=box];
  "Regenerate knowledge graph\n(/graphify . --update)" [shape=box];
  "Use finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

  "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Build/update knowledge graph\n(/graphify . --update)";
  "Build/update knowledge graph\n(/graphify . --update)" -> "Dispatch Claude subagent implementer (Agent tool, ./claude-implementer-prompt.md), record agentId";
  "Dispatch Claude subagent implementer (Agent tool, ./claude-implementer-prompt.md), record agentId" -> "Implementer subagent reports STATUS";

  "Automated Quality Gate\n(conda run -n Video-Tree-TRM ruff/pytest/radon)" [shape=box];
  "Gate passes?" [shape=diamond];
  "Fix gate issues via SendMessage(to: agentId)" [shape=box];

  "Implementer subagent reports STATUS" -> "Automated Quality Gate\n(conda run -n Video-Tree-TRM ruff/pytest/radon)" [label="DONE / DONE_WITH_CONCERNS"];
  "Automated Quality Gate\n(conda run -n Video-Tree-TRM ruff/pytest/radon)" -> "Gate passes?";
  "Gate passes?" -> "Dispatch Codex spec reviewer (/codex:rescue --fresh --wait, ./spec-reviewer-prompt.md)" [label="yes"];
  "Gate passes?" -> "Fix gate issues via SendMessage(to: agentId)" [label="no (max 2 retries)"];
  "Fix gate issues via SendMessage(to: agentId)" -> "Automated Quality Gate\n(conda run -n Video-Tree-TRM ruff/pytest/radon)";
  "Implementer subagent reports STATUS" -> "Provide missing context, continue via SendMessage(to: agentId)" [label="NEEDS_CONTEXT"];
  "Implementer subagent reports STATUS" -> "Escalate / re-plan / spawn fresh subagent with more guidance" [label="BLOCKED"];
  "Provide missing context, continue via SendMessage(to: agentId)" -> "Implementer subagent reports STATUS";

  "Dispatch Codex spec reviewer (/codex:rescue --fresh --wait, ./spec-reviewer-prompt.md)" -> "Spec reviewer approves?";
  "Spec reviewer approves?" -> "Fix spec gaps via SendMessage(to: agentId)" [label="no"];
  "Fix spec gaps via SendMessage(to: agentId)" -> "Dispatch Codex spec reviewer (/codex:rescue --fresh --wait, ./spec-reviewer-prompt.md)";
  "Spec reviewer approves?" -> "Dispatch Codex code quality reviewer (/codex:rescue --fresh --wait, ./code-quality-reviewer-prompt.md)" [label="yes"];

  "Dispatch Codex code quality reviewer (/codex:rescue --fresh --wait, ./code-quality-reviewer-prompt.md)" -> "Quality reviewer approves?";
  "Quality reviewer approves?" -> "Fix quality issues via SendMessage(to: agentId)" [label="no"];
  "Fix quality issues via SendMessage(to: agentId)" -> "Dispatch Codex code quality reviewer (/codex:rescue --fresh --wait, ./code-quality-reviewer-prompt.md)";
  "Quality reviewer approves?" -> "Dispatch Codex code style reviewer (/codex:rescue --fresh --wait, ./code-style-reviewer-prompt.md)" [label="yes"];

  "Dispatch Codex code style reviewer (/codex:rescue --fresh --wait, ./code-style-reviewer-prompt.md)" -> "Style reviewer approves?";
  "Style reviewer approves?" -> "Fix style issues via SendMessage(to: agentId)" [label="no"];
  "Fix style issues via SendMessage(to: agentId)" -> "Dispatch Codex code style reviewer (/codex:rescue --fresh --wait, ./code-style-reviewer-prompt.md)";
  "Style reviewer approves?" -> "Mark task complete in TodoWrite" [label="yes"];

  "Mark task complete in TodoWrite" -> "More tasks remain?";
  "More tasks remain?" -> "Dispatch Claude subagent implementer (Agent tool, ./claude-implementer-prompt.md), record agentId" [label="yes (fresh subagent)"];
  "More tasks remain?" -> "Dispatch Codex final whole-implementation reviewer (/codex:rescue --fresh --wait)" [label="no"];
  "Dispatch Codex final whole-implementation reviewer (/codex:rescue --fresh --wait)" -> "Regenerate knowledge graph\n(/graphify . --update)";
  "Regenerate knowledge graph\n(/graphify . --update)" -> "Use finishing-a-development-branch";
}
```

### 1. Read the plan once

Read the plan file once. Extract every task's full text and its surrounding context. Put all tasks into `TodoWrite`. After this, the plan file is not read again — the controller passes full task text into each implementer subagent dispatch (the subagent must not be sent a file reference to chase).

### 1.5 Build/update knowledge graph

Before spawning the first implementer subagent, ensure the knowledge graph is current so the implementer can consult it for structural context.

**Prerequisite:** Graphify 已装进 `Video-Tree-TRM` 环境、且 `/graphify` skill 已项目局部安装（`.claude/skills/graphify/`）。首次知识图谱须由人类手动跑 `/graphify .`（全量混合：代码 tree-sitter + 文档 LLM 语义）。若 `graphify-out/graph.json` 不存在，则一次性提示人类先手动 `/graphify .`，本步降级为常规文件读取、不阻断流程。

**Run（控制器执行，增量合并刷新）:**

```text
/graphify . --update
```

`--update` 走 `detect_incremental` 增量：仅代码变更不调 LLM、文档变更才抽语义，**合并保留两层**（代码 + 文档语义），只换变更文件、剪除删除文件。输出在项目根的 `graphify-out/`。

**What it gives the implementer:** 控制器可把图谱上下文带给 implementer 子代理；子代理用 **CLI** 做结构化导航而非盲读文件（0.8.35 CLI 原生支持）：
`conda run -n Video-Tree-TRM graphify query "<question>"` / `graphify path "<A>" "<B>"` / `graphify explain "<NodeName>"` / `graphify affected "<NodeName>"`（反向影响面）。

**When to skip:** 项目尚无代码（greenfield 首个任务）则跳过 —— 无可图。

### 2. Dispatch the Claude subagent implementer

For each new task, spawn a fresh Claude Code subagent with the `Agent` tool:

- `subagent_type`: `general-purpose`.
- prompt: the body from `./claude-implementer-prompt.md`, with the bracketed sections filled in (full task text, scene-setting context, absolute working directory).
- **Record the returned `agentId`** — you need it to send fix instructions back to the same subagent (§3).

A fresh subagent per task is the "fresh subagent per task" principle: each task gets a clean, isolated context window. If the task runs a slow test suite, the subagent should run it inside tmux (see tmux policy) so the human can attach.

The prompt template (`./claude-implementer-prompt.md`) embeds the full task text, scene-setting context, the self-review checklist, escalation guidance, and the required structured-output footer that produces the STATUS signal described in §4.

### 3. Iterate on the same task with `SendMessage`

When the spec, quality, style, or gate review finds something to fix, send the fix back to **the same implementer subagent**:

```
SendMessage(to: <agentId>, <fix instructions + reviewer feedback>)
```

`SendMessage` continues the subagent that did the original implementation, so it still has all the context about what it built and why. Spawning a fresh subagent mid-task wastes context and invites regressions.

If that subagent has already exited or lost its context, spawn a fresh subagent with the `Agent` tool and re-feed the full reviewer feedback in its prompt. Only spawn a brand-new subagent for the **next** task in the plan.

### 4. Handle implementer status signals

The implementer subagent is instructed (by `./claude-implementer-prompt.md`) to terminate its output with a structured `STATUS` block. The four statuses, and how to handle each:

- **DONE** — Proceed to the automated quality gate.
- **DONE_WITH_CONCERNS** — The subagent completed the work but flagged doubts. Read the concerns before proceeding.
  - If the concerns are about correctness or scope, address them (via `SendMessage`) before review.
  - If they're observations (e.g., "this file is getting large"), note them and proceed.
- **NEEDS_CONTEXT** — The subagent needs information that wasn't provided. Supply the missing context and continue via `SendMessage`.
- **BLOCKED** — The subagent cannot complete the task. Assess the blocker:
  - Context problem → provide more context, continue via `SendMessage`.
  - Insufficient reasoning → continue via `SendMessage` with more explicit guidance and worked-out direction, or spawn a fresh subagent with a sharper prompt.
  - Task too large → break it into smaller pieces, spawn a fresh subagent for each.
  - Plan is wrong → escalate to the human.

If the implementer's output is missing the structured `STATUS` block (e.g., it errored out or just forgot), treat the missing status as `BLOCKED` and inspect the partial output.

### 4.5 Automated Quality Gate

After the implementer subagent reports `DONE` or `DONE_WITH_CONCERNS`, run automated tools on the changed files **before** dispatching any Codex reviewer. This catches objective violations cheaply (seconds, no review tokens) so reviewers can focus on judgment calls.

**Gate checklist (Controller runs these):**

```bash
# 1. Format check
conda run -n Video-Tree-TRM ruff format --check <changed_files>

# 2. Lint check
conda run -n Video-Tree-TRM ruff check <changed_files>

# 3. Cyclomatic complexity (block on grade C or worse)
conda run -n Video-Tree-TRM radon cc <changed_files> -n C -s

# 4. Tests pass
conda run -n Video-Tree-TRM pytest tests/ -x -q

# 5. Structural checks (grep-based)
# - No bare except: grep -rn 'except\s*:' or 'except Exception.*pass'
# - No files > 200 lines in core changes

# 6. Metrics regression check
# - Read Wiki schemas/ to find tables affected by changed files
# - If relevant tables exist in results/harness.db:
#   Query current metrics vs baseline from Wiki metrics/
#   Any regression = gate failure

# 7. 核心算法保真检查（仅当任务涉及核心算法迁移时）
# - 读取 research-wiki/ARCHITECTURE.md §6 核心算法清单
# - 对每个被修改的核心算法文件，diff 与参考代码
# - 确认核心逻辑（条件分支、数学公式、状态机转换）未被简化
# - 若有差异，生成差异报告要求 implementer 解释
```

**If any check fails:**
1. Collect all tool outputs into a single fix instruction.
2. Send it back to the implementer subagent via `SendMessage(to: agentId, <fix instruction with tool outputs>)`.
3. Re-run the gate on the result.
4. Maximum 2 retries. If still failing after 2 retries, escalate to user.

**If all checks pass:** Proceed to spec compliance review.

**Note:** The format check (`ruff format --check`) can often be auto-fixed. If only formatting fails, the controller MAY run `conda run -n Video-Tree-TRM ruff format <files>` directly and commit, skipping the round-trip to the implementer.

### 5. Spec compliance review

After the quality gate passes, run a read-only Codex review with `/codex:rescue --fresh --wait`, passing the prompt template at `./spec-reviewer-prompt.md`. This Codex reviewer:

- Reads the actual code the implementer wrote (via `git diff` and direct file reads) — **does not trust** the implementer's self-report.
- Verifies the implementation matches the spec exactly: nothing missing, nothing extra, no misunderstandings.

If the reviewer flags issues, send them back to the implementer subagent via `SendMessage` and re-run spec review (a fresh `/codex:rescue --fresh --wait`) on the result. Loop until approved. Do not accept "close enough."

### 5.5 核心算法保真审查

仅当当前任务涉及核心算法迁移（参照 `research-wiki/ARCHITECTURE.md §6`）时执行此步骤。

将以下内容交给 Codex 审查（`/codex:rescue --fresh --wait`）：

1. 当前任务修改的文件（`git diff`）
2. 对应的参考代码文件（从参考路径读取）
3. 审查指令："逐一比对以下核心逻辑，确认新实现未简化、省略或改变算法行为：[列出具体算法要点]"

**通过标准**：Codex 确认核心逻辑一致，或差异有合理的架构理由（如 Protocol 接口化）。
**未通过**：发回 implementer 修正，循环直到通过。

不涉及核心算法的任务跳过此步骤。

### 6. Functional quality review

Only after spec compliance passes, run a second read-only Codex review (`/codex:rescue --fresh --wait`) with `./code-quality-reviewer-prompt.md`. This reviewer:

- Examines architecture, decomposition, plan conformance, file growth, naming, error handling, test quality, and obvious smells.
- Returns Strengths and Issues categorized as Critical / Important / Minor.

If issues are raised, send them back to the implementer subagent via `SendMessage` and re-run quality review (a fresh Codex pass). Loop until approved.

### 7. Code style review

Only after functional quality review passes, run a third read-only Codex review (`/codex:rescue --fresh --wait`) with `./code-style-reviewer-prompt.md`. This reviewer:

- Evaluates code form and style: over-engineering, YAGNI violations, naming clarity, comment quality, unnecessary abstraction.
- Does NOT re-check architecture or functional correctness (already verified).
- Returns Important and Minor issues only (no Critical category — that's for the functional reviewer).

If issues are raised, send them back to the implementer subagent via `SendMessage` and re-run style review. Loop until approved.

**When to skip:** If the task is purely mechanical (rename, config change, one-line fix), the controller MAY skip this review at its discretion. Flag the skip in the task completion note.

### 8. Mark the task complete and continue

Once all required reviewers approve, mark the task complete in `TodoWrite` and move to the next task — back to step 2 with a fresh implementer subagent.

### 9. Final whole-implementation review

After **all** tasks pass, run one more read-only Codex review (`/codex:rescue --fresh --wait`): a whole-implementation reviewer. Give it the full set of git SHAs from this branch plus the original plan, and have it look across task boundaries for:

- Integration mistakes that no per-task review could catch (interfaces that drift between tasks, duplicated logic across files, dead code from earlier tasks).
- Plan coverage as a whole: are there any spec requirements that landed in no task?
- Cross-cutting concerns (logging, config, error paths, test layout) consistency.

You can reuse `./code-quality-reviewer-prompt.md` for this pass, but expand the scope from "this task's commits" to "the entire branch since plan execution started."

Then proceed to Step 10.

### 10. Harness evaluation

After the final whole-implementation review passes, invoke the `harness-eval` skill:

```
/harness-eval
```

- **Passes** → Proceed to Step 11.
- **Fails** → Read the diagnosis from the harness-eval output. Identify which task(s) need iteration. Return to Step 2 (spawn a fresh implementer subagent) for the relevant task, incorporating the diagnosis into the subagent's prompt.

### 11. Regenerate knowledge graph

After harness evaluation passes, regenerate the knowledge graph so it reflects all code changes from the entire plan execution（控制器执行）:

```text
/graphify . --update
```

This keeps `graphify-out/` in sync with the final codebase state. Future skill invocations (on subsequent plans or branches) will start from an accurate graph.

Then proceed to `finishing-a-development-branch`.

**When to skip:** If Step 1.5 was skipped (图谱未建 / 项目尚无代码), skip this too.

## Model selection

**Implementer (Claude Code subagent side)** — runs on Claude Code's default model. Give it strong context and a precise task; for architecturally tricky tasks, expand the context and direction you hand the subagent rather than trying to swap models.

**Reviewer (Codex side) — default to gpt-5.4 at high effort.** This is configured in `.codex/config.toml`. For the final whole-implementation review, keep gpt-5.4 and consider bumping to `--effort xhigh` for the widest cross-task scope.

Principle: review quality compounds across the loop. Three independent Codex passes are the structural guarantee that the implementer's blind spots get caught. Do not weaken them to save tokens — a weak review lets defects through and costs more in remediation later.

## Worked example

```
You: I'm using Subagent-Driven Development to execute this plan.

[Read plan file once: research-wiki/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

[Build/update knowledge graph]
  /graphify . --update
  → graphify-out/GRAPH_REPORT.md updated (3 communities, 12 god nodes)

--- Task 1: Hook installation script ---
[Get Task 1 text and context (already extracted)]
[Spawn Claude subagent implementer via Agent tool with ./claude-implementer-prompt.md]
  → agentId = impl-task1
[Implementer subagent returns:]

Implementer subagent:
  - Implemented install-hook command
  - Added tests, 5/5 passing (conda run -n Video-Tree-TRM pytest)
  - Self-review: realized I missed the --force flag, added it
  - Committed (SHA abc123)
  ---
  STATUS: DONE
  COMMIT_SHAS: abc123
  NOTES: none
  ---

[Automated quality gate: conda run -n Video-Tree-TRM ruff/radon/pytest — all pass]

[Dispatch Codex spec reviewer: /codex:rescue --fresh --wait with ./spec-reviewer-prompt.md]
Codex spec reviewer: ✅ Spec compliant — all requirements met, nothing extra

[Dispatch Codex code quality reviewer: /codex:rescue --fresh --wait with ./code-quality-reviewer-prompt.md]
Codex quality reviewer: Strengths — good test coverage, clean error handling. Issues — none. ✅ Approved.

[Dispatch Codex code style reviewer: /codex:rescue --fresh --wait with ./code-style-reviewer-prompt.md]
Codex style reviewer: Issues — none. ✅ Approved.

[Mark Task 1 complete]

--- Task 2: Recovery modes ---
[Spawn fresh Claude subagent implementer → agentId = impl-task2]

Implementer subagent:
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed (SHA def456)
  ---
  STATUS: DONE
  COMMIT_SHAS: def456
  ---

[Automated quality gate: pass]
[Codex spec reviewer]
Codex spec reviewer: ❌ Issues:
  - Missing: progress reporting (spec says "report every 100 items")
  - Extra:   added --json flag (not requested)

[Fix via SendMessage(to: impl-task2, "Remove the --json flag; add progress reporting every 100 items as the spec requires.")]

Implementer subagent:
  - Removed --json flag
  - Added progress reporting at 100-item intervals
  - Committed (SHA def789)
  ---
  STATUS: DONE
  COMMIT_SHAS: def789
  ---

[Codex spec reviewer re-runs (fresh)] ✅ Spec compliant now
[Codex quality reviewer] Issues (Important): magic number 100
[Fix via SendMessage(to: impl-task2, "Extract 100 into PROGRESS_INTERVAL constant.")]
Implementer subagent: extracted constant, committed ghi012, STATUS: DONE
[Codex quality reviewer re-runs] ✅ Approved
[Codex style reviewer] Minor: rename PROGRESS_INTERVAL to RECOVERY_PROGRESS_INTERVAL for clarity
[Fix via SendMessage(to: impl-task2, "Rename PROGRESS_INTERVAL to RECOVERY_PROGRESS_INTERVAL for clarity.")]
Implementer subagent: renamed constant, committed jkl345, STATUS: DONE
[Codex style reviewer re-runs] ✅ Approved

[Mark Task 2 complete]

... (Tasks 3–5 similarly) ...

[All tasks complete]
[Dispatch Codex final whole-implementation reviewer (/codex:rescue --fresh --wait) across all SHAs]
Codex final reviewer: ✅ No cross-task issues found.

[Regenerate knowledge graph]
  /graphify . --update
  → graphify-out/ updated with all new code from this plan

[Hand off to finishing-a-development-branch]
```

## Companion files

- `./claude-implementer-prompt.md` — Prompt body for the Claude subagent implementer (spawned with the `Agent` tool, `subagent_type=general-purpose`).
- `./spec-reviewer-prompt.md` — Prompt body for the spec compliance review, run as a read-only Codex session (`/codex:rescue --fresh --wait`).
- `./code-quality-reviewer-prompt.md` — Prompt body for the functional quality review, run as a read-only Codex session. Also reused for the final whole-implementation review.
- `./code-style-reviewer-prompt.md` — Prompt body for the code style review, run as a read-only Codex session. Focuses on form/style rather than functional quality.

## Common mistakes

- **Reusing a previous task's subagent for a new task.** Spawn a fresh `Agent` subagent per task — otherwise the new task inherits context-polluted state and produces confused output.
- **Spawning a fresh subagent for a fix instead of `SendMessage`.** The implementer then restarts cold and may undo or duplicate work it already did. Use `SendMessage(to: agentId)` for fixes; only spawn fresh when the subagent has truly died.
- **Trusting the implementer subagent's self-report.** Every Codex reviewer must read real code and diffs. The reviewer prompts are explicit about this; respect it.
- **Stopping after each task to check in.** Don't. Execute continuously. Only stop for BLOCKED you can't resolve.
- **Reading the plan file from inside the implementer subagent.** Don't. Paste the task text directly into the subagent's prompt — the subagent should not be navigating filesystems looking for the plan.
- **Letting reviewers approve "close enough."** Iterate the loop. The whole point of the cross-provider split is that the Codex reviewer has no incentive to be charitable toward the Claude implementer.

## Wiki Integration

**Precondition**: `research-wiki/` directory exists (skip this section entirely if it does not).

**Trigger**: When executing a plan and the task produces knowledge worth preserving; skip mechanical changes such as pure renames.

**Output path**: Plan and review records are saved to `research-wiki/plans/` and `research-wiki/reviews/` instead of `docs/superpowers/plans/`.

**Steps**:
1. If the task produces reusable implementation knowledge, run `.claude/tools/research_wiki.py add_entity research-wiki/ --type plan --id <slug> --title "<task plan title>"` to create the plan entity
2. If the task includes useful review feedback, run `.claude/tools/research_wiki.py add_entity research-wiki/ --type review --id <slug> --title "<task review title>"` to create the review entity
3. Append the key decisions, reusable implementation notes, and accepted or rejected review items with reasons to the generated page
4. If the plan is related to a design, run `.claude/tools/research_wiki.py add_edge research-wiki/ --from "plan:<id>" --to "design:<id>" --type implements --evidence "..."`
5. If the review feedback changes a design or plan, run `.claude/tools/research_wiki.py add_edge research-wiki/ --from "review:<id>" --to "<target-type>:<id>" --type informs --evidence "..."`
6. Run `.claude/tools/research_wiki.py rebuild_index research-wiki/`