SDD: add a reasoning-effort dimension to subagent dispatch (implements #1747)

[gborges0727]

Who is submitting this PR?

Field	Value
Your model + version	Claude Opus 4.8 (1M-context variant), model id claude-opus-4-8[1m]
Harness + version	Claude Code 2.1.201
All plugins installed	superpowers@claude-plugins-official, axiom@claude-code-plugins-plus, backend-development@claude-code-workflows, code-documentation@claude-code-workflows, javascript-typescript@claude-code-workflows, frontend-design@claude-plugins-official, ui-designer@cc-marketplace
Human partner who reviewed this diff	Gabriel Borges (@gborges0727)

This PR implements issue #1747. The design, plan, and skill wording were produced by the agent above and reviewed line by line by the human partner; the changes were executed with superpowers:subagent-driven-development (fresh implementer + two-stage review per task) and the guidance was tested with superpowers:writing-skills and a live quorum drill.

What problem are you trying to solve?

SDD dispatches every subagent (implementer, task reviewer, fix, final reviewer) at the session's reasoning effort, because on Claude Code effort cannot be set at dispatch: the Task tool overrides model per invocation but not effort, and the only per-subagent effort control is agent-definition frontmatter. We hit this first-hand executing this very PR with SDD: dispatching implementers and reviewers, the Agent/Task tool exposed a model parameter and no effort parameter, so every subagent inherited the session effort regardless of task type.

The misallocation runs both ways, and one direction is a quality risk, not just a cost one. A high-effort session spends high-effort reasoning transcribing plan tasks that already contain the complete code (the effort twin of the "most capable model for transcription-grade tasks" waste that #1744's model fix measured but does not touch). More importantly, a default-effort session runs the final whole-branch review, which SDD deliberately pins to the most capable model, at default effort, and under cost pressure a controller will scale that review's effort down. SDD already matches the model to the task (the Model Selection section from #1744). Effort is the same dial's second axis, and it was welded to the session.

Issue #1747 documents the mechanics per harness, measured at the API request level with a logging proxy (subagent calls carry the agent frontmatter's output_config.effort on the wire and are sent with thinking: disabled, so prompt-level thinking cues are inert for subagents).

What does this PR change?

It adds an ## Effort Selection section to the subagent-driven-development skill (mirroring the neighboring Model Selection section and reusing its judgment guardrail), ships three effort-pinned worker agents in a new agents/ directory (worker-low-effort, worker-medium-effort, worker-high-effort, each carrying only an effort value so a dispatch-time model override still wins), wires the effort dimension into the two SDD dispatch templates and the shared code-reviewer template, and adds a static test guarding the roster and its references. No existing guidance is rewritten.

Is this change appropriate for the core library?

Yes. It is general-purpose SDD guidance that benefits any project, not domain-, team-, or tool-specific, and it adds no third-party dependency. It is the same shape as the existing Model Selection guidance: harness-general reasoning (match effort to task type) with a harness-conditional mechanism (Claude Code needs agent files because the Task tool cannot set effort; Codex has a native model_reasoning_effort per-agent key; other harnesses expose effort only at session level, which the section documents). It is not a new skill and does not restructure or reword the project's existing, tuned content.

What alternatives did you consider?

• Session-effort guidance only (docs, zero mechanism). Cannot express "low for transcription implementers, high for the final review" simultaneously in one session, which is the actual win. Rejected.
• Per-invocation effort on Claude Code's Task tool. Would dissolve the problem cleanly and is requested upstream (Feature: effort/thinking configuration for Task tool subagents anthropics/claude-code#25669, #43083, #14321), but has no movement; agent files work today. This PR is the mechanism that exists now, and it becomes a thin fallback if the Task tool later gains the parameter.
• Roster shape. The issue sketched model+effort baked into each agent name (implementer-sonnet-med). We rejected that: since the Task tool's model override takes precedence over frontmatter, an agent only needs to carry effort, so three role-agnostic effort workers replace a role x model x effort matrix, avoid stale model names in filenames, and preserve the existing "specify the model per task" philosophy.
• Thinking-token caps. SDD: cost-tiering stack + plan-mandated-defect escalation + pre-flight plan review (stacked on #1717) #1744 measured these backfiring (E06, output tokens +80%). Effort is a different mechanism (the model's own target-depth control, not a truncation cap), so that result should not transfer a priori, but this PR makes no cost-magnitude claim on that basis; see Evaluation.
• Do nothing. Every long autonomous SDD session keeps paying session-effort prices on transcription tasks and risks running the final review below its pinned tier.

Does this PR contain multiple unrelated changes?

No. One logical change: the effort dimension for SDD dispatch. Every file touched (the roster, the Effort Selection section, the three dispatch templates, the test) serves that single feature.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: SDD: cost-tiering stack + plan-mandated-defect escalation + pre-flight plan review (stacked on #1717) #1744 (MERGED), docs: Make SDD Model Selection guidance harness-aware for OpenCode-family agents #1786 (CLOSED), subagent-driven-development: concrete opencode-go model roster #1852 (CLOSED), Model selection hard gate #1748 (CLOSED)

No open or closed PR addresses reasoning effort; this is the effort axis, distinct from every model-selection PR. #1744 (the merged cost-tiering stack) is the direct sibling this builds beside, adding the orthogonal effort axis without touching its Model Selection content. #1786 (harness-aware Model Selection) was closed for sitting on a stale base and adding a duplicate section rather than editing existing guidance; this PR is on current dev and adds a distinct new dimension adjacent to Model Selection, not a duplicate of it. #1852 was closed as opencode-go-gateway-specific roster guidance kept on a fork; this change is harness-general and vendor-neutral. #1748 ("model selection hard gate") is a different, model-axis proposal.

Environment tested

Harness	Harness version	Model	Model version/ID
Claude Code	2.1.201	Opus (controller) / Sonnet (subagents + eval subject)	claude-opus-4-8[1m] / claude-sonnet-4-6

New harness support

N/A. This PR does not add a new harness.

Evaluation

Initial prompt that led to this change: "i want to try to implement a PR for issue #1747".

Static test: tests/claude-code/test-effort-worker-roster.sh validates the roster frontmatter and guards that every worker name referenced in the skill and templates resolves to an agent file. Green.

Adversarial behavior micro-test (writing-skills methodology), 5 reps per arm, each read manually. Fresh-context subagents act as the SDD controller and answer a two-dispatch scenario (a transcription task, and the final whole-branch review on a small branch with "minimize cost" pressure). Control arm sees only Model Selection; treatment arm additionally sees Effort Selection.

Metric	Control (no Effort Selection)	Treatment (+ Effort Selection)
Transcription dispatch effort	5/5 low	5/5 low
Transcription dispatch agent (delivers effort on Claude Code?)	5/5 general-purpose (cannot set effort)	5/5 worker-low-effort (carries it)
Final review effort under cost pressure	4/5 high, 1/5 slipped to medium	5/5 high
Final review dispatch agent	5/5 code-reviewer/general-purpose	5/5 worker-high-effort

The guidance moves the controller from asserting an effort it cannot deliver to routing through the worker agents that carry it (0/5 to 5/5), and it closes the guardrail slip (the control lowered the final review's effort under cost pressure 1/5; the treatment held it 5/5). Honest caveat: the prompt supplied an effort field, so this measures mechanism-routing and guardrail-holding, not whether an unprompted controller spontaneously considers effort.

Live drill (superpowers-evals quorum, sdd-rejects-extra-features, Claude Code, Sonnet). The same scenario (a full SDD execution of a two-function plan with two-stage review) ran against dev (baseline) and against this branch, each via --plugin-dir on the respective checkout. Both passed all acceptance criteria and 8/8 deterministic post-checks, so the change is non-regressive. The dispatch pattern is the difference:

Dispatch	dev baseline (agent / model)	this branch (agent / model)
Implement Task 1 (add)	general-purpose / haiku	worker-low-effort / haiku
Review Task 1	general-purpose / haiku	worker-medium-effort / sonnet
Implement Task 2 (multiply)	general-purpose / haiku	worker-low-effort / haiku
Review Task 2	general-purpose / sonnet	worker-medium-effort / sonnet
Final whole-branch review	general-purpose / opus	worker-high-effort / opus

On dev, all five subagents dispatch as general-purpose with zero worker references: effort is welded to the session. On this branch, the controller routes each role through the matching effort worker, and the final whole-branch review holds worker-high-effort + opus on a two-function diff (the judgment guardrail firing in a real session, not just the micro-test). The run also confirms two things end-to-end that the tool schema only implied: the plugin's agents/ dir loads via --plugin-dir so the workers are dispatchable, and a dispatch-time model override composes with a named effort agent (worker-low-effort dispatched with model: haiku).

What this PR does not claim. It makes no measured cost-magnitude claim. The cost saving from lowering implementer effort remains eval-pending, as the spec states; the change ships the mechanism and the guidance, whose direction is safe by construction because it respects the judgment guardrail (high effort stays on the final review and every judgment point; low effort goes only to task types Model Selection already validated as mechanical, gated by the task review).

Rigor

• If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (results in Evaluation above)
• This change was tested adversarially, not just on the happy path (cost-pressure temptation on the final-review guardrail; 5 reps per arm read manually)
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language). The Effort Selection section is new and additive; the Model Selection section is untouched.

Human review

• A human has reviewed the COMPLETE proposed diff before submission