maestro-flow 0.1.0

package/.claude/commands/maestro-milestone-complete.md

@@ -0,0 +1,58 @@
+---
+name: maestro-milestone-complete
+description: Archive completed milestone and prepare for next
+argument-hint: "[milestone, e.g., 'v1.0']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Mark a milestone as complete after its audit has passed. Validates that the audit report exists and shows a passing verdict, archives the milestone by updating state.json, generates a milestone summary document capturing key outcomes and learnings, and prepares the project state for the next milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-complete.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** Skill({ skill: "maestro-milestone-audit" }) should have passed (all phases completed, no integration gaps).
+
+**State files:**
+- `.workflow/state.json` -- current_milestone, milestones array
+- `.workflow/roadmap.md` -- milestone structure
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+**Next-step routing on completion:**
+- Next milestone has phases → Skill({ skill: "maestro-plan", args: "{next_milestone_first_phase}" })
+- Need to capture learnings → Skill({ skill: "manage-memory-capture", args: "compact" })
+- View updated project state → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
+| E002 | error | Audit not passed (report missing or verdict FAIL) | Run maestro-milestone-audit first |
+| E003 | error | Incomplete phases remain in this milestone | Complete remaining phases before milestone completion |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS before proceeding
+- [ ] Milestone marked complete in state.json with timestamp
+- [ ] Milestone summary generated with outcomes and learnings
+- [ ] Roadmap snapshot saved to milestones directory
+- [ ] project.md Context updated with milestone summary and key learnings
+- [ ] state.json updated with next milestone as current
+</success_criteria>

package/.claude/commands/maestro-phase-add.md

