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.
   • Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
   • Note everything that is now inconsistent, missing, or contradictory.
   • Revise only files that already exist (existingOutputPaths). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to /opsx:propose (same change name) to create them.
   • If the change is already coherent, say so and make no edits.

5. Confirm and apply, one artifact at a time

   • Show each proposed revision and why. Write only after the user confirms.
   • If the user rejects a revision, do not write it - leave that artifact unchanged.
   • When a substantial rewrite is needed, get that artifact's rules and template first:

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

   • If the artifact being revised is tasks, worktrail's own orchestrator (not OpenSpec) compiles tasks.md into a per-task file-scope plan afterward (worktrail-compile), and OpenSpec's checklist schema carries no field for that. This is a delta edit, not a fresh write - apply these rules only to the task line(s) this revision adds or changes scope for; do not retroactively rewrite untouched existing task lines to add tags they lack:
     • Requirement coverage: if the revision adds or rescopes a task so it implements a requirement declared in this change's specs/**/spec.md (### Requirement: <Name> under ## ADDED Requirements / ## MODIFIED Requirements), append (Requirement: <exact title>) to that task line - the exact requirement name must appear somewhere in tasks.md.
     • File-less tasks: if the revision adds or rescopes a task that creates or modifies no file (pure end-to-end verification, or pure cleanup with no diff), give it a leading tail-kind tag or worktrail-compile rejects it for having no file scope: [e2e] for verification-only tasks, [cleanup] for cleanup-only tasks - e.g. - [ ] 3.1 [e2e] Run the full test suite and confirm it passes. Any other kind tag, including [docs], does NOT exempt a task from file scope - a [docs]-tagged task still needs a real file (the doc it updates).

6. Point to the next step (guidance only - NEVER act on it)

   • Artifacts still missing -> suggest /opsx:propose (same change name) to create them.
   • Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; within a worktrail pipeline point to worktrail-sdd-workflow's implement pipeline (NOT /opsx:apply, which worktrail's orchestrator replaces).
   • Everything done and implemented -> suggest /opsx:archive.

Output

After each invocation, show:

• Which artifacts were revised (and which proposed revisions were rejected)
• Anything deferred to /opsx:propose (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 worktrail-sdd-workflow's implement pipeline (NOT /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:propose's job (re-run against the same change name).
• 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).
• Before writing a tasks.md revision, re-check only the task line(s) this revision touched against the requirement-coverage and file-less-task rules above - an added or rescoped task implementing a declared requirement must carry (Requirement: <exact title>), and one with no file changes must carry [e2e] or [cleanup]. Do not touch untouched existing lines to satisfy this check.