recipe-blueprint

Context: Create or update structural design artifacts in docs/product/design/ that provide shared context for prototype generation and downstream UI specification. Blueprint bridges the gap between "what problems to solve" (discovery) and "what the product looks and works like" (prototypes).

Orchestrator Definition

Execution Protocol:

1. Delegate analysis work to sub-agents (via Agent tool) when context separation benefits accuracy
2. Follow the blueprint flow defined below
3. Stop at every [STOP — BLOCKING] marker — present findings and CANNOT proceed until user explicitly confirms

Workflow Overview

Input (validated opportunities / discovery outputs / strategic update)
    ↓
1. Context Assessment → Determine scope and mode (create vs. update)
    ↓
2. MVP Scope Definition → Feature prioritization from validated hypotheses
    ↓
3. Information Architecture → Page structure, navigation, multi-sided layout [Stop: User confirms IA]
    ↓
4. Content Model → Entity types, relationships, states
    ↓
5. Core User Flows → 5-10 primary flows across personas [Stop: User confirms structure]
    ↓
6. Brand Direction → Visual tone, color/typography direction, reference products
    ↓
7. AI Interaction Model → Interaction patterns, capability boundaries, guardrails (if applicable) [Stop: User confirms design direction]
    ↓
Output: docs/product/design/ artifacts

Execution Decision Flow

1. Context Assessment

Input: $ARGUMENTS

Read project context to determine scope:

File	Extract
docs/product/vision.md	Product vision, design vision, outcomes, NSM, strategic priorities
docs/product/design-principles.md	Trade-off resolutions that constrain all design decisions
docs/product/personas/	All persona files — roles, JTBD, pains, behavioral patterns
docs/discovery/INDEX.md	Opportunity and hypothesis status overview
docs/discovery/opportunities/	Validated opportunities with impact assessment
docs/discovery/hypotheses/	Hypothesis status, confidence scores, learnings
docs/discovery/journeys/	Journey maps (if available)
docs/product/learnings.md	Tier 1 learnings from reflection cycles

Gate: Vision, design principles, and at least one persona file must exist. At least one Opportunity must be identified (draft status is sufficient — validation is not required). If missing → inform user which prerequisite files are needed before proceeding.

Situation	Mode	Action
No docs/product/design/ exists	Create	Full blueprint definition
Blueprint exists, new Opportunities discovered	Update	Extend IA, flows, content model for new scope
Blueprint exists, new learnings in docs/product/learnings.md	Update	Revise based on new learnings
Existing codebase	Create/Update	Invoke codebase-analyzer for current architecture understanding

2. MVP Scope Definition

Synthesize validated opportunities and hypotheses into a feature scope:

1. List all validated and in-progress Opportunities with their confidence scores
2. Map each Opportunity to candidate features (from hypothesis Solutions)
3. Apply MVP prioritization — see product-principles skill references/mvp-definition.md for MoSCoW/RICE frameworks
4. Produce a feature priority matrix:
   • Must Have: Validated Opportunities with confidence 5+ across Value and Usability
   • Should Have: Validated Opportunities with confidence 3-4
   • Could Have: Opportunities with partial validation
   • Won't Have (this cycle): Explicitly deferred scope

Record the scope in the IA artifact header (Step 3).

3. Information Architecture

Use blueprint-standards skill references/ia-template.md to structure the IA:

1. Site map: Organize pages hierarchically based on MVP scope
   • Every page traces to an Opportunity or a supporting function (authentication, settings, onboarding)
   • Mark each page with its primary persona
2. Navigation model: Define global navigation, contextual navigation, and utility navigation
3. Multi-sided considerations: For marketplace/platform products, define both sides of the market with their entry pages, core loops, and connection points
4. Page inventory: For each page, define purpose, primary persona, key content, entry/exit points

[STOP — BLOCKING] Present IA to user for confirmation:

• Site map with page-to-Opportunity traceability
• Navigation model
• Multi-sided structure (if applicable)
• MVP scope summary

CANNOT proceed to Step 4 until user explicitly confirms the IA structure.

4. Content Model

Use blueprint-standards skill references/content-model-template.md to define the data structure:

1. Entity inventory: List all content types the product manages, mapped to Opportunities
2. Entity definitions: For each entity, define attributes, relationships, and states
3. Entity relationship diagram: Show how entities connect
4. Display contexts: Where each entity appears in the IA (list view, detail, creation, embedded)

5. Core User Flows

