Update an existing Spectra change from external context
Update an existing Spectra change — from a plan file or conversation context.
Plan file support is available when the tool has a plan directory (~/.claude/plans/). Otherwise, use conversation context to update artifacts.
Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.
Input: Optionally specify a plan file path or name.
/spectra-ingest ~/.claude/plans/agile-discovering-rocket.md/spectra-ingest agile-discovering-rocket/spectra-ingest (use conversation context or auto-detect plan file)Steps
Locate the requirement source
a. Argument provided → treat as plan file reference (prepend ~/.claude/plans/ and append .md if needed)
b. No argument, plan file detectable:
~/.claude/plans/<name>.md)c. No argument, no plan file detectable:
~/.claude/plans/ for recent filesd. Conversation context fallback (no plan files found at all):
Parse the plan structure (skip if using conversation context)
Claude Code plan files typically contain:
# ...) — the high-level goalExtract:
plan_title: from the H1 headingplan_context: from the Context sectionplan_stages: each numbered stage with its goal and file listplan_files: all file paths mentionedplan_verification: verification stepsCheck for active changes (REQUIRED — ingest only updates existing changes)
spectra list --json
Also check for parked changes:
spectra list --parked --json
Parse both JSON outputs to get the full list of changes (active + parked). Parked changes should be annotated with "(parked)" in any selection list.
/spectra-propose first to create one." and stopSelect the change
After selecting the change, check if it is parked:
spectra list --parked --json
If the selected change appears in the parked array:
spectra unpark "<name>" then proceedIf there is no AskUserQuestion tool available (non-Claude-Code environment):
Inform the user that this change is currently parked(暫存)and ask via plain text whether to unpark and continue, or cancel.
Wait for the user's response. If the user confirms, run spectra unpark "<name>" then proceed.
Read existing artifacts for context before updating.
Update artifacts
For each artifact, get instructions first:
spectra instructions <artifact-id> --change "<name>" --json
Use the template from instructions as the output structure. Apply context and rules as constraints but do NOT copy them into the file.
The instructions JSON includes locale — the language to write artifacts in. If present, you MUST write the artifact content in that language. Exception: spec files (specs/*/*.md) MUST always be written in English regardless of locale, because they use normative language (SHALL/MUST).
Plan-to-Artifact Mapping (when using a plan file):
| Plan Section | Artifact | How to Map |
|---|---|---|
| Title | Change name | Convert to kebab-case |
| Context | proposal: Why | Direct content transfer |
| Stages overview | proposal: What | Summarize all stages |
| Individual stages | tasks.md groups | One stage = one ## heading, sub-items = - [ ] |
| File paths | proposal: Impact | Affected code list |
| Verification steps | tasks.md | Final verification task group |
Context-to-Artifact Mapping (when using conversation context):
| Conversation Element | Artifact | How to Map |
|---|---|---|
| Goal / requirement | proposal: Why | Extract motivation from discussion |
| Discussed approach | proposal: What | Summarize agreed approach |
| Mentioned files | proposal: Impact | Affected code list |
| Discussion phases | tasks.md groups | One topic = one ## heading |
When updating an existing change:
[x] items[P] markers on tasks that still qualifyParallel task markers ([P]): When creating or updating the tasks artifact, first read openspec/config.yaml. If parallel_tasks: true is set, add [P] markers to new tasks that can be executed in parallel. Format: - [ ] [P] Task description. A task qualifies for [P] if it targets different files from other pending tasks AND has no dependency on incomplete tasks in the same group. When parallel_tasks is not enabled, do NOT add [P] markers — but still preserve any existing [P] markers already in the file.
After creating each artifact, re-check status:
spectra status --change "<name>" --json
Continue until all applyRequires artifacts are complete. Show progress: "✓ Created <artifact-id>"
Analyze-Fix Loop (max 2 iterations)
spectra analyze <name> --json
spectra analyze <name> --json
d. Repeat up to 2 total iterationsValidation
spectra validate "<name>"
If validation fails, fix errors and re-validate.
Summary and next steps
Show:
<path>) or conversation contextUse AskUserQuestion tool to confirm the workflow is complete. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:
/spectra-apply <change-name> when ready./spectra-apply <change-name> to start implementation.If AskUserQuestion tool is not available, display the summary and inform the user to run /spectra-apply <change-name> when ready. Then STOP — do not continue.
After the user responds, if they chose "Done", the workflow is OVER. If they chose "Apply", invoke /spectra-apply <change-name> to begin implementation.
Guardrails
~/.claude/plans//spectra-propose[x]) — never revert progressspectra CLI is not available, report the error and stop