@codename_inc/spectre 3.7.0 → 5.0.0

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

@@ -0,0 +1,211 @@
+---
+name: "plan"
+description: "👻 | Unified planning entry point - researches, assesses complexity, routes to workflow - primary agent"
+user-invocable: true
+---
+
+# plan
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# plan: Intelligent Planning Router
+
+## Description
+
+- **What** — Research codebase, assess complexity, route to appropriate workflow (direct tasks or plan-first)
+- **Outcome** — Detailed task breakdown ready for execution
+
+## ARGUMENTS Input
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## MANDATORY COMPLIANCE RULES
+
+> **⚠️ 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.
+
+**After ANY user conversation or questions:**
+
+1. Re-read this prompt from Step 4
+2. Determine where you are in the workflow
+3. Execute the next required Skill invocation
+
+**You MUST call these skills (not describe them):**
+
+- Use the **Skill** tool with `skill: "spectre-create_plan"` and `args: "{path} --depth {tier}"` — generates plan.md
+- Use the **Skill** tool with `skill: "spectre-create_tasks"` and `args: "{path}"` — generates tasks.md
+
+## Instructions
+
+- Research before routing; present architectural options for user buy-in
+- Route based on hard-stops and clarity, not point-scoring
+- Never overwrite existing `tasks.md` or `plan.md` — use scoped names
+
+## Step 1 - Research Codebase
+
+- **Action** — DetermineOutputDir:
+
+  - `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.
+
+  Scan for: `task_context.md`, `specs/plan.md`, `concepts/scope.md`, `research/*.md`
+
+  | Dimension | Covered if artifact contains... | Covered by |
+  | --- | --- | --- |
+  | **File locations** | Specific file paths relevant to this feature, entry points, config files | `@finder` |
+  | **Code understanding** | Data flow analysis, dependency tracing, how current code works with file:line refs | `@analyst` |
+  | **Codebase patterns** | Similar implementations found in codebase, reusable components, naming/style conventions | `@patterns` |
+  | **External research** | Best practices, libraries/frameworks, prior art, common pitfalls with source links | `@web-research` |
+
+  For each dimension, assess: **covered** (artifact has substantive findings for this feature) or **gap** (missing, superficial, or about a different feature).
+
+- **Action** — DispatchResearch: Spawn agents **only for dimensions marked as gaps**. Skip agents whose dimensions are already covered. Each prompt must include the feature/problem description from ARGUMENTS so the agent has full context.
+
+  - **If all 4 covered** → skip to SaveResearch (merge existing findings into task_context.md if scattered across files)
+
+  - **If gaps exist** → spawn only the needed agents in parallel:
+
+  - `@finder` *(if File locations = gap)* — "Find all files, components, entry points, routes, and configuration related to \[feature/problem\]. Include: (1) files that would need to be modified or extended, (2) entry points where this feature connects to the system (routes, handlers, event listeners, CLI commands), (3) configuration files, schemas, or migrations that may be affected, (4) test files covering the affected areas. Return file paths organized by relevance."
+
+  - `@analyst` *(if Code understanding = gap)* — "Analyze how the code paths related to \[feature/problem\] work end-to-end. Trace: (1) data flow from input through processing to storage and output, (2) key dependencies and how components interact, (3) state management patterns and data access methods in the affected areas, (4) error handling and edge cases in the current implementation. Return findings with specific file:line references."
+
+  - `@patterns` *(if Codebase patterns = gap)* — "Find existing implementations in this codebase that are similar to \[feature/problem\] and could serve as a reference. Look for: (1) analogous features already built — how were they structured?, (2) reusable components, utilities, or abstractions we should leverage, (3) conventions for naming, file organization, and code style in this area, (4) testing patterns used for similar features. Return concrete code examples with file:line references."
+
+  - `@web-research` *(if External research = gap)* — "Research best practices, proven patterns, relevant libraries/frameworks, and how other projects solve \[feature/problem\]. Focus on: (1) industry best practices and common pitfalls, (2) libraries or frameworks that simplify this work, (3) how well-known open-source projects approach similar problems, (4) architectural patterns recommended for this type of feature. Return findings with source links."
+
+  - **Wait** for all dispatched agents; read identified files
+
+- **Action** — SaveResearch: Merge all findings (existing artifacts + new agent results) into `{OUT_DIR}/task_context.md` with sections: Architecture Patterns, Dependencies, Implementation Approaches, Impact Summary, and External Research (best practices, recommended libraries/frameworks, prior art, common pitfalls)
+
+## Step 2 - Assess Complexity
+
+Use research findings from Step 1 to determine appropriate planning depth.
+
+- **Action** — AssessFromResearch: Score complexity signals from research:
+
+  | Signal | Source | Assessment |
+  | --- | --- | --- |
+  | Files impacted | @finder | 1-3 files = Low, 4-8 = Med, 9+ = High |
+  | Pattern match | @patterns | Clear existing pattern = Low, Adapt pattern = Med, New pattern = High |
+  | Components crossed | @analyst | 1 component = Low, 2-3 = Med, 4+ = High |
+  | Data model changes | Research findings | None = Low, Modify existing = Med, New models/schema = High |
+  | 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** — DetermineTier:
+
+  - **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
+
+- **Action** — LogTier: Note the assessed tier in your response for transparency, then proceed immediately to the next step. Do NOT ask for confirmation.
+
+> **CHECKPOINT**: After determining tier, proceed IMMEDIATELY to the next step — Step 3 (High-Level Design) for STANDARD/COMPREHENSIVE, or Step 4 (Route) for LIGHT. Do NOT end turn here. Do NOT ask user to confirm the tier.
+
+## Step 3 - High-Level Design
+
+**SKIP IF LIGHT** — proceed directly to Step 4.
+
+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.
+
+- **Action** — PresentDesign: Synthesize research from Step 1 into a single proposed approach with open questions. Present inline (do not write a separate design file).
+
+  **Format**:
+
+  > Here's the high-level design I'd take. Scan the shape, then resolve any open questions or push back on the approach.
+  >
+  > **Approach**: [1-2 paragraph summary of the solution shape — what changes structurally, not file-by-file]
+  >
+  > **Key components touched**:
+  > - `path/file.ts` — [what shifts and why]
+  > - `path/other.ts` — [what shifts and why]
+  >
+  > **Key decisions**:
+  > - [decision] — [rationale; alternative considered]
+  > - [decision] — [rationale; alternative considered]
+  >
+  > **Open questions** (with default assumption):
+  > 1. [question] — *default: [assumption]*
+  > 2. [question] — *default: [assumption]*
+  >
+  > Reply with answers, edits to the approach, or 'looks good' to continue.
+
+  **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`.
+  - 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).
+
+- **Wait** — User signals alignment.
+
+- **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.
+
+> **CHECKPOINT**: After alignment, proceed IMMEDIATELY to Step 4. The ONLY valid next action is invoking a Skill.
+
+## Step 4 - Route to Workflow
+
+### ⛔ MANDATORY SKILL INVOCATION ⛔
+
+```plaintext
+┌────────────────────────────────────────────────────────────────────────┐
+│  YOU MUST USE THE SKILL TOOL TO INVOKE THESE COMMANDS                  │
+│                                                                        │
+│  ❌ WRONG: "I'll now create the plan..."                               │
+│  ❌ WRONG: "The next step would be to run create_plan"        │
+│  ❌ WRONG: Ending turn without invoking Skill tool                     │
+│                                                                        │
+│  ✅ CORRECT: Skill tool with skill: "spectre-create_plan", args: "..." │
+│  ✅ CORRECT: Skill tool with skill: "spectre-create_tasks", args: "..."│
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+**DO NOT:**
+
+- Say you’ll create a plan or set of tasks yourself without running the skill tool
+- Describe what you would do
+- Summarize the plan/task steps yourself
+- End your turn without invoking Skill
+- Write plan.md or tasks.md content directly
+
+**YOU MUST:**
+
+- Use the Skill tool: `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth {tier}"`
+- Use the Skill tool: `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+
+---
+
+### Routing Logic
+
+- **If LIGHT**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md --depth light"`
+  - **Wait** — Returns task breakdown with brief implementation approach
+  - Skip to footer
+
+- **ElseIf STANDARD**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth standard"`
+  - **Wait** — Returns focused plan (Overview, Approach, Out of Scope)
+  - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
+  - **Wait** — User approval
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+  - **Wait** — Returns task breakdown
+
+- **ElseIf COMPREHENSIVE**:
+
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_plan"`, `args: "{OUT_DIR}/task_context.md --depth comprehensive"`
+  - **Wait** — Returns full plan (all sections: Architecture, Phases, API Design, Testing Strategy, etc.)
+  - **Action** — PromptUser: "Review plan. Reply 'Approved' or provide feedback."
+  - **Wait** — User approval
+  - **INVOKE NOW** → Skill tool with `skill: "spectre-create_tasks"`, `args: "{OUT_DIR}/task_context.md"`
+  - **Wait** — Returns task breakdown
+
+---
+
+- **Action** — RenderFooter: Use `Skill(spectre-guide)` skill for Next Steps

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

@@ -0,0 +1,42 @@
+---
+name: "plan_review"
+description: "👻 | Find simplifications in a plan or tasks"
+user-invocable: true
+---
+
+# plan_review
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+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.
+
+Review the following [plan/document/tasks/context] and identify opportunities to simplify while ensuring all requirements and functionality are delivered.
+
+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
+
+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
+
+## 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.
+
+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
+
+Remember: The goal is fast feedback during development. More comprehensive testing comes later.
+
+End with a prioritized list of recommendations (high/medium/low impact).

package/plugins/spectre-codex/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 `plan` or `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 `scope` as next step.
+- **scope.md exists for this branch** (no ux.md) — post-scope validation. Default fidelity: **mid-fi**. On completion, recommend `ux` or `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 `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.
+
+### `@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.
+
+### `@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.
+
+### `@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 `@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: plan  OR  resume 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 @dev prompt)
+
+When delegating to `@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-guide)` skill, with mode-specific recommendation:
+  - **If `FROM_UX=true`** → recommend: "Resume `ux` Stage 2 with this prototype as input"
+  - **If `--explore`** → recommend: `scope` with the prototype as anchor
+  - **If post-scope** → recommend: `ux` (if flows still need detail) or `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