Move OpenSpec to Agent Skills only (deprecate generated commands) #2022

Activity

1. clay-good commented on Oct 7, 2026

   

   clay-good

   on Oct 7, 2026

   Last edited by clay-good

   Collaborator

   More actions

   Proposed build — Phase 1 is in review

   Scope is unchanged: this only affects generated command files. The openspec CLI stays, since skills still call it for status, validate and archive.

   Phase 1 PRs (merge in this order)

   #	PR	What it does
   1	#2087	update deletes only command files OpenSpec generated. Edits, and files it can't read, are kept and listed
   2	#2089	update prints a deprecation notice with the switch and keep-commands steps; docs say the same
   3	#2091	Amazon Q keeps its prompts under every delivery setting, since it loads no skills
   4	#2092	CoStrict skills install where CoStrict reads them; Hermes note made current. Closes this issue, so it merges last

   Nothing changes on the default delivery in Phase 1. Merged together locally, the four pass the full suite: 6,440 tests, plus the same 10 failures main already has.

   Design principles

   1. openspec update is the migration. No script, no flag, no manual steps.
   2. Never delete a file we didn't write. Compare before unlinking; keep anything that differs and print its path.
   3. Reconstruct the generation inputs from disk. Command content depends on which workflows were installed, so compare against the set actually present.
   4. Write skills before touching commands. A run that dies halfway leaves working commands.
   5. Separate detection from writing. An adapter's getFilePath finds command files; formatFile writes them. Writing can go long before detection.
   6. Deprecate the default, not the feature. delivery: both keeps working until there's evidence nobody needs it.

   Phases

   Phase	Release	What changes
   1	Next minor	The four PRs above
   2	Next major	Default becomes delivery: skills; generated commands cleared; warning shown
   3	After an observation period	Remove command writing and the delivery setting
   4	Later	Remove the adapter shells

   What the audit got wrong, and what changed

   Every per-tool claim was rechecked against upstream source, not docs. Two of my earlier statements were wrong:

   • OpenCode needs no change. I said a skill becomes /name only with metadata: opencode/slash: "true". OpenCode's docs say so, but no code in the release or on main reads that key. In released v1.19.0, command/index.ts registers every skill as a slash command. The planned OpenCode PR was dropped.
   • Amazon Q needed real work. Its CLI reads .amazonq/prompts and has no skill support. Under skills-only delivery it would have had no working workflow at all, so the default flip would have broken every Amazon Q user. That's fix(amazon-q): keep Amazon Q's prompts under every delivery setting #2091, which takes the least disruptive answer to the open Amazon Q question: keep its commands. AWS ends support for the IDE plugins on April 30, 2027 and points users to Kiro, which OpenSpec supports.

   Also confirmed in source:

   • Gemini CLI registers every skill as a slash command (SkillCommandLoader.ts, autoExecute: true), so no tool is left without a way to start a workflow.
   • CoStrict reads project skills from .agents, .claude and .roo, never .cospec. Its users relied on commands alone, so the flip would have broken them too.
   • Hermes v2026.6.5+ loads a trusted repo's .hermes/skills after hermes skills trust.

   Traps found and fixed along the way

   • Global delivery inference. On first run, OpenSpec saves a delivery inferred from the files on disk globally. An Amazon-Q-only project would have saved delivery: commands and stripped skills from every other project on the machine. Fixed in fix(amazon-q): keep Amazon Q's prompts under every delivery setting #2091; shown before and after on the real CLI.
   • Update loop, already on main. A tool sharing .agents with an owner tool, plus a customized legacy skill, re-synced on every update. Reproduced with Antigravity and Codex. The CoStrict move would have spread it to every CoStrict user sharing .agents. Fixed in fix(costrict): install skills where CoStrict reads them #2092.

   For Phase 2, not Phase 1

   • Migrated users have an explicit delivery: both they never chose. migrateIfNeeded writes the inferred value, so a flip that keeps explicit settings would skip most existing users. That needs deciding before the flip.
   • Edited command files are already overwritten by a plain update under both, by design ("generated files are OpenSpec's to own"). fix(update): keep command files the user edited when moving to skills #2087 guarantees the switch never deletes an edit still on disk. The notice's own advice, openspec config set delivery skills && openspec update, switches before any regeneration.
   • Keep the adapters through Phase 3. Cleanup is gated on CommandAdapterRegistry.has(toolId) and finds files via adapter.getFilePath(). Delete an adapter and update silently stops finding that tool's leftovers.
   • Still to settle: what evidence moves us from Phase 2 to Phase 3.
2. clay-good

   added 9 commits that reference this issue on Oct 14, 2026

   fix(update): report unreadable command files apart from edits

   ...

   7553e83

   docs(update): describe when the deprecation notice shows accurately

   ...

   2563f0f

   fix(update): only advise switching where it changes something

   ...

   29a3df1

   docs(amazon-q): say when leftover skill folders are removed

   ...

   497ff3c

   test: give the deprecation notice tests their own anchor in update.te…

   ...

   239ddaf

   test: give the Amazon Q tests their own anchor in update.test.ts

   ...

   561bc44

   fix(costrict): install skills where CoStrict reads them

   ...

   8d206bd

   fix(costrict): install skills where CoStrict reads them

   ...

   d0f268c

   test: read the supported-tools page with normalized line endings

   ...

   0b192a0