OpenSpec

Use OpenSpec (@fission-ai/openspec) for spec-driven development when implementing non-trivial changes in existing projects. Use when the environment exposes openspec tools (openspec_init, openspec_list, openspec_show, openspec_validate, openspec_archive, openspec_status, openspec_update, openspec_run). Triggered by user phrases like "propose a change", "spec this out", "open a change for X", or when starting a multi-step feature in a repo that already has an openspec/ directory.

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

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_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.