@codename_inc/spectre 4.0.0 → 5.1.0

package/README.md

@@ -65,7 +65,7 @@ Session continuity deep dive: [`docs/codex-sessionstart-memory.md`](./docs/codex
 
 ## 🔁 How It Works
 
-- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux_spec` to define user flows, components, and layout for a new feature.
+- run one of the kickoff prompts in Claude Code - `/spectre:scope` is the main command for building new features, but also `/spectre:kickoff` for high ambiguity new features (includes web research), `/spectre:research` for codebase research "how might we build …” style Qs, or `/spectre:ux` to define user flows, components, and layout for a new feature.
 
 - follow the prompts/instructions to create the related canonical document and Claude Code will suggest the next step in the SPECTRE workflow automatically (e.g., going from `scope` to `plan` to `tasks` and so on)
 
@@ -281,7 +281,7 @@ Although I do sometimes use @spectre:web-research for web research. It's like mi
 
 - start /spectre:scope to get crisp on what's in/out. this is non-negotiable unless the feature is a one line ask.
 
-  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux_spec. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
+  - if the feature's ux/user flow is unclear to me, or I want to make sure to really nail it, i run /spectre:ux. Its similar to /spectre:scope but focuses on getting clear on the core user flows.
 
 - /spectre:plan to build out a well researched technical design or set of tasks
 
@@ -367,7 +367,7 @@ I use /spectre:fix for pretty much all bugs I run into.
 | --- | --- |
 | `/spectre:sweep` | Light cleanup pass — lint, test, descriptive commits |
 | `/spectre:learn` | Capture knowledge for future sessions |
-| `/spectre:ux_spec` | UX specification for UI-heavy features |
+| `/spectre:ux` | UX specification for UI-heavy features |
 | `/spectre:fix` | Investigate bugs & implement fixes |
 
 ## 📁 Repository Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codename_inc/spectre",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "type": "module",
   "bin": {
     "spectre": "./bin/spectre.js"

package/plugins/spectre/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "spectre",
-  "version": "4.0.0",
+  "version": "5.1.0",
   "description": "Agentic coding workflow with session memory. spectre guides you through Scope, Plan, Execute, Clean, Test, Rebase, and Extract phases."
 }

package/plugins/spectre/skills/create_plan/SKILL.md

@@ -29,8 +29,9 @@ Treat the current command arguments as this workflow's input. When invoked from
   - **If** found with comprehensive analysis → use existing research; skip to Step 3.
   - **Else** → proceed with new research below.
 - **Action** — AutomatedResearch: Spawn parallel research agents for comprehensive analysis.
-  - Use `codebase-locator` to find all files related to feature area.
-  - Dispatch multiple parallel `codebase-analyzer` subagents to understand current implementation patterns. Pay particular attention to how and where data is accessed that will be needed for this feature.
+  - Use `@finder` to find all files related to feature area.
+  - Dispatch multiple parallel `@analyst` subagents to understand current implementation patterns. Pay particular attention to how and where data is accessed that will be needed for this feature.
+  - Use `@patterns` to surface canonical reference implementations already in the codebase — these become "follow this file" anchors in the plan.
   - Wait for ALL agents to complete before proceeding.
   - Read ALL identified files into context.
 - **Action** — TraceCodePaths: Trace through relevant execution paths.
@@ -97,17 +98,28 @@ Dynamically generate up to 10 technical questions based on research findings. **
 
 - **Action** — DesignTechnicalApproach: Create the implementation plan.
 
-  **STANDARD** depth — Focused plan for contained changes. Include the sections that matter for THIS feature. Typical sections: Overview, Desired End State, Out of Scope, Technical Approach.
-
-  **COMPREHENSIVE** depth — Full technical design for complex/risky changes. Consider all of the following, but only include sections relevant to the feature: Overview, Current State (with file:line refs), Desired End State, Out of Scope, Technical Approach, System Architecture, Implementation Phases, Component/Data Architecture, API Design, Testing Strategy.
-
-  Use your judgment — the goal is a plan that gives a developer everything they need to implement, not a template with empty sections.
-
-- **Action** — AppendCriticalFiles: End the plan with a "Critical Files for Implementation" section.
-
-  - List 3-7 files most critical for implementing this plan.
-  - Format: `path/to/file.ts` — brief reason (e.g., "Core logic to modify", "Pattern to follow", "Interface to implement").
-  - These should be specific files discovered during research, not guesses.
+  Every plan, regardless of depth, MUST include these seven sections. They are the verification spine — without them, downstream agents cannot self-check their work.
+
+  **Required for both STANDARD and COMPREHENSIVE:**
+  1. **Overview** — 1–2 paragraphs: what problem, what shape the solution takes, why this approach.
+  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").
+  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.
+  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.
+  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.
+  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.
+  7. **Risks & Filled Assumptions** — Two short subsections:
+     - *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."
+     - *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.
+
+  **COMPREHENSIVE additionally requires:**
+  8. **Current State** — How the affected code path works today, with file:line refs. Anchored to research findings.
+  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.
+  10. **Component / Data Architecture** — Where data is created, mutated, and read. Schema deltas if any.
+  11. **API Design** — Endpoint signatures, request/response shapes, error contracts. Required if any external or internal API surface changes.
+  12. **Migration Plan** — Required if any data-layer change. Up + down migration sketch, backfill strategy, rollback plan.
+  13. **Testing Strategy** — What test types cover what (unit / integration / e2e), where new tests live, what's deferred to the post-feature coverage task.
+
+  Use your judgment on section length, not on inclusion. If a required section is genuinely N/A for this feature, write the section header followed by *"N/A — <one-line reason>"*. Empty section headers are not acceptable; absent section headers are not acceptable.
 
 - **Action** — DocumentPlan: Save to `{OUT_DIR}/specs/plan.md` (use scoped name if exists)
 

package/plugins/spectre/skills/create_tasks/SKILL.md

@@ -129,12 +129,46 @@ Read completely (no limits):
   - This section helps the user understand how the work integrates with the product before diving into tasks
 
 ### Task Hierarchy (4 Levels)
-- **📦 Phase**: Organizational header (no checkbox) — groups related parent tasks
-- **📋 Parent Task**: Cohesive deliverable (small-medium scope) — one component/file
-- **✓ Sub-task**: Atomic work (single focused change) — single action, 2-3 acceptance criteria
-- **✓ Acceptance Criteria**: Verifiable outcomes (not implementation steps)
+- **Phase**: Organizational header (no checkbox) — groups related parent tasks
+- **Parent Task**: Cohesive deliverable (small-medium scope) — one component/file
+- **Sub-task**: Atomic work (single focused change) — single action, 2-3 acceptance criteria
+- **Acceptance Criteria**: Executable, verifiable outcomes (see Acceptance Criteria Types below)
 
-**Numbering**: Phase 1 → Parent 1.1, 1.2 → Sub-tasks 1.1.1, 1.1.2 → Criteria ✓
+**Numbering**: Phase 1 → Parent 1.1, 1.2 → Sub-tasks 1.1.1, 1.1.2 → Criteria
+
+### Right-Sized for AI Execution
+
+Published data on AI agent execution (Cognition's Devin reviews, Anthropic's Claude Code guidance) converges on a bounded sweet spot: each sub-task should be completable in roughly the time a junior would take in a 4–8 hour window — not a multi-day epic, not a 10-line tweak.
+
+**Hard size cap — split a sub-task if ANY of these is true:**
+- Touches more than 3 files
+- Has more than 5 acceptance criteria
+- Would require more than ~200 lines of diff
+- Requires a mid-execution judgment call about scope (split the judgment into its own predecessor task)
+- Spans more than one concern (e.g., schema + UI in one sub-task)
+
+When splitting, keep the integration-aware principle intact: each split task still names its Producer / Consumer / Replaces.
+
+### Acceptance Criteria Types
+
+Every acceptance criterion MUST be one of three executable types. Prose criteria like "feature works correctly" or "behavior is consistent" are forbidden — an executor cannot self-check them.
+
+1. **Test passes** — `Test \`<test_name>\` passes` (or `tests in <file_path> pass`)
+2. **Observable behavior** — A specific, checkable runtime signal: `GET /api/x returns 200 with field \`y\``, `Console logs \`event=loaded params={...}\``, `Button click triggers <handler> within 100ms`
+3. **State / file condition** — `File \`<path>\` exists and contains <pattern>`, `Migration \`<id>\` applied`, `Env var \`X\` is read at startup`
+
+Mixing types within a sub-task is fine. What's not fine: criteria the agent cannot verify without asking the user.
+
+### Test-First Task Pairing
+
+For any sub-task that changes observable behavior (not pure refactors or cleanup), pair it with a preceding RED task. Pattern:
+
+- **N.M.k RED**: Write failing test `<test_name>` asserting `<behavior>`. Acceptance: test exists and fails for the documented reason.
+- **N.M.(k+1) Build**: Implement `<change>`. Acceptance: the RED test passes; no other tests regress.
+
+This is the TDAD pattern (test-driven agentic development): the failing test is the executor's self-correction signal. Without it, the executor is guessing whether the implementation is right.
+
+Pure refactors, cleanups, and config-only tasks don't require RED pairing — but if behavior changes, the RED comes first.
 
 ### Integration-Aware Task Principle
 
@@ -153,11 +187,23 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
 - **Cleanup tasks**: Remove/redirect old code paths (MANDATORY when replacing patterns)
 
 ### 4b. Create Parent Tasks
-- **Action** — CreateParentTasks: Draft as many phases as needed to logically organize work, each with as many parent tasks (📋) as required to cover complete scope.
+- **Action** — CreateParentTasks: Draft as many phases as needed to logically organize work, each with as many parent tasks as required to cover complete scope.
   - Each parent task = single cohesive deliverable (small-medium scope)
   - Cover ALL extracted requirements with no gaps
   - Group related work into phases for clarity
   - Align with technical approach (from research or existing docs)
+  - Every parent task carries explicit sequencing in its body:
+    - **Predecessor**: parent task IDs that must complete first (or "none")
+    - **Unblocks**: parent task IDs this unblocks (or "terminal")
+  - The first phase is always **Phase 0 — Dependency Verification** (see 4a-Phase0 below). Other phases start at Phase 1.
+
+### 4a-Phase0. Phase 0 — Dependency Verification (always present)
+
+Before any implementation, generate a Phase 0 containing one sub-task per external dependency listed in `plan.md`'s "External Dependencies — Verify Before Implementation" section. Each sub-task verifies the package exists at the named version and exposes the API the plan assumed.
+
+- Acceptance type: state condition (`npm view <pkg>@<ver>` returns valid metadata) and/or test passes (a minimal import-and-call smoke test).
+- If `plan.md` declared "no new packages," Phase 0 is a single sub-task that confirms no new dependencies were silently introduced during implementation (cross-check `package.json` diff at end).
+- Phase 0 unblocks Phase 1; it cannot be skipped or run in parallel with Phase 1.
 
 ### 4c. Break Down Sub-tasks
 - **Action** — BreakdownSubTasks: For each parent, generate as many detailed sub-tasks as needed to complete the parent.
@@ -171,14 +217,19 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
     - Completable as a single focused change
 
   - **What to INCLUDE in sub-tasks:**
-    - ✅ Technical terms (JWT, REST, WebSocket, React hooks, SQL queries)
-    - ✅ Architecture patterns (middleware, pub/sub, observer, factory)
-    - ✅ Integration points (which components connect, API contracts)
-    - ✅ File/component names (UserProfileComponent, authMiddleware.ts)
-    - ✅ Technical constraints (max file size, timeout duration, data format)
-    - ✅ **Produces**: What output this creates (variable name, return value, prop)
-    - ✅ **Consumed by**: What uses this output (component, hook, render path)
-    - ✅ **Replaces**: What old code path this supersedes (if any)
+    - Technical terms (JWT, REST, WebSocket, React hooks, SQL queries)
+    - Architecture patterns (middleware, pub/sub, observer, factory)
+    - Integration points (which components connect, API contracts)
+    - File/component names (UserProfileComponent, authMiddleware.ts)
+    - Technical constraints (max file size, timeout duration, data format)
+    - **Produces**: What output this creates (variable name, return value, prop)
+    - **Consumed by**: What uses this output (component, hook, render path)
+    - **Replaces**: What old code path this supersedes (if any)
+    - **Context** (required): a self-contained payload an executor can use without re-reading the full plan. Include:
+      - 2–4 file:line refs pulled from research (the exact code being modified or extended)
+      - 1 canonical reference pointer (a file:line from `@patterns` research that shows the shape to follow)
+      - 1 link/anchor into `plan.md` for the relevant section
+    - **Predecessor** (sub-task level, optional): a sub-task ID this depends on. Only when intra-parent ordering is non-obvious.
 
   - **What to AVOID in sub-tasks:**
     - ❌ Code snippets or pseudo-code
@@ -187,12 +238,11 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
     - ❌ Specific library API calls (unless architecturally significant)
 
   - **Acceptance criteria**:
-    - Describe technical behaviors and observable outcomes
-    - Include integration expectations and error handling
-    - 2-3 verifiable outcomes per sub-task
-    - Be specific about technical requirements
+    - Every criterion MUST be one of the three executable types (see "Acceptance Criteria Types" above): test passes / observable behavior / state condition.
+    - 2–3 criteria per sub-task. If a sub-task needs more than 3 to be checkable, split it.
+    - Prose criteria ("works correctly", "is consistent", "user-friendly") are forbidden — they're not self-checkable.
 
-  - **Decomposition**: Split if 5+ criteria or multiple concerns
+  - **Decomposition (hard size cap)**: Split if ANY of: >3 files touched, >5 criteria, >~200 LOC, mid-task scope judgment required, or more than one concern.
 
 ### 4d. Validate Task Structure
 - **Action** — VerifyCoverage: Cross-reference tasks against extracted requirements.
@@ -204,13 +254,19 @@ Tasks without consumers are incomplete. Tasks that don't address old code paths
   - **Coverage Validation**:
     - [ ] All extracted requirements from Step 3 addressed by tasks?
     - [ ] No gaps in requirement coverage?
+    - [ ] Every "Verification" entry from `plan.md` mapped to at least one acceptance criterion?
   - **Exclusion Validation**:
-    - [ ] Adding anything beyond explicit requests?
-    - [ ] Avoiding "nice-to-have" additions not requested?
+    - [ ] No additions beyond explicit requests?
+    - [ ] `plan.md`'s "Out-of-Bounds — DO NOT add" list carried forward verbatim into tasks.md banner?
+    - [ ] No task implements anything in the Out-of-Bounds list?
   - **Structure Validation**:
     - [ ] Parent tasks are small-medium scope, sub-tasks are atomic?
-    - [ ] Each sub-task has 2-3 acceptance criteria?
-    - [ ] Acceptance criteria verifiable (not implementation steps)?
+    - [ ] Each sub-task has 2-3 acceptance criteria, each one of the three executable types?
+    - [ ] No sub-task exceeds the size cap (>3 files / >5 criteria / >~200 LOC / multi-concern / mid-task scope judgment)?
+    - [ ] Every behavior-changing sub-task is preceded by a RED test sub-task?
+    - [ ] Every sub-task has a Context payload (2–4 file:line refs, 1 canonical reference, 1 plan.md anchor)?
+    - [ ] Every parent task has Predecessor and Unblocks declared?
+    - [ ] Phase 0 — Dependency Verification is present and unblocks Phase 1?
 
 - **Action** — ValidateIntegration: Verify every build task is wired to consumers.
   - **Consumer Specified**:
@@ -288,6 +344,13 @@ Save to `${TASKS_FILE}`:
 - **In Scope**: {bullet list}
 - **Out of Scope**: {bullet list}
 
+## Out-of-Bounds — DO NOT add
+*Carried forward verbatim from plan.md. Executors: if a task tempts you to add any of these, stop and ask.*
+- {Forbidden addition 1, e.g. "rate limiting"}
+- {Forbidden addition 2, e.g. "retry/backoff"}
+- {Forbidden addition 3, e.g. "telemetry events"}
+- {Forbidden addition 4, e.g. "admin UI"}
+
 ## Requirements Traced
 | ID | Description | Source | Tasks |
 |----|-------------|--------|-------|
@@ -315,30 +378,66 @@ Save to `${TASKS_FILE}`:
 
 ## Tasks
 
+### Phase 0: Dependency Verification
+*Confirms every external dependency in plan.md exists at the declared version before any implementation begins.*
+
+#### [0.1] Verify external dependencies
+- **Predecessor**: none
+- **Unblocks**: 1.1
+- [ ] **0.1.1** Verify each package@version from plan.md "External Dependencies" section exists
+  - **Produces**: confirmation log of resolved package metadata
+  - **Consumed by**: Phase 1 implementation tasks
+  - **Context**:
+    - plan.md anchor: `## External Dependencies — Verify Before Implementation`
+    - check commands listed in plan section
+  - [ ] State condition: `npm view <pkg>@<ver>` returns valid metadata for every package
+  - [ ] State condition: no package in the list is flagged as deprecated or security-advised
+  - [ ] Test passes: minimal import-and-call smoke for each new package
+
 ### Phase 1: {Phase Name}
 
 #### [1.1] {Parent Task Title}
-- [ ] **1.1.1** {Sub-task with technical specifics}
+- **Predecessor**: 0.1
+- **Unblocks**: 1.2
+
+- [ ] **1.1.1 RED** Write failing test `{test_name}` asserting `{behavior}`
+  - **Produces**: a failing test that pins the desired behavior
+  - **Consumed by**: 1.1.2 (turns this red to green)
+  - **Replaces**: N/A
+  - **Context**:
+    - `path/to/existing/code.ts:42` — current behavior being changed
+    - `path/to/similar/test.ts:18` — canonical test shape to follow
+    - plan.md anchor: `### Verification — How We Know This Works`
+  - [ ] State condition: file `path/to/test.ts` exists and contains test `{test_name}`
+  - [ ] Test passes: the new test fails, with failure message referencing the unimplemented behavior
+
+- [ ] **1.1.2 Build** {Implement the change}
   - **Produces**: {output variable/value/prop}
   - **Consumed by**: {component/hook that uses this}
   - **Replaces**: {old code path, or "N/A" if new}
-  - [ ] {Technical outcome 1}
-  - [ ] {Technical outcome 2}
-  - [ ] {Technical outcome 3}
-
-- [ ] **1.1.2** {Sub-task with technical specifics}
-  - **Produces**: {output variable/value/prop}
-  - **Consumed by**: {component/hook that uses this}
-  - [ ] {Technical outcome 1}
-  - [ ] {Technical outcome 2}
+  - **Context**:
+    - `path/to/file.ts:120` — code to modify
+    - `path/to/file.ts:180` — adjacent code that must not regress
+    - `path/to/canonical/example.ts:55` — pattern to follow (from @patterns research)
+    - plan.md anchor: `## Technical Approach`
+  - [ ] Test passes: `{test_name}` (from 1.1.1) now passes
+  - [ ] Test passes: existing tests in `path/to/related.test.ts` still pass
+  - [ ] Observable behavior: `{specific runtime signal, e.g. log line, HTTP response shape}`
 
 #### [1.2] {Parent Task Title} — Integration
-*This task wires outputs from 1.1 to consumers*
-- [ ] **1.2.1** {Wire X to Y}
-  - **Wires**: {1.1.1 output} → {consumer component/render}
+- **Predecessor**: 1.1
+- **Unblocks**: {next parent or "terminal"}
+
+- [ ] **1.2.1** Wire {1.1.2 output} to {consumer}
+  - **Wires**: {1.1.2 output} → {consumer component/render}
   - **Removes**: {old code path being replaced}
-  - [ ] {Consumer uses new data source}
-  - [ ] {Old data source removed/redirected}
+  - **Context**:
+    - `path/to/consumer.tsx:30` — where the wire lands
+    - `path/to/old/path.ts:12` — old code path to remove
+    - plan.md anchor: `### Technical Approach`
+  - [ ] Test passes: integration test asserting consumer renders new data source
+  - [ ] State condition: old code path file `path/to/old/path.ts` deleted or import removed
+  - [ ] Observable behavior: data flows from producer to rendered output (with `{specific assertion}`)
 
 ### Phase 2: {Phase Name}
 ...

package/plugins/spectre/skills/guide/SKILL.md

@@ -94,7 +94,7 @@ This is how the creator of SPECTRE uses it daily:
 ### Building a Feature (the main loop)
 
 1. **`/spectre:scope`** — Get crisp on what's in/out. Non-negotiable unless it's a one-liner.
-   - If UX is unclear: run `/spectre:ux_spec` first for user flows and components
+   - If UX is unclear: run `/spectre:ux` first for user flows and components
 
 2. **`/spectre:plan`** — Build a well-researched technical design or task set
    - Once you have scope/plan/tasks, run `/spectre:handoff` for a fresh context window
@@ -147,7 +147,7 @@ Brain dump context, walk away, review the PR. Zero confirmation gates — scope,
 | `/spectre:scope` | Starting any new feature — interactive scoping with IN/OUT boundaries |
 | `/spectre:kickoff` | High-ambiguity projects — includes web research for best practices |
 | `/spectre:research` | Need deep codebase understanding before planning |
-| `/spectre:ux_spec` | UI-heavy features that need screen layouts, user flows, component states |
+| `/spectre:ux` | UI-heavy features that need screen layouts, user flows, component states |
 
 ### Phase: Plan — Research & Task Breakdown
 
@@ -213,7 +213,7 @@ Brain dump context, walk away, review the PR. Zero confirmation gates — scope,
 -> `/spectre:scope` (always start here unless it's trivial)
 
 **Feature has complex UI?**
--> `/spectre:ux_spec` after scope, before plan
+-> `/spectre:ux` after scope, before plan
 
 **High ambiguity / new project?**
 -> `/spectre:kickoff` (includes web research)
@@ -283,7 +283,7 @@ SPECTRE generates these documents in `docs/tasks/{branch_name}/`:
 | Document | Generated By | Purpose |
 |----------|-------------|---------|
 | `concepts/scope.md` | `/spectre:scope` | What's IN and OUT |
-| `specs/ux.md` | `/spectre:ux_spec` | User flows, components, interactions |
+| `specs/ux.md` | `/spectre:ux` | User flows, components, interactions |
 | `specs/plan.md` | `/spectre:create_plan` | Technical design and phasing |
 | `specs/tasks.md` | `/spectre:create_tasks` | Concrete tasks with acceptance criteria |
 | `reviews/code_review.md` | `/spectre:code_review` | Severity-based code review findings |

package/plugins/spectre/skills/plan/SKILL.md

@@ -49,9 +49,11 @@ Treat the current command arguments as this workflow's input. When invoked from
   - `OUT_DIR=docs/tasks/{branch_name}` (or user-specified)
   - `mkdir -p "${OUT_DIR}"`
 
-- **Action** — ScanExistingContext: Read all existing artifacts in `{OUT_DIR}/ (if you haven’t already)` and assess coverage across 4 dimensions.
+- **Action** — ScanExistingContext: Read all existing artifacts in `{OUT_DIR}/ (if you haven't already)` and assess coverage across 4 dimensions.
 
-  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `research/*.md`
+  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `specs/ux.md`, `research/*.md`
+
+  While scanning `concepts/scope.md` and `specs/ux.md`, extract any **filled assumptions** — places where the upstream artifact defaulted a value because the user didn't specify (e.g., DB choice, retry policy, copy variants, segment fallbacks). Carry these forward to Step 3's design surface so they're reviewer-visible before plan generation.
 
   | Dimension | Covered if artifact contains... | Covered by |
   | --- | --- | --- |
@@ -95,13 +97,26 @@ Use research findings from Step 1 to determine appropriate planning depth.
   | Integration points | Research findings | Internal only = Low, 1-2 external = Med, 3+ external = High |
   | External complexity | @web-research | Well-documented with libraries = Low, Some prior art = Med, Novel/emerging = High |
 
-- **Action** — CheckHardStops: Any true = automatic COMPREHENSIVE | db_schema_destructive | new_service_or_component | auth_or_pii_change | | payment_billing_logic | public_api_change | caching_consistency | slo_sla_risk |
+- **Action** — CheckHardStops: Any true = automatic COMPREHENSIVE.
+  - `db_schema_destructive` — drops, renames, or non-additive column changes
+  - `data_migration_required` — backfill, transform, or row-by-row data change
+  - `new_service_or_component` — net-new service, daemon, or top-level component
+  - `auth_or_pii_change` — authn/authz flow, session handling, PII storage/exposure
+  - `secrets_or_credentials_handling` — new secret introduced, rotation, or boundary change
+  - `payment_billing_logic` — money flow, invoicing, charge logic
+  - `public_api_change` — externally-consumed API surface modified
+  - `concurrent_writes_or_locking` — concurrency, locking, or distributed coordination
+  - `caching_consistency` — cache invalidation, staleness windows, multi-tier caching
+  - `cross_service_or_cross_workspace_change` — coordinated change across services or workspaces
+  - `slo_sla_risk` — latency, throughput, or availability budget at stake
+
+- **Action** — DetermineTier (decisive rules, not point-scoring):
 
-- **Action** — DetermineTier:
+  - **COMPREHENSIVE** — if ANY hard-stop is triggered OR any signal scores High OR two or more signals score Medium
+  - **STANDARD** — if no hard-stops AND no High signals AND at most one Medium signal
+  - **LIGHT** — only if every signal scores Low AND no hard-stops AND the change is plausibly a single-file diff
 
-  - **LIGHT**: All/most Low signals, single component, clear pattern match, no hard-stops
-  - **STANDARD**: Mix of Low/Med signals, multi-file but contained scope, no hard-stops
-  - **COMPREHENSIVE**: Any High signal, multiple Med signals, or any hard-stop triggered
+  When in doubt between two tiers, choose the higher. The cost of over-planning a small change is hours; the cost of under-planning a large one is weeks.
 
 - **Action** — LogTier: Note the assessed tier in your response for transparency, then proceed immediately to the next step. Do NOT ask for confirmation.
 
@@ -129,6 +144,14 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
   > - [decision] — [rationale; alternative considered]
   > - [decision] — [rationale; alternative considered]
   >
+  > **How we'll know it works** (verification spine):
+  > - [change] → [test name | observable behavior | state condition]
+  > - [change] → [test name | observable behavior | state condition]
+  >
+  > **Filled assumptions** (surfaced from scope.md / ux.md / inferred):
+  > - [assumption] — *source: [scope.md / ux.md / default]*
+  > - [assumption] — *source: [scope.md / ux.md / default]*
+  >
   > **Open questions** (with default assumption):
   > 1. [question] — *default: [assumption]*
   > 2. [question] — *default: [assumption]*
@@ -138,6 +161,8 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
   **CRITICAL**:
   - **Single proposed approach**, not a menu. If a true fork exists, surface it as an open question with your recommendation — not as parallel options.
   - Stay at the *shape* level: components, key decisions, structural changes. Defer file-by-file detail to `create_plan`.
+  - **Verification is mandatory.** Every major change in the approach must declare how it will be checked — falsifiable signal, not prose. This becomes the spine that `create_plan` and `create_tasks` build on.
+  - **Filled assumptions are mandatory.** If scope.md or ux.md left something silent and you defaulted it, surface the default here. Reviewer-visible by design — these are the silent decisions that bite at execution.
   - Open questions should be specific and answerable; pair each with a default assumption so the user can skip if the default is fine.
 
 - **Action** — IterateDesign: If the user replies with answers, edits, or pushback, update the design and re-present. Loop until user says 'looks good' (or equivalent).
@@ -208,4 +233,24 @@ Goal: align on the *shape* of the solution before generating a full plan. This c
 
 ---
 
+### Post-Tasks Tier Re-check
+
+After tasks return, do a fast self-check against tier signals:
+
+- Count parent tasks, sub-tasks, files touched (sum of unique paths in Context blocks), and Phase 0 dep count.
+- **Escalation triggers** (any true → recommend re-running at a higher tier):
+  - Tier was LIGHT but tasks touch >3 files OR have >2 parent tasks
+  - Tier was STANDARD but tasks reveal a hard-stop signal not caught earlier (e.g., a migration sub-task appeared)
+  - Tasks contain any Out-of-Bounds violation
+- **Downgrade triggers** (rare; only suggest if confident):
+  - Tier was COMPREHENSIVE but tasks collapsed to a single parent with no migrations, no new components, and no API change
+
+If an escalation/downgrade is triggered, surface it as a recommendation — do NOT silently re-run. Format:
+
+> Tier reassessment: I planned this as {original tier}, but tasks revealed {signal}. Recommend re-running as {new tier}. Reply 'rerun' to regenerate or 'keep' to proceed as-is.
+
+Only proceed past this checkpoint when the user confirms.
+
+---
+
 - **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps