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

[clay-good]

Status

Ready for review. Fixes #1155. Hardened by five rounds of independent adversarial review passes (thirteen total); full suite green locally (2,046 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 is derived per tool from the surface that tool actually got: command tools keep /opsx:propose, skill-only tools get their documented skill invocation (Kimi Code: /skill:openspec-propose "your idea"), and Codex — skills-invocable, no slash surface — gets a syntax-neutral line (Start your first change with the openspec-propose skill). Mixed selections print one labeled hint per distinct form (including adapter-backed + skill-only mixes like claude+kimi), so every advertised instruction is usable by the tool it names; the one-time migration message stays syntax-neutral on disagreement and no longer advertises /opsx:propose under an explicit delivery: skills. A tool that got no artifacts at all (delivery: commands + no adapter) gets a configuration correction naming it (openspec config set delivery both), even when other selected tools did generate; when nothing was generated for anyone, the hint and restart line are suppressed entirely. The restart line only claims slash commands when commands were generated (otherwise: "Restart your IDE for the new skills to take effect.").
• The one-time profile-migration message ("New in this version: /opsx:propose") derives its reference per detected tool and stays syntax-neutral when tools disagree — including command tools mixed with skill-only tools (Claude + Kimi) and explicit delivery: skills, where /opsx:* will never exist. The legacy-upgrade getting-started menu in update does the same (a legacy Codex upgrade previously advertised the /opsx:* prompts Codex lost in feat(codex): make Codex skills-only and retire managed custom prompts #1283); command-tool upgrades keep byte-identical output.
• 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 interactive welcome screen's /opsx examples; inferDelivery treating an adapterless project's lack of commands as a skills-only preference; the summary counts line (6 skills in .codex, .kimi-code/) listing directories for tools that got nothing (toolDirs predates this PR); the hint printing /opsx:propose for hyphen-command tools (opencode/pi/oh-my-pi) whose commands are invoked as /opsx-*.

🤖 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 accurately summarizes the main change: using 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

[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).

[alfred-openspec]

One remaining capability mismatch: openspec init --tools codex now prints /openspec-propose even though Codex has no slash-command surface and the repo docs intentionally direct users to .codex/skills/openspec-*. I reproduced it at 36997e8; the same capability-blind branch also prints Restart your IDE for slash commands. Please make the hint syntax-neutral or Codex-specific for skills-invocable tools and pin the Codex end-to-end case.

[clay-good]

Addressed in efda4c3 + 3f681cd:

• Codex capability mismatch (your review): the hint is now syntax-neutral for skills-invocable tools, and the restart line only claims slash commands when commands were generated. The same fix is applied to the one-time migration message (codex-only detection previously printed /openspec-propose there too). Codex end-to-end cases are pinned: codex-only init, codex+vibe mixed labeling, codex+kimi under delivery: commands, and the codex-only migration message.
• Went one step further on the same finding class (fourth adversarial review round): hints are now derived per tool from the surface it actually got, and the delivery: commands correction is per-tool instead of keyed on the global aggregate — previously --tools claude,kimi with delivery: commands gave Kimi zero artifacts, no correction, and a dead /opsx:propose instruction. Mixed adapter+skill-only selections (claude+kimi, claude+codex) now label each line. The migration message also stops advertising /opsx:propose under an explicit delivery: skills.

Real output on this head (delivery: both unless noted):

$ openspec init --tools codex
  Start your first change with the openspec-propose skill
Restart your IDE for the new skills to take effect.

$ openspec init --tools claude,codex
  Start your first change: /opsx:propose "your idea" (Claude Code)
  Start your first change with the openspec-propose skill (Codex)
Restart your IDE for slash commands to take effect.

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

$ openspec config set delivery commands && openspec init --tools claude,kimi
No skills or commands were generated for Kimi Code: delivery is set to 'commands' but it supports only skills. Run 'openspec config set delivery both' to generate skills.
  Start your first change: /opsx:propose "your idea"

Codex SKILL.md content remains byte-identical to main (still owned by #1143). Full suite green except the 17 known environment-only zsh-installer failures (#1400); lint and typecheck clean. The CodeRabbit duplicate-logCalls thread was a false positive (two separate it() blocks) — replied and resolved.

[alfred-openspec]

The Codex hint is fixed and the expanded init coverage passes, but the one-time migration path still collapses mixed command and skill-only tools to the command form. I reproduced a project with Claude commands plus a Kimi openspec-propose skill at 3f681cd: migrateIfNeeded prints only /opsx:propose, which Kimi cannot invoke, despite the changeset and code comment promising usable guidance when detected tools disagree. Please make the migration message syntax-neutral or per-tool for mixed command-surface selections and add the Claude plus Kimi regression case.

[clay-good]

Addressed in f5c2de1:

• Mixed command + skill-only migration (your review): the propose reference is now derived per detected tool — /opsx:propose only for tools whose commands will exist under the effective delivery, the documented skill invocation for skill-only tools — and the shared message goes syntax-neutral when they disagree. Your exact repro (Claude commands + Kimi openspec-propose skill, pre-profile config):

$ openspec update --force
Migrated: custom profile with 1 workflows
New in this version: the openspec-propose skill. Try 'openspec config profile core' for the streamlined experience.

Claude-only still prints /opsx:propose; kimi-only prints /skill:openspec-propose. Regression tests pin claude+kimi (your ask), claude commands-installed, kimi-only, codex-only, codex+kimi, and explicit delivery: skills.

• Same class, one surface further: the legacy-upgrade "Getting started" menu in update hard-coded /opsx:new//opsx:continue//opsx:apply. A legacy Codex upgrade (managed opsx-*.md prompt in $CODEX_HOME/prompts with codex unconfigured) advertised the very prompts Codex lost in feat(codex): make Codex skills-only and retire managed custom prompts #1283. Menu lines are now derived per newly configured tool with the same rules:

$ openspec update --force   # legacy Codex prompt detected, codex newly configured
Getting started:
  the openspec-new-change skill       Start a new change
  the openspec-continue-change skill  Create the next artifact
  the openspec-apply-change skill     Implement tasks

Command-tool legacy upgrades (claude, cursor, …) keep byte-identical output — verified with cat -ve against the old hard-coded lines. That was the last hard-coded /opsx:* instruction outside the pre-selection welcome screen; a sweep of every printed instruction surface (init, update, migration, legacy-cleanup summaries, doctor/config) found no other capability-blind reference. Full suite green except the 17 known environment-only zsh-installer failures (#1400); lint and typecheck clean.

[alfred-openspec]

Re-review at f5c2de1: mixed command and skill-only migration guidance now falls back to a syntax-neutral skill reference, and the legacy Codex upgrade menu uses the same capability-aware contract. I reproduced the Claude plus Kimi case successfully; 218 focused tests, clean skill regeneration, build, and the full exact-head CI and CodeQL matrix pass.