maestro-flow-one 0.2.6 → 0.2.7

package/maestro-flow/agents/impeccable-agent.md

@@ -0,0 +1,99 @@
+---
+name: impeccable-agent
+description: Autonomous executor for non-interactive impeccable commands. Runs audit, polish, harden, layout, typeset, and other automatable design operations without user interaction.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Skill
+---
+
+# Impeccable Agent
+
+Autonomous design operations agent. Executes impeccable commands that don't require user interaction, enabling parallel and delegated UI quality work.
+
+## Allowed Commands
+
+Commands are classified by interaction level. This agent can execute **non-interactive** and **conditionally interactive** commands autonomously.
+
+### Non-Interactive (always safe to execute)
+
+| Command | Category | What it does |
+|---------|----------|-------------|
+| audit | Evaluate | Technical quality checks, produces score |
+| critique | Evaluate | UX review with heuristic scoring, produces score + findings |
+| polish | Refine | Final quality pass, applies fixes |
+| harden | Refine | Production edge cases: errors, i18n, overflow |
+| onboard | Refine | First-run flows, empty states |
+| typeset | Enhance | Improve typography hierarchy |
+| layout | Enhance | Fix spacing, rhythm, visual hierarchy |
+| adapt | Fix | Responsive/device adaptations |
+| optimize | Fix | UI performance fixes |
+| clarify | Fix | Improve UX copy and labels |
+| explore | Build | Multi-style comparison (auto-selects variant 1 in agent mode) |
+
+### Conditionally Interactive (safe with sufficient context)
+
+These commands ask questions only "if unclear from codebase". When PRODUCT.md and DESIGN.md exist, they typically run without interaction.
+
+| Command | Category | Condition for autonomy |
+|---------|----------|----------------------|
+| bolder | Refine | PRODUCT.md exists (personality context available) |
+| quieter | Refine | PRODUCT.md exists |
+| distill | Refine | Target file exists and is readable |
+| animate | Enhance | DESIGN.md exists (motion context available) |
+| colorize | Enhance | DESIGN.md exists (color palette available) |
+| delight | Enhance | PRODUCT.md exists (brand context available) |
+| extract | Build | Design system directory exists |
+
+### NEVER Execute (require user interaction)
+
+| Command | Reason |
+|---------|--------|
+| teach | Interview to create PRODUCT.md |
+| shape | Discovery interview + brief confirmation |
+| craft | Multiple user gates |
+| live | Interactive browser session |
+| overdrive | Requires explicit user creative vision |
+| document | Requires creative input for design system |
+
+## Execution Protocol
+
+1. **Load context**: Run `maestro impeccable load-context` to load PRODUCT.md and DESIGN.md
+2. **Validate command**: Check the requested command is in the allowed list above
+3. **Execute**: `Skill({ skill: "maestro-impeccable", args: "{command} {target} --skip-harvest -y" })`
+   - Always pass `-y` to auto-confirm where the skill allows
+   - Pass `--skip-harvest` — the caller handles harvest if needed
+4. **Report**: Return the command output (scores, changes made, findings)
+
+## Usage Pattern
+
+The agent receives a prompt describing which impeccable command(s) to run and on what target:
+
+```
+Run impeccable audit on src/pages/ then polish any P0 findings.
+```
+
+```
+Run critique on src/components/dashboard.html and report the score.
+```
+
+```
+Run these commands sequentially on src/pages/landing.html:
+1. layout
+2. typeset
+3. polish
+```
+
+## Multi-Command Sequences
+
+When given multiple commands, execute sequentially. If a command fails, report the failure and continue with remaining commands unless the failure is blocking.
+
+## Context Requirements
+
+- `.workflow/impeccable/PRODUCT.md` should exist for conditionally interactive commands
+- `.workflow/impeccable/DESIGN.md` should exist for color/typography-aware commands
+- If either is missing, restrict to non-interactive commands only

package/maestro-flow/commands/lifecycle/analyze.md

@@ -79,7 +79,7 @@ Phase 4: Output context.md for downstream plan --gaps
 **Next-step routing on completion:**
 
 Phase/Milestone scope:
