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.jsonindex 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.jsonindex 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/.gitignoreindex 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.mdindex 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---