fix: map skill references for skills-only delivery

[Tylor110077]

Summary

• add transformToSkillReferences() for skills-only delivery
• wire the transformer in init and update
• add tests for command-reference transformation and skills-only init output

Testing

• npx vitest run test/utils/command-references.test.ts test/core/init.test.ts
• npm run build

Closes #879

Summary by CodeRabbit

• New Features
  • Enhanced SKILL.md generation to support skill references in skills delivery mode, mapping workflow identifiers to their corresponding skill references.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 112fd556-6f18-4e7f-b09b-d1475ffef060

📥 Commits

Reviewing files that changed from the base of the PR and between afdca0d and 5fb16bd.

📒 Files selected for processing (5)

• src/core/init.ts
• src/core/update.ts
• src/utils/command-references.ts
• test/core/init.test.ts
• test/utils/command-references.test.ts

---

📝 Walkthrough

Walkthrough

The PR fixes a bug where skills-only delivery mode generated SKILL.md files containing /opsx:* command references instead of /openspec-* skill namespace equivalents. It introduces a new transformer function that maps these hardcoded references to their corresponding skill cross-references and wires it into the skill generation flow.

Changes

Cohort / File(s)	Summary
Transformer Logic src/core/init.ts, src/core/update.ts	Updated SKILL.md generation to conditionally apply transformToSkillReferences for non-opencode tools when delivery === 'skills', replacing the hardcoded /opsx:* references with /openspec-* equivalents in generated skill files.
Command Reference Utilities src/utils/command-references.ts	Added OPSX_TO_SKILL_REFERENCE mapping object (8 workflow mappings) and new exported function transformToSkillReferences() that scans and replaces /opsx:<workflow> patterns with corresponding /openspec-* skill references.
Test Suite Updates test/core/init.test.ts, test/utils/command-references.test.ts	Updated delivery=skills test to expect /openspec-* references; added comprehensive test suite for transformToSkillReferences covering known/unknown workflow mappings and edge cases.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [Bug] Skills-only delivery emits /opsx:* command references #879 — This PR directly implements the proposed fix for the bug where skills-only delivery emitted /opsx:* command references instead of /openspec-* skill references by introducing transformToSkillReferences and wiring it into the skill generation flow.

Possibly related PRs

• fix(opencode): transform command references from colon to hyphen format #626 — Both PRs modify the command-reference transformation pipeline during skill generation by updating src/core/init.ts and src/core/update.ts to pass transformation callbacks; #626 adds transformToHyphenCommands for OpenCode while this PR extends that infrastructure with transformToSkillReferences for skills delivery mode.
• fix: use Skill tool for sync invocation in archive templates #632 — Both PRs replace /opsx:<workflow> cross-references with corresponding skill invocations (e.g., /opsx:apply → /openspec-apply-change), addressing reference namespace consistency in generated content.

Suggested reviewers

• TabishB

Poem

🐰 Cross-references once broken, now refine,
From /opsx: commands to skill designs divine,
Skills-only mode now gleams so bright,
With /openspec-* paths set right! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: mapping skill references for skills-only delivery mode, which directly addresses the bug fix.
Linked Issues check	✅ Passed	The PR fully implements the suggested fix from issue #879: adds transformToSkillReferences() function with explicit mapping, wires it into init/update paths when delivery==='skills', and validates with comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing issue #879: new transformer function, conditional integration in generation paths, and tests validating the fix. No unrelated changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}