Prototype-First Workflow Refactor

/prototype New Skill

Behavior by project type:

• UI projects: Static HTML/CSS pages with fake data, clickable navigation, hub page linking all variations
• CLI tools: Basic working CLI scripts with fixture data that demo each variation's workflow
• APIs: Endpoint stubs with fixture responses, Postman/curl examples
• Infrastructure: Minimal working setup (docker-compose, config files) that demonstrates the concept

Key features:

• Builds all variations in one invocation by default
• Creates comparison hub page with side-by-side navigation
• Supports --variant N flag to build/rebuild a single variation
• Feature-interview can trigger mini-prototype cycles on existing prototypes
• No backend, no auth, no real data — purely demonstrative
• Heavily informed by research docs: ICP drives persona-appropriate copy/density, competitive analysis informs differentiation, journey map shapes the flow between screens, concept brief grounds the prototype in validated assumptions

Alignment Pages New Convention

Key principles:

• Custom-built, not templated: Each agent crafts the HTML page to fit the situation. There is no shared template or CSS library — the agent decides what layout, structure, and visual approach best communicates the skill's output.
• Situation-appropriate: An idea scope brief page might be a simple overview with cards. A ux-variations page might show side-by-side comparisons. A spec-interview page might walk through screens with annotated production concerns. The format follows the content.
• Temporary artifacts: Alignment pages exist to ensure agent-user alignment before proceeding. They are archived or deleted once the user confirms alignment and the pipeline moves forward.
• Opened in browser: The agent opens the page in the user's browser after building it, so they can review visually.

/spec-interview Major Change

What changes:

• Position in pipeline: Moves from pre-prototype (step 3) to post-prototype (step 10). Now sits after /consolidate-prototypes.
• Input: Takes the consolidated clickable prototype as primary input, not a concept brief or draft spec.
• Interview mode: Screen-by-screen walkthrough of the prototype. For each screen/page asks:
  • What's the real data model behind this?
  • What API calls does this screen make?
  • What authentication/authorization applies?
  • What happens when the data is empty? When a request fails? When the user has no permission?
  • What are the performance requirements?
  • What analytics/tracking is needed?
• Iterative prototype updates: When the interview reveals gaps ("this screen needs an error state we didn't prototype"), spec-interview can trigger prototype updates before finalizing.
• Output: Full production spec (specs/[topic].md) + alignment HTML page. The spec references the prototype as source of truth for visual/interaction decisions.

What stays the same:

• Canonical spec sections (Overview, Goals, Non-Goals, Detailed Design, Edge Cases, Test Plan, Acceptance Criteria)
• Interview logging with deviation tracking
• --ideas flag for batch processing

/feature-interview Changed

What changes:

• Position in pipeline: Moves to post-ship. No longer the second step — it's for adding features to an existing shipped product.
• Scope triage: Feature-interview now triages the scope of the proposed feature:
  • Small (config change, copy update, simple toggle): routes to spec + implement directly
  • Medium (new component, new screen, workflow change): routes to a single-variation mini-prototype cycle
  • Large (new product area, major workflow redesign): routes to full pipeline (ux-variations → ui-interview → prototype → etc.)
• Mini-prototype support: For medium features, can trigger a focused prototype of just that feature in the context of the existing product.

What stays the same:

• Evidence-backed triage (validates against code, docs, git history)
• Interview logging
• Routing to appropriate next skill

/ux-variations Renamed

What changes:

• Name: ux-variation → ux-variations (plural)
• Output: Now also generates an HTML alignment page
• Next step routing: Updated to route to /ui-interview (per variation) → /prototype instead of /exec

What stays the same:

• 3-5 distinct variation archetypes
• --layout-mode for visual/spatial variations
• Interview-based exploration of onboarding, workflows, sharing, return-use, etc.

/consolidate-prototypes Renamed Changed

What changes:

