fix(init): use skill references for tools without a command adapter

[clay-good]

Status

Ready for review. Fixes #1155. Hardened by three independent adversarial review passes; full suite green locally (2,034 passed; the only failures are the 17 known environment-only zsh-installer ones covered by #1400).

What was wrong

Tools with no command adapter — Kimi Code, Mistral Vibe, Hermes, ForgeCode, CodeArts Agent — skip command generation even under the default both delivery (Commands skipped for: kimi (no adapter)). But the skills generated for them still told agents to run /opsx:apply, /opsx:archive, /opsx:continue, … — commands that were never created — and the init summary ended with Start your first change: /opsx:propose. The committed skills/ tree (the npx skills add Fission-AI/OpenSpec channel) had the same problem: it ships SKILL.md files only, yet referenced /opsx:* throughout. Reported in #1155 (the "5 commands" count from that report was already fixed on main; the references and the hint were not).

#1194 fixed this for the global delivery: skills setting, but the per-tool case (delivery both, tool has no adapter) was left out: getTransformerForTool only looked at delivery, not at the tool's command surface.

How it was fixed

• getTransformerForTool now also takes the tool's command-surface capability (type-only import of CommandSurfaceCapability) and returns a skill-reference transform when the capability is none, honoring each tool's documented invocation syntax (Kimi Code: /skill:openspec-*; all others: /openspec-* per fix: use skill references in SKILL.md for skills-only delivery #1194). All three call sites (init + update ×2) pass resolveCommandSurfaceCapability(tool.value).
• The init getting-started hint uses the same transform whenever no selected tool got commands, so it prints the tool's skill invocation (e.g. /skill:openspec-propose "your idea" for Kimi Code) instead of a command that doesn't exist. When mixed selections disagree on syntax (kimi + vibe), init prints one labeled hint per distinct form so every advertised instruction is usable by the tool it names; the one-time migration message stays syntax-neutral in that case. When nothing was generated at all (delivery: commands + adapterless tools only), init prints a configuration correction (openspec config set delivery both) instead of any invocation hint, and suppresses the "Restart your IDE" line.
• The one-time profile-migration message ("New in this version: /opsx:propose") is now capability-aware for projects whose detected tools have no adapter.
• scripts/generate-skillssh.mjs and its parity test apply the transform, and skills/ is regenerated — the diff there is purely the reference swap (35 lines).

Codex SKILL.md content is deliberately unchanged (skills-invocable never triggers the new branch) — #1143 owns codex reference rewriting. The shared getting-started hint does improve for codex-only setups too, since codex lost its /opsx prompts in #1283 and the old hint pointed at them.

Replication / proof

Before (clean build of main):

$ openspec init --tools kimi
6 skills in .kimi-code/
Commands skipped for: kimi (no adapter)
  Start your first change: /opsx:propose "your idea"
$ grep -rn "/opsx:" .kimi-code/skills/ | wc -l
      12

After (this branch):

$ openspec init --tools kimi
6 skills in .kimi-code/
Commands skipped for: kimi (no adapter)
  Start your first change: /skill:openspec-propose "your idea"
$ grep -rn "/opsx" .kimi-code/skills/ | wc -l
       0
$ grep -rn "/skill:openspec-" .kimi-code/skills/ | wc -l
      12
$ grep -rn "/opsx" skills/ | wc -l
       0

Regression tests: adapterless tool under default delivery gets skill references and the skill-based hint; adapter-backed tool (claude) keeps /opsx:* in both skills and hint; the kimi update-path test asserts refreshed skills contain no /opsx (mutation-verified: reverting the update.ts change now fails tests); transformer unit tests cover all three capabilities; skills.sh parity test pins the transformed output.

Notes

• No template changes — golden-hash template parity is unaffected; the skills.sh parity test was updated alongside its generator, and the regenerated skills/ diff is reference-swaps only.
• Verified no published-API break: the package exports only dist/index.js, which never re-exports getTransformerForTool.
• A changeset is included (patch bump). Pre-existing issues found during review, deliberately out of scope: delivery: commands + adapterless-only tools still generates nothing (the misleading hint is now replaced with a configuration correction, but whether that delivery setting should fall back to skills for such tools is a design question — worth its own issue; openspec update in that same config silently removes the skills and reports success, also pre-existing); core-profile skills reference workflows outside the profile (affects adapter-backed tools identically); the unconditional "Restart your IDE for slash commands" line (fix: only show 'Restart your IDE' message for IDE-embedded tools #1097); the interactive welcome screen's /opsx examples; inferDelivery treating an adapterless project's lack of commands as a skills-only preference.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Fixed “Getting started” and “Start your first change” hints to route to the correct command/skill invocation that matches what was actually generated.
  • Updated “Restart your IDE” and “New in this version” messaging to appear only when relevant, and to use the right /opsx-* vs /openspec-*//skill:openspec-* targets.
• Documentation
  • Regenerated and updated OpenSpec skills and examples to consistently use openspec-*/skill:openspec-* references instead of unused /opsx:* variants.
• Tests
  • Expanded coverage for adapterless vs adapter-backed tools, migration behavior, and skills distribution parity.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Skill and command reference transformation now accounts for each tool’s command-surface capability. Initialization, update, migration, and skills.sh generation produce skill-compatible references when commands are unavailable.

Changes

Capability-aware skill reference generation

Layer / File(s)	Summary
Transformer contract and selection src/utils/command-references.ts, src/utils/index.ts, test/utils/command-references.test.ts	getTransformerForTool accepts command-surface capability, selects skill references for adapterless tools, preserves hyphen-command handling, and tests the selection paths.
Capability-aware generation and guidance src/core/init.ts, src/core/update.ts, src/core/migration.ts, test/core/init.test.ts, test/core/update.test.ts	Initialization, update, legacy setup, and migration pass capability information and rewrite guidance or generated skills when commands are unavailable.
Published skill output and documentation scripts/generate-skillssh.mjs, test/core/templates/skillssh-parity.test.ts, skills/openspec-*/SKILL.md, .changeset/adapterless-skill-references.md	skills.sh generation and parity checks apply skill-reference transformation, committed skill instructions use /openspec-* routes, and the patch release describes the updated references.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• Fission-AI/OpenSpec issue 1155 — Directly addresses adapterless Kimi/Vibe guidance and generated references for unavailable /opsx:* commands.

Possibly related PRs

• Fission-AI/OpenSpec#1194 — Updates the shared skill-reference transformation flow.
• Fission-AI/OpenSpec#1003 — Relates to Kimi skills-only initialization behavior.
• Fission-AI/OpenSpec#1357 — Touches skills.sh generation and parity validation.

Suggested reviewers: tabishb, alfred-openspec

Sequence Diagram(s)

sequenceDiagram
  participant InitCommand
  participant CapabilityResolver
  participant TransformerSelector
  participant SkillGenerator
  participant ConsoleOutput
  InitCommand->>CapabilityResolver: resolve tool command surface
  CapabilityResolver->>TransformerSelector: provide delivery and capability
  TransformerSelector->>SkillGenerator: select skill or command reference transformation
  SkillGenerator-->>InitCommand: generate transformed skill content
  InitCommand->>ConsoleOutput: print matching start reference

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: init now uses skill references for tools without a command adapter.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/adapterless-skill-references

---

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.}

[alfred-openspec]

The capability-only transform breaks Kimi’s documented invocation contract: Kimi skills use /skill:openspec-* (see docs/supported-tools.md, docs/how-commands-work.md, and docs/commands.md), but this head rewrites both generated cross-references and the getting-started hint to /openspec-*. Please make the skill-reference transform tool-specific and add an end-to-end Kimi assertion for the actual invocation syntax.

[clay-good]

Addressed in 881d893: skill-reference transforms are now selected per tool via getSkillReferenceTransformer. Kimi Code gets its documented /skill:openspec-* invocations everywhere (generated skill cross-references, the getting-started hint, and the migration message); vibe/hermes/forgecode/codeartsagent keep the /openspec-* form their docs specify. End-to-end Kimi assertions added for generated content (init), refreshed content (update path), and the hint. Verified live:

$ openspec init --tools kimi
  Start your first change: /skill:openspec-propose "your idea"
$ grep -rho "/skill:openspec-[a-z-]*" .kimi-code/skills/ | sort -u | head -2
/skill:openspec-apply-change
/skill:openspec-archive-change

Note this also fixes a pre-existing docs mismatch: under delivery: skills, Kimi previously got /openspec-* references from the blanket transform.

[alfred-openspec]

The Kimi /skill: prefix is fixed at 881d893, but the commands-only adapterless corner still prints a dead getting-started instruction. Reproduced with global delivery=commands plus openspec init --tools kimi: setup creates neither skills nor commands, then tells the user to run /skill:openspec-propose. Please gate the hint on an actually generated surface (or print a configuration correction) and add an end-to-end commands-only adapterless assertion.

[clay-good]

Addressed in 8f6d324:

• Commands-only adapterless corner (your review): when delivery: commands is set and every selected tool lacks a command adapter, init now prints a configuration correction instead of a dead invocation hint, and no "Start your first change" line is shown. Covered by an end-to-end test (delivery=commands + --tools kimi asserts nothing is generated, no hint, and the openspec config set delivery both remedy is printed).

$ openspec init --tools kimi   # global delivery: commands
No skills or commands were generated: delivery is set to 'commands' but Kimi Code supports only skills. Run 'openspec config set delivery both' to generate skills.

• From a parallel adversarial review round: mixed selections that disagree on invocation syntax (--tools kimi,vibe) now fall back to the default /openspec-* form in the shared hint and migration message rather than using the first tool's syntax (each tool's own SKILL.md files always keep their documented form); added the missing changeset; corrected an inaccurate code comment about codex handling.

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@src/core/migration.ts`:
- Around line 215-217: Update the transformer-selection logic around
skillTransformers in migration.ts and the corresponding initialization logic in
init.ts to compare each transformer’s output for the same dummy input rather
than function identity. Use the shared transformer when all outputs agree,
including independently created closures with the same prefix; otherwise retain
the transformToSkillReferences fallback and existing command-surface behavior.

In `@test/core/init.test.ts`:
- Line 986: The delivery=commands test at test/core/init.test.ts:986-986 and the
mixed adapterless tools test at test/core/init.test.ts:1013-1013 each declare
logCalls twice consecutively; remove one duplicate declaration from each test
while retaining the single declaration used by its assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fbf35083-deb1-46a4-ab0b-b5064d9d50bf

📥 Commits

Reviewing files that changed from the base of the PR and between 881d893 and 8f6d324.

📒 Files selected for processing (5)

• .changeset/adapterless-skill-references.md
• src/core/init.ts
• src/core/migration.ts
• src/utils/command-references.ts
• test/core/init.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

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

[coderabbitai]

🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

Remove duplicate constant declarations.

The variable logCalls is declared twice consecutively in these test cases, which will cause a SyntaxError: Identifier 'logCalls' has already been declared and break the test build.

• test/core/init.test.ts#L986-L986: Remove the duplicated logCalls declaration in the delivery=commands test.
• test/core/init.test.ts#L1013-L1013: Remove the duplicated logCalls declaration in the mixed adapterless tools test.

📍 Affects 1 file

• test/core/init.test.ts#L986-L986 (this comment)
• test/core/init.test.ts#L1013-L1013

🤖 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/core/init.test.ts` at line 986, The delivery=commands test at
test/core/init.test.ts:986-986 and the mixed adapterless tools test at
test/core/init.test.ts:1013-1013 each declare logCalls twice consecutively;
remove one duplicate declaration from each test while retaining the single
declaration used by its assertions.