@@ -0,0 +1,55 @@
+---
+name: maestro-phase-add
+description: Add or insert a new phase into the project roadmap with automatic renumbering
+argument-hint: "<slug> <title> [--after N]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+---
+
+<purpose>
+Add a new phase to the project roadmap, either appending it at the end or inserting it after a specified phase number. Handles automatic renumbering of subsequent phase directories, updates roadmap.md with the new entry, and initializes the phase directory with an index.json so it is ready for planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/phase-add.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when creating new phase index
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase slug and title (required), optional --after N flag.
+
+**Flags:**
+- `--after N` -- Insert after phase N (renumbers subsequent phases). If omitted, appends at end.
+
+**State files:**
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/state.json` -- project-level state
+- `.workflow/phases/` -- existing phase directories
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/phase-add.md' completely.
+
+**Next-step routing on completion:**
+- Plan the new phase → Skill({ skill: "maestro-plan", args: "{new_phase_number}" })
+- Analyze before planning → Skill({ skill: "maestro-analyze", args: "{new_phase_number}" })
+- View updated roadmap → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Meaning                          |
+|------|----------------------------------|
+| E001 | Phase name/slug required         |
+| E002 | roadmap.md not found             |
+| E003 | Duplicate phase name/slug exists |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase directory created with NN-slug format
+- [ ] roadmap.md updated with new phase entry at correct position
+- [ ] index.json initialized in new phase directory with status = "pending"
+- [ ] Subsequent phases renumbered correctly (if --after N used)
+- [ ] state.json updated if renumbering affected tracked phases
+</success_criteria>

package/.claude/commands/maestro-phase-transition.md

@@ -0,0 +1,65 @@
+---
+name: maestro-phase-transition
+description: Mark current or specified phase as complete, extract learnings, advance to next phase
+argument-hint: "[phase-number] [--force]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion]
+---
+
+<purpose>
+Transition from one phase to the next after verification passes. Validates that the current phase meets all completion criteria (tasks done, verification passed, no unresolved gaps), marks it complete in the phase index, and advances the project state to the next phase. If the next phase directory does not exist, it is created and initialized.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/phase-transition.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when updating project state
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase number to transition from (optional, defaults to current_phase from state.json).
+
+**Flags:**
+- `--force` -- Skip gap check and force transition even with warnings
+
+**State files:**
+- `.workflow/state.json` -- project-level state (current_phase, milestones)
+- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata and status
+- `.workflow/phases/{NN}-{slug}/verification.json` -- verification results
+- `.workflow/phases/{NN}-{slug}/review.json` -- code review results (if exists)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/phase-transition.md' completely.
+
+**Next-step routing on completion:**
+- Next phase exists, ready to plan → Skill({ skill: "maestro-plan", args: "{next_phase}" })
+- Next phase needs analysis first → Skill({ skill: "maestro-analyze", args: "{next_phase}" })
+- Next phase needs UI design → Skill({ skill: "maestro-ui-design", args: "{next_phase}" })
+- All phases in milestone complete → Skill({ skill: "maestro-milestone-audit" })
+- View updated dashboard → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Meaning                                    |
+|------|--------------------------------------------|
+| E001 | Phase number required (could not determine) |
+| E002 | Phase has not passed verification           |
+| E003 | Phase has unresolved critical gaps          |
+| W001 | Phase has warnings but no blockers          |
+| W002 | UAT test failures exist (quality-test) — review recommended before transition |
+| W003 | Code review verdict is BLOCK — Skill({ skill: "quality-review" }) findings should be fixed first |
+| W004 | Code review not yet run — Skill({ skill: "quality-review" }) recommended before transition |
+</error_codes>
+
+<success_criteria>
+- [ ] Current phase index.json marked status = "complete" with completed_at timestamp
+- [ ] Next phase directory created (if not already existing)
+- [ ] Next phase index.json initialized with status = "pending"
+- [ ] state.json current_phase updated to next phase number
+- [ ] Learnings extracted and appended to specs/learnings.md
+- [ ] project.md requirements moved Active → Validated for completed phase
+- [ ] roadmap.md phase marked as ✅ COMPLETED
+</success_criteria>

package/.claude/commands/maestro-plan.md

@@ -0,0 +1,87 @@
+---
+name: maestro-plan
+description: Explore, clarify, plan, check, and confirm a phase execution plan
+argument-hint: "<phase> [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create a verified execution plan (plan.json + .task/TASK-*.json) for a roadmap phase through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Invoked when a phase is ready to be planned after init/brainstorm. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number or slug)
+
+**Flags:**
+- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
+- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
+- `--auto` -- Skip interactive clarification (P2), use defaults
+- `--gaps` -- Gap closure mode: load verification.json gaps, skip exploration, plan only gap fixes
+- `--dir <path>` -- Use arbitrary directory instead of phase resolution (scratch mode, skip roadmap validation)
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/` (or `--dir` path):
+- context.md (user decisions from Skill({ skill: "maestro-analyze" }))
+- index.json (phase metadata)
+- spec-ref from index.json (if set)
+- codebase/doc-index.json (if exists)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/plan.md' completely.
+
+**Report format on completion:**
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+
+Plan: {phase_dir}/plan.json
+Tasks: {phase_dir}/.task/TASK-*.json
+
+Next steps:
+  Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
+  Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
+
+Note: If this was a --gaps plan, after execute run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are closed.
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | --gaps requires verification.json to exist | Check arguments format, re-run with correct input |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to phase directory with summary, approach, task_ids, waves
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel)
+- [ ] index.json updated with plan status and timestamps
+</success_criteria>

package/.claude/commands/maestro-quick.md

