openspec-update-change

name	openspec-update-change
description	Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
allowed-tools	Bash(openspec:*)
license	MIT
compatibility	Requires openspec CLI.
metadata	{"internal":true,"author":"openspec","version":"1.0","generatedBy":"1.6.0"}

Revise a change's existing planning artifacts and keep them coherent. Never edit code.

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. If no change name provided, prompt for selection

   Run openspec list --json to get available changes sorted by most recently modified. Then use the AskUserQuestion tool to let the user select which change to update.

   Present the top 3-4 most recently modified changes as options, showing:

   • Change name
   • Schema (from schema field if present, otherwise "spec-driven")
   • Status (e.g., "0/5 tasks", "complete", "no tasks")
   • How recently it was modified (from lastModified field)

   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Get the change's artifacts

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

   Parse the JSON to understand current state. The response includes:

   • schemaName: The workflow schema being used (e.g., "spec-driven")
   • artifacts: Array of artifacts with their status ("done", "ready", "blocked")
   • isComplete: Boolean indicating if all artifacts are complete
   • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context. Use these instead of assuming repo-local paths.

   The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.

   The files to edit are artifactPaths.<id>.existingOutputPaths - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. specs/**/*.md). Do NOT write to resolvedOutputPath: for a glob artifact it is still the glob pattern, not a real file.

3. Understand the request

   • If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
   • If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.

4. Read and reconcile

   • Read the artifact(s) the request touches and the change's other existing artifacts.

Output

After each invocation, show:

• Which artifacts were revised (and which proposed revisions were rejected)
• Anything deferred to /opsx:continue (not-yet-created artifacts or files)
• Where the change stands and the recommended next command

Guardrails

• Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to /opsx:apply.
• Use the artifact ids and paths reported by openspec status; never branch on hardcoded artifact names.
• Edit only the concrete files in existingOutputPaths; never write to a glob resolvedOutputPath.
• Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is /opsx:continue's job.
• Confirm every edit with the user before writing.
• If the request changes the change's intent rather than refining it, recommend starting fresh with /opsx:new (the "Update vs. Start Fresh" heuristic).