- Moved testing-skills-with-subagents to writing-skills/testing-skills-with-subagents.md
- Moved examples/ directory to writing-skills/examples/
- Updated writing-skills to reference via @testing-skills-with-subagents.md
- Updated README to reflect consolidation
- Removed standalone skill (now a supporting reference)
- Moved testing-anti-patterns to test-driven-development/testing-anti-patterns.md
- Added reference in TDD skill for progressive disclosure
- Updated README to reflect consolidation
- Removed standalone skill (now a supporting reference)
The contribution workflow is now via standard GitHub PR process,
not a dedicated skill. The skill was documenting an old workflow
that no longer applies.
Tested against claude -p with multiple scenarios. Key fixes:
- Clarify skill check comes BEFORE ANY response including clarifications
- Add rationalizations: "I need more context first", "Let me explore first", "This feels productive"
- Flowchart entry point now "User message received" → clearer blocking gate
- Shorter, more scannable format (flowchart + table)
Verified: "Fix login bug" now triggers systematic-debugging first
Documents:
- How to run integration tests
- subagent-driven-development test details
- Token analysis tool usage
- Troubleshooting common issues
- Writing new integration tests
- Session transcript format
- Rewrote analyze-token-usage.py to parse main session file correctly
- Extracts usage from toolUseResult fields for each subagent
- Shows breakdown by agent with descriptions
- Integrated into test-subagent-driven-development-integration.sh
- Displays token usage automatically after each test run
The skill instructions are internal and don't appear in user-facing
output. Updated verification to parse the session JSONL transcript
and check for actual tool usage:
- Skill tool invocation
- Task tool (subagents)
- TodoWrite (tracking)
- Implementation results
The superpowers-dev marketplace makes skills available only when running
from the plugin directory. Updated test to run claude from superpowers
directory while working on the test project.
Claude Code headless mode requires --allowed-tools flag to actually
execute tool calls. Without it, Claude only responds as if it's doing
things but doesn't actually use tools.
Changes:
- Updated run_claude helper to accept allowed_tools parameter
- Updated integration test to use --allowed-tools=all
- This enables actual tool execution (Write, Task, Bash, etc.)
Now the integration test should actually execute the workflow instead
of just talking about it.
Simplified command substitution to avoid shell parsing issues.
Instead of nested heredoc in command substitution, write prompt
to file first then read it.
Created full end-to-end integration test that executes a real plan
and verifies the new workflow improvements actually work.
New test: test-subagent-driven-development-integration.sh
- Creates real Node.js test project
- Generates implementation plan (2 tasks)
- Executes using subagent-driven-development skill
- Verifies 8 key behaviors:
1. Plan read once at beginning (not per task)
2. Full task text provided to subagents (not file reading)
3. Subagents perform self-review
4. Spec compliance review before code quality
5. Spec reviewer reads code independently
6. Working implementation produced
7. Tests pass
8. No extra features added (spec compliance)
Integration tests are opt-in (--integration flag) due to 10-30 min runtime.
Updated run-skill-tests.sh:
- Added --integration flag
- Separates fast tests from integration tests
- Shows note when integration tests skipped
Updated README with integration test documentation.
Run with:
./run-skill-tests.sh # Fast tests only
./run-skill-tests.sh --integration # Include integration tests
Created automated test suite for testing superpowers skills using
Claude Code CLI in headless mode.
New files:
- tests/claude-code/run-skill-tests.sh - Main test runner
- tests/claude-code/test-helpers.sh - Helper functions for testing
- tests/claude-code/test-subagent-driven-development.sh - First test
- tests/claude-code/README.md - Documentation
Test framework features:
- Run Claude Code with prompts and capture output
- Assertion helpers (contains, not_contains, count, order)
- Test project creation helpers
- Timeout support (default 5 minutes)
- Verbose mode for debugging
- Specific test selection
First test verifies subagent-driven-development skill:
- Skill loading
- Workflow ordering (spec compliance before code quality)
- Self-review requirements
- Plan reading efficiency (read once)
- Spec compliance reviewer skepticism
- Review loops
- Task context provision
Run with: cd tests/claude-code && ./run-skill-tests.sh
Made sequencing explicit:
- Spec compliance review loop must fully complete (✅) before code quality
- Added "Do NOT proceed to code quality review until spec compliance is ✅"
- Code Quality Review section starts with "Only run after spec compliance review is complete"
- Red Flags: Added "Start code quality review before spec compliance is ✅ (wrong order)"
This ensures we don't waste time reviewing code quality of the wrong
implementation. Verify they built the right thing first, then verify
they built it well.
The spec compliance reviewer now:
- Does NOT trust implementer's report
- Is warned implementer finished suspiciously quickly
- MUST verify everything by reading actual code
- Compares implementation to requirements line by line
- Reports issues with file:line references
Key additions:
- "Do Not Trust the Report" section
- Explicit DO NOT / DO lists
- "Verify by reading code, not by trusting report"
- Changed "What Was Implemented" to "What Implementer Claims They Built"
This prevents rubber-stamping and ensures independent verification
of spec compliance against actual codebase.
Key improvements based on feedback:
1. Read plan once, not per task
- Extract all tasks in Step 1
- Reference extracted tasks in Step 2
- Eliminates redundant file reading
2. Enable questions during work
- Not just before, but also while working
- "It's always OK to ask questions"
- Don't guess or make assumptions
3. Add self-review before reporting
- Completeness: implemented everything?
- Quality: best work, clear names?
- Discipline: avoided overbuilding?
- Testing: comprehensive, real behavior?
- Catches issues before handoff
4. Add spec compliance review
- Separate reviewer checks: built the right thing?
- Flags missing requirements
- Flags extra/unneeded work
- Flags misunderstandings
- Runs BEFORE code quality review
5. Make reviews loops, not one-shot
- Reviewer finds issues
- Implementer fixes
- Reviewer reviews again
- Repeat until approved
- Applies to both spec and code quality
Two-stage review process:
- Stage 1: Spec compliance (right thing?)
- Stage 2: Code quality (built well?)
This enables subagents to do their best work with clear requirements,
opportunities to clarify, self-critique, and thorough review loops.
Changed workflow so controller provides complete task context directly
rather than making subagent read plan file.
Key changes:
- Controller reads plan and extracts full task text
- Controller provides scene-setting context (dependencies, architecture)
- Subagent receives complete information in prompt (no file reading)
- Subagent can ask clarifying questions before beginning work
- Controller handles questions/concerns before subagent proceeds
Benefits:
- No file reading overhead for subagent
- Controller curates exactly what context is needed
- Questions surfaced before work begins (not after)
- Subagent has complete information to do best work
This enables subagents to start with clarity rather than ambiguity.
Analyzed feedback from two Claude instances using superpowers in real
development scenarios. Identified 8 core problems and proposed improvements
organized by impact and risk.
Key problems:
- Configuration change verification gap (verify success not intent)
- Background process accumulation across subagents
- Context bloat in subagent prompts
- Missing self-reflection before handoff
- Mock-interface drift
- Code reviewer file access issues
- Skills not being read/enforced
- Fix workflow latency
Proposed improvements organized in 3 phases:
- Phase 1: High-impact, low-risk (do first)
- Phase 2: Moderate changes (test carefully)
- Phase 3: Optimization (validate first)
See plan for detailed analysis and open questions.
Fixed POSIX compatibility issue in hooks/run-hook.cmd that caused
"Bad substitution" errors on Ubuntu/Debian systems where /bin/sh is dash.
Changes:
- Replaced bash-specific ${BASH_SOURCE[0]:-$0} with POSIX-compliant $0
- Tested with both bash and sh (POSIX mode) on macOS
- Updated version to 3.6.2 in all required files
Fixes#141
New features:
- Cross-platform polyglot wrapper (run-hook.cmd) for Windows/Unix
- Pure bash JSON escaping for Windows compatibility
- Documentation for polyglot hooks setup
* feat: Add Windows support for session-start hook
- Create polyglot session-start.cmd that works in both CMD and bash
- Update hooks.json to use the .cmd polyglot launcher
- Replace sed/awk with pure bash for JSON escaping (Windows compatibility)
The polyglot script uses a heredoc trick:
- CMD sees the @echo off block and runs bash.exe with cygpath conversion
- Bash sees a heredoc and skips to the Unix section
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Add execute permission to session-start.cmd for Unix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* docs: Add comprehensive polyglot hooks documentation
- Add docs/windows/polyglot-hooks.md explaining the cross-platform technique
- Add reusable run-hook.cmd wrapper for parameterized hook execution
- Document how the polyglot works in CMD vs bash
- Include troubleshooting section and related GitHub issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* test: Add polyglot hook test script for macOS/Linux
Run ./test-polyglot.sh from repo root to verify:
- Required files exist with execute permissions
- Simple wrapper (session-start.cmd) produces valid JSON
- Parameterized wrapper (run-hook.cmd) works
- Heredoc correctly skips CMD block on Unix
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Use direct pipe to jq in test to avoid variable escaping issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* refactor: Use single reusable run-hook.cmd for all hooks
- Remove session-start.cmd in favor of run-hook.cmd
- Update hooks.json to use: run-hook.cmd session-start.sh
- Simplify test script to only test run-hook.cmd
This makes it easy to add more hooks - just create the .sh file
and add a line to hooks.json pointing to run-hook.cmd with the script name.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* fix: Simplify run-hook.cmd CMD block
Pass path directly to bash instead of using cygpath in a subshell.
The complex quoting was causing issues on Windows.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* chore: Remove test-polyglot.sh
Testing complete - polyglot hooks work on Windows and macOS.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
Switch from chat.message hook to session.created event for injecting
the using-superpowers skill content. The new approach:
- Injects at session creation via session.prompt() with noReply: true
- Explicitly tells model the skill is already loaded to prevent
redundant use_skill calls
- Consolidates bootstrap generation into getBootstrapContent() helper
- Removes fallback pattern in favor of single implementation
Tested with 10 consecutive test runs and manual skill trigger validation.
Create comprehensive tests in tests/opencode/ that verify the plugin
works correctly in an isolated test environment:
- setup.sh: Creates temp HOME and installs plugin with proper symlinks
- test-plugin-loading.sh: Verifies plugin structure and JavaScript syntax
- test-skills-core.sh: Unit tests for skills-core.js library functions
- test-tools.sh: Integration tests for use_skill/find_skills (requires OpenCode)
- test-priority.sh: Tests project > personal > superpowers priority
- run-tests.sh: Main test runner with options for integration tests
Run basic tests: ./tests/opencode/run-tests.sh
Run all tests: ./tests/opencode/run-tests.sh --integration
- Add project-local skills directory (.opencode/skills/) with highest priority
- Use client.session.prompt() with noReply for skill loading to persist across compaction
- Add session.compacted event handler to re-inject bootstrap after context compaction
- Update find_skills to list skills from project > personal > superpowers directories
- Support project: prefix for explicit project skill loading
- Keep chat.message hook as fallback for initial context injection
- Delete .opencode/prompts/superpowers.txt (no longer needed)
- Simplify INSTALL.md to remove prompt file copying and agent configuration steps
- Installation now relies on plugin's chat.message hook for automatic context injection
- Cleaner, simpler setup process with fewer manual configuration steps
OpenCode doesn't support injecting context through event hooks. Instead,
the plugin now generates a prompt file that agents can reference via
{file:./prompts/superpowers.txt} in their configuration.
- Replace CommonJS require() with ES import statements
- Use createRequire() for loading CommonJS skills-core module
- Export plugin as 'SuperpowersPlugin' named export
- Maintains compatibility with existing skills-core.js CommonJS module
- Native OpenCode plugin approach using their JavaScript plugin system
- Shared core module (lib/skills-core.js) for code reuse with Codex
- Custom tools: use_skill and find_skills
- Session startup hook for automatic bootstrap
- Three-phase implementation plan
- Update session-start hook to clarify that using-superpowers content is provided directly
- Add explicit guidance to use Skill tool only for other skills
- Prevents confusing loop where agents execute using-superpowers manually
- Reduces overhead and improves user experience
Fixes redundant skill execution in bootstrap workflow.
Update .claude-plugin/plugin.json version from 3.2.3 to 3.4.0 to match
the version already set in marketplace.json. This ensures consistency
across all plugin manifest files.
Remove heavyweight 6-phase process with formal checklists and return to
conversational approach:
- Natural dialogue instead of structured phases
- One question at a time without rigid progression
- 200-300 word design sections with validation
- Keep documentation and implementation handoff
- Remove AskUserQuestion tool requirements and complex flowcharts
This aligns with the original spec: help turn ideas into designs through
collaborative questioning, then present design in small sections.
Applied Strunk's "Elements of Style" principles:
- Rule 13: Omitted needless words (removed "already", "genuinely", etc.)
- Rule 11: Converted negative to positive form ("don't ask" → "ask only when")
- Rule 10: Used active voice where appropriate
- Rule 15: Improved parallel construction in lists
- General: Made language more direct and concrete
Changes maintain the skill's functionality while improving readability.
- Make README more egalitarian: 'AI coding assistants' vs 'Claude Code'
- Reorganize installation: 'Claude Code (via Plugin Marketplace)' and 'Codex (Experimental)'
- Add update checking to bootstrap with 3-second timeout protection
- Bootstrap now checks if local installation is behind GitHub and suggests 'git pull'
- Network failures or timeouts don't block bootstrap (graceful fallback)
- Restructured Codex files to .codex/ directory
- Updated README with simplified GitHub URL installation
- Added comprehensive release notes for v3.3.0
- Moved superpowers-codex script to .codex/superpowers-codex
- Updated all path references for new structure
- Installation now uses GitHub raw URL for streamlined setup
Codex support includes:
- Unified superpowers-codex script with bootstrap/use-skill/find-skills
- Cross-platform Node.js implementation
- Namespaced skills (superpowers:skill-name)
- Tool mapping (TodoWrite→update_plan, etc.)
- Clean skill display without frontmatter
- Personal skill override system
- AGENTS.md (in user's ~/.codex/) now just tells Codex to run bootstrap
- Bootstrap contains all the critical rules and skill locations
- Updated INSTALL.md to show the simplified AGENTS.md example
- Added explanatory text: 'Superpowers teach you new skills and capabilities'
- Single unified script: superpowers-codex with bootstrap/use-skill/find-skills commands
- Cross-platform Node.js implementation (works on Windows, macOS, Linux)
- Namespaced skills: superpowers:skill-name for superpowers, skill-name for personal
- Personal skills override superpowers skills when names match
- Clean skill display: shows name/description without raw frontmatter
- Helpful context: shows supporting files directory for each skill
- Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
- Updated terminology: "Superpowers skills" instead of "Core skills"
- Bootstrap integration with AGENTS.md for automatic startup
- Installation guide and bootstrap instructions specific to Codex
The Skill tool is the proper mechanism for invoking skills, not the Read tool.
Updated the bootstrap instructions and anti-rationalization guidance to reflect this.
Add three layers of enforcement to prevent agents from skipping skill usage:
1. EXTREMELY-IMPORTANT block with absolute language
- "If even 1% chance a skill applies, you MUST read it"
- "You do not have a choice. You cannot rationalize your way out."
2. MANDATORY FIRST RESPONSE PROTOCOL checklist
- 5-step process agents must complete before any response
- Explicit "responding without this = failure" consequence
3. Common Rationalizations section with 8 specific patterns
- "This is just a simple question" → WRONG
- "I can check files quickly" → WRONG
- "Let me gather information first" → WRONG
- Plus 5 more common evasion patterns
These changes address observed agent behavior where they rationalize
around skill usage despite clear instructions. The forceful language
and pre-emptive counter-arguments aim to make rationalization harder.
Fixes#55
Added superpowers:code-reviewer agent to plugin's agents/ directory.
Previously, skills referenced a code-reviewer agent that users needed
to configure personally, causing failures for new users.
Changes:
- New: agents/code-reviewer.md - Agent definition with systematic review checklist
- Updated: skills/requesting-code-review/SKILL.md - Use superpowers:code-reviewer
- Updated: skills/subagent-driven-development/SKILL.md - Use superpowers:code-reviewer
- Version bump: 3.2.0 -> 3.2.1
- Added: .claude-plugin/marketplace.json for local development testing
Jesse Vincent