fix(skills): plans reference the spec instead of restating it — end to end (SUP-333 A)

Consolidates the reference-discipline change with every consumer of it,
so this PR is independently mergeable (previously split across two
stacked PRs whose intermediate state left the SDD spec reviewer blind).

writing-plans: plans reference the spec — never restate, paraphrase,
or summarize it; spec owns WHAT/WHY, plan owns HOW; cite by path in
the header (**Spec:** template line) and by section where a task needs
context; No Placeholders repetition stays intra-plan; no-spec branch
scoped to conversational-requirements-only (eval-caught: an agent used
an unscoped no-spec branch to skip writing the spec entirely).

brainstorming: spec path loophole closed (claude shortened
docs/superpowers/specs/ to docs/specs/, documented run); an existing
differently-named docs dir is not a "user preference".

subagent-driven-development: Spec Context section — the controller
reads the plan-cited spec and pastes cited sections into implementer
and spec-reviewer prompts; the spec reviewer's diff-only rule gets a
spec-document exception. Without this, reference discipline starves
the pipeline of requirements.

executing-plans: Step 1 reads the spec the plan cites (the
non-subagent path; plans are no longer self-contained).

Eval evidence (quorum, full-stack text): cost-spec-plan-duplication
claude 3/3 pass (RED: 5/5 agents failed), codex pass, pi pass (the
683-line duplication RED agent); sdd-spec-context-consumed functional
pass with deterministic dispatch-prompt check;
writing-plans-no-spec-conversational 2/2 pass;
triggering-writing-plans canary 3/3.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

skills/brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. The one exception: a request that leaves zero design decisions open (a fully specified trivial change, e.g. 'add a basic checkbox, nothing fancy') needs no design - implement it directly without invoking this skill."
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
 ---
 
 # Brainstorming Ideas Into Designs
@@ -11,13 +11,11 @@ Start by understanding the current project context, then ask questions one at a
 
 <HARD-GATE>
 Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
-
-Exception — nothing to design: if the request leaves no design decisions open — the user has fully specified the outcome and there is exactly one reasonable way to do it (e.g. "add a basic checkbox, nothing fancy", a literal config value change, a copy fix) — implement it directly. Brainstorming exists to surface decisions; when there are none, the user's request IS the design. Any of these put the gate back on: a new file or dependency, a schema/API/data question, more than one plausible interpretation, or the user framing it as a feature or project to think through.
 </HARD-GATE>
 
 ## Anti-Pattern: "This Is Too Simple To Need A Design"
 
-Projects go through this process. A todo list, a single-function utility, a data migration — "simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but if anything remains to decide, you MUST present it and get approval. Do not confuse this with the nothing-to-design exception above: "this seems simple, I'll skip the design" is a rationalization whenever decisions exist — the exception applies only when the user's request already contains every decision.
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
 
 ## Checklist
 