-- Go recommendation, UI work needed → `/maestro-ui-design {phase}`
+- Go recommendation, UI work needed → `/maestro-ui-craft --chain build {target}`
 - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
 - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
 
@@ -129,5 +129,5 @@ Both modes (full + quick):
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
 - [ ] Artifact registered in state.json with correct scope/milestone/phase
-- [ ] Next step routed (ui-design/plan for Go, brainstorm for No-Go)
+- [ ] Next step routed (ui-craft/plan for Go, brainstorm for No-Go)
 </success_criteria>

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -1,112 +1,116 @@
----
-name: maestro-brainstorm
-description: Brainstorm with auto pipeline or single-role analysis
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/brainstorm.md
-</required_reading>
-
-<deferred_reading>
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
-- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
-
-**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
-**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
-**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
-**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
-| E002 | error | No active session for single role mode | Guide user to run auto mode first |
-| E003 | error | Invalid role name | Show valid roles list |
-| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
-| W002 | warning | Project context (.workflow/) not found | Continue without project context |
-| W003 | warning | Role template not found | Use generic analysis structure |
-| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
-| W005 | warning | External research agent failed | Continue without designResearchContext |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
-- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
-- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
-- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists AND exactly one of `html-prototypes/` / `ascii-mockups/` / `api-sketches/` exists with `README.md` + ≥1 prototype file
-- [ ] ui-designer/analysis.md references each prototype via `@-notation`
-- [ ] HTML prototypes are self-contained (no external `<link>`/`<script src>` URLs — warn only)
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] UI-bearing feature specs reference the corresponding prototype in Section 3 (Interface Contract)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-- [ ] Confidence scored per role completion and after cross-role analysis
-- [ ] Readiness gate checked before spec generation
-- [ ] Pressure pass completed on at least 1 feature spec
-- [ ] Confidence summary appended to synthesis-changelog.md
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Brainstorm with auto pipeline or single-role analysis
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-ui-craft <feature-description> --chain build` to build with the established design system"
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+- [ ] Confidence scored per role completion and after cross-role analysis
+- [ ] Readiness gate checked before spec generation
+- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Confidence summary appended to synthesis-changelog.md
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/maestro-flow/commands/lifecycle/composer.md

@@ -35,6 +35,11 @@ $ARGUMENTS — natural language description, or flags.
 - Design drafts: `.workflow/templates/design-drafts/`
 - Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
 - Max nodes: 20
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
 </context>
 
 <state_machine>

package/maestro-flow/commands/lifecycle/impeccable.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-impeccable
-description: Production-grade UI design with knowhow accumulation — 23 commands for build, evaluate, refine, enhance, fix
-argument-hint: "<command> [target] [--skip-harvest] [-y]"
+description: Production-grade UI design with knowhow accumulation — 24 commands + integrated design search for build, evaluate, refine, enhance, fix
+argument-hint: "<command> [target] [--skip-harvest] [-y] | search <query> [-d <domain>] [--design-system]"
 allowed-tools:
   - Read
   - Write
@@ -13,13 +13,17 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Replaces impeccable as the primary UI design entry point. 23 commands covering the full design lifecycle:
-Build (craft, shape, teach, document, extract), Evaluate (critique, audit), Refine (polish, bolder, quieter, distill, harden, onboard),
+Replaces impeccable as the primary UI design entry point. 24 commands covering the full design lifecycle:
+Build (craft, shape, teach, document, extract, explore), Evaluate (critique, audit), Refine (polish, bolder, quieter, distill, harden, onboard),
 Enhance (animate, colorize, typeset, layout, delight, overdrive), Fix (clarify, adapt, optimize), Iterate (live).
 
 Core innovation over impeccable: after each command execution, automatically harvests design decisions
 into `.workflow/knowhow/` (DCS-, AST-, TIP-, REF-) for cross-session accumulation. Other maestro commands
 consume this via `category: coding` auto-injection and keyword matching.
+
+Includes integrated `search` CLI subcommand for querying the UI/UX design knowledge base
+(BM25 search engine + 30+ CSV data files covering styles, colors, typography, UX guidelines, charts, stacks).
+Search is invoked directly via `maestro impeccable search`, not through the Skill dispatch.
 </purpose>
 
 <deferred_reading>
@@ -29,11 +33,11 @@ consume this via `category: coding` auto-injection and keyword matching.
 <context>
 $ARGUMENTS — sub-command + target + optional flags.
 
-**Sub-commands** (23):
+**Sub-commands** (24):
 
 | Category | Commands |
 |----------|----------|
-| Build | craft, shape, teach, document, extract |
+| Build | craft, shape, teach, document, extract, explore |
 | Evaluate | critique, audit |
 | Refine | polish, bolder, quieter, distill, harden, onboard |
 | Enhance | animate, colorize, typeset, layout, delight, overdrive |
@@ -51,7 +55,23 @@ and writes knowhow entries. DCS-/AST- types also get spec index entries for disc
 
 <execution>
 
-## 1. Invoke Skill
+## 1. Route
+
+If first argument is `search` → direct CLI dispatch (no Skill, no harvest):
+
+```bash
+maestro impeccable search "<query>" [options]
+```
+
+Options: `-d <domain>`, `-s <stack>`, `-n <max>`, `--design-system`, `-p <name>`, `-f <fmt>`, `--persist`, `--page <page>`, `-o <dir>`
+
+Domains: style, color, chart, landing, product, ux, typography, icons, react, web, google-fonts.
+Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, html-tailwind, shadcn, + more.
+
+Search uses `workflows/impeccable/ui-search/search.py` (BM25 engine + 30+ CSV knowledge files).
+Output goes to stdout. No Skill invocation, no harvest. Return after output.
+
+## 2. Invoke Skill (all other sub-commands)
 
 ```
 Skill({ skill: "maestro-impeccable", args: "$ARGUMENTS" })
