docs: align cli-update OpenCode spec with commands/ and opsx-* paths

[HowardYan888]

Summary

• Update the OpenCode cli-update scenario to use .opencode/commands/ and opsx-*.md filenames, matching the adapter and OpenCode command directory: command/ vs commands/ #748 fix.
• Document hyphen command-reference transforms for OpenCode.
• Add a legacy scenario clarifying that .opencode/command/ files are cleaned up via openspec init/legacy cleanup, not refreshed by openspec update.

Test plan

• Docs-only change; no code or runtime behavior changes.
• Verified spec wording against src/core/command-generation/adapters/opencode.ts and legacy cleanup tests.

Made with Cursor

Summary by CodeRabbit

• Documentation
  • Updated the openspec update command specification to clarify how OpenSpec-managed command files are refreshed, how command references are formatted for compatibility, and which frontmatter placeholder must be present for change ID arguments.
  • Documented a legacy command path cleanup scenario, including when openspec init/cleanup is required and ensuring openspec update does not refresh files that remain only in the legacy location.

[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

Run ID: 62446053-e482-4331-a732-13ef59b37e8d

📥 Commits

Reviewing files that changed from the base of the PR and between 1677566 and 53f0955.

📒 Files selected for processing (1)

• openspec/specs/cli-update/spec.md

💤 Files with no reviewable changes (1)

• openspec/specs/cli-update/spec.md

---

📝 Walkthrough

Walkthrough

This PR updates the OpenSpec CLI update specification for OpenCode command files, covering managed files under .opencode/commands/, hyphenated command references, archive argument handling, and legacy path cleanup.

Changes

CLI Update Specification Refinement

Layer / File(s)	Summary
OpenCode command update scenario specification openspec/specs/cli-update/spec.md	The specification defines refreshing opsx-*.md files under .opencode/commands/, converting command references to hyphen form, requiring $ARGUMENTS in archive frontmatter, and cleaning up legacy .opencode/command/ files. Legacy-only files are excluded from openspec update refreshes.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• Fission-AI/OpenSpec#627: Addresses a related OpenCode command reference conversion from colon to hyphen form.

Suggested reviewers: 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 matches the docs-only spec update for OpenCode cli-update paths and opsx-* command files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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]

This now matches the OpenCode adapter’s plural commands path, opsx filenames, hyphen references, and the existing legacy-cleanup behavior. Approved with the full CI matrix green.