feat: add agent template rendering workflow #353
Conversation
📝 WalkthroughWalkthroughA comprehensive template-and-render system is introduced to generate agent-specific documentation, configurations, and test artifacts from centralized templates with placeholder substitution and partial inclusion, enabling deterministic rendering across Claude, Codex, and OpenCode agents. Changes
Sequence DiagramsequenceDiagram
actor User
participant CLI as Agent CLI
participant Renderer as render-agent.js
participant Config as Agent Config<br/>(agents/*.json)
participant Targets as Targets Map<br/>(templates/targets.json)
participant Templates as Template Files<br/>(templates/...)
participant Output as Output Files<br/>(docs/, .codex/, etc)
User->>CLI: Invoke render-agent.js<br/>--agent codex --write
CLI->>Renderer: Parse args
Renderer->>Config: Load agents/codex.json
Config-->>Renderer: Agent metadata<br/>(AGENT_ID, SKILLS_DIR, etc)
Renderer->>Targets: Load templates/targets.json
Targets-->>Renderer: Target mappings<br/>(template → output)
loop For each target
Renderer->>Templates: Load template file
Templates-->>Renderer: Template content<br/>with {{PLACEHOLDERS}}
Renderer->>Renderer: Resolve {{VAR}}<br/>from agent config
Renderer->>Renderer: Include partials<br/>{{> partial-path}}
Renderer->>Renderer: Validate unresolved<br/>placeholders
end
Renderer->>Output: Write rendered files<br/>(--write mode)
Output-->>Renderer: Files written
Renderer-->>CLI: Success summary<br/>(X files rendered)
CLI-->>User: Output & exit code
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
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: 5
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🤖 Fix all issues with AI agents
In `@skills/writing-skills/testing-skills-with-subagents.md`:
- Line 15: The documentation line "**Complete worked example:** See
examples/CLAUDE_MD_TESTING.md ..." references a missing path; update that
reference to the correct relative location of the example file (replace the
incorrect "examples/CLAUDE_MD_TESTING.md" with the correct path to
CLAUDE_MD_TESTING.md, e.g., "./examples/CLAUDE_MD_TESTING.md" or
"skills/writing-skills/examples/CLAUDE_MD_TESTING.md") so the link points to the
actual file; edit the string in the markdown where "**Complete worked
example:**" appears.
In `@templates/docs/README.codex.md`:
- Around line 36-40: The README template uses hardcoded "Codex" and ".codex"
instead of the template placeholders, so update the command string to use the
placeholders: replace the literal "Codex" with {{AGENT_NAME}} and replace the
".codex" directory with ".{{AGENT_ID}}", ensuring the example command becomes:
Run {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} find-skills to
show available skills so template substitution can work correctly.
- Around line 91-104: Replace hardcoded ".codex" paths in the Architecture
section with the template variables already present (use
{{SUPERPOWERS_DIR}}/.superpowers or another provided dir variable instead of
literal ".codex") and make the shared core module path generic by removing the
codex-specific prefix (e.g., reference the module as
{{SUPERPOWERS_DIR}}/superpowers/lib/skills-core.js or simply
./lib/skills-core.js or the package name "superpowers/lib/skills-core.js");
update the occurrences around the CLI Location line
(`{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}}`) and the Shared Core
Module path (`~/.codex/superpowers/lib/skills-core.js`) to use these
variables/placeholders so no hardcoded ".codex" remains and the core module path
is not codex-specific.
- Around line 48-62: Replace hardcoded ".codex" directory segments in the three
command examples by templating the agent-specific hidden folder so the commands
point to .{{AGENT_ID}}; specifically update the occurrences of
".codex/superpowers-{{AGENT_ID}}" used with the commands "find-skills",
"use-skill superpowers:brainstorming", and "bootstrap" to
".{{AGENT_ID}}/superpowers-{{AGENT_ID}}" so the template substitutes the correct
per-agent directory.
In `@templates/tests/subagent-driven-dev/go-fractals/scaffold.sh`:
- Around line 14-41: The script fails in CI because git commit in scaffold.sh
runs without local user config; update the scaffold.sh sequence (after git init
and before git commit) to set a local git user and email for this repo (e.g.,
via git config user.name and git config user.email or using repo-local config)
so the commit succeeds; ensure these configs are set in the same script before
the git add/git commit steps.
🟡 Minor comments (17)
templates/tests/skill-triggering/prompts/executing-plans.txt-1-1 (1)
1-1: The referenced plan filedocs/plans/2024-01-15-auth-system.mddoes not exist.No test fixture creates this file. Update the prompt to reference an existing plan file from
docs/plans/(e.g., one of the 2025 or 2026 dated plans), or add test scaffolding to create this fixture before execution.templates/skills/writing-skills/examples/CLAUDE_MD_TESTING.md-8-19 (1)
8-19: Add language identifiers to fenced blocks to satisfy MD040.
The scenario blocks currently omit a language tag, which markdownlint flags.✍️ Suggested update
-``` +```text IMPORTANT: This is a real scenario. Choose and act. ... -``` +```text IMPORTANT: This is a real scenario. Choose and act. ... -``` +```text IMPORTANT: This is a real scenario. Choose and act. ... -``` +```text IMPORTANT: This is a real scenario. Choose and act. ...Also applies to: 22-36, 39-50, 53-62
docs/plans/2026-01-24-agent-templates-implementation.md-206-211 (1)
206-211: Plan document contains incorrect partial loading logic.The
renderTemplatefunction code shown in lines 206-211 has a bug: it extracts the extension fromname(which already includes the extension), then passes both toloadPartial. This would produce incorrect file paths likeskills-table.md.claude.md.The actual implementation in
scripts/render-agent.js(lines 46-65) already has the correct logic—it usespath.extname()and properly strips the extension before building paths. The plan document's code snippet should be updated to match the correct implementation:Correct implementation (already in scripts/render-agent.js)
function loadPartial(name, templateExt) { const ext = path.extname(name) || (templateExt || ''); const extName = ext.startsWith('.') ? ext.slice(1) : ext; const base = ext ? name.slice(0, -ext.length) : name; const candidateAgent = path.join(partialsDir, `${base}.${agent}.${extName}`); const candidateDefault = path.join(partialsDir, `${base}.${extName}`); if (fs.existsSync(candidateAgent)) return fs.readFileSync(candidateAgent, 'utf8'); if (fs.existsSync(candidateDefault)) return fs.readFileSync(candidateDefault, 'utf8'); throw new Error(`Missing partial "${name}" for agent "${agent}"`); }Update the plan document to reflect the correct implementation already in
scripts/render-agent.jsto avoid confusion.templates/skills/writing-skills/SKILL.md-556-556 (1)
556-556: Inconsistent cross-reference syntax.Line 556 uses
@testing-skills-with-subagents.md, but the document's own guidance (lines 280-289) explicitly warns against using@syntax to avoid force-loading files and consuming context unnecessarily.📝 Suggested fix
-**Testing methodology:** See `@testing-skills-with-subagents.md` for the complete testing methodology: +**Testing methodology:** See testing-skills-with-subagents.md for the complete testing methodology:templates/skills/writing-skills/SKILL.md-316-316 (1)
316-316: Inconsistent cross-reference syntax.Line 316 uses
@graphviz-conventions.dot, but lines 280-289 explicitly warn against using@syntax because it "force-loads files immediately, consuming 200k+ context before you need them." The guidance recommends using skill names only with explicit requirement markers.📝 Suggested fix
-See `@graphviz-conventions.dot` for graphviz style rules. +See graphviz-conventions.dot for graphviz style rules.Or if this needs to be a required reference:
-See `@graphviz-conventions.dot` for graphviz style rules. +**REQUIRED REFERENCE:** See graphviz-conventions.dot for graphviz style rules.docs/README.opencode.md-1-12 (1)
1-12: Add a language identifier to the Quick Install fenced block.The quick-install code fence is missing a language tag, which triggers MD040. Use a neutral label like
textto keep lint clean.🔧 Suggested fix
-``` +```text Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart OpenCode.</details> </blockquote></details> <details> <summary>templates/tests/claude-code/run-skill-tests.sh-31-111 (1)</summary><blockquote> `31-111`: **Harden CLI arg validation and fail when a requested test is missing.** With `set -u`, a missing value for `--test` or `--timeout` causes an unset variable error with unhelpful messaging. Additionally, when a user explicitly requests a specific test via `--test` that doesn't exist, the script reports SKIP and exits 0 instead of treating it as a failure. <details> <summary>🐛 Proposed fix</summary> ```diff --test|-t) - SPECIFIC_TEST="$2" - shift 2 + if [ $# -lt 2 ] || [[ "$2" == -* ]]; then + echo "ERROR: --test requires a test filename" + exit 1 + fi + SPECIFIC_TEST="$2" + shift 2 ;; --timeout) - TIMEOUT="$2" - shift 2 + if [ $# -lt 2 ] || [[ "$2" == -* ]]; then + echo "ERROR: --timeout requires a number of seconds" + exit 1 + fi + TIMEOUT="$2" + shift 2 ;; @@ - if [ ! -f "$test_path" ]; then - echo " [SKIP] Test file not found: $test" - skipped=$((skipped + 1)) - continue - fi + if [ ! -f "$test_path" ]; then + if [ -n "$SPECIFIC_TEST" ]; then + echo " [FAIL] Test file not found: $test" + failed=$((failed + 1)) + else + echo " [SKIP] Test file not found: $test" + skipped=$((skipped + 1)) + fi + continue + fitemplates/tests/subagent-driven-dev/go-fractals/design.md-51-66 (1)
51-66: Add a language hint to the architecture code block.The fenced code block at lines 51–66 lacks a language identifier, triggering markdownlint's MD040 rule. Adding
textimproves compliance and readability.✍️ Suggested edit
-``` +```text cmd/ fractals/ main.go # Entry point, CLI setup internal/ sierpinski/ sierpinski.go # Algorithm sierpinski_test.go mandelbrot/ mandelbrot.go # Algorithm mandelbrot_test.go cli/ root.go # Root command, help sierpinski.go # Sierpinski subcommand mandelbrot.go # Mandelbrot subcommand</details> </blockquote></details> <details> <summary>templates/docs/README.codex.md-140-148 (1)</summary><blockquote> `140-148`: **Hardcoded paths in Troubleshooting section.** Lines 141 and 147 use hardcoded `.codex` paths instead of `.{{AGENT_ID}}`. <details> <summary>🔧 Proposed fix</summary> ```diff -2. Check CLI works: `{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} find-skills` +2. Check CLI works: `{{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} find-skills` 3. Verify skills have SKILL.md files ### CLI script not executable ```bash -chmod +x {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} +chmod +x {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}}</details> </blockquote></details> <details> <summary>docs/plans/2026-01-24-agent-templates-design.md-3-6 (1)</summary><blockquote> `3-6`: **Update the status to reflect current implementation state.** The PR includes implementation, so “Awaiting Implementation” reads stale. Consider “In progress” or “Implemented” to avoid confusion. </blockquote></details> <details> <summary>templates/tests/opencode/test-tools.sh-29-36 (1)</summary><blockquote> `29-36`: **Treat non-timeout non-zero exits as failures.** Right now a non-timeout failure can still let the test pass if output matches. That risks masking real errors. <details> <summary>🛠️ Proposed fix (apply to all three blocks)</summary> ```diff - echo " [WARN] OpenCode returned non-zero exit code: $exit_code" + echo " [FAIL] OpenCode returned non-zero exit code: $exit_code" + exit 1Also applies to: 60-67, 84-91
templates/tests/opencode/test-plugin-loading.sh-61-66 (1)
61-66: Run the syntax check against the resolved plugin symlink target.
plugin_filepoints to a different path than the verified symlink target, which can create false negatives if the layout changes. Use the symlink target you already validated.🛠️ Proposed fix
-plugin_file="$HOME/.config/opencode/superpowers/.opencode/plugins/superpowers.js" -if node --check "$plugin_file" 2>/dev/null; then +plugin_file="$(readlink -f "$HOME/.config/opencode/plugins/superpowers.js")" +if node --check "$plugin_file" 2>/dev/null; thentemplates/skills/writing-skills/testing-skills-with-subagents.md-184-199 (1)
184-199: Add a language identifier to the fenced block flagged by markdownlint (MD040).One fenced block is missing a language spec (reported at Line 199). Add a language tag to keep markdownlint clean.
🛠️ Example fix
-``` +```markdown ... -``` +```templates/tests/opencode/run-tests.sh-32-34 (1)
32-34:--testoption lacks validation for missing argument.If
--testis passed without a value (e.g., as the last argument),shift 2will fail or$2will be unset. Add a check for the argument.Proposed fix
--test|-t) + if [[ -z "${2:-}" ]]; then + echo "Error: --test requires a test name" + exit 1 + fi SPECIFIC_TEST="$2" shift 2 ;;templates/tests/claude-code/test-subagent-driven-development-integration.sh-152-157 (1)
152-157:$?captures exit code ofecho, not the pipeline.At line 155,
$?reflects the exit code of the precedingechostatement (line 154), not thetimeout ... | teepipeline. Capture the exit code immediately after the pipeline.Proposed fix
echo "Running {{AGENT_NAME}} (output will be shown below and saved to $OUTPUT_FILE)..." echo "================================================================================" -cd "$SCRIPT_DIR/../.." && timeout 1800 {{CLI_CMD}} -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions 2>&1 | tee "$OUTPUT_FILE" || { +cd "$SCRIPT_DIR/../.." && timeout 1800 {{CLI_CMD}} -p "$PROMPT" --allowed-tools=all --add-dir "$TEST_PROJECT" --permission-mode bypassPermissions 2>&1 | tee "$OUTPUT_FILE" +exit_code=${PIPESTATUS[0]} +if [ "$exit_code" -ne 0 ]; then echo "" echo "================================================================================" - echo "EXECUTION FAILED (exit code: $?)" + echo "EXECUTION FAILED (exit code: $exit_code)" exit 1 -} +fi echo "================================================================================"templates/tests/claude-code/analyze-token-usage.py-67-68 (1)
67-68: Bareexceptsilently swallows all exceptions, includingKeyboardInterrupt.The bare
except: passhides JSON parsing errors, making debugging difficult. At minimum, catchjson.JSONDecodeError(orValueErrorfor broader compat) and consider logging skipped lines.Proposed fix
- except: - pass + except (json.JSONDecodeError, KeyError) as e: + # Skip malformed lines; optionally log for debugging + passtemplates/tests/claude-code/test-helpers.sh-6-29 (1)
6-29: Command construction via string interpolation is fragile with special characters.Building the command as a string and passing to
bash -ccan break if$promptcontains quotes or special characters. Consider using an array for the command.Proposed fix using array
run_claude() { local prompt="$1" local timeout="${2:-60}" local allowed_tools="${3:-}" - local output_file=$(mktemp) + local output_file + output_file=$(mktemp) - # Build command - local cmd="{{CLI_CMD}} -p \"$prompt\"" - if [ -n "$allowed_tools" ]; then - cmd="$cmd --allowed-tools=$allowed_tools" - fi + # Build command array + local cmd=({{CLI_CMD}} -p "$prompt") + if [ -n "$allowed_tools" ]; then + cmd+=(--allowed-tools="$allowed_tools") + fi - # Run {{AGENT_NAME}} in headless mode with timeout - if timeout "$timeout" bash -c "$cmd" > "$output_file" 2>&1; then + # Run {{AGENT_NAME}} in headless mode with timeout + if timeout "$timeout" "${cmd[@]}" > "$output_file" 2>&1; then cat "$output_file" rm -f "$output_file" return 0
🧹 Nitpick comments (25)
templates/tests/subagent-driven-dev/svelte-todo/design.md (1)
19-32: Consider adding language identifiers to fenced code blocks.Per markdownlint, fenced code blocks should have a language specified. For ASCII diagrams like this UI mock, you can use
textorplaintextas the language identifier.📝 Suggested fix
-``` +```text ┌─────────────────────────────────────────┐Similarly for the component structure block at line 36.
docs/plans/2026-01-24-agent-templates-implementation.md (1)
406-423: Missing language specifiers in fenced code blocks.The nested code blocks demonstrating the "Templates & Rendering" section lack language specifiers, which affects syntax highlighting and linting compliance.
📝 Suggested fix
```markdown ### Templates & Rendering Source files live in `templates/`. Regenerate agent‑specific outputs with: -``` +```bash node scripts/render-agent.js --agent codex --write node scripts/render-agent.js --agent claude --write node scripts/render-agent.js --agent opencode --writeValidate all templates:
-
+bash
bash tests/render-templates.sh</details> </blockquote></details> <details> <summary>templates/skills/using-git-worktrees/SKILL.md (1)</summary><blockquote> `42-49`: **Consider adding language specifiers to fenced code blocks.** The static analysis tool flagged three fenced code blocks without language identifiers. While these blocks contain text/narrative content rather than code, adding `text` or `markdown` identifiers would improve formatting consistency. <details> <summary>💅 Proposed formatting improvement</summary> Line 42-49: ```diff -``` +```text No worktree directory found. Where should I create worktrees?Line 138-142:
-``` +```text Worktree ready at <full-path>Line 180-192:
-``` +```text You: I'm using the using-git-worktrees skill to set up an isolated workspace.Also applies to: 138-142, 180-192
templates/skills/writing-skills/SKILL.md (1)
199-199: Add language specifier for consistency.The fenced code block contains YAML examples and should have a language identifier for proper syntax highlighting.
💅 Proposed formatting improvement
-``` +```yaml # ❌ BAD: Too abstract, vague, doesn't include when to usetemplates/README.md (2)
54-59: Consider adding a language spec to the output example block.Static analysis suggests adding a language identifier to this fenced code block. While it's showing expected output rather than executable code, adding
textorplaintextas the language identifier would satisfy the linter and improve consistency.📝 Proposed fix
-``` +```text # Should see: # /superpowers:brainstorm - Interactive design refinement # /superpowers:write-plan - Create implementation plan # /superpowers:execute-plan - Execute plan in batches</details> --- `175-176`: **Wrap bare URLs in markdown link syntax.** The bare URLs should follow markdown best practices by using link syntax for better readability and consistency. <details> <summary>🔗 Proposed fix</summary> ```diff ## Support -- **Issues**: https://github.com/obra/superpowers/issues -- **Marketplace**: https://github.com/obra/superpowers-marketplace +- **Issues**: [https://github.com/obra/superpowers/issues](https://github.com/obra/superpowers/issues) +- **Marketplace**: [https://github.com/obra/superpowers-marketplace](https://github.com/obra/superpowers-marketplace)templates/.opencode/INSTALL.md (3)
49-51: Add language specifier to fenced code block.Per MD040, fenced code blocks should have a language specified for proper syntax highlighting and accessibility.
Proposed fix
-``` +```text use skill tool to list skills</details> --- `57-59`: **Add language specifier to fenced code block.** Same issue—add a language specifier for consistency. <details> <summary>Proposed fix</summary> ```diff -``` +```text use skill tool to load superpowers/brainstorming</details> --- `119-120`: **Consider using proper Markdown link syntax for URLs.** Per MD034, bare URLs should be avoided. Use proper link syntax for better rendering across Markdown parsers. <details> <summary>Proposed fix</summary> ```diff -- Report issues: https://github.com/obra/superpowers/issues -- Full documentation: https://github.com/obra/superpowers/blob/main/docs/README.opencode.md +- Report issues: <https://github.com/obra/superpowers/issues> +- Full documentation: <https://github.com/obra/superpowers/blob/main/docs/README.opencode.md>templates/tests/skill-triggering/run-all.sh (3)
1-5: Consider addingpipefailto catch pipeline failures.With
set -ealone, ifrun-test.shfails butteesucceeds, the pipeline exit code will be 0 (fromtee), potentially masking failures. Addingpipefailensures the pipeline fails if any command in it fails.Proposed fix
#!/bin/bash # Run all skill triggering tests # Usage: ./run-all.sh -set -e +set -eo pipefail
29-32: Skipped skills are not tracked in the summary.When a prompt file is missing, the skill is skipped but not recorded in
RESULTSor counted. Consider adding aSKIPPEDcounter for completeness.Proposed enhancement
PASSED=0 FAILED=0 +SKIPPED=0 RESULTS=() for skill in "${SKILLS[@]}"; do prompt_file="$PROMPTS_DIR/${skill}.txt" if [ ! -f "$prompt_file" ]; then echo "⚠️ SKIP: No prompt file for $skill" + SKIPPED=$((SKIPPED + 1)) + RESULTS+=("⚠️ $skill (skipped)") continue fiAnd in the summary section:
echo "Passed: $PASSED" echo "Failed: $FAILED" +echo "Skipped: $SKIPPED"
36-36: Document the purpose of the hardcoded3argument.The third argument passed to
run-test.shis undocumented. Consider adding a comment or using a named variable to clarify its purpose (e.g., retry count, timeout, verbosity level).+ # Third argument is the number of retries (or timeout/attempts) + RETRIES=3 if "$SCRIPT_DIR/run-test.sh" "$skill" "$prompt_file" 3 2>&1 | tee /tmp/skill-test-$skill.log; thentemplates/tests/subagent-driven-dev/svelte-todo/scaffold.sh (2)
21-37: Template placeholders are intentional; Shellcheck warnings can be ignored.The
{{AGENT_ID}}and{{CLI_CMD}}syntax are template placeholders designed to be substituted by the rendering pipeline (render-agent.js). The Shellcheck warnings about literal braces are false positives in this context.Consider adding a comment at the top of the file to clarify this is a template:
#!/bin/bash # Scaffold the Svelte Todo test project # Usage: ./scaffold.sh /path/to/target/directory +# +# NOTE: This file is a template. Placeholders like {{AGENT_ID}} and {{CLI_CMD}} +# are substituted during rendering via render-agent.js.
14-15: Consider using--quietflag forgit initfor consistency.Other scripts in the test suite (e.g.,
test-subagent-driven-development-integration.shline 108) usegit init --quietto suppress output. Consider the same here for cleaner scaffold output.Proposed fix
# Initialize git repo -git init +git init --quiettemplates/tests/claude-code/README.md (1)
112-115: Trim adverb repetition in “What it tests” bullets.Small wording cleanup for readability.
✍️ Suggested edit
- - Our improvements are actually applied + - Our improvements are appliedBased on static analysis hints, ...
templates/tests/opencode/setup.sh (1)
10-11: Separate declaration and assignment to preserve exit codes.Combining
exportwith command substitution masks the return value ofmktemp. Ifmktempfails, the exit code is lost. Whileset -eprovides some protection, separating them is safer and clearer.♻️ Proposed fix
-export TEST_HOME=$(mktemp -d) +TEST_HOME=$(mktemp -d) +export TEST_HOMEtemplates/docs/README.opencode.md (2)
324-328: Use markdown link syntax for bare URLs.The bare URLs on lines 326-328 should use proper markdown link syntax for consistency with the rest of the document and to satisfy linting rules.
♻️ Proposed fix
## Getting Help -- Report issues: https://github.com/obra/superpowers/issues -- Main documentation: https://github.com/obra/superpowers -- OpenCode docs: https://opencode.ai/docs/ +- Report issues: <https://github.com/obra/superpowers/issues> +- Main documentation: <https://github.com/obra/superpowers> +- OpenCode docs: <https://opencode.ai/docs/>
10-12: Consider adding language identifier to fenced code blocks.The code blocks on lines 10, 176, and 184 lack language identifiers. For user prompt examples, consider using
textor leaving them as-is if the intent is to show plain text instructions.Also applies to: 176-178, 184-186
templates/tests/skill-triggering/run-test.sh (1)
63-67: Inconsistent output formatting between test scripts.This script uses emoji (✅, ❌) for PASS/FAIL output, while
explicit-skill-requests/run-test.shuses plain text. Consider aligning the output format across test scripts for consistency.scripts/render-agent.js (1)
7-10: Edge case: missing argument value returnsundefined, notnull.If a flag is provided but its value is missing (e.g.,
--agentas the last argument),args[idx + 1]returnsundefined, notnull. This could cause subtle issues since the check on line 18 uses!agentwhich treats bothnullandundefinedthe same way, but the inconsistency could cause confusion.♻️ Proposed fix
function arg(name) { const idx = args.indexOf(name); - return idx === -1 ? null : args[idx + 1]; + return idx === -1 ? null : (args[idx + 1] ?? null); }templates/tests/claude-code/analyze-token-usage.py (1)
76-81: Cost calculation treats cache tokens the same as regular input tokens.The
calculate_costfunction sumscache_creationandcache_readtokens withinput_tokensat the same rate. If the actual API pricing differs for cached tokens (e.g., discounted cache reads), the estimate will be inaccurate. Consider documenting this assumption or adding separate rate parameters.templates/tests/opencode/test-skills-core.sh (1)
369-378: Test creates git repo and changes directory but doesn't restore PWD before trap fires.The
cd "$TEST_HOME/test-repo"at line 371 changes the working directory. While line 378 doescd "$SCRIPT_DIR", if any command between them fails (due toset -e), the script exits without restoring the directory. This could cause cleanup issues ifcleanup_test_envrelies on the original working directory. Consider using a subshell orpushd/popd.Safer approach using subshell
-# Create a test git repo -mkdir -p "$TEST_HOME/test-repo" -cd "$TEST_HOME/test-repo" -git init --quiet -git config user.email "[email protected]" -git config user.name "Test" -echo "test" > file.txt -git add file.txt -git commit -m "initial" --quiet -cd "$SCRIPT_DIR" +( + # Create a test git repo in subshell to preserve working directory + mkdir -p "$TEST_HOME/test-repo" + cd "$TEST_HOME/test-repo" + git init --quiet + git config user.email "[email protected]" + git config user.name "Test" + echo "test" > file.txt + git add file.txt + git commit -m "initial" --quiet +)templates/tests/claude-code/test-subagent-driven-development-integration.sh (1)
29-29: Trap expands$TEST_PROJECTat definition time, not signal time.Using double quotes means
$TEST_PROJECTis expanded when the trap is set. IfTEST_PROJECTwere modified later, the trap would use the old value. In this case it's likely fine sinceTEST_PROJECTis set on line 25 before the trap, but using single quotes is safer practice.Proposed fix
-trap "cleanup_test_project $TEST_PROJECT" EXIT +trap 'cleanup_test_project "$TEST_PROJECT"' EXITtemplates/tests/opencode/run-tests.sh (1)
101-104: Auto-chmod on test files may mask permission issues.Automatically making test files executable hides potential deployment problems where files should already be executable. Consider emitting a warning instead.
templates/tests/claude-code/test-helpers.sh (1)
127-139: Declare and assign separately to avoid masking return values.Per SC2155,
local var=$(cmd)masks the command's exit status. Whilemktemprarely fails, separating declaration and assignment is safer.Proposed fix
create_test_project() { - local test_dir=$(mktemp -d) + local test_dir + test_dir=$(mktemp -d) echo "$test_dir" }
| **REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables). | ||
|
|
||
| **Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants. | ||
| **Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing AGENTS.md / CLAUDE.md documentation variants. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and examine line 15
fd -t f "testing-skills-with-subagents.md"Repository: obra/superpowers
Length of output: 179
🏁 Script executed:
# Look at the context around line 15 in the file
if [ -f "skills/writing-skills/testing-skills-with-subagents.md" ]; then
sed -n '10,20p' "skills/writing-skills/testing-skills-with-subagents.md"
fiRepository: obra/superpowers
Length of output: 679
🏁 Script executed:
# Check for AGENTS.md and CLAUDE.md files
fd -t f -i "agents\.md"
fd -t f -i "claude\.md"Repository: obra/superpowers
Length of output: 179
🏁 Script executed:
# Check if the example file exists
if [ -f "examples/CLAUDE_MD_TESTING.md" ]; then
echo "✓ Example file exists: examples/CLAUDE_MD_TESTING.md"
wc -l "examples/CLAUDE_MD_TESTING.md"
else
echo "✗ Example file not found"
fiRepository: obra/superpowers
Length of output: 84
🏁 Script executed:
# Search for references to AGENTS.md and CLAUDE.md in the repository
rg "AGENTS\.md|CLAUDE\.md" --type md -lRepository: obra/superpowers
Length of output: 752
Fix broken file path reference in documentation.
The referenced example file examples/CLAUDE_MD_TESTING.md does not exist at that path. The file is actually located at skills/writing-skills/examples/CLAUDE_MD_TESTING.md. Update the documentation reference to use the correct relative path (e.g., ./examples/CLAUDE_MD_TESTING.md if in the same directory, or the full path from the repository root).
🤖 Prompt for AI Agents
In `@skills/writing-skills/testing-skills-with-subagents.md` at line 15, The
documentation line "**Complete worked example:** See
examples/CLAUDE_MD_TESTING.md ..." references a missing path; update that
reference to the correct relative location of the example file (replace the
incorrect "examples/CLAUDE_MD_TESTING.md" with the correct path to
CLAUDE_MD_TESTING.md, e.g., "./examples/CLAUDE_MD_TESTING.md" or
"skills/writing-skills/examples/CLAUDE_MD_TESTING.md") so the link points to the
actual file; edit the string in the markdown where "**Complete worked
example:**" appears.
| Tell Codex: | ||
|
|
||
| ``` | ||
| Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} find-skills to show available skills | ||
| ``` |
There was a problem hiding this comment.
Hardcoded "Codex" breaks template substitution.
Line 36 uses hardcoded "Codex" instead of the {{AGENT_NAME}} placeholder, and lines 39 uses hardcoded .codex paths instead of .{{AGENT_ID}}. This template is designed for variable substitution but these values won't be replaced during rendering.
🔧 Proposed fix
-Tell Codex:
+Tell {{AGENT_NAME}}:
-Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} find-skills to show available skills
+Run {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} find-skills to show available skills
🤖 Prompt for AI Agents
In `@templates/docs/README.codex.md` around lines 36 - 40, The README template
uses hardcoded "Codex" and ".codex" instead of the template placeholders, so
update the command string to use the placeholders: replace the literal "Codex"
with {{AGENT_NAME}} and replace the ".codex" directory with ".{{AGENT_ID}}",
ensuring the example command becomes: Run
{{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} find-skills to show
available skills so template substitution can work correctly.
| ``` | ||
| Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} find-skills | ||
| ``` | ||
|
|
||
| ### Loading a Skill | ||
|
|
||
| ``` | ||
| Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} use-skill superpowers:brainstorming | ||
| ``` | ||
|
|
||
| ### Bootstrap All Skills | ||
|
|
||
| ``` | ||
| Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} bootstrap | ||
| ``` |
There was a problem hiding this comment.
Additional hardcoded .codex paths need templating.
Lines 49, 55, and 61 all contain hardcoded .codex paths that should use .{{AGENT_ID}} for proper template substitution.
🔧 Proposed fix
-Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} find-skills
+Run {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} find-skills
### Loading a Skill
-Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} use-skill superpowers:brainstorming
+Run {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} use-skill superpowers:brainstorming
### Bootstrap All Skills
-Run {{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}} bootstrap
+Run {{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}} bootstrap
🤖 Prompt for AI Agents
In `@templates/docs/README.codex.md` around lines 48 - 62, Replace hardcoded
".codex" directory segments in the three command examples by templating the
agent-specific hidden folder so the commands point to .{{AGENT_ID}};
specifically update the occurrences of ".codex/superpowers-{{AGENT_ID}}" used
with the commands "find-skills", "use-skill superpowers:brainstorming", and
"bootstrap" to ".{{AGENT_ID}}/superpowers-{{AGENT_ID}}" so the template
substitutes the correct per-agent directory.
| ### {{AGENT_NAME}} CLI Tool | ||
|
|
||
| **Location:** `{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}}` | ||
|
|
||
| A Node.js CLI script that provides three commands: | ||
| - `bootstrap` - Load complete bootstrap with all skills | ||
| - `use-skill <name>` - Load a specific skill | ||
| - `find-skills` - List all available skills | ||
|
|
||
| ### Shared Core Module | ||
|
|
||
| **Location:** `~/.codex/superpowers/lib/skills-core.js` | ||
|
|
||
| The {{AGENT_NAME}} 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. |
There was a problem hiding this comment.
Hardcoded paths in Architecture section.
Lines 93 and 102 contain hardcoded .codex paths. The shared core module path on line 102 also appears to be codex-specific (~/.codex/superpowers/lib/skills-core.js).
🔧 Proposed fix
### {{AGENT_NAME}} CLI Tool
-**Location:** `{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}}`
+**Location:** `{{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}}`
A Node.js CLI script that provides three commands:
- `bootstrap` - Load complete bootstrap with all skills
- `use-skill <name>` - Load a specific skill
- `find-skills` - List all available skills
### Shared Core Module
-**Location:** `~/.codex/superpowers/lib/skills-core.js`
+**Location:** `~/.{{AGENT_ID}}/superpowers/lib/skills-core.js`📝 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.
| ### {{AGENT_NAME}} CLI Tool | |
| **Location:** `{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}}` | |
| A Node.js CLI script that provides three commands: | |
| - `bootstrap` - Load complete bootstrap with all skills | |
| - `use-skill <name>` - Load a specific skill | |
| - `find-skills` - List all available skills | |
| ### Shared Core Module | |
| **Location:** `~/.codex/superpowers/lib/skills-core.js` | |
| The {{AGENT_NAME}} 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. | |
| ### {{AGENT_NAME}} CLI Tool | |
| **Location:** `{{SUPERPOWERS_DIR}}/.{{AGENT_ID}}/superpowers-{{AGENT_ID}}` | |
| A Node.js CLI script that provides three commands: | |
| - `bootstrap` - Load complete bootstrap with all skills | |
| - `use-skill <name>` - Load a specific skill | |
| - `find-skills` - List all available skills | |
| ### Shared Core Module | |
| **Location:** `~/.{{AGENT_ID}}/superpowers/lib/skills-core.js` | |
| The {{AGENT_NAME}} 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. |
🤖 Prompt for AI Agents
In `@templates/docs/README.codex.md` around lines 91 - 104, Replace hardcoded
".codex" paths in the Architecture section with the template variables already
present (use {{SUPERPOWERS_DIR}}/.superpowers or another provided dir variable
instead of literal ".codex") and make the shared core module path generic by
removing the codex-specific prefix (e.g., reference the module as
{{SUPERPOWERS_DIR}}/superpowers/lib/skills-core.js or simply
./lib/skills-core.js or the package name "superpowers/lib/skills-core.js");
update the occurrences around the CLI Location line
(`{{SUPERPOWERS_DIR}}/.codex/superpowers-{{AGENT_ID}}`) and the Shared Core
Module path (`~/.codex/superpowers/lib/skills-core.js`) to use these
variables/placeholders so no hardcoded ".codex" remains and the core module path
is not codex-specific.
| # Initialize git repo | ||
| git init | ||
|
|
||
| # Copy design and plan | ||
| cp "$SCRIPT_DIR/design.md" . | ||
| cp "$SCRIPT_DIR/plan.md" . | ||
|
|
||
| # Create .{{AGENT_ID}} settings to allow reads/writes in this directory | ||
| mkdir -p .{{AGENT_ID}} | ||
| cat > .{{AGENT_ID}}/settings.local.json << 'SETTINGS' | ||
| { | ||
| "permissions": { | ||
| "allow": [ | ||
| "Read(**)", | ||
| "Edit(**)", | ||
| "Write(**)", | ||
| "Bash(go:*)", | ||
| "Bash(mkdir:*)", | ||
| "Bash(git:*)" | ||
| ] | ||
| } | ||
| } | ||
| SETTINGS | ||
|
|
||
| # Create initial commit | ||
| git add . | ||
| git commit -m "Initial project setup with design and plan" | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and view the relevant section
fd scaffold.sh -x wc -l {}Repository: obra/superpowers
Length of output: 299
🏁 Script executed:
# View the file content at the specified lines
cat -n templates/tests/subagent-driven-dev/go-fractals/scaffold.sh | sed -n '14,41p'Repository: obra/superpowers
Length of output: 786
🌐 Web query:
git commit requires user.name user.email configuration behavior
💡 Result:
git commit needs an author/committer identity (name + email) to write into each commit object, and that identity becomes part of commit history permanently (“baked into” the commit) [1].
Where Git gets user.name / user.email
Git resolves identity in roughly this order:
- Environment variables override config:
GIT_AUTHOR_NAME,GIT_AUTHOR_EMAIL,GIT_COMMITTER_NAME,GIT_COMMITTER_EMAIL(andEMAILfor email) override config values [2]. - Git config (highest-precedence wins): repo-local
.git/config> global~/.gitconfig> system config [1]. - If still missing, Git may try to guess defaults for name/email unless you disable guessing (next section) [3].
What happens if you don’t configure them
- If Git can’t determine an email/name (common in CI containers, minimal environments, or when
HOMEisn’t what you expect), the commit/merge that creates a commit fails with the familiar message “Please tell me who you are … fatal: unable to auto-detect email address …” [4]. - This can also show up during
git merge,git pull, or rebase when they need to create a commit (e.g., a merge commit).
user.useConfigOnly: force “no guessing”
If you set:
user.useConfigOnly=true
Git will not guess user.name / user.email; it will only use values explicitly provided via config (or env vars). This makes new repos/clones error out until you set identity for that repo (useful if you use different emails per repo) [3].
How to set it (global vs per-repo)
Global (applies to all repos on the machine) [1]:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"Per-repo (only this repository) [1]:
git config user.name "Your Name"
git config user.email "[email protected]"Debugging tip
To see which file a value is coming from:
git config --list --show-origin[1]
Sources: Git book on first-time setup/identity and config precedence [1]; git-config docs for env var overrides and identity keys [2], and for user.useConfigOnly behavior [3]; example of the failure message/conditions in practice (CI/container) [4].
Set local git user before committing to avoid CI failures.
git commit requires user.name and user.email configuration; without them, it fails with "fatal: unable to auto-detect email address." This is common in CI environments and automated scaffolds. Configure locally before the commit.
🐛 Proposed fix
# Initialize git repo
git init
+git config user.name "Superpowers Scaffold"
+git config user.email "scaffold@local"
@@
# Create initial commit
git add .
git commit -m "Initial project setup with design and plan"🧰 Tools
🪛 Shellcheck (0.11.0)
[warning] 22-22: This { is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 22-22: This { is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 22-22: This } is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 22-22: This } is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 23-23: This { is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 23-23: This { is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 23-23: This } is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
[warning] 23-23: This } is literal. Check expression (missing ;/\n?) or quote it.
(SC1083)
🤖 Prompt for AI Agents
In `@templates/tests/subagent-driven-dev/go-fractals/scaffold.sh` around lines 14
- 41, The script fails in CI because git commit in scaffold.sh runs without
local user config; update the scaffold.sh sequence (after git init and before
git commit) to set a local git user and email for this repo (e.g., via git
config user.name and git config user.email or using repo-local config) so the
commit succeeds; ensure these configs are set in the same script before the git
add/git commit steps.
|
Fechado: PR aberto no upstream por engano; vou recriar no fork. |
1 participant
Summary
Test Plan
--- claude ---
Rendered 43 files for claude (check only).
--- codex ---
Rendered 10 files for codex (check only).
--- opencode ---
Rendered 15 files for opencode (check only).
All agents rendered successfully.
OpenCode Plugin Test Suite
========================================
Repository: /home/k2/git/superpowers/.worktrees/agent-templates
Test time: Sat Jan 24 09:05:28 -03 2026
Running: test-plugin-loading.sh
[PASS] (0s)
Running: test-skills-core.sh
[PASS] (1s)
========================================
Test Results Summary
Passed: 2
Failed: 0
Skipped: 0
Note: Integration tests were not run.
Use --integration flag to run tests that require OpenCode.
STATUS: PASSED
Summary by CodeRabbit
Release Notes
New Features
Documentation
Tests
Chores
✏️ Tip: You can customize this high-level summary in your review settings.