Context
I run OpenSpec across many projects, initialized per-project via the node package (@fission-ai/openspec) with agent instructions (Claude, Codex, etc.).
Problem (discovery gap)
The workflow commands are namespaced as /opsx:explore, /opsx:propose, /opsx:apply, /opsx:archive, /opsx:sync — but both users and LLM agents naturally say/type "openspec explore", "openspec propose", etc. Nothing in the project scaffold that openspec init generates maps that natural verb to the actual slash command.
Observed impact
The agent routinely misreads "do an openspec explore/propose" as an invitation to hand-build the artifact with the CLI (openspec new change + manual file writes) instead of invoking /opsx:explore or /opsx:propose. That bypasses the official openspec instructions <artifact> template flow and the TodoWrite-driven sequence, and (for explore) violates the "think, don't implement" stance. This happens repeatedly, across sessions.
Proposed fix
Since openspec init / openspec update already emit per-agent instruction files (CLAUDE.md, AGENTS.md, ...), inject a short verb→command mapping into those generated files at init/update time, e.g.:
"When the user says 'openspec explore/propose/apply/archive/sync', run the matching /opsx:<verb> command — do not hand-build the artifact."
Optional: also accept a natural-language alias so openspec explore resolves to /opsx:explore directly.
Benefit
Any agent in any project inherits the mapping at init time, instead of relying on each user's private global memory. Fixes the root cause (discovery) rather than the symptom.
Related
Side note: the openspec feedback CLI command appears broken — it fails with could not add label: 'feedback' not found, which is why this is filed as a GitHub issue instead. The label may not exist in this repo's issue tracker.
Context
I run OpenSpec across many projects, initialized per-project via the node package (
@fission-ai/openspec) with agent instructions (Claude, Codex, etc.).Problem (discovery gap)
The workflow commands are namespaced as
/opsx:explore,/opsx:propose,/opsx:apply,/opsx:archive,/opsx:sync— but both users and LLM agents naturally say/type "openspec explore", "openspec propose", etc. Nothing in the project scaffold thatopenspec initgenerates maps that natural verb to the actual slash command.Observed impact
The agent routinely misreads "do an openspec explore/propose" as an invitation to hand-build the artifact with the CLI (
openspec new change+ manual file writes) instead of invoking/opsx:exploreor/opsx:propose. That bypasses the officialopenspec instructions <artifact>template flow and the TodoWrite-driven sequence, and (for explore) violates the "think, don't implement" stance. This happens repeatedly, across sessions.Proposed fix
Since
openspec init/openspec updatealready emit per-agent instruction files (CLAUDE.md, AGENTS.md, ...), inject a short verb→command mapping into those generated files at init/update time, e.g.:Optional: also accept a natural-language alias so
openspec exploreresolves to/opsx:exploredirectly.Benefit
Any agent in any project inherits the mapping at init time, instead of relying on each user's private global memory. Fixes the root cause (discovery) rather than the symptom.
Related
/opsx:*command references #879 (skills-only delivery cross-refs)Side note: the
openspec feedbackCLI command appears broken — it fails withcould not add label: 'feedback' not found, which is why this is filed as a GitHub issue instead. The label may not exist in this repo's issue tracker.