@@ -60,7 +80,7 @@ Skill({ skill: "maestro-impeccable", args: "$ARGUMENTS" })
 The skill handles: context loading (spec load --category ui, with load-context fallback), register detection (brand/product),
 reference file loading, and command execution.
 
-## 2. Harvest
+## 3. Harvest
 
 After the skill completes, read `~/.maestro/workflows/impeccable.md` and follow the harvest workflow.
 
@@ -69,12 +89,29 @@ Skip harvest if:
 - Sub-command is `live` (interactive, no harvestable output)
 - Sub-command is unrecognized
 
+## 4. Post-Execution Routing
+
+After harvest (or skip), determine whether this command was invoked as part of a larger pipeline by checking conversation context (e.g., brainstorm Step 3.5, ui-craft chain step).
+
+**Pipeline context detected** (called via Skill from brainstorm, ui-craft, etc.):
+- Report command result (output, scores, artifacts produced) and **stop**
+- Do NOT suggest next-step commands — the calling flow owns what happens next
+
+**Standalone invocation** (user directly ran `/maestro-impeccable`):
+- Show next-step suggestions based on what was executed:
+  - `teach` → suggest `explore` or `shape`
+  - `explore` → suggest `shape` → `craft`
+  - `shape` → suggest `craft`
+  - `craft` → suggest `critique`
+  - `critique`/`audit` → suggest commands from findings
+  - Enhancement/fix commands → suggest `critique` to re-evaluate
+
 </execution>
 
 <error_codes>
 | Code | Severity | Description |
 |------|----------|-------------|
-| E001 | error | Invalid sub-command (not in 23 valid commands) |
+| E001 | error | Invalid sub-command (not in 24 valid commands) |
 | E002 | error | No intent or target specified |
 | W001 | warning | Harvest failed — design knowledge not captured (command still succeeded) |
 | W002 | warning | PRODUCT.md missing — skill will auto-trigger teach |

package/maestro-flow/commands/lifecycle/merge.md

@@ -31,6 +31,9 @@ Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequen
 <execution>
 Follow '~/.maestro/workflows/merge.md' completely.
 
+**Knowledge inquiry on completion:**
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2>")`.
+
 **Next-step routing on completion:**
 - View dashboard → Skill({ skill: "manage-status" })
 - Audit milestone → Skill({ skill: "maestro-milestone-audit" })

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -69,6 +69,10 @@ maestro-plan → maestro-execute → maestro-verify
 ```
 
 **Note (full mode):** `maestro-init` MUST run before `--mode full`. It creates the `.workflow/` directory and project context.
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
+2. Optional — proceed without if unavailable.
 </context>
 
 <execution>
@@ -100,7 +104,7 @@ Follow `~/.maestro/workflows/spec-generate.md` completely.
 |-----------|-----------|
 | Roadmap approved, need analysis | /maestro-analyze 1 |
 | Simple project, ready to plan | /maestro-plan 1 |
-| Need UI design first | /maestro-ui-design 1 |
+| Need UI design first | /maestro-ui-craft --chain build |
 | View project dashboard | /manage-status |
 | Need project setup (full mode) | /maestro-init |
 </execution>

package/maestro-flow/commands/lifecycle/ui-craft.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-ui-craft
 description: Chain maestro-impeccable commands with intelligent routing and quality gate loops for automated UI production
-argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [-y] [-c]"
+argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [--skip-design-explore] [--skip-design] [--styles <N>] [--stack <stack>] [-y] [-c]"
 allowed-tools:
   - Read
   - Write
@@ -22,11 +22,20 @@ Core innovation: critique/audit scores drive automatic command selection and ite
 Impeccable has 23 commands across 6 categories — this command chains them into automated pipelines
 with quality gates that loop until design quality meets the threshold.
 
+Includes integrated design-explore: multi-variant design system generation (via ui-search BM25 engine + CSV knowledge base),
+HTML prototype rendering for visual comparison, interactive user review with mix support,
+and automatic bridge to impeccable's DESIGN.md format. Replaces the former maestro-ui-design command.
+
 Prerequisite: maestro-impeccable skill available (auto-discovered by harness).
 
 Session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
 
+<deferred_reading>
+- [impeccable harvest workflow](~/.maestro/workflows/impeccable.md) — read after command execution for harvest logic
+- [design stage workflow](~/.maestro/workflows/impeccable/design.md) — read when S_DESIGN_EXPLORE or S_BRIDGE state entered
+</deferred_reading>
+
 <invariants>
 1. **Session before execution** — status.json created before any chain step runs
 2. **All steps via Skill** — every impeccable command dispatched through `Skill({ skill: "maestro-impeccable" })`
@@ -46,6 +55,9 @@ $ARGUMENTS — intent description or target path, with optional flags.
 - `--max-loops <n>` — Maximum quality gate iterations (default: 3)
 - `-c` / `--continue` — Resume previous ui-craft session
 - `-y` — Auto mode: auto-select at ambiguous routing, skip confirmations where impeccable allows
+- `--skip-design-explore` / `--skip-design` — Skip design-explore (prototype comparison) and bridge (use existing DESIGN.md or full shape interview)
+- `--styles <N>` — Number of design system variants to generate and compare (2-5, default 3). Only used in build chain design-explore step
+- `--stack <stack>` — Tech stack for supplementary guidelines (default: html-tailwind). Passed to ui-search
 </context>
 
 <chains>
@@ -54,13 +66,14 @@ $ARGUMENTS — intent description or target path, with optional flags.
 
 | Chain | Sequence | Gate Condition |
 |-------|----------|----------------|
-| **build** | teach? → shape → craft → **critique** → [refine loop] → audit → polish | critique ≥ threshold AND P0 == 0 |
+| **build** | teach? → **design_explore?** → shape → craft → **critique** → [refine loop] → audit → polish | critique ≥ threshold AND P0 == 0 |
 | **improve** | **critique** → [refine loop] → polish → audit | critique ≥ threshold AND P0 == 0 |
 | **enhance** | {cmd} → **critique** → polish (if needed) | critique ≥ threshold |
 | **harden** | harden → **audit** → polish | audit ≥ threshold×0.5 |
 | **live** | live | — (interactive, no gate) |
 
 - `teach?` — conditional: only if PRODUCT.md missing/placeholder
+- `design_explore?` — conditional: only if DESIGN.md missing AND `--skip-design-explore` not set. Delegates to `Skill("maestro-impeccable", "explore")` which handles variant generation, prototype rendering, visual comparison, user selection/mix, AND bridge to DESIGN.md internally
 - `[refine loop]` — quality gate loop: extract suggested commands from critique → execute → re-critique
 
 ### Intent → Chain Routing
@@ -68,6 +81,7 @@ $ARGUMENTS — intent description or target path, with optional flags.
 | Intent Pattern | Chain |
 |---------------|-------|
 | 新建, create, build, new, 从零, landing, feature, page | build |
+| 设计, design, 风格, style, 设计系统, design system, 视觉, theme | build |
 | 改进, improve, fix, 优化, iterate, better, 迭代 | improve |
 | 动画, 颜色, 排版, animate, color, type, bold, delight, enhance | enhance |
 | 生产, production, harden, 上线, ship, edge case, i18n | harden |
@@ -84,6 +98,7 @@ S_PARSE      — 解析参数、意图分类、chain 选择                PERSI
 S_RESUME     — 扫描已有 ui-craft session、恢复执行           PERSIST: —
 S_SETUP      — 加载 context、检查 PRODUCT.md                PERSIST: —
 S_CREATE     — 创建 session + status.json                    PERSIST: session (全量)
+S_DESIGN_EXPLORE — 委托 impeccable explore：多变体生成、原型对比、选型/混搭、自动 bridge 到 DESIGN.md  PERSIST: explore_completed, design_md_path
 S_CHAIN      — 按序执行 chain 步骤                           PERSIST: step progress, executed commands
 S_GATE       — 质量门控：解析评分、决策                       PERSIST: scores, loop count
 S_REFINE     — 执行自动选取的 refine 命令                    PERSIST: refine commands, loop state
@@ -109,10 +124,16 @@ S_CREATE:
   → S_CHAIN      DO: A_CREATE_SESSION
 
 S_CHAIN:
+  → S_DESIGN_EXPLORE  WHEN: current step is 'design_explore' AND DESIGN.md missing AND --skip-design-explore not set AND --skip-design not set
   → S_GATE       WHEN: current step is gate command (critique/audit)
+  → S_CHAIN      WHEN: step is design_explore but skip conditions met → advance
   → S_CHAIN      WHEN: step is normal command → execute → advance
   → S_REPORT     WHEN: all steps complete
 
+S_DESIGN_EXPLORE:
+  → S_CHAIN      WHEN: explore completed (DESIGN.md produced) → advance to shape
+  → S_CHAIN      WHEN: explore failed → W004 → advance to shape (full interview fallback)
+
 S_GATE:
   → S_CHAIN      WHEN: PASS (score ≥ threshold AND P0 == 0) → advance to next step
   → S_REFINE     WHEN: FAIL (score < threshold OR P0 > 0)
@@ -160,6 +181,15 @@ S_REPORT:
    ```
 3. Write status.json before executing any step
 
