openspec-propose

Installation
SKILL.md

Propose a new change - create the change and generate all artifacts in one step.

Planning boundary: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.

I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:

  • proposal.md (what & why)
  • specs/<capability-path>/spec.md (what the system must do - a delta, not the main spec)
  • design.md (how)
  • tasks.md (implementation steps)

<capability-path> is the spec directory relative to specs/ (for example, user-auth or identity/user-auth). Preserve an existing capability's full path and follow the project's established organization for new capabilities.

When the user is ready to implement, they must start the apply workflow explicitly.


Store selection: If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run openspec store list --json to discover registered store ids, then pass --store <id> on the commands that read or write specs and changes (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Once selected, treat --store <id> as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run openspec status --change "<name>" --json --store "<id>", not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local openspec/ root.

Project check: These steps expect a project that already uses OpenSpec. Before the first step that writes anything (new change, archive, sync specs, or authoring an artifact file), confirm the project has a root: run openspec list --json (with --store <id> when a store is selected, since the store is then the root) and read root. A root object means the project is set up. "root": null means it is not - there is no openspec/ directory here, and a write such as openspec new change would create one as a side effect. The command also exits non-zero, which is that answer rather than a broken CLI, so read the JSON instead of retrying or working around it.

Installs
3.7K
GitHub Stars
71.8K
First Seen
Jul 17, 2026