fix: add transformToSkillReferences for skills-only delivery

[furaul]

Summary

Fixes #881 (also closes #879)

When delivery: 'skills' is configured, generated SKILL.md files contain hardcoded /opsx:* command references (e.g., /opsx:apply, /opsx:archive) that point to commands that don't exist in skills-only mode. Users should see /openspec-apply-change, /openspec-explore, etc. instead.

Changes

• Add transformToSkillReferences() in src/utils/command-references.ts — maps all 11 /opsx:<workflow> patterns to their /openspec-<skill-name> equivalents using an explicit lookup table (inline to avoid circular dependency with profile-sync-drift.ts)
• Wire the transformer in src/core/init.ts and src/core/update.ts (3 call sites) — extends the existing transformer ternary so that transformToSkillReferences is used when delivery === 'skills' and the tool is not opencode/pi
• Add 17 unit tests covering all 11 mappings, unknown pattern passthrough, multiple references, edge cases, and a sync guard that verifies the inline mapping stays aligned with WORKFLOW_TO_SKILL_DIR

Transformer selection logic

const transformer = (tool.value === 'opencode' || tool.value === 'pi')
  ? transformToHyphenCommands       // existing: /opsx:apply -> /opsx-apply
  : delivery === 'skills'
    ? transformToSkillReferences    // new: /opsx:apply -> /openspec-apply-change
    : undefined;                   // both/commands: keep /opsx:* as-is

Test plan

• All 37 command-references tests pass (11 mapping tests + 6 edge cases + sync guard + existing tests)
• Full test suite: 1409 passed, 1 pre-existing failure unrelated to this change
• ESLint: clean
• TypeScript type check: clean

Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features
  • Enhanced skill documentation generation with improved workflow command reference formatting
  • Expanded support for workflow-to-skill mapping across multiple tool configurations
  • Improved consistency in skill reference output for specialized delivery modes

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a new transformToSkillReferences utility function to replace /opsx:* command references with /openspec-* skill references. Integrated this transformer into skill generation logic in init.ts and update.ts to apply it when delivery === 'skills', with comprehensive test coverage for the new functionality.

Changes

Cohort / File(s)	Summary
Transformer Implementation src/utils/command-references.ts, src/utils/index.ts	Added transformToSkillReferences() function with internal OPSX_TO_SKILL mapping table (11 workflows); iterates through mappings to replace /opsx:<workflow> with /openspec-<skillDir>. Re-exported from utils index.
Transformer Integration src/core/init.ts, src/core/update.ts	Wired transformer selection logic: applies transformToHyphenCommands for opencode/pi tools; applies transformToSkillReferences for other tools when delivery === 'skills'; otherwise passes undefined.
Test Coverage test/utils/command-references.test.ts	Added comprehensive Vitest suite with 11 workflow mappings, unmatched pattern handling, multiline content support, edge cases (empty input, no references), and synchronization check against WORKFLOW_TO_SKILL_DIR.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: add /opsx:sync command for syncing delta specs to main specs #450 — Defines and registers the openspec-sync-specs skill template that this PR's transformer mapping directly references via /opsx:sync → /openspec-sync-specs.
• fix(opencode): transform command references from colon to hyphen format #626 — Similarly modifies src/utils/command-references.ts and transformer wiring in init.ts/update.ts to handle command-reference transformations for a different delivery mode.
• fix: use Skill tool for sync invocation in archive templates #632 — Updates templates to use openspec-sync-specs instead of /opsx:sync, complementing this PR's transformer-based approach to fixing broken skill references.

Suggested reviewers

• TabishB
• alfred-openspec

Poem

🐰 A rabbit hops with glee,
/opsx: becomes /openspec-* — do you see?
Skills now reference skills so bright,
No broken links in sight! ✨

🚥 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 PR title clearly summarizes the main change: adding the transformToSkillReferences function to support skills-only delivery mode.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding requirements from linked issues #879 and #881: implements transformToSkillReferences with correct mappings, wires it into init.ts and update.ts with proper delivery-aware logic, and includes comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issues: adding the new transformer function, wiring it into core files, updating exports, and adding comprehensive tests. No unrelated modifications 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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/core/init.ts (1)

541-546: Optional: extract transformer selection to a shared helper.

The same (opencode|pi) → hyphen | skills → skillRefs | undefined selection is now duplicated at three call sites (here, update.ts L199-203, and L675-679). Consider lifting it into a tiny helper in src/utils/command-references.ts so future tool/delivery additions only need to change one place.

♻️ Example

// src/utils/command-references.ts
export function selectSkillTransformer(toolId: string, delivery: string) {
  if (toolId === 'opencode' || toolId === 'pi') return transformToHyphenCommands;
  if (delivery === 'skills') return transformToSkillReferences;
  return undefined;
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/core/init.ts` around lines 541 - 546, Extract the duplicated
transformer-selection logic into a single helper (e.g., selectSkillTransformer)
that returns transformToHyphenCommands when tool id is "opencode" or "pi",
returns transformToSkillReferences when delivery === "skills", and otherwise
returns undefined; replace the inline ternary expression in init.ts and the
other two call sites (the locations using transformToHyphenCommands /
transformToSkillReferences) with calls to selectSkillTransformer to centralize
future changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/core/init.ts`:
- Around line 541-546: Extract the duplicated transformer-selection logic into a
single helper (e.g., selectSkillTransformer) that returns
transformToHyphenCommands when tool id is "opencode" or "pi", returns
transformToSkillReferences when delivery === "skills", and otherwise returns
undefined; replace the inline ternary expression in init.ts and the other two
call sites (the locations using transformToHyphenCommands /
transformToSkillReferences) with calls to selectSkillTransformer to centralize
future changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 88677937-d318-4377-b8fb-5c64386359ed

📥 Commits

Reviewing files that changed from the base of the PR and between f529b25 and 5a2f694.

📒 Files selected for processing (5)

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