fix(installer): generate working OpenCode command pointers

[blade035]

Summary

Fixes opencode integration: the command pointers generated by the installer reference skills using @skills/<id> syntax, which opencode does not support. opencode resolves @ references as file paths relative to the project root (packages/opencode/src/config/markdown.ts FILE_REGEX, packages/opencode/src/session/prompt.ts resolvePromptParts) — there is no @skills/ namespace. As a result, no skill content is ever injected into the prompt; the LLM must rediscover the skill by agentic file exploration (non-deterministic, and a no-op for non-agentic editors).

This PR changes the installer's default command-pointer body template to emit a real relative path (@{target_dir}/{canonicalId}/SKILL.md), which opencode resolves correctly.

Related issues:

• [BUG] opencode does not load any skills involving a workflow.md in the skill folder #1956 ([BUG] opencode does not load any skills involving a workflow.md in the skill folder) — likely the same root cause: skill content never reaches the prompt.
• [BUG] Bmad is not working on OpenCode CLI #2319 ([BUG] Bmad is not working on OpenCode CLI) — closed; this PR addresses the underlying pointer/syntax problem.

What changed

• tools/installer/ide/_config-driven.js
  • DEFAULT_COMMANDS_BODY_TEMPLATE: @skills/{canonicalId} → @{target_dir}/{canonicalId}/SKILL.md
  • {target_dir} was already supported by expandBodyTemplate (lines 96–97); only the default template and comments were wrong.
  • Corrected misleading comments that claimed @skills/<id> "matches OpenCode's native syntax".
• tools/installer/ide/platform-codes.yaml
  • opencode entry: added commands_body_template: "@{target_dir}/{canonicalId}/SKILL.md" + explanatory comment.
• test/test-installation-components.js (Suite 8)
  • Assertion updated to expect @.agents/skills/bmad-master/SKILL.md.

Verification

All green:

• node test/test-installation-components.js — all suites pass (incl. updated Suite 8)
• npm run lint, npx prettier --check, npm run format:check
• full npm test (test:refs / test:install / test:urls / test:channels / test:renderer / test:retrospective / test:sprint-planning / test:skills / lint / lint:md / format:check)

End-to-end repro with the generated pointer (opencode CLI 1.18.14):

1. Fresh install generates pointer body @.agents/skills/bmad-master/SKILL.md (was @skills/bmad-master).
2. opencode run --command bmad-master → skill marker PR_MARKER_LOADED_9f2c seen in the session: content is injected.
3. Proof the reference is resolved as a file: a pointer targeting pointer-target.md produced its marker FROM_POINTER_bbb in the session.
4. Negative control: the old @skills/bmad-master body injected nothing — the model had to agentically Read _bmad/_config/skill-manifest.csv and the SKILL.md itself to "discover" the skill.
5. Without any pointer, the skill-registered command failed in the CLI (UnknownError: Unexpected server error), while a plain hello.md command worked — the failure is specific to skill-backed commands.

Migration note (existing installs)

commands_body_template only takes effect on a fresh or re-run install; pointer files that already exist are not rewritten (existing content is respected, and the generator's reserved-guard skips files it doesn't own). Existing opencode installs with old @skills/<id> pointers must delete the stale files in commands_target_dir (remove-command-pointers / manual deletion) and re-run the installer.

[greptile-apps]

Greptile Summary

The PR replaces OpenCode’s unsupported skill namespace references with project-relative paths to installed SKILL.md files.

• Updates the default and OpenCode-specific command-pointer templates.
• Adds assertions for the working path and removal of the legacy reference.
• Corrects installer documentation around OpenCode path resolution.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
tools/installer/ide/_config-driven.js	Updates the default command-pointer body to reference the installed skill file through the project-relative target directory.
tools/installer/ide/platform-codes.yaml	Explicitly configures OpenCode to generate command pointers targeting each installed SKILL.md file.
test/test-installation-components.js	Verifies the generated OpenCode pointer uses the installed file path and excludes the obsolete namespace syntax.

_{Reviews (2): Last reviewed commit: "test(installer): guard against legacy @s..." | Re-trigger Greptile}

[coderabbitai]

📝 Walkthrough

Walkthrough

OpenCode command pointers now reference each installed skill’s SKILL.md through a project-root-relative path. Installer documentation and installation tests reflect the updated pointer format.

Changes

OpenCode skill pointer updates

Layer / File(s)	Summary
Pointer generation and validation tools/installer/ide/_config-driven.js, tools/installer/ide/platform-codes.yaml, test/test-installation-components.js	OpenCode command pointers now target {target_dir}/{canonicalId}/SKILL.md. Documentation describes direct skill-content routing, and the installation test verifies the .agents/skills/<canonicalId>/SKILL.md reference.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• bmad-code-org/BMAD-METHOD#1868: Added the SKILL.md entrypoint changes used by these OpenCode pointers.
• bmad-code-org/BMAD-METHOD#2313: Added the shared .agents/skills target configuration.
• bmad-code-org/BMAD-METHOD#2324: Introduced the OpenCode command-pointer generation and related tests.

Suggested reviewers: alexeyv, bmadcode, bdsoha

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the fix to generated OpenCode command pointers.
Description check	✅ Passed	The description directly explains the OpenCode pointer issue, implementation changes, migration steps, and verification results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

test/test-installation-components.js (1)

359-362: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Make the regression assertion reject the legacy namespace.

The current includes check proves that the new path is present. It does not prove that @skills/bmad-master is absent. Add a negative assertion or match the complete generated body.

Proposed assertion

     assert(
       commandContent.includes('@.agents/skills/bmad-master/SKILL.md'),
       'Command pointer body references the installed skill via @<target_dir>/<canonicalId>/SKILL.md',
     );
+    assert(
+      !commandContent.includes('`@skills/bmad-master`'),
+      'Command pointer does not use the legacy `@skills/`<canonicalId> namespace',
+    );

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/test-installation-components.js` around lines 359 - 362, Update the
assertion in the command-content test to verify that the legacy
`@skills/bmad-master` namespace is absent, either by adding a negative assertion
alongside the existing path check or by matching the complete generated body.
Preserve validation that the installed skill is referenced through
@.agents/skills/bmad-master/SKILL.md.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/test-installation-components.js`:
- Around line 359-362: Update the assertion in the command-content test to
verify that the legacy `@skills/bmad-master` namespace is absent, either by adding
a negative assertion alongside the existing path check or by matching the
complete generated body. Preserve validation that the installed skill is
referenced through @.agents/skills/bmad-master/SKILL.md.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 97d9debd-6001-492a-9090-be310ef026a4

📥 Commits

Reviewing files that changed from the base of the PR and between cbb69e6 and 83da44d.

📒 Files selected for processing (3)

• test/test-installation-components.js
• tools/installer/ide/_config-driven.js
• tools/installer/ide/platform-codes.yaml

[sanmaxdev]

Verified the command pointer resolves directly to the installed SKILL.md and the regression guard excludes the legacy namespace. npm ci && npm run quality passed on ddf9f4926c6388dbebf121bee1dac34d8ffeefbc.