diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 6c0b8349..81984994 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -413,6 +413,15 @@ rulings, or stop on load-bearing ones. There is no second fix wave — residual load-bearing findings surface to your human partner when finishing-a-development-branch presents the options. +The wave closing is policy, not a verdict. A sufficiently strong reviewer +finds real defects indefinitely, so "review until one comes back clean" +never terminates — the completed wave is the exit, not a clean report. +New Critical/Important breakage in the final fix diff joins the residuals +for adjudication; it does not start a second wave. And review procedures +your human partner sets up for one review — competing reviewers, scoring, +extra seats — apply to that review only. Never adopt them as standing +procedure for reviews they didn't ask about. + ## Finish When the final whole-branch review is clean and its fixes are merged, @@ -434,6 +443,8 @@ Use superpowers:finishing-a-development-branch. | "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. | | "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. | | "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. | +| "This new finding is real — one more wave" | Real findings are infinite under a strong reviewer. The completed wave is the exit; adjudicate and route. | +| "They liked competing reviewers earlier, I'll run them again" | One-off review procedures apply to the review they were given for. Re-adopting them unasked is scope creep in review clothing. | ## Example Workflow diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index b14b5858..5aa3f5f0 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/skills/using-superpowers/references/codex-tools.md @@ -9,6 +9,47 @@ multi_agent = true This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings. +## SDD dispatch: pin fork_turns and the model on every spawn + +Every `spawn_agent` call in subagent-driven-development sets +`fork_turns: "none"`. The parameter defaults to `"all"`, which forks your +entire session transcript into the child — the opposite of the fresh, +constructed context SDD requires — and a full-history fork also refuses +model and effort overrides. Never omit the parameter, and never pass +`"all"` or a turn count for an SDD dispatch. + +Before Task 1, check your `spawn_agent` tool schema for `model` and +`reasoning_effort` parameters (present on Codex 0.145+). + +**If the parameters exist**, set both explicitly on every dispatch: + +| Role | model | reasoning_effort | +|------|-------|------------------| +| Implementer (all rounds) | `gpt-5.6-terra` | `high` | +| Task reviewer | `gpt-5.6-terra` | `high` | +| Scoped re-review | `gpt-5.6-terra` | `medium` | +| Final whole-branch review | `gpt-5.6-terra` | `high` | + +On Codex this table IS the Model Selection mapping — including the final +review, which stays on terra/high rather than "most capable available." +Never give a subagent your session's model when you run a frontier config +(sol at xhigh or max): reviewer tier never exceeds implementer tier, and +a fix round never gets an effort bump. Rounds 4-5's "more capable model" +means a fresh implementer at the same tier; a task that genuinely needs +more than terra/high is a BLOCKED escalation to your human partner, not +a quiet tier climb. Frontier-tier subagents at inherited effort are the +measured top driver of Codex SDD runs spinning out to 8+ hours +(PRI-2672): review seats that inherited sol found real-but-endless +defects every round, and fix diffs ballooned instead of converging. + +**If the parameters do not exist** (Codex 0.144 and earlier), every child +inherits your session's model and effort and no override is possible — +role files in `~/.codex/agents/` do not attach to spawns either. Say so +to your human partner before starting a plan of more than a few tasks, +and offer the choice: proceed with inheritance, or restart the session +at a lower effort so the whole run — controller and children — pays the +lower rate. + ## Environment Detection Skills that create worktrees or finish branches should detect their