+### A_DESIGN_EXPLORE
+
+Delegate to impeccable explore as a black-box command. The explore command internally handles:
+variant generation, prototype rendering, visual comparison, user review, mix protocol, rejected variant harvest, bridge to DESIGN.md, and spec registration.
+
+1. Execute: `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
+2. On completion: verify `.workflow/impeccable/DESIGN.md` exists
+3. Update status.json: `explore_completed: true`, `design_md_path`
+
 ### A_FINAL_REPORT
 
 1. Read critique trend if available (impeccable's critique persists snapshots automatically)
@@ -205,11 +235,26 @@ Execute via: `Skill({ skill: "maestro-impeccable", args: "{command} {target}" })
 
 After each step: update status.json `current_step` and step `status`.
 
-**Rules:**
+**Step-specific logic:**
+
+### 4a. Design-explore step (build chain only)
+
+When current step is `design_explore`:
+
+1. Check if `.workflow/impeccable/DESIGN.md` already exists → skip, advance to shape
+2. Check if `--skip-design-explore` or `--skip-design` is set → skip, advance to shape
+3. Otherwise → execute A_DESIGN_EXPLORE:
+   - `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
+   - explore handles everything internally: variant generation, prototype rendering, visual comparison, user selection/mix, bridge to DESIGN.md, spec registration
+4. On completion → verify DESIGN.md exists, advance to shape
+5. On failure → W004, advance to shape (full interview fallback, no DESIGN.md)
+
+### 4c. Normal steps
+
 - `teach`, `shape`, `craft` are interactive — do NOT suppress their user gates
 - After `teach` completes → re-run context loader for fresh PRODUCT.md
 - After `craft` completes → the build exists, ready for evaluation
-- Gate steps (critique/audit) → transition to quality gate logic
+- Gate steps (critique/audit) → transition to quality gate logic (Section 5)
 
 ## 5. Quality Gate
 
@@ -335,6 +380,8 @@ These are structural/interactive — never picked by the refine loop:
 | overdrive | Requires explicit user vision |
 | critique | Gate command, not a fix |
 | audit | Gate command, not a fix |
+| design | Design system generation (setup) |
+| bridge | Format bridging (setup) |
 
 </quality_gate_routing>
 
@@ -349,6 +396,11 @@ These are structural/interactive — never picked by the refine loop:
 | W001 | warning | PRODUCT.md missing, prepending teach to chain |
 | W002 | warning | Max quality gate loops exceeded, forcing continue |
 | W003 | warning | Could not parse score from critique/audit output |
+| E006 | error | Python 3 not available for design system generation |
+| E007 | error | ui-search scripts not found at expected path |
+| W004 | warning | Design system generation failed, skipping design+bridge, falling back to shape full interview |
+| W005 | warning | Bridge transformation failed, continuing without DESIGN.md |
+| W008 | warning | Node.js not available for prototype rendering, falling back to text-only variant comparison |
 </error_codes>
 
 <success_criteria>

package/maestro-flow/commands/manage/issue-discover.md

@@ -48,6 +48,10 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 **State files:**
 - `.workflow/issues/issues.jsonl` -- issues appended here
 - `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
