@codename_inc/spectre 5.2.0 → 5.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/package.json +2 -2
  2. package/plugins/spectre/.claude-plugin/plugin.json +1 -1
  3. package/plugins/spectre/skills/create_plan/SKILL.md +31 -7
  4. package/plugins/spectre/skills/plan/SKILL.md +38 -12
  5. package/plugins/spectre/skills/plan_review/SKILL.md +66 -31
  6. package/plugins/spectre-codex/skills/create_plan/SKILL.md +31 -7
  7. package/plugins/spectre-codex/skills/plan/SKILL.md +38 -12
  8. package/plugins/spectre-codex/skills/plan_review/SKILL.md +66 -31
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@codename_inc/spectre",
3
- "version": "5.2.0",
3
+ "version": "5.2.2",
4
4
  "type": "module",
5
5
  "bin": {
6
- "spectre": "./bin/spectre.js"
6
+ "spectre": "bin/spectre.js"
7
7
  },
8
8
  "files": [
9
9
  "bin",
package/plugins/spectre/.claude-plugin/plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "spectre",
3
- "version": "5.2.0",
3
+ "version": "5.2.2",
4
4
  "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
5
5
  }
package/plugins/spectre/skills/create_plan/SKILL.md CHANGED
@@ -27,6 +27,7 @@ Treat the current command arguments as this workflow's input. When invoked from
27
27
  - **Action** — CheckExistingResearch: Check if technical research already completed.
28
28
  - Read `TASK_DIR/task_context.md`; look for "## Technical Research" section.
29
29
  - **If** found with comprehensive analysis → use existing research; skip to Step 3.
30
+ - **If** ARGUMENTS contains `--depth light` and `TASK_DIR/task_context.md` already contains substantive router research (file locations, code understanding, codebase patterns, and impact summary) → use existing research; skip to Step 3.
30
31
  - **Else** → proceed with new research below.
31
32
  - **Action** — AutomatedResearch: Spawn parallel research agents for comprehensive analysis.
32
33
  - Use `@finder` to find all files related to feature area.
@@ -61,6 +62,8 @@ Treat the current command arguments as this workflow's input. When invoked from
61
62
 
62
63
  Dynamically generate up to 10 technical questions based on research findings. **IMPORTANT**: Only ask questions genuinely not answered in the PRD or discoverable through code investigation. Goal: eliminate scope and design ambiguity. If a question involves choosing between approaches, present options with Pros/Cons/Trade-offs.
63
64
 
65
+ - **Action** — LightModeClarifications: If ARGUMENTS contains `--depth light`, do NOT stop for user clarifications. Use conservative, codebase-consistent defaults and record them in the plan's **Filled Assumptions** section, then skip to Step 3. If an unresolved question would affect canonical scope, security/privacy, data correctness, or public API behavior, return control to `plan` with a tier reassessment recommendation instead of guessing.
66
+
64
67
  - **Action** — DetectClarificationMethod: Check if `AskUserQuestion` tool is available.
65
68
  - **If available** → use inline clarification flow (Path A).
66
69
  - **If not available** → use file-based clarification flow (Path B).
@@ -94,16 +97,17 @@ Dynamically generate up to 10 technical questions based on research findings. **
94
97
  - **Action** — DetermineDepth: Read `--depth` from ARGUMENTS
95
98
 
96
99
  - Default: `standard` if not specified
97
- - Options: `standard`, `comprehensive`
100
+ - Options: `light`, `standard`, `comprehensive`
101
+ - **Action** — DetectOrchestratedMode: If ARGUMENTS contains `--no-review`, this workflow is being invoked by `plan` as part of the meta-flow. Generate and save the plan, then return control to `plan` without asking for standalone user review.
98
102
 
99
103
  - **Action** — DesignTechnicalApproach: Create the implementation plan.
100
104
 
101
- Every plan, regardless of depth, MUST include these seven sections. They are the verification spine — without them, downstream agents cannot self-check their work.
105
+ Every plan, regardless of depth, MUST include the verification spine. LIGHT is concise, not shallow: keep it brief and decisive, but still explain the solution shape, codebase pattern to follow, risks/assumptions, and how the work will be verified.
102
106
 
103
- **Required for both STANDARD and COMPREHENSIVE:**
107
+ **Required for LIGHT, STANDARD, and COMPREHENSIVE:**
104
108
  1. **Overview** — 1–2 paragraphs: what problem, what shape the solution takes, why this approach.
105
109
  2. **Technical Approach** — How the change actually lands: components touched, data flow, key decisions with rationale. Reference existing patterns from `@patterns` research by file:line (e.g., "follow the shape of `src/widgets/HotDogWidget.ts:42` for the registration step").
106
- 3. **Critical Files for Implementation** — 3–7 specific files from research. Format: `path/to/file.ts` — *reason* (Core logic to modify / Pattern to follow / Interface to implement / Test to extend). No guesses — only files surfaced during Step 1 research.
110
+ 3. **Critical Files for Implementation** — 1–7 specific files from research. Format: `path/to/file.ts` — *reason* (Core logic to modify / Pattern to follow / Interface to implement / Test to extend). No guesses — only files surfaced during Step 1 research.
107
111
  4. **External Dependencies — Verify Before Implementation** — Every third-party package required, with exact version and a one-line existence check. Format: `package@1.2.3 — verify: npm view package@1.2.3` (or pip equivalent). Required even if "no new packages" (write that explicitly). This is the slopsquatting fence: ~20% of AI-suggested packages don't exist; we catch that here, not in production.
108
112
  5. **Verification — How We Know This Works** — For each major change in Technical Approach, 1–3 falsifiable signals: a test name, an observable behavior, or a state/file condition. Prose like "the feature works" is not acceptable — it must be checkable. Format: `<change> → verifies by: <test name | observable behavior | state condition>`. These become acceptance criteria in `create_tasks` downstream.
109
113
  6. **Out-of-Bounds — DO NOT add** — 4–8 concrete things the implementation must NOT add, even if "best practice." Examples: rate limiting, retry/backoff, caching layer, optimistic UI, soft-delete, telemetry events, feature flags, admin UI. This is the YAGNI fence against familiar-shape bias (agents reproduce mature-system patterns unprompted). Be specific to this feature, not generic.
@@ -111,6 +115,12 @@ Dynamically generate up to 10 technical questions based on research findings. **
111
115
  - *Risks*: what could go wrong (e.g., concurrent write race, migration ordering, third-party rate limit). Each with a one-line mitigation or "accept and monitor."
112
116
  - *Filled Assumptions*: things the plan defaulted because the spec didn't say (e.g., "Assumed Postgres; spec didn't specify DB." "Assumed retry count = 0; spec didn't mention failure modes."). Reviewer-visible by design — these are the silent decisions that bite at execution.
113
117
 
118
+ **LIGHT constraints:**
119
+ - Keep the seven required sections compact: usually 1 short paragraph or 3–5 bullets per section.
120
+ - Prefer one clear implementation path that follows existing codebase patterns; do not enumerate broad alternatives.
121
+ - Do not add standalone clarification gates, review gates, plan_review, or expanded architecture sections.
122
+ - If the plan needs more than 3 critical files, a new abstraction, data migration, public API change, or unresolved scope/security/data correctness decision, stop and return a tier reassessment recommendation to `plan`.
123
+
114
124
  **COMPREHENSIVE additionally requires:**
115
125
  8. **Current State** — How the affected code path works today, with file:line refs. Anchored to research findings.
116
126
  9. **Implementation Phases** — Ordered phases, each with its own Verification subsection (Phase N succeeds when …). Phases must be sequenced by dependency, not by file. Migration phases come before consumer phases.
@@ -125,14 +135,28 @@ Dynamically generate up to 10 technical questions based on research findings. **
125
135
 
126
136
  - **Action** — RequestReview:
127
137
 
128
- > "Implementation plan saved to `{path}`. Review and reply with feedback or 'Approved' to proceed."
138
+ - **If `--no-review` is present**:
139
+
140
+ > "Draft implementation plan saved to `{path}`. Returning to `plan` for the next routed step."
141
+
142
+ Do NOT wait for user approval. Return control to the invoking `plan` workflow.
143
+
144
+ - **Else**:
129
145
 
