fix(init): clarify Codex desktop skill usage

[javigomez]

Summary

• Clarify that $openspec-propose is the supported invocation for Codex CLI and IDE.
• Tell Codex desktop app users to select openspec-propose from the Skills sidebar.
• Add documentation, regression assertions, and a patch changeset.

Why

openspec init installs Codex skills under .agents/skills and intentionally skips command files. The existing hint is correct for CLI and IDE, but can be misleading in the desktop app where typing the $... form may not provide an obvious action. /opsx-* is not a Codex command.

Tests

• npm run lint -- --quiet
• npm run build
• npx vitest run test/core/init.test.ts --reporter=verbose
• npx vitest run --silent --reporter=dot --no-color

Summary by CodeRabbit

• Documentation

  • Clarified how to invoke OpenSpec skills in Codex CLI, IDE, and desktop app.
  • Added guidance for selecting openspec-propose from the Codex desktop Skills sidebar.

• User Experience

  • Updated setup completion messages with Codex-specific instructions for getting started.
  • Improved onboarding guidance for users working across Codex environments.

• Tests

  • Added coverage to verify Codex CLI/IDE and desktop app instructions appear correctly.

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

Run ID: 1040b344-5b4c-400b-8ff6-869ca9b4c962

📥 Commits

Reviewing files that changed from the base of the PR and between a0ddb60 and 2f32b6e.

📒 Files selected for processing (4)

• .changeset/quiet-codex-skill-hint.md
• docs/supported-tools.md
• src/core/init.ts
• test/core/init.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR clarifies Codex onboarding instructions for CLI, IDE extension, and desktop app users. The initialization hint, supporting documentation, tests, and patch changeset now reflect the separate Codex workflows.

Changes

Codex onboarding

Layer / File(s)	Summary
Codex guidance and release metadata docs/supported-tools.md, .changeset/quiet-codex-skill-hint.md	Documents $openspec-propose for Codex CLI and IDE users, Skills sidebar selection for the desktop app, and the related patch release.
Codex setup hint and tests src/core/init.ts, test/core/init.test.ts	Adds Codex-specific setup hints and verifies the CLI/IDE label and Skills sidebar instruction in Codex hint scenarios.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 2f32b

This change clarifies how users invoke an existing Codex skill in different interfaces without changing runtime behavior, access, or security controls. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: alfred-openspec, clay-good, tabishb

🚥 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 and concisely describes the main change: clarifying Codex desktop skill usage during initialization.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
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.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (2 skipped: 2 unsupported.)

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

[alfred-openspec]

Verified against the current official Codex skills guidance: CLI and IDE support $ skill mentions, while the desktop app exposes skills through its sidebar. The Codex-only hint preserves the existing behavior for other tools, the single- and multi-tool paths are covered, and all hosted CI and Security checks are green. Approved at 2f32b6e.