@@ -111,8 +109,7 @@ digraph brainstorming {
 **Documentation:**
 
 - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
-  - The `docs/superpowers/` prefix is the convention; do not shorten it to `docs/specs/`
-  - (User preferences for spec location override this default)
+  - (An explicit user instruction overrides this default; an existing differently-named docs directory does not)
 - Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git
 

skills/executing-plans/SKILL.md

@@ -16,7 +16,7 @@ Load plan, review critically, execute all tasks, report when complete.
 ## The Process
 
 ### Step 1: Load and Review Plan
-1. Read plan file
+1. Read plan file, and the spec it cites in its `**Spec:**` header (plans reference requirements rather than restating them)
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Raise them with your human partner before starting
 4. If no concerns: Create todos for the plan items and proceed

skills/subagent-driven-development/SKILL.md

@@ -11,8 +11,6 @@ Execute plan by dispatching fresh subagent per task, with two-stage review after
 
 **Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
 
-**Proportionality:** Review fanout scales with the change. When the entire plan is one trivial, fully-specified mechanical change — a one-line edit, a log statement, a constant bump — implement it directly (or with a single implementer subagent), verify it, and commit. Skip the review subagents and the final reviewer: a diff with no room for interpretation has nothing for a spec or quality review to catch, and three dispatches for one line cost more than the change itself. When in doubt whether a change is trivial, it is not — run the full pipeline. Within a multi-task plan, run the full pipeline for every task regardless of size; this exception applies only when the whole plan is one trivial change.
-
 **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. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
 
 ## When to Use
@@ -63,16 +61,11 @@ digraph process {
     }
 
     "Read plan, extract all tasks with full text, note context, create todos" [shape=box];
-    "Entire plan = one trivial mechanical change?" [shape=diamond];
-    "Implement directly, verify, commit (no review fanout)" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer subagent for entire implementation" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Read plan, extract all tasks with full text, note context, create todos" -> "Entire plan = one trivial mechanical change?";
-    "Entire plan = one trivial mechanical change?" -> "Implement directly, verify, commit (no review fanout)" [label="yes — see Proportionality"];
-    "Implement directly, verify, commit (no review fanout)" -> "Use superpowers:finishing-a-development-branch";
-    "Entire plan = one trivial mechanical change?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="no"];
+    "Read plan, extract all tasks with full text, note context, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
     "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -93,6 +86,10 @@ digraph process {
 }
 ```
 
+## Spec Context
+
+If the plan's header cites a spec (`**Spec:** <path>`), read it once during plan extraction. Plans reference requirements rather than restating them — when a task cites a spec section, paste that section's text into the implementer and spec-reviewer prompts along with the task text. Implementer subagents never read the spec file themselves; the spec reviewer may additionally read it at the cited path (its prompt says so).
+
 ## Model Selection
 
 Use the least powerful model that can handle each role to conserve cost and increase speed.
@@ -244,7 +241,7 @@ Done!
 
 **Never:**
 - Start implementation on main/master branch without explicit user consent
-- Skip reviews (spec compliance OR code quality) on a non-trivial task — the Proportionality exception covers only a plan that is one trivial mechanical change
+- Skip reviews (spec compliance OR code quality)
 - Proceed with unfixed issues
 - Dispatch multiple implementation subagents in parallel (conflicts)
 - Make subagent read plan file (provide full text instead)

skills/subagent-driven-development/implementer-prompt.md

@@ -12,6 +12,8 @@ Subagent (general-purpose):
 
     [FULL TEXT of task from plan - paste it here, don't make subagent read file]
 
+    [If the task cites spec sections, paste the cited sections' text here too]
+
     ## Context
 
     [Scene-setting: where this fits, dependencies, architectural context]

skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -12,7 +12,7 @@ Subagent (general-purpose):
 
     ## What Was Requested
 
-    [FULL TEXT of task requirements]
+    [FULL TEXT of task requirements, including the text of any spec sections the task cites]
 
     ## What Implementer Claims They Built
 
@@ -28,7 +28,7 @@ Subagent (general-purpose):
     git diff [BASE_SHA]..[HEAD_SHA]
     ```
 
-    Only read files in this diff. Do not crawl the broader codebase.
+    Only read files in this diff. Do not crawl the broader codebase. (One exception: if the requirements cite a spec document, you may read that spec at its cited path.)
 
     ## Read-Only Review
 

skills/writing-plans/SKILL.md

@@ -11,14 +11,14 @@ Write comprehensive implementation plans assuming the engineer has zero context
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
-**Plans reference the spec; they never restate it.** The spec owns the WHAT and WHY — requirements, acceptance criteria, design decisions. The plan owns the HOW — tasks, files, code, commands. Cite the spec by path in the header and by section where a task needs context. Re-deriving spec content inline doubles the documents and lets them drift apart. "Zero context" means the engineer can execute each step mechanically; it does not mean the plan repeats what the spec already says — they can read the spec at the cited path.
+**Plans reference the spec; they never restate, paraphrase, or summarize it.** The spec owns the WHAT and WHY — requirements, acceptance criteria, design decisions; the plan owns the HOW — tasks, files, code, commands. Cite it by path in the header and by section where a task needs context. Reference discipline never means skipping the spec: if brainstorming produced one, it exists and the plan cites it. No Placeholders still requires repeating code and commands WITHIN the plan; copying FROM the spec is different: a step that needs a requirement's prose is under-specified — turn it into a concrete action. Snapshotting spec text into the plan hides drift, not prevents it. "Zero context" means each step is mechanically executable, not that the plan repeats the spec.
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
 **Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
 
 **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
-- (User preferences for plan location override this default)
+- (An explicit user instruction overrides this default; an existing differently-named docs directory does not)
 
 ## Scope Check
 
@@ -55,7 +55,7 @@ This structure informs the task decomposition. Each task should produce self-con
 
 **Goal:** [One sentence describing what this builds]
 
-**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — requirements and design decisions live there; do not restate them here]
+**Spec:** [Path to the spec doc, e.g. `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` — requirements and design decisions live there; do not restate them here. Only if no spec doc exists (requirements arrived conversationally; brainstorming never ran): write "none — requirements:" and state them once here, not per task]
 
 **Architecture:** [2-3 sentences about approach]