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#

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.

2. Read state first. openspec_list { kind: "changes" } shows active changes. openspec_status shows artifact completion.

3. Propose a change. Create openspec/changes/<change-name>/ with:

   • proposal.md — why this change, what it changes, who benefits
   • specs/ — requirements grouped by capability
   • design.md — technical approach
   • tasks.md — implementation checklist (each task on its own line)

4. Validate. openspec_validate { name: "<change-name>" } catches structural issues.

5. Apply (implement). Work through tasks.md, ticking each item as you finish. Keep diffs scoped — one task at a time.

6. Sync / archive. openspec_archive { changeName: "<change-name>", yes: true } rolls the change's specs into the main spec set and moves the folder under openspec/changes/archive/<date>-<name>/.

Tool reference#

ToolPurposeopenspec_initScaffold openspec/ in a project, optionally with --tools <ids> and --profile <name>``openspec_updateRegenerate AI assistant instructions after upgrading openspecopenspec_listList active changes (default) or specsopenspec_showShow a single change/spec, optionally include raw files via includeFiles: true``openspec_validateValidate change/spec structureopenspec_archiveArchive a completed changeopenspec_statusArtifact completion status for the project or a changeopenspec_runEscape 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_validate before declaring a change ready.
• Do not archive a change that still has unchecked items in tasks.md unless 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.