@codename_inc/spectre 4.0.0 → 5.1.0

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

@@ -1,6 +1,6 @@
 ---
 name: plan_review
-description: 👻 | Find simplifications in a plan or tasks
+description: 👻 | Independent multi-lens review of plan.md + tasks.md — finds overengineering, missing verification, hallucinated deps, weak references
 user-invocable: true
 ---
 
@@ -10,33 +10,174 @@ user-invocable: true
 
 Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
 
+# plan_review: Multi-Lens Review of Plan & Tasks
 
-You are a senior staff engineer with deep expertise in system design, architecture, and pragmatic problem-solving. Your specialty is finding the simplest path to meet all requirements.
+## Description
 
-Review the following [plan/document/tasks/context] and identify opportunities to simplify while ensuring all requirements and functionality are delivered.
+- **What** — Independent review of `plan.md` + `tasks.md` from four specialized lenses, dispatched in parallel
+- **Outcome** — Structured findings with concrete edit suggestions; optional write-back to update both artifacts
+- **Role** — Senior staff engineer + reviewer panel; bias toward pragmatic problem-solving, YAGNI enforcement, and verifiability
 
-For each simplification opportunity, provide:
-1. **What to simplify** - Specific component, process, or decision
-2. **Why** - What complexity it removes (cognitive load, dependencies, maintenance burden, etc.)
-3. **Impact** - Confirm that all original requirements remain satisfied
-4. **Risk** - Any trade-offs or risks introduced by the simplification
+## ARGUMENTS Input
 
-Focus on:
-- Removing unnecessary abstractions or indirection
-- Consolidating duplicated logic or patterns
-- Questioning assumptions that add complexity
-- Identifying over-engineering
-- Suggesting proven, boring solutions over novel approaches
+<ARGUMENTS>
+$ARGUMENTS
+</ARGUMENTS>
 
-## Testing Review
-**Context**: We use fast TDD with 1 happy path test + 1 unhappy path test per feature. A separate task handles achieving 100% test coverage post-feature work.
+## Why Four Lenses
 
-Evaluate the testing approach and flag:
-- **Over-testing**: Tests beyond 1 happy + 1 unhappy path that should be deferred to the coverage task
-- **Wrong tests**: Testing implementation details instead of behavior, brittle tests that will break on refactors, or tests that don't actually validate requirements
-- **Missing critical paths**: Cases where the 1+1 approach genuinely misses a requirement-breaking scenario (rare, but call it out)
-- **Test complexity**: Overly elaborate test setup, mocking, or assertions that could be simpler
+A single reviewer biases toward the issues it notices first. Published practice (Cognition, Anthropic, Osmani) converges on four high-yield review angles for AI-agent-authored plans. We dispatch each as a parallel subagent so coverage is structurally guaranteed, not dependent on a single reviewer remembering everything.
 
-Remember: The goal is fast feedback during development. More comprehensive testing comes later.
+| Lens | Subagent | Finds |
+|------|----------|-------|
+| **YAGNI / familiar-shape bias** | `@reviewer` | Mature-system patterns that crept in unprompted (auth → rate-limit, CRUD → soft-delete, etc.). Forces ONE "delete this" recommendation. |
+| **Verifiability** | `@analyst` | Acceptance criteria that aren't executable; verification gaps between plan and tasks. |
+| **Existence / hallucination** | `@finder` | File paths, packages, APIs, or symbols referenced that don't actually exist. The slopsquatting fence. |
+| **Canonical reference quality** | `@patterns` | "Follow existing pattern" claims without a real file:line anchor; missed reuse opportunities. |
 
