docs: Update INSTALL.md with Codex bootstrap setup#505
Closed
docs: Update INSTALL.md with Codex bootstrap setup#505
Conversation
Integrate Manus-style persistent planning for long-running tasks that span multiple sessions or exceed 50 tool calls. Introduces new manus-planning skill with 3-file system (task_plan.md, findings.md, progress.md), archive support, and conditional PreToolUse hooks for automatic plan reminders. Changes: - New manus-planning skill with 5-phase workflow and persistent memory - Brainstorming updated to offer both Native and Manus planning options - Added PreToolUse hook (manus-pretool.sh) for context-aware plan reminders - Updated using-superpowers with planning approach guidance - Rebranded from superpowers to superpowers-ng v0.1.0 - Added comprehensive README highlighting NG features - Created new RELEASE-NOTES.md focused on v0.1.0 changes Files: - skills/manus-planning/SKILL.md (main skill definition) - skills/manus-planning/templates/ (3 template files) - commands/manus-plan.md (slash command) - hooks/manus-pretool.sh (conditional hook script) - hooks/hooks.json (added PreToolUse hook) - skills/brainstorming/SKILL.md (planning choice) - skills/using-superpowers/SKILL.md (planning guidance) - .claude-plugin/plugin.json (rebranded metadata) - README.md (complete rewrite for NG) - RELEASE-NOTES.md (fresh v0.1.0) Credits: Jesse Vincent (obra/superpowers), Ahmad Othman Ammar Adi (planning-with-files) Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Adds comprehensive integration with Ralph, enabling Superpowers-NG skills to work seamlessly in autonomous loop environments: - brainstorming: Now checks for existing design.md and skips re-brainstorming in subsequent loops - manus-planning: Already compatible with Ralph's multi-session nature and --continue flag - Documentation: Ralph integration guide with PROMPT.md template using official status format - Examples: 5 concrete scenarios, circuit breaker patterns, anti-patterns, exit criteria This enables Ralph users to: - Design once, implement across multiple loops - Maintain persistent memory via manus-planning files - Keep TDD discipline throughout autonomous sessions - Use evidence-based completion signals Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
* test: add manus pretool hook unit test * test: add ralph status block unit test * test: add manus resume integration test * test: add ralph status emission integration * test: add manus+ralph combined integration * docs: wire slim manus/ralph tests into runner * test: improve Ralph integration test prompts with status block format * test: add git setup to Ralph integration tests * test: improve manus-ralph combined test prompt and timeout * test: simplify manus-ralph combined test with pre-created files * test: simplify manus resume test with pre-created files
Add support for working directly in repo without worktrees across all relevant skills (brainstorming, writing-plans, finishing-a-development-branch, using-git-worktrees, manus-planning). Changes: - Add user choice between worktree (recommended) and direct-on-repo workflows - Update cleanup steps to be optional and worktree-specific only - Add safety checks for direct-on-repo mode (feature branch, clean working tree) - Preserve worktree as recommended default while enabling faster direct workflow This provides flexibility for users who prefer simpler workflows without sacrificing the isolation benefits of worktrees for those who need them. Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: fix documentation accuracy issues in skills (obra#157) - Fix broken commit message HEREDOC syntax in sharing-skills/SKILL.md - Move entire message inside command substitution for valid bash - Fix contradictory test requirements in systematic-debugging/SKILL.md - Clarify automated tests are "strongly preferred" - One-off scripts should be documented for regression testing - Requirement is for "reproducible test" not escape clause - Fix typo in testing-skills-with-subagents/SKILL.md - "ith" -> "with" in checklist item * fix use_skill agent context (obra#290) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup (obra#297) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup The plugin was hardcoded to look for personal skills in ~/.config/opencode/skills, ignoring users who set OPENCODE_CONFIG_DIR to a custom path (e.g., for dotfiles management). Now uses OPENCODE_CONFIG_DIR if set, falling back to the default path. * fix: update help text to use dynamic paths Use configDir and personalSkillsDir variables in help text so paths are accurate when OPENCODE_CONFIG_DIR is set. * fix: normalize OPENCODE_CONFIG_DIR before use Handle edge cases where the env var might be: - Empty or whitespace-only - Using ~ for home directory (common in .env files) - A relative path Now trims, expands ~, and resolves to absolute path. * feat(opencode): use native skills and fix agent reset bug (obra#226) (obra#330) * fix use_skill agent context (obra#290) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup (obra#297) * fix: respect OPENCODE_CONFIG_DIR for personal skills lookup The plugin was hardcoded to look for personal skills in ~/.config/opencode/skills, ignoring users who set OPENCODE_CONFIG_DIR to a custom path (e.g., for dotfiles management). Now uses OPENCODE_CONFIG_DIR if set, falling back to the default path. * fix: update help text to use dynamic paths Use configDir and personalSkillsDir variables in help text so paths are accurate when OPENCODE_CONFIG_DIR is set. * fix: normalize OPENCODE_CONFIG_DIR before use Handle edge cases where the env var might be: - Empty or whitespace-only - Using ~ for home directory (common in .env files) - A relative path Now trims, expands ~, and resolves to absolute path. * feat(opencode): use native skills and fix agent reset bug (obra#226) - Replace custom use_skill/find_skills tools with OpenCode's native skill tool - Use experimental.chat.system.transform hook instead of session.prompt (fixes obra#226 agent reset on first message) - Symlink skills directory into ~/.config/opencode/skills/superpowers/ - Update installation docs with comprehensive Windows support: - Command Prompt, PowerShell, and Git Bash instructions - Proper symlink vs junction handling - Reinstall safety with cleanup steps - Verification commands for each shell * Add OpenCode native skills changes to release notes Documents: - Breaking change: switch to native skill tool - Fix for agent reset bug (obra#226) - Fix for Windows installation (obra#232) --------- Co-authored-by: Vinicius da Motta <viniciusmotta8@gmail.com> Co-authored-by: oribi <oribarilan@gmail.com> * fix: Windows hook execution for Claude Code 2.1.x (obra#331) * fix: convert shell scripts from CRLF to LF line endings Add .gitattributes to enforce LF line endings for shell scripts, preventing bash errors like "/usr/bin/bash: line 1: : command not found" when scripts are checked out on Windows with CRLF. Fixes obra#317 (SessionStart hook fails due to CRLF line endings) Files converted: - hooks/session-start.sh - lib/brainstorm-server/start-server.sh - lib/brainstorm-server/stop-server.sh - lib/brainstorm-server/wait-for-feedback.sh - skills/systematic-debugging/find-polluter.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: update Windows hook execution for Claude Code 2.1.x Claude Code 2.1.x changed the Windows execution model: it now auto-detects .sh files in hook commands and prepends "bash " automatically. This broke the polyglot wrapper because: Before: "run-hook.cmd" session-start.sh (wrapper executes) After: bash "run-hook.cmd" session-start.sh (bash can't run .cmd) Changes: - hooks.json now calls session-start.sh directly (Claude Code handles bash) - Added deprecation comment to run-hook.cmd explaining the change - Updated RELEASE-NOTES.md Fixes obra#317, obra#313, obra#275, obra#292 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> * chore: release v4.1.0 Breaking changes: - OpenCode: Switched to native skills system (migration required) Fixes: - OpenCode: Fixed agent reset on session start (obra#226) - OpenCode: Fixed Windows installation (obra#232) - Claude Code: Fixed Windows hook execution for 2.1.x Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: bump plugin version to 4.1.0 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(opencode): update docs for native skills, fix symlink instructions Issues addressed: - obra#342: INSTALL.md still referenced removed find_skills/use_skill tools - obra#339: Symlink instructions could fail if target already exists Changes: - INSTALL.md: Added missing skills symlink step, updated to native skill tool - INSTALL.md: Removed Node.js prerequisite (no longer needed) - README.opencode.md: Added explicit rm before ln -s (ln -sf doesn't remove dirs) - Both files: Use ln -s instead of ln -sf for clarity Note: obra#343 (plugin vs plugins folder name) not addressed in this commit Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(opencode): standardize on plugins/ directory per official docs OpenCode officially documents ~/.config/opencode/plugins/ (plural) as the plugin directory. Our docs previously used plugin/ (singular), which also works but caused confusion. Changes: - Renamed .opencode/plugin/ to .opencode/plugins/ in repo structure - Updated INSTALL.md to use plugins/ everywhere - Updated README.opencode.md (all platforms: Linux, macOS, Windows CMD, PowerShell, Git Bash) to use plugins/ - Updated test scripts to match Tested: Both singular and plural forms work, but we now match official docs. Fixes obra#343 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * chore: bump version to 4.1.1 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * codex: clarify subagent tool mapping in bootstrap * fix(tests): handle case variations in skill recognition test The assertion now matches "subagent-driven-development", "Subagent-Driven Development", and "Subagent Driven" since Claude's responses may use different casing and formatting styles. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test: add worktree requirement test for subagent-driven-development Add Test 8 to verify that using-git-worktrees is mentioned as a required skill for subagent-driven-development. This test will initially fail per TDD approach - the skill file needs to be updated to pass this test. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * test: add Test 9 - main branch red flag warning TDD: Test verifies that subagent-driven-development skill warns against starting implementation directly on main/master branch. Test expects skill to recommend worktree or feature branch instead. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(subagent-driven-development): add using-git-worktrees as required skill Adds using-git-worktrees as the first required workflow skill in the Integration section. This makes explicit that an isolated workspace should be set up before starting subagent-driven development. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(subagent-driven-development): add main branch red flag to Never list Add explicit warning against starting implementation on main/master branch without first using a worktree for isolation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(using-git-worktrees): add subagent/executing-plans as callers Update Integration section to show bidirectional relationship: subagent-driven-development and executing-plans now list using-git-worktrees as required, so this skill should list them as callers. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(executing-plans): add worktree requirement before executing plans Add Integration section referencing using-git-worktrees skill as required, consistent with subagent-driven-development skill. Also add reminder to never start on main/master branch. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: change main branch red flag to require explicit user consent Instead of prohibiting main branch work entirely, allow it with explicit user consent. This is more flexible while still ensuring users are aware of the implications. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Simplify installation verification instructions Remove /help command check and specific slash command list. Skills are primarily invoked by describing what you want to do, not by running specific commands. * fix: Windows hook execution for Claude Code 2.1.x (obra#331) * fix: convert shell scripts from CRLF to LF line endings Add .gitattributes to enforce LF line endings for shell scripts, preventing bash errors like "/usr/bin/bash: line 1: : command not found" when scripts are checked out on Windows with CRLF. Fixes obra#317 (SessionStart hook fails due to CRLF line endings) Files converted: - hooks/session-start.sh - lib/brainstorm-server/start-server.sh - lib/brainstorm-server/stop-server.sh - lib/brainstorm-server/wait-for-feedback.sh - skills/systematic-debugging/find-polluter.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: update Windows hook execution for Claude Code 2.1.x Claude Code 2.1.x changed the Windows execution model: it now auto-detects .sh files in hook commands and prepends "bash " automatically. This broke the polyglot wrapper because: Before: "run-hook.cmd" session-start.sh (wrapper executes) After: bash "run-hook.cmd" session-start.sh (bash can't run .cmd) Changes: - hooks.json now calls session-start.sh directly (Claude Code handles bash) - Added deprecation comment to run-hook.cmd explaining the change - Updated RELEASE-NOTES.md Fixes obra#317, obra#313, obra#275, obra#292 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> * fix: run SessionStart hook async to prevent Windows terminal freeze The synchronous SessionStart hook blocked the TUI from entering raw mode on Windows, freezing all keyboard input. The pure-bash escape_for_json function is O(n^2) on Git Bash, taking 60+ seconds. Running the hook async prevents the freeze while still injecting superpowers context. Multiple users confirmed this workaround. Fixes obra#404, obra#413, obra#414, obra#419 * fix: replace O(n^2) escape_for_json with parameter substitution The character-by-character loop using ${input:$i:1} was O(n^2) in bash due to substring copy overhead. On Windows Git Bash this took 60+ seconds, freezing terminal input even with async hooks. Replaced with bash parameter substitution (${s//old/new}) which runs each pattern as a single C-level pass. 7x faster on macOS, expected to be dramatically faster on Windows Git Bash where the original caused the worst hangs. Relates to obra#404, obra#413 * Fix Windows/PowerShell invocation of superpowers-codex Windows doesn't respect shebangs, so directly invoking the extensionless superpowers-codex script triggers an "Open with" dialog. Prefix all invocations with `node` (harmless on Unix, required on Windows) and add a .cmd wrapper for manual invocation on Windows. Fixes obra#285, obra#243 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix ~/ path expansion on Windows — use $HOME instead PowerShell doesn't expand ~ when passed as an argument to node, causing MODULE_NOT_FOUND errors. $HOME expands correctly in both bash and PowerShell. Fixes obra#285 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Remove bootstrap CLI and related files The bootstrap CLI (superpowers-codex), Windows wrapper, and bootstrap content file are no longer needed — Codex now has native skill discovery that replaces this mechanism. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add minimal Codex installer for native skill discovery Creates symlink from ~/.agents/skills/superpowers to repo skills dir, updates ~/.codex/AGENTS.md with gatekeeper block, removes old bootstrap block if present. Windows junction fallback when symlinks are blocked. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rewrite INSTALL.md for native skill discovery Two-step install: clone + run installer. Replaces the old manual setup that required editing AGENTS.md by hand. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rewrite Codex docs for native skill discovery Replaces bootstrap CLI references with native discovery flow. Install is now clone + run installer. Documents tool mappings, personal skills path, and Windows junction fallback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Polish docs from 5-agent review - INSTALL.md: add prerequisites, Windows note, verify step, clone deletion in uninstall - README.codex.md: fix Windows section (junctions not symlinks), add description field guidance, consistent terminology - install-codex.mjs: accurate link type labels (symlink vs junction) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix path resolution and symlink removal in Codex installer Use fileURLToPath() instead of manual URL pathname parsing to correctly handle paths with spaces and special characters on all platforms. Replace execSync rm/rmdir with fs.unlinkSync for stale symlink removal. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Drop installer script and AGENTS.md gatekeeper Testing showed native skill discovery works without the AGENTS.md gatekeeper — using-superpowers bootstraps itself via SKILL.md frontmatter. Install is now just clone + symlink, driven by INSTALL.md. No Node.js dependency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add Windows uninstall instructions and expand migration steps Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix stale Codex skills path in writing-skills SKILL.md ~/.codex/skills/ is deprecated; Codex uses ~/.agents/skills/ via native discovery. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Release v4.2.0: Windows fixes, Codex native skill discovery, worktree requirements * Fix stream-json output requiring --verbose flag Claude CLI now requires --verbose when using --output-format stream-json with -p (print mode). Without it, the test fails with: "Error: When using --print, --output-format=stream-json requires --verbose" * fix(writing-plans): use 4-backtick fence for nested code blocks in Task Structure template * Enforce brainstorming workflow with hard gates and process flow The brainstorming skill described a process but didn't enforce it. Models would skip the design phase and jump straight to implementation skills like frontend-design, or collapse the entire brainstorming process into a single text block. Changes to brainstorming skill: - Add HARD-GATE: no implementation until design is approved - Add explicit checklist that maps to task items - Add graphviz process flow with writing-plans as terminal state - Add anti-pattern callout for "too simple to need a design" - Scale design sections by section complexity, not project complexity - Make writing-plans the only valid next skill after brainstorming Changes to using-superpowers skill: - Add EnterPlanMode intercept to workflow graph - Route plan mode attempts through brainstorming skill instead Tested with claude -p --plugin-dir across three variants (no skill, original skill, updated skill) to verify behavioral compliance. * Make SessionStart hook synchronous so using-superpowers loads before first turn When async is true, the hook may not complete before the model starts responding, meaning the using-superpowers skill instructions aren't in context for the first message. * Release v4.3.0: Enforce brainstorming workflow, prevent unintended plan mode * Add Cursor plugin manifest and hook response compatibility Enable native Cursor plugin discovery with a .cursor-plugin manifest, and make the SessionStart hook emit both Cursor and Claude response shapes so context injection works across both platforms. Document Cursor install usage in the README while keeping Claude-first wording. Co-authored-by: Cursor <cursoragent@cursor.com> * update 'Verify Installation' section 'Verify Installation' section with updated instructions. * feat: Add local project scope support to Codex CLI Enable .codex/skills/ directory for project-local skills with three-tier resolution (project > personal > superpowers) and explicit namespace prefixes (project:, superpowers-ng:). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * feat: Adopt upstream native Codex skill discovery architecture Replace the custom bootstrap CLI (superpowers-codex, 267 lines) with upstream's native Codex skill discovery via ~/.agents/skills/ symlink. Deleted: - .codex/superpowers-codex (custom Node.js CLI) - .codex/superpowers-bootstrap.md (bootstrap content) - .opencode/plugin/superpowers.js (old singular path, replaced by plugins/) - lib/skills-core.js (shared module, no longer needed) Preserved: - Project-local skills via .codex/skills/ (three-tier priority documented) - Manus planning compatibility (3-file system, PreToolUse hooks) - Ralph integration (autonomous mode, design detection, loop persistence) - superpowers-ng branding throughout The native discovery approach is simpler (zero Node.js dependency), more maintainable, and future-proof as Codex improves its skill system. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Joshua Shanks <jjshanks@gmail.com> Co-authored-by: Vinicius da Motta <viniciusmotta8@gmail.com> Co-authored-by: oribi <oribarilan@gmail.com> Co-authored-by: Jesse Vincent <jesse@fsck.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Daniel E. <daniel.e@teachingstrategies.com> Co-authored-by: CL Kao <clkao@datarecce.io> Co-authored-by: Drew Ritter <drew@ritter.dev> Co-authored-by: chengfei.jin <chengfei.jin@infaith.com.cn> Co-authored-by: coltwindy <coltwindy@gmail.com> Co-authored-by: ericzakariasson <eric@anysphere.co> Co-authored-by: Cursor <cursoragent@cursor.com>
Update all references from upstream obra/superpowers to the forked OniReimu/superpowers-ng repository across installation guides, documentation, and plugin manifests. - Update GitHub URLs in .claude-plugin/plugin.json and .cursor-plugin/plugin.json - Fix .cursor-plugin metadata (name, display name, description, author) - Update installation guide URLs in .codex/INSTALL.md, .opencode/INSTALL.md - Update docs/README.codex.md and docs/README.opencode.md with correct URLs - Update support/issues links in README.md and RELEASE-NOTES.md Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Update all local directory references to use superpowers-ng consistently: - ~/.codex/superpowers → ~/.codex/superpowers-ng - ~/.agents/skills/superpowers → ~/.agents/skills/superpowers-ng - ~/.config/opencode/superpowers → ~/.config/opencode/superpowers-ng - ~/.config/superpowers → ~/.config/superpowers-ng Affects install guides, docs, hooks, skills, and test scripts. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Fix upstream superpower path references to superpowers-ng
# Conflicts: # .claude-plugin/marketplace.json
Add comprehensive installation guides covering both global and project-local scopes. Includes submodule and local clone options, Windows instructions, and updated skill priority documentation. Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Add bootstrap steps for the superpowers-ng skill system across all three installation methods (global, submodule, and local clone). Includes bootstrap verification steps and updated uninstall procedures to remove bootstrap blocks from AGENTS.md. Updates migration guide for users transitioning from old bootstrap mechanism.
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughThe PR rebrands "Superpowers" to "Superpowers-NG" with Manus-style persistent planning for long-running tasks. Updates plugin manifests and installation flows across multiple platforms (Claude Code, Cursor, Codex, OpenCode), removes legacy CLI tools, introduces comprehensive Manus planning skills and Ralph integration documentation, and updates all skill namespace references and configuration paths throughout the codebase. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Poem
✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changes
This PR updates
.codex/INSTALL.mdto document the bootstrap setup required for Codex agents to automatically load the superpowers-ng skill system at conversation start. Unlike Claude Code (which uses hooks), Codex usesAGENTS.mdfor this purpose.Summary by CodeRabbit
New Features
Enhancements
Migration