Add local project scope support to Codex CLI#501
Closed
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>
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>
📝 WalkthroughWalkthroughThis PR renames the plugin from "superpowers" to "superpowers-ng" and introduces a Manus-based persistent planning system for multi-session task management, Ralph autonomous loop integration, PreToolUse hooks, and extensive documentation. Version changes to 0.1.0 with updated authorship metadata. All skill identifiers transition to the new "superpowers-ng:" namespace. Changes
Sequence DiagramssequenceDiagram
participant User
participant Claude
participant PreToolUse Hook
participant Manus Files
participant Skill
User->>Claude: Request task execution
Claude->>PreToolUse Hook: Write/Edit/Bash tool triggered
PreToolUse Hook->>Manus Files: Check docs/manus/.active marker
alt Manus Active
PreToolUse Hook->>Manus Files: Read first 30 lines of task_plan.md
Manus Files-->>PreToolUse Hook: Return plan content
PreToolUse Hook-->>Claude: Inject plan preview in additionalContext
else Manus Inactive
PreToolUse Hook-->>Claude: Return empty JSON object
end
Claude->>Skill: Execute with injected context
Skill->>Manus Files: Update progress.md with phase status
Skill->>Manus Files: Log decisions in findings.md
Skill-->>User: Return execution result
sequenceDiagram
participant Designer as Designer (Claude)
participant Brainstorming as Brainstorming Skill
participant Planning as Planning System
participant Native as Native Planning
participant Manus as Manus Planning
Designer->>Brainstorming: Request design phase
Brainstorming->>Brainstorming: Phase 0: Check existing designs
alt Design Exists
Brainstorming-->>Designer: Announce existing design
else Design Missing
Brainstorming->>Brainstorming: Phase 1-3: Brainstorm & design
end
Brainstorming->>Planning: User chooses planning system
Planning-->>Designer: Present native vs Manus options
Designer->>Native: Choose native planning
Native->>Native: Execute writing-plans skill
Designer->>Manus: Choose Manus planning
Manus->>Manus: Create task_plan.md, findings.md, progress.md
Manus->>Manus: Initialize .active marker
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
skills/finishing-a-development-branch/SKILL.md (1)
154-159:⚠️ Potential issue | 🟡 MinorQuick Reference table is inconsistent with the "optional cleanup" paradigm for Option 1.
The table shows "Keep Worktree =
-" for Option 1 (Merge Locally), implying automatic removal, while Step 5 now characterises all worktree cleanup as optional. Option 4 has the same discrepancy. Consider updating the table header or cell values to signal optionality (e.g., "(opt)" or "?"), or align the table with the directive at Line 134/191 once that is resolved.✏️ Suggested fix
-| Option | Merge | Push | Keep Worktree | Cleanup Branch | -|--------|-------|------|---------------|----------------| -| 1. Merge locally | ✓ | - | - | ✓ | -| 2. Create PR | - | ✓ | ✓ | - | -| 3. Keep as-is | - | - | ✓ | - | -| 4. Discard | - | - | - | ✓ (force) | +| Option | Merge | Push | Keep Worktree | Cleanup Branch | +|--------|-------|------|---------------|----------------| +| 1. Merge locally | ✓ | - | opt | ✓ | +| 2. Create PR | - | ✓ | ✓ | - | +| 3. Keep as-is | - | - | ✓ | - | +| 4. Discard | - | - | opt | ✓ (force) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/finishing-a-development-branch/SKILL.md` around lines 154 - 159, Update the Quick Reference table in SKILL.md so its "Keep Worktree" and "Cleanup Branch" cells reflect that cleanup is optional for Option 1 ("Merge locally") and Option 4 ("Discard") and match the Step 5 wording; specifically edit the table row entries for "Option 1. Merge locally" and "Option 4. Discard" under the "Keep Worktree" and "Cleanup Branch" columns to indicate optionality (for example use "✓ (opt)" or "?(opt)") or adjust the column headers to make optionality explicit so the table aligns with the optional cleanup guidance in the prose; ensure the symbols "Option 1", "Option 4", "Keep Worktree", and "Cleanup Branch" are the ones you modify..codex/INSTALL.md (1)
19-33:⚠️ Potential issue | 🟡 MinorDuplicate step number — two "3." entries exist.
The original step 3 (
Update ~/.codex/AGENTS.md, line 19) and the new optional step (line 28) are both numbered3.. This makes the installation guide ambiguous for users following numbered steps.📝 Proposed fix — renumber the optional step as 4.
3. **Update ~/.codex/AGENTS.md** to include this superpowers section: ... -3. **Optional: Create project-local skills directory** (for per-project skills): +4. **Optional: Create project-local skills directory** (for per-project skills): ```bash mkdir -p .codex/skills ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.codex/INSTALL.md around lines 19 - 33, Two steps are both numbered "3." in the INSTALL.md snippet (the "Update ~/.codex/AGENTS.md" step and the "Optional: Create project-local skills directory" step). Rename/renumber the optional step "Create project-local skills directory" to "4." (and update its heading text "Optional: Create project-local skills directory" and the following code block reference `mkdir -p .codex/skills`) so the ordered list is no longer ambiguous; ensure the sequence reads 3. then 4. in that section.docs/README.codex.md (1)
128-132:⚠️ Potential issue | 🟡 Minor"Consistent behavior across platforms" overstates parity for OpenCode.
lib/skills-core.js'sresolveSkillPathonly acceptssuperpowersDirandpersonalDir— it has noprojectDirparameter and noproject:prefix handling. The project tier is implemented exclusively in the Codex CLI viaprocess.cwd(). OpenCode users relying on the shared module therefore get two-tier resolution (personal > superpowers), not three-tier, making the "consistent behavior" claim misleading for project-scoped skills.Consider clarifying that project-tier resolution is Codex-CLI-specific:
-The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin, ensuring consistent behavior across platforms. +The Codex implementation uses the shared `skills-core` module (ES module format) for skill discovery and parsing. This is the same module used by the OpenCode plugin for personal and superpowers skill resolution. Project-scoped skill resolution (the `project:` prefix and `.codex/skills/` lookup) is implemented in the Codex CLI and is not available in OpenCode.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/README.codex.md` around lines 128 - 132, The README claim that the shared skills-core module provides "consistent behavior across platforms" is misleading because resolveSkillPath in lib/skills-core.js only accepts superpowersDir and personalDir (no projectDir or project: prefix), so project-tier resolution is implemented only in the Codex CLI via process.cwd(); update the README section "Shared Core Module" to explicitly state that resolveSkillPath provides two-tier resolution (personal > superpowers) and that three-tier project-scoped resolution (project:) is handled by the Codex CLI, referencing resolveSkillPath and the CLI's use of process.cwd() for project-tier behavior so readers know where project lookup is implemented and why OpenCode differs.
🧹 Nitpick comments (15)
docs/plans/2025-11-22-opencode-support-design.md (1)
39-41: Consider updating stalesuperpowersinstallation path references in this design doc.Lines 39–41 and the code sample at line 160 still reference
~/.config/opencode/superpowers/— the pre-rename path. Since the project has rebranded tosuperpowers-ng, these paths may now conflict with actual INSTALL.md instructions (updated in this PR). Keeping them in sync avoids confusion for contributors following this design doc.✏️ Suggested update to directory path references
- Core: `~/.config/opencode/superpowers/skills/` (or installed location) + Core: `~/.config/opencode/superpowers-ng/skills/` (or installed location) Personal: `~/.config/opencode/skills/` (shadows core skills)And in the plugin structure example:
- const superpowersDir = path.join(process.env.HOME, '.config/opencode/superpowers'); + const superpowersDir = path.join(process.env.HOME, '.config/opencode/superpowers-ng');🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/plans/2025-11-22-opencode-support-design.md` around lines 39 - 41, Update all stale path references of "~/.config/opencode/superpowers/" to the rebranded "~/.config/opencode/superpowers-ng/" (including the "Skill Directories" section and the plugin structure code sample that currently reference the old path) so the design doc matches the INSTALL.md; search for the literal string "superpowers/" and replace with "superpowers-ng/" and verify any related examples or variable names mention "superpowers" are renamed or annotated to avoid confusion (e.g., plugin structure example and any code blocks).tests/opencode/test-priority.sh (1)
189-195: Test 5 never fails — consider hardening the assertion or removing the test.The
elsebranch emits[INFO]withoutexit 1, so Test 5 always passes regardless of whatproject:priority-testactually returns outside of a project context. This means the test provides zero coverage guarantee for this scenario.Either assert the expected failure explicitly, or drop this test case to avoid the false confidence of a "passing" test:
🧪 Option A — assert failure when not in project context
if echo "$output" | grep -qi "not found\|error"; then echo " [PASS] project: prefix correctly fails when not in project context" else - echo " [INFO] project: prefix behavior outside project context may vary" + echo " [FAIL] project: prefix unexpectedly succeeded outside project context" + exit 1 fi🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/opencode/test-priority.sh` around lines 189 - 195, The current test uses the conditional that checks echo "$output" | grep -qi "not found\|error" but the else branch only logs an [INFO] message so Test 5 never fails; update the else branch to assert failure (e.g., echo " [FAIL] project: prefix did not fail outside project context" && exit 1) or remove the entire if/else block to avoid a useless passing test, keeping the check of the variable output and the grep pattern intact so the test actually fails when the expected error is not present.tests/claude-code/test-helpers.sh (1)
228-239:assert_valid_jsonintroduces an undocumentedpython3dependency not listed in project prerequisites.The project documentation (
.opencode/INSTALL.md) specifies Node.js as a prerequisite but does not mention python3. If python3 is unavailable in the test environment, this function silently reports[FAIL]with "Invalid JSON" for all inputs—a false negative with no diagnostic. Since Node.js is already an established dependency and used throughout the test suite (tests/opencode/test-skills-core.sh), using it here would be more consistent and remove the implicit undocumented dependency.♻️ Proposed refactor: use `node` instead of `python3`
assert_valid_json() { local json="$1" local test_name="${2:-test}" - if echo "$json" | python3 -c 'import json, sys; json.load(sys.stdin)' 2>/dev/null; then + if echo "$json" | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{try{JSON.parse(d)}catch(e){process.exit(1)}})" 2>/dev/null; then echo " [PASS] $test_name" return 0 else echo " [FAIL] $test_name" echo " Invalid JSON" return 1 fi }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/claude-code/test-helpers.sh` around lines 228 - 239, The assert_valid_json function currently calls python3, introducing an undocumented dependency; update it to use the existing Node.js runtime instead by invoking node to parse the JSON (use a short node -e script that reads stdin and JSON.parse) and surface parse errors in the failure output; also add a pre-check that node is available (or detect invocation failure) and print a clear diagnostic if node is missing so tests don't silently produce false negatives—refer to the assert_valid_json function when making these changes..codex/superpowers-codex (1)
196-212: Missing source log forforceSuperpowersbranch creates asymmetric UX.When
forceProjectis true (lines 202–212), the user sees a# Loading project skill:/# Source:message. TheforceSuperpowersbranch (lines 197–201) doesn't print any such message, so explicitly-namespaced superpowers skills load silently while project skills announce themselves.Consider adding matching log output for consistency:
Proposed fix
if (forceSuperpowers) { if (fs.existsSync(superpowersSkillsDir)) { const superpowersPath = path.join(superpowersSkillsDir, actualSkillPath); skillFile = findSkillFile(superpowersPath); + if (skillFile) { + console.log(`# Loading superpowers skill: superpowers-ng:${actualSkillPath}`); + console.log(`# Source: ${skillFile}`); + console.log(''); + } } } else if (forceProject) {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.codex/superpowers-codex around lines 196 - 212, The forceSuperpowers branch silently loads namespaced superpowers skills; add the same console logging used in the forceProject branch so behavior is symmetric: after computing superpowersPath and calling findSkillFile(superpowersPath) (variables: forceSuperpowers, superpowersSkillsDir, superpowersPath, actualSkillPath, skillFile, findSkillFile), if skillFile is truthy print the two lines matching project logs (e.g. "# Loading superpowers skill: superpowers-ng:actualSkillPath" and "# Source: ${skillFile}") and a blank line.tests/subagent-driven-dev/svelte-todo/scaffold.sh (1)
46-46: Namespace correctly updated; consider updating the--plugin-dirplaceholder too.The skill identifier is correctly updated to
superpowers-ng:subagent-driven-development. The--plugin-dir /path/to/superpowersplaceholder could be updated to/path/to/superpowers-ngfor full consistency, though it's just a placeholder the user replaces.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/subagent-driven-dev/svelte-todo/scaffold.sh` at line 46, Update the placeholder plugin directory in the echo'd Claude command for consistency: change the `--plugin-dir /path/to/superpowers` placeholder to `--plugin-dir /path/to/superpowers-ng` in the echoed string (the line that prints the claude command which references Plan: $TARGET_DIR/plan.md and the skill `superpowers-ng:subagent-driven-development`) so the namespace and plugin-dir placeholders match.tests/subagent-driven-dev/go-fractals/scaffold.sh (1)
45-45: Namespace correctly updated, consistent with svelte-todo scaffold.Same optional nit as the svelte-todo scaffold: the
--plugin-dir /path/to/superpowersplaceholder could also be updated to match the new name.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/subagent-driven-dev/go-fractals/scaffold.sh` at line 45, Update the placeholder plugin directory in the echo'd command to match the new package name; replace the hardcoded "--plugin-dir /path/to/superpowers" reference used in the scaffold line that prints the claude invocation (the echo containing TARGET_DIR/plan.md) with the new plugin-dir path consistent with the updated namespace so examples match the svelte-todo scaffold.docs/ralph-integration/PROMPT.template.md (1)
106-116: Add language identifiers to fenced code blocks for RALPH_STATUS examples.The markdownlint tool flags all status block examples (lines 106, 136, 149, 162, 288, 309, 330, 354, 371, 378, 383) as missing a language specifier (MD040). Since these blocks aren't a specific language, adding
textwould satisfy the linter and improve rendering in some Markdown processors.Example fix for the first status block
-``` +```text ---RALPH_STATUS---Apply similarly to all other status block fenced code blocks.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ralph-integration/PROMPT.template.md` around lines 106 - 116, Add a language identifier "text" to each fenced code block that contains the RALPH status examples (the blocks delimited by ---RALPH_STATUS--- and ---END_RALPH_STATUS---) so the linter (MD040) is satisfied; e.g., change ``` to ```text for every example block showing STATUS, TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS, WORK_TYPE, EXIT_SIGNAL and RECOMMENDATION (all occurrences of the RALPH status blocks).hooks/hooks.json (1)
14-24: Consider single-quoting the${CLAUDE_PLUGIN_ROOT}path to guard against spaces.The new
PreToolUsehook command uses the same escaped-double-quote pattern as the existingSessionStarthook. Per the project learning, when Claude Code expands${CLAUDE_PLUGIN_ROOT}before handing the command to the shell, single quotes are the preferred way to prevent word-splitting on paths with spaces (e.g.,C:\Users\Name With Spaces\...):♻️ Suggested quoting change
- "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh" + "command": "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' manus-pretool.sh"If you update this, apply the same fix to the
SessionStartcommand for consistency.Based on learnings: "single quotes around the variable are necessary because Claude Code expands variables before passing the command to the shell. The quotes protect against word splitting when the expanded path contains spaces."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@hooks/hooks.json` around lines 14 - 24, The PreToolUse hook command currently wraps ${CLAUDE_PLUGIN_ROOT} in escaped double-quotes; change it to use single quotes around the variable (i.e., "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd' manus-pretool.sh") to prevent word-splitting when the expanded path contains spaces, and make the same change to the SessionStart hook's command for consistency; update the JSON value for the "command" entry within the "PreToolUse" hook object (and the corresponding "SessionStart" command) so the variable is single-quoted.tests/claude-code/run-skill-tests.sh (1)
130-140:TIMEOUT_CMDis recomputed on every iteration; prefer an array for quoting safety.
command -vis invoked once per test even though the result never changes — hoist the detection block before the loop. The unquoted$TIMEOUT_CMDalso relies on word-splitting to work, which is shellcheck-flagged (SC2086); an array is the idiomatic fix.🔧 Proposed refactor
Move before the
forloop (around line 109) and replace the string variable with an array:+# Determine timeout command once, before the loop +TIMEOUT_CMD_ARGS=() +if command -v timeout >/dev/null 2>&1; then + TIMEOUT_CMD_ARGS=("timeout" "$TIMEOUT") +elif command -v gtimeout >/dev/null 2>&1; then + TIMEOUT_CMD_ARGS=("gtimeout" "$TIMEOUT") +fi + for test in "${tests[@]}"; do ... - # Check if timeout command is available - if command -v timeout >/dev/null 2>&1; then - TIMEOUT_CMD="timeout $TIMEOUT" - elif command -v gtimeout >/dev/null 2>&1; then - TIMEOUT_CMD="gtimeout $TIMEOUT" - else - TIMEOUT_CMD="" - fi - if [ "$VERBOSE" = true ]; then - if $TIMEOUT_CMD bash "$test_path"; then + if "${TIMEOUT_CMD_ARGS[@]}" bash "$test_path"; then ... - if output=$($TIMEOUT_CMD bash "$test_path" 2>&1); then + if output=$("${TIMEOUT_CMD_ARGS[@]}" bash "$test_path" 2>&1); then🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/claude-code/run-skill-tests.sh` around lines 130 - 140, Hoist the timeout detection out of the per-test loop and replace the string TIMEOUT_CMD with an array to avoid re-running command -v and to prevent word-splitting: run the detection once (check for timeout then gtimeout) and set TIMEOUT_CMD as an array (empty array if neither found), then when running tests use "${TIMEOUT_CMD[@]}" before bash "$test_path" (and keep VERBOSE checks as-is) so invocation is safe and only evaluated once.hooks/manus-pretool.sh (2)
24-44:escape_for_jsonis slow and omits required JSON control-character escaping.Two issues:
Performance: The character-by-character
for (( i=0; … ))loop iterates ~2 000 times for a 30-line plan and runs before every tool call. In a typical 100-call agent session this adds several seconds of overhead.Incomplete escaping: RFC 8259 §7 requires U+0000–U+001F control characters to be escaped as
\uXXXX. The function only handles\n,\r,\t, so a plan file containing any other control character produces technically invalid JSON.Since Node.js is a hard dependency of this project, a one-liner covers both:
⚡ Proposed replacement (node-based)
-# Escape content for JSON using pure bash -escape_for_json() { - local input="$1" - local output="" - local i char - for (( i=0; i<${`#input`}; i++ )); do - char="${input:$i:1}" - case "$char" in - $'\\') output+='\\';; - '"') output+='\"';; - $'\n') output+='\n';; - $'\r') output+='\r';; - $'\t') output+='\t';; - *) output+="$char";; - esac - done - printf '%s' "$output" -} - -# Read first 30 lines of task_plan.md -plan_preview=$(head -30 "$PLAN_FILE" 2>/dev/null || echo "Error reading plan file") -plan_escaped=$(escape_for_json "$plan_preview") +# Read first 30 lines and JSON-encode using node (required by this project) +plan_escaped=$(head -30 "$PLAN_FILE" 2>/dev/null \ + | node -e "let s='';process.stdin.on('data',d=>s+=d);process.stdin.on('end',()=>process.stdout.write(JSON.stringify(s).slice(1,-1)))" \ + 2>/dev/null || echo "Error reading plan file")If
jqis available in the environment, that's even simpler:head -30 "$PLAN_FILE" | jq -Rs '.[:-1]'.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@hooks/manus-pretool.sh` around lines 24 - 44, The current escape_for_json function is slow and misses RFC8259 control-character escapes; replace its use by piping the plan preview through a JSON-safe encoder instead of the per-character bash loop: read the first 30 lines into plan_preview as you do, then produce plan_escaped by running that content through a Node.js one-liner (or jq -Rs if available) to produce a properly escaped JSON string (handling U+0000–U+001F as \uXXXX); update places that reference escape_for_json, remove the escape_for_json function, and ensure plan_escaped is assigned from the Node/jq command output so downstream consumers get valid JSON.
7-9: Misleading comment:PWDis the project root, not the plugin directory.Claude Code PreToolUse hooks run with
PWDset to the user's project root (whereclaudewas started). The comment "The hook runs from the plugin directory" suggests uncertainty, butPWDis the correct value to use here. Clarifying the comment prevents future confusion:📝 Proposed fix
-# Get the working directory (where the user's project is) -# The hook runs from the plugin directory, so we need to find the actual working directory -WORKING_DIR="${PWD}" +# Working directory is the user's project root — Claude Code sets PWD accordingly for hooks +WORKING_DIR="${PWD}"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@hooks/manus-pretool.sh` around lines 7 - 9, Update the misleading comment around WORKING_DIR: clarify that PWD is the user's project root (where claude was started) and not the plugin directory, remove the sentence "The hook runs from the plugin directory", and note that WORKING_DIR="${PWD}" intentionally captures the project root; update the comment immediately above the WORKING_DIR assignment to reflect this correct behavior.tests/opencode/test-tools.sh (1)
39-39:grep -qiwith\|is not portable — fails silently on macOS (BSD grep).
\|is a GNU grep BRE extension. BSD grep (the default on macOS) treats\|as a literal pipe character, so the alternation never matches and this check silently fails on any macOS runner.🔧 Proposed fix (use ERE with `-E`)
-if echo "$output" | grep -qi "superpowers-ng:brainstorming\|superpowers-ng:using-superpowers\|Available skills"; then +if echo "$output" | grep -Eqi "superpowers-ng:brainstorming|superpowers-ng:using-superpowers|Available skills"; then🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/opencode/test-tools.sh` at line 39, The grep command in the test uses the BRE alternation escape sequence (\|) which is a GNU extension and breaks on BSD grep (macOS); update the check that currently pipes into grep -qi "superpowers-ng:brainstorming\|superpowers-ng:using-superpowers\|Available skills" to use an ERE-based invocation (grep -E -i or egrep -i) so the alternation works portably, i.e., change the grep flags to use -E (or use multiple grep checks) in the test-tools.sh snippet.skills/manus-planning/examples.md (1)
164-166: Missing language specifier on fenced code block (MD040).📝 Proposed fix
- ``` + ```text I'm using the finishing-a-development-branch skill to complete this work. ```🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/manus-planning/examples.md` around lines 164 - 166, The fenced code block containing the line "I'm using the finishing-a-development-branch skill to complete this work." is missing a language specifier; update the opening fence from ``` to ```text to satisfy MD040 (e.g., change the block that begins with three backticks before that sentence to use ```text) so the code fence explicitly declares the language/format.tests/claude-code/test-manus-resume-integration.sh (1)
10-10: SC2064: use single quotes intrapto prevent premature expansion.With double quotes,
$TEST_PROJECTexpands immediately whentrapis registered. This happens to be safe here sinceTEST_PROJECTis already set and won't change, but it's non-idiomatic and shellcheck flags it.🔧 Proposed fix
-trap "cleanup_test_project $TEST_PROJECT" EXIT +trap 'cleanup_test_project "$TEST_PROJECT"' EXIT🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tests/claude-code/test-manus-resume-integration.sh` at line 10, The trap registration uses double quotes which expands $TEST_PROJECT immediately; change the trap to use single quotes so expansion happens when the trap runs (use trap with the command string quoted in single quotes and the variable quoted inside, targeting the existing trap call, the cleanup_test_project function, and the TEST_PROJECT variable).lib/skills-core.js (1)
103-111: Consider documenting thatresolveSkillPathdoes not handle theproject:prefix.The function only recognizes
superpowers-ng:as a special prefix. Both existing callers (.opencode/plugin/superpowers.jsand.codex/superpowers-codex) strip theproject:prefix locally before any call toresolveSkillPath, so in practice the function is safe from receivingproject:-prefixed names. However, sinceresolveSkillPathis exported and could be called directly, its JSDoc should clarify that it does not supportproject:prefix handling—or the function could be updated to handle all three prefix types (project:,superpowers-ng:, and no prefix) for consistency and future-proofing.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@lib/skills-core.js` around lines 103 - 111, Update the JSDoc for resolveSkillPath to explicitly state it only recognizes the "superpowers-ng:" prefix (and bare names) and does not handle a "project:" prefix, so callers must strip "project:" before calling; reference the resolveSkillPath function and mention existing callers (.opencode/plugin/superpowers.js and .codex/superpowers-codex) that already strip "project:" locally. If you prefer to change behavior instead, add handling for "project:" in resolveSkillPath by detecting a "project:" prefix, stripping it (similar to how "superpowers-ng:" is handled), and document the new supported prefixes in the JSDoc.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude-plugin/plugin.json:
- Around line 9-10: The homepage and repository fields in the plugin manifest
(.claude-plugin/plugin.json) currently point to a non-existent repo; update the
"homepage" and "repository" values to the actual fork's public URLs for the
superpowers-ng plugin (or remove those fields entirely if no public fork exists)
so the manifest reflects a valid reachable repository/location.
In @.codex/superpowers-codex:
- Around line 272-275: The displayName computation uses substring checks with
skillFile.includes(projectSkillsDir) and skillFile.includes(personalSkillsDir)
which can misclassify paths; change those to prefix checks using
skillFile.startsWith(projectSkillsDir) and
skillFile.startsWith(personalSkillsDir) (keeping the same conditional order and
variables forceSuperpowers, forceProject, actualSkillPath) so the source
detection relies on path prefixes rather than substrings.
In @.gitignore:
- Around line 1-4: The .gitignore update claimed to add a `.codex/skills/`
ignore pattern but the diff only added `**/CLAUDE.md`, so project-local skills
under `.codex/skills/` will be tracked; update the .gitignore to include an
entry for `.codex/skills/` (or `/.codex/skills/`/`**/.codex/skills/` as
appropriate for repo layout) so user-created skills are excluded, and verify the
pattern is not negated elsewhere and is documented in the PR description to
match the stated objective.
In `@docs/ralph-integration/README.md`:
- Around line 161-178: The "Status Format" block in README.md diverges from the
canonical PROMPT.template.md (wrong field names/order, wrong closing delimiter,
and invalid STATUS values); update the "Status Format" section to exactly match
PROMPT.template.md by replacing the current block that uses ---RALPH_STATUS--- /
---END_STATUS--- and fields PROGRESS/REMAINING/WORK_TYPE/STATUS with the
canonical block that begins with ---RALPH_STATUS---, uses the field order and
names: STATUS, TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS (values:
PASSING | FAILING | NOT_RUN), WORK_TYPE, EXIT_SIGNAL (false | true),
RECOMMENDATION, and ends with ---END_RALPH_STATUS---; ensure EXIT_SIGNAL rules
remain unchanged and remove the invalid STATUS value NOT_RUN from the STATUS
field so only STATUS: IN_PROGRESS | COMPLETE | BLOCKED is present.
In `@skills/brainstorming/SKILL.md`:
- Line 40: The phrase "multiple choice questions" in SKILL.md should use the
hyphenated compound modifier "multiple-choice questions"; update the text line
containing "Prefer multiple choice questions when possible, but open-ended is
fine too" to read "Prefer multiple-choice questions when possible, but
open-ended is fine too" so the compound modifier is grammatically correct.
In `@skills/finishing-a-development-branch/SKILL.md`:
- Around line 136-150: Update the contradictory guidance so Step 5 remains
optional: modify the "Red Flags → Always" rule that currently says "Clean up
worktree for Options 1 & 4 only" to a conditional instruction referencing the
Step 5 heading "Step 5: Optional Cleanup (Worktree Only)" (e.g., "If you used a
worktree for Options 1 & 4, remove it; otherwise skip cleanup") or move the
requirement into the Option-specific steps; ensure the phrasing aligns with the
optional language in "Step 5: Optional Cleanup (Worktree Only)" so the agent is
not forced to always remove worktrees.
In `@skills/manus-planning/SKILL.md`:
- Around line 48-55: The fenced code block that starts with "There's an active
manus task: "[goal from task_plan.md]"" and shows "Is your request:" is missing
a language specifier and is rendered as plain text; update the opening fence
from ``` to ```text so the block becomes ```text ... ``` to silence MD040 and
ensure proper markdownlint formatting.
In `@skills/manus-planning/templates/progress.md`:
- Around line 21-61: The markdown uses lone hyphens after the bold labels (e.g.,
"**Actions:**" and "**Files Modified:**" within Phase 2, Phase 3, Phase 4, and
Phase 5) which render as setext underlines; replace each lone "-" line with an
explicit list item (for example "- [What was done]" or "- [ ]") so they are
parsed as list items rather than setext headings; update the blocks under the
headings "Phase 2: Implementation", "Phase 3: Implementation", "Phase 4: Testing
& Verification", and "Phase 5: Delivery" to use that explicit list-item pattern
consistently.
In `@tests/claude-code/test-manus-pretool-hook.sh`:
- Line 10: The trap currently uses double quotes which expands $TEST_PROJECT at
trap-definition time; change the trap to use single quotes so the command runs
with $TEST_PROJECT expanded when the signal fires (e.g., update the trap line
referencing cleanup_test_project and TEST_PROJECT to use single-quoted command
string so ShellCheck SC2064 is avoided).
In `@tests/claude-code/test-manus-ralph-combined-integration.sh`:
- Line 85: The test assertion message for
assert_file_exists("$TEST_PROJECT/docs/manus/.active", ...) is misleading
because the .active file is created earlier in the test and the intent here is
to verify it still exists after the Claude run; update the second argument (the
assertion description) to something like "manus .active still exists (not
removed by Claude)" or "manus .active preserved after Claude run" so the
assertion reflects the actual check being performed.
- Line 10: Change the trap invocation to use single quotes to address SC2064:
update the existing trap that calls cleanup_test_project with the TEST_PROJECT
variable so the trap command string is wrapped in single quotes and the
$TEST_PROJECT value is expanded at trap setup (i.e., keep reference to the
cleanup_test_project function and the TEST_PROJECT variable but move the
variable expansion outside the single-quoted portion so the project name is
substituted when the trap is registered).
In `@tests/claude-code/test-ralph-status-emission-integration.sh`:
- Line 10: The trap currently expands TEST_PROJECT at definition time causing
SC2064; change the trap to defer expansion by using a single-quoted command
string so cleanup_test_project is called with the runtime value of TEST_PROJECT
(reference the existing trap line and the cleanup_test_project function and
TEST_PROJECT variable) — update the trap to use a quoted command like
'cleanup_test_project "$TEST_PROJECT"' so the variable is evaluated when the
EXIT signal runs.
---
Outside diff comments:
In @.codex/INSTALL.md:
- Around line 19-33: Two steps are both numbered "3." in the INSTALL.md snippet
(the "Update ~/.codex/AGENTS.md" step and the "Optional: Create project-local
skills directory" step). Rename/renumber the optional step "Create project-local
skills directory" to "4." (and update its heading text "Optional: Create
project-local skills directory" and the following code block reference `mkdir -p
.codex/skills`) so the ordered list is no longer ambiguous; ensure the sequence
reads 3. then 4. in that section.
In `@docs/README.codex.md`:
- Around line 128-132: The README claim that the shared skills-core module
provides "consistent behavior across platforms" is misleading because
resolveSkillPath in lib/skills-core.js only accepts superpowersDir and
personalDir (no projectDir or project: prefix), so project-tier resolution is
implemented only in the Codex CLI via process.cwd(); update the README section
"Shared Core Module" to explicitly state that resolveSkillPath provides two-tier
resolution (personal > superpowers) and that three-tier project-scoped
resolution (project:) is handled by the Codex CLI, referencing resolveSkillPath
and the CLI's use of process.cwd() for project-tier behavior so readers know
where project lookup is implemented and why OpenCode differs.
In `@skills/finishing-a-development-branch/SKILL.md`:
- Around line 154-159: Update the Quick Reference table in SKILL.md so its "Keep
Worktree" and "Cleanup Branch" cells reflect that cleanup is optional for Option
1 ("Merge locally") and Option 4 ("Discard") and match the Step 5 wording;
specifically edit the table row entries for "Option 1. Merge locally" and
"Option 4. Discard" under the "Keep Worktree" and "Cleanup Branch" columns to
indicate optionality (for example use "✓ (opt)" or "?(opt)") or adjust the
column headers to make optionality explicit so the table aligns with the
optional cleanup guidance in the prose; ensure the symbols "Option 1", "Option
4", "Keep Worktree", and "Cleanup Branch" are the ones you modify.
---
Nitpick comments:
In @.codex/superpowers-codex:
- Around line 196-212: The forceSuperpowers branch silently loads namespaced
superpowers skills; add the same console logging used in the forceProject branch
so behavior is symmetric: after computing superpowersPath and calling
findSkillFile(superpowersPath) (variables: forceSuperpowers,
superpowersSkillsDir, superpowersPath, actualSkillPath, skillFile,
findSkillFile), if skillFile is truthy print the two lines matching project logs
(e.g. "# Loading superpowers skill: superpowers-ng:actualSkillPath" and "#
Source: ${skillFile}") and a blank line.
In `@docs/plans/2025-11-22-opencode-support-design.md`:
- Around line 39-41: Update all stale path references of
"~/.config/opencode/superpowers/" to the rebranded
"~/.config/opencode/superpowers-ng/" (including the "Skill Directories" section
and the plugin structure code sample that currently reference the old path) so
the design doc matches the INSTALL.md; search for the literal string
"superpowers/" and replace with "superpowers-ng/" and verify any related
examples or variable names mention "superpowers" are renamed or annotated to
avoid confusion (e.g., plugin structure example and any code blocks).
In `@docs/ralph-integration/PROMPT.template.md`:
- Around line 106-116: Add a language identifier "text" to each fenced code
block that contains the RALPH status examples (the blocks delimited by
---RALPH_STATUS--- and ---END_RALPH_STATUS---) so the linter (MD040) is
satisfied; e.g., change ``` to ```text for every example block showing STATUS,
TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS, WORK_TYPE, EXIT_SIGNAL
and RECOMMENDATION (all occurrences of the RALPH status blocks).
In `@hooks/hooks.json`:
- Around line 14-24: The PreToolUse hook command currently wraps
${CLAUDE_PLUGIN_ROOT} in escaped double-quotes; change it to use single quotes
around the variable (i.e., "'${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd'
manus-pretool.sh") to prevent word-splitting when the expanded path contains
spaces, and make the same change to the SessionStart hook's command for
consistency; update the JSON value for the "command" entry within the
"PreToolUse" hook object (and the corresponding "SessionStart" command) so the
variable is single-quoted.
In `@hooks/manus-pretool.sh`:
- Around line 24-44: The current escape_for_json function is slow and misses
RFC8259 control-character escapes; replace its use by piping the plan preview
through a JSON-safe encoder instead of the per-character bash loop: read the
first 30 lines into plan_preview as you do, then produce plan_escaped by running
that content through a Node.js one-liner (or jq -Rs if available) to produce a
properly escaped JSON string (handling U+0000–U+001F as \uXXXX); update places
that reference escape_for_json, remove the escape_for_json function, and ensure
plan_escaped is assigned from the Node/jq command output so downstream consumers
get valid JSON.
- Around line 7-9: Update the misleading comment around WORKING_DIR: clarify
that PWD is the user's project root (where claude was started) and not the
plugin directory, remove the sentence "The hook runs from the plugin directory",
and note that WORKING_DIR="${PWD}" intentionally captures the project root;
update the comment immediately above the WORKING_DIR assignment to reflect this
correct behavior.
In `@lib/skills-core.js`:
- Around line 103-111: Update the JSDoc for resolveSkillPath to explicitly state
it only recognizes the "superpowers-ng:" prefix (and bare names) and does not
handle a "project:" prefix, so callers must strip "project:" before calling;
reference the resolveSkillPath function and mention existing callers
(.opencode/plugin/superpowers.js and .codex/superpowers-codex) that already
strip "project:" locally. If you prefer to change behavior instead, add handling
for "project:" in resolveSkillPath by detecting a "project:" prefix, stripping
it (similar to how "superpowers-ng:" is handled), and document the new supported
prefixes in the JSDoc.
In `@skills/manus-planning/examples.md`:
- Around line 164-166: The fenced code block containing the line "I'm using the
finishing-a-development-branch skill to complete this work." is missing a
language specifier; update the opening fence from ``` to ```text to satisfy
MD040 (e.g., change the block that begins with three backticks before that
sentence to use ```text) so the code fence explicitly declares the
language/format.
In `@tests/claude-code/run-skill-tests.sh`:
- Around line 130-140: Hoist the timeout detection out of the per-test loop and
replace the string TIMEOUT_CMD with an array to avoid re-running command -v and
to prevent word-splitting: run the detection once (check for timeout then
gtimeout) and set TIMEOUT_CMD as an array (empty array if neither found), then
when running tests use "${TIMEOUT_CMD[@]}" before bash "$test_path" (and keep
VERBOSE checks as-is) so invocation is safe and only evaluated once.
In `@tests/claude-code/test-helpers.sh`:
- Around line 228-239: The assert_valid_json function currently calls python3,
introducing an undocumented dependency; update it to use the existing Node.js
runtime instead by invoking node to parse the JSON (use a short node -e script
that reads stdin and JSON.parse) and surface parse errors in the failure output;
also add a pre-check that node is available (or detect invocation failure) and
print a clear diagnostic if node is missing so tests don't silently produce
false negatives—refer to the assert_valid_json function when making these
changes.
In `@tests/claude-code/test-manus-resume-integration.sh`:
- Line 10: The trap registration uses double quotes which expands $TEST_PROJECT
immediately; change the trap to use single quotes so expansion happens when the
trap runs (use trap with the command string quoted in single quotes and the
variable quoted inside, targeting the existing trap call, the
cleanup_test_project function, and the TEST_PROJECT variable).
In `@tests/opencode/test-priority.sh`:
- Around line 189-195: The current test uses the conditional that checks echo
"$output" | grep -qi "not found\|error" but the else branch only logs an [INFO]
message so Test 5 never fails; update the else branch to assert failure (e.g.,
echo " [FAIL] project: prefix did not fail outside project context" && exit 1)
or remove the entire if/else block to avoid a useless passing test, keeping the
check of the variable output and the grep pattern intact so the test actually
fails when the expected error is not present.
In `@tests/opencode/test-tools.sh`:
- Line 39: The grep command in the test uses the BRE alternation escape sequence
(\|) which is a GNU extension and breaks on BSD grep (macOS); update the check
that currently pipes into grep -qi
"superpowers-ng:brainstorming\|superpowers-ng:using-superpowers\|Available
skills" to use an ERE-based invocation (grep -E -i or egrep -i) so the
alternation works portably, i.e., change the grep flags to use -E (or use
multiple grep checks) in the test-tools.sh snippet.
In `@tests/subagent-driven-dev/go-fractals/scaffold.sh`:
- Line 45: Update the placeholder plugin directory in the echo'd command to
match the new package name; replace the hardcoded "--plugin-dir
/path/to/superpowers" reference used in the scaffold line that prints the claude
invocation (the echo containing TARGET_DIR/plan.md) with the new plugin-dir path
consistent with the updated namespace so examples match the svelte-todo
scaffold.
In `@tests/subagent-driven-dev/svelte-todo/scaffold.sh`:
- Line 46: Update the placeholder plugin directory in the echo'd Claude command
for consistency: change the `--plugin-dir /path/to/superpowers` placeholder to
`--plugin-dir /path/to/superpowers-ng` in the echoed string (the line that
prints the claude command which references Plan: $TARGET_DIR/plan.md and the
skill `superpowers-ng:subagent-driven-development`) so the namespace and
plugin-dir placeholders match.
Comment on lines
+9
to
+10
| "homepage": "https://github.com/OniReimu/superpowers", | ||
| "repository": "https://github.com/OniReimu/superpowers", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n .claude-plugin/plugin.jsonRepository: obra/superpowers
Length of output: 1110
🌐 Web query:
github OniReimu superpowers repository
💡 Result:
I couldn’t find a GitHub repository named superpowers owned by OniReimu.
The “Superpowers” repo people commonly mean is obra/superpowers (Claude Code superpowers / core skills library). (github.com)
https://github.com/obra/superpowers
Citations:
🌐 Web query:
github OniReimu superpowers-ng repository
💡 Result:
I couldn’t find any public GitHub repository named superpowers-ng under a user/org OniReimu, nor any page that matches “OniReimu superpowers-ng” in GitHub search results.
If you meant the well-known “Superpowers” repo for coding-agent workflows, that’s obra/superpowers. [1] (Unrelated: there’s also a separate superpowers GitHub organization for an archived HTML5 game maker.) [2]
What to check next
- Confirm the exact casing/spelling of the account name and repo name.
- The repo may be deleted, renamed, or private (won’t appear in public search).
Sources: [1], [2]
Homepage and repository URLs point to non-existent repositories.
The homepage and repository fields reference https://github.com/OniReimu/superpowers, but neither OniReimu/superpowers nor OniReimu/superpowers-ng exist as public repositories. Since the plugin name is superpowers-ng, update these URLs to point to the actual fork location, or remove them if the fork is not publicly available.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude-plugin/plugin.json around lines 9 - 10, The homepage and repository
fields in the plugin manifest (.claude-plugin/plugin.json) currently point to a
non-existent repo; update the "homepage" and "repository" values to the actual
fork's public URLs for the superpowers-ng plugin (or remove those fields
entirely if no public fork exists) so the manifest reflects a valid reachable
repository/location.
.codex/superpowers-codex
Outdated
Comment on lines
272
to
275
| const displayName = forceSuperpowers ? `superpowers-ng:${actualSkillPath}` : | ||
| forceProject ? `project:${actualSkillPath}` : | ||
| (skillFile.includes(projectSkillsDir) ? `project:${actualSkillPath}` : | ||
| skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers-ng:${actualSkillPath}`); |
There was a problem hiding this comment.
Use startsWith instead of includes for path-based source detection.
String.includes() performs a substring match, which can misidentify the skill source if one directory path is a substring of another (e.g., when CWD is the home directory, projectSkillsDir and personalSkillsDir would overlap). Using startsWith is the correct path-prefix check.
Proposed fix
- const displayName = forceSuperpowers ? `superpowers-ng:${actualSkillPath}` :
- forceProject ? `project:${actualSkillPath}` :
- (skillFile.includes(projectSkillsDir) ? `project:${actualSkillPath}` :
- skillFile.includes(personalSkillsDir) ? actualSkillPath : `superpowers-ng:${actualSkillPath}`);
+ const displayName = forceSuperpowers ? `superpowers-ng:${actualSkillPath}` :
+ forceProject ? `project:${actualSkillPath}` :
+ (skillFile.startsWith(projectSkillsDir) ? `project:${actualSkillPath}` :
+ skillFile.startsWith(personalSkillsDir) ? actualSkillPath : `superpowers-ng:${actualSkillPath}`);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.codex/superpowers-codex around lines 272 - 275, The displayName computation
uses substring checks with skillFile.includes(projectSkillsDir) and
skillFile.includes(personalSkillsDir) which can misclassify paths; change those
to prefix checks using skillFile.startsWith(projectSkillsDir) and
skillFile.startsWith(personalSkillsDir) (keeping the same conditional order and
variables forceSuperpowers, forceProject, actualSkillPath) so the source
detection relies on path prefixes rather than substrings.
Comment on lines
1
to
+4
| .worktrees/ | ||
| .private-journal/ | ||
| .claude/ | ||
| **/CLAUDE.md |
There was a problem hiding this comment.
Missing .codex/skills/ gitignore entry stated in PR objectives.
The PR description explicitly states ".gitignore: added .codex/skills/ pattern", but the only change present is **/CLAUDE.md. No existing rule covers .codex/skills/, so project-local skills will be tracked by git — users who create skills under .codex/skills/ will accidentally commit them unless they add their own ignore rule.
🛠️ Proposed fix
.worktrees/
.private-journal/
.claude/
+.codex/skills/
**/CLAUDE.md📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| .worktrees/ | |
| .private-journal/ | |
| .claude/ | |
| **/CLAUDE.md | |
| .worktrees/ | |
| .private-journal/ | |
| .claude/ | |
| .codex/skills/ | |
| **/CLAUDE.md |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.gitignore around lines 1 - 4, The .gitignore update claimed to add a
`.codex/skills/` ignore pattern but the diff only added `**/CLAUDE.md`, so
project-local skills under `.codex/skills/` will be tracked; update the
.gitignore to include an entry for `.codex/skills/` (or
`/.codex/skills/`/`**/.codex/skills/` as appropriate for repo layout) so
user-created skills are excluded, and verify the pattern is not negated
elsewhere and is documented in the PR description to match the stated objective.
Comment on lines
+161
to
+178
| ```markdown | ||
| ## Status Format | ||
|
|
||
| At the end of EVERY response, emit: | ||
|
|
||
| ---RALPH_STATUS--- | ||
| WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING | ||
| STATUS: IN_PROGRESS | COMPLETE | BLOCKED | NOT_RUN | ||
| PROGRESS: [What was accomplished this loop] | ||
| REMAINING: [Tasks left in @fix_plan.md] | ||
| EXIT_SIGNAL: true | false | ||
| ---END_STATUS--- | ||
|
|
||
| EXIT_SIGNAL = true ONLY when: | ||
| - All tasks in @fix_plan.md complete | ||
| - All Manus phases complete (if using manus-planning) | ||
| - Tests pass (verified via verification-before-completion) | ||
| ``` |
There was a problem hiding this comment.
Status block format is inconsistent with PROMPT.template.md — will confuse integrators.
The status emission format shown here diverges from the canonical format defined in PROMPT.template.md in multiple ways:
- Different fields: This shows
PROGRESSandREMAINING; the template usesTASKS_COMPLETED_THIS_LOOP,FILES_MODIFIED,TESTS_STATUS, andRECOMMENDATION. - Different closing delimiter:
---END_STATUS---here vs.---END_RALPH_STATUS---in the template. - Different field order:
WORK_TYPEappears first here;STATUSappears first in the template. - Invalid STATUS value:
NOT_RUNis listed as aSTATUSvalue here, but in the template it's aTESTS_STATUSvalue.
Since PROMPT.template.md is the authoritative reference that gets copied into projects, this section should match it exactly.
Proposed fix to align with PROMPT.template.md
### Status Emission
Ralph needs status at the end of every response:
```markdown
## Status Format
At the end of EVERY response, emit:
----RALPH_STATUS---
-WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
-STATUS: IN_PROGRESS | COMPLETE | BLOCKED | NOT_RUN
-PROGRESS: [What was accomplished this loop]
-REMAINING: [Tasks left in `@fix_plan.md`]
-EXIT_SIGNAL: true | false
----END_STATUS---
+---RALPH_STATUS---
+STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+TASKS_COMPLETED_THIS_LOOP: <number>
+FILES_MODIFIED: <number>
+TESTS_STATUS: PASSING | FAILING | NOT_RUN
+WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
+EXIT_SIGNAL: false | true
+RECOMMENDATION: <one line summary of what to do next>
+---END_RALPH_STATUS---
EXIT_SIGNAL = true ONLY when:
- All tasks in `@fix_plan.md` complete
- All Manus phases complete (if using manus-planning)
- Tests pass (verified via verification-before-completion)</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/ralph-integration/README.md around lines 161 - 178, The "Status Format"
block in README.md diverges from the canonical PROMPT.template.md (wrong field
names/order, wrong closing delimiter, and invalid STATUS values); update the
"Status Format" section to exactly match PROMPT.template.md by replacing the
current block that uses ---RALPH_STATUS--- / ---END_STATUS--- and fields
PROGRESS/REMAINING/WORK_TYPE/STATUS with the canonical block that begins with
---RALPH_STATUS---, uses the field order and names: STATUS,
TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS (values: PASSING |
FAILING | NOT_RUN), WORK_TYPE, EXIT_SIGNAL (false | true), RECOMMENDATION, and
ends with ---END_RALPH_STATUS---; ensure EXIT_SIGNAL rules remain unchanged and
remove the invalid STATUS value NOT_RUN from the STATUS field so only STATUS:
IN_PROGRESS | COMPLETE | BLOCKED is present.
</details>
<!-- fingerprinting:phantom:medusa:phoenix -->
<!-- This is an auto-generated comment by CodeRabbit -->
| **Phase 1: Understanding the idea** | ||
| - Check out the current project state first (files, docs, recent commits) | ||
| - Ask questions one at a time to refine the idea | ||
| - Prefer multiple choice questions when possible, but open-ended is fine too |
There was a problem hiding this comment.
Hyphenate "multiple-choice" as a compound modifier.
As flagged by LanguageTool: "multiple choice questions" → "multiple-choice questions".
✏️ Proposed fix
- - Prefer multiple choice questions when possible, but open-ended is fine too
+ - Prefer multiple-choice questions when possible, but open-ended is fine too📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - Prefer multiple choice questions when possible, but open-ended is fine too | |
| - Prefer multiple-choice questions when possible, but open-ended is fine too |
🧰 Tools
🪛 LanguageTool
[grammar] ~40-~40: Use a hyphen to join words.
Context: ...ime to refine the idea - Prefer multiple choice questions when possible, but open...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/brainstorming/SKILL.md` at line 40, The phrase "multiple choice
questions" in SKILL.md should use the hyphenated compound modifier
"multiple-choice questions"; update the text line containing "Prefer multiple
choice questions when possible, but open-ended is fine too" to read "Prefer
multiple-choice questions when possible, but open-ended is fine too" so the
compound modifier is grammatically correct.
Comment on lines
+21
to
+61
| **Actions:** | ||
| - | ||
|
|
||
| **Files Modified:** | ||
| - | ||
|
|
||
| --- | ||
|
|
||
| ### Phase 3: Implementation | ||
| **Status:** pending | ||
| **Started:** | ||
|
|
||
| **Actions:** | ||
| - | ||
|
|
||
| **Files Modified:** | ||
| - | ||
|
|
||
| --- | ||
|
|
||
| ### Phase 4: Testing & Verification | ||
| **Status:** pending | ||
| **Started:** | ||
|
|
||
| **Actions:** | ||
| - | ||
|
|
||
| **Files Modified:** | ||
| - | ||
|
|
||
| --- | ||
|
|
||
| ### Phase 5: Delivery | ||
| **Status:** pending | ||
| **Started:** | ||
|
|
||
| **Actions:** | ||
| - | ||
|
|
||
| **Files Modified:** | ||
| - |
There was a problem hiding this comment.
Bare - placeholders are interpreted as setext heading underlines, not list items.
In Phases 2–5, **Actions:** and **Files Modified:** followed by a lone - on the next line match CommonMark's setext level-2 heading rule. This turns the bold-text labels into actual Markdown headings, explaining the MD003 and MD024 warnings from markdownlint.
Phase 1 already avoids this by using - [What was done] — apply the same pattern to the remaining phases.
📝 Proposed fix (Phase 2; repeat for Phases 3–5)
**Actions:**
--
+- [action]
**Files Modified:**
--
+- [filename]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| **Actions:** | |
| - | |
| **Files Modified:** | |
| - | |
| --- | |
| ### Phase 3: Implementation | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - | |
| **Files Modified:** | |
| - | |
| --- | |
| ### Phase 4: Testing & Verification | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - | |
| **Files Modified:** | |
| - | |
| --- | |
| ### Phase 5: Delivery | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - | |
| **Files Modified:** | |
| - | |
| **Actions:** | |
| - [action] | |
| **Files Modified:** | |
| - [filename] | |
| --- | |
| ### Phase 3: Implementation | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - [action] | |
| **Files Modified:** | |
| - [filename] | |
| --- | |
| ### Phase 4: Testing & Verification | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - [action] | |
| **Files Modified:** | |
| - [filename] | |
| --- | |
| ### Phase 5: Delivery | |
| **Status:** pending | |
| **Started:** | |
| **Actions:** | |
| - [action] | |
| **Files Modified:** | |
| - [filename] |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 21-21: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 24-24: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 33-33: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 33-33: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 36-36: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 36-36: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 45-45: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 45-45: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 48-48: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 48-48: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 57-57: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 57-57: Multiple headings with the same content
(MD024, no-duplicate-heading)
[warning] 60-60: Heading style
Expected: atx; Actual: setext
(MD003, heading-style)
[warning] 60-60: Multiple headings with the same content
(MD024, no-duplicate-heading)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/manus-planning/templates/progress.md` around lines 21 - 61, The
markdown uses lone hyphens after the bold labels (e.g., "**Actions:**" and
"**Files Modified:**" within Phase 2, Phase 3, Phase 4, and Phase 5) which
render as setext underlines; replace each lone "-" line with an explicit list
item (for example "- [What was done]" or "- [ ]") so they are parsed as list
items rather than setext headings; update the blocks under the headings "Phase
2: Implementation", "Phase 3: Implementation", "Phase 4: Testing &
Verification", and "Phase 5: Delivery" to use that explicit list-item pattern
consistently.
| echo "=== Test: manus pretool hook ===" | ||
|
|
||
| TEST_PROJECT=$(create_test_project) | ||
| trap "cleanup_test_project $TEST_PROJECT" EXIT |
There was a problem hiding this comment.
Fix trap quoting to avoid SC2064.
With double quotes, $TEST_PROJECT expands immediately at trap definition time rather than when the signal fires. While safe here since TEST_PROJECT is assigned on the immediately preceding line and never reassigned, it's best practice (and suppresses the ShellCheck SC2064 warning) to use single quotes:
🛠️ Proposed fix
-trap "cleanup_test_project $TEST_PROJECT" EXIT
+trap 'cleanup_test_project "$TEST_PROJECT"' EXIT📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| trap "cleanup_test_project $TEST_PROJECT" EXIT | |
| trap 'cleanup_test_project "$TEST_PROJECT"' EXIT |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 10-10: Use single quotes, otherwise this expands now rather than when signalled.
(SC2064)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/claude-code/test-manus-pretool-hook.sh` at line 10, The trap currently
uses double quotes which expands $TEST_PROJECT at trap-definition time; change
the trap to use single quotes so the command runs with $TEST_PROJECT expanded
when the signal fires (e.g., update the trap line referencing
cleanup_test_project and TEST_PROJECT to use single-quoted command string so
ShellCheck SC2064 is avoided).
| echo "=== Integration Test: manus + ralph combined ===" | ||
|
|
||
| TEST_PROJECT=$(create_test_project) | ||
| trap "cleanup_test_project $TEST_PROJECT" EXIT |
There was a problem hiding this comment.
Use single quotes in trap to satisfy SC2064.
$TEST_PROJECT is set on the previous line and doesn't change, so the double-quoted form is functionally safe here, but single quotes are the idiomatic fix for the SC2064 warning and better communicate intent.
🛠️ Proposed fix
-trap "cleanup_test_project $TEST_PROJECT" EXIT
+trap 'cleanup_test_project "$TEST_PROJECT"' EXIT📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| trap "cleanup_test_project $TEST_PROJECT" EXIT | |
| trap 'cleanup_test_project "$TEST_PROJECT"' EXIT |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 10-10: Use single quotes, otherwise this expands now rather than when signalled.
(SC2064)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/claude-code/test-manus-ralph-combined-integration.sh` at line 10,
Change the trap invocation to use single quotes to address SC2064: update the
existing trap that calls cleanup_test_project with the TEST_PROJECT variable so
the trap command string is wrapped in single quotes and the $TEST_PROJECT value
is expanded at trap setup (i.e., keep reference to the cleanup_test_project
function and the TEST_PROJECT variable but move the variable expansion outside
the single-quoted portion so the project name is substituted when the trap is
registered).
| exit 0 | ||
| fi | ||
|
|
||
| assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active created" |
There was a problem hiding this comment.
Test assertion name is misleading — .active was pre-created, not created by Claude.
The .active file is explicitly created at line 46. The assertion on line 85 verifies it still exists after the Claude run (i.e., Claude didn't remove it prematurely), not that it was created. The test name should reflect that.
🛠️ Proposed fix
-assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active created"
+assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active preserved while task still active"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active created" | |
| assert_file_exists "$TEST_PROJECT/docs/manus/.active" "manus .active preserved while task still active" |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/claude-code/test-manus-ralph-combined-integration.sh` at line 85, The
test assertion message for
assert_file_exists("$TEST_PROJECT/docs/manus/.active", ...) is misleading
because the .active file is created earlier in the test and the intent here is
to verify it still exists after the Claude run; update the second argument (the
assertion description) to something like "manus .active still exists (not
removed by Claude)" or "manus .active preserved after Claude run" so the
assertion reflects the actual check being performed.
| echo "=== Integration Test: Ralph status emission ===" | ||
|
|
||
| TEST_PROJECT=$(create_test_project) | ||
| trap "cleanup_test_project $TEST_PROJECT" EXIT |
There was a problem hiding this comment.
Same SC2064 trap issue as test-manus-ralph-combined-integration.sh.
🛠️ Proposed fix
-trap "cleanup_test_project $TEST_PROJECT" EXIT
+trap 'cleanup_test_project "$TEST_PROJECT"' EXIT📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| trap "cleanup_test_project $TEST_PROJECT" EXIT | |
| trap 'cleanup_test_project "$TEST_PROJECT"' EXIT |
🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 10-10: Use single quotes, otherwise this expands now rather than when signalled.
(SC2064)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@tests/claude-code/test-ralph-status-emission-integration.sh` at line 10, The
trap currently expands TEST_PROJECT at definition time causing SC2064; change
the trap to defer expansion by using a single-quoted command string so
cleanup_test_project is called with the runtime value of TEST_PROJECT (reference
the existing trap line and the cleanup_test_project function and TEST_PROJECT
variable) — update the trap to use a quoted command like 'cleanup_test_project
"$TEST_PROJECT"' so the variable is evaluated when the EXIT signal runs.
Merged upstream obra/superpowers v4.1.0-v4.3.0 changes while preserving all fork-specific features: Manus planning, Ralph integration, superpowers-ng branding, and Codex local scope with three-tier skill priority. Upstream features adopted: - Brainstorming hard gates, checklist, graphviz process flow (v4.3.0) - EnterPlanMode intercept in using-superpowers (v4.3.0) - O(n^2) escape_for_json perf fix (7x faster) - Cursor plugin manifest and dual-shape hook JSON compatibility - .gitattributes for LF line endings (Windows CRLF fix) - Worktree requirement for subagent-driven-development - SessionStart hook synchronous mode - writing-plans nested code fence fix - OpenCode native skills, Windows docs, plugins/ directory - Test improvements (case sensitivity, verbose flag) Fork features preserved: - Manus planning system (Phase 0 check, planning choice) - Ralph autonomous loop integration - superpowers-ng: namespace prefixes throughout - Codex bootstrap CLI with three-tier resolution - .codex/superpowers-codex and .codex/superpowers-bootstrap.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 6
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
skills/executing-plans/SKILL.md (1)
82-84:⚠️ Potential issue | 🟡 MinorIntegration section still uses the old
superpowers:namespace — inconsistent with the change on Line 49.All three references in this section were not migrated to
superpowers-ng:, includingfinishing-a-development-branchwhich is the exact same skill already updated on Line 49. With the new prefix-based resolution, these stale references will either silently route to the wrong tier or fail to resolve.📝 Proposed fix
## Integration **Required workflow skills:** -- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting -- **superpowers:writing-plans** - Creates the plan this skill executes -- **superpowers:finishing-a-development-branch** - Complete development after all tasks +- **superpowers-ng:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting +- **superpowers-ng:writing-plans** - Creates the plan this skill executes +- **superpowers-ng:finishing-a-development-branch** - Complete development after all tasks🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/executing-plans/SKILL.md` around lines 82 - 84, The integration section still uses the old prefix "superpowers:" for the skill references; update each reference to use the new "superpowers-ng:" prefix so they match the migrated entry (e.g., change "superpowers:using-git-worktrees", "superpowers:writing-plans", and "superpowers:finishing-a-development-branch" to "superpowers-ng:using-git-worktrees", "superpowers-ng:writing-plans", and "superpowers-ng:finishing-a-development-branch"); ensure exact skill slugs are preserved and that the updated references follow the same prefix-based resolution pattern used elsewhere (as on the already-updated finishing-a-development-branch).RELEASE-NOTES.md (1)
37-37:⚠️ Potential issue | 🟡 MinorClarify the distinction between the deprecated
~/.codex/skills/path and the new project-local.codex/skills/when documenting the feature.Line 37 (Upstream v4.2.0) explicitly deprecates
~/.codex/skills/(absolute, home-directory path). The project-local.codex/skills/introduced by this PR is a relative path in the project root — an entirely different mechanism — but shares the same directory name. Without a callout in the release notes, readers may incorrectly conclude the new feature is also deprecated.When the missing feature entry (see prior comment) is added, include a note such as: "Not to be confused with the deprecated
~/.codex/skills/user-global path — this is a project-relative.codex/skills/directory."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@RELEASE-NOTES.md` at line 37, Update the release note sentence about deprecating ~/.codex/skills to explicitly distinguish it from the new project-local .codex/skills directory: edit the Upstream v4.2.0 release entry text to add a short clarifying sentence such as "Not to be confused with the deprecated ~/.codex/skills/ user-global path — this refers to a project-relative .codex/skills/ directory" so readers know the new project-local mechanism is not deprecated; ensure you modify the same release note paragraph that mentions "~/.codex/skills/" and add the clarification immediately after that clause.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/README.codex.md`:
- Around line 65-69: Add a language specifier to the fenced code blocks showing
the CLI examples: change the opening fences for the block containing "Run
~/.codex/superpowers/.codex/superpowers-codex find-skills" (and the subsequent
"use-skill superpowers-ng:brainstorming" and "bootstrap" lines) and the block
containing "Run ~/.codex/superpowers/.codex/superpowers-codex use-skill
project:my-project-skill" from ``` to ```text so the linter recognizes them as
plaintext code blocks.
- Line 123: The docs show a mismatch between the tier label "superpowers" in the
Skill Priority sentence and the namespace prefix "superpowers-ng:" used in the
use-skill example; make them consistent by renaming either the tier label to
"superpowers-ng" or the example prefix to "superpowers:" so the folder path,
tier name, and namespace prefix align (update the Skill Priority phrase that
mentions "~/.codex/superpowers/skills/" and/or the use-skill example that uses
"superpowers-ng:" to the chosen canonical name across the document).
In `@hooks/hooks.json`:
- Around line 15-24: The PreToolUse hook definition (the object with "matcher":
"Write|Edit|Bash" and the nested "hooks" array containing the command
"\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh") is missing
"async": true; add "async": true to that hook object so the hook runs
asynchronously on Windows (preventing event-loop hang) while leaving the
existing command and matcher unchanged.
In `@README.md`:
- Line 222: The README has mismatched repository names: the Issues link
"https://github.com/OniReimu/superpowers/issues" does not match the clone URL
referencing "OniReimu/superpowers-ng"; update one so both use the same repo name
— either change the Issues URL to
"https://github.com/OniReimu/superpowers-ng/issues" to match the clone URL, or
change the clone URL string "OniReimu/superpowers-ng" to "OniReimu/superpowers"
so both links are consistent; ensure the two strings in the README are identical
and point to the actual GitHub repository.
- Around line 68-70: Replace the forked clone URL in the README (the line
containing "git clone https://github.com/OniReimu/superpowers-ng.git") with the
upstream repository URL for this PR (e.g. "git clone
https://github.com/obra/superpowers.git") so users clone the correct upstream
repo; update the following line "cd superpowers-ng" if the cloned directory name
differs (e.g. "cd superpowers") to keep commands consistent.
In `@RELEASE-NOTES.md`:
- Around line 145-352: Add documentation for the project-local skill scope
feature to the release notes by creating a short New Feature subsection that
explains the three-tier skill resolution (project → personal → superpowers-ng),
the new project-local skill directory (.codex/skills/), the explicit namespace
prefixes project: and superpowers-ng:, and the project-tier detection via
process.cwd(); place this under the v0.1.0 New Features (or as a v0.2.0 entry if
you prefer a follow-up release), include concise usage examples for invoking
namespaced skills and the resolution order, and update the "What's Next" list to
remove or adjust items that now ship with this change.
---
Outside diff comments:
In `@RELEASE-NOTES.md`:
- Line 37: Update the release note sentence about deprecating ~/.codex/skills to
explicitly distinguish it from the new project-local .codex/skills directory:
edit the Upstream v4.2.0 release entry text to add a short clarifying sentence
such as "Not to be confused with the deprecated ~/.codex/skills/ user-global
path — this refers to a project-relative .codex/skills/ directory" so readers
know the new project-local mechanism is not deprecated; ensure you modify the
same release note paragraph that mentions "~/.codex/skills/" and add the
clarification immediately after that clause.
In `@skills/executing-plans/SKILL.md`:
- Around line 82-84: The integration section still uses the old prefix
"superpowers:" for the skill references; update each reference to use the new
"superpowers-ng:" prefix so they match the migrated entry (e.g., change
"superpowers:using-git-worktrees", "superpowers:writing-plans", and
"superpowers:finishing-a-development-branch" to
"superpowers-ng:using-git-worktrees", "superpowers-ng:writing-plans", and
"superpowers-ng:finishing-a-development-branch"); ensure exact skill slugs are
preserved and that the updated references follow the same prefix-based
resolution pattern used elsewhere (as on the already-updated
finishing-a-development-branch).
---
Duplicate comments:
In `@skills/brainstorming/SKILL.md`:
- Line 90: Update the phrase "multiple choice questions" to the hyphenated
compound modifier "multiple-choice questions" in the line containing the
sentence "Prefer multiple choice questions when possible, but open-ended is fine
too" so it reads "Prefer multiple-choice questions when possible, but open-ended
is fine too".
Comment on lines
+15
to
+24
| "PreToolUse": [ | ||
| { | ||
| "matcher": "Write|Edit|Bash", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh" | ||
| } | ||
| ] | ||
| } |
There was a problem hiding this comment.
Missing "async": true risks a hang on Windows
The new PreToolUse hook omits the async field, making it synchronous (the default). Official plugin hooks missing async: true cause Claude Code to hang on Windows, because Windows requires active polling of subprocess handles and the event loop hasn't started yet during synchronous hook init — so the subprocess completion signal is never received.
This hook injects context rather than making permission decisions (allow/deny/block), so there is no functional reason for it to be synchronous — adding "async": true is safe and correct. After the background process exits, any JSON response containing additionalContext is delivered to Claude as context on the next conversation turn, which is sufficient for this hook's purpose.
🔧 Proposed fix
{
"type": "command",
- "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh"
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh",
+ "async": true
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "PreToolUse": [ | |
| { | |
| "matcher": "Write|Edit|Bash", | |
| "hooks": [ | |
| { | |
| "type": "command", | |
| "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh" | |
| } | |
| ] | |
| } | |
| { | |
| "type": "command", | |
| "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh", | |
| "async": true | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@hooks/hooks.json` around lines 15 - 24, The PreToolUse hook definition (the
object with "matcher": "Write|Edit|Bash" and the nested "hooks" array containing
the command "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" manus-pretool.sh") is
missing "async": true; add "async": true to that hook object so the hook runs
asynchronously on Windows (preventing event-loop hang) while leaving the
existing command and matcher unchanged.
Comment on lines
+68
to
+70
| # Clone the repository | ||
| git clone https://github.com/OniReimu/superpowers-ng.git | ||
| cd superpowers-ng |
There was a problem hiding this comment.
Clone URL points to the fork, not the upstream repo this PR targets.
The manual installation step directs users to OniReimu/superpowers-ng.git, but this PR is being merged into obra/superpowers. After merge, users would be cloning the fork instead of the repository they actually installed from.
📝 Proposed fix (if intent is to always point to the upstream)
-git clone https://github.com/OniReimu/superpowers-ng.git
-cd superpowers-ng
+git clone https://github.com/obra/superpowers.git
+cd superpowers📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Clone the repository | |
| git clone https://github.com/OniReimu/superpowers-ng.git | |
| cd superpowers-ng | |
| # Clone the repository | |
| git clone https://github.com/obra/superpowers.git | |
| cd superpowers |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 68 - 70, Replace the forked clone URL in the README
(the line containing "git clone https://github.com/OniReimu/superpowers-ng.git")
with the upstream repository URL for this PR (e.g. "git clone
https://github.com/obra/superpowers.git") so users clone the correct upstream
repo; update the following line "cd superpowers-ng" if the cloned directory name
differs (e.g. "cd superpowers") to keep commands consistent.
|
|
||
| - **Issues**: https://github.com/obra/superpowers/issues | ||
| - **Marketplace**: https://github.com/obra/superpowers-marketplace | ||
| - **Issues**: https://github.com/OniReimu/superpowers/issues |
There was a problem hiding this comment.
Issues URL repo name doesn't match the clone URL.
Line 222 links to OniReimu/superpowers/issues, but the clone URL at Line 69 references OniReimu/superpowers-ng. One of the two is wrong — this will produce a 404 for users trying to file bugs.
📝 Proposed fix (if fork URLs are intentional)
-- **Issues**: https://github.com/OniReimu/superpowers/issues
+- **Issues**: https://github.com/OniReimu/superpowers-ng/issues📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Issues**: https://github.com/OniReimu/superpowers/issues | |
| - **Issues**: https://github.com/OniReimu/superpowers-ng/issues |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 222, The README has mismatched repository names: the
Issues link "https://github.com/OniReimu/superpowers/issues" does not match the
clone URL referencing "OniReimu/superpowers-ng"; update one so both use the same
repo name — either change the Issues URL to
"https://github.com/OniReimu/superpowers-ng/issues" to match the clone URL, or
change the clone URL string "OniReimu/superpowers-ng" to "OniReimu/superpowers"
so both links are consistent; ensure the two strings in the README are identical
and point to the actual GitHub repository.
Comment on lines
+145
to
+352
| ## v0.1.0 (2026-01-13) | ||
|
|
||
| ### Improvements | ||
|
|
||
| **Strengthened using-superpowers skill for explicit skill requests** | ||
|
|
||
| Addressed a failure mode where Claude would skip invoking a skill even when the user explicitly requested it by name (e.g., "subagent-driven-development, please"). Claude would think "I know what that means" and start working directly instead of loading the skill. | ||
|
|
||
| Changes: | ||
| - Updated "The Rule" to say "Invoke relevant or requested skills" instead of "Check for skills" - emphasizing active invocation over passive checking | ||
| - Added "BEFORE any response or action" - the original wording only mentioned "response" but Claude would sometimes take action without responding first | ||
| - Added reassurance that invoking a wrong skill is okay - reduces hesitation | ||
| - Added new red flag: "I know what that means" → Knowing the concept ≠ using the skill | ||
|
|
||
| **Added explicit skill request tests** | ||
|
|
||
| New test suite in `tests/explicit-skill-requests/` that verifies Claude correctly invokes skills when users request them by name. Includes single-turn and multi-turn test scenarios. | ||
|
|
||
| ## v4.0.2 (2025-12-23) | ||
|
|
||
| ### Fixes | ||
|
|
||
| **Slash commands now user-only** | ||
|
|
||
| Added `disable-model-invocation: true` to all three slash commands (`/brainstorm`, `/execute-plan`, `/write-plan`). Claude can no longer invoke these commands via the Skill tool—they're restricted to manual user invocation only. | ||
|
|
||
| The underlying skills (`superpowers:brainstorming`, `superpowers:executing-plans`, `superpowers:writing-plans`) remain available for Claude to invoke autonomously. This change prevents confusion when Claude would invoke a command that just redirects to a skill anyway. | ||
|
|
||
| ## v4.0.1 (2025-12-23) | ||
|
|
||
| ### Fixes | ||
|
|
||
| **Clarified how to access skills in Claude Code** | ||
|
|
||
| Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The `using-superpowers` skill now explicitly states that the Skill tool loads skill content directly—no need to read files. | ||
|
|
||
| - Added "How to Access Skills" section to `using-superpowers` | ||
| - Changed "read the skill" → "invoke the skill" in instructions | ||
| - Updated slash commands to use fully qualified skill names (e.g., `superpowers:brainstorming`) | ||
|
|
||
| **Added GitHub thread reply guidance to receiving-code-review** (h/t @ralphbean) | ||
|
|
||
| Added a note about replying to inline review comments in the original thread rather than as top-level PR comments. | ||
|
|
||
| **Added automation-over-documentation guidance to writing-skills** (h/t @EthanJStark) | ||
|
|
||
| Added guidance that mechanical constraints should be automated, not documented—save skills for judgment calls. | ||
|
|
||
| ## v4.0.0 (2025-12-17) | ||
|
|
||
| ### New Features | ||
|
|
||
| **Two-stage code review in subagent-driven-development** | ||
|
|
||
| Subagent workflows now use two separate review stages after each task: | ||
|
|
||
| 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. | ||
|
|
||
| 2. **Code quality review** - Only runs after spec compliance passes. Reviews for clean code, test coverage, maintainability. | ||
|
|
||
| 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. | ||
|
|
||
| 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 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 | ||
|
|
||
| **Debugging techniques consolidated with tools** | ||
|
|
||
| `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 | ||
|
|
||
| **Testing anti-patterns reference** | ||
|
|
||
| `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 | ||
|
|
||
| - **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 | ||
|
|
||
| --- | ||
|
|
||
| ## v3.6.2 (2025-12-03) | ||
|
|
||
| ### Fixed | ||
|
|
||
| - **Linux Compatibility**: Fixed polyglot hook wrapper (`run-hook.cmd`) to use POSIX-compliant syntax | ||
| - Replaced bash-specific `${BASH_SOURCE[0]:-$0}` with standard `$0` on line 16 | ||
| - Resolves "Bad substitution" error on Ubuntu/Debian systems where `/bin/sh` is dash | ||
| - Fixes #141 | ||
|
|
||
| --- | ||
|
|
||
| ## v3.5.1 (2025-11-24) | ||
|
|
||
| ### Changed | ||
|
|
||
| - **OpenCode Bootstrap Refactor**: Switched from `chat.message` hook to `session.created` event for bootstrap injection | ||
| - Bootstrap now injects at session creation via `session.prompt()` with `noReply: true` | ||
| - Explicitly tells the model that using-superpowers is already loaded to prevent redundant skill loading | ||
| - Consolidated bootstrap content generation into shared `getBootstrapContent()` helper | ||
| - Cleaner single-implementation approach (removed fallback pattern) | ||
|
|
||
| --- | ||
|
|
||
| ## v3.5.0 (2025-11-23) | ||
|
|
||
| ### Added | ||
|
|
||
| - **OpenCode Support**: Native JavaScript plugin for OpenCode.ai | ||
| - Custom tools: `use_skill` and `find_skills` | ||
| - Message insertion pattern for skill persistence across context compaction | ||
| - Automatic context injection via chat.message hook | ||
| - Auto re-injection on session.compacted events | ||
| - Three-tier skill priority: project > personal > superpowers | ||
| - Project-local skills support (`.opencode/skills/`) | ||
| - Shared core module (`lib/skills-core.js`) for code reuse with Codex | ||
| - Automated test suite with proper isolation (`tests/opencode/`) | ||
| - Platform-specific documentation (`docs/README.opencode.md`, `docs/README.codex.md`) | ||
|
|
||
| ### Changed | ||
|
|
||
| - **Refactored Codex Implementation**: Now uses shared `lib/skills-core.js` ES module | ||
| - Eliminates code duplication between Codex and OpenCode | ||
| - Single source of truth for skill discovery and parsing | ||
| - Codex successfully loads ES modules via Node.js interop | ||
|
|
||
| - **Improved Documentation**: Rewrote README to explain problem/solution clearly | ||
| - Removed duplicate sections and conflicting information | ||
| - Added complete workflow description (brainstorm → plan → execute → finish) | ||
| - Simplified platform installation instructions | ||
| - Emphasized skill-checking protocol over automatic activation claims | ||
|
|
||
| --- | ||
|
|
||
| ## v3.4.1 (2025-10-31) | ||
|
|
||
| ### Improvements | ||
|
|
||
| - Optimized superpowers bootstrap to eliminate redundant skill execution. The `using-superpowers` skill content is now provided directly in session context, with clear guidance to use the Skill tool only for other skills. This reduces overhead and prevents the confusing loop where agents would execute `using-superpowers` manually despite already having the content from session start. | ||
|
|
||
| ## v3.4.0 (2025-10-30) | ||
|
|
||
| ### Improvements | ||
|
|
||
| - Simplified `brainstorming` skill to return to original conversational vision. Removed heavyweight 6-phase process with formal checklists in favor of natural dialogue: ask questions one at a time, then present design in 200-300 word sections with validation. Keeps documentation and implementation handoff features. | ||
|
|
||
| ## v3.3.1 (2025-10-28) | ||
|
|
||
| ### Improvements | ||
|
|
||
| - Updated `brainstorming` skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans. | ||
| - Applied writing clarity improvements to `brainstorming` skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction). | ||
|
|
||
| ### Bug Fixes | ||
|
|
||
| - Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex). | ||
|
|
||
| ## v3.3.0 (2025-10-28) | ||
| **Initial release** of Superpowers-NG, an enhanced fork of [obra/superpowers](https://github.com/obra/superpowers) with Manus-style persistent planning and Ralph integration. | ||
|
|
||
| ### New Features | ||
|
|
||
| **Experimental Codex Support** | ||
| - Added unified `superpowers-codex` script with bootstrap/use-skill/find-skills commands | ||
| - Cross-platform Node.js implementation (works on Windows, macOS, Linux) | ||
| - Namespaced skills: `superpowers:skill-name` for superpowers skills, `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. | ||
| - Bootstrap integration with minimal AGENTS.md for automatic startup | ||
| - Complete installation guide and bootstrap instructions specific to Codex | ||
|
|
||
| **Key differences from Claude Code integration:** | ||
| - Single unified script instead of separate tools | ||
| - Tool substitution system for Codex-specific equivalents | ||
| - Simplified subagent handling (manual work instead of delegation) | ||
| - Updated terminology: "Superpowers skills" instead of "Core skills" | ||
|
|
||
| ### Files Added | ||
| - `.codex/INSTALL.md` - Installation guide for Codex users | ||
| - `.codex/superpowers-bootstrap.md` - Bootstrap instructions with Codex adaptations | ||
| - `.codex/superpowers-codex` - Unified Node.js executable with all functionality | ||
|
|
||
| **Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback. | ||
|
|
||
| ## v3.2.3 (2025-10-23) | ||
|
|
||
| ### Improvements | ||
|
|
||
| **Updated using-superpowers skill to use Skill tool instead of Read tool** | ||
| - Changed skill invocation instructions from Read tool to Skill tool | ||
| - Updated description: "using Read tool" → "using Skill tool" | ||
| - Updated step 3: "Use the Read tool" → "Use the Skill tool to read and run" | ||
| - Updated rationalization list: "Read the current version" → "Run the current version" | ||
| #### Manus Planning System | ||
|
|
||
| **File-based planning that survives context resets** | ||
|
|
||
| Added `manus-planning` skill inspired by [planning-with-files](https://github.com/OthmanAdi/planning-with-files) by OthmanAdi. This enables long-running tasks that span multiple sessions or exceed 50 tool calls. | ||
|
|
||
| The Skill tool is the proper mechanism for invoking skills in Claude Code. This update corrects the bootstrap instructions to guide agents toward the correct tool. | ||
| **The 3 Files** (`docs/manus/`): | ||
| - `task_plan.md` - Goal, 5 phases (Requirements → Planning → Implementation → Testing → Delivery), decisions table, errors log | ||
| - `findings.md` - Requirements, research, technical decisions, resources (critical for visual/browser content that doesn't persist in context) | ||
| - `progress.md` - Session log with timestamps, test results table, error log, 5-question reboot check for context resumption | ||
|
|
||
| **Key Features:** | ||
| - **Persistent memory**: Files survive context resets, enabling work across multiple sessions | ||
| - **Automatic reminders**: PreToolUse hooks show plan preview before Write/Edit/Bash operations (when `.active` marker exists) | ||
| - **2-Action Rule**: After every 2 view/browser/search operations, update `findings.md` to preserve discoveries | ||
| - **Archive system**: Completed tasks auto-archive to `docs/manus/archive/YYYY-MM-DD-<topic>/`, new tasks get prompted (continue or start new) | ||
| - **5 Phases**: Structured workflow from Requirements through Delivery with status tracking | ||
|
|
||
| ### Files Changed | ||
| - Updated: `skills/using-superpowers/SKILL.md` - Changed tool references from Read to Skill | ||
| **Files:** | ||
| - `skills/manus-planning/SKILL.md` - Main skill definition | ||
| - `skills/manus-planning/templates/task_plan.md` - Phase tracking template | ||
| - `skills/manus-planning/templates/findings.md` - Research storage template | ||
| - `skills/manus-planning/templates/progress.md` - Session log template | ||
| - `commands/manus-plan.md` - Slash command `/manus-plan` | ||
| - `hooks/manus-pretool.sh` - Conditional PreToolUse hook (only active when marker file exists) | ||
|
|
||
| ## v3.2.2 (2025-10-21) | ||
| #### Brainstorming Enhancement | ||
|
|
||
| ### Improvements | ||
| **Planning choice after design** | ||
|
|
||
| **Strengthened using-superpowers skill against agent rationalization** | ||
| - Added EXTREMELY-IMPORTANT block with absolute language about mandatory skill checking | ||
| - "If even 1% chance a skill applies, you MUST read it" | ||
| - "You do not have a choice. You cannot rationalize your way out." | ||
| - Added MANDATORY FIRST RESPONSE PROTOCOL checklist | ||
| - 5-step process agents must complete before any response | ||
| - Explicit "responding without this = failure" consequence | ||
| - Added Common Rationalizations section with 8 specific evasion patterns | ||
| - "This is just a simple question" → WRONG | ||
| - "I can check files quickly" → WRONG | ||
| - "Let me gather information first" → WRONG | ||
| - Plus 5 more common patterns observed in agent behavior | ||
| Updated `brainstorming` skill to present both planning options after design completion: | ||
| 1. **Native planning** (writing-plans → executing-plans): Short tasks, interactive development | ||
| 2. **Manus planning** (manus-planning): Long runs, multi-session projects | ||
|
|
||
| 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 non-compliance harder. | ||
| When Manus is chosen, design document content is automatically copied into `findings.md` for persistent reference. | ||
|
|
||
| ### Files Changed | ||
| - Updated: `skills/using-superpowers/SKILL.md` - Added three layers of enforcement to prevent skill-skipping rationalization | ||
| **File:** | ||
| - `skills/brainstorming/SKILL.md` - Updated "After the Design" section | ||
|
|
||
| ## v3.2.1 (2025-10-20) | ||
| #### Planning Guidance | ||
|
|
||
| ### New Features | ||
| **Added planning approach comparison** | ||
|
|
||
| **Code reviewer agent now included in plugin** | ||
| - Added `superpowers:code-reviewer` agent to plugin's `agents/` directory | ||
| - Agent provides systematic code review against plans and coding standards | ||
| - Previously required users to have personal agent configuration | ||
| - All skill references updated to use namespaced `superpowers:code-reviewer` | ||
| - Fixes #55 | ||
| Updated `using-superpowers` skill with "Planning Approaches" section explaining when to use Native vs Manus planning: | ||
|
|
||
| ### Files Changed | ||
| - New: `agents/code-reviewer.md` - Agent definition with review checklist and output format | ||
| - Updated: `skills/requesting-code-review/SKILL.md` - References to `superpowers:code-reviewer` | ||
| - Updated: `skills/subagent-driven-development/SKILL.md` - References to `superpowers:code-reviewer` | ||
| | Approach | Skills | Best For | | ||
| |----------|--------|----------| | ||
| | **Native** | writing-plans + executing-plans | Short tasks (<30 min), interactive development with human checkpoints | | ||
| | **Manus** | manus-planning | Long autonomous runs, multi-session projects, tasks requiring >50 tool calls | | ||
|
|
||
| ## v3.2.0 (2025-10-18) | ||
| **File:** | ||
| - `skills/using-superpowers/SKILL.md` - Added planning guidance section | ||
|
|
||
| ### New Features | ||
| #### Ralph Integration | ||
|
|
||
| **Design documentation in brainstorming workflow** | ||
| - Added Phase 4: Design Documentation to brainstorming skill | ||
| - Design documents now written to `docs/plans/YYYY-MM-DD-<topic>-design.md` before implementation | ||
| - Restores functionality from original brainstorming command that was lost during skill conversion | ||
| - Documents written before worktree setup and implementation planning | ||
| - Tested with subagent to verify compliance under time pressure | ||
| **Seamless integration with Ralph autonomous loop framework** | ||
|
|
||
| ### Breaking Changes | ||
| Added comprehensive support for using Superpowers-NG skills within [Ralph](https://github.com/frankbria/ralph-claude-code), the autonomous loop framework for Claude Code. | ||
|
|
||
| **Skill reference namespace standardization** | ||
| - All internal skill references now use `superpowers:` namespace prefix | ||
| - Updated format: `superpowers:test-driven-development` (previously just `test-driven-development`) | ||
| - Affects all REQUIRED SUB-SKILL, RECOMMENDED SUB-SKILL, and REQUIRED BACKGROUND references | ||
| - Aligns with how skills are invoked using the Skill tool | ||
| - Files updated: brainstorming, executing-plans, subagent-driven-development, systematic-debugging, testing-skills-with-subagents, writing-plans, writing-skills | ||
| **Key improvements**: | ||
| - **brainstorming** now checks for existing design files before starting | ||
| - Auto-detects `docs/plans/*-design.md`, `design.md`, or `docs/manus/findings.md` | ||
| - In autonomous mode (Ralph loops): automatically uses existing design and skips to implementation | ||
| - In interactive mode: offers choices (use existing, refine, start fresh) | ||
| - Prevents redundant brainstorming in subsequent Ralph loops | ||
| - **manus-planning** already compatible with Ralph's multi-session nature | ||
| - Persistent files survive loop resets | ||
| - Auto-resumes via `.active` marker detection | ||
| - Perfect for Ralph's `--continue` session model | ||
| - Phased brainstorming structure (Phase 0 → Phase 3) for clearer flow | ||
|
|
||
| ### Improvements | ||
| **Documentation**: | ||
| - `docs/ralph-integration/README.md` - Complete integration guide | ||
| - Architecture overview (Ralph vs Superpowers layers) | ||
| - Skill lifecycle in Ralph loops (once per task vs every loop) | ||
| - PROMPT.md structure and patterns | ||
| - File management strategy | ||
| - Common issues and solutions | ||
| - `docs/ralph-integration/PROMPT.template.md` - Ready-to-use PROMPT.md template | ||
| - **Ralph's official status block format** with all required fields: | ||
| - STATUS, TASKS_COMPLETED_THIS_LOOP, FILES_MODIFIED, TESTS_STATUS, WORK_TYPE, EXIT_SIGNAL, RECOMMENDATION | ||
| - **Concrete examples**: 5 detailed scenarios showing exact status emissions | ||
| - **Circuit breaker patterns**: Test-only loops, recurring errors, zero progress detection | ||
| - **Anti-patterns table**: 8 explicitly forbidden patterns (refactor working code, add unplanned features, etc.) | ||
| - **Exit criteria checklist**: 7-item checklist for when to set EXIT_SIGNAL: true | ||
| - Conditional skill invocation (check for existing artifacts) | ||
| - Autonomous mode behavior guidelines | ||
| - Phase-based workflow with Superpowers skills | ||
| - Customizable project context sections | ||
|
|
||
| **Design vs implementation plan naming** | ||
| - Design documents use `-design.md` suffix to prevent filename collisions | ||
| - Implementation plans continue using existing `YYYY-MM-DD-<feature-name>.md` format | ||
| - Both stored in `docs/plans/` directory with clear naming distinction | ||
| **Updated Files**: | ||
| - `skills/brainstorming/SKILL.md` - Added Phase 0 (Check for Existing Design) with autonomous mode logic | ||
| - `README.md` - Added "Integration with Ralph" section | ||
|
|
||
| ## v3.1.1 (2025-10-17) | ||
|
|
||
| ### Bug Fixes | ||
|
|
||
| - **Fixed command syntax in README** (#44) - Updated all command references to use correct namespaced syntax (`/superpowers:brainstorm` instead of `/brainstorm`). Plugin-provided commands are automatically namespaced by Claude Code to avoid conflicts between plugins. | ||
|
|
||
| ## v3.1.0 (2025-10-17) | ||
| **Benefits for Ralph users**: | ||
| - No duplicate work across loops (design once, implement across many loops) | ||
| - Persistent memory via manus-planning files | ||
| - TDD and debugging discipline maintained across sessions | ||
| - Evidence-based completion signals (verification-before-completion) | ||
| - Ready-to-use templates for quick setup | ||
|
|
||
| ### Technical Implementation | ||
|
|
||
| #### Hooks System Enhancement | ||
|
|
||
| **Conditional PreToolUse hook** | ||
|
|
||
| Added PreToolUse hook to `hooks.json` that fires before Write/Edit/Bash operations: | ||
| - Only outputs when `docs/manus/.active` marker file exists | ||
| - Displays first 30 lines of `task_plan.md` as context reminder | ||
| - Outputs empty JSON `{}` when inactive (no interference with native planning) | ||
| - Cross-platform compatible (uses same `run-hook.cmd` wrapper as SessionStart) | ||
|
|
||
| **Files:** | ||
| - `hooks/hooks.json` - Added PreToolUse matcher for Write|Edit|Bash | ||
| - `hooks/manus-pretool.sh` - Bash script with JSON escaping, checks marker file | ||
|
|
||
| ### Breaking Changes | ||
|
|
||
| **Skill names standardized to lowercase** | ||
| - All skill frontmatter `name:` fields now use lowercase kebab-case matching directory names | ||
| - Examples: `brainstorming`, `test-driven-development`, `using-git-worktrees` | ||
| - All skill announcements and cross-references updated to lowercase format | ||
| - This ensures consistent naming across directory names, frontmatter, and documentation | ||
|
|
||
| ### New Features | ||
|
|
||
| **Enhanced brainstorming skill** | ||
| - Added Quick Reference table showing phases, activities, and tool usage | ||
| - Added copyable workflow checklist for tracking progress | ||
| - Added decision flowchart for when to revisit earlier phases | ||
| - Added comprehensive AskUserQuestion tool guidance with concrete examples | ||
| - Added "Question Patterns" section explaining when to use structured vs open-ended questions | ||
| - Restructured Key Principles as scannable table | ||
|
|
||
| **Anthropic best practices integration** | ||
| - Added `skills/writing-skills/anthropic-best-practices.md` - Official Anthropic skill authoring guide | ||
| - Referenced in writing-skills SKILL.md for comprehensive guidance | ||
| - Provides patterns for progressive disclosure, workflows, and evaluation | ||
|
|
||
| ### Improvements | ||
|
|
||
| **Skill cross-reference clarity** | ||
| - All skill references now use explicit requirement markers: | ||
| - `**REQUIRED BACKGROUND:**` - Prerequisites you must understand | ||
| - `**REQUIRED SUB-SKILL:**` - Skills that must be used in workflow | ||
| - `**Complementary skills:**` - Optional but helpful related skills | ||
| - Removed old path format (`skills/collaboration/X` → just `X`) | ||
| - Updated Integration sections with categorized relationships (Required vs Complementary) | ||
| - Updated cross-reference documentation with best practices | ||
|
|
||
| **Alignment with Anthropic best practices** | ||
| - Fixed description grammar and voice (fully third-person) | ||
| - Added Quick Reference tables for scanning | ||
| - Added workflow checklists Claude can copy and track | ||
| - Appropriate use of flowcharts for non-obvious decision points | ||
| - Improved scannable table formats | ||
| - All skills well under 500-line recommendation | ||
|
|
||
| ### Bug Fixes | ||
|
|
||
| - **Re-added missing command redirects** - Restored `commands/brainstorm.md` and `commands/write-plan.md` that were accidentally removed in v3.0 migration | ||
| - Fixed `defense-in-depth` name mismatch (was `Defense-in-Depth-Validation`) | ||
| - Fixed `receiving-code-review` name mismatch (was `Code-Review-Reception`) | ||
| - Fixed `commands/brainstorm.md` reference to correct skill name | ||
| - Removed references to non-existent related skills | ||
|
|
||
| ### Documentation | ||
|
|
||
| **writing-skills improvements** | ||
| - Updated cross-referencing guidance with explicit requirement markers | ||
| - Added reference to Anthropic's official best practices | ||
| - Improved examples showing proper skill reference format | ||
|
|
||
| ## v3.0.1 (2025-10-16) | ||
|
|
||
| ### Changes | ||
|
|
||
| We now use Anthropic's first-party skills system! | ||
|
|
||
| ## v2.0.2 (2025-10-12) | ||
|
|
||
| ### Bug Fixes | ||
|
|
||
| - **Fixed false warning when local skills repo is ahead of upstream** - The initialization script was incorrectly warning "New skills available from upstream" when the local repository had commits ahead of upstream. The logic now correctly distinguishes between three git states: local behind (should update), local ahead (no warning), and diverged (should warn). | ||
|
|
||
| ## v2.0.1 (2025-10-12) | ||
|
|
||
| ### Bug Fixes | ||
|
|
||
| - **Fixed session-start hook execution in plugin context** (#8, PR #9) - The hook was failing silently with "Plugin hook error" preventing skills context from loading. Fixed by: | ||
| - Using `${BASH_SOURCE[0]:-$0}` fallback when BASH_SOURCE is unbound in Claude Code's execution context | ||
| - Adding `|| true` to handle empty grep results gracefully when filtering status flags | ||
|
|
||
| --- | ||
|
|
||
| # Superpowers v2.0.0 Release Notes | ||
|
|
||
| ## Overview | ||
|
|
||
| Superpowers v2.0 makes skills more accessible, maintainable, and community-driven through a major architectural shift. | ||
|
|
||
| The headline change is **skills repository separation**: all skills, scripts, and documentation have moved from the plugin into a dedicated repository ([obra/superpowers-skills](https://github.com/obra/superpowers-skills)). This transforms superpowers from a monolithic plugin into a lightweight shim that manages a local clone of the skills repository. Skills auto-update on session start. Users fork and contribute improvements via standard git workflows. The skills library versions independently from the plugin. | ||
|
|
||
| Beyond infrastructure, this release adds nine new skills focused on problem-solving, research, and architecture. We rewrote the core **using-skills** documentation with imperative tone and clearer structure, making it easier for Claude to understand when and how to use skills. **find-skills** now outputs paths you can paste directly into the Read tool, eliminating friction in the skills discovery workflow. | ||
|
|
||
| Users experience seamless operation: the plugin handles cloning, forking, and updating automatically. Contributors find the new architecture makes improving and sharing skills trivial. This release lays the foundation for skills to evolve rapidly as a community resource. | ||
|
|
||
| ## Breaking Changes | ||
|
|
||
| ### Skills Repository Separation | ||
|
|
||
| **The biggest change:** Skills no longer live in the plugin. They've been moved to a separate repository at [obra/superpowers-skills](https://github.com/obra/superpowers-skills). | ||
|
|
||
| **What this means for you:** | ||
|
|
||
| - **First install:** Plugin automatically clones skills to `~/.config/superpowers/skills/` | ||
| - **Forking:** During setup, you'll be offered the option to fork the skills repo (if `gh` is installed) | ||
| - **Updates:** Skills auto-update on session start (fast-forward when possible) | ||
| - **Contributing:** Work on branches, commit locally, submit PRs to upstream | ||
| - **No more shadowing:** Old two-tier system (personal/core) replaced with single-repo branch workflow | ||
|
|
||
| **Migration:** | ||
|
|
||
| If you have an existing installation: | ||
| 1. Your old `~/.config/superpowers/.git` will be backed up to `~/.config/superpowers/.git.bak` | ||
| 2. Old skills will be backed up to `~/.config/superpowers/skills.bak` | ||
| 3. Fresh clone of obra/superpowers-skills will be created at `~/.config/superpowers/skills/` | ||
|
|
||
| ### Removed Features | ||
|
|
||
| - **Personal superpowers overlay system** - Replaced with git branch workflow | ||
| - **setup-personal-superpowers hook** - Replaced by initialize-skills.sh | ||
|
|
||
| ## New Features | ||
|
|
||
| ### Skills Repository Infrastructure | ||
|
|
||
| **Automatic Clone & Setup** (`lib/initialize-skills.sh`) | ||
| - Clones obra/superpowers-skills on first run | ||
| - Offers fork creation if GitHub CLI is installed | ||
| - Sets up upstream/origin remotes correctly | ||
| - Handles migration from old installation | ||
|
|
||
| **Auto-Update** | ||
| - Fetches from tracking remote on every session start | ||
| - Auto-merges with fast-forward when possible | ||
| - Notifies when manual sync needed (branch diverged) | ||
| - Uses pulling-updates-from-skills-repository skill for manual sync | ||
|
|
||
| ### New Skills | ||
|
|
||
| **Problem-Solving Skills** (`skills/problem-solving/`) | ||
| - **collision-zone-thinking** - Force unrelated concepts together for emergent insights | ||
| - **inversion-exercise** - Flip assumptions to reveal hidden constraints | ||
| - **meta-pattern-recognition** - Spot universal principles across domains | ||
| - **scale-game** - Test at extremes to expose fundamental truths | ||
| - **simplification-cascades** - Find insights that eliminate multiple components | ||
| - **when-stuck** - Dispatch to right problem-solving technique | ||
|
|
||
| **Research Skills** (`skills/research/`) | ||
| - **tracing-knowledge-lineages** - Understand how ideas evolved over time | ||
|
|
||
| **Architecture Skills** (`skills/architecture/`) | ||
| - **preserving-productive-tensions** - Keep multiple valid approaches instead of forcing premature resolution | ||
|
|
||
| ### Skills Improvements | ||
|
|
||
| **using-skills (formerly getting-started)** | ||
| - Renamed from getting-started to using-skills | ||
| - Complete rewrite with imperative tone (v4.0.0) | ||
| - Front-loaded critical rules | ||
| - Added "Why" explanations for all workflows | ||
| - Always includes /SKILL.md suffix in references | ||
| - Clearer distinction between rigid rules and flexible patterns | ||
|
|
||
| **writing-skills** | ||
| - Cross-referencing guidance moved from using-skills | ||
| - Added token efficiency section (word count targets) | ||
| - Improved CSO (Claude Search Optimization) guidance | ||
|
|
||
| **sharing-skills** | ||
| - Updated for new branch-and-PR workflow (v2.0.0) | ||
| - Removed personal/core split references | ||
|
|
||
| **pulling-updates-from-skills-repository** (new) | ||
| - Complete workflow for syncing with upstream | ||
| - Replaces old "updating-skills" skill | ||
|
|
||
| ### Tools Improvements | ||
|
|
||
| **find-skills** | ||
| - Now outputs full paths with /SKILL.md suffix | ||
| - Makes paths directly usable with Read tool | ||
| - Updated help text | ||
|
|
||
| **skill-run** | ||
| - Moved from scripts/ to skills/using-skills/ | ||
| - Improved documentation | ||
|
|
||
| ### Plugin Infrastructure | ||
|
|
||
| **Session Start Hook** | ||
| - Now loads from skills repository location | ||
| - Shows full skills list at session start | ||
| - Prints skills location info | ||
| - Shows update status (updated successfully / behind upstream) | ||
| - Moved "skills behind" warning to end of output | ||
|
|
||
| **Environment Variables** | ||
| - `SUPERPOWERS_SKILLS_ROOT` set to `~/.config/superpowers/skills` | ||
| - Used consistently throughout all paths | ||
|
|
||
| ## Bug Fixes | ||
|
|
||
| - Fixed duplicate upstream remote addition when forking | ||
| - Fixed find-skills double "skills/" prefix in output | ||
| - Removed obsolete setup-personal-superpowers call from session-start | ||
| - Fixed path references throughout hooks and commands | ||
|
|
||
| ## Documentation | ||
|
|
||
| ### README | ||
| - Updated for new skills repository architecture | ||
| - Prominent link to superpowers-skills repo | ||
| - Updated auto-update description | ||
| - Fixed skill names and references | ||
| - Updated Meta skills list | ||
|
|
||
| ### Testing Documentation | ||
| - Added comprehensive testing checklist (`docs/TESTING-CHECKLIST.md`) | ||
| - Created local marketplace config for testing | ||
| - Documented manual testing scenarios | ||
|
|
||
| ## Technical Details | ||
|
|
||
| ### File Changes | ||
|
|
||
| **Added:** | ||
| - `lib/initialize-skills.sh` - Skills repo initialization and auto-update | ||
| - `docs/TESTING-CHECKLIST.md` - Manual testing scenarios | ||
| - `.claude-plugin/marketplace.json` - Local testing config | ||
|
|
||
| **Removed:** | ||
| - `skills/` directory (82 files) - Now in obra/superpowers-skills | ||
| - `scripts/` directory - Now in obra/superpowers-skills/skills/using-skills/ | ||
| - `hooks/setup-personal-superpowers.sh` - Obsolete | ||
|
|
||
| **Modified:** | ||
| - `hooks/session-start.sh` - Use skills from ~/.config/superpowers/skills | ||
| - `commands/brainstorm.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT | ||
| - `commands/write-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT | ||
| - `commands/execute-plan.md` - Updated paths to SUPERPOWERS_SKILLS_ROOT | ||
| - `README.md` - Complete rewrite for new architecture | ||
|
|
||
| ### Commit History | ||
| **Plugin renamed to superpowers-ng** | ||
|
|
||
| This release includes: | ||
| - 20+ commits for skills repository separation | ||
| - PR #1: Amplifier-inspired problem-solving and research skills | ||
| - PR #2: Personal superpowers overlay system (later replaced) | ||
| - Multiple skill refinements and documentation improvements | ||
| This fork is distributed separately from original superpowers: | ||
| - Plugin name: `superpowers-ng` | ||
| - Repository: `OniReimu/superpowers` | ||
| - Version reset to v0.1.0 | ||
|
|
||
| ## Upgrade Instructions | ||
| **File:** | ||
| - `.claude-plugin/plugin.json` - Updated name, version, author, repository, added credits | ||
|
|
||
| ### Fresh Install | ||
| ### Credits | ||
|
|
||
| ```bash | ||
| # In Claude Code | ||
| /plugin marketplace add obra/superpowers-marketplace | ||
| /plugin install superpowers@superpowers-marketplace | ||
| ``` | ||
| **Original Authors:** | ||
| - **Jesse Vincent (obra)** - [obra/superpowers](https://github.com/obra/superpowers) - Original Superpowers framework | ||
| - **Ahmad Othman Ammar Adi (OthmanAdi)** - [planning-with-files](https://github.com/OthmanAdi/planning-with-files) - Manus 3-file pattern | ||
|
|
||
| The plugin handles everything automatically. | ||
| **Superpowers-NG:** | ||
| - **OniReimu** - Integration and enhancement | ||
|
|
||
| ### Upgrading from v1.x | ||
| **Inspiration:** | ||
| - Manus AI (acquired by Meta for $2B) - Context engineering principles codified in planning-with-files | ||
|
|
||
| 1. **Backup your personal skills** (if you have any): | ||
| ```bash | ||
| cp -r ~/.config/superpowers/skills ~/superpowers-skills-backup | ||
| ``` | ||
| ### Design Decisions | ||
|
|
||
| 2. **Update the plugin:** | ||
| ```bash | ||
| /plugin update superpowers | ||
| ``` | ||
| **Separate planning systems (no cross-style switching)** | ||
| - Native and Manus use different file formats and hooks | ||
| - Users choose one at the start based on task complexity | ||
| - Prevents format conflicts and unexpected behavior | ||
|
|
||
| 3. **On next session start:** | ||
| - Old installation will be backed up automatically | ||
| - Fresh skills repo will be cloned | ||
| - If you have GitHub CLI, you'll be offered the option to fork | ||
| **Marker file for conditional hooks** | ||
| - `.active` file enables/disables PreToolUse hooks | ||
| - Clean isolation: hooks don't fire for native planning | ||
| - Automatically removed on task completion | ||
|
|
||
| 4. **Migrate personal skills** (if you had any): | ||
| - Create a branch in your local skills repo | ||
| - Copy your personal skills from backup | ||
| - Commit and push to your fork | ||
| - Consider contributing back via PR | ||
| **Archive approach for multi-task handling** | ||
| - Completed tasks (no `.active`): Auto-archive to `docs/manus/archive/YYYY-MM-DD-<topic>/` | ||
| - In-progress tasks (`.active` exists): Prompt user to continue or start new | ||
| - Preserves history while keeping active location predictable | ||
|
|
||
| ## What's Next | ||
| **Design document integration** | ||
| - Brainstorming → Manus flow copies design content into `findings.md` | ||
| - Becomes part of persistent research storage | ||
| - Accessible across context resets | ||
|
|
||
| ### For Users | ||
| ### Known Limitations | ||
|
|
||
| - Explore the new problem-solving skills | ||
| - Try the branch-based workflow for skill improvements | ||
| - Contribute skills back to the community | ||
| **Installation requires manual setup** | ||
| - Marketplace integration pending | ||
| - Users must clone repository directly | ||
| - Will be resolved in future release | ||
|
|
||
| ### For Contributors | ||
| **No cross-platform testing** | ||
| - Hook script tested on macOS only | ||
| - Should work on Linux/Windows (uses polyglot wrapper) | ||
| - Community testing needed | ||
|
|
||
| - Skills repository is now at https://github.com/obra/superpowers-skills | ||
| - Fork → Branch → PR workflow | ||
| - See skills/meta/writing-skills/SKILL.md for TDD approach to documentation | ||
| ### Upgrade Path | ||
|
|
||
| ## Known Issues | ||
| **For users of obra/superpowers:** | ||
| - Superpowers-NG is a separate fork, not a drop-in replacement | ||
| - Can install both plugins side-by-side | ||
| - Native planning workflows unchanged | ||
| - Manus planning is additive, opt-in feature | ||
|
|
||
| None at this time. | ||
| **For new users:** | ||
| - Start with either Native or Manus planning based on task | ||
| - Both workflows fully supported | ||
| - Brainstorming skill guides choice after design | ||
|
|
||
| ## Credits | ||
| ### What's Next | ||
|
|
||
| - Problem-solving skills inspired by Amplifier patterns | ||
| - Community contributions and feedback | ||
| - Extensive testing and iteration on skill effectiveness | ||
| **Planned enhancements:** | ||
| - Marketplace publication for easy installation | ||
| - Subagent handoff support (Task 8 from implementation plan) | ||
| - Template customization | ||
| - Cross-platform testing and validation | ||
| - Community feedback integration | ||
|
|
||
| --- | ||
|
|
||
| **Full Changelog:** https://github.com/obra/superpowers/compare/dd013f6...main | ||
| **Skills Repository:** https://github.com/obra/superpowers-skills | ||
| **Issues:** https://github.com/obra/superpowers/issues | ||
| **Full Changelog:** https://github.com/OniReimu/superpowers/compare/obra:main...OniReimu:main | ||
| **Issues:** https://github.com/OniReimu/superpowers/issues | ||
| **Original Superpowers:** https://github.com/obra/superpowers |
There was a problem hiding this comment.
The PR's primary feature (project-local skill scope) is absent from the release notes.
The v0.1.0 section thoroughly documents Manus planning, Ralph integration, brainstorming enhancements, and the plugin rename — but contains no entry for the three-tier skill resolution system (project > personal > superpowers-ng), the project: / superpowers-ng: namespace prefixes, or the project-tier detection via process.cwd() that this PR implements. The "What's Next" section even lists future work without acknowledging this already-shipped feature.
Consider adding a dedicated sub-section (e.g. under New Features or as a separate ## v0.2.0 entry if this is intended as a follow-on release) covering:
- Project-local skill directory (
.codex/skills/) - Three-tier resolution order (project → personal → superpowers-ng)
- Explicit namespace prefix invocation (
project:skill-name,superpowers-ng:skill-name)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@RELEASE-NOTES.md` around lines 145 - 352, Add documentation for the
project-local skill scope feature to the release notes by creating a short New
Feature subsection that explains the three-tier skill resolution (project →
personal → superpowers-ng), the new project-local skill directory
(.codex/skills/), the explicit namespace prefixes project: and superpowers-ng:,
and the project-tier detection via process.cwd(); place this under the v0.1.0
New Features (or as a v0.2.0 entry if you prefer a follow-up release), include
concise usage examples for invoking namespaced skills and the resolution order,
and update the "What's Next" list to remove or adjust items that now ship with
this change.
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>
Author
|
Closing — PR should target the fork repo instead. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/README.codex.md (1)
121-121:$skill-nameplaceholder is inconsistent with how skill invocation is described elsewhere.The backtick-wrapped
$skill-namereads as a shell variable, but every other place in this document describes skill invocation as plain name mentions (e.g., Line 57:"use brainstorming"). A concrete example would be clearer.📝 Proposed fix
-- `Skill` tool → native `$skill-name` mention +- `Skill` tool → mention the skill by name (e.g., `use brainstorming`)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/README.codex.md` at line 121, The README uses a backtick-wrapped `$skill-name` which is inconsistent with other mentions (e.g., "use brainstorming") and reads like a shell variable; update the `Skill` tool documentation to use the plain name invocation format instead (replace `$skill-name` with a concrete example such as "use brainstorming" or "invoke brainstorming" wherever `Skill` or `$skill-name` appears) and add one short concrete example sentence showing the invocation to match the style used on Line 57.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/README.codex.md`:
- Line 129: The README incorrectly claims Codex CLI supports PreToolUse hooks
via the `docs/manus/.active` marker; update the content to remove or correct
those statements and instead clarify Codex's actual mechanisms: mention that
Codex does not expose PreToolUse hooks, that its hook-like integration is
limited to `notify` (invoked when an agent finishes a turn), and that tool
execution control is handled via `approval_policy` and Rules (e.g., `.rules`
files and `prefix_rule`), replacing the inaccurate lines about PreToolUse
operating the same way.
---
Duplicate comments:
In `@docs/README.codex.md`:
- Line 82: The doc uses the label "superpowers" but the namespace prefix in the
PR is `superpowers-ng:`, so update all occurrences of the tier label
"superpowers" (notably the phrases at the current lines referencing the third
tier and the "Superpowers skills" section) to "superpowers-ng" or
"Superpowers-ng" to match the `superpowers-ng:` namespace; search for the
literal "superpowers" in README.codex.md (including the block around lines 82
and 107–113) and replace the tier labels and any headings so they consistently
reflect `superpowers-ng:` across the document.
---
Nitpick comments:
In `@docs/README.codex.md`:
- Line 121: The README uses a backtick-wrapped `$skill-name` which is
inconsistent with other mentions (e.g., "use brainstorming") and reads like a
shell variable; update the `Skill` tool documentation to use the plain name
invocation format instead (replace `$skill-name` with a concrete example such as
"use brainstorming" or "invoke brainstorming" wherever `Skill` or `$skill-name`
appears) and add one short concrete example sentence showing the invocation to
match the style used on Line 57.
| The `manus-planning` skill works on Codex with these considerations: | ||
|
|
||
| - The 3-file system (`task_plan.md`, `findings.md`, `progress.md`) works identically | ||
| - PreToolUse hooks via `docs/manus/.active` marker operate the same way |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, examine the file to understand the context
head -n 145 docs/README.codex.md | tail -n 20Repository: obra/superpowers
Length of output: 960
🌐 Web query:
OpenAI Codex CLI hook system PreToolUse support documentation
💡 Result:
Codex CLI does not document/support a Claude-style hook system with lifecycle events like PreToolUse. In the current Codex configuration docs, the only “hook-like” integration point is notify: a command Codex invokes when the agent finishes a turn, passing a JSON payload. [1], [2]
If your goal is to block or gate potentially dangerous tool/command execution (the typical PreToolUse use case), Codex’s documented mechanisms are:
approval_policy: controls when Codex pauses for approval before executing commands. [1]- Rules (
.rulesfiles /prefix_rule): control which commands can run outside the sandbox (allow/prompt/forbidden), and can be tested withcodex execpolicy check. [3]
Sources
[1] Codex “Configuration Reference” (includes approval_policy, notify) (developers.openai.com)
[2] Codex repo docs/config.md (mentions notify runs when an agent finishes a turn) (raw.githubusercontent.com)
[3] Codex “Rules” documentation (prefix_rule, decisions, codex execpolicy check) (developers.openai.com)
Citations:
- 1: https://developers.openai.com/codex/config-reference
- 2: https://raw.githubusercontent.com/openai/codex/main/docs/config.md
- 3: https://developers.openai.com/codex/rules
🌐 Web query:
Claude Code PreToolUse hooks documentation API reference
💡 Result:
Anthropic’s official Claude Code “PreToolUse” hook API reference is documented in the Claude Code Hooks reference:
- Hooks reference (API / schema, events, inputs/outputs, decision control): https://docs.anthropic.com/en/docs/claude-code/hooks [1]
- PreToolUse definition: runs after Claude creates tool parameters and before executing the tool call. Common matchers include
Bash,Read,Write,Edit|MultiEdit,WebFetch,WebSearch, etc. [1] - Config structure:
hooks -> PreToolUse -> [{ matcher, hooks: [{ type:"command", command }] }]in~/.claude/settings.jsonor.claude/settings.json/.claude/settings.local.json. [1] - Input payload (stdin): includes
hook_event_name,tool_name, andtool_input(tool-dependent). [1] - Output/behavior: via exit codes (notably exit code
2blocks PreToolUse tool execution) or JSON output; PreToolUse can returnhookSpecificOutput.permissionDecision: "allow" | "deny" | "ask"(+ reason) to control execution. [1]
- PreToolUse definition: runs after Claude creates tool parameters and before executing the tool call. Common matchers include
If you want a companion “how-to” (not the reference), Anthropic’s Get started with Claude Code hooks guide includes a PreToolUse example and points back to the reference for full details: https://docs.anthropic.com/en/docs/claude-code/hooks-guide [2]
Remove or correct claims about Codex CLI supporting PreToolUse hooks—Codex does not expose this mechanism.
OpenAI Codex CLI does not document or support PreToolUse hooks as found in Claude Code. Codex's hook-like integration is limited to notify (invoked when the agent finishes a turn), and tool execution control relies on approval_policy and Rules (.rules files / prefix_rule), not PreToolUse. Stating that PreToolUse hooks "operate the same way" on Codex (lines 129 and 138) is inaccurate and will mislead users into expecting functionality that does not exist.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/README.codex.md` at line 129, The README incorrectly claims Codex CLI
supports PreToolUse hooks via the `docs/manus/.active` marker; update the
content to remove or correct those statements and instead clarify Codex's actual
mechanisms: mention that Codex does not expose PreToolUse hooks, that its
hook-like integration is limited to `notify` (invoked when an agent finishes a
turn), and that tool execution control is handled via `approval_policy` and
Rules (e.g., `.rules` files and `prefix_rule`), replacing the inaccurate lines
about PreToolUse operating the same way.
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
Added three-tier skill resolution to Codex CLI enabling project-local skills in
.codex/skills/directory alongside personal and superpowers tiers. Skills can be invoked with explicit namespace prefixes (project:,superpowers-ng:) or resolved by priority.Changes
process.cwd(), skill listing with priority order, and namespace prefix support🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation
Improvements