spectra-apply-plus

name	spectra-apply-plus
description	Implement Spectra tasks with a sub-agent quality gate after completion
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.

     spectra in-progress add "<name>"
     

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

   Parse the JSON to understand:

   • schemaName: The workflow being used (e.g., "spec-driven")
   • Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)

3. Get apply instructions

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

   This returns:

   • Context file paths (varies by schema)
   • Progress (total, complete, remaining)
   • Task list with status
   • Dynamic instruction based on current state

   Handle states:

   • If state: "blocked" (missing artifacts): show message, suggest using $spectra-propose to create the change artifacts first
   • If state: "all_done": congratulate, suggest archive
   • Otherwise: proceed to implementation

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:

   • Show which task is being worked on
   • Re-read the sections of design and spec files that are relevant to this task's scope — do not rely on memory from earlier in the conversation, as context may have been compressed
   • Read the Implementation Contract for this task before editing any source file. If design.md exists and contains an ## Implementation Contract section (or contract content under another heading the design uses), read the part of it that covers this task's scope. The contract names the observable behavior, interface or data shape, failure modes, acceptance criteria, and scope boundaries you must satisfy. Treat the contract as the durable handoff — it is what the task will be measured against, regardless of who started the change.
   • Detect unclear or path-only tasks before writing code. A task is unclear if it:
     • only names files to edit ("edit foo.rs", "update bar.svelte") with no behavior, contract, or verification target;
     • is vague ("handle edge cases", "wire it up", "make it work");
     • conflicts with the implementation contract (asks for behavior the contract excludes, or omits behavior the contract requires). When this happens, pause. Either update the artifact (design or tasks) so the task names a concrete behavior and verification target, or report the blocker and wait for guidance. Do NOT silently guess against unclear requirements.
   • Before writing code, check:
     1. Reuse — search adjacent modules and shared utilities for existing implementations before writing new code
     2. Quality — derive values from existing state instead of duplicating; use existing types and constants over new literals
     3. Efficiency — parallelize independent async operations; avoid unnecessary awaits; match operation scope to actual need
     4. No Placeholders in artifacts — if the design or spec for this task contains placeholder language (TBD, TODO, "add appropriate handling"), pause and fix the artifact first or flag to the user. Do not implement against vague requirements.
     5. Examples as verification — if the spec for this task's scope includes ##### Example: blocks, use them as concrete test cases:
        • When TDD is enabled: derive the first failing test directly from the example's GIVEN/WHEN/THEN values
        • When TDD is not enabled: after implementing, verify the code handles the example's input→output correctly
        • Example tables map to parameterized tests — one test per row Do NOT invent additional test values beyond what the spec examples provide without reason. The examples ARE the agreed specification.
   • Make the code changes required
   • Keep changes minimal and focused
   • Verify before marking done — re-read the task description from the tasks file AND the relevant Implementation Contract content from design.md. For each requirement stated in the task description and each contract item that covers this task's scope, confirm it is addressed by your changes. Confirm the verification target named by the task (test name, CLI invocation, analyzer check, or manual assertion) actually passes. If any contract item, task requirement, or verification target is missing or failing, implement/fix it now. Do not mark the task complete until every part of the description is covered and the contract for this task is satisfied.
   • Mark task complete by running: spectra task done --change "<name>" <task-id> This command marks the checkbox in tasks.md AND records which files were modified for this task.
   • Continue to next task

   Parallel task dispatch: When consecutive [P]-marked tasks are found and parallel_tasks: true is configured (see Step 5), dispatch them as parallel agents in a single message. If any [P] task fails, pause and report.

   Pause if:

   • Task is unclear → ask for clarification
   • Implementation reveals a design issue → suggest updating artifacts
   • Error or blocker encountered → report and wait for guidance
   • User interrupts

---

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

---

Surgical & Simplicity Discipline

在 step 7 的 task loop 期間，編輯任何來源碼之前必須套用以下兩項紀律。它們補充（而不取代）既有的 Reuse / Quality / Efficiency / No Placeholders / Examples as verification 檢查。

Simplicity First — 寫最少能解決任務的程式碼

