Spectra Ingest

Parse the plan structure (skip if using conversation context)

Claude Code plan files typically contain:

• Title (# ...) — the high-level goal
• Context section — background, motivation, current state
• Stages/Steps — numbered implementation stages with goals and file lists
• Files involved — list of files to modify/create
• Verification section — how to test the changes

Extract:

• plan_title: from the H1 heading
• plan_context: from the Context section
• plan_stages: each numbered stage with its goal and file list
• plan_files: all file paths mentioned
• plan_verification: verification steps

Check 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.

• If one change exists (active or parked) → use the AskUserQuestion tool to confirm updating it
• If multiple changes exist → use the AskUserQuestion tool to let user pick which one to update
• If no changes at all (neither active nor parked) → tell the user: "No active change found. Use /spectra-propose first to create one." and stop

Select the change

After selecting the change, check if it is parked:

spectra list --parked --json

If the selected change appears in the parked array:

• Inform the user that this change is currently parked（暫存）
• Use AskUserQuestion tool to ask: continue (unpark) or cancel
• If continue: run spectra unpark "<name>" then proceed
• If cancel: stop the workflow

If 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):

Context-to-Artifact Mapping (when using conversation context):

When updating an existing change:

• Merge new context into existing proposal (don't replace)
• Add new tasks from plan stages or conversation, preserve completed [x] items
• Preserve existing [P] markers on tasks that still qualify
• Do NOT remove existing content

Parallel 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

1. Filter findings to Critical and Warning only (ignore Suggestion)
2. If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
3. If Critical/Warning findings exist: a. Show: "Found N issue(s), fixing... (attempt M/2)" b. Fix each finding in the affected artifact c. Re-run spectra analyze <name> --json d. Repeat up to 2 total iterations
4. After 2 attempts, if findings remain:
   • Show remaining findings as a summary
   • Proceed normally (do NOT block)

Validation

spectra validate "<name>"

If validation fails, fix errors and re-validate.

Summary and next steps

Show:

• Source used: plan file (<path>) or conversation context
• Change name and location
• Artifacts created/updated
• Validation result

Use AskUserQuestion tool to confirm the workflow is complete. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:

• First option (will be auto-selected): "Done" — End the ingest workflow. Inform the user they can run /spectra-apply <change-name> when ready.
• Second option: "Apply" — Invoke /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.