- 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
The old brainstorming command included writing the design document
before handing off to implementation planning. This was lost when
the command was converted to a skill.
Added Phase 4: Design Documentation to write the validated design
to docs/plans/YYYY-MM-DD-<topic>.md before proceeding to worktree
setup and planning.
Tested with subagent to verify design document is written and
committed even under time pressure.
Plugin-provided commands are automatically namespaced by Claude Code
to avoid conflicts. Updated all documentation to show correct syntax.
Changes:
- README.md: Updated all command examples to use /superpowers:* format
- plugin.json: Bump version to 3.1.1
- RELEASE-NOTES.md: Added v3.1.1 release entry
Fixes#44
Removed all references to the separate obra/superpowers-skills repository
and updated documentation to reflect that skills are now included directly
in the plugin using Claude Code's first-party skills system.
Changes:
- Removed outdated architecture section about repository separation
- Removed find-skills tool and SUPERPOWERS_SKILLS_ROOT references
- Removed git-based update and forking workflows
- Updated contributing section for direct repository contributions
- Updated skills list to match current plugin structure
- Simplified installation and update instructions
- commands/brainstorm.md: Redirect to brainstorming skill
- commands/write-plan.md: Redirect to writing-plans skill
These command files provide Claude Code slash commands that invoke the
corresponding skills with proper descriptions for discoverability.
- Add explicit guidance to use AskUserQuestion in Phase 1 (Understanding)
- Add explicit guidance to use AskUserQuestion in Phase 2 (Exploration)
- Add concrete examples showing how to structure questions with options
- Add "Question Patterns" section explaining when to use AskUserQuestion vs open-ended
- Update Quick Reference table to include Tool Usage column
- Update Key Principles to mention structured choices with AskUserQuestion
Benefits:
- Makes it clear when to use structured vs open-ended questions
- Provides concrete examples for effective use of AskUserQuestion
- Helps present options with clear trade-offs
- 156 lines (well under 500-line Anthropic recommendation)
Update all skill references to use explicit requirement markers:
- REQUIRED BACKGROUND: For prerequisite understanding
- REQUIRED SUB-SKILL: For mandatory workflow dependencies
- Complementary skills: For optional but helpful related skills
Changes:
- Remove old path format (skills/collaboration/X → X)
- Add explicit "REQUIRED" markers to make dependencies clear
- Update Integration sections with categorized skill relationships
- Fix non-existent skill references
- Update cross-reference documentation in writing-skills
This makes it immediately clear which skills MUST be used vs optional references,
helping Claude understand and comply with skill dependencies.
- Fix description: correct grammar and use third-person voice
- Add Quick Reference table for easy scanning
- Add copyable checklist for tracking progress through phases
- Add decision flowchart for when to revisit earlier phases
- Convert "Remember" section to structured Key Principles table
- Remove references to non-existent related skills
Follows Anthropic patterns:
- Workflow with checklist format
- Quick reference table at top
- Appropriate use of flowchart for decision points
- Scannable table format for principles
- 108 lines (well under 500-line recommendation)
- Add anthropic-best-practices.md as ancillary reference document
- Reference it in writing-skills SKILL.md overview
- Provides official guidance on skill structure, progressive disclosure, workflows,
and evaluation patterns that complement the TDD-focused approach
- Update all 20 skill frontmatter names to match their directory names in lowercase
- Fix defense-in-depth name (was Defense-in-Depth-Validation)
- Fix receiving-code-review name (was Code-Review-Reception)
- Update all skill announcements and cross-references to use lowercase names
- Update commands redirects to reference lowercase skill names
Ensures consistent naming: skill directory names, frontmatter names, and documentation
references all use lowercase kebab-case format (e.g., brainstorming, test-driven-development)
This restructures the repo to support multiple plugins by moving the current
plugin into a subdirectory. The plugin continues to be published as "superpowers"
in the marketplace.
The initialization script was incorrectly warning about upstream updates
when the local repository was ahead of upstream. This happened because
the logic didn't distinguish between three states:
- Local behind: LOCAL=BASE, REMOTE≠BASE → should update or warn
- Local ahead: LOCAL≠BASE, REMOTE=BASE → no warning needed
- Diverged: LOCAL≠BASE, REMOTE≠BASE → should warn
Changed the else clause to only set SKILLS_BEHIND when REMOTE≠BASE,
which correctly handles all three scenarios.
Fixes the issue reported in #8 where users with local commits ahead
of upstream were seeing spurious "new skills available" warnings.
Determine and fetch from the current branch's tracking remote instead of
hardcoding upstream/origin. This ensures the correct remote is updated
regardless of fork/upstream setup.
Fixes issue where auto-update wasn't fetching on session start.
Following The Elements of Style:
- Use active voice (Rule 10): "We rewrote" not "has been rewritten"
- Omit needless words (Rule 13): removed "automatically", "optionally", etc.
- Break up long sentences: split run-on second sentence into short, direct statements
- Put statements in positive form (Rule 11): direct assertions rather than negatives
- Keep it concise: "Claude notifies" not "Claude will notify"
Overview section now more direct and forceful while maintaining all information.
Provides prose description of v2.0 changes before diving into details:
- Skills repository separation (what it means, why it matters)
- Nine new skills (problem-solving, research, architecture)
- using-skills rewrite (imperative tone, clearer structure)
- Improved tools (find-skills outputs usable paths)
- Community focus (easier to contribute and improve skills)
Session start hook now:
- Inlines full getting-started/SKILL.md content (no @ links in hooks)
- Runs find-skills and shows complete skills list
- Shows tool paths after the guide
Getting-started improvements:
- Removed "Just Read This Guide?" section (redundant with hook)
- Removed "Last thing" announcement requirement
- Tightened intro from ~80 to ~35 words
- Simplified "How to Load Skills" section
- Updated Workflow 2 to reference skills list shown at session start
- Removed redundant find-skills path examples
This eliminates friction - agents see all available skills immediately without
needing to search first. No excuse for "I didn't want to spend time searching."
Added section "5. Cross-Referencing Other Skills" under CSO, explaining:
- Proper format: skills/path/name (no @ prefix or /SKILL.md suffix)
- Why: @ syntax force-loads files, burning context unnecessarily
- How to read: Use Read tool on ${CLAUDE_PLUGIN_ROOT}/skills/path/SKILL.md
This completes the move of cross-referencing guidance from getting-started
to writing-skills, improving separation of concerns.
Improved separation of concerns:
- getting-started: focused on USING skills (workflows, finding, reading)
- writing-skills: focused on WRITING skills (including cross-references)
The "Referencing Skills in Documentation" section belongs in writing-skills
because it's authoring guidance, not usage guidance. Added as subsection 5
under Claude Search Optimization (CSO).
Tested with subagents to verify improved clarity in both skills.
Fixed three key issues identified through TDD testing:
1. Removed writing-skills content duplication
- Moved detailed RED-GREEN-REFACTOR process to skills/meta/writing-skills
- Added concise pointer to writing-skills for those who need it
2. Clarified conversation search workflow
- Changed "Mandatory Workflow 3" → "Workflow 3: Historical Context Search (Conditional)"
- Updated Workflow 2 step 2 to explicitly reference Workflow 3's conditions
- Eliminated contradiction between mandatory and conditional framing
3. Fixed typo: "juming" → "jumping"
Tested with subagents before and after changes to verify improvements.
Personal skills should be version controlled. Added deployment checklist items:
- Commit skill to git
- Push to GitHub
- Consider sharing to core
This ensures personal skills are properly tracked and backed up.
The SessionStart hook now tells Claude the exact paths to find-skills
and skill-run tools. Since hooks have CLAUDE_PLUGIN_ROOT expanded,
the actual paths are injected into Claude's context.
This solves the problem of CLAUDE_PLUGIN_ROOT not being available
as a bash environment variable.
CLAUDE_PLUGIN_ROOT is a template variable for documentation, not a bash
environment variable. Updated getting-started to use explicit paths that
work in actual bash commands.
Changes:
- Use ~/.claude/plugins/cache/superpowers explicitly in bash examples
- Add helper to find plugin location if needed
- Update skill reading instructions to check both personal and core locations
Consolidated into scripts/find-skills. The old tools in skills/getting-started/
are no longer needed - all functionality is now in scripts/find-skills which:
- Shows all skills with descriptions (default)
- Filters by pattern (when pattern provided)
- Searches both personal and core skills
- Works without CLAUDE_PLUGIN_ROOT environment variable
Consolidates skill discovery and adds generic runner for cross-platform compatibility.
Changes:
- Created scripts/find-skills: Unified tool (show all + filter by pattern)
- Shows descriptions by default
- Searches personal first, then core (shadowing)
- Logs searches for gap analysis
- Bash 3.2 compatible
- Created scripts/run: Generic runner for any skill script
- Searches personal superpowers first, then core
- Enables running arbitrary skill scripts without CLAUDE_PLUGIN_ROOT env var
- Example: scripts/run skills/collaboration/remembering-conversations/tool/search-conversations
- Fixed bash 3.2 compatibility in list-skills, skills-search
- Replaced associative arrays with newline-delimited lists
- Works on macOS default bash (3.2) and Linux bash 4+
- Updated all documentation to reference scripts/find-skills
- Removed redundant wrapper scripts
This solves the CLAUDE_PLUGIN_ROOT environment variable issue - scripts
can now be called from anywhere without needing the env var set.
Allows indexing conversations without AI summary generation.
Still generates embeddings locally for semantic search.
Usage: index-conversations --cleanup --no-summaries
Changes:
- Added --no-summaries flag parsing in index-cli.ts
- Updated indexConversations, indexSession, indexUnprocessed to accept noSummaries param
- Changed indexUnprocessed to check database instead of summary file existence
- Updated help text with new flag and examples
This enables indexing large conversation archives without API costs.
Mode-switching was overcomplicated. Back to phases with explicit permission
to revisit earlier phases when constraints emerge or validation fails.
Simpler, clearer, preserves what worked.
Updates conversation indexing and search to use the new personal superpowers
directory structure with environment variable support.
Changes:
- Added src/paths.ts for centralized directory resolution
- Updated db.ts, indexer.ts, verify.ts to use paths.ts
- Created migrate-to-config.sh for data migration from ~/.clank
- Updated all documentation references from ~/.clank to ~/.config/superpowers
- Database paths automatically updated during migration
Migration tested with 5,017 conversations and 6,385 exchanges.
**Discovery enhancement:**
- Add Mandatory Workflow 4 to getting-started: "When Stuck"
- Creates path: getting-started → when-stuck dispatch → specific technique
- Prevents spinning wheels without seeking help
**Trigger clarity:**
- Replace phrase examples with pattern descriptions
- "Partner reveals constraint you didn't consider" (pattern) not "Oh, I forgot..." (phrase)
- Emphasizes NEW information that invalidates current context
- Prevents ambiguity between new constraints vs clarifications
Tested: All skills verified with subagents, triggers work correctly.
- Reference preserving-productive-tensions from brainstorming EXPLORING mode
- Reference detecting-emergent-patterns from brainstorming when stuck
- Reference tracing-knowledge-lineages from brainstorming before changes
- Reference tracing-knowledge-lineages from executing-plans REVIEWING mode
Makes new architecture skills discoverable through commonly-used workflows.
**Mode-switching enhancements:**
- Update brainstorming skill with flexible UNDERSTANDING/EXPLORING/DESIGNING modes
- Update executing-plans skill with REVIEWING/EXECUTING/BLOCKED/REPORTING modes
- Add inline dot diagrams with full contextual labels for all valid transitions
- Enforce explicit mode switch announcements
**New architecture skills from amplifier patterns:**
- preserving-productive-tensions: Recognize when to preserve multiple valid approaches vs force resolution
- tracing-knowledge-lineages: Understand idea evolution to avoid repeating failures
- detecting-emergent-patterns: Cross-domain synthesis, collision-zone thinking, simplification cascades
All skills pressure-tested with subagents using RED-GREEN-REFACTOR methodology.
Jesse Vincent