• 不要實作 tasks.md 任務描述與 design.md Implementation Contract 以外的功能。
• 不要為單一使用情境引入抽象層、設定選項或「彈性」；YAGNI 優先於可擴充性。
• 不要為 contract 已排除或型別已保證的情境撰寫錯誤處理；只在系統邊界（外部輸入、外部 API）驗證。
• 完成後若發現實作行數遠超必要（例如 200 行能壓到 50 行），先檢查是否過度設計，必要時重寫成更小的版本。
• 自問：「資深工程師會不會說這太複雜？」如果會，就簡化。

Surgical Changes — 只動該動的，且只清自己造成的殘骸

• 不要「順手」改鄰近區塊的程式碼、註解或格式。
• 不要重構沒壞的東西；不要為了個人風格偏好改既有寫法。
• 即使既有風格與你習慣不同，跟著現況走（match existing style）。
• 若注意到不相關的死碼、bug 或可改進處，不要直接刪或改 — 在 step 11 的 implementation-notes.md 以 open-question 條目記錄，交給使用者決定。
• 只移除「因為本次改動而變成 orphan」的 import、變數、函式；既有的 pre-existing 死碼不要動。
• 驗收標準：本次 diff 的每一行，都能直接追溯到 tasks.md 中的某條任務或 design.md 中的 Implementation Contract 項目。

Maintain Balance — Simplicity 不等於程式碼高爾夫

Simplicity First 與 Surgical Changes 的目的是「不寫不必要的東西」，不是「越短越好」。下列反例同樣違反紀律，被 review loop 視為 Critical：

• 巢狀三元運算子（nested ternary）— 用 if/else 或 switch 替代。
• 為了減少行數犧牲可讀性的 dense one-liner、過度連鎖的 method chain。
• 為了「合併」把多個關注點塞進同一個 function、component 或檔案。
• 移除有意義的中介變數，讓 expression 變成難以閱讀或除錯的長句。
• 移除真正在傳遞意圖的命名常數，改用 magic number 或 inline literal。
• 拿掉合理的抽象（helper、type alias）只為了減少一層間接。

判準：實作完成後重讀 diff，若 future-self 或 reviewer 需要花超過幾秒才能理解某行的意圖，那不是 simpler，是 cleverer。Cleverer 違反紀律。Clarity 永遠優先於 brevity。

若違反上述任一條（無論刻意或非刻意），視同 task 未完成 — 在執行 spectra task done 之前先修正。若是刻意 deviate（例如 contract 與既有程式衝突，需要動到鄰近區塊），依 step 11 Implementation Notes Protocol 寫一筆 deviation 條目，說明原因。

Keep verbatim (do not translate): shell commands, file paths, code identifiers, schema field names (applyRequires, outputPath 等), artifact IDs, capability slugs, and quoted source text. If the user explicitly requests another language later, follow the latest user instruction. 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

10. Sub-Agent Review/Rating/Fix Loop

Run this review/rating/fix loop once per change, after the normal workflow has completed its required artifact or task work.

Entry conditions

• For spectra-propose-plus, start this loop only after proposal, design, specs, and tasks artifacts required for apply are complete.
• For spectra-apply-plus, start this loop only after all implementation tasks are complete and tasks.md 全 [x].
• Do not run this loop per artifact or per task; the granularity is per-change.

Round limit and pass condition

• Run max 6 rounds.
• A round passes only when quality_score > 9 and critical_gap == false.
• If round 6 still does not meet the pass condition, write decision: aborted, print the unresolved findings, and end the plus workflow.
• If a round passes, write decision: passed, stop the loop, and continue to the normal final validation or completion summary.

Fresh sub-agent calls

• Each round MUST spawn TWO fresh reviewer sub-agents in parallel (single message, two tool calls):
  • Reviewer A — Adherence: checks that the artifacts (and for apply-plus, the implementation diff) match the prior artifacts. For propose-plus: proposal ↔ design ↔ spec ↔ tasks internal consistency, scope coverage, and acceptance criteria completeness. For apply-plus: implementation matches design.md Implementation Contract, tasks.md task descriptions, and spec.md requirements; implementation-notes.md deviations are justified.
  • Reviewer B — Quality: scans for bugs, regressions, missing tests, security sharp edges, and risks NOT directly named in the artifacts. For propose-plus: missing risks, unstated assumptions, scope gaps. For apply-plus: logic bugs, error-handling gaps at real boundaries, untested edge cases from spec ##### Example: blocks.
