fix(adapters): reference slash commands by the names each tool registers

[clay-good]

Status: LGTM — behavior-preserving for Claude Code, corrective for 22 other tools, 3,334 tests pass.

What was wrong

OpenSpec writes your slash commands, then tells you what to type. For most tools it told you wrong.

Command bodies are authored with /opsx:apply-style references. Only 7 of the 28 tools with a command adapter actually register that name — the ones whose files live in an opsx/ directory (Claude Code, CodeBuddy, Crush, Gemini, Lingma, Qoder, ZCode). The other 21 write .../opsx-apply.md, where the filename is the command, so their palettes register /opsx-apply. Five of those 21 were rewritten to the hyphen form; the remaining 16 — including Cursor, GitHub Copilot, Windsurf, Kilo Code, Factory Droid and Cline — were not.

The result, reported in #1307 and #727: the generated command bodies, the generated SKILL.md files, and the "Getting started" line printed by openspec init all advertised a command the tool had never heard of.

On main, a single generated Cursor file contradicts itself — the frontmatter
names the command /opsx-apply, the body then tells you to run /opsx:apply:

$ openspec init --tools cursor                                   # on main
Getting started:
  Start your first change: /opsx:propose "your idea"             # Cursor registers /opsx-propose

$ grep -o '/opsx[:-][a-z-]*' .cursor/commands/opsx-apply.md | sort -u
/opsx-apply                                                      # frontmatter name
/opsx:apply                                                      # body cross-references
/opsx:archive
/opsx:continue

