diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 06cd0a21..15b6fd32 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -26,7 +26,7 @@ You MUST create a task for each of these items and complete them in order: 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria 4. **Propose 2-3 approaches** — with trade-offs and your recommendation 5. **Present design** — in sections scaled to their complexity, get user approval after each section -6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit +6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD--design.md` and commit (exactly this path — not `docs/specs/`) 7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) 8. **User reviews written spec** — ask user to review the spec file before proceeding 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan @@ -109,7 +109,7 @@ digraph brainstorming { **Documentation:** - Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD--design.md` - - (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 diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 78d88540..da10abac 100644 --- a/skills/executing-plans/SKILL.md +++ b/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 diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index d44f91bb..bdb26898 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -86,6 +86,10 @@ digraph process { } ``` +## Spec Context + +If the plan's header cites a spec (`**Spec:** `), 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. diff --git a/skills/subagent-driven-development/implementer-prompt.md b/skills/subagent-driven-development/implementer-prompt.md index d9a32f70..ec9005f6 100644 --- a/skills/subagent-driven-development/implementer-prompt.md +++ b/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] diff --git a/skills/subagent-driven-development/spec-reviewer-prompt.md b/skills/subagent-driven-development/spec-reviewer-prompt.md index 1cc84a76..793dd96f 100644 --- a/skills/subagent-driven-development/spec-reviewer-prompt.md +++ b/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 diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 847412ec..d2fb1b82 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -7,16 +7,18 @@ description: Use when you have a spec or requirements for a multi-step task, bef ## Overview -Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. +Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to execute: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. 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, 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-.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 @@ -53,6 +55,8 @@ 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--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] **Tech Stack:** [Key technologies/libraries]