• Both reviewers receive identical context (artifact paths and, for apply-plus, the changed-file list) and return findings independently. Do not pass Reviewer A output into Reviewer B or vice versa.
• After both reviewers complete, the main agent aggregates findings (deduplicate identical issues by location + summary) and applies the confidence filter (see below) before passing the filtered set to the rater.
• Each round MUST spawn a separate fresh sub-agent for the rater role.
• The reviewer roles and the rater are independent sub-agent calls; do not perform any of them inline in the main agent context.
• Do not reuse a sub-agent across rounds, and do not pass prior sub-agent state into the next round.
• The rater receives the filtered, aggregated reviewer findings as input, then independently returns quality_score, critical_gap, and rationale.

Reviewer output requirements

• Both reviewers MUST classify each finding into Critical, Warning, or Suggestion.
• Every finding MUST include the following fields:
  • severity: one of Critical, Warning, Suggestion (before filtering)
  • confidence: integer 0–100, using the rubric below
  • location: artifact + section, or file path + line range
  • summary: one-line description of the issue
  • recommendation: concrete action to resolve
• Every finding names the artifact, section, source path, or changed file it applies to.
• Scope errors at proposal level (e.g., the proposal targets the wrong capability) may set decision: aborted instead of continuing fixes.

Confidence scoring rubric (per finding)

• 0 — Not confident at all. False positive or pre-existing issue. SHOULD NOT be reported.
• 25 — Somewhat confident. Could be a real issue but the reviewer was unable to verify against artifacts or code.
• 50 — Moderately confident. Verified to be real, but minor / unlikely to hit in practice / outside the changed scope.
• 75 — Highly confident. Verified to be real and will hit in practice. Use this when judgment-based impact assessment supports the finding but no direct artifact citation exists.
• 100 — Certain. Evidence directly confirms the issue, OR the finding cites a specific artifact clause (a SHALL in spec.md, an Implementation Contract item in design.md, a task description line in tasks.md, a non-goal in proposal.md) that the artifact set or implementation provably does not satisfy.
• Direct artifact-requirement violations MUST score 100. If a reviewer can name the exact SHALL / contract item / task line being violated, the finding is objectively verifiable and SHALL NOT be downgraded below 100. This invariant guarantees the confidence filter never demotes an artifact violation to Suggestion.

Confidence filter (applied by main agent before rater)

• Drop any finding with confidence < 50. These do not appear in the round file.
• Downgrade findings with confidence ∈ [50, 80) to Suggestion regardless of original severity. They appear in the round file under Suggestion for visibility but do NOT count as Critical.
• Only findings with confidence ≥ 80 may be classified as Critical or Warning in the final round file.
• critical_gap is true only when at least one finding survives filtering with severity == Critical AND confidence ≥ 80.
• The filter exists to keep the review loop signal-to-noise high; the rater sees only the filtered set.

Common false positives — do NOT flag The following SHOULD NOT be reported, or if reported MUST be scored ≤ 25:

• Pre-existing issues on lines not modified by this change (apply-plus) or content not introduced by this proposal (propose-plus).
• Issues a linter, typechecker, formatter, or compiler would catch (missing imports, type errors, formatting, broken syntax). CI will fail separately; the review loop is not the right channel.
• Pedantic style nitpicks that a senior engineer would not call out in review.
• "Missing test coverage" complaints unless tasks.md or design.md explicitly required the test, or a spec ##### Example: block is not exercised.
• Issues already documented as intentional in design.md, implementation-notes.md, the proposal's Non-Goals section, or ## Alternatives Considered.
• Intentional behavior changes that align with the proposal's ## What Changes or ## Proposed Solution.
• Suggestions to add abstractions, configurability, or defensive error handling that the spec/contract did not require — these conflict with Simplicity First.
• Suggestions to refactor unrelated code touched only incidentally — these conflict with Surgical Changes.

