From b2914b3828c656df450e5bdc31cdf31a800110f3 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Mon, 6 Jul 2026 11:40:08 -0400 Subject: [PATCH] skill: add algorithm fidelity review to subagent-driven-development Co-Authored-By: Claude Opus 4.6 (1M context) --- .../subagent-driven-development/SKILL.md | 487 ++++++++++++++++++ 1 file changed, 487 insertions(+) create mode 100644 .claude/skills/subagent-driven-development/SKILL.md diff --git a/.claude/skills/subagent-driven-development/SKILL.md b/.claude/skills/subagent-driven-development/SKILL.md new file mode 100644 index 0000000..f10f7e4 --- /dev/null +++ b/.claude/skills/subagent-driven-development/SKILL.md @@ -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-` (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- "; echo '=== DONE ==='; sleep 86400" + +# Poll for status +tmux capture-pane -t sdd-task- -p | tail -20 + +# Human attaches to inspect +tmux attach -t sdd-task- +``` + +**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 ""` / `graphify path "" ""` / `graphify explain ""` / `graphify affected ""`（反向影响面）。 + +**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: , ) +``` + +`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 + +# 2. Lint check +conda run -n Video-Tree-TRM ruff check + +# 3. Cyclomatic complexity (block on grade C or worse) +conda run -n Video-Tree-TRM radon cc -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, )`. +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 ` 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 --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 --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:" --to "design:" --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:" --to ":" --type informs --evidence "..."` +6. Run `.claude/tools/research_wiki.py rebuild_index research-wiki/`