diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 87d873f4b..b9aa59578 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "superpowers", "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "6.4.2", + "version": "6.4.1", "source": "./", "author": { "name": "Jesse Vincent", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index aa2a09cea..97eb2a8fc 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "superpowers", "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques", - "version": "6.4.2", + "version": "6.4.1", "author": { "name": "Jesse Vincent", "email": "jesse@fsck.com" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index f14735290..5aa395588 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "superpowers", - "version": "6.4.2", + "version": "6.4.1", "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.", "author": { "name": "Jesse Vincent", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 8a8475cca..792dcd0e4 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -2,7 +2,7 @@ "name": "superpowers", "displayName": "Superpowers", "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques", - "version": "6.4.2", + "version": "6.4.1", "author": { "name": "Jesse Vincent", "email": "jesse@fsck.com" diff --git a/.devin-plugin/plugin.json b/.devin-plugin/plugin.json index 71d0f0b8a..bee4db483 100644 --- a/.devin-plugin/plugin.json +++ b/.devin-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "superpowers", - "version": "6.4.2", + "version": "6.4.1", "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.", "author": { "name": "Jesse Vincent", diff --git a/.hermes-plugin/plugin.yaml b/.hermes-plugin/plugin.yaml index 9de7655ae..2639ad8e3 100644 --- a/.hermes-plugin/plugin.yaml +++ b/.hermes-plugin/plugin.yaml @@ -1,5 +1,5 @@ name: superpowers -version: 6.4.2 +version: 6.4.1 description: Superpowers skills and workflow bootstrap for Hermes Agent author: obra provides_hooks: diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json index 1effbcfaf..f1be031c9 100644 --- a/.kimi-plugin/plugin.json +++ b/.kimi-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "superpowers", - "version": "6.4.2", + "version": "6.4.1", "description": "An agentic skills framework and software development methodology.", "author": { "name": "Jesse Vincent", diff --git a/.muse-plugin/marketplace.json b/.muse-plugin/marketplace.json index c3d729538..59ae54ebc 100644 --- a/.muse-plugin/marketplace.json +++ b/.muse-plugin/marketplace.json @@ -9,7 +9,7 @@ { "name": "superpowers", "description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques", - "version": "6.4.2", + "version": "6.4.1", "source": "./", "author": { "name": "Jesse Vincent", diff --git a/.muse-plugin/plugin.json b/.muse-plugin/plugin.json index 3588fd506..3a822199b 100644 --- a/.muse-plugin/plugin.json +++ b/.muse-plugin/plugin.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "name": "superpowers", "displayName": "Superpowers", - "version": "6.4.2", + "version": "6.4.1", "description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques", "compat": { "source": "native", diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md index dca404b08..890958064 100644 --- a/.opencode/INSTALL.md +++ b/.opencode/INSTALL.md @@ -79,7 +79,7 @@ V1 `plugin` key and the V2 `plugins` key): ```json { - "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.2"] + "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.1"] } ``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..da5796987 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Superpowers — Contributor Guidelines + +Read and follow [AGENTS.md](AGENTS.md) before doing anything in this repository. diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 44490ef1e..7b9e9b4af 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,21 +1,5 @@ # Superpowers Release Notes -## v6.4.2 (2026-09-25) - -`writing-plans` produces leaner plans, faster. Plans now record the decisions an implementer needs (signatures, test assertions, the spec's values) instead of writing out the code. Some frontier models, including Opus 5.5, could get overzealous during plan writing and, with certain prompting, would sometimes try to implement the entire project while designing the plan. The new skill keeps planning focused on the plan. When we reproduced the original report, the scratch builds went away, and plans took a quarter of the time and about a third of the tokens. Thanks to Harper Reed for the report and session bundle. (#2333) - -### Writing Plans - -- **A plan records decisions. It's not a transcript of the code.** "What a Step Contains" replaces the "No Placeholders" section. A test step names the test and its assertions. A code step gives the exact signature, the file, and the spec's values, and includes a body only for an algorithm those don't determine. A verification step gives the command and its passing output. A reference to another task goes through that task's Interfaces block. Placeholders are still called out as the opposite failure. (#2333) -- **Self-review checks proportion.** The plan compares its own length to the spec's. A plan several times longer than the spec is a transcript, and when code blocks dominate, bodies get replaced with signatures and test assertions. (#2333) -- **The plan's reader is described as capable:** an engineer who writes idiomatic code once they know the exact interface and test. This replaces "zero context, questionable taste." Steps are now sized as "one action with a checkable result" instead of "2-5 minutes." (#2333) -- Every plan written by the new skill executed 9/9 against planted-defect probes on Sonnet 5, the same result as full-code plans. (#2333) -- Removed `plan-document-reviewer-prompt.md`. Nothing referenced it. (#2333) - -### Documentation - -- Removed `CLAUDE.md`. Claude Code now reads `AGENTS.md` directly, but only when no `CLAUDE.md` exists, so keeping the one-line pointer would have hidden the real guidelines. - ## v6.4.1 (2026-09-18) v6.4.0 was never shipped. v6.4.1 is the first release with these changes. It holds back the new `proving-it-works-with-a-movie` skill, which is getting cleanup and robustness work and will return in a later release. diff --git a/docs/README.opencode.md b/docs/README.opencode.md index 404a65d10..f6c2f5eff 100644 --- a/docs/README.opencode.md +++ b/docs/README.opencode.md @@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key): ```json { - "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.2"] + "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.1"] } ``` diff --git a/gemini-extension.json b/gemini-extension.json index 915bfd27b..8a9b48e2c 100644 --- a/gemini-extension.json +++ b/gemini-extension.json @@ -1,6 +1,6 @@ { "name": "superpowers", "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques", - "version": "6.4.2", + "version": "6.4.1", "contextFileName": "GEMINI.md" } diff --git a/package.json b/package.json index d9339add4..80a562e23 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "superpowers", - "version": "6.4.2", + "version": "6.4.1", "description": "Superpowers skills and runtime bootstrap for coding agents", "type": "module", "main": ".opencode/plugins/superpowers.js", diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 4cf0275d8..78c7126e0 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -7,7 +7,9 @@ description: Use when you have a spec or requirements for a multi-step task, bef ## Overview -Write implementation plans for an engineer who has not seen this codebase or this spec. Assume they write idiomatic code in the project's language once they know the exact interface and the exact test, and that they will make a reasonable choice wherever the plan leaves one open. What they cannot know is what you decided: which files, which names and signatures, which values from the spec, which tests prove each task. Document those. 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 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. + +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. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." @@ -40,9 +42,9 @@ deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable. -## Step Granularity +## Bite-Sized Task Granularity -**Each step is one action with a checkable result:** +**Each step is one action (2-5 minutes):** - "Write the failing test" - step - "Run it to make sure it fails" - step - "Implement the minimal code to make the test pass" - step @@ -118,11 +120,12 @@ def test_specific_behavior(): Run: `pytest tests/path/test.py::test_name -v` Expected: FAIL with "function not defined" -- [ ] **Step 3: Implement `function(input: InputType) -> ResultType` in `exact/path/to/file.py`** +- [ ] **Step 3: Write minimal implementation** -One line on the approach when the signature and the test leave a choice -(which library call, which data structure); a code block only for an -algorithm they do not determine. +```python +def function(input): + return expected +``` - [ ] **Step 4: Run test to verify it passes** @@ -137,28 +140,15 @@ git commit -m "feat: add specific feature" ``` ```` -## What a Step Contains +## No Placeholders -A step is done when the implementer can write exactly one reasonable thing -from it. That is the whole requirement: unambiguous, not complete. Each kind -of step carries what makes it unambiguous and nothing more: - -- **A test step:** the test's name and its assertions, as code, with the - spec's exact values in them. -- **A code step:** the exact signature (name, parameters, return type), the - file it lives in, and the specific values the spec pins. The implementer - writes the body. A body appears only for an algorithm the signature and - tests do not determine, or for exact copy the spec fixes. -- **A verification step:** the command to run and the output that means it - passed. -- **A reference to another task:** that task's Interfaces block says what - to use; the plan does not repeat that task's code. - -A plan is the set of decisions the implementer cannot make alone. A plan -longer than the code it describes has written the code instead. Lines that -decide nothing ("TBD", "handle edge cases", "add appropriate validation", -"write tests for the above", a type or function no task defines) are the -opposite failure, and the self-review catches both. +Every step must contain the actual content an engineer needs. These are **plan failures** — never write them: +- "TBD", "TODO", "implement later", "fill in details" +- "Add appropriate error handling" / "add validation" / "handle edge cases" +- "Write tests for the above" (without actual test code) +- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order) +- Steps that describe what to do without showing how (code blocks required for code steps) +- References to types, functions, or methods not defined in any task ## Self-Review @@ -166,14 +156,12 @@ After writing the complete plan, look at the spec with fresh eyes and check the **1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps. -**2. Step scan:** Every step must let the implementer write exactly one reasonable thing, and no step may carry more than that: a line that decides nothing is a gap, a function body the signature and tests already determine is a transcript. Fix both. +**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them. **3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. **4. Review Focus:** For each input class or failure mode the spec implies, is there a task whose tests exercise it? The five uncovered ones most likely to bite a person go in the Review Focus section, and each line there gets its test added to the owning task. An empty section means you checked and found none, not that you skipped the check. -**5. Proportion:** Compare the plan's length to the spec's. A plan several times longer than the spec it implements is a transcript of the program, not a plan. If code blocks are most of the document, replace bodies with signatures, test names and assertions, and check that each step is still unambiguous. - If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task. ## Execution Handoff diff --git a/skills/writing-plans/plan-document-reviewer-prompt.md b/skills/writing-plans/plan-document-reviewer-prompt.md new file mode 100644 index 000000000..1c12c1d61 --- /dev/null +++ b/skills/writing-plans/plan-document-reviewer-prompt.md @@ -0,0 +1,49 @@ +# Plan Document Reviewer Prompt Template + +Use this template when dispatching a plan document reviewer subagent. + +**Purpose:** Verify the plan is complete, matches the spec, and has proper task decomposition. + +**Dispatch after:** The complete plan is written. + +``` +Subagent (general-purpose): + description: "Review plan document" + prompt: | + You are a plan document reviewer. Verify this plan is complete and ready for implementation. + + **Plan to review:** [PLAN_FILE_PATH] + **Spec for reference:** [SPEC_FILE_PATH] + + ## What to Check + + | Category | What to Look For | + |----------|------------------| + | Completeness | TODOs, placeholders, incomplete tasks, missing steps | + | Spec Alignment | Plan covers spec requirements, no major scope creep | + | Task Decomposition | Tasks have clear boundaries, steps are actionable | + | Buildability | Could an engineer follow this plan without getting stuck? | + + ## Calibration + + **Only flag issues that would cause real problems during implementation.** + An implementer building the wrong thing or getting stuck is an issue. + Minor wording, stylistic preferences, and "nice to have" suggestions are not. + + Approve unless there are serious gaps — missing requirements from the spec, + contradictory steps, placeholder content, or tasks so vague they can't be acted on. + + ## Output Format + + ## Plan Review + + **Status:** Approved | Issues Found + + **Issues (if any):** + - [Task X, Step Y]: [specific issue] - [why it matters for implementation] + + **Recommendations (advisory, do not block approval):** + - [suggestions for improvement] +``` + +**Reviewer returns:** Status, Issues (if any), Recommendations