Failure handling

• If a reviewer or the rater returns no response or malformed output, retry once with a fresh sub-agent invocation for the same role.
• If both parallel reviewers fail in the same round, treat it as a single role failure (the reviewer role); retry once.
• If the same role fails two consecutive times in a single round, abort the entire plus workflow.
• On abort from sub-agent failure, write the current round file with decision: aborted and include the failure note in ## Decision.
• Do not mark a malformed or failed round as passed, and do not continue to the next round after two consecutive failures.

Rater output requirements

• The rater writes quality_score as a number from 0 to 10.
• The rater writes critical_gap as true or false.
• The rater writes one concise rationale paragraph.
• The rater must not override missing reviewer evidence by optimism alone.
• The rater SHALL only consider findings that survived the confidence filter; do not re-introduce filtered-out findings.

Round file path

• Create the reviews directory if needed: openspec/changes/<change>/reviews/.
• For spectra-propose-plus, write openspec/changes/<change>/reviews/propose-r<N>.md.
• For spectra-apply-plus, write openspec/changes/<change>/reviews/apply-r<N>.md.
• Use <N> as the 1-based round number.
• The generic path pattern is openspec/changes/<change>/reviews/<skill>-r<N>.md.

Round file schema

• # Propose Plus Review — Round <N> or # Apply Plus Review — Round <N>
• ## Reviewer Findings — list aggregated, post-filter findings grouped under Critical / Warning / Suggestion. Each entry MUST include severity, confidence, location, summary, recommendation, and which reviewer raised it (A or B; A+B if both raised it independently).
• ## Rating — quality_score, critical_gap, rationale paragraph.
• ## Fix Actions
• ## Decision — value MUST be exactly one of passed, next_round, or aborted.

Fix actions

• If the decision is next_round, fix the concrete findings before starting the next round.
• Record modified files and the reason for each fix in ## Fix Actions.
• Re-run relevant CLI checks or tests before the next round when fixes affect generated artifacts or implementation code.
• If no fixes are needed because the round passed, write None; pass condition met.

Round file language

• The Round file (openspec/changes/<change>/reviews/<skill>-r<N>.md) prose content — Reviewer Findings, Rater rationale, Fix Actions descriptions, and the ## Decision explanation — MUST be written in Traditional Chinese.
• Keep the following verbatim (do not translate):
  • Section headings: # Propose Plus Review — Round <N>, # Apply Plus Review — Round <N>, ## Reviewer Findings, ## Rating, ## Fix Actions, ## Decision.
  • The decision value: one of passed, next_round, aborted.
  • Field names and their values: quality_score (number 0–10), critical_gap (true / false), severity, confidence, location, summary, recommendation.
  • Direct quotations from spec delta, master spec, or any other English-language artifact.
  • CLI commands, file paths, code identifiers, artifact IDs, capability slugs.
• This rule applies to both spectra-propose-plus and spectra-apply-plus round files because they share this review-loop template.
• If the user explicitly requests another language later, follow the latest user instruction.

10. Apply-plus response language

For spectra-apply-plus, ai 的回覆要用中文.

All user-facing AI responses during this workflow MUST be written in Traditional Chinese unless the user explicitly requests another language.

This includes:

• Status updates while tasks are being implemented.
• Pause messages when a blocker is encountered.
• Review loop summaries.
• Final implementation summaries.

This does not require translating:

• Shell commands.
• File paths.
• Code identifiers.
• Existing quoted source text.

If the user explicitly requests another language later, follow the latest user instruction.

Keep technical names exact even when the surrounding explanation is Chinese.

Do not mix languages for ordinary prose unless a command, path, symbol, or quoted artifact requires it.

The goal is predictable Chinese-facing interaction for apply-plus while preserving exact technical references.

Artifact modifications during apply-plus

When the apply-plus workflow modifies an artifact — during review-loop fix actions, or after spectra-ingest updates tasks.md / design.md / proposal.md — the updated artifact content MUST follow the same Chinese language rule as propose-plus:

