OpenSpec
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.
When to use
- The user asks to propose, scope, or specify a change before coding.
- The project already has
openspec/— keep using it. - The change touches multiple files or modules and benefits from a checklist.
- The user wants to archive a completed change ("close out the dark-mode change").
Skip OpenSpec for trivial edits (one-line fixes, typos, log tweaks). The ceremony is not worth it.
Core workflow
- Confirm the project is OpenSpec-enabled. Look for
openspec/at the project root. If missing and the user wants to start:openspec_initwith the appropriatetoolslist for their AI assistant. - Read state first.
openspec_list { kind: "changes" }shows active changes.openspec_statusshows artifact completion. - Propose a change. Create
openspec/changes/<change-name>/with:proposal.md— why this change, what it changes, who benefitsspecs/— requirements grouped by capabilitydesign.md— technical approachtasks.md— implementation checklist (each task on its own line)
- Validate.
openspec_validate { name: "<change-name>" }catches structural issues. - Apply (implement). Work through
tasks.md, ticking each item as you finish. Keep diffs scoped — one task at a time. - Sync / archive.
openspec_archive { changeName: "<change-name>", yes: true }rolls the change's specs into the main spec set and moves the folder underopenspec/changes/archive/<date>-<name>/.
Tool reference
| Tool | Purpose |
|---|---|
openspec_init |
Scaffold openspec/ in a project, optionally with --tools <ids> and --profile <name> |
openspec_update |
Regenerate AI assistant instructions after upgrading openspec |
openspec_list |
List active changes (default) or specs |
openspec_show |
Show a single change/spec, optionally include raw files via includeFiles: true |
openspec_validate |
Validate change/spec structure |
openspec_archive |
Archive a completed change |
openspec_status |
Artifact completion status for the project or a change |
openspec_run |
Escape hatch for openspec subcommands not surfaced above |
Anti-patterns
- 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.
- Do not skip
openspec_validatebefore declaring a change ready. - Do not archive a change that still has unchecked items in
tasks.mdunless the user explicitly accepts the partial state. - 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.
For longer examples and trigger patterns, see references/workflow.md.