Use blueprint-standards skill references/flow-template.md to define 5-10 primary flows:

1. Identify the highest-impact flows from validated Opportunities and journey maps
2. Write each flow from a specific persona's perspective
3. Include decision points, error scenarios, and alternative paths
4. Reference IA pages — each step maps to a page in the site map

Prioritize flows that:

• Cover the core value loop (the primary reason users return)
• Span both sides of the marketplace (if applicable)
• Address the highest-confidence Opportunities first

[STOP — BLOCKING] Present content model and user flows to user for confirmation:

• Entity overview with relationships
• Core flow list with persona assignments
• Flow details for the top 3 highest-priority flows

CANNOT proceed to Step 6 until user explicitly confirms the structural design.

6. Brand Direction

Use blueprint-standards skill references/brand-direction-template.md to define visual direction:

1. Tone & Voice: Position along key dimensions (formal↔casual, expert↔approachable), traced to design principles
2. Color direction: Primary, surface, accent color families with intentional rationale — directional, not final hex values
3. Typography direction: Heading, body, UI font style intentions with language considerations
4. Visual density: Whitespace, information density, surface elevation — informed by persona context
5. Reference products: Products whose visual approach aligns, with specific aspects to reference and avoid
6. Visual Tokens (auto-derived): Derive concrete values from the direction defined above:
   • Color tokens: Select specific hex values from Reference Products' palettes and the Color Direction families. Use WebSearch to inspect Reference Products' public sites when no color values are stated in the Color Direction
   • Typography tokens: Select Google Fonts families that match the Typography Direction intentions and language considerations
   • Spacing tokens: Determine base unit from the Visual Density → Whitespace value (generous → 8px, moderate → 6px, compact → 4px) and derive scale
   • Mark source as auto-derived in the template
   • These tokens ensure prototype consistency. They are not final production values — those are determined during UI Spec

Reference the competitive landscape research (if available in research/) for visual benchmarking.

Note: Design experts can refine Visual Tokens after blueprint completion using recipe-refine-visuals. The refinement updates the same brand-direction.md file.

7. AI Interaction Model

Skip this step if the product has no AI-powered features.

Use blueprint-standards skill references/ai-interaction-model-template.md to define:

1. AI features inventory: Map each AI feature to its user goal, AI role, interaction pattern, and linked Opportunity
2. Interaction pattern decisions: For each feature — chat vs. form vs. inline vs. hybrid, UI placement, user control model
3. Capability boundaries: What AI reliably handles vs. known limitations, with fallbacks
4. Response display strategy: How to show AI output based on response time (streaming, progressive, staged)
5. Error taxonomy: Generation failure, inappropriate output, timeout, low confidence — each with user-visible behavior and recovery
6. Human-AI handoff: The boundary between AI-generated and human-edited content
7. Guardrails: Content safety, scope limitation, quality gates

[STOP — BLOCKING] Present brand direction and AI interaction model to user for confirmation:

• Tone & voice positioning
• Color and typography direction
• Visual Tokens (auto-derived color, typography, spacing values)
• AI interaction pattern decisions
• Capability boundaries and guardrails

CANNOT write files until user explicitly confirms the design direction.

8. File Output

After user approval, write all artifacts to docs/product/design/:

• docs/product/design/information-architecture.md
• docs/product/design/content-model.md
• docs/product/design/brand-direction.md
• docs/product/design/ai-interaction-model.md (if applicable)
• docs/product/design/flows/flow-{name}.md (one file per flow)

Sub-agent Usage

Agent	When	Why (context separation benefit)
codebase-analyzer (via Agent tool, subagent_type: "discover:codebase-analyzer")	Existing codebase exists	Objective assessment of current architecture, routes, and components without hypothesis bias

Scope Boundaries

Included: Information architecture, user flows, content model, brand direction, AI interaction model, MVP scope synthesis Not included: Opportunity discovery, hypothesis validation, pixel-level design specifications (UI Spec scope), component APIs and final production token values (UI Spec scope), PRD creation

Completion Criteria

• Project context read (vision, principles, personas, opportunities)
• MVP scope synthesized from validated hypotheses
• Information architecture defined with Opportunity traceability
• User confirmed IA
• Content model defined with entity relationships
• Core user flows defined (5-10 flows)
• User confirmed structural design
• Brand direction defined with design principle traceability
• Visual Tokens auto-derived from brand direction
• AI interaction model defined (if applicable)
• User confirmed design direction
• All artifacts written to docs/product/design/