skill: add algorithm fidelity review to subagent-driven-development
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,487 @@
|
||||
---
|
||||
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 已装进 `chs` 环境、且 `/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/`
|
||||
Reference in New Issue
Block a user