spectra-apply

name	spectra-apply
description	Implement or resume tasks from a Spectra change
effort	xhigh
license	MIT
compatibility	Requires spectra CLI.
metadata	{"author":"spectra","version":"1.0","generatedBy":"Spectra"}

Implement tasks from a Spectra change.

Input: Optionally specify a change name (e.g., /spectra-apply add-auth). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Task tracking is file-based only. The tasks file's markdown checkboxes (- [ ] / - [x]) are the single source of truth for progress. Do NOT use any external task management system, built-in task tracker, or todo tool. When a task is done, edit the checkbox in the tasks file — that is the only way to record progress.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

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 spectra list --json AND spectra list --parked --json to get all available changes (including parked ones). Parked changes should be annotated with "(parked)" in the selection list. Use the AskUserQuestion tool to let the user select

   Always announce: "Using change: " and how to override (e.g., /spectra-apply <other>).

2. Check status to understand the schema

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

   If the command fails: show the error and STOP.

   If the command succeeds, check whether the change is parked (status can succeed even for parked changes):

   spectra list --parked --json
   

   Look for the change name in the parked array of the JSON output.

   • If the change IS in the parked list (it's parked): Inform the user that this change is currently parked（暫存）. Use the AskUserQuestion tool to ask whether to continue. Two options:

     • Continue: Unpark the change and proceed with apply
     • Cancel: Stop the workflow

     If the user chooses to continue:

     spectra unpark "<name>"
     

     Then mark it as in-progress:

     spectra in-progress add "<name>"
     

     This is a silent operation — do not show the output to the user.

     Then re-run spectra status --change "<name>" --json and continue normally.

     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 set spectra in-progress add "<name>", and continue normally.

   • If the change is NOT in the parked list: mark it as in-progress and proceed normally.

3b. Preflight check

If the apply instructions JSON includes a preflight field, act on its status:

• "clean": silently continue — no output needed.

• "warnings": display a brief summary, then continue automatically:

  ⚠ Preflight warnings:
  - Drifted files (modified after change was created): <list paths>
  - Change is <N> days old
  Continuing...
  

  Only show the lines that are relevant (skip drifted if none, skip staleness if not stale).

• "critical": display missing files with their source artifact, then use the AskUserQuestion tool to ask the user:

  ⚠ Preflight: missing files detected
  - <path> (referenced in <source artifact>)
  - ...
  These files are referenced in the change artifacts but no longer exist on disk.
  

  Options: "Continue anyway" / "Stop" If the user chooses "Stop", end the workflow.

  If there is no AskUserQuestion tool available: Display the same information as plain text and ask whether to continue or stop. Wait for the user's response.

If the preflight field is absent (blocked or all_done states), skip this step.

3c. Artifact quality check

Run spectra analyze <change-name> --json to check cross-artifact consistency (Coverage, Consistency, Ambiguity, Gaps).

• Zero findings: silently continue.

• Warning/Suggestion only: display a one-line summary (e.g., "⚠ Artifact analysis: 2 warnings found") and continue automatically.

• Critical findings: display each Critical finding (summary + location + recommendation), then use the AskUserQuestion tool:

  • Fix and continue — fix the artifact issues inline, then proceed
  • Continue anyway — skip fixes and start implementation
  • Stop — end the workflow

  If there is no AskUserQuestion tool available, present options as plain text and wait for the user's response.

3d. Drift dormancy check (passive trigger for stale changes)

When the change has been dormant for more than 5 days AND the change directory has had zero commits in the past 3 days, surface a drift report before tasks begin — the change is likely out-of-sync with the current codebase.

Detect dormancy from .openspec.yaml created and git log -1 --format=%at -- docs/specs/changes/<name>/:

• Both conditions met: run spectra drift <change-name>, display the report, then use the AskUserQuestion tool:
  • Continue with apply — proceed to tasks (recommended for Light drift)
  • Refresh first — pause apply, run /spectra-ingest <change-name> to update artifacts, then resume
  • Stop — end the workflow
• Either condition not met: silently continue, no output.

The trigger is guidance only — it MUST NOT block apply from proceeding when the user chooses to continue. Hard-blocking on dormancy would punish legitimate "I came back after a long weekend" cases.

(Threshold reasoning: AI-assisted commits are daily-cadence. ≥5 days dormant + ≥3 days no commit ≈ genuine stagnation, not normal pacing.)

If there is no AskUserQuestion tool available, present options as plain text and wait for the user's response.

4. Read context files

   Read the files listed in 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

5. Check project preferences

   Read .spectra.yaml in the project root. If tdd: true is set, apply TDD discipline throughout implementation:

   • For each task, write a failing test FIRST, then implement to make it pass
   • Fetch TDD instructions by running spectra instructions --skill tdd, then follow the Red-Green-Refactor cycle
   • For bug fixes, reproduce the bug with a failing test before fixing

   If audit: true is set, apply sharp-edges discipline throughout implementation:

   • When designing APIs or interfaces, evaluate through 3 adversary lenses (Scoundrel, Lazy Developer, Confused Developer)
   • When adding configuration options, verify defaults are secure and zero/empty values are safe
   • When accepting parameters, check for type confusion and silent failures
   • Fetch audit instructions by running spectra instructions --skill audit, follow the discipline checklist (not the standalone 3-agent workflow)

   If parallel_tasks: true is set, check whether consecutive pending tasks have [P] markers (format: - [ ] [P] Task description). You SHALL dispatch consecutive [P] tasks as parallel agents. Only fall back to sequential when tasks have a data dependency (one task's output is another's input) or when tasks modify overlapping regions of the same file. Targeting the same file alone is NOT a reason to skip parallel dispatch — if the modified regions are disjoint, dispatch in parallel. If the environment does not support parallel execution, ignore [P] markers and execute tasks sequentially.

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)

   Reminder: Track progress by editing checkboxes in the tasks file only. Do not use any built-in task tracker.

   For each pending task:

---

Rationalization Table

What You're Thinking	What You Should Do
"This task looks done, I'll mark it complete"	Re-read the task description first. Check whether your diff covers every part of it. Incomplete tasks marked done are the #1 source of rework
"This task is trivial, I don't need to re-read the design"	Re-read. Context compression loses details. 30s of reading saves 30min of rework
"I already know how this works, skip the code search"	Search anyway. Someone may have added a utility since you last looked
"The test is obvious, I'll add it after implementation"	If TDD is enabled, test first. If not, still write it before marking done
"This is just a small refactor, no test needed"	Small refactors are how regressions sneak in. Write the test
"The artifact says X but Y makes more sense"	Pause and suggest updating the artifact. Don't silently deviate
"I'll fix this other thing I noticed while I'm here"	Finish current task first. Address the other thing separately
"The example values are just illustrations, I'll pick better ones"	Use the spec example values exactly. They were chosen deliberately

---

8. Final check

   After completing all tasks, re-run:

   spectra instructions apply --change "<name>" --json
   

   Confirm state: "all_done". If not, review remaining tasks and complete them.

9. 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! You can archive this change with `/spectra-archive`.

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)
• 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
• No external task tracking — do not use any built-in task management, todo list, or progress tracking tool; the tasks file is the only system
• If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response

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