@@ -0,0 +1,56 @@
+---
+name: maestro-quick
+description: Execute a quick task with workflow guarantees but skip optional agents
+argument-hint: "[description] [--full] [--discuss]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+<purpose>
+Execute small, ad-hoc tasks with workflow guarantees (atomic commits, state tracking) using a shortened pipeline. Invoked for tasks that are well-understood and do not require full phase-level planning. Produces scratch task directory with plan, execution results, and optional verification. Flags --discuss and --full enable additional pipeline stages.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/quick.md
+</required_reading>
+
+<context>
+$ARGUMENTS
+
+Parse for:
+- `--full` flag -- Enables plan-checking (max 2 iterations) and post-execution verification
+- `--discuss` flag -- Decision extraction before planning (gray areas, Locked/Free/Deferred classification)
+- Remaining text as task description
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/quick.md' completely.
+
+**Next-step routing on completion:**
+- Task done, --full verification passed → Skill({ skill: "manage-status" })
+- Task done, verification found gaps → Skill({ skill: "quality-debug", args: "{issue}" })
+- Task done, want to sync docs → Skill({ skill: "quality-sync" })
+- Need a full phase workflow instead → Skill({ skill: "maestro-plan", args: "{phase}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Task description required (no text provided) | Check arguments format, re-run with correct input |
+| E002 | error | Scratch directory creation failed | Check disk space and .workflow/ permissions |
+| W001 | warning | Verification found minor gaps | Review gaps and determine if they need fixing |
+</error_codes>
+
+<success_criteria>
+- [ ] Scratch task directory created under .workflow/scratch/
+- [ ] plan.json written with task definitions
+- [ ] All tasks executed with summaries written
+- [ ] state.json updated with scratch task entry
+- [ ] Commit created with task changes
+</success_criteria>

package/.claude/commands/maestro-roadmap.md

@@ -0,0 +1,95 @@
+---
+name: maestro-roadmap
+description: Interactive roadmap creation with iterative refinement — lightweight alternative to spec-generate
+argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
+
+Produces `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/roadmap.md
+@~/.maestro/templates/roadmap.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
+- `-c` / `--continue`: Resume from last checkpoint
+- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
+- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+
+**Input types:**
+- Direct text: `"Implement user authentication system with OAuth and 2FA"`
+- File reference: `@requirements.md`
+- Brainstorm import: `--from-brainstorm WFS-xxx`
+
+**Relationship to pipeline:**
+```
+maestro-brainstorm (optional upstream)
+        ↓ guidance-specification.md
+maestro-init (project setup — no roadmap)
+        ↓ project.md, state.json, config.json
+maestro-roadmap (this command — light path)
+        ↓ roadmap.md → .workflow/roadmap.md
+maestro-plan → maestro-execute → maestro-verify
+
+Alternative heavy path (skip maestro-roadmap):
+maestro-init → maestro-spec-generate → spec package + roadmap.md
+```
+
+**Dual modes:**
+| Mode | Strategy | Best For |
+|------|----------|----------|
+| Progressive | MVP → Usable → Refined (as **Milestones**, each with 1-2 phases) | High uncertainty, need validation |
+| Direct | Topological task sequence (1-2 phases, wave DAG handles ordering) | Clear requirements, confirmed tech |
+
+Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Direct, else → ask user.
+
+**Minimum-phase principle:** Default 1 phase per milestone. Only split into 2 phases when hard dependency exists (runtime + not parallelizable + full barrier). Max 2 phases, exceptional 3 with justification.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/roadmap.md' completely.
+
+**Next-step routing on completion:**
+- Roadmap approved → Skill({ skill: "maestro-analyze", args: "1" })
+- Simple project, skip analysis → Skill({ skill: "maestro-plan", args: "1" })
+- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
+- View project dashboard → Skill({ skill: "manage-status" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Requirement text or @file required | Prompt user for input |
+| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
+| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
+| W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
+</error_codes>
+
+<success_criteria>
+- [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Decomposition strategy selected (progressive or direct)
+- [ ] Phases defined with success criteria, dependencies, and requirement mappings
+- [ ] Every Active requirement from project.md mapped to exactly one phase
+- [ ] No circular dependencies in phase ordering
+- [ ] User approved roadmap (or auto-approved with -y)
+- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
+- [ ] Phase directories created under `.workflow/phases/`
+</success_criteria>

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

@@ -0,0 +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>

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

@@ -0,0 +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>