Codex had the same problem in a sharper form: it generates no command files at all, yet its skills said /opsx:apply. Codex invokes skills as $openspec-apply-change (#1379, #1110).

How it was fixed

An invocation has two parts, and only one can be read off the file an adapter writes. The name comes from the path; the prefix is the tool's own and is declared as adapter metadata (invocationPrefix, defaulting to /):

Adapter writes	Tool registers
.claude/commands/opsx/apply.md	/opsx:apply
.cursor/commands/opsx-apply.md	/opsx-apply
.amazonq/prompts/opsx-apply.md	@opsx-apply
no command file (Codex)	$openspec-apply-change

Amazon Q is the one tool that registers no slash command at all: it loads those files into its prompt library, invoked with @. Deriving only colon-versus-hyphen would have handed it /opsx-apply, which is still a name it never answers to — so the prefix is metadata, not a guess. A tripwire test fails if a new adapter grows an undeclared prefix.

That model drives every tool-specific surface: command bodies, SKILL.md cross-references, and the init / update / migration hints. A newly added adapter is classified by its own path, so this cannot drift again — which is how the old list ended up 16 tools behind.

Proof it works

$ openspec init --tools claude,cursor,amazon-q,kimi,codex      # after
Getting started:
  Start your first change: /opsx:propose "your idea" (Claude Code)
  Start your first change: /opsx-propose "your idea" (Cursor)
  Start your first change: @opsx-propose "your idea" (Amazon Q Developer)
  Start your first change: /skill:openspec-propose "your idea" (Kimi Code)
  Start your first change: $openspec-propose "your idea" (Codex)

$ grep -o '@opsx-[a-z-]*' .amazonq/prompts/opsx-apply.md | sort -u
@opsx-apply
@opsx-archive
@opsx-continue          # no /opsx: and no /opsx- survive anywhere under .amazonq/

$ grep -o '/opsx[:-][a-z-]*' .cursor/commands/opsx-apply.md | sort -u
/opsx-apply
/opsx-archive
/opsx-continue

$ grep -o '/opsx[:-][a-z-]*' .claude/commands/opsx/apply.md | sort -u
/opsx:apply
/opsx:archive
/opsx:continue          # unchanged

$ grep -o '\$openspec-[a-z-]*' .codex/skills/openspec-apply-change/SKILL.md | sort -u
$openspec-apply-change

Verified end to end across all three delivery modes (skills, commands, both) and on the upgrade path: a project generated by the old build is healed by openspec update, with zero stale references left in any tool directory.

New tests: invocation.test.ts asserts every registered adapter is classified from its own file path against an expected table (so a new adapter can't silently pick the wrong form), update.test.ts heals a Cursor project seeded with stale /opsx: references and pins claude+qwen to their own forms in one run, and migration.test.ts covers a flat-tool upgrade message. Per-adapter reference tests moved to the generator layer, which now owns the rewrite, with a new case pinning that those adapters stay pure formatters.

A mutation run over the change found five ways to delete parts of it without failing a test — the whole update.ts and migration.ts hunks among them. All five now fail, verified by re-applying each mutation.

npm run build, npm run lint, npx vitest run (3,334 tests, 115 files) all pass.

Is this a breaking change?

No. Command filenames and paths are untouched — every command a user has today keeps working. What changes is the text OpenSpec generates inside those files and prints to the terminal, which moves from a name that did not resolve to one that does. Claude Code output is byte-identical.

Notes

• Supersedes fix: use colon syntax for Cursor slash commands #1335, which fixes Cursor slash commands: colon vs hyphen mismatch in docs and generated content #1307 in the opposite direction — changing Cursor's frontmatter name to /opsx:<id> while keeping the opsx-<id>.md filename. Cursor's docs state commands are stored as .cursor/commands/[command].md and the reporter's own palette screenshot shows the hyphen form, so the filename wins and the frontmatter change would not have taken effect. fix: use colon syntax for Cursor slash commands #1335 is also currently conflicting.
• Supersedes fix: unify tool command invocation rendering across generation paths #740 ("Closes [Bug Report] prompts and skills are not exact compatible with commands like "/opsx-new" in version 1.1.1 #727"), whose diff contains only three planning docs and no source changes. Its design sketched a hand-maintained per-tool pattern field; deriving from getFilePath avoids the drift that caused this bug.
• Cursor slash commands: colon vs hyphen mismatch in docs and generated content #1307's reporter suggested emitting colon syntax for Cursor rather than hyphenating. The evidence points the other way, so this PR resolves the mismatch by the other route.
• Regarding OpenSpec's Codex-cli, is it possible to execute commands using slash commands during use #1110 is a question ("where are the Codex slash commands?"); it is answered by the new How To Invoke table plus the corrected Codex hint, not by making slash commands work in Codex — they don't exist there.
• Docs swept, not just patched. The two partial nine-row syntax tables in commands.md and how-commands-work.md are the same drift that caused this bug, so they now key on the file shape and defer to one authoritative table. faq.md, troubleshooting.md, installation.md and README.md no longer tell skills-only users they have no slash command, or offer "type /opsx and watch autocomplete" as a health check on tools where it never completes. cli-init, cli-update and legacy-cleanup specs updated to match the code.
• Amazon Q's @ form is now confirmed and implemented. An earlier revision dropped this row because I could not confirm the syntax. AWS's prompt-management docs and aws/amazon-q-developer-cli#2243 both confirm @prompt-name, so invocation.ts now renders a full name rather than a two-valued style — the follow-up that note anticipated, done here.
• Cline and Kilo Code need no exception. Kilo Code's docs say the current format drops the .md suffix, and Cline's workflow docs say a workflow is invoked by filename without the extension. Both are plain /opsx-<id>, which is what the flat rule already produces.
• Depends on fix(update): refresh command files for tools configured without skills #1442 to reach delivery: commands users on a plain openspec update. Command files carry no version stamp, so needsUpdate stays false for commands-only tools and update reports "already up to date" without rewriting them (update --force and re-init both work today). That is a pre-existing bug on main which fix(update): refresh command files for tools configured without skills #1442 fixes with tests; I have not duplicated it here.
• The pre-selection welcome banner renders before you pick a tool, so it cannot know the spelling. It no longer claims it does: the setup summary says "Workflow commands, if supported" (skills-only tools correctly get none) and the quick start is marked "spelling varies by tool". The post-setup restart line says "the new commands" rather than "slash commands", which was wrong for Amazon Q.
• transformToHyphenCommands became transformCommandInvocations(text, invocation) now that the prefix varies, and rewrites only known command ids, matching transformToSkillReferences. The old unanchored /\/opsx:/g was harmless with 5 adapters and no longer worth the blast radius at 22.
• Refs The Codex CLI integration continues to generate a deprecated slash-command workflow (/opsx:*). #1129: its stale-Codex-prompt half is already fixed on main; this PR fixes the remaining half (Codex assets referencing /opsx:*).

---

Closes #1307
Closes #727
Closes #1379
Closes #1110
Refs #1129

Summary by CodeRabbit

• Documentation
  • Standardized canonical slash-command naming (/opsx:propose) and added tool-specific “How To Invoke” tables with correct per-tool spellings (including Codex $openspec-* forms) and guidance on using exactly what setup/autocomplete shows.
  • Updated Quick Start, FAQ, installation, troubleshooting, and onboarding/cleanup text to reflect tool-specific command vs skill invocation behavior.
• Bug Fixes
  • Improved per-tool command invocation handling so generated references match how each tool registers commands (flat vs namespaced), including preserving unknown /opsx:<id> references.
• Tests
  • Added/expanded coverage for invocation-style detection and end-to-end generated command/skill content across tools.

[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

Command generation now derives flat or namespaced invocation styles from tool paths, applies reference rewriting centrally, and updates initialization, migration, and update flows to emit tool-specific command syntax. Documentation, specifications, release notes, and tests cover slash, hyphenated, and Codex skill invocations.

Changes

Command invocation and reference formatting

Layer / File(s)	Summary
Invocation-aware command generation src/core/command-generation/..., test/core/command-generation/...	Command paths determine whether known /opsx:<id> references become /opsx-<id>, while adapters format already-transformed bodies and tests validate both invocation styles.
Tool-specific transformer selection src/utils/command-references.ts, src/core/command-surface.ts, src/core/{init,migration,update}.ts, test/core/{init,migration,update}.test.ts, test/utils/command-references.test.ts	Transformer selection uses delivery, command-surface capability, and invocation style for generated skills, migration text, onboarding hints, and command references.
Specifications and release metadata openspec/specs/..., .changeset/command-invocation-parity.md	Specifications and patch release notes describe adapter-path generation and tool-specific command-reference spelling.
Invocation conventions documentation README.md, docs/*.md	Documentation explains canonical command naming, path-dependent syntax, tool-specific wrappers, Codex skill invocation, and troubleshooting guidance.
User-facing surface wording src/core/legacy-cleanup.ts, src/ui/welcome-screen.ts, test/core/legacy-cleanup.test.ts	Cleanup and welcome messages refer to OpenSpec skills and commands without the former fixed slash-command wording.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related issues

• The Codex CLI integration continues to generate a deprecated slash-command workflow (/opsx:*). #1129: Covers migrating Codex from /opsx:* prompt commands to $openspec-* skills.

Possibly related PRs

• Fission-AI/OpenSpec#1194: Modifies shared command-reference transformer selection in initialization and update flows.
• Fission-AI/OpenSpec#1404: Changes the same skills-only transformer-resolution pipeline.
• Fission-AI/OpenSpec#1283: Covers Codex skills-only invocation handling.

Suggested reviewers: alfred-openspec, tabishb

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 69.23% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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: generating slash-command references using each tool’s registered command name.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/command-invocation-parity

---

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

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	bc270ea
Status:	✅  Deploy successful!
Preview URL:	https://4df0963b.openspec-docs.pages.dev
Branch Preview URL:	https://fix-command-invocation-parit.openspec-docs.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/utils/command-references.ts (1)

139-152: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Sound refactor of transformer selection. Generalizing from a hard-coded tool list to capability + invocation-style-derived logic is a solid fix for the drift problem described in the comment. Verified all branches against the accompanying test file's expectations.

One note: making invocationStyle a required (non-optional) parameter is intentional per the doc comment, but see the companion comment in test/utils/command-references.test.ts — several existing test call sites were not updated to pass this argument, so the "fails to compile" guarantee isn't actually being exercised for those calls.

🤖 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 `@src/utils/command-references.ts` around lines 139 - 152, Make invocationStyle
required in getTransformerForTool, then update every existing call site in
command-references tests to pass the appropriate style value. Ensure the tests
exercise the intended compile-time contract rather than relying on the current
optional parameter.

🤖 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 `@docs/supported-tools.md`:
- Around line 21-35: Separate command-file classification from invocation
syntax: in docs/supported-tools.md lines 21-35, narrow the broad adapter-backed
grouping or explicitly include the Amazon Q, Cline, and Kilo Code wrapper/suffix
exceptions in the table; in docs/how-commands-work.md lines 83-88, qualify the
statement that every opsx-<id> command file uses dash syntax so tool-specific
invocation forms remain accurate.

---

Nitpick comments:
In `@src/utils/command-references.ts`:
- Around line 139-152: Make invocationStyle required in getTransformerForTool,
then update every existing call site in command-references tests to pass the
appropriate style value. Ensure the tests exercise the intended compile-time
contract rather than relying on the current optional parameter.

🪄 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 Plus

Run ID: 5e24b382-7dcc-4237-b397-cf4b257f2312

📥 Commits

Reviewing files that changed from the base of the PR and between fc886af and bf2b09a.

📒 Files selected for processing (23)

• docs/commands.md
• docs/how-commands-work.md
• docs/supported-tools.md
• openspec/specs/cli-init/spec.md
• openspec/specs/command-generation/spec.md
• src/core/command-generation/adapters/bob.ts
• src/core/command-generation/adapters/oh-my-pi.ts
• src/core/command-generation/adapters/opencode.ts
• src/core/command-generation/adapters/pi.ts
• src/core/command-generation/adapters/qwen.ts
• src/core/command-generation/generator.ts
• src/core/command-generation/invocation.ts
• src/core/command-surface.ts
• src/core/init.ts
• src/core/migration.ts
• src/core/update.ts
• src/utils/command-references.ts
• test/core/command-generation/adapters.test.ts
• test/core/command-generation/invocation.test.ts
• test/core/init.test.ts
• test/core/migration.test.ts
• test/core/update.test.ts
• test/utils/command-references.test.ts

[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 `@docs/supported-tools.md`:
- Around line 21-24: Update the command-path patterns in the table rows for
namespaced and filename-based commands to avoid incorrectly requiring `.md`; use
an extension-neutral pattern or split the entries by each documented extension,
including `.toml`, `.prompt`, and `.prompt.md`, while preserving the existing
tool mappings and command examples.
- Around line 34-36: Update the exception summary following the table to
accurately cover all exception rows: remove the “last four” and universal
`opsx-<id>` claims, distinguish wrapper and extension variations, note that
skills-only tools generate no command files, and identify Codex’s
`openspec-<id>` stem separately.

🪄 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 Plus

Run ID: e4629f56-4b69-4781-a3d2-1c8dfe560d17

📥 Commits

Reviewing files that changed from the base of the PR and between bf2b09a and 6ce948a.

📒 Files selected for processing (3)

• docs/how-commands-work.md
• docs/supported-tools.md
• test/utils/command-references.test.ts

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

• docs/how-commands-work.md
• test/utils/command-references.test.ts

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@docs/faq.md`:
- Line 39: Update the command-recovery guidance in the FAQ to recommend
`openspec init` when command files are missing or the project has not been
initialized, and reserve `openspec update` for refreshing existing command
files. Preserve the surrounding restart and “Getting started” instructions.

In `@docs/installation.md`:
- Around line 69-74: Update the OpenSpec invocation guidance in the installation
prompt to document Kimi Code’s required /skill:openspec-propose form, or
instruct users to follow the exact invocation emitted by openspec init. Preserve
the existing tool-specific forms for other integrations and ensure Kimi is not
directed to /openspec-propose.

In `@src/ui/welcome-screen.ts`:
- Around line 40-42: Update the welcome-screen bullet text around the setup
summary so it does not promise opsx slash commands for skills-only tools; use
wording that accurately covers skills and commands, or render the commands
portion conditionally based on the selected tools while preserving the existing
chalk styling.

🪄 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 Plus

Run ID: 18ad0f24-416b-4f7e-aac4-5c8d2c12d42c

📥 Commits

Reviewing files that changed from the base of the PR and between 6ce948a and 4e5e358.

📒 Files selected for processing (18)

• .changeset/command-invocation-parity.md
• README.md
• docs/commands.md
• docs/faq.md
• docs/how-commands-work.md
• docs/installation.md
• docs/supported-tools.md
• docs/troubleshooting.md
• openspec/specs/cli-init/spec.md
• openspec/specs/cli-update/spec.md
• openspec/specs/command-generation/spec.md
• openspec/specs/legacy-cleanup/spec.md
• src/core/command-generation/adapters/bob.ts
• src/core/command-generation/adapters/oh-my-pi.ts
• src/core/command-generation/adapters/pi.ts
• src/core/legacy-cleanup.ts
• src/ui/welcome-screen.ts
• test/core/legacy-cleanup.test.ts

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

• docs/supported-tools.md
• openspec/specs/command-generation/spec.md
• src/core/command-generation/adapters/oh-my-pi.ts
• docs/commands.md
• src/core/command-generation/adapters/bob.ts

[coderabbitai]

🧹 Nitpick comments (1)

test/core/update.test.ts (1)

326-327: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert a rewritten hyphen reference in each skill.

These negative-only assertions pass if the update removes every /opsx:* reference rather than rewriting it. Assert a known /opsx-... reference (and, in the stale fixture, verify the replacement seeded a colon reference).

• test/core/update.test.ts#L326-L327: assert the refreshed Cursor skill contains its expected hyphenated invocation.
• test/core/update.test.ts#L350-L354: assert the refreshed Qwen skill contains its expected hyphenated invocation.

🤖 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/update.test.ts` around lines 326 - 327, Strengthen the
refreshed-skill assertions in test/core/update.test.ts at lines 326-327 and
350-354: in each Cursor and Qwen skill test, assert the expected /opsx-...
invocation is present instead of relying only on the absence of /opsx:. For the
stale fixture, also verify that the rewrite seeded the expected colon reference,
while preserving the existing negative assertion.

🤖 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/core/update.test.ts`:
- Around line 326-327: Strengthen the refreshed-skill assertions in
test/core/update.test.ts at lines 326-327 and 350-354: in each Cursor and Qwen
skill test, assert the expected /opsx-... invocation is present instead of
relying only on the absence of /opsx:. For the stale fixture, also verify that
the rewrite seeded the expected colon reference, while preserving the existing
negative assertion.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dab321c4-866d-4834-ab35-fb1f11c5d015

📥 Commits

Reviewing files that changed from the base of the PR and between 4e5e358 and 101fece.

📒 Files selected for processing (7)

• src/core/command-generation/invocation.ts
• test/core/command-generation/adapters.test.ts
• test/core/command-generation/invocation.test.ts
• test/core/init.test.ts
• test/core/migration.test.ts
• test/core/update.test.ts
• test/utils/command-references.test.ts

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

• src/core/command-generation/invocation.ts
• test/core/command-generation/adapters.test.ts
• test/core/command-generation/invocation.test.ts
• test/core/init.test.ts

[alfred-openspec]

The central rewrite is solid, but the current invocation model still treats every flat filename as /opsx-. Amazon Q's prompt library invokes these as @, so its generated command bodies, skills, onboarding hint, and the universal table row are still wrong; please represent that wrapper in the invocation metadata instead of deriving only colon versus hyphen. Also fix the three verified current-head copy issues: use openspec init when commands are missing or the tool was never initialized, include Kimi's /skill:openspec-propose form in the installation prompt, and do not promise opsx commands in the welcome screen for skills-only tools.

[clay-good]

All four points from the review are addressed, plus three more instances of the same class found by sweeping for them. CI is green on bc270ea (14 checks, 0 failures, tests on linux/macOS/Windows).

1. Amazon Q's @ wrapper is now in the invocation metadata

You were right that deriving only colon-versus-hyphen can't represent this. An invocation now has two parts, and only one is derivable:

• The name still comes from getFilePath — that's the part that drifted before, so it stays derived.
• The prefix is adapter metadata: invocationPrefix, defaulting to /. Amazon Q's adapter declares '@'.

export interface CommandInvocation {
  style: CommandInvocationStyle;  // from the file the adapter writes
  prefix: string;                 // the tool's own, declared not guessed
}

CommandInvocationStyle alone is no longer passed anywhere; transformToHyphenCommands became transformCommandInvocations(text, invocation), and resolveCommandInvocationStyle became resolveCommandInvocation. That one change covers all four surfaces you listed — command bodies, skills, the onboarding hint, and the docs table — because they all already went through the same transformer.

A tripwire test fails if a new adapter grows an undeclared prefix, so this can't drift the way the old tool list did.

Syntax confirmed, not guessed — an earlier revision of this PR dropped the Amazon Q row precisely because I couldn't confirm it: AWS prompt management docs and aws/amazon-q-developer-cli#2243 both give @prompt-name.

$ openspec init --tools claude,cursor,amazon-q,kimi,codex
Getting started:
  Start your first change: /opsx:propose "your idea" (Claude Code)
  Start your first change: /opsx-propose "your idea" (Cursor)
  Start your first change: @opsx-propose "your idea" (Amazon Q Developer)
  Start your first change: /skill:openspec-propose "your idea" (Kimi Code)
  Start your first change: $openspec-propose "your idea" (Codex)

$ for d in .claude .cursor .amazonq .kimi-code .codex; do ... done
.claude      /opsx:
.cursor      /opsx-
.amazonq     @opsx-
.kimi-code   /skill:openspec-
.codex       $openspec-

No stray /@opsx, @/opsx, or @opsx: anywhere — the rewrite consumes the whole /opsx:. openspec update --force also heals a project generated before this fix, covered by a new test.

2–4. The three copy issues

• openspec init when commands are missing — fixed in faq.md. Confirmed the behavior first: update iterates getConfiguredToolsForProfileSync, so a tool that was never initialized isn't in the config and update does nothing for it.
• Kimi's /skill:openspec-propose — added to the installation prompt, along with Amazon Q's @opsx-propose.
• Welcome screen — the "opsx slash commands" bullet is now "Workflow commands, if supported". It renders one prompt before tool selection (init.ts:192 vs :199), so it can't be made conditional; the honest fix is to stop asserting. Kept to 35 chars to hold the existing 59-column animation budget.

Three more of the same, found by sweeping

Your review named four sites; the same false promise appeared in three others:

Where	Was	Now
Welcome quick-start	literal /opsx:propose	marked "spelling varies by tool"
Post-setup restart line	"slash commands to take effect"	"the new commands"
README + troubleshooting	exception lists skipped Amazon Q	@opsx-propose named

The troubleshooting one was actively misleading: it explained that /opsx never autocompletes for tools without command files, and Amazon Q isn't one of those — it has command files, they just land in the prompt library rather than the slash menu.

On CodeRabbit's Cline and Kilo Code claim

Checked and not reproduced — no exception needed. Cline's workflow docs say a workflow is invoked by filename without the extension, and Kilo Code's docs say the current format drops the .md suffix. Both are plain /opsx-<id>, which is what the flat rule already produces. Its update.test.ts nitpick was already handled in e4db819.

Verification

npm run build, npm run lint, npx tsc --noEmit, npx vitest run — 3,334 tests / 115 files, all pass. openspec validate --all is 52/53; the one failure (change/schema-alias-support) is pre-existing on main and unrelated.

[alfred-openspec]

Verified exact head bc270ea: Amazon Q now uses @opsx-*, Codex/Kimi and other skills-only hints use their real forms, and init/update/migration stay consistent. Build, lint, 1,304 focused tests, and all hosted checks are green.

[alfred-openspec]

Re-reviewed exact head 8fea739. The added migration regression proves Amazon Q keeps its @opsx-* form and falls back safely when mixed with slash-command tools; the prior init, update, docs, Kimi, Codex, and skills-only fixes remain intact. Build, lint, 1,407 focused tests, and all hosted checks pass.