-End with a prioritized list of recommendations (high/medium/low impact).
+## Step 1 — Locate Artifacts
+
+- **Action** — DetermineTaskDir:
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - **If** user specifies path in ARGUMENTS → `TASK_DIR={that value}`
+  - **Else** → `TASK_DIR=docs/tasks/{branch_name}`
+
+- **Action** — ResolveArtifacts: Locate the three required inputs.
+  - `PLAN=${TASK_DIR}/specs/plan.md` (or scoped name)
+  - `TASKS=${TASK_DIR}/specs/tasks.md` (or scoped name)
+  - `CONTEXT=${TASK_DIR}/task_context.md`
+  - 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.
+
+- **Action** — ReadAll: Read each file completely into context before dispatching reviewers. Reviewers receive curated excerpts, not raw paths.
+
+## Step 2 — Dispatch Four Parallel Reviewers
+
+Spawn all four subagents in a single message (parallel). Each receives the same artifact excerpts but a different review brief.
+
+### Lens 1 — YAGNI / Familiar-Shape Bias (`@reviewer`)
+
+> 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.
+>
+> Find:
+> 1. Anything in `plan.md` Technical Approach that isn't traceable to a requirement in `task_context.md` / scope / PRD.
+> 2. Tasks in `tasks.md` that implement something the requirements don't ask for.
+> 3. Abstractions, interfaces, or layers introduced for a single concrete caller.
+> 4. Generality (config files, plugin points, factories) where the actual need is one specific behavior.
+> 5. Overlap with the `Out-of-Bounds — DO NOT add` list (if anything violates that list, it's a hard fail).
+>
+> 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.
+
+### Lens 2 — Verifiability (`@analyst`)
+
+> 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.
+>
+> Find:
+> 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).
+> 2. Phases in `plan.md` that don't declare a verification signal.
+> 3. Sub-tasks in `tasks.md` whose acceptance criteria aren't one of the three executable types (test passes / observable behavior / state condition).
+> 4. Verification signals in `plan.md` with no matching acceptance criterion in `tasks.md`.
+> 5. Behavior-changing sub-tasks in `tasks.md` that lack a preceding RED test sub-task.
+>
+> Required output: list every non-executable criterion with a proposed rewrite in one of the three types. Cite file:line for each.
+
+### Lens 3 — Existence / Hallucination (`@finder`)
+
+> 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.
+>
+> Verify:
+> 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.
+> 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.)
+> 3. Every function, class, or symbol named in plan/tasks — grep the repo, confirm it exists where claimed.
+> 4. Every API endpoint, env var, or CLI flag referenced — confirm it's defined in the codebase.
+>
+> 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.
+
+### Lens 4 — Canonical Reference Quality (`@patterns`)
+
+> 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.
+>
+> Find:
+> 1. Places in `plan.md` Technical Approach that reference "existing patterns" or "similar features" without a specific file:line.
+> 2. Sub-tasks in `tasks.md` whose Context block lacks a canonical reference pointer.
+> 3. Better canonical references that the plan missed — actual files in the codebase that more closely match the intended shape.
+> 4. Reuse opportunities the plan ignored: utilities, hooks, helpers, or types already in the repo that the plan re-implements.
+>
+> Required output: for each weak/missing reference, propose a specific file:line that should be the anchor. For each missed reuse, cite the existing utility and which task should use it.
+
+## Step 3 — Synthesize Findings
+
+- **Action** — CollectFindings: Wait for all four reviewers to return. Read every finding.
+
+- **Action** — DeduplicateAndPrioritize: Merge findings that overlap (e.g., a missing canonical reference may surface from both Lens 4 and Lens 2). Assign severity:
+  - **Blocker** — would cause execution to fail or produce wrong output (hallucinated file path, criterion the executor can't check, Out-of-Bounds violation)
+  - **High** — meaningfully reduces output quality (missing RED test, weak canonical reference, prose criterion)
+  - **Medium** — overengineering or reuse miss without functional blast radius
+  - **Low** — stylistic or nice-to-have
+
+- **Action** — RenderFindingsTable: Output a single structured table. Schema is fixed.
+
+  ```markdown
+  ## Review Findings — {feature name}
+
+  ### Must-Delete (Lens 1 — YAGNI)
+  > {The single nominated highest-leverage cut, with rationale.}
+
+  ### Findings
+
+  | # | Severity | Lens | Location | Finding | Suggested Edit |
+  |---|----------|------|----------|---------|----------------|
+  | 1 | Blocker  | Existence | plan.md `## External Dependencies` | `react-use-undocumented@2.4.0` doesn't exist on npm | Remove; the plan can use `useReducer` from React stdlib (see `src/hooks/useFormState.ts:18`) |
+  | 2 | High     | Verifiability | tasks.md `1.2.1` | "Component renders correctly" is prose | Replace with: Test passes `<ProductCard /> renders product.title and product.price` |
+  | 3 | High     | YAGNI | plan.md `## Technical Approach` | Adds retry-with-backoff for a sync internal call | Delete; not in requirements; Out-of-Bounds list already forbids retry logic |
+  | … |          |       |          |         |                |
+
+  ### Summary
+  - Blockers: {N} — must resolve before /execute
+  - High: {N}
+  - Medium: {N}
+  - Low: {N}
+  ```
+
+## Step 4 — Surface Findings & Apply Edits
+
+- **Action** — PresentFindings: Render the findings table inline.
+
+- **Action** — OfferWriteBack: After the table, prompt:
+
+  > Reply with which findings to apply:
+  > - `all` — apply every suggested edit
+  > - `blockers` — apply Blocker + High severity only
+  > - `1,3,5` — apply specific finding numbers
+  > - `skip` — leave artifacts unchanged
+  >
+  > For findings I apply, I'll edit plan.md and/or tasks.md inline and re-run a fast self-check.
+
+- **Wait** — User selects.
+
+- **Action** — ApplyEdits: For each selected finding:
+  - Open the named artifact (plan.md or tasks.md)
+  - Apply the Suggested Edit verbatim where possible; if the edit needs adaptation, make the minimum change consistent with the finding's intent
+  - Track which findings were applied
+
+- **Action** — SelfCheck: After edits, run a fast pass over the modified sections:
+  - Re-verify any file:line refs touched
+  - Re-verify acceptance criteria are still executable
+  - Confirm no edit introduced a new Out-of-Bounds violation
+  - If any check fails, surface it and ask the user before continuing
+
+- **Action** — ReportApplied:
+
+  > Applied: {list of finding numbers}. Skipped: {list}.
+  > {Path to updated plan.md and tasks.md}.
+
+## Step 5 — Next Steps
+
+- **Action** — RenderFooter: Use `@skill-spectre:spectre-guide` skill for Next Steps footer.
+
+---
+
+## Notes
+
+- 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.
+- The four lenses are intentionally non-overlapping by design but will surface overlap in practice — dedupe at synthesis, don't ask reviewers to coordinate.
+- 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/skills/prototype/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: prototype
+description: 👻 | Generate a self-contained HTML prototype to validate a feature visually before planning - primary agent
+user-invocable: true
+---
+
+# prototype
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# prototype: Make the Feature Visible Before You Plan It
+
+Produce a self-contained, clickable HTML artifact that makes a feature visible — resolving ambiguity before scope, validating flows before plan, or anchoring stakeholder review. Output: single portable HTML file the user can open locally or host anywhere, saved to `{OUT_DIR}/prototypes/{name}_{MMDDYY}.html`.
+
+## ARGUMENTS
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## Invocation Modes
+
+Detect mode from environment markers, ARGUMENTS, and existing docs. **Order matters** — check from most context to least:
+
+- **Complete ux.md exists** (post-ux) — full Stage 2 spec is on disk. The prototype's job is to **render the spec**, not synthesize it. Default fidelity: **high-fi**. Skip all intake except visual anchor. Treat ux.md as authoritative — don't invent screens, don't contradict documented states or copy. On completion, recommend `/spectre:plan` or `/spectre:create_tasks`.
+- **`FROM_UX=true`** — invoked mid-flow from `ux` Stage 1 → Stage 2 gate. Only approved flows exist (no detailed spec yet). Skip flow-discovery intake. Default fidelity: **mid-fi**. On completion, point user back to `ux` Stage 2.
+- **`--explore` flag in ARGUMENTS** — pre-scope discovery. Concept is unvalidated. Default fidelity: **low-fi**. On completion, recommend `/spectre:scope` as next step.
+- **scope.md exists for this branch** (no ux.md) — post-scope validation. Default fidelity: **mid-fi**. On completion, recommend `/spectre:ux` or `/spectre:plan` based on feature complexity.
+- **Standalone, no context** — ask the user what they're prototyping. Default fidelity: **mid-fi**.
+
+---
+
+# STAGE 1: Intake & Fidelity Alignment
+
+**Goal**: Confirm what we're prototyping, at what fidelity, and what visual anchor to use. Keep this tight — 2 to 4 questions, never a form.
+
+## Step 1 — Immediate Reply & Detect Context
+
+- **Action** — ImmediateReply: Respond before any tools.
+  - **If** `FROM_UX=true` → acknowledge ux context, read approved flows from `{OUT_DIR}/ux.md`, **SKIP to Step 3**
+  - **Else If** ARGUMENTS empty → probe: "What are we prototyping? A quick description is enough — I'll figure out the fidelity from context."
+  - **Else** → proceed to Step 2
+  - **CRITICAL**: No tool calls in this step except reading ux output when `FROM_UX=true`.
+
+## Step 2 — Read Available Context & Classify ux.md
+
+- **Action** — DetectExistingDocs: Check for relevant inputs before asking the user anything.
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - Look for: `docs/tasks/{branch_name}/concepts/scope.md`, `docs/tasks/{branch_name}/specs/prd.md`, `docs/tasks/{branch_name}/ux.md`
+  - Read whichever exist FULLY (no offset/limit)
+
+- **Action** — ClassifyUxDoc: If `ux.md` exists, classify its completeness — this drives fidelity AND how much intake to skip.
+  - **Complete** — contains all of: Screens, Layouts, Components, Interactions, States, Content sections (the Stage 2 deliverables from `/spectre:ux`). Treat as authoritative. Skip flow-discovery questions. Set mode = **post-ux**.
+  - **Flows-only** — contains user flows / journeys but missing Stage 2 sections. Treat flows as approved input but expect to make UI decisions. Set mode = **flows-only ux**.
+  - **Absent** — fall back to scope.md / prd.md / standalone modes.
+
+## Step 3 — Recommend Fidelity, Confirm Anchor
+
+Pick fidelity from signals available:
+
+| Signal present | Recommends |
+|---|---|
+| `--explore` flag, or no scope/prd | **Low-fi** — grayscale, layout-only, no typography polish |
+| scope.md exists, no design system anchor | **Mid-fi** — real colors, basic type, simplified components (default) |
+| scope.md + flows-only ux.md, or brand/design system anchor | **Mid-fi to High-fi** — depends on anchor strength |
+| **Complete ux.md** (post-ux) | **High-fi** — full design tokens, realistic data, micro-interactions; render the spec faithfully |
+
+### Intake by mode
+
+**Post-ux mode** (complete ux.md) — present a tight confirmation, ask one question:
+
+> **Prototype plan** — rendering complete UX spec
+>
+> Source: `{path to ux.md}` ({N} screens, {M} components, {K} states specified)
+> Fidelity: **high-fi** (default — full spec is on disk; I'll render it faithfully, not invent)
+>
+> One thing I need: **visual anchor** — brand colors, font stack, an existing app/URL to match, or a named aesthetic (e.g. "Linear-style", "Notion-quiet", "Stripe-clean"). If the spec already specifies design tokens, reply "use the spec." If you skip this, I'll commit to a deliberate named aesthetic and call it out at the top of the file.
+
+**All other modes** — present recommendation + request anchor + confirm framing:
+
+> **Prototype plan**
+>
+> I'm reading this as: **{inferred feature/flow}**
+> Recommended fidelity: **{low-fi | mid-fi | high-fi}** — {one-line reason}
+> Primary flow: **{name}** (from {scope.md | ux.md flows | your description})
+>
+> Two things I need from you:
+> 1. **Override fidelity?** Or "looks good."
+> 2. **Visual anchor** — brand colors, font stack, an existing app/URL to match, or a named aesthetic (e.g. "Linear-style", "Notion-quiet", "Stripe-clean"). If you skip this, I'll commit to a deliberate named aesthetic and call it out at the top of the file so you can redirect.
+
+**Wait for response.** If user pushes back on fidelity or feature framing, adjust and re-confirm.
+
+---
+
+# STAGE 2: Parallel Research & Generation
+
+**Gate**: Only proceed after Stage 1 confirmation (or `FROM_UX=true`).
+
+## Step 4 — Dispatch Parallel Subagents
+
+Spawn three subagents in parallel. Each has a focused job.
+
+### `@spectre:web-research` — Visual Reference Discovery
+
+Prompt template:
+
+> Research visual design patterns and UI conventions for **{feature type}**. Specifically:
+>
+> 1. Find 2–3 living examples or screenshots of similar UI patterns in well-regarded products. Return URLs and visual descriptions.
+> 2. Identify the established UX convention for this interaction type (wizard, dashboard, list+detail, modal flow, etc.) and any recent (2025–2026) refinements.
+> 3. If the user specified an aesthetic anchor ({anchor_text}), find representative color palettes (hex), typography choices (font families with fallbacks), and one or two distinctive design moves that define the aesthetic.
+> 4. Return concrete decisions — colors, fonts, layout patterns — not general advice.
+>
+> Length: under 400 words. Cite sources.
+
+**Why**: Grounds generation in specific references. Without this step the model defaults to its own distribution (Inter + purple gradients). This is the anti-slop forcing function.
+
+### `@spectre:analyst` — Flow & Content Extraction
+
+Use one of two prompt templates based on mode detected in Step 2.
+
+**Extraction mode** — post-ux (complete ux.md present):
+
+> Read **{path to ux.md}** fully. The Stage 2 spec is authoritative — your job is to **extract** structured data for HTML rendering, NOT to synthesize new screens, states, or content.
+>
+> Return a render brief organized by ux.md section:
+>
+> 1. **Screens** — verbatim from the Screens section: name, purpose, navigation relationships
+> 2. **Layouts** — verbatim from Layouts: per-screen header/main/footer + responsive breakpoints
+> 3. **Components** — verbatim from Components: each element's purpose, location, all documented states (default, hover, active, disabled, loading, error)
+> 4. **Interactions** — verbatim from the Interactions table: Element | Action | Result
+> 5. **States** — verbatim from the States table: State | Trigger | Appearance | Available Actions
+> 6. **Content** — verbatim copy from the Content section: page titles, button labels, empty-state messages, error messages, confirmation dialogs. Use this copy EXACTLY in the prototype — do not paraphrase.
+> 7. **Edge cases & a11y** — note any documented constraints (limits, null/long data, keyboard actions, focus management) the prototype should reflect
+>
+> If the spec specifies a state or content value, the prototype must match it. If the spec is silent on a detail, flag it as a "filled assumption" so it appears in the prototype's metadata header. Never invent screens that aren't in the spec.
+
+**Synthesis mode** — flows-only ux, scope-only, or standalone:
+
+> Read these documents fully: **{list of paths — scope.md, prd.md, ux.md flows section if present}**. Extract a content skeleton for an HTML prototype:
+>
+> 1. **Primary flow** — entry → action → outcome, with decision points
+> 2. **Required UI states per screen** — every screen needs at minimum: happy path, empty state, error or edge state. Some screens also need: loading, success
+> 3. **Stated constraints** — any layout, behavior, or content constraints from the docs
+> 4. **Realistic content** — actual product names, plausible numbers, real-looking copy. NO Lorem ipsum. NO "Card Title." If domain-specific data is unclear, invent plausible values that match the feature's domain.
+> 5. **Component inventory** — every recurring UI element that will need a named CSS class (button, card, input, badge, etc.)
+>
+> Return a structured flow brief: screen list, per-screen state list, realistic content for each, component inventory.
+
+**Why**: This is the content skeleton. In post-ux mode, the spec already did this work — re-synthesizing risks contradicting documented decisions. In all other modes, skipping synthesis produces prototypes with Lorem ipsum and inconsistent component styling.
+
+### `@spectre:patterns` — Existing Codebase Anchor (only if applicable)
+
+Skip this agent if there is no existing app to anchor to. Otherwise:
+
+> Find existing UI patterns in this codebase that the prototype should match or extend: design tokens (colors, spacing, type), component conventions (button styles, card layouts), and any established interaction patterns. Return file references with the actual values (hex codes, class names, etc.) — not just paths.
+
+**Why**: When prototyping inside an existing app, the prototype should look like a plausible new screen of that app, not a designer's blank canvas.
+
+## Step 5 — Generate the HTML Artifact
+
+Wait for ALL subagents to complete. Synthesize their outputs, then generate a single self-contained HTML file. Use `@spectre:dev` to produce the file (or inline if the synthesis is straightforward).
+
+### Hard constraints on the generated HTML
+
+**File structure** (every prototype includes these in order):
+
+1. **`<!DOCTYPE html>` + minimal `<head>`** with `<meta viewport>` and an inline `<style>` block
+2. **Metadata comment block** at the very top of `<head>`:
+   ```html
+   <!--
+     SPECTRE PROTOTYPE
+     Feature: {feature name}
+     Fidelity: {low-fi | mid-fi | high-fi}
+     Generated: {YYYY-MM-DD}
+     Branch: {branch_name}
+     Flow covered: {primary flow}
+     Screens/states: {comma-separated list}
+     Visual anchor: {named aesthetic or reference URL}
+     Source spec: {path to ux.md if post-ux mode, else "none — synthesized from {scope.md | description}"}
+     Key assumptions: {bullet list of design decisions and content assumptions}
+     Filled assumptions: {only in post-ux mode — items the spec was silent on that the prototype filled in; review these against the spec}
+     NOT included: {explicit list of what was deliberately left out}
+     Next step: /spectre:plan  OR  resume /spectre:ux Stage 2
+   -->
+   ```
+3. **Design tokens comment block** in `<head>`:
+   ```html
+   <!-- DESIGN TOKENS
+     Primary: #{hex}
+     Accent: #{hex}
+     Surface: #{hex}
+     Text: #{hex}
+     Font: {family}, served from {CDN or system}
+     Border-radius: {value}
+     Spacing unit: {value}
+   -->
+   ```
+   Also encode these as CSS custom properties on `:root` so they're reusable in the stylesheet.
+4. **Navigation bar** (only if multi-screen) — vanilla JS section toggling via `display:block/none`. No routing, no framework.
+5. **One `<section>` per screen.** Every screen must include the happy path AND at least one of: empty state, error state, loading state. Skipping these is the most common prototype failure mode.
+6. **Inline `<script>`** at end of body for interactions (tab switching, form submit interception, modal toggle, accordion). Vanilla JS only.
+
+**Size budget**: under 300KB. No base64 photos. No Chart.js or other large libraries. Use inline SVG and CSS-drawn shapes for any illustrations. Tailwind via CDN is acceptable for mid/high-fi; skip for low-fi.
+
+**Asset rules** (keep the file portable so users can open locally, email it, host on a gist, or push to any static host):
+- No `<img src="https://...">` that can 404 — use inline SVG, data URIs, or CSS shapes
+- No local relative paths (`./image.png`, `../style.css`) — they break the moment the file moves
+- Fonts: Google Fonts CDN (single family, two weights max) or system fonts. No custom WOFF files.
+
+### Negative constraints (embed these explicitly in the @spectre:dev prompt)
+
+When delegating to `@spectre:dev`, the prompt MUST include these as forbidden patterns:
+
+- **No generic AI aesthetic.** Do not use Inter or Roboto by default. Do not use purple gradients on white. Commit to a named, deliberate aesthetic and call it out in the metadata.
+- **No Lorem ipsum or placeholder filler.** All text must be realistic for the domain. "Card Title", "User Name", "Description goes here" are forbidden.
+- **No happy-path-only screens.** Every screen must show at least one non-happy state (empty, error, or edge).
+- **No broken interactivity.** Every `onclick`, `<form>`, or interactive element must respond visually. No `href="#"` that causes page jumps. No event handlers that throw console errors.
+- **No external image dependencies that can break.** Inline SVG only.
+- **No inconsistent component instances.** Define every recurring component as a named CSS class ONCE and reuse it. Do not re-style inline. If a card appears five times, it uses the same class five times.
+- **No page-thinking when flow-thinking is required.** Screens appear in the order a user encounters them, not in the order they're easy to build.
+- **No file-size bloat.** No base64 photos. No Chart.js, D3, or other heavyweight libraries. SVG and CSS only.
+
+### Output location
+
+- **Action** — DetermineOutputDir:
+  - `branch_name=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)`
+  - **If** `FROM_UX=true` or `FROM_KICKOFF=true` → use the existing task directory
+  - **Else If** user specifies path → use that
+  - **Else** → `OUT_DIR=docs/tasks/{branch_name}`
+  - `mkdir -p "$OUT_DIR/prototypes"`
+
+- **Action** — SaveArtifact: Write file to `{OUT_DIR}/prototypes/{feature_slug}_{MMDDYY}.html`
+
+## Step 6 — Self-Check Portability
+
+Before reporting completion, sanity-check the artifact against the portability rules:
+
+- File size under 300KB
+- No `<img src="http...">` external images
+- No local relative paths (`./`, `../`, `/local/`)
+- All recurring components share a named CSS class (no inline-styled duplicates)
+- Every screen includes at least one non-happy state
+
+Surface any violations as caveats in the handoff. Don't silently ship a broken portable file.
+
+## Step 7 — Present & Handoff
+
+- **Action** — PresentForReview:
+
+  > **Prototype complete**: `{path}` ({size} KB, {N} screens, {fidelity})
+  >
+  > **Visual anchor**: {named aesthetic}
+  > **Key assumptions made** (also embedded in file header):
+  > - {bullet 1}
+  > - {bullet 2}
+  > - {bullet 3}
+  > **NOT included**: {explicit list}
+  >
+  > Open the file in a browser to review (`open {path}` on macOS, or drag into any browser tab). The file is fully self-contained — share it however you like (email, gist, static host, etc.). Reply with feedback to iterate, or pick a next step below.
+
+- **Action** — SurfaceFilledAssumptions (post-ux mode only): If `mode = post-ux` AND any filled assumptions exist (items the spec was silent on that the prototype filled in), append a closing-the-loop block:
+
+  > **Filled assumptions** — ux.md was silent on these; I made calls to render the spec. Review and tell me which to promote into the spec:
+  >
+  > 1. {assumption} → I chose **{decision}** ({why, one line})
+  > 2. {assumption} → I chose **{decision}** ({why, one line})
+  > 3. {assumption} → I chose **{decision}** ({why, one line})
+  >
+  > Reply with numbers to update ux.md (e.g. `1, 3`), `all` to add all, or `skip` to leave the spec as-is.
+
+  If user picks updates:
+  - Edit `ux.md` directly: place each chosen item in the appropriate section (Components / States / Content / Edge Cases / Interactions).
+  - Re-run the Step 6 portability check (no regen needed unless user also requested HTML changes).
+  - Re-present with a one-line diff per added item: `ux.md ← added: {item} (in {section})`.
+
+- **Action** — RenderFooter: Render Next Steps using `@skill-spectre:spectre-guide` skill, with mode-specific recommendation:
+  - **If `FROM_UX=true`** → recommend: "Resume `/spectre:ux` Stage 2 with this prototype as input"
+  - **If `--explore`** → recommend: `/spectre:scope` with the prototype as anchor
+  - **If post-scope** → recommend: `/spectre:ux` (if flows still need detail) or `/spectre:plan` (if ready to build)
+  - **Else** → standard Next Steps options
+
+---
+
+## Iteration Loop
+
+If the user replies with feedback after Step 7:
+- Small visual tweaks (color, copy, layout) → edit the HTML directly
+- Structural changes (add screen, change flow) → re-run Step 4 subagents with the deltas and regenerate
+- **Spec contradicts prototype** (post-ux mode) → ask which is authoritative for each contradiction, then update ux.md AND the HTML together so they stay paired; re-run Step 6 portability check
+- After any edit, re-run the Step 6 self-check before re-presenting
+
+---
+
+## Success Criteria
+
+- [ ] Immediate reply sent; mode detected (FROM_UX, --explore, post-scope, or standalone)
+- [ ] Existing context docs (scope.md, prd.md, ux.md) read FULLY before asking questions
+- [ ] Fidelity recommended with rationale; user confirmed or overrode
+- [ ] Visual anchor captured (named aesthetic or reference) — never left as generic default
+- [ ] Three subagents dispatched in parallel: web-research (references), analyst (flow + content), patterns (existing codebase anchor, if applicable)
+- [ ] ALL subagents completed before generation
+- [ ] HTML artifact is single self-contained file under 300KB
+- [ ] Metadata comment block at top of `<head>` includes feature, fidelity, assumptions, NOT-included list
+- [ ] Design tokens block present and encoded as CSS custom properties on `:root`
+- [ ] Every screen includes happy path + at least one non-happy state (empty, error, or edge)
+- [ ] No Lorem ipsum, no placeholder filler — realistic domain content throughout
+- [ ] No external image dependencies (inline SVG only)
+- [ ] All recurring components use a single named CSS class (no inline re-styling)
+- [ ] All interactive elements respond visually; no console errors; no `href="#"` jump links
+- [ ] Saved to `{OUT_DIR}/prototypes/{slug}_{MMDDYY}.html`
+- [ ] Portability self-check run (size, external images, relative paths, component reuse, state coverage); violations surfaced as caveats
+- [ ] (post-ux mode only) Filled assumptions surfaced in chat with offer to update ux.md; selected items written to ux.md with diff summary
+- [ ] Next Steps footer rendered with mode-appropriate recommendation