From 705e254099065842ab3d4615c0fedffb352eeca6 Mon Sep 17 00:00:00 2001 From: Gabriel Borges Date: Mon, 6 Jul 2026 20:43:12 -0400 Subject: [PATCH 1/5] docs(sdd): add effort dimension design spec --- .../2026-07-06-sdd-effort-dimension-design.md | 250 ++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-06-sdd-effort-dimension-design.md diff --git a/docs/superpowers/specs/2026-07-06-sdd-effort-dimension-design.md b/docs/superpowers/specs/2026-07-06-sdd-effort-dimension-design.md new file mode 100644 index 0000000000..059ea4059b --- /dev/null +++ b/docs/superpowers/specs/2026-07-06-sdd-effort-dimension-design.md @@ -0,0 +1,250 @@ +# SDD Effort Dimension Design + +**Status:** Proposed. Ships the effort-control mechanism and dispatch +guidance. Makes no measured cost claim (see Validation). +**Issue:** obra/superpowers#1747. +**Objective:** give SDD a per-role reasoning-effort dial, so a subagent's +effort matches its task instead of inheriting the session's. + +## Overview + +SDD dispatches every subagent (implementer, task reviewer, fix, final +reviewer) at the session's reasoning effort, because effort cannot be set at +dispatch. A high-effort session spends high-effort reasoning transcribing a +plan that already contains the code. A default-effort session runs the final +whole-branch review, which SDD pins to the most capable model, at default +effort. SDD already matches the *model* to the task (the Model Selection +section, from the #1744 cost-tiering work). Effort is the same dial's second +axis, fixed at the session level today. + +This design adds effort as an explicit SDD dispatch dimension. On Claude Code +it ships a small roster of effort-pinned worker agents (the only mechanism +that sets per-role effort there). On Codex it documents the native +`model_reasoning_effort` key. On other harnesses it documents the +session-level limitation. The role prompts, the dispatch flow, and the model +choice are all unchanged. + +## Relationship to existing work + +This sits directly beside the Model Selection section produced by the +strict-cost SDD work (`2026-06-10-strict-cost-sdd-design.md`, PR #1744) and +reuses its structure and its guardrails: + +- **Effort is the second axis of the model dial.** The task-type boundaries + are the same ones Model Selection already validated (transcription vs + standard vs judgment). This design does not introduce new task + categories; it maps the existing ones to an effort level. +- **The judgment guardrail applies unchanged: cheapen mechanics, never + judgment.** Low effort is used only where the work is mechanical + (deterministic, cheaply verifiable, gated by the task review). High + effort stays on every judgment point: the final whole-branch review, + subtle reviews, BLOCKED diagnosis, and adjudication. Matching effort to + task type this way does not trade quality for cost, which is what lets + the guidance ship ahead of the full eval campaign (see Validation). + +The strict-cost L1 ladder proposed a per-task complexity tag from the +planner (`mechanical / standard / judgment`). If that ships, the same tag +can drive both the model tier and the effort level. This design does not +depend on it and does not implement it. + +## Mechanism, per harness + +The harnesses expose reasoning depth at different points, which is why the +mechanism is harness-conditional while the guidance is harness-general. + +- **Claude Code.** The Task tool overrides `model` per dispatch but not + `effort`. The only per-subagent effort control is agent-definition + frontmatter. Subagent calls carry the agent's frontmatter effort on the + wire and are sent with thinking disabled, so prompt-level thinking cues + are inert for subagents. Therefore effort control requires named agent + files. A dispatch-time `model` override takes precedence over an agent's + frontmatter model, so an agent file can pin *only* effort and leave the + model to the dispatch. The two axes stay independent. +- **Codex.** `model_reasoning_effort` is a first-class per-custom-agent key + that inherits from the session when unset. The knob exists natively; the + guidance simply tells SDD to set it. +- **Other harnesses (Gemini CLI and similar).** Reasoning depth is exposed + at session or model-selection level, with no per-role mechanism. No + change beyond documenting the session-effort tax. + +## Component 1: effort-pinned worker roster + +New directory `agents/` at the plugin root (Claude Code auto-discovers it). +Three files, each a general-purpose worker distinguished only by its effort +frontmatter: + +``` +agents/worker-low-effort.md effort: low +agents/worker-medium-effort.md effort: medium +agents/worker-high-effort.md effort: high +``` + +**Frontmatter.** `name`, `description`, `effort`. No `model` key, so the +dispatch-time model override supplies the model (and the agent falls back to +the session model if a dispatch ever omits it). No `tools` key, so the agent +inherits the full toolset, which implementers need for edits and reviewers +use read-only by their prompt. The `description` states that the agent is an +explicit dispatch target for superpowers dispatch skills and not for +automatic delegation, so Claude does not auto-select it for unrelated tasks. + +**Body.** A short, role-neutral system prompt that fixes only the effort +posture and defers everything else to the dispatch prompt. It must not +impose a role, since the same worker serves implementers and reviewers. +Example for `worker-low-effort.md`: + +```markdown +--- +name: worker-low-effort +description: Effort-pinned general-purpose worker running at low reasoning + effort. Explicit dispatch target for superpowers dispatch skills + (subagent-driven-development, dispatching-parallel-agents) when the caller + has judged the task transcription-grade or mechanical. The caller supplies + the role, task, and model at dispatch; this agent only fixes the reasoning + effort the Task tool cannot set per invocation. Not for automatic delegation. +effort: low +--- + +You are a general-purpose worker running at low reasoning effort. Your role, +task, and instructions come entirely from the dispatch prompt you were given. +Follow it exactly and do not expand scope. If the task turns out to need more +reasoning than low effort supports, say so plainly and stop, so the caller can +re-dispatch you at a higher tier. +``` + +`worker-medium-effort.md` and `worker-high-effort.md` are identical except +for the effort level and a body tuned to it (medium: "take the reasoning the +task needs without over-investing"; high: "take the time the task needs, +state your reasoning, and flag uncertainty rather than smoothing it over"). + +**Naming.** `worker--effort`, referenceable bare or as +`superpowers:worker--effort`. The plugin namespace disambiguates from +any other effort agents a user has installed. The names are role-agnostic on +purpose, so `dispatching-parallel-agents` can use them too. + +**Effort levels.** Low, medium, high cover the three task-type tiers and are +supported across the models SDD uses. xhigh and max are deliberately omitted +from the first roster (YAGNI); adding a file later is trivial if a role +needs one. + +**Haiku caveat.** Haiku has no effort parameter, so `worker-low-effort` +dispatched on Haiku runs Haiku with no effort change. That is acceptable for +the cheapest tier, since Haiku is already the reasoning floor. When low +effort is wanted on a non-floor model, pair `worker-low-effort` with a model +that honors effort (for example Sonnet). The guidance states this. + +## Component 2: Effort Selection section in the SDD skill + +A new `## Effort Selection` subsection in +`skills/subagent-driven-development/SKILL.md`, placed immediately after +`## Model Selection` and mirroring its shape. Content: + +- Effort is the second axis of the same capability match; set it to the + least effort the role needs, for the same cost reason model is set. +- The judgment guardrail, restated: cheapen mechanics, never judgment. +- Role-to-effort map: + - Transcription-grade implementation (the plan carries the complete code) + and single-file mechanical fixes: low. + - Standard implementation from a prose spec, and integration work: medium. + - Design or architecture implementation: high. + - The final whole-branch review: high, on the most capable model. It is a + judgment task, so do not lower its effort. + - Task reviewer: scale effort to the diff exactly as the model is scaled. + A small mechanical diff does not need high effort. A subtle change + (concurrency, a contract change, shared state) does. Reviewing is + judgment, so do not default reviewer effort to the floor. + - Fix subagents: match the task's tier, one step up if the fix itself + needs judgment the original task did not. +- The dispatch rule, the analog of "always specify the model explicitly": + on Claude Code, always dispatch through the effort-matched worker agent. + An omitted effort inherits the session's and defeats this section. +- The per-harness mechanism note (Claude Code worker agents, Codex + `model_reasoning_effort`, other harnesses session-level with the effort + tax), and the Haiku caveat. + +## Component 3: dispatch template edits + +`skills/subagent-driven-development/implementer-prompt.md` and +`task-reviewer-prompt.md` each change their dispatch header. Today it reads +`Subagent (general-purpose):` with a required `model:` placeholder. It +becomes a dispatch target that names the effort-matched worker on Claude +Code, keeps `general-purpose` as the fallback when the roster is absent or on +non-Claude-Code harnesses, keeps the `model:` placeholder unchanged, and +adds an `effort:` note that points at the new Effort Selection section (and, +for Codex, at `model_reasoning_effort`). The templates stay harness-general. + +## Component 4: final review and standalone code review + +SDD's final whole-branch review dispatches via `worker-high-effort` on the +most capable model. This is stated in the Effort Selection section (Component +2), since SDD's final review reuses the `requesting-code-review` template +rather than owning one. One line is added to +`skills/requesting-code-review/code-reviewer.md` noting effort selection, so +the standalone use of that skill is not left without the dimension. The +substantive guidance stays in SDD. + +## Component 5: tests + +A shell test under `tests/claude-code/`, following the existing convention +(bash, sourced `test-helpers.sh`), doing static validation with no CLI +invocation: + +- Every `agents/worker-*-effort.md` parses, has a `name`, a `description`, + and an `effort` value in the supported set (low, medium, high). +- Every worker name referenced in `SKILL.md` and the two templates has a + matching file in `agents/` (a drift guard against renaming one and not the + other). + +Static and deterministic, so it runs fast and does not depend on a live +model. + +## Validation + +The mechanism (Components 1, 3, 4, 5) and the fact that effort is a +dispatchable second axis are unconditional. They add capability and make no +cost or quality claim. + +The role-to-effort defaults (Component 2) make no *measured* cost claim. The +repo's standard for behavior-changing cost guidance is the N=5 eval gate +campaign (`sdd-quality-reviewer-catches-planted-defect`, +`sdd-rejects-extra-features`, deliverable parity), and this design does not +run it. The defaults are safe to ship ahead of that campaign for one +specific reason: the direction respects the judgment guardrail by +construction. High effort stays on every judgment point, and low effort is +applied only to task types Model Selection already validated as mechanical, +where the task review gate catches errors. So the guidance cannot regress +quality by matching effort to task type, whatever the eventual measured +magnitude of the cost saving turns out to be. + +What remains eval-pending, and is called out as such rather than claimed: +the magnitude of the cost saving from lowering implementer effort, and +whether effort-token dynamics differ from the thinking-cap result the +strict-cost campaign measured backfiring (effort is the model's own +target-depth control, not a truncation cap, so that result should not +transfer a priori, but it is not measured here). If the maintainer wants the +defaults gated, the same harness that gated the model tiers applies +unchanged, since the task categories are identical. + +## Scope boundaries + +**Touches:** new `agents/` directory (three worker files), +`skills/subagent-driven-development/SKILL.md`, its two prompt templates, one +line in `skills/requesting-code-review/code-reviewer.md`, one new test. + +**Does not touch:** the Model Selection section's content (effort sits beside +it, does not rewrite it), the model-tiering work, other skills, or Codex and +Gemini config files. Codex is documented, not shipped, because superpowers +ships no per-role Codex custom-agent TOMLs today; when it does, the effort key +goes in alongside the model choice. + +**Non-goals:** running the eval campaign, implementing the planner complexity +tag, adding xhigh/max workers, or changing role prompts or the dispatch flow. + +## Open decisions + +- **RELEASE-NOTES entry.** Whether this PR adds a RELEASE-NOTES stanza and a + version bump, or leaves both to the maintainer at release time. Default: + leave the bump to the maintainer; add a notes stanza only if the + maintainer's PRs conventionally include one. +- **Worker naming.** `worker--effort` versus a more explicit prefix + (`sp-worker-...`). Default: `worker--effort`, relying on the + `superpowers:` plugin namespace to disambiguate. From 64117dae6ef74fe7396a2ceded06c4f25b7475e8 Mon Sep 17 00:00:00 2001 From: Gabriel Borges Date: Mon, 6 Jul 2026 20:43:12 -0400 Subject: [PATCH 2/5] feat(sdd): add effort-pinned worker agent roster and validation test --- agents/worker-high-effort.md | 7 ++ agents/worker-low-effort.md | 7 ++ agents/worker-medium-effort.md | 7 ++ tests/claude-code/run-skill-tests.sh | 1 + .../claude-code/test-effort-worker-roster.sh | 82 +++++++++++++++++++ 5 files changed, 104 insertions(+) create mode 100644 agents/worker-high-effort.md create mode 100644 agents/worker-low-effort.md create mode 100644 agents/worker-medium-effort.md create mode 100755 tests/claude-code/test-effort-worker-roster.sh diff --git a/agents/worker-high-effort.md b/agents/worker-high-effort.md new file mode 100644 index 0000000000..8b1ca73c87 --- /dev/null +++ b/agents/worker-high-effort.md @@ -0,0 +1,7 @@ +--- +name: worker-high-effort +description: Effort-pinned general-purpose worker running at high reasoning effort. Explicit dispatch target for superpowers dispatch skills (subagent-driven-development, dispatching-parallel-agents) when the caller has judged the task to need real judgment, such as design work or the final whole-branch review. The caller supplies the role, task, and model at dispatch. This agent only fixes the reasoning effort the Task tool cannot set per invocation. Not for automatic delegation. +effort: high +--- + +You are a general-purpose worker running at high reasoning effort. Your role, task, and instructions come entirely from the dispatch prompt you were given. Take the time the task needs, state your reasoning, and flag any uncertainty explicitly rather than smoothing over a gap to produce a tidier answer. Follow the prompt exactly and do not expand scope. diff --git a/agents/worker-low-effort.md b/agents/worker-low-effort.md new file mode 100644 index 0000000000..f94ddd34ed --- /dev/null +++ b/agents/worker-low-effort.md @@ -0,0 +1,7 @@ +--- +name: worker-low-effort +description: Effort-pinned general-purpose worker running at low reasoning effort. Explicit dispatch target for superpowers dispatch skills (subagent-driven-development, dispatching-parallel-agents) when the caller has judged the task transcription-grade or mechanical. The caller supplies the role, task, and model at dispatch. This agent only fixes the reasoning effort the Task tool cannot set per invocation. Not for automatic delegation. +effort: low +--- + +You are a general-purpose worker running at low reasoning effort. Your role, task, and instructions come entirely from the dispatch prompt you were given. Follow it exactly and do not expand scope. If the task turns out to need more reasoning than low effort supports, say so plainly and stop, so the caller can re-dispatch you at a higher tier. diff --git a/agents/worker-medium-effort.md b/agents/worker-medium-effort.md new file mode 100644 index 0000000000..e42c9841dc --- /dev/null +++ b/agents/worker-medium-effort.md @@ -0,0 +1,7 @@ +--- +name: worker-medium-effort +description: Effort-pinned general-purpose worker running at medium reasoning effort. Explicit dispatch target for superpowers dispatch skills (subagent-driven-development, dispatching-parallel-agents) when the caller has judged the task standard implementation or integration work. The caller supplies the role, task, and model at dispatch. This agent only fixes the reasoning effort the Task tool cannot set per invocation. Not for automatic delegation. +effort: medium +--- + +You are a general-purpose worker running at medium reasoning effort. Your role, task, and instructions come entirely from the dispatch prompt you were given. Take the reasoning the task needs without over-investing, follow the prompt exactly, and do not expand scope. If the task turns out to need more reasoning than medium effort supports, say so plainly and stop, so the caller can re-dispatch you at a higher tier. diff --git a/tests/claude-code/run-skill-tests.sh b/tests/claude-code/run-skill-tests.sh index c94cfec9e0..832a60fb36 100755 --- a/tests/claude-code/run-skill-tests.sh +++ b/tests/claude-code/run-skill-tests.sh @@ -75,6 +75,7 @@ done tests=( "test-worktree-path-policy.sh" "test-sdd-workspace.sh" + "test-effort-worker-roster.sh" "test-subagent-driven-development.sh" ) diff --git a/tests/claude-code/test-effort-worker-roster.sh b/tests/claude-code/test-effort-worker-roster.sh new file mode 100755 index 0000000000..a6f205b7db --- /dev/null +++ b/tests/claude-code/test-effort-worker-roster.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash +# Tests for the effort-pinned worker roster: agents/worker--effort.md +# exist with valid frontmatter, and every worker name referenced in the SDD +# skill and its dispatch templates has a matching agent file (drift guard). +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +AGENTS_DIR="$REPO_ROOT/agents" +SDD_DIR="$REPO_ROOT/skills/subagent-driven-development" +CODE_REVIEWER="$REPO_ROOT/skills/requesting-code-review/code-reviewer.md" + +FAILURES=0 +pass() { echo " [PASS] $1"; } +fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); } + +# fm_value : print a single-line YAML frontmatter value +fm_value() { + awk -v key="$2" ' + /^---$/ { d++; next } + d==1 && $1==key":" { sub(/^[^:]*:[[:space:]]*/, ""); print; exit } + ' "$1" +} + +check_roster() { + echo "--- roster files exist with valid frontmatter ---" + local level file name effort + for level in low medium high; do + file="$AGENTS_DIR/worker-${level}-effort.md" + if [[ -f "$file" ]]; then + pass "exists: agents/worker-${level}-effort.md" + else + fail "missing: agents/worker-${level}-effort.md" + continue + fi + name="$(fm_value "$file" name)" + [[ "$name" == "worker-${level}-effort" ]] \ + && pass "name matches for worker-${level}-effort" \ + || fail "name mismatch for worker-${level}-effort (got '$name')" + [[ -n "$(fm_value "$file" description)" ]] \ + && pass "has description: worker-${level}-effort" \ + || fail "missing description: worker-${level}-effort" + effort="$(fm_value "$file" effort)" + [[ "$effort" == "$level" ]] \ + && pass "effort=$level for worker-${level}-effort" \ + || fail "effort mismatch for worker-${level}-effort (got '$effort')" + done +} + +check_drift_guard() { + echo "--- every referenced worker name has a file (drift guard) ---" + local refs name + refs="$(grep -rhoE 'worker-(low|medium|high)-effort' \ + "$SDD_DIR/SKILL.md" \ + "$SDD_DIR/implementer-prompt.md" \ + "$SDD_DIR/task-reviewer-prompt.md" \ + "$CODE_REVIEWER" \ + 2>/dev/null | sort -u || true)" + if [[ -z "$refs" ]]; then + pass "no worker references yet (nothing to drift)" + return + fi + while IFS= read -r name; do + [[ -n "$name" ]] || continue + [[ -f "$AGENTS_DIR/${name}.md" ]] \ + && pass "referenced $name has a file" \ + || fail "referenced $name has NO file in agents/" + done <<< "$refs" +} + +main() { + echo "=== Test: effort worker roster ===" + check_roster + check_drift_guard + if [[ "$FAILURES" -gt 0 ]]; then + echo "FAILED ($FAILURES failure(s))" + exit 1 + fi + echo "OK" +} + +main "$@" From fc5d9560c697b7f45350fa96a2c8d681d5c23a09 Mon Sep 17 00:00:00 2001 From: Gabriel Borges Date: Mon, 6 Jul 2026 20:43:12 -0400 Subject: [PATCH 3/5] docs(sdd): add Effort Selection guidance to SDD skill --- skills/subagent-driven-development/SKILL.md | 53 +++++++++++++++++++ .../claude-code/test-effort-worker-roster.sh | 18 +++++++ 2 files changed, 71 insertions(+) diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index d8ca081570..6c2597a4df 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -129,6 +129,59 @@ that implementer. Single-file mechanical fixes also take the cheapest tier. - Touches multiple files with integration concerns → standard model - Requires design judgment or broad codebase understanding → most capable model +## Effort Selection + +Reasoning effort is the second axis of the same capability match as Model +Selection. Set it to the least effort the role needs, for the same reason you +set the model: a high-effort session spends high-effort reasoning transcribing +a plan that already contains the code, and a default-effort session runs the +final review at default effort. + +The judgment guardrail from Model Selection applies unchanged: +cheapen mechanics, never judgment. Low effort goes only to mechanical work +(deterministic, cheaply verifiable, gated by the task review). High effort +stays on every judgment point. Matching effort to task type this way does not +trade quality for cost, because the task categories are the ones Model +Selection already draws. + +**Effort by role:** +- Transcription-grade implementation (the plan carries the complete code) and + single-file mechanical fixes: low. +- Standard implementation from a prose spec, and integration work: medium. +- Design or architecture implementation: high. +- The final whole-branch review: high, on the most capable model. It is a + judgment task, so do not lower its effort. +- Task reviewer: scale effort to the diff exactly as you scale the model. A + small mechanical diff does not need high effort. A subtle change + (concurrency, a contract change, shared mutable state) does. Reviewing is + judgment, so do not default reviewer effort to the floor. +- Fix subagents: match the task's tier, one step up if the fix itself needs + judgment the original task did not. + +**Always dispatch through the effort-matched agent on Claude Code.** An omitted +effort inherits the session's, which defeats this section, the same way an +omitted model does for Model Selection. + +**Per-harness mechanism.** The harnesses expose reasoning depth at different +points: +- **Claude Code:** the Task tool overrides model per dispatch but not effort. + The only per-subagent effort control is agent-definition frontmatter, so + dispatch through the effort-matched worker agent shipped in this plugin's + `agents/` directory: `worker-low-effort`, `worker-medium-effort`, + `worker-high-effort`. A dispatch-time model override still takes precedence + over the agent's frontmatter, so pick the model per Model Selection and the + effort by the worker name. The two axes stay independent. +- **Codex:** set `model_reasoning_effort` in the role's custom-agent config + alongside its model. Unset keys inherit from the session. +- **Other harnesses:** effort is session-level only. A session pinned high + pays an effort tax on every micro-task, with no per-role control until the + harness adds one. + +Haiku has no effort parameter, so `worker-low-effort` dispatched on Haiku runs +Haiku with no effort change. That is fine for the cheapest tier, since Haiku is +already the reasoning floor. When you want low effort on a non-floor model, +pair `worker-low-effort` with a model that honors effort (for example Sonnet). + ## Handling Implementer Status Implementer subagents report one of four statuses. Handle each appropriately: diff --git a/tests/claude-code/test-effort-worker-roster.sh b/tests/claude-code/test-effort-worker-roster.sh index a6f205b7db..c31dccfdad 100755 --- a/tests/claude-code/test-effort-worker-roster.sh +++ b/tests/claude-code/test-effort-worker-roster.sh @@ -68,10 +68,28 @@ check_drift_guard() { done <<< "$refs" } +check_effort_section() { + echo "--- SDD SKILL.md has Effort Selection section referencing the roster ---" + local skill="$SDD_DIR/SKILL.md" + grep -q '^## Effort Selection' "$skill" \ + && pass "SKILL.md has '## Effort Selection'" \ + || fail "SKILL.md missing '## Effort Selection'" + grep -q 'cheapen mechanics, never judgment' "$skill" \ + && pass "Effort Selection keeps the judgment guardrail" \ + || fail "Effort Selection missing the judgment guardrail phrase" + local level + for level in low medium high; do + grep -q "worker-${level}-effort" "$skill" \ + && pass "Effort Selection references worker-${level}-effort" \ + || fail "Effort Selection missing worker-${level}-effort" + done +} + main() { echo "=== Test: effort worker roster ===" check_roster check_drift_guard + check_effort_section if [[ "$FAILURES" -gt 0 ]]; then echo "FAILED ($FAILURES failure(s))" exit 1 From 447fbcd7156609402d29341ede03600e15b582a6 Mon Sep 17 00:00:00 2001 From: Gabriel Borges Date: Mon, 6 Jul 2026 20:43:12 -0400 Subject: [PATCH 4/5] docs(sdd): wire effort dimension into dispatch templates --- .../requesting-code-review/code-reviewer.md | 4 ++++ .../implementer-prompt.md | 8 +++++++- .../task-reviewer-prompt.md | 12 ++++++++++- .../claude-code/test-effort-worker-roster.sh | 20 +++++++++++++++++++ 4 files changed, 42 insertions(+), 2 deletions(-) diff --git a/skills/requesting-code-review/code-reviewer.md b/skills/requesting-code-review/code-reviewer.md index db84ae2a0f..f81fac8f76 100644 --- a/skills/requesting-code-review/code-reviewer.md +++ b/skills/requesting-code-review/code-reviewer.md @@ -2,6 +2,10 @@ Use this template when dispatching a code reviewer subagent. +On Claude Code, dispatch through the effort-matched worker agent, scaled to the +review's difficulty (see subagent-driven-development's Effort Selection). On +Codex, set model_reasoning_effort. + **Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. ``` diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index 218fcfeb57..16b856e19c 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/skills/subagent-driven-development/implementer-prompt.md @@ -3,10 +3,16 @@ Use this template when dispatching an implementer subagent. ``` -Subagent (general-purpose): +Subagent (Claude Code: the effort-matched worker per SKILL.md Effort +Selection, one of worker-low-effort, worker-medium-effort, or +worker-high-effort. Other harnesses, or if the roster is absent: +general-purpose): description: "Implement Task N: [task name]" model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted model silently inherits the session's most expensive one] + effort: [Claude Code carries effort via the worker agent above. Codex: set + model_reasoning_effort per SKILL.md Effort Selection. Other + harnesses run at session effort.] prompt: | You are implementing Task N: [task name] diff --git a/skills/subagent-driven-development/task-reviewer-prompt.md b/skills/subagent-driven-development/task-reviewer-prompt.md index 588a40227a..91787f5e03 100644 --- a/skills/subagent-driven-development/task-reviewer-prompt.md +++ b/skills/subagent-driven-development/task-reviewer-prompt.md @@ -8,10 +8,16 @@ code quality. more, nothing less) and is well-built (clean, tested, maintainable) ``` -Subagent (general-purpose): +Subagent (Claude Code: the effort-matched worker per SKILL.md Effort +Selection, scaled to the diff, one of worker-low-effort, worker-medium-effort, +or worker-high-effort. Other harnesses, or if the roster is absent: +general-purpose): description: "Review Task N (spec + quality)" model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted model silently inherits the session's most expensive one] + effort: [Claude Code carries effort via the worker agent above. Codex: set + model_reasoning_effort per SKILL.md Effort Selection. Other + harnesses run at session effort.] prompt: | You are reviewing one task's implementation: first whether it matches its requirements, then whether it is well-built. This is a task-scoped gate, @@ -167,6 +173,10 @@ Subagent (general-purpose): **Placeholders:** - `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection +- `[EFFORT]` REQUIRED on Claude Code: dispatch through the effort-matched + worker agent (worker-low-effort, worker-medium-effort, or worker-high-effort), + scaled to the diff, per SKILL.md Effort Selection. On Codex, set + model_reasoning_effort instead. - `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N` prints the path; same file the implementer worked from) - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from diff --git a/tests/claude-code/test-effort-worker-roster.sh b/tests/claude-code/test-effort-worker-roster.sh index c31dccfdad..0d3dedc0cf 100755 --- a/tests/claude-code/test-effort-worker-roster.sh +++ b/tests/claude-code/test-effort-worker-roster.sh @@ -85,11 +85,31 @@ check_effort_section() { done } +check_template_wiring() { + echo "--- dispatch templates reference the effort roster / Effort Selection ---" + grep -q 'Effort Selection' "$SDD_DIR/implementer-prompt.md" \ + && pass "implementer-prompt references Effort Selection" \ + || fail "implementer-prompt missing Effort Selection reference" + grep -q 'model_reasoning_effort' "$SDD_DIR/implementer-prompt.md" \ + && pass "implementer-prompt notes Codex model_reasoning_effort" \ + || fail "implementer-prompt missing Codex effort note" + grep -q 'Effort Selection' "$SDD_DIR/task-reviewer-prompt.md" \ + && pass "task-reviewer-prompt references Effort Selection" \ + || fail "task-reviewer-prompt missing Effort Selection reference" + grep -q 'model_reasoning_effort' "$SDD_DIR/task-reviewer-prompt.md" \ + && pass "task-reviewer-prompt notes Codex model_reasoning_effort" \ + || fail "task-reviewer-prompt missing Codex effort note" + grep -qi 'effort' "$CODE_REVIEWER" \ + && pass "code-reviewer template notes effort" \ + || fail "code-reviewer template missing effort note" +} + main() { echo "=== Test: effort worker roster ===" check_roster check_drift_guard check_effort_section + check_template_wiring if [[ "$FAILURES" -gt 0 ]]; then echo "FAILED ($FAILURES failure(s))" exit 1 From aead28476c28a684d50fbe7ceb72809b9d9b5103 Mon Sep 17 00:00:00 2001 From: Gabriel Borges Date: Mon, 6 Jul 2026 20:43:13 -0400 Subject: [PATCH 5/5] docs(sdd): pin final-review effort inline and tighten code-reviewer test check --- skills/requesting-code-review/code-reviewer.md | 5 +++-- tests/claude-code/test-effort-worker-roster.sh | 9 ++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/requesting-code-review/code-reviewer.md b/skills/requesting-code-review/code-reviewer.md index f81fac8f76..1cde626779 100644 --- a/skills/requesting-code-review/code-reviewer.md +++ b/skills/requesting-code-review/code-reviewer.md @@ -3,8 +3,9 @@ Use this template when dispatching a code reviewer subagent. On Claude Code, dispatch through the effort-matched worker agent, scaled to the -review's difficulty (see subagent-driven-development's Effort Selection). On -Codex, set model_reasoning_effort. +review's difficulty (see subagent-driven-development's Effort Selection). SDD's +final whole-branch review is a judgment task and stays at high effort regardless +of the diff size. On Codex, set model_reasoning_effort. **Purpose:** Review completed work against requirements and code quality standards before it cascades into more work. diff --git a/tests/claude-code/test-effort-worker-roster.sh b/tests/claude-code/test-effort-worker-roster.sh index 0d3dedc0cf..6f8a7a71d3 100755 --- a/tests/claude-code/test-effort-worker-roster.sh +++ b/tests/claude-code/test-effort-worker-roster.sh @@ -99,9 +99,12 @@ check_template_wiring() { grep -q 'model_reasoning_effort' "$SDD_DIR/task-reviewer-prompt.md" \ && pass "task-reviewer-prompt notes Codex model_reasoning_effort" \ || fail "task-reviewer-prompt missing Codex effort note" - grep -qi 'effort' "$CODE_REVIEWER" \ - && pass "code-reviewer template notes effort" \ - || fail "code-reviewer template missing effort note" + grep -q 'Effort Selection' "$CODE_REVIEWER" \ + && pass "code-reviewer template references Effort Selection" \ + || fail "code-reviewer template missing Effort Selection reference" + grep -q 'model_reasoning_effort' "$CODE_REVIEWER" \ + && pass "code-reviewer template notes Codex model_reasoning_effort" \ + || fail "code-reviewer template missing Codex effort note" } main() {