130
- - **Wait** — User provides feedback or approval
146
+ > "Implementation plan saved to `{path}`. Review and reply with feedback or 'Approved' to proceed."
147
+
148
+ - **Wait** — User provides feedback or approval, unless `--no-review` is present.
131
149
 
132
150
  ## Step (4/4) - Finalize and Present Next Steps
133
151
 
134
152
  - **Action** — ConfirmCompletion:
135
153
 
154
+ - **If `--no-review` is present**:
155
+
156
+ > "Draft implementation plan saved to `{plan_path}`. Returning to `plan`."
157
+
158
+ Stop here. Do not render the standalone Next Steps footer.
159
+
136
160
  > "🎯 Implementation Planning Complete. Documents: {plan_path}, task_context.md"
137
161
 
138
- - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps footer
162
+ - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps footer
package/plugins/spectre/skills/plan/SKILL.md CHANGED
@@ -15,7 +15,7 @@ Treat the current command arguments as this workflow's input. When invoked from
15
15
  ## Description
16
16
 
17
17
  - **What** — Research codebase, assess complexity, route to appropriate workflow (direct tasks or plan-first)
18
- - **Outcome** — Detailed task breakdown ready for execution
18
+ - **Outcome** — A right-sized `plan.md` + `tasks.md`; STANDARD/COMPREHENSIVE include review and a final execution gate, while LIGHT stays non-blocking.
19
19
 
20
20
  ## ARGUMENTS Input
21
21
 
@@ -23,7 +23,7 @@ Treat the current command arguments as this workflow's input. When invoked from
23
23
 
24
24
  ## MANDATORY COMPLIANCE RULES
25
25
 
26
- > **⚠️ NON-NEGOTIABLE**: This workflow MUST invoke nested workflows via the Skill tool. Failure to invoke `Skill(create_plan)` and `Skill(create_tasks)` (Claude slash route: `/spectre:create_plan` and `/spectre:create_tasks`) is a critical error. Do NOT summarize, describe, or skip these workflows. INVOKE THEM.
26
+ > **⚠️ NON-NEGOTIABLE**: After tier routing, this workflow MUST invoke nested workflows via the Skill tool. LIGHT must invoke `Skill(create_plan)` and `Skill(create_tasks)`; STANDARD/COMPREHENSIVE must invoke `Skill(create_plan)`, `Skill(create_tasks)`, and `Skill(plan_review)` (Claude slash route: `/spectre:create_plan`, `/spectre:create_tasks`, and `/spectre:plan_review`). Failure to invoke the required skills is a critical error. Do NOT summarize, describe, or skip these workflows. INVOKE THEM.
27
27
 
28
28
  **After ANY user conversation or questions:**
29
29
 
@@ -33,14 +33,16 @@ Treat the current command arguments as this workflow's input. When invoked from
33
33
 
34
34
  **You MUST call these skills (not describe them):**
35
35
 
36
- - Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md
36
+ - Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md, including LIGHT
37
37
  - Use the **Skill** tool with `skill: "spectre-create_tasks"` and `args: "{path}"` — generates tasks.md
38
+ - Use the **Skill** tool with `skill: "spectre-plan_review"` and `args: "{OUT_DIR} --auto-apply scope-safe"` — reviews and integrates scope-safe feedback for STANDARD/COMPREHENSIVE
38
39
 
39
40
  ## Instructions
40
41
 
41
42
  - Research before routing; present architectural options for user buy-in
42
43
  - Route based on hard-stops and clarity, not point-scoring
43
44
  - Never overwrite existing `tasks.md` or `plan.md` — use scoped names
45
+ - Treat `concepts/scope.md` (then `specs/prd.md` / `specs/ux.md` when present) as canonical. Plan generation, task generation, review, and feedback integration may change implementation approach, sequencing, verification, references, and YAGNI fences, but MUST NOT cut, narrow, expand, or reinterpret the agreed scope without an explicit user scope-change gate.
44
46
 
45
47
  ## Step 1 - Research Codebase
46
48
 
@@ -124,7 +126,7 @@ Use research findings from Step 1 to determine appropriate planning depth.
124
126
 
125
127
  ## Step 3 - High-Level Design
126
128
 
127
- **SKIP IF LIGHT** — proceed directly to Step 4.
129
+ **SKIP IF LIGHT** — proceed directly to Step 4. LIGHT still generates a real plan in Step 4; it only skips this human alignment gate.
128
130
 
129
131
  Goal: align on the *shape* of the solution before generating a full plan. This catches misalignments early and gives the user a chance to redirect before reading a long plan doc.
130
132
 
@@ -171,7 +173,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
171
173
 
172
174
  - **Action** — PersistDesign: Append a "Selected Design" section to `{OUT_DIR}/task_context.md` capturing the agreed approach, key decisions, and resolved questions. This is what `create_plan` consumes.
173
175
 
174
- > **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. The ONLY valid next action is invoking a Skill.
176
+ > **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. This is the early gate. The next valid actions are Skill invocations that generate the draft plan, generate tasks, run plan_review, integrate scope-safe feedback, and then present the final plan/tasks for the user's final gate.
175
177
 
176
178
  ## Step 4 - Route to Workflow
177
179
 
@@ -187,6 +189,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
187
189
  │ │
188
190
  │ ✅ CORRECT: Skill tool with skill: "spectre-create_plan", args: "..." │
189
191
  │ ✅ CORRECT: Skill tool with skill: "spectre-create_tasks", args: "..."│
192
+ │ ✅ CORRECT: Skill tool with skill: "spectre-plan_review", args: "..." │
190
193
  └────────────────────────────────────────────────────────────────────────┘
191
194
  ```
192
195
 
@@ -202,6 +205,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
202
205
 
203
206
  - Use the Skill tool: `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth {tier}"`
204
207
  - Use the Skill tool: `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
208
+ - For STANDARD/COMPREHENSIVE, use the Skill tool: `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
205
209
 
206
210
  ---
207
211
 
@@ -209,27 +213,34 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
209
213
 
210
214
  - **If LIGHT**:
211
215
 
216
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth light --no-review"`
217
+ - **Wait** — Returns concise plan with solution shape, patterns, risks, and verification approach
212
218
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md --depth light"`
213
- - **Wait** — Returns task breakdown with brief implementation approach
219
+ - **Wait** — Returns task breakdown grounded in the light plan
220
+ - **Action** — PresentLightArtifacts: Summarize `{OUT_DIR}/specs/plan.md` and `{OUT_DIR}/specs/tasks.md`. State that LIGHT skipped `plan_review` and the human execution gate by design.
214
221
  - Skip to footer
215
222
 
216
223
  - **ElseIf STANDARD**:
217
224
 
218
- - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard"`
225
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard --no-review"`
219
226
  - **Wait** — Returns focused plan (Overview, Approach, Out of Scope)
220
- - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
221
- - **Wait** — User approval
222
227
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
223
228
  - **Wait** — Returns task breakdown
229
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
230
+ - **Wait** — Returns findings, applied edits, skipped scope-changing recommendations, and updated artifacts
231
+ - **Action** — IntegratePlanReviewFeedback: Read the plan_review report path returned by `plan_review`. Confirm every scope-safe Blocker/High finding is reflected in `plan.md` and/or `tasks.md`. If `plan_review` produced a scope-safe suggested edit but did not apply it because it needed minor adaptation, apply the smallest artifact edit now and record it in the final summary. Do not apply Scope Change Required findings.
232
+ - Continue to Final Gate
224
233
 
225
234
  - **ElseIf COMPREHENSIVE**:
226
235
 
227
- - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive"`
236
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive --no-review"`
228
237
  - **Wait** — Returns full plan (all sections: Architecture, Phases, API Design, Testing Strategy, etc.)
229
- - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
230
- - **Wait** — User approval
231
238
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
232
239
  - **Wait** — Returns task breakdown
240
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
241
+ - **Wait** — Returns findings, applied edits, skipped scope-changing recommendations, and updated artifacts
242
+ - **Action** — IntegratePlanReviewFeedback: Read the plan_review report path returned by `plan_review`. Confirm every scope-safe Blocker/High finding is reflected in `plan.md` and/or `tasks.md`. If `plan_review` produced a scope-safe suggested edit but did not apply it because it needed minor adaptation, apply the smallest artifact edit now and record it in the final summary. Do not apply Scope Change Required findings.
243
+ - Continue to Final Gate
233
244
 
