maestro-flow 0.1.4 → 0.2.0

package/.claude/commands/maestro-spec-generate.md

@@ -1,102 +1,102 @@
----
-name: maestro-spec-generate
-description: Generate specification package from idea/requirements through 7-phase document chain producing product brief, PRD, architecture, epics, and interactive roadmap
-argument-hint: "<idea or @file> [-y] [-c] [--count N]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Transform an idea, brainstorm output, or user requirements into a complete specification package through a 7-phase document chain: Discovery → Requirement Clarification → Product Brief → PRD → Architecture → Epics & Stories → Readiness Check → Roadmap Generation. Outputs a validated specification package with roadmap in `.workflow/.spec/` and writes `.workflow/roadmap.md` for downstream execution.
-
-This is the heavy-path entry for structured decomposition: idea → spec-generate (spec + roadmap) → init → plan → execute.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/spec-generate.md
-</required_reading>
-
-<deferred_reading>
-- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm session reference.
-
-**Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint (reads spec-config.json)
-- `--count N`: Limit number of exploration dimensions (default 5)
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
-
-**Input types:**
-- Direct text: `"Build a real-time collaboration platform"`
-- File reference: `@requirements.md` or `@design-brief.txt`
-- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
-
-**Output location:** `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
-
-**Relationship to pipeline:**
-```
-maestro-brainstorm (optional upstream)
-        ↓ guidance-specification.md
-maestro-init (REQUIRED first step — project setup)
-        ↓ project.md, state.json, config.json
-maestro-spec-generate (this command — heavy path)
-        ↓ spec package + roadmap.md → .workflow/roadmap.md
-maestro-plan → maestro-execute → maestro-verify
-
-Alternative light path (skip spec-generate):
-maestro-init → maestro-roadmap → roadmap.md directly
-```
-**Note:** `maestro-init` MUST run before this command. It creates the `.workflow/` directory and project context that spec-generate builds upon.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/spec-generate.md' completely.
-
-**Next-step routing on completion:**
-- Roadmap generated, ready to plan → Skill({ skill: "maestro-plan", args: "1" })
-- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
-- Need analysis before planning → Skill({ skill: "maestro-analyze", args: "1" })
-- View project dashboard → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Idea/topic text or @file required | Prompt user for input |
-| E002 | error | `.workflow/` not initialized (no parent dir) | Create `.workflow/` directory |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
-| E004 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
-| W002 | warning | Codebase exploration failed | Continue without codebase context |
-| W005 | warning | External research agent failed | Continue without apiResearchContext |
-| W003 | warning | Glossary has < 5 terms | Note in readiness check |
-| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
-</error_codes>
-
-<success_criteria>
-- [ ] `spec-config.json` created with session metadata and phase tracking
-- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
-- [ ] `glossary.json` with 5+ core terms for cross-document consistency
-- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
-- [ ] All requirements have RFC 2119 keywords and acceptance criteria
-- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
-- [ ] Architecture includes state machine, config model, error handling, observability (service type)
-- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
-- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
-- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
-- [ ] `spec-summary.md` with one-page executive summary
-- [ ] All documents have valid YAML frontmatter with session_id
-- [ ] Glossary terms used consistently across all documents
-- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
-- [ ] `roadmap.md` generated from Epics with interactive user confirmation
-- [ ] `.workflow/roadmap.md` written (if `.workflow/` exists)
-</success_criteria>
+---
+name: maestro-spec-generate
+description: Generate specification package from idea/requirements through 7-phase document chain producing product brief, PRD, architecture, epics, and interactive roadmap
+argument-hint: "<idea or @file> [-y] [-c] [--count N]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Transform an idea, brainstorm output, or user requirements into a complete specification package through a 7-phase document chain: Discovery → Requirement Clarification → Product Brief → PRD → Architecture → Epics & Stories → Readiness Check → Roadmap Generation. Outputs a validated specification package with roadmap in `.workflow/.spec/` and writes `.workflow/roadmap.md` for downstream execution.
+
+This is the heavy-path entry for structured decomposition: idea → spec-generate (spec + roadmap) → init → plan → execute.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/spec-generate.md
+</required_reading>
+
+<deferred_reading>
+- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm session reference.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint (reads spec-config.json)
+- `--count N`: Limit number of exploration dimensions (default 5)
+- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+
+**Input types:**
+- Direct text: `"Build a real-time collaboration platform"`
+- File reference: `@requirements.md` or `@design-brief.txt`
+- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+
+**Output location:** `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
+
+**Relationship to pipeline:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md
+maestro-init (REQUIRED first step — project setup)
+        ↓ project.md, state.json, config.json
+maestro-spec-generate (this command — heavy path)
+        ↓ spec package + roadmap.md → .workflow/roadmap.md
+maestro-plan → maestro-execute → maestro-verify
+
+Alternative light path (skip spec-generate):
+maestro-init → maestro-roadmap → roadmap.md directly
+```
+**Note:** `maestro-init` MUST run before this command. It creates the `.workflow/` directory and project context that spec-generate builds upon.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/spec-generate.md' completely.
+
+**Next-step routing on completion:**
+- Roadmap generated, ready to plan → Skill({ skill: "maestro-plan", args: "1" })
+- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
+- Need analysis before planning → Skill({ skill: "maestro-analyze", args: "1" })
+- View project dashboard → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Idea/topic text or @file required | Prompt user for input |
+| E002 | error | `.workflow/` not initialized (no parent dir) | Create `.workflow/` directory |
+| E003 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
+| E004 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W002 | warning | Codebase exploration failed | Continue without codebase context |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+| W003 | warning | Glossary has < 5 terms | Note in readiness check |
+| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+</error_codes>
+
+<success_criteria>
+- [ ] `spec-config.json` created with session metadata and phase tracking
+- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
+- [ ] `glossary.json` with 5+ core terms for cross-document consistency
+- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
+- [ ] All requirements have RFC 2119 keywords and acceptance criteria
+- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
+- [ ] Architecture includes state machine, config model, error handling, observability (service type)
+- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
+- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
+- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
+- [ ] `spec-summary.md` with one-page executive summary
+- [ ] All documents have valid YAML frontmatter with session_id
+- [ ] Glossary terms used consistently across all documents
+- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
+- [ ] `roadmap.md` generated from Epics with interactive user confirmation
+- [ ] `.workflow/roadmap.md` written (if `.workflow/` exists)
+</success_criteria>

package/.claude/commands/maestro-ui-design.md

@@ -1,152 +1,152 @@
----
-name: maestro-ui-design
-description: Generate UI design prototypes with multiple styles via ui-ux-pro-max, user selects winner, solidify as code reference
-argument-hint: "<phase|topic> [--styles N] [--stack <stack>] [--targets <pages>] [--layouts N] [--refine] [--persist] [--full] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Generate UI design prototypes for a phase or topic. Two workflow paths, auto-selected by skill availability:
-
-1. **Primary (ui-style.md):** Delegates design to ui-ux-pro-max skill. Generates multiple style variants via `--design-system`, user selects, solidifies as code reference. Lightweight and fast.
-2. **Fallback (ui-design.md):** Self-contained 4-layer pipeline (style → animation → layout → assembly) with 6D attribute space, OKLCH tokens, layout templates, and full prototype matrix. Used when ui-ux-pro-max is unavailable or `--full` is requested.
-
-Both paths produce the same output contract: MASTER.md + design-tokens.json + animation-tokens.json + selection.json for downstream plan/execute consumption.
-
-Position in pipeline: analyze -> **ui-design** -> plan -> execute -> verify
-</purpose>
-
-<deferred_reading>
-- [ui-style.md](~/.maestro/workflows/ui-style.md) — read when SKILL_PATH found (primary path)
-- [ui-design.md](~/.maestro/workflows/ui-design.md) — read when SKILL_PATH empty or --full (fallback path)
-- [index.json](~/.maestro/templates/index.json) — read when updating phase metadata
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-</deferred_reading>
-
-<context>
-$ARGUMENTS — phase number for phase mode, topic text for scratch mode, with optional flags.
-
-**Flags:**
-- `--styles N` — Number of style variants to generate (default: 3, range: 2-5)
-- `--layouts N` — Number of layout variants per target (default: 2, range: 1-3)
-- `--stack <stack>` — Tech stack for implementation guidelines (default: html-tailwind). Options: html-tailwind, react, nextjs, vue, svelte, shadcn
-- `--targets <pages>` — Comma-separated page/component targets to prototype (default: inferred from phase goal or "home")
-- `--refine` — Refinement mode: fine-tune an existing design-ref instead of generating from scratch (ui-design.md only)
-- `--persist` — Save design system with hierarchical page overrides (MASTER.md + pages/)
-- `--full` — Force full 4-layer pipeline (ui-design.md) even when ui-ux-pro-max is available
-- `-y` / `--yes` — Auto mode: skip interactive selection, pick top-scored variant
-
-**Workflow routing:**
-- Default: auto-detect ui-ux-pro-max skill → if found, use `ui-style.md` (lightweight); if not, use `ui-design.md` (self-contained)
-- `--full`: always use `ui-design.md` regardless of skill availability
-- Flags `--layouts N` and `--refine` are only effective with `ui-design.md` (full pipeline)
-
-**Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
-**Scratch mode** (text): creates `.workflow/scratch/ui-design-{slug}-{date}/` for standalone exploration.
-
-**Output artifacts (in phase or scratch directory):**
-| Artifact | Description |
-|----------|-------------|
-| `design-ref/` | Root directory for all design outputs |
-| `design-ref/MASTER.md` | Selected design system (colors, typography, spacing, effects, anti-patterns) |
-| `design-ref/design-tokens.json` | Production-ready tokens (OKLCH colors, typography.combinations, component_styles, opacity) |
-| `design-ref/animation-tokens.json` | Animation system (duration, easing, transitions, keyframes, interactions) |
-| `design-ref/layout-templates/` | Structural layout templates per target (dom_structure + css_layout_rules) |
-| `design-ref/prototypes/` | Assembled HTML/CSS prototypes (styles x layouts x targets) |
-| `design-ref/prototypes/compare.html` | Interactive matrix comparison page |
-| `design-ref/.intermediates/` | Analysis options, user selections, exploration data |
-| `design-ref/selection.json` | User selection metadata + rationale |
-| `design-ref/pages/{page}.md` | Page-specific design overrides (if --persist) |
-</context>
-
-<execution>
-## Workflow Routing (skill detection)
-
-Detect ui-ux-pro-max skill availability:
-
-```bash
-SKILL_PATH=""
-for path in \
-  "skills/ui-ux-pro-max/scripts/search.py" \
-  "$HOME/.claude/plugins/cache/ui-ux-pro-max-skill/ui-ux-pro-max/*/scripts/search.py"; do
-  expanded=$(ls $path 2>/dev/null | tail -1)
-  if [ -n "$expanded" ]; then SKILL_PATH="$expanded"; break; fi
-done
-[ -z "$SKILL_PATH" ] && SKILL_PATH=$(find "$HOME/.claude/plugins" -path "*/ui-ux-pro-max/*/scripts/search.py" -print -quit 2>/dev/null)
-```
-
-**Route:**
-- **`--full` flag present** → Follow '~/.maestro/workflows/ui-design.md' completely (forced full pipeline)
-- **SKILL_PATH found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight, delegates design to ui-ux-pro-max)
-- **SKILL_PATH empty** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained 4-layer pipeline fallback)
-
-Pass `SKILL_PATH` to the workflow when using ui-style.md.
-
-**Report format on completion:**
-
-```
-=== UI DESIGN READY ===
-Phase:   {phase_name}
-Styles:  {style_count} variants, #{selected} selected
-Layouts: {layout_count} per target
-Targets: {target_list}
-Stack:   {stack}
-Matrix:  {S x L x T} = {total} prototypes
-
-Design System:
-  MASTER.md:        {phase_dir}/design-ref/MASTER.md
-  Tokens:           {phase_dir}/design-ref/design-tokens.json
-  Animation:        {phase_dir}/design-ref/animation-tokens.json
-  Layout Templates: {phase_dir}/design-ref/layout-templates/
-  Prototypes:       {phase_dir}/design-ref/prototypes/
-  Compare:          {phase_dir}/design-ref/prototypes/compare.html
-
-Next steps:
-  Skill({ skill: "maestro-plan", args: "{phase}" })              -- Plan with design reference
-  Skill({ skill: "maestro-ui-design", args: "{phase} --refine" }) -- Refine selected design
-  Skill({ skill: "maestro-analyze", args: "{phase}" })           -- Analyze before planning
-```
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | Phase or topic argument required | parse_input |
-| E002 | error | Phase directory not found | parse_input |
-| E003 | error | Python not available (both paths need Python for ui-ux-pro-max or agent fallback) | setup |
-| E004 | error | --refine requires existing design-ref/ | parse_input |
-| W001 | warning | Design system generation returned partial results | generate |
-| W002 | warning | Prototype rendering failed for one variant | render |
-| W003 | warning | No context.md found, using phase goal only | context |
-| W004 | warning | ui-ux-pro-max not found, falling back to full pipeline | routing |
-</error_codes>
-
-<success_criteria>
-**Both paths (common):**
-- [ ] Requirements extracted from phase context (context.md, brainstorm, spec, or user input)
-- [ ] N style variants generated with contrasting design directions
-- [ ] User selected preferred variant (or auto-selected in -y mode)
-- [ ] MASTER.md written with complete design system specification
-- [ ] design-tokens.json written with production-ready tokens (OKLCH colors, component_styles)
-- [ ] animation-tokens.json written (duration, easing, transitions, keyframes)
-- [ ] selection.json recorded with choice metadata
-- [ ] index.json updated with design_ref status
-
-**ui-style.md path (primary):**
-- [ ] ui-ux-pro-max --design-system called with product/industry/style keywords
-- [ ] Tokens extracted from ui-ux-pro-max output into structured JSON
-
-**ui-design.md path (--full or fallback):**
-- [ ] 6D attribute space used for maximum contrast between variants
-- [ ] Layout templates generated per target (dom_structure + css_layout_rules)
-- [ ] HTML prototypes assembled: styles x layouts x targets
-- [ ] compare.html generated as interactive matrix viewer
-</success_criteria>
-</output>
+---
+name: maestro-ui-design
+description: Generate UI design prototypes with multiple styles via ui-ux-pro-max, user selects winner, solidify as code reference
+argument-hint: "<phase|topic> [--styles N] [--stack <stack>] [--targets <pages>] [--layouts N] [--refine] [--persist] [--full] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Generate UI design prototypes for a phase or topic. Two workflow paths, auto-selected by skill availability:
+
+1. **Primary (ui-style.md):** Delegates design to ui-ux-pro-max skill. Generates multiple style variants via `--design-system`, user selects, solidifies as code reference. Lightweight and fast.
+2. **Fallback (ui-design.md):** Self-contained 4-layer pipeline (style → animation → layout → assembly) with 6D attribute space, OKLCH tokens, layout templates, and full prototype matrix. Used when ui-ux-pro-max is unavailable or `--full` is requested.
+
+Both paths produce the same output contract: MASTER.md + design-tokens.json + animation-tokens.json + selection.json for downstream plan/execute consumption.
+
+Position in pipeline: analyze -> **ui-design** -> plan -> execute -> verify
+</purpose>
+
+<deferred_reading>
+- [ui-style.md](~/.maestro/workflows/ui-style.md) — read when SKILL_PATH found (primary path)
+- [ui-design.md](~/.maestro/workflows/ui-design.md) — read when SKILL_PATH empty or --full (fallback path)
+- [index.json](~/.maestro/templates/index.json) — read when updating phase metadata
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number for phase mode, topic text for scratch mode, with optional flags.
+
+**Flags:**
+- `--styles N` — Number of style variants to generate (default: 3, range: 2-5)
+- `--layouts N` — Number of layout variants per target (default: 2, range: 1-3)
+- `--stack <stack>` — Tech stack for implementation guidelines (default: html-tailwind). Options: html-tailwind, react, nextjs, vue, svelte, shadcn
+- `--targets <pages>` — Comma-separated page/component targets to prototype (default: inferred from phase goal or "home")
+- `--refine` — Refinement mode: fine-tune an existing design-ref instead of generating from scratch (ui-design.md only)
+- `--persist` — Save design system with hierarchical page overrides (MASTER.md + pages/)
+- `--full` — Force full 4-layer pipeline (ui-design.md) even when ui-ux-pro-max is available
+- `-y` / `--yes` — Auto mode: skip interactive selection, pick top-scored variant
+
+**Workflow routing:**
+- Default: auto-detect ui-ux-pro-max skill → if found, use `ui-style.md` (lightweight); if not, use `ui-design.md` (self-contained)
+- `--full`: always use `ui-design.md` regardless of skill availability
+- Flags `--layouts N` and `--refine` are only effective with `ui-design.md` (full pipeline)
+
+**Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
+**Scratch mode** (text): creates `.workflow/scratch/ui-design-{slug}-{date}/` for standalone exploration.
+
+**Output artifacts (in phase or scratch directory):**
+| Artifact | Description |
+|----------|-------------|
+| `design-ref/` | Root directory for all design outputs |
+| `design-ref/MASTER.md` | Selected design system (colors, typography, spacing, effects, anti-patterns) |
+| `design-ref/design-tokens.json` | Production-ready tokens (OKLCH colors, typography.combinations, component_styles, opacity) |
+| `design-ref/animation-tokens.json` | Animation system (duration, easing, transitions, keyframes, interactions) |
+| `design-ref/layout-templates/` | Structural layout templates per target (dom_structure + css_layout_rules) |
+| `design-ref/prototypes/` | Assembled HTML/CSS prototypes (styles x layouts x targets) |
+| `design-ref/prototypes/compare.html` | Interactive matrix comparison page |
+| `design-ref/.intermediates/` | Analysis options, user selections, exploration data |
+| `design-ref/selection.json` | User selection metadata + rationale |
+| `design-ref/pages/{page}.md` | Page-specific design overrides (if --persist) |
+</context>
+
+<execution>
+## Workflow Routing (skill detection)
+
+Detect ui-ux-pro-max skill availability:
+
+```bash
+SKILL_PATH=""
+for path in \
+  "skills/ui-ux-pro-max/scripts/search.py" \
+  "$HOME/.claude/plugins/cache/ui-ux-pro-max-skill/ui-ux-pro-max/*/scripts/search.py"; do
+  expanded=$(ls $path 2>/dev/null | tail -1)
+  if [ -n "$expanded" ]; then SKILL_PATH="$expanded"; break; fi
+done
+[ -z "$SKILL_PATH" ] && SKILL_PATH=$(find "$HOME/.claude/plugins" -path "*/ui-ux-pro-max/*/scripts/search.py" -print -quit 2>/dev/null)
+```
+
+**Route:**
+- **`--full` flag present** → Follow '~/.maestro/workflows/ui-design.md' completely (forced full pipeline)
+- **SKILL_PATH found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight, delegates design to ui-ux-pro-max)
+- **SKILL_PATH empty** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained 4-layer pipeline fallback)
+
+Pass `SKILL_PATH` to the workflow when using ui-style.md.
+
+**Report format on completion:**
+
+```
+=== UI DESIGN READY ===
+Phase:   {phase_name}
+Styles:  {style_count} variants, #{selected} selected
+Layouts: {layout_count} per target
+Targets: {target_list}
+Stack:   {stack}
+Matrix:  {S x L x T} = {total} prototypes
+
+Design System:
+  MASTER.md:        {phase_dir}/design-ref/MASTER.md
+  Tokens:           {phase_dir}/design-ref/design-tokens.json
+  Animation:        {phase_dir}/design-ref/animation-tokens.json
+  Layout Templates: {phase_dir}/design-ref/layout-templates/
+  Prototypes:       {phase_dir}/design-ref/prototypes/
+  Compare:          {phase_dir}/design-ref/prototypes/compare.html
+
+Next steps:
+  Skill({ skill: "maestro-plan", args: "{phase}" })              -- Plan with design reference
+  Skill({ skill: "maestro-ui-design", args: "{phase} --refine" }) -- Refine selected design
+  Skill({ skill: "maestro-analyze", args: "{phase}" })           -- Analyze before planning
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | Phase or topic argument required | parse_input |
+| E002 | error | Phase directory not found | parse_input |
+| E003 | error | Python not available (both paths need Python for ui-ux-pro-max or agent fallback) | setup |
+| E004 | error | --refine requires existing design-ref/ | parse_input |
+| W001 | warning | Design system generation returned partial results | generate |
+| W002 | warning | Prototype rendering failed for one variant | render |
+| W003 | warning | No context.md found, using phase goal only | context |
+| W004 | warning | ui-ux-pro-max not found, falling back to full pipeline | routing |
+</error_codes>
+
+<success_criteria>
+**Both paths (common):**
+- [ ] Requirements extracted from phase context (context.md, brainstorm, spec, or user input)
+- [ ] N style variants generated with contrasting design directions
+- [ ] User selected preferred variant (or auto-selected in -y mode)
+- [ ] MASTER.md written with complete design system specification
+- [ ] design-tokens.json written with production-ready tokens (OKLCH colors, component_styles)
+- [ ] animation-tokens.json written (duration, easing, transitions, keyframes)
+- [ ] selection.json recorded with choice metadata
+- [ ] index.json updated with design_ref status
+
+**ui-style.md path (primary):**
+- [ ] ui-ux-pro-max --design-system called with product/industry/style keywords
+- [ ] Tokens extracted from ui-ux-pro-max output into structured JSON
+
+**ui-design.md path (--full or fallback):**
+- [ ] 6D attribute space used for maximum contrast between variants
+- [ ] Layout templates generated per target (dom_structure + css_layout_rules)
+- [ ] HTML prototypes assembled: styles x layouts x targets
+- [ ] compare.html generated as interactive matrix viewer
+</success_criteria>
+</output>