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
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.
Jesse Vincent