openspec-apply-change

Apply OpenSpec Change

Implement tasks from an OpenSpec change.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. Select the change

   If a name is provided, use it. Otherwise:

   • Infer from conversation context if the user mentioned a change
   • Auto-select if only one active change exists
   • If ambiguous, run openspec list --json to get available changes and use the AskUserQuestion tool to let the user select

   Always announce: "Using change: " and how to override (e.g., /opsx:apply <other>).

2. Check status to understand the schema

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

   Parse the JSON to understand:

   • schemaName: The workflow being used (e.g., "spec-driven")
   • Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)

3. Get apply instructions

   openspec instructions apply --change "<name>" --json
   

   This returns:

   • contextFiles: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
   • Progress (total, complete, remaining)
   • Task list with status
   • Dynamic instruction based on current state

   Handle states:

   • If state: "blocked" (missing artifacts): show message, suggest using openspec-continue-change
   • If state: "all_done": skip implementation tasks, but still run the prototype-retention and consolidate completion steps below before suggesting archive
   • Otherwise: proceed to implementation

4. Read context files

   Read every file path listed under contextFiles from the apply instructions output. The files depend on the schema being used:

   • spec-driven: proposal, specs, design, tasks
   • Other schemas: follow the contextFiles from CLI output

5. Show current progress

   Display:

   • Schema being used
   • Progress: "N/M tasks complete"
   • Remaining tasks overview
   • Dynamic instruction from CLI

6. Implement tasks (loop until done or blocked)

   For each pending task:

   • Show which task is being worked on
   • Make the code changes required
   • Keep changes minimal and focused
   • Mark task complete in the tasks file: - [ ] → - [x]
   • Continue to next task

   Pause if:

   • Task is unclear → ask for clarification
   • Implementation reveals a design issue → suggest updating artifacts
   • Error or blocker encountered → report and wait for guidance
   • User interrupts

   After all tasks are complete and the schema is spec-driven-plus, finalize prototype retention before generating consolidate:

   • Read <changeRoot>/prototype.md. If it is a non-UI stub, record Prototype retention: not applicable and continue.
   • If it references HTML files, load prototype-workflow and apply its long-term-value and validity gates to every file.
   • Add or update the ## Prototype Retention table with one final archive or delete decision and a concrete rationale per file.
   • For every delete decision, immediately delete the HTML from docs/prototypes/, remove its docs/prototypes/README.md index entry, and replace or remove references in the current change so no broken link remains.
   • Leave archive files in the staging directory until /opsx:archive.
   • Verify every referenced prototype has a final decision and every deleted path no longer exists.

   After all tasks are complete and the schema is spec-driven-plus, check for the consolidate artifact:

   openspec instructions consolidate --change "<name>" --json
   

   If the instructions indicate consolidate is pending (not already done), read the consolidate template, scan related archived changes, and generate consolidate.md before proceeding to completion.

   Skip if:

   • Schema is not spec-driven-plus (only this schema has consolidate)
   • consolidate.md already exists and is complete