codename-inc/prototype

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>:

   <!--
     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>:

   <!-- 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