[clay-good]

Third adversarial review round complete (three independent passes: newest-commit correctness, cross-file consistency, break-nothing gate — all MERGE-SAFE/SHIP). Residual fixes in 70617b3: the 'Restart your IDE' line is now suppressed when nothing was generated (it printed directly after the configuration correction), init test temp dirs use randomUUID(), and the changeset wording clarifies the skills.sh channel uses the default /openspec-* form. The PR description's proof block was re-measured against a real build of main (12 /opsx: lines before, 0 after, 12 /skill:openspec-* after). Verified out of scope and pre-existing: dangling core-profile references (identical on main for claude), and openspec update with delivery: commands silently removing skills — both noted in the description.

[alfred-openspec]

The commands-only dead hint is fixed at 86155d0, but the new mixed-syntax fallback deliberately reintroduces an invalid instruction for Kimi. Reproduced openspec init --tools kimi,vibe: both skill trees are generated correctly, then the shared setup summary says /openspec-propose, which Vibe accepts but Kimi does not (Kimi requires /skill:openspec-propose). Please emit per-tool hints or a syntax-neutral instruction instead of choosing a form that is wrong for one configured tool; the current mixed-tool test should assert every advertised instruction is usable, not codify the fallback.

[clay-good]

Addressed in 36997e8:

• Mixed-syntax hint (alfred): the fallback is gone. Successful tools are grouped by their transformed reference and init prints one labeled hint per distinct form, so every advertised instruction is usable by the tool it names. The mixed-tool test now asserts exactly that (two lines, each pinned to its tool's documented syntax, no /opsx:):

$ openspec init --tools kimi,vibe
  Start your first change: /skill:openspec-propose "your idea" (Kimi Code)
  Start your first change: /openspec-propose "your idea" (Mistral Vibe)

• Transformer comparison (CodeRabbit, migration.ts): now compares transformed outputs rather than function identities; when detected tools disagree, the migration message stays syntax-neutral (New in this version: the openspec-propose skill.).
• Duplicate logCalls (CodeRabbit, init.test.ts): false positive — the two declarations at lines 987 and 1016 are in two different it() blocks, each declared once per scope. A same-scope redeclaration would be a SyntaxError, and the file runs green (59/59 locally, CI green on the previous push).