• tasks.md, design.md, proposal.md, and other non-spec artifacts under openspec/changes/<change>/: Traditional Chinese.
• Spec files (openspec/changes/<change>/specs/**/spec.md and openspec/specs/**/spec.md): always English, regardless of any other language rule. Delta specs are merged into master specs and must use normative SHALL/MUST wording.

Keep CLI commands, file paths, code identifiers, schema field names, artifact IDs, capability slugs, and existing quoted source text verbatim. If the user explicitly requests another language later, follow the latest user instruction.

11. Implementation Notes Protocol

During the apply-plus task loop, maintain a lightweight running log at openspec/changes/<change>/implementation-notes.md that captures only two categories of information:

• Deviations: places where the implementation intentionally departs from spec.md, design.md, or tasks.md (because the spec was ambiguous, the codebase reality differs, or a discovered issue forced a different path).
• Open questions: items that need user confirmation or revision before this change can be considered complete.

Design decisions that match the spec, ordinary tradeoffs, and small judgment calls do NOT belong here — they are already covered by design.md, tasks.md, and the review-loop round files. Keep this log narrow.

File creation rule (eager)

• At the start of Step 7 (the task loop), before processing the first task, create openspec/changes/<change>/implementation-notes.md if it does not already exist.
• Initialize the file with a single-line HTML comment header (and nothing else):

  <!-- apply-plus implementation notes | change: <change-name> | initialized: <YYYY-MM-DD HH:MM> | no entries below means no deviations or open questions were recorded -->
  

• Entries (see below) are appended in order beneath this header.
• Eager creation makes "no entries" an explicit positive signal (apply-plus ran and found nothing to report), distinct from file-absent which signals a workflow integrity failure.

Entry format

Each entry MUST be appended (never rewriting earlier entries) using this exact structure:

## <YYYY-MM-DD HH:MM> — <short title>
- 類別：deviation | open-question
- 任務：<task-id or "n/a">
- 內容：<one-paragraph description of what happened or what needs answering>
- 原因：<why this path was chosen, or why the user needs to weigh in>

Prose (內容, 原因, title) is written in Traditional Chinese, matching the apply-plus response-language rule. CLI commands, file paths, code identifiers, capability slugs, and quoted source text remain verbatim in English.

When to write an entry

• When task-level implementation diverges from design.md Implementation Contract, tasks.md description, or relevant spec.md requirements — write a deviation entry before marking the task done.
• When the task surfaces a question the user must decide (e.g. ambiguous requirement, missing schema field, contested naming) and the agent has to proceed under an assumption — write an open-question entry naming the assumption.
• Do not batch entries to the end of the session; record at the moment the decision is made, while context is fresh.

When NOT to write an entry

• Routine implementation that matches the artifacts — no entry.
• Trivial naming or formatting choices — no entry.
• Anything already documented in design.md or the round-<N> review files — no entry.

Sub-agent reviewer requirement

The review-loop reviewer (Section 10) MUST, at the start of each round, read openspec/changes/<change>/implementation-notes.md.

• File absent: this is a Critical finding — apply-plus failed to initialize the running log, indicating either an aborted workflow or a skill-integrity failure. The round MUST NOT pass; recommend re-running apply-plus or back-filling the file before the next round.
• File present with only the initialization comment and no entries: treat as confirmed empty — apply-plus reached the task loop and found nothing requiring a deviation or open-question entry. No finding raised by virtue of emptiness alone.
• File present with entries:
  • deviation entries are evaluated for whether the divergence is justified. An unjustified deviation is a Critical finding; a justified-but-undocumented-in-design.md deviation is at minimum a Warning recommending the divergence be back-filled into design.md during Fix Actions.
  • open-question entries are surfaced as Warning findings with a recommended ## Fix Actions step naming how to obtain user confirmation before the round can pass.

The rater (Section 10) does not read this file directly; it reads only the reviewer findings, which already incorporate the notes context.

Idempotence and ingest interaction

• spectra-ingest may modify tasks.md / design.md / proposal.md. After ingest resolves an open question, the agent MUST append a follow-up entry noting the resolution (do not delete or rewrite the original open-question entry — the historical record is the point).
• Reviewer treats a resolved open-question entry (i.e. one followed by a resolution entry) as no longer blocking.

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