• Name: ui-consolidate → consolidate-prototypes
• Output: Now builds a consolidated clickable prototype instead of a spec document. Merges the best elements from evaluated prototype variations into a single runnable artifact.
• Process: Same per-variation interview (keep/reject/neutral), cross-variation synthesis, conflict resolution — but the deliverable is a built prototype, not a document.
• Next step: Routes to /spec-interview (which will extract the production spec from this prototype)

/roadmap Changed

What changes:

• Gate update: Now requires consolidated prototype + production spec + refreshed research docs (both --post-prototype and --post-spec passes) before creating a roadmap
• Remove: Phase 0 / prototype-first enforcement logic — this is now handled by the upstream prototype gate
• State machine: Update states B0 (missing design gates) to check for prototype + spec instead of just spec

/plan-phase Changed

What changes:

• Remove: Phase 0 / prototype-first logic, fixture-data enforcement, infrastructure deferral logic — all now upstream
• Focus: Purely on production implementation decomposition. Every phase it plans is a production phase.
• Reference: Can reference the consolidated prototype as a visual spec alongside the written spec

/research-roadmap Changed

What changes:

• New mode: --post-prototype — After consolidate-prototypes. Scans all research docs against the consolidated prototype. Flags docs where prototype findings contradict or supersede earlier research (e.g., "journey map onboarding stage doesn't match the prototype's actual onboarding flow," "ICP assumed technical users but prototype feedback shows non-technical users engage more").
• New mode: --post-spec — After spec-interview. Scans research docs against production spec constraints. Flags docs invalidated by production realities (e.g., "competitive analysis positioned us on real-time, but spec shows we'll use batch processing," "positioning doc claims instant setup but spec requires OAuth config").
• Both passes must complete before /roadmap will proceed. Ensures roadmap is built on fully current, prototype-validated, spec-validated research.

What stays the same:

• Default mode (no flags) still scans general research health and queues missing/stale docs
• Queue format (Priority Documentation Todo in tasks/todo.md)
• Staleness heuristics and dependency chain awareness

/idea-scope-brief, /ui-interview Minor

What changes:

• Add alignment HTML output
• /ui-interview: clarified that it runs per-variation in the prototype pipeline
• Updated next-step routing to reflect new pipeline order

Skill Renaming Breaks Existing Projects

Risk: Renaming ux-variation → ux-variations and ui-consolidate → consolidate-prototypes breaks existing references in roadmaps, specs, interview logs, and next-step routing.

Mitigation: Clean break. No aliases or redirects. /hygiene handles cleanup — it flags stale references to old skill names during audits. Existing projects run /hygiene --fix to update references.

Research Refresh Can Stall the Pipeline

Risk: research-roadmap --post-prototype might queue heavy research rewrites (e.g., re-run /icp) that block spec-interview.

Mitigation: research-roadmap populates tasks/todo.md with the stale research skills that need re-running. spec-interview's gate checks that all queued research tasks are completed. The user runs each queued research skill, then proceeds. This is intentionally blocking — spec-interview should work from current research, not stale assumptions.

Spec-Interview Prototype Updates Create Loop Risk

Risk: spec-interview updates the prototype → does this retrigger research-roadmap --post-prototype → which might queue more research → infinite loop?

Mitigation: User decides per-update. Each time spec-interview wants to update the prototype, it asks the user via AskUserQuestion whether this change warrants re-running upstream steps. Most additive changes (new error states, missing screens) won't need it. Fundamental changes (scrapping a whole screen) might.

Non-UI Prototype Scope Is Fuzzy

Risk: For CLI/API/infra projects, the line between "prototype" and "actual implementation" is blurry.

Mitigation: Scope rule: prototype demonstrates exactly one core user workflow end-to-end with fixture data. For CLI: one command chain. For API: one request flow. For infra: one setup-to-verify cycle. Scope, not fidelity — the prototype proves the concept works, not that it handles every edge case.

Alignment Page Accumulation

Risk: A full pipeline run produces 8-10 HTML files in alignment/.

Mitigation: Two-layer cleanup. (1) When a skill runs, it archives the previous skill's alignment page to docs/history/archive/. Only the current alignment page exists at any time. (2) /hygiene flags any stale alignment pages during audits.