+
+### Pre-load specs
+1. **Debug specs**: Run `maestro spec load --category debug` to load known antipatterns, root causes, and gotchas. Informs discovery perspectives with prior findings.
+2. Optional — proceed without if unavailable.
 </context>
 
 <execution>

package/maestro-flow/commands/quality/refactor.md

@@ -41,6 +41,9 @@ If not provided, prompt user for scope.
 <execution>
 Follow '~/.maestro/workflows/refactor.md' completely.
 
+**Knowledge inquiry on completion:**
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2>")`.
+
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
 - Test failures after refactor → `/quality-debug {scope}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"

package/maestro-flow/commands/lifecycle/ui-design.md

@@ -1,104 +0,0 @@
----
-name: maestro-ui-design
-description: Generate UI design prototypes, select and solidify as code
-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, workflow routing, scope modes, and output artifacts defined in the routed workflow (ui-style.md or ui-design.md).
-
-**Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
-**Scratch mode** (text): creates `.workflow/scratch/{YYYYMMDD}-ui-design-{slug}/` for standalone exploration.
-</context>
-
-<execution>
-## 1. Load UI Specs
-
-Load project UI conventions before generating designs:
-
-```bash
-maestro spec load --category ui
-```
-
-If specs not initialized, continue without — the workflow still produces valid output.
-
-## 2. Workflow Routing
-
-Detect ui-ux-pro-max skill availability and route to the appropriate workflow:
-
-- **`--full` flag present** → Follow '~/.maestro/workflows/ui-design.md' completely (forced full pipeline)
-- **ui-ux-pro-max found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight delegation)
-- **ui-ux-pro-max not found** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained fallback)
-
-Skill detection logic, report format, and complete pipeline steps defined in the routed workflow file.
-
-**Next-step routing on completion:**
-- Plan with design reference → /maestro-plan {phase}
-- Refine selected design → /maestro-ui-design {phase} --refine
-- Analyze before planning → /maestro-analyze {phase}
-</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):**
-- [ ] UI specs loaded via `spec load --category ui` (if available)
-- [ ] 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>