Skip to content

An agentic skills framework & software development methodology that works.

Prepare v4.0.0 release

Jesse Vincent95c6e1633630
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d4291379f..961d1c10b 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": "3.6.2",
+ "version": "4.0.0",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index da89c3177..179bf5e59 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": "3.6.2",
+ "version": "4.0.0",
"author": {
"name": "Jesse Vincent",
"email": "[email protected]"
diff --git a/.gitignore b/.gitignore
index 4764f267b..573cae048 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,3 @@
.worktrees/
.private-journal/
-.claude/settings.local.json
+.claude/
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 5e7e7df1b..35be6b6ec 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,122 +1,88 @@
# Superpowers Release Notes
-## v4.0.0 (2025-12-11) - dev branch
+## v4.0.0 (2025-12-17)
-### Major Changes
+### New Features
-**Complete skill rewrite with executable flowcharts**
+**Two-stage code review in subagent-driven-development**
-Rewrote several skills using Mermaid flowcharts that serve as executable specifications.
-The key insight: skill descriptions in plugin.json override flowchart content when they
-contain workflow summaries, causing Claude to follow the description instead of the
-detailed process. Fixed by making descriptions trigger-only ("Use when X") without
-process details.
+Subagent workflows now use two separate review stages after each task:
-Skills rewritten with flowcharts:
-- **subagent-driven-development** - Two-stage code review (spec compliance then code quality)
-- **systematic-debugging** - Consolidated from 3 separate skills (root-cause-tracing, defense-in-depth, condition-based-waiting)
-- **using-superpowers** - Visual flowchart showing skill check as blocking gate
+1. **Spec compliance review** - Skeptical reviewer verifies implementation matches spec exactly. Catches missing requirements AND over-building. Won't trust implementer's report—reads actual code.
-**Skill consolidation**
-- Merged `root-cause-tracing`, `defense-in-depth`, `condition-based-waiting` into `systematic-debugging`
-- Merged `testing-skills-with-subagents` into `writing-skills`
-- Merged `testing-anti-patterns` into `test-driven-development`
-- Removed obsolete `sharing-skills` skill
+2. **Code quality review** - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability.
-### Improvements
+This catches the common failure mode where code is well-written but doesn't match what was requested. Reviews are loops, not one-shot: if reviewer finds issues, implementer fixes them, then reviewer checks again.
-**Fixed skill descriptions that override flowcharts**
-
-Updated 7 skill descriptions to be trigger-only (no workflow summaries):
-- dispatching-parallel-agents
-- executing-plans
-- requesting-code-review
-- systematic-debugging
-- test-driven-development
-- writing-plans
-- writing-skills
-
-**Strengthened brainstorming skill trigger**
-- Added skill priority guidance ensuring process skills (brainstorming, debugging) trigger before implementation skills
-- Clearer "Use when" description for feature requests
-
-**Improved subagent-driven-development skill**
-- Complete rewrite with visual flowchart showing controller/worker/reviewer flow
-- Controller now provides full task text to workers (not just references)
-- Two-stage review: spec compliance first, then code quality
-- Spec compliance reviewer made skeptical and verification-focused
-
-**Rewrote using-superpowers skill**
-- Added visual flowchart showing skill check as blocking gate before ANY response
-- Converted rationalizations from bullet list to scannable table format
-- Added new rationalizations based on observed failures
-- Clarified skill check applies even before asking clarifying questions
+Other subagent workflow improvements:
+- Controller provides full task text to workers (not file references)
+- Workers can ask clarifying questions before AND during work
+- Self-review checklist before reporting completion
+- Plan read once at start, extracted to TodoWrite
-### New Features
+New prompt templates in `skills/subagent-driven-development/`:
+- `implementer-prompt.md` - Includes self-review checklist, encourages questions
+- `spec-reviewer-prompt.md` - Skeptical verification against requirements
+- `code-quality-reviewer-prompt.md` - Standard code review
-**Skill triggering test framework** (`tests/skill-triggering/`)
-- Tests whether skills trigger correctly from naive prompts
-- Validates 6 skills: systematic-debugging, test-driven-development, writing-plans, dispatching-parallel-agents, executing-plans, requesting-code-review
-- All tests passing - skills trigger based on descriptions without explicit naming
-
-**Subagent-driven-development test suite** (`tests/subagent-driven-dev/`)
-- End-to-end test using go-fractals project scaffold
-- Validates full workflow: task execution, code review, verification
-- Tests with `--dangerously-skip-permissions` for automation
-
-**Flowchart visualization tool** (`tests/render-graphs.js`)
-- Extracts Mermaid diagrams from SKILL.md files
-- Generates PNG visualizations for documentation
-- Useful for reviewing skill flowcharts
-
-**Claude Code skills test framework** (`tests/claude-code/`)
-- Integration tests using `claude -p` to verify skill behavior
-- Tests verify skill usage via session transcript analysis
-- Supports `--dangerously-skip-permissions` for unrestricted testing
-- Real-time output display during test runs
-- Token usage analysis for cost tracking
-
-**Testing documentation** (`docs/testing.md`)
-- Comprehensive guide to testing skills with Claude Code
-- Covers integration testing patterns and best practices
-- Documents permission modes and transcript verification
+**Debugging techniques consolidated with tools**
-### Documentation
+`systematic-debugging` now bundles supporting techniques and tools:
+- `root-cause-tracing.md` - Trace bugs backward through call stack
+- `defense-in-depth.md` - Add validation at multiple layers
+- `condition-based-waiting.md` - Replace arbitrary timeouts with condition polling
+- `find-polluter.sh` - Bisection script to find which test creates pollution
+- `condition-based-waiting-example.ts` - Complete implementation from real debugging session
-**Added "Description Trap" documentation to writing-skills**
-- Documents how skill descriptions override flowchart content
-- Explains why descriptions must be trigger-only
-- Provides examples of good vs bad descriptions
+**Testing anti-patterns reference**
-### Files Changed
+`test-driven-development` now includes `testing-anti-patterns.md` covering:
+- Testing mock behavior instead of real behavior
+- Adding test-only methods to production classes
+- Mocking without understanding dependencies
+- Incomplete mocks that hide structural assumptions
+
+**Skill test infrastructure**
+
+Three new test frameworks for validating skill behavior:
+
+`tests/skill-triggering/` - Validates skills trigger from naive prompts without explicit naming. Tests 6 skills to ensure descriptions alone are sufficient.
+
+`tests/claude-code/` - Integration tests using `claude -p` for headless testing. Verifies skill usage via session transcript (JSONL) analysis. Includes `analyze-token-usage.py` for cost tracking.
+
+`tests/subagent-driven-dev/` - End-to-end workflow validation with two complete test projects:
+- `go-fractals/` - CLI tool with Sierpinski/Mandelbrot (10 tasks)
+- `svelte-todo/` - CRUD app with localStorage and Playwright (12 tasks)
+
+### Major Changes
+
+**DOT flowcharts as executable specifications**
+
+Rewrote key skills using DOT/GraphViz flowcharts as the authoritative process definition. Prose becomes supporting content.
+
+**The Description Trap** (documented in `writing-skills`): Discovered that skill descriptions override flowchart content when descriptions contain workflow summaries. Claude follows the short description instead of reading the detailed flowchart. Fix: descriptions must be trigger-only ("Use when X") with no process details.
+
+**Skill priority in using-superpowers**
+
+When multiple skills apply, process skills (brainstorming, debugging) now explicitly come before implementation skills. "Build X" triggers brainstorming first, then domain skills.
+
+**brainstorming trigger strengthened**
+
+Description changed to imperative: "You MUST use this before any creative work—creating features, building components, adding functionality, or modifying behavior."
+
+### Breaking Changes
+
+**Skill consolidation** - Six standalone skills merged:
+- `root-cause-tracing`, `defense-in-depth`, `condition-based-waiting` → bundled in `systematic-debugging/`
+- `testing-skills-with-subagents` → bundled in `writing-skills/`
+- `testing-anti-patterns` → bundled in `test-driven-development/`
+- `sharing-skills` removed (obsolete)
+
+### Other Improvements
-**Skills Updated:**
-- `skills/brainstorming/SKILL.md` - Stronger trigger, skill priority
-- `skills/dispatching-parallel-agents/SKILL.md` - Trigger-only description
-- `skills/executing-plans/SKILL.md` - Trigger-only description
-- `skills/requesting-code-review/SKILL.md` - Trigger-only description
-- `skills/subagent-driven-development/SKILL.md` - Complete rewrite with flowcharts
-- `skills/systematic-debugging/SKILL.md` - Consolidated from 3 skills
-- `skills/test-driven-development/SKILL.md` - Merged testing-anti-patterns
-- `skills/using-superpowers/SKILL.md` - Flowchart format, new rationalizations
-- `skills/writing-plans/SKILL.md` - Trigger-only description
-- `skills/writing-skills/SKILL.md` - Merged testing-skills-with-subagents, description trap docs
-
-**Skills Removed:**
-- `skills/condition-based-waiting/` - Merged into systematic-debugging
-- `skills/defense-in-depth/` - Merged into systematic-debugging
-- `skills/root-cause-tracing/` - Merged into systematic-debugging
-- `skills/sharing-skills/` - Obsolete
-- `skills/testing-anti-patterns/` - Merged into test-driven-development
-- `skills/testing-skills-with-subagents/` - Merged into writing-skills
-
-**Test Infrastructure:**
-- New: `tests/skill-triggering/` - Skill triggering validation
-- New: `tests/subagent-driven-dev/` - Full workflow test suite
-- New: `tests/render-graphs.js` - Flowchart visualization
-- New: `tests/claude-code/` - Integration test framework
-- New: `docs/testing.md` - Testing documentation
-- New: `docs/plans/skills-improvement-plan.md` - Improvement roadmap
+- **render-graphs.js** - Tool to extract DOT diagrams from skills and render to SVG
+- **Rationalizations table** in using-superpowers - Scannable format including new entries: "I need more context first", "Let me explore first", "This feels productive"
+- **docs/testing.md** - Guide to testing skills with Claude Code integration tests
---