\r \r

OpenSpec\r

\r Use OpenSpec to align on what before writing how. Specs and proposals live under openspec/ in the project. Each in-flight change gets its own folder with proposal.md, specs/, design.md, and tasks.md.\r \r

When to use\r

\r

• The user asks to propose, scope, or specify a change before coding.\r
• The project already has openspec/ — keep using it.\r
• The change touches multiple files or modules and benefits from a checklist.\r
• The user wants to archive a completed change ("close out the dark-mode change").\r \r Skip OpenSpec for trivial edits (one-line fixes, typos, log tweaks). The ceremony is not worth it.\r \r

Core workflow\r

\r

1. Confirm the project is OpenSpec-enabled. Look for openspec/ at the project root. If missing and the user wants to start: openspec_init with the appropriate tools list for their AI assistant.\r
2. Read state first. openspec_list { kind: "changes" } shows active changes. openspec_status shows artifact completion.\r
3. Propose a change. Create openspec/changes/\x3Cchange-name>/ with:\r
   • proposal.md — why this change, what it changes, who benefits\r
   • specs/ — requirements grouped by capability\r
   • design.md — technical approach\r
   • tasks.md — implementation checklist (each task on its own line)\r
4. Validate. openspec_validate { name: "\x3Cchange-name>" } catches structural issues.\r
5. Apply (implement). Work through tasks.md, ticking each item as you finish. Keep diffs scoped — one task at a time.\r
6. Sync / archive. openspec_archive { changeName: "\x3Cchange-name>", yes: true } rolls the change's specs into the main spec set and moves the folder under openspec/changes/archive/\x3Cdate>-\x3Cname>/.\r \r

Tool reference\r

\r | Tool | Purpose |\r | --- | --- |\r | openspec_init | Scaffold openspec/ in a project, optionally with --tools \x3Cids> and --profile \x3Cname> |\r | openspec_update | Regenerate AI assistant instructions after upgrading openspec |\r | openspec_list | List active changes (default) or specs |\r | openspec_show | Show a single change/spec, optionally include raw files via includeFiles: true |\r | openspec_validate | Validate change/spec structure |\r | openspec_archive | Archive a completed change |\r | openspec_status | Artifact completion status for the project or a change |\r | openspec_run | Escape hatch for openspec subcommands not surfaced above |\r \r

Anti-patterns\r

\r

• Do not invent specs for changes the user did not ask to formalize. Use OpenSpec when the user wants spec-driven flow, not as a tax on every edit.\r
• Do not skip openspec_validate before declaring a change ready.\r
• Do not archive a change that still has unchecked items in tasks.md unless the user explicitly accepts the partial state.\r
• Do not edit openspec/specs/ directly in the middle of a change — drive spec updates through the change folder and let archive roll them in.\r \r For longer examples and trigger patterns, see references/workflow.md.\r