234
245
  ---
235
246
 
@@ -253,4 +264,19 @@ Only proceed past this checkpoint when the user confirms.
253
264
 
254
265
  ---
255
266
 
267
+ ### Final Gate
268
+
269
+ - **Action** — PresentFinalArtifacts:
270
+ - Summarize final artifact paths: `{OUT_DIR}/specs/plan.md`, `{OUT_DIR}/specs/tasks.md`, and the saved plan_review report under `{OUT_DIR}/reviews/`.
271
+ - Summarize review integration: findings applied by `plan_review`, any additional plan-orchestrator edits applied to integrate feedback, skipped edits, and any recommendations that were blocked because they would change canonical scope.
272
+ - If plan_review surfaced a scope-changing recommendation, state: "This requires a scope change; I did not apply it." Ask the user whether to reopen scope or approve the current canonical-scope-preserving plan/tasks.
273
+ - Otherwise prompt: "Final reviewed plan/tasks are ready. Reply `Approved` to proceed to execution, or provide final feedback."
274
+
275
+ - **Wait** — User final approval or feedback.
276
+
277
+ - **If feedback preserves canonical scope** — apply the smallest edits to `plan.md`/`tasks.md`, re-run `plan_review {OUT_DIR} --auto-apply scope-safe` if the feedback changes implementation approach, verification, dependencies, task sequencing, or references, then present the Final Gate again.
278
+ - **If feedback changes canonical scope** — stop and route back to `/spectre:scope` (or explicitly update the canonical scope artifact if the user directs it). Do not silently update plan/tasks against stale scope.
279
+
280
+ ---
281
+
256
282
  - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps
package/plugins/spectre/skills/plan_review/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: plan_review
3
- description: 👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
3
+ description: 👻 | Independent multi-lens review of plan.md and/or tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -10,14 +10,21 @@ user-invocable: true
10
10
 
11
11
  Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
12
12
 
13
- # plan_review: Multi-Lens Review of Plan & Tasks
13
+ # plan_review: Multi-Lens Review of Plan and/or Tasks
14
14
 
15
15
  ## Description
16
16
 
17
- - **What** — Independent review of `plan.md` + `tasks.md` from four specialized lenses, dispatched in parallel
18
- - **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update both artifacts
17
+ - **What** — Independent review of any available planning artifacts (`plan.md`, `tasks.md`, and optional `task_context.md`) from four specialized lenses, dispatched in parallel
18
+ - **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update the available artifacts
19
+ - **Artifact** — Always save a Markdown review report before any write-back so pre-integration findings are auditable
19
20
  - **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
20
21
 
22
+ ## Canonical Scope Invariant
23
+
24
+ `concepts/scope.md` is canonical when present. If absent, use `specs/prd.md`, `specs/ux.md`, and explicit requirements in `task_context.md` as the scope source, in that order.
25
+
26
+ Reviewers may recommend deleting unrequested implementation details, unnecessary abstractions, weak verification, hallucinated references, bad dependencies, or task sequencing problems. They MUST NOT cut, narrow, expand, or reinterpret agreed scope. If a reviewer believes the agreed scope itself is too large, internally inconsistent, or missing a requirement, phrase that as a **Scope Change Required** recommendation for the user. Do not apply it to `plan.md` or `tasks.md` during write-back.
27
+
21
28
  ## ARGUMENTS Input
22
29
 
23
30
  <ARGUMENTS>
@@ -42,63 +49,73 @@ A single reviewer biases toward the issues it notices first. Published practice
42
49
  - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
43
50
  - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
44
51
 
45
- - **Action** — ResolveArtifacts: Locate the three required inputs.
52
+ - **Action** — ResolveArtifacts: Locate the available review inputs.
46
53
  - `PLAN=${TASK_DIR}/specs/plan.md` (or scoped name)
47
54
  - `TASKS=${TASK_DIR}/specs/tasks.md` (or scoped name)
48
55
  - `CONTEXT=${TASK_DIR}/task_context.md`
49
- - If any are missing, list what's missing and stop — do NOT review against a partial set. Suggest the user run `/spectre:plan` or `/spectre:create_tasks` first.
56
+ - `SCOPE=${TASK_DIR}/concepts/scope.md` when present; otherwise use `specs/prd.md` / `specs/ux.md` as available
57
+ - `REVIEWS_DIR=${TASK_DIR}/reviews`
58
+ - `REVIEW_REPORT=${REVIEWS_DIR}/plan_review.md`; if that exists, use `plan_review_{YYYY-MM-DD_HHMMSS}.md` to avoid overwriting prior review evidence.
59
+ - `plan.md` and `tasks.md` are independently reviewable. It is valid to review only `plan.md`, only `tasks.md`, or both.
60
+ - `task_context.md` is helpful context but is not required. If it is missing, continue and note that requirements traceability is limited.
61
+ - If both `plan.md` and `tasks.md` are missing, stop and suggest the user run `/spectre:plan` or `/spectre:create_tasks` first.
62
+ - If exactly one of `plan.md` or `tasks.md` is missing, list it as absent context and continue. Do not decline, stop, or ask the user to create the missing artifact.
50
63
 
51
- - **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
64
+ - **Action** — ReadAvailable: Read each available file completely into context before dispatching reviewers. Reviewers receive curated excerpts plus an artifact manifest that says which files are present and absent. Every reviewer must review the artifacts that exist and must not treat absent artifacts as a blocker. The manifest must label the canonical scope source and state that review findings may not remove or narrow scope.
52
65
 
53
66
  ## Step 2 — Dispatch Four Parallel Reviewers
54
67
 
55
- Spawn all four subagents in a single message (parallel). Each receives the same artifact excerpts but a different review brief.
68
+ Spawn all four subagents in a single message (parallel). Each receives the same available artifact excerpts, the artifact manifest, and a different review brief.
69
+
70
+ Missing-artifact rule for every lens: review what exists. If a finding depends on a missing artifact, phrase it as "not reviewable because `<artifact>` is absent" only when that context is necessary; do not fail the review or ask for the missing artifact.
56
71
 
57
72
  ### Lens 1 — YAGNI / Familiar-Shape Bias (`@reviewer`)
58
73
 
59
- > Review this plan and task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
74
+ > Review the available plan and/or task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
60
75
  >
61
76
  > Find:
62
- > 1. Anything in `plan.md` Technical Approach that isn't traceable to a requirement in `task_context.md` / scope / PRD.
63
- > 2. Tasks in `tasks.md` that implement something the requirements don't ask for.
77
+ > 1. When `plan.md` is present: anything in Technical Approach that isn't traceable to a requirement in available context (`scope.md` / `task_context.md` / PRD / UX). If context is absent, use the plan's own requirements and boundaries.
78
+ > 2. When `tasks.md` is present: tasks that implement something the available requirements don't ask for. If requirements context is absent, use the task list's stated goals and boundaries.
64
79
  > 3. Abstractions, interfaces, or layers introduced for a single concrete caller.
65
80
  > 4. Generality (config files, plugin points, factories) where the actual need is one specific behavior.
66
81
  > 5. Overlap with the `Out-of-Bounds — DO NOT add` list (if anything violates that list, it's a hard fail).
67
82
  >
68
- > Required output: nominate the SINGLE highest-leverage thing to delete and justify it. You must pick one. Then list other simplifications ranked by impact. For each finding, cite the exact file:line or section header it lives in.
83
+ > Scope guard: you may nominate implementation detail to delete only when it is not required by canonical scope. Do not nominate an agreed requirement, user-approved behavior, or required task as the thing to delete. If the best "cut" would change canonical scope, label it **Scope Change Required** and do not include it as an auto-applicable deletion.
84
+ >
85
+ > Required output: nominate the SINGLE highest-leverage implementation detail to delete and justify it. You must pick one unless every possible deletion would change canonical scope; in that case, say "No scope-safe deletion found" and provide the nearest Scope Change Required recommendation separately. Then list other simplifications ranked by impact. For each finding, cite the exact file:line or section header it lives in.
69
86
 
70
87
  ### Lens 2 — Verifiability (`@analyst`)
71
88
 
72
- > Review this plan and task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
89
+ > Review the available plan and/or task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
73
90
  >
74
91
  > Find:
75
- > 1. Items in `plan.md` "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
76
- > 2. Phases in `plan.md` that don't declare a verification signal.
77
- > 3. Sub-tasks in `tasks.md` whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
78
- > 4. Verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
79
- > 5. Behavior-changing sub-tasks in `tasks.md` that lack a preceding RED test sub-task.
92
+ > 1. When `plan.md` is present: items in "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
93
+ > 2. When `plan.md` is present: phases that don't declare a verification signal.
94
+ > 3. When `tasks.md` is present: sub-tasks whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
95
+ > 4. When both `plan.md` and `tasks.md` are present: verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
96
+ > 5. When `tasks.md` is present: behavior-changing sub-tasks that lack a preceding RED test sub-task.
80
97
  >
81
98
  > Required output: list every non-executable criterion with a proposed rewrite in one of the three types. Cite file:line for each.
82
99
 
83
100
  ### Lens 3 — Existence / Hallucination (`@finder`)
84
101
 
85
- > Review this plan and task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
102
+ > Review the available plan and/or task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
86
103
  >
87
104
  > Verify:
88
- > 1. Every file path mentioned in `plan.md` "Critical Files for Implementation" and in `tasks.md` Context blocks — does the file exist in the repo today? Use Glob/Read to confirm.
89
- > 2. Every package in `plan.md` "External Dependencies" — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
90
- > 3. Every function, class, or symbol named in plan/tasks — grep the repo, confirm it exists where claimed.
105
+ > 1. Every file path mentioned in available artifacts, including `plan.md` "Critical Files for Implementation" and `tasks.md` Context blocks when present — does the file exist in the repo today? Use Glob/Read to confirm.
106
+ > 2. Every package in `plan.md` "External Dependencies" when `plan.md` is present — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
107
+ > 3. Every function, class, or symbol named in available plan/tasks — grep the repo, confirm it exists where claimed.
91
108
  > 4. Every API endpoint, env var, or CLI flag referenced — confirm it's defined in the codebase.
92
109
  >
93
110
  > Required output: list every reference that fails verification, with `expected: <plan claim>` and `actual: <repo state>`. If everything checks out, say so explicitly — don't pad.
94
111
 
95
112
  ### Lens 4 — Canonical Reference Quality (`@patterns`)
96
113
 
97
- > Review this plan and task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
114
+ > Review the available plan and/or task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
98
115
  >
99
116
  > Find:
100
- > 1. Places in `plan.md` Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
101
- > 2. Sub-tasks in `tasks.md` whose Context block lacks a canonical reference pointer.
117
+ > 1. When `plan.md` is present: places in Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
118
+ > 2. When `tasks.md` is present: sub-tasks whose Context block lacks a canonical reference pointer.
102
119
  > 3. Better canonical references that the plan missed — actual files in the codebase that more closely match the intended shape.
103
120
  > 4. Reuse opportunities the plan ignored: utilities, hooks, helpers, or types already in the repo that the plan re-implements.
104
121
  >
@@ -113,6 +130,7 @@ Spawn all four subagents in a single message (parallel). Each receives the same
113
130
  - **High** — meaningfully reduces output quality (missing RED test, weak canonical reference, prose criterion)
114
131
  - **Medium** — overengineering or reuse miss without functional blast radius
115
132
  - **Low** — stylistic or nice-to-have
133
+ - **Scope Change Required** — may be valid feedback, but would cut, expand, or reinterpret canonical scope and therefore needs explicit user approval before any artifact edit
116
134
 
117
135
  - **Action** — RenderFindingsTable: Output a single structured table. Schema is fixed.
118
136
 
@@ -138,11 +156,24 @@ Spawn all four subagents in a single message (parallel). Each receives the same
138
156
  - Low: {N}
139
157
  ```
140
158
 
159
+ - **Action** — SaveReviewArtifact: Before applying any edits to `plan.md` or `tasks.md`, save the pre-integration review findings as a Markdown report.
160
+ - Create `${REVIEWS_DIR}` if missing.
161
+ - Write `${REVIEW_REPORT}` using the RenderFindingsTable content plus:
162
+ - Reviewed artifacts: exact plan/tasks/context/scope paths present and absent.
163
+ - Canonical scope source used.
164
+ - Auto-apply mode: enabled/disabled.
165
+ - Timestamp.
166
+ - Explicit note: "This report captures plan_review findings before any write-back to plan.md or tasks.md."
167
+ - Do not overwrite an existing report. Use the timestamped filename if the default already exists.
168
+ - Include the saved report path in all subsequent summaries and in `ReportApplied`.
169
+
141
170
  ## Step 4 — Surface Findings & Apply Edits
142
171
 
143
- - **Action** — PresentFindings: Render the findings table inline.
172
+ - **Action** — PresentFindings: Render the findings table inline and include `Review report saved: {REVIEW_REPORT}`.
173
+
174
+ - **Action** — DetectAutoApplyMode: If ARGUMENTS contains `--auto-apply scope-safe`, skip the user selection prompt and apply all scope-safe Blocker and High findings, plus Medium/Low findings only when the Suggested Edit is unambiguous and cannot change canonical scope. Do not apply findings marked Scope Change Required. Continue to ApplyEdits and SelfCheck, then return the applied/skipped summary to the invoking workflow.
144
175
 
145
- - **Action** — OfferWriteBack: After the table, prompt:
176
+ - **Action** — OfferWriteBack: Unless `--auto-apply scope-safe` is present, after the table prompt:
146
177
 
147
178
  > Reply with which findings to apply:
148
179
  > - `all` — apply every suggested edit
@@ -150,25 +181,29 @@ Spawn all four subagents in a single message (parallel). Each receives the same
150
181
  > - `1,3,5` — apply specific finding numbers
151
182
  > - `skip` — leave artifacts unchanged
152
183
  >
153
- > For findings I apply, I'll edit plan.md and/or tasks.md inline and re-run a fast self-check.
184
+ > For findings I apply, I'll edit the relevant available artifact(s) inline and re-run a fast self-check.
154
185
 
155
186
  - **Wait** — User selects.
156
187
 
157
188
  - **Action** — ApplyEdits: For each selected finding:
158
- - Open the named artifact (plan.md or tasks.md)
189
+ - Open the named artifact (`plan.md` or `tasks.md`)
159
190
  - Apply the Suggested Edit verbatim where possible; if the edit needs adaptation, make the minimum change consistent with the finding's intent
160
191
  - Track which findings were applied
192
+ - Before writing, confirm the edit preserves every requirement and boundary in the canonical scope source. If it would remove, narrow, expand, or reinterpret scope, skip it and record it as "skipped: requires scope change."
161
193
 
162
194
  - **Action** — SelfCheck: After edits, run a fast pass over the modified sections:
163
195
  - Re-verify any file:line refs touched
164
196
  - Re-verify acceptance criteria are still executable
165
197
  - Confirm no edit introduced a new Out-of-Bounds violation
198
+ - Confirm canonical scope is still fully represented by the resulting plan/tasks
166
199
  - If any check fails, surface it and ask the user before continuing
167
200
 
168
201
  - **Action** — ReportApplied:
169
202
 
170
203
  > Applied: {list of finding numbers}. Skipped: {list}.
171
- > {Path to updated plan.md and tasks.md}.
204
+ > Review report: {REVIEW_REPORT}.
205
+ > {Path to updated artifact(s)}.
206
+ > Scope-change recommendations not applied: {list or "none"}.
172
207
 
173
208
  ## Step 5 — Next Steps
174
209
 
@@ -178,6 +213,6 @@ Spawn all four subagents in a single message (parallel). Each receives the same
178
213
 
179
214
  ## Notes
180
215
 
181
- - This skill does NOT generate plans or tasks. It reviews them. If `plan.md` or `tasks.md` doesn't exist, route the user to `/spectre:plan` first.
216
+ - This skill does NOT generate plans or tasks. It reviews available planning artifacts. If only one of `plan.md` or `tasks.md` exists, review that artifact. Only route the user to `/spectre:plan` or `/spectre:create_tasks` when neither reviewable artifact exists.
182
217
  - The four lenses are intentionally non-overlapping by design but will surface overlap in practice — dedupe at synthesis, don't ask reviewers to coordinate.
183
218
  - The "Must-Delete" nomination from Lens 1 is mandatory output — even on a tight plan, naming the single weakest element is a forcing function against under-review.
package/plugins/spectre-codex/skills/create_plan/SKILL.md CHANGED
@@ -27,6 +27,7 @@ Treat the current command arguments as this workflow's input. When invoked from
27
27
  - **Action** — CheckExistingResearch: Check if technical research already completed.
28
28
  - Read `TASK_DIR/task_context.md`; look for "## Technical Research" section.
29
29
  - **If** found with comprehensive analysis → use existing research; skip to Step 3.
30
+ - **If** ARGUMENTS contains `--depth light` and `TASK_DIR/task_context.md` already contains substantive router research (file locations, code understanding, codebase patterns, and impact summary) → use existing research; skip to Step 3.
30
31
  - **Else** → proceed with new research below.
31
32
  - **Action** — AutomatedResearch: Spawn parallel research agents for comprehensive analysis.
32
33
  - Use `@finder` to find all files related to feature area.
@@ -61,6 +62,8 @@ Treat the current command arguments as this workflow's input. When invoked from
61
62
 
62
63
  Dynamically generate up to 10 technical questions based on research findings. **IMPORTANT**: Only ask questions genuinely not answered in the PRD or discoverable through code investigation. Goal: eliminate scope and design ambiguity. If a question involves choosing between approaches, present options with Pros/Cons/Trade-offs.
63
64
 
65
+ - **Action** — LightModeClarifications: If ARGUMENTS contains `--depth light`, do NOT stop for user clarifications. Use conservative, codebase-consistent defaults and record them in the plan's **Filled Assumptions** section, then skip to Step 3. If an unresolved question would affect canonical scope, security/privacy, data correctness, or public API behavior, return control to `plan` with a tier reassessment recommendation instead of guessing.
66
+
64
67
  - **Action** — DetectClarificationMethod: Check if `AskUserQuestion` tool is available.
65
68
  - **If available** → use inline clarification flow (Path A).
66
69
  - **If not available** → use file-based clarification flow (Path B).
@@ -94,16 +97,17 @@ Dynamically generate up to 10 technical questions based on research findings. **
94
97
  - **Action** — DetermineDepth: Read `--depth` from ARGUMENTS
95
98
 
96
99
  - Default: `standard` if not specified
97
- - Options: `standard`, `comprehensive`
100
+ - Options: `light`, `standard`, `comprehensive`
101
+ - **Action** — DetectOrchestratedMode: If ARGUMENTS contains `--no-review`, this workflow is being invoked by `plan` as part of the meta-flow. Generate and save the plan, then return control to `plan` without asking for standalone user review.
98
102
 
99
103
  - **Action** — DesignTechnicalApproach: Create the implementation plan.
100
104
 
101
- Every plan, regardless of depth, MUST include these seven sections. They are the verification spine — without them, downstream agents cannot self-check their work.
105
+ Every plan, regardless of depth, MUST include the verification spine. LIGHT is concise, not shallow: keep it brief and decisive, but still explain the solution shape, codebase pattern to follow, risks/assumptions, and how the work will be verified.
102
106
 
103
- **Required for both STANDARD and COMPREHENSIVE:**
107
+ **Required for LIGHT, STANDARD, and COMPREHENSIVE:**
104
108
  1. **Overview** — 1–2 paragraphs: what problem, what shape the solution takes, why this approach.
105
109
  2. **Technical Approach** — How the change actually lands: components touched, data flow, key decisions with rationale. Reference existing patterns from `@patterns` research by file:line (e.g., "follow the shape of `src/widgets/HotDogWidget.ts:42` for the registration step").
106
- 3. **Critical Files for Implementation** — 3–7 specific files from research. Format: `path/to/file.ts` — *reason* (Core logic to modify / Pattern to follow / Interface to implement / Test to extend). No guesses — only files surfaced during Step 1 research.
110
+ 3. **Critical Files for Implementation** — 1–7 specific files from research. Format: `path/to/file.ts` — *reason* (Core logic to modify / Pattern to follow / Interface to implement / Test to extend). No guesses — only files surfaced during Step 1 research.
107
111
  4. **External Dependencies — Verify Before Implementation** — Every third-party package required, with exact version and a one-line existence check. Format: `package@1.2.3 — verify: npm view package@1.2.3` (or pip equivalent). Required even if "no new packages" (write that explicitly). This is the slopsquatting fence: ~20% of AI-suggested packages don't exist; we catch that here, not in production.
108
112
  5. **Verification — How We Know This Works** — For each major change in Technical Approach, 1–3 falsifiable signals: a test name, an observable behavior, or a state/file condition. Prose like "the feature works" is not acceptable — it must be checkable. Format: `<change> → verifies by: <test name | observable behavior | state condition>`. These become acceptance criteria in `create_tasks` downstream.
109
113
  6. **Out-of-Bounds — DO NOT add** — 4–8 concrete things the implementation must NOT add, even if "best practice." Examples: rate limiting, retry/backoff, caching layer, optimistic UI, soft-delete, telemetry events, feature flags, admin UI. This is the YAGNI fence against familiar-shape bias (agents reproduce mature-system patterns unprompted). Be specific to this feature, not generic.
@@ -111,6 +115,12 @@ Dynamically generate up to 10 technical questions based on research findings. **
111
115
  - *Risks*: what could go wrong (e.g., concurrent write race, migration ordering, third-party rate limit). Each with a one-line mitigation or "accept and monitor."
112
116
  - *Filled Assumptions*: things the plan defaulted because the spec didn't say (e.g., "Assumed Postgres; spec didn't specify DB." "Assumed retry count = 0; spec didn't mention failure modes."). Reviewer-visible by design — these are the silent decisions that bite at execution.
113
117
 
118
+ **LIGHT constraints:**
119
+ - Keep the seven required sections compact: usually 1 short paragraph or 3–5 bullets per section.
120
+ - Prefer one clear implementation path that follows existing codebase patterns; do not enumerate broad alternatives.
121
+ - Do not add standalone clarification gates, review gates, plan_review, or expanded architecture sections.
122
+ - If the plan needs more than 3 critical files, a new abstraction, data migration, public API change, or unresolved scope/security/data correctness decision, stop and return a tier reassessment recommendation to `plan`.
123
+
114
124
  **COMPREHENSIVE additionally requires:**
115
125
  8. **Current State** — How the affected code path works today, with file:line refs. Anchored to research findings.
116
126
  9. **Implementation Phases** — Ordered phases, each with its own Verification subsection (Phase N succeeds when …). Phases must be sequenced by dependency, not by file. Migration phases come before consumer phases.
@@ -125,14 +135,28 @@ Dynamically generate up to 10 technical questions based on research findings. **
125
135
 
126
136
  - **Action** — RequestReview:
127
137
 
128
- > "Implementation plan saved to `{path}`. Review and reply with feedback or 'Approved' to proceed."
138
+ - **If `--no-review` is present**:
139
+
140
+ > "Draft implementation plan saved to `{path}`. Returning to `plan` for the next routed step."
141
+
142
+ Do NOT wait for user approval. Return control to the invoking `plan` workflow.
143
+
144
+ - **Else**:
129
145
 
130
- - **Wait** — User provides feedback or approval
146
+ > "Implementation plan saved to `{path}`. Review and reply with feedback or 'Approved' to proceed."
147
+
148
+ - **Wait** — User provides feedback or approval, unless `--no-review` is present.
131
149
 
132
150
  ## Step (4/4) - Finalize and Present Next Steps
133
151
 
134
152
  - **Action** — ConfirmCompletion:
135
153
 
154
+ - **If `--no-review` is present**:
155
+
156
+ > "Draft implementation plan saved to `{plan_path}`. Returning to `plan`."
157
+
158
+ Stop here. Do not render the standalone Next Steps footer.
159
+
136
160
  > "🎯 Implementation Planning Complete. Documents: {plan_path}, task_context.md"
137
161
 
138
- - **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps footer
162
+ - **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps footer
package/plugins/spectre-codex/skills/plan/SKILL.md CHANGED
@@ -15,7 +15,7 @@ Treat the current command arguments as this workflow's input. When invoked from
15
15
  ## Description
16
16
 
17
17
  - **What** — Research codebase, assess complexity, route to appropriate workflow (direct tasks or plan-first)
18
- - **Outcome** — Detailed task breakdown ready for execution
18
+ - **Outcome** — A right-sized `plan.md` + `tasks.md`; STANDARD/COMPREHENSIVE include review and a final execution gate, while LIGHT stays non-blocking.
19
19
 
20
20
  ## ARGUMENTS Input
21
21
 
@@ -23,7 +23,7 @@ Treat the current command arguments as this workflow's input. When invoked from
23
23
 
24
24
  ## MANDATORY COMPLIANCE RULES
25
25
 
26
- > **⚠️ NON-NEGOTIABLE**: This workflow MUST invoke nested workflows via the Skill tool. Failure to invoke `Skill(create_plan)` and `Skill(create_tasks)` (Claude slash route: `create_plan` and `create_tasks`) is a critical error. Do NOT summarize, describe, or skip these workflows. INVOKE THEM.
26
+ > **⚠️ NON-NEGOTIABLE**: After tier routing, this workflow MUST invoke nested workflows via the Skill tool. LIGHT must invoke `Skill(create_plan)` and `Skill(create_tasks)`; STANDARD/COMPREHENSIVE must invoke `Skill(create_plan)`, `Skill(create_tasks)`, and `Skill(plan_review)` (Claude slash route: `create_plan`, `create_tasks`, and `plan_review`). Failure to invoke the required skills is a critical error. Do NOT summarize, describe, or skip these workflows. INVOKE THEM.
27
27
 
28
28
  **After ANY user conversation or questions:**
29
29
 
@@ -33,14 +33,16 @@ Treat the current command arguments as this workflow's input. When invoked from
33
33
 
34
34
  **You MUST call these skills (not describe them):**
35
35
 
36
- - Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md
36
+ - Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md, including LIGHT
37
37
  - Use the **Skill** tool with `skill: "spectre-create_tasks"` and `args: "{path}"` — generates tasks.md
38
+ - Use the **Skill** tool with `skill: "spectre-plan_review"` and `args: "{OUT_DIR} --auto-apply scope-safe"` — reviews and integrates scope-safe feedback for STANDARD/COMPREHENSIVE
38
39
 
39
40
  ## Instructions
40
41
 
41
42
  - Research before routing; present architectural options for user buy-in
42
43
  - Route based on hard-stops and clarity, not point-scoring
43
44
  - Never overwrite existing `tasks.md` or `plan.md` — use scoped names
45
+ - Treat `concepts/scope.md` (then `specs/prd.md` / `specs/ux.md` when present) as canonical. Plan generation, task generation, review, and feedback integration may change implementation approach, sequencing, verification, references, and YAGNI fences, but MUST NOT cut, narrow, expand, or reinterpret the agreed scope without an explicit user scope-change gate.
44
46
 
45
47
  ## Step 1 - Research Codebase
46
48
 
@@ -124,7 +126,7 @@ Use research findings from Step 1 to determine appropriate planning depth.
124
126
 
125
127
  ## Step 3 - High-Level Design
126
128
 
127
- **SKIP IF LIGHT** — proceed directly to Step 4.
129
+ **SKIP IF LIGHT** — proceed directly to Step 4. LIGHT still generates a real plan in Step 4; it only skips this human alignment gate.
128
130
 
129
131
  Goal: align on the *shape* of the solution before generating a full plan. This catches misalignments early and gives the user a chance to redirect before reading a long plan doc.
130
132
 
@@ -171,7 +173,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
171
173
 
172
174
  - **Action** — PersistDesign: Append a "Selected Design" section to `{OUT_DIR}/task_context.md` capturing the agreed approach, key decisions, and resolved questions. This is what `create_plan` consumes.
173
175
 
174
- > **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. The ONLY valid next action is invoking a Skill.
176
+ > **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. This is the early gate. The next valid actions are Skill invocations that generate the draft plan, generate tasks, run plan_review, integrate scope-safe feedback, and then present the final plan/tasks for the user's final gate.
175
177
 
176
178
  ## Step 4 - Route to Workflow
177
179
 
@@ -187,6 +189,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
187
189
  │ │
188
190
  │ ✅ CORRECT: Skill tool with skill: "spectre-create_plan", args: "..." │
189
191
  │ ✅ CORRECT: Skill tool with skill: "spectre-create_tasks", args: "..."│
192
+ │ ✅ CORRECT: Skill tool with skill: "spectre-plan_review", args: "..." │
190
193
  └────────────────────────────────────────────────────────────────────────┘
191
194
  ```
192
195
 
@@ -202,6 +205,7 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
202
205
 
203
206
  - Use the Skill tool: `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth {tier}"`
204
207
  - Use the Skill tool: `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
208
+ - For STANDARD/COMPREHENSIVE, use the Skill tool: `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
205
209
 
206
210
  ---
207
211
 
@@ -209,27 +213,34 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
209
213
 
210
214
  - **If LIGHT**:
211
215
 
216
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth light --no-review"`
217
+ - **Wait** — Returns concise plan with solution shape, patterns, risks, and verification approach
212
218
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md --depth light"`
213
- - **Wait** — Returns task breakdown with brief implementation approach
219
+ - **Wait** — Returns task breakdown grounded in the light plan
220
+ - **Action** — PresentLightArtifacts: Summarize `{OUT_DIR}/specs/plan.md` and `{OUT_DIR}/specs/tasks.md`. State that LIGHT skipped `plan_review` and the human execution gate by design.
214
221
  - Skip to footer
215
222
 
216
223
  - **ElseIf STANDARD**:
217
224
 
218
- - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard"`
225
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard --no-review"`
219
226
  - **Wait** — Returns focused plan (Overview, Approach, Out of Scope)
220
- - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
221
- - **Wait** — User approval
222
227
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
223
228
  - **Wait** — Returns task breakdown
229
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
230
+ - **Wait** — Returns findings, applied edits, skipped scope-changing recommendations, and updated artifacts
231
+ - **Action** — IntegratePlanReviewFeedback: Read the plan_review report path returned by `plan_review`. Confirm every scope-safe Blocker/High finding is reflected in `plan.md` and/or `tasks.md`. If `plan_review` produced a scope-safe suggested edit but did not apply it because it needed minor adaptation, apply the smallest artifact edit now and record it in the final summary. Do not apply Scope Change Required findings.
232
+ - Continue to Final Gate
224
233
 
225
234
  - **ElseIf COMPREHENSIVE**:
226
235
 
227
- - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive"`
236
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive --no-review"`
228
237
  - **Wait** — Returns full plan (all sections: Architecture, Phases, API Design, Testing Strategy, etc.)
229
- - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
230
- - **Wait** — User approval
231
238
  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
232
239
  - **Wait** — Returns task breakdown
240
+ - **INVOKE NOW** → Skill tool with `skill: "spectre-plan_review"`, `args: "{OUT_DIR} --auto-apply scope-safe"`
241
+ - **Wait** — Returns findings, applied edits, skipped scope-changing recommendations, and updated artifacts
242
+ - **Action** — IntegratePlanReviewFeedback: Read the plan_review report path returned by `plan_review`. Confirm every scope-safe Blocker/High finding is reflected in `plan.md` and/or `tasks.md`. If `plan_review` produced a scope-safe suggested edit but did not apply it because it needed minor adaptation, apply the smallest artifact edit now and record it in the final summary. Do not apply Scope Change Required findings.
243
+ - Continue to Final Gate
233
244
 
234
245
  ---
235
246
 
@@ -253,4 +264,19 @@ Only proceed past this checkpoint when the user confirms.
253
264
 
254
265
  ---
255
266
 
267
+ ### Final Gate
268
+
269
+ - **Action** — PresentFinalArtifacts:
270
+ - Summarize final artifact paths: `{OUT_DIR}/specs/plan.md`, `{OUT_DIR}/specs/tasks.md`, and the saved plan_review report under `{OUT_DIR}/reviews/`.
271
+ - Summarize review integration: findings applied by `plan_review`, any additional plan-orchestrator edits applied to integrate feedback, skipped edits, and any recommendations that were blocked because they would change canonical scope.
272
+ - If plan_review surfaced a scope-changing recommendation, state: "This requires a scope change; I did not apply it." Ask the user whether to reopen scope or approve the current canonical-scope-preserving plan/tasks.
273
+ - Otherwise prompt: "Final reviewed plan/tasks are ready. Reply `Approved` to proceed to execution, or provide final feedback."
274
+
275
+ - **Wait** — User final approval or feedback.
276
+
277
+ - **If feedback preserves canonical scope** — apply the smallest edits to `plan.md`/`tasks.md`, re-run `plan_review {OUT_DIR} --auto-apply scope-safe` if the feedback changes implementation approach, verification, dependencies, task sequencing, or references, then present the Final Gate again.
278
+ - **If feedback changes canonical scope** — stop and route back to `scope` (or explicitly update the canonical scope artifact if the user directs it). Do not silently update plan/tasks against stale scope.
279
+
280
+ ---
281
+
256
282
  - **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps
package/plugins/spectre-codex/skills/plan_review/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: "plan_review"
3
- description: "👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references"
3
+ description: "👻 | Independent multi-lens review of plan.md and/or tasks.md — finds overengineering, missing verification, hallucinated deps, weak references"
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -10,14 +10,21 @@ user-invocable: true
10
10
 
11
11
  Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
12
12
 
13
- # plan_review: Multi-Lens Review of Plan & Tasks
13
+ # plan_review: Multi-Lens Review of Plan and/or Tasks
14
14
 
15
15
  ## Description
16
16
 
17
- - **What** — Independent review of `plan.md` + `tasks.md` from four specialized lenses, dispatched in parallel
18
- - **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update both artifacts
17
+ - **What** — Independent review of any available planning artifacts (`plan.md`, `tasks.md`, and optional `task_context.md`) from four specialized lenses, dispatched in parallel
18
+ - **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update the available artifacts
19
+ - **Artifact** — Always save a Markdown review report before any write-back so pre-integration findings are auditable
19
20
  - **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
20
21
 
22
+ ## Canonical Scope Invariant
23
+
24
+ `concepts/scope.md` is canonical when present. If absent, use `specs/prd.md`, `specs/ux.md`, and explicit requirements in `task_context.md` as the scope source, in that order.
25
+
26
+ Reviewers may recommend deleting unrequested implementation details, unnecessary abstractions, weak verification, hallucinated references, bad dependencies, or task sequencing problems. They MUST NOT cut, narrow, expand, or reinterpret agreed scope. If a reviewer believes the agreed scope itself is too large, internally inconsistent, or missing a requirement, phrase that as a **Scope Change Required** recommendation for the user. Do not apply it to `plan.md` or `tasks.md` during write-back.
27
+
21
28
  ## ARGUMENTS Input
22
29
 
23
30
  <ARGUMENTS>
@@ -42,63 +49,73 @@ A single reviewer biases toward the issues it notices first. Published practice
42
49
  - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
43
50
  - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
44
51
 
45
- - **Action** — ResolveArtifacts: Locate the three required inputs.
52
+ - **Action** — ResolveArtifacts: Locate the available review inputs.
46
53
  - `PLAN=${TASK_DIR}/specs/plan.md` (or scoped name)
47
54
  - `TASKS=${TASK_DIR}/specs/tasks.md` (or scoped name)
48
55
  - `CONTEXT=${TASK_DIR}/task_context.md`
49
- - If any are missing, list what's missing and stop — do NOT review against a partial set. Suggest the user run `plan` or `create_tasks` first.
56
+ - `SCOPE=${TASK_DIR}/concepts/scope.md` when present; otherwise use `specs/prd.md` / `specs/ux.md` as available
57
+ - `REVIEWS_DIR=${TASK_DIR}/reviews`
58
+ - `REVIEW_REPORT=${REVIEWS_DIR}/plan_review.md`; if that exists, use `plan_review_{YYYY-MM-DD_HHMMSS}.md` to avoid overwriting prior review evidence.
59
+ - `plan.md` and `tasks.md` are independently reviewable. It is valid to review only `plan.md`, only `tasks.md`, or both.
60
+ - `task_context.md` is helpful context but is not required. If it is missing, continue and note that requirements traceability is limited.
61
+ - If both `plan.md` and `tasks.md` are missing, stop and suggest the user run `plan` or `create_tasks` first.
62
+ - If exactly one of `plan.md` or `tasks.md` is missing, list it as absent context and continue. Do not decline, stop, or ask the user to create the missing artifact.
50
63
 
51
- - **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
64
+ - **Action** — ReadAvailable: Read each available file completely into context before dispatching reviewers. Reviewers receive curated excerpts plus an artifact manifest that says which files are present and absent. Every reviewer must review the artifacts that exist and must not treat absent artifacts as a blocker. The manifest must label the canonical scope source and state that review findings may not remove or narrow scope.
52
65
 
53
66
  ## Step 2 — Dispatch Four Parallel Reviewers
54
67
 
55
- Spawn all four subagents in a single message (parallel). Each receives the same artifact excerpts but a different review brief.
68
+ Spawn all four subagents in a single message (parallel). Each receives the same available artifact excerpts, the artifact manifest, and a different review brief.
69
+
70
+ Missing-artifact rule for every lens: review what exists. If a finding depends on a missing artifact, phrase it as "not reviewable because `<artifact>` is absent" only when that context is necessary; do not fail the review or ask for the missing artifact.
56
71
 
57
72
  ### Lens 1 — YAGNI / Familiar-Shape Bias (`@reviewer`)
58
73
 
59
- > Review this plan and task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
74
+ > Review the available plan and/or task list for unrequested complexity. Agents have a documented "familiar-shape bias": shown a feature, they reproduce the mature-system shape from their training data (auth → adds rate-limiting; CRUD → adds soft-delete; form → adds optimistic UI; service → adds telemetry; module → adds feature flags). Your job is to find that bias here.
60
75
  >
61
76
  > Find:
62
- > 1. Anything in `plan.md` Technical Approach that isn't traceable to a requirement in `task_context.md` / scope / PRD.
63
- > 2. Tasks in `tasks.md` that implement something the requirements don't ask for.
77
+ > 1. When `plan.md` is present: anything in Technical Approach that isn't traceable to a requirement in available context (`scope.md` / `task_context.md` / PRD / UX). If context is absent, use the plan's own requirements and boundaries.
78
+ > 2. When `tasks.md` is present: tasks that implement something the available requirements don't ask for. If requirements context is absent, use the task list's stated goals and boundaries.
64
79
  > 3. Abstractions, interfaces, or layers introduced for a single concrete caller.
65
80
  > 4. Generality (config files, plugin points, factories) where the actual need is one specific behavior.
66
81
  > 5. Overlap with the `Out-of-Bounds — DO NOT add` list (if anything violates that list, it's a hard fail).
67
82
  >
68
- > Required output: nominate the SINGLE highest-leverage thing to delete and justify it. You must pick one. Then list other simplifications ranked by impact. For each finding, cite the exact file:line or section header it lives in.
83
+ > Scope guard: you may nominate implementation detail to delete only when it is not required by canonical scope. Do not nominate an agreed requirement, user-approved behavior, or required task as the thing to delete. If the best "cut" would change canonical scope, label it **Scope Change Required** and do not include it as an auto-applicable deletion.
84
+ >
85
+ > Required output: nominate the SINGLE highest-leverage implementation detail to delete and justify it. You must pick one unless every possible deletion would change canonical scope; in that case, say "No scope-safe deletion found" and provide the nearest Scope Change Required recommendation separately. Then list other simplifications ranked by impact. For each finding, cite the exact file:line or section header it lives in.
69
86
 
70
87
  ### Lens 2 — Verifiability (`@analyst`)
71
88
 
72
- > Review this plan and task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
89
+ > Review the available plan and/or task list for verification quality. The single highest-correlate of successful AI-agent execution is the ability to self-verify. Find every place where verification is missing, prose-only, or disconnected.
73
90
  >
74
91
  > Find:
75
- > 1. Items in `plan.md` "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
76
- > 2. Phases in `plan.md` that don't declare a verification signal.
77
- > 3. Sub-tasks in `tasks.md` whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
78
- > 4. Verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
79
- > 5. Behavior-changing sub-tasks in `tasks.md` that lack a preceding RED test sub-task.
92
+ > 1. When `plan.md` is present: items in "Verification — How We Know This Works" that are prose ("works correctly", "is consistent") rather than executable (test name / observable behavior / state condition).
93
+ > 2. When `plan.md` is present: phases that don't declare a verification signal.
94
+ > 3. When `tasks.md` is present: sub-tasks whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
95
+ > 4. When both `plan.md` and `tasks.md` are present: verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
96
+ > 5. When `tasks.md` is present: behavior-changing sub-tasks that lack a preceding RED test sub-task.
80
97
  >
81
98
  > Required output: list every non-executable criterion with a proposed rewrite in one of the three types. Cite file:line for each.
82
99
 
83
100
  ### Lens 3 — Existence / Hallucination (`@finder`)
84
101
 
85
- > Review this plan and task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
102
+ > Review the available plan and/or task list for references to things that may not exist. AI-generated plans hallucinate file paths, package names, function signatures, and API endpoints at measurable rates (~20% for packages per Snyk analysis). Your job is to verify every reference is real.
86
103
  >
87
104
  > Verify:
88
- > 1. Every file path mentioned in `plan.md` "Critical Files for Implementation" and in `tasks.md` Context blocks — does the file exist in the repo today? Use Glob/Read to confirm.
89
- > 2. Every package in `plan.md` "External Dependencies" — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
90
- > 3. Every function, class, or symbol named in plan/tasks — grep the repo, confirm it exists where claimed.
105
+ > 1. Every file path mentioned in available artifacts, including `plan.md` "Critical Files for Implementation" and `tasks.md` Context blocks when present — does the file exist in the repo today? Use Glob/Read to confirm.
106
+ > 2. Every package in `plan.md` "External Dependencies" when `plan.md` is present — does it exist at the named version? (Note: actual install/registry check is the executor's Phase 0 job; your job is to flag suspicious names — typos, near-misses to well-known packages, lookalikes.)
107
+ > 3. Every function, class, or symbol named in available plan/tasks — grep the repo, confirm it exists where claimed.
91
108
  > 4. Every API endpoint, env var, or CLI flag referenced — confirm it's defined in the codebase.
92
109
  >
93
110
  > Required output: list every reference that fails verification, with `expected: <plan claim>` and `actual: <repo state>`. If everything checks out, say so explicitly — don't pad.
94
111
 
95
112
  ### Lens 4 — Canonical Reference Quality (`@patterns`)
96
113
 
97
- > Review this plan and task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
114
+ > Review the available plan and/or task list for the quality of "follow existing pattern" references. Anthropic's own guidance is to anchor plans with concrete examples (e.g., "HotDogWidget.php is a good example"). Vague "follow existing patterns" without a file:line anchor is a documented failure mode.
98
115
  >
99
116
  > Find:
100
- > 1. Places in `plan.md` Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
101
- > 2. Sub-tasks in `tasks.md` whose Context block lacks a canonical reference pointer.
117
+ > 1. When `plan.md` is present: places in Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
118
+ > 2. When `tasks.md` is present: sub-tasks whose Context block lacks a canonical reference pointer.
102
119
  > 3. Better canonical references that the plan missed — actual files in the codebase that more closely match the intended shape.
103
120
  > 4. Reuse opportunities the plan ignored: utilities, hooks, helpers, or types already in the repo that the plan re-implements.
104
121
  >
@@ -113,6 +130,7 @@ Spawn all four subagents in a single message (parallel). Each receives the same
113
130
  - **High** — meaningfully reduces output quality (missing RED test, weak canonical reference, prose criterion)
114
131
  - **Medium** — overengineering or reuse miss without functional blast radius
115
132
  - **Low** — stylistic or nice-to-have
133
+ - **Scope Change Required** — may be valid feedback, but would cut, expand, or reinterpret canonical scope and therefore needs explicit user approval before any artifact edit
116
134
 
117
135
  - **Action** — RenderFindingsTable: Output a single structured table. Schema is fixed.
118
136
 
@@ -138,11 +156,24 @@ Spawn all four subagents in a single message (parallel). Each receives the same
138
156
  - Low: {N}
139
157
  ```
140
158
 
159
+ - **Action** — SaveReviewArtifact: Before applying any edits to `plan.md` or `tasks.md`, save the pre-integration review findings as a Markdown report.
160
+ - Create `${REVIEWS_DIR}` if missing.
161
+ - Write `${REVIEW_REPORT}` using the RenderFindingsTable content plus:
162
+ - Reviewed artifacts: exact plan/tasks/context/scope paths present and absent.
163
+ - Canonical scope source used.
164
+ - Auto-apply mode: enabled/disabled.
165
+ - Timestamp.
166
+ - Explicit note: "This report captures plan_review findings before any write-back to plan.md or tasks.md."
167
+ - Do not overwrite an existing report. Use the timestamped filename if the default already exists.
168
+ - Include the saved report path in all subsequent summaries and in `ReportApplied`.
169
+
141
170
  ## Step 4 — Surface Findings & Apply Edits
142
171
 
143
- - **Action** — PresentFindings: Render the findings table inline.
172
+ - **Action** — PresentFindings: Render the findings table inline and include `Review report saved: {REVIEW_REPORT}`.
173
+
174
+ - **Action** — DetectAutoApplyMode: If ARGUMENTS contains `--auto-apply scope-safe`, skip the user selection prompt and apply all scope-safe Blocker and High findings, plus Medium/Low findings only when the Suggested Edit is unambiguous and cannot change canonical scope. Do not apply findings marked Scope Change Required. Continue to ApplyEdits and SelfCheck, then return the applied/skipped summary to the invoking workflow.
144
175
 
145
- - **Action** — OfferWriteBack: After the table, prompt:
176
+ - **Action** — OfferWriteBack: Unless `--auto-apply scope-safe` is present, after the table prompt:
146
177
 
147
178
  > Reply with which findings to apply:
148
179
  > - `all` — apply every suggested edit
@@ -150,25 +181,29 @@ Spawn all four subagents in a single message (parallel). Each receives the same
150
181
  > - `1,3,5` — apply specific finding numbers
151
182
  > - `skip` — leave artifacts unchanged
152
183
  >
153
- > For findings I apply, I'll edit plan.md and/or tasks.md inline and re-run a fast self-check.
184
+ > For findings I apply, I'll edit the relevant available artifact(s) inline and re-run a fast self-check.
154
185
 
155
186
  - **Wait** — User selects.
156
187
 
157
188
  - **Action** — ApplyEdits: For each selected finding:
158
- - Open the named artifact (plan.md or tasks.md)
189
+ - Open the named artifact (`plan.md` or `tasks.md`)
159
190
  - Apply the Suggested Edit verbatim where possible; if the edit needs adaptation, make the minimum change consistent with the finding's intent
160
191
  - Track which findings were applied
192
+ - Before writing, confirm the edit preserves every requirement and boundary in the canonical scope source. If it would remove, narrow, expand, or reinterpret scope, skip it and record it as "skipped: requires scope change."
161
193
 
162
194
  - **Action** — SelfCheck: After edits, run a fast pass over the modified sections:
163
195
  - Re-verify any file:line refs touched
164
196
  - Re-verify acceptance criteria are still executable
165
197
  - Confirm no edit introduced a new Out-of-Bounds violation
198
+ - Confirm canonical scope is still fully represented by the resulting plan/tasks
166
199
  - If any check fails, surface it and ask the user before continuing
167
200
 
168
201
  - **Action** — ReportApplied:
169
202
 
170
203
  > Applied: {list of finding numbers}. Skipped: {list}.
171
- > {Path to updated plan.md and tasks.md}.
204
+ > Review report: {REVIEW_REPORT}.
205
+ > {Path to updated artifact(s)}.
206
+ > Scope-change recommendations not applied: {list or "none"}.
172
207
 
173
208
  ## Step 5 — Next Steps
174
209
 
@@ -178,6 +213,6 @@ Spawn all four subagents in a single message (parallel). Each receives the same
178
213
 
179
214
  ## Notes
180
215
 
181
- - This skill does NOT generate plans or tasks. It reviews them. If `plan.md` or `tasks.md` doesn't exist, route the user to `plan` first.
216
+ - This skill does NOT generate plans or tasks. It reviews available planning artifacts. If only one of `plan.md` or `tasks.md` exists, review that artifact. Only route the user to `plan` or `create_tasks` when neither reviewable artifact exists.
182
217
  - The four lenses are intentionally non-overlapping by design but will surface overlap in practice — dedupe at synthesis, don't ask reviewers to coordinate.
183
218
  - The "Must-Delete" nomination from Lens 1 is mandatory output — even on a tight plan, naming the single weakest element is a forcing function against under-review.