openspec-apply-change

Implement tasks from an OpenSpec change. ## Local Workflow Customizations The steps labeled **Local Customization** are repository-specific additions layered on top of the upstream OpenSpec skill. Keep them grouped when merging future upstream updates so the local workflow policy stays easy to review and reapply. **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`). 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**: 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: <name>" and how to override (e.g., `/opsx:apply <other>`). 2. **Check status to understand the schema** ```bash openspec status --change "<name>" --json ``` Parse the JSON to understand: - `schemaName`: The workflow being used (e.g., "spec-driven") - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) 3. **Local Customization: commit planning artifacts before apply when needed** Inspect git status before implementation begins. - If the selected change's planning artifacts are already committed, continue. - If files under the selected change's planning artifacts are uncommitted, stage only the files relevant to that change and create a commit before proceeding into apply. - If unrelated uncommitted work would be swept into that commit, pause and ask the user how to proceed rather than bundling unrelated changes. - This is a phase-boundary checkpoint only; do not create an additional "end-of-apply" commit in this skill. 4. **Get apply instructions** ```bash 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"`: congratulate, suggest archive - Otherwise: proceed to implementation 5. **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 6. **Show current progress** Display: - Schema being used - Progress: "N/M tasks complete" - Remaining tasks overview - Dynamic instruction from CLI 7. **Implement tasks (loop until done or blocked)** For each pending task: - Show which task is being worked on - If a task is a workflow/meta action (for example commit, spec sync, or archive), treat it as invalid task content, call it out, and do not execute it as implementation work - 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 8. **On completion or pause, show status** Display: - Tasks completed this session - Overall progress: "N/M tasks complete" - If all done: suggest archive - If paused: explain why and wait for guidance **Output During Implementation** ``` ## Implementing: <change-name> (schema: <schema-name>) Working on task 3/7: <task description> [...implementation happening...] ✓ Task complete Working on task 4/7: <task description> [...implementation happening...] ✓ Task complete ``` **Output On Completion** ``` ## Implementation Complete **Change:** <change-name> **Schema:** <schema-name> **Progress:** 7/7 tasks complete ✓ ### Completed This Session - [x] Task 1 - [x] Task 2 ... All tasks complete! Ready to archive this change. ``` **Output On Pause (Issue Encountered)** ``` ## Implementation Paused **Change:** <change-name> **Schema:** <schema-name> **Progress:** 4/7 tasks complete ### Issue Encountered <description of the issue> **Options:** 1. <option 1> 2. <option 2> 3. Other approach What would you like to do? ``` **Guardrails** - Keep going through tasks until done or blocked - Always read context files before starting (from the apply instructions output) - Commit the selected change's planning artifacts before entering apply when that phase boundary has uncommitted work - Do not create a post-implementation commit in apply; archive handles the next commit checkpoint when needed - Do not treat commit/sync/archive workflow actions as implementation tasks - If task is ambiguous, pause and ask before implementing - If implementation reveals issues, pause and suggest artifact updates - Keep code changes minimal and scoped to each task - Update task checkbox immediately after completing each task - Pause on errors, blockers, or unclear requirements - don't guess - Use contextFiles from CLI output, don't assume specific file names **Fluid Workflow Integration** This skill supports the "actions on a change" model: - **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions - **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly