openspec-ff-change

Fast-forward through artifact creation - generate everything needed to start implementation in one go.

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.

Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.

Steps

1. If no clear input provided, ask what they want to build

   Ask the user (open-ended, no preset options):

   "What change do you want to work on? Describe what you want to build or fix."

   From their description, derive a kebab-case name (e.g., "add user authentication" → add-user-auth).

   IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Create the change directory

   openspec new change "<name>"
   

   This creates a scaffolded change in the planning home resolved by the CLI.

3. Get the artifact build order

   openspec status --change "<name>" --json
   

   Parse the JSON to get:

   • applyRequires: array of artifact IDs needed before implementation (e.g., ["tasks"])
   • artifacts: list of all artifacts, each with its status and its requires edges (the artifact IDs it directly depends on)
   • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context. Use these instead of assuming repo-local paths.

4. Create every artifact in the required set

   Use a todo list to track progress through the artifacts.

   Loop through artifacts in dependency order (artifacts with no pending dependencies first):

   a. For each artifact that is ready (dependencies satisfied):

   • Get instructions:

     openspec instructions <artifact-id> --change "<name>" --json
     

   • The instructions JSON includes:
     • context: Project background (constraints for you - do NOT include in output)
     • rules: Artifact-specific rules (constraints for you - do NOT include in output)
     • template: The structure to use for your output file
     • instruction: Schema-specific guidance for this artifact type
     • skipped/warning: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
     • resolvedOutputPath: Resolved path or pattern to write the artifact
     • dependencies: Completed artifacts to read for context
   • Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
   • If the instruction field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at resolvedOutputPath
   • Otherwise create the artifact file using template as the structure and write it to resolvedOutputPath. If resolvedOutputPath is a glob, follow instruction to choose the concrete file path
   • Apply context and rules as constraints - but do NOT copy them into the file
   • Show brief progress: "✓ Created "

   b. Continue until every artifact in the required set exists (not just apply.requires)

   • After creating each artifact, re-run openspec status --change "<name>" --json
   • The required set is applyRequires plus every artifact reachable from those by following the requires edges in status --json - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
   • status is file-existence only, so an applyRequires artifact reading done does NOT mean its dependencies exist - writing tasks.md early marks tasks done while specs was never written. Use each artifact's requires edges, not its status, to build the required set: a done artifact still lists what it depends on
   • An artifact already reading status: "skipped" is satisfied: the change declares skip_specs in .openspec.yaml, so its files must NOT exist. Never try to create one
   • Create every artifact in the required set that is missing, then re-check - creating one can unblock others
   • Skip one only when status already reports it skipped, or when its own instruction says it is conditional: run openspec instructions <artifact-id> --change "<name>" --json and skip only if its instruction field marks it optional (e.g. "create only if..."). Spec-driven's design.md qualifies; specs qualifies only via the skipped status above, never by your own judgment. Tell the user, and do not reconsider it
   • Dependencies are enablers, not gates: if a required artifact is still blocked only because you skipped a conditional dependency, write it anyway
   • Stop when every artifact in the required set is done, skipped, or was deliberately skipped