maestro-flow 0.3.48 → 0.4.1

package/.claude/commands/maestro-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 — 24 commands + chain orchestration with quality gates + design search
+argument-hint: "<command|chain|intent> [target] [flags]"
 allowed-tools:
   - Read
   - Write
@@ -9,81 +9,238 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Skill
+  - Agent
   - AskUserQuestion
+  - TodoWrite
 ---
+
 <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),
-Enhance (animate, colorize, typeset, layout, delight, overdrive), Fix (clarify, adapt, optimize), Iterate (live).
+UI design command. Parse input → prerequisites → read workflow file → execute → track.
 
-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.
+- **Direct**: single command via workflow file
+- **Chain**: orchestrate command sequence with quality gates
+- **Search**: query design knowledge base via CLI
 </purpose>
 
-<deferred_reading>
-- [impeccable harvest workflow](~/.maestro/workflows/impeccable.md) — read after command execution for harvest logic
-</deferred_reading>
-
-<context>
-$ARGUMENTS — sub-command + target + optional flags.
-
-**Sub-commands** (23):
-
-| Category | Commands |
-|----------|----------|
-| Build | craft, shape, teach, document, extract |
-| Evaluate | critique, audit |
-| Refine | polish, bolder, quieter, distill, harden, onboard |
-| Enhance | animate, colorize, typeset, layout, delight, overdrive |
-| Fix | clarify, adapt, optimize |
-| Iterate | live |
-
-**Flags:**
-- `--skip-harvest` — Execute command without knowhow capture
-- `-y` — Auto-confirm where the skill allows
-
-**Harvest behavior**: After command completion, the harvest workflow extracts design decisions
-and writes knowhow entries. DCS-/AST- types also get spec index entries for discoverability.
-`live` command is exempt (too ephemeral). Use `--skip-harvest` to suppress.
-</context>
-
-<execution>
-
-## 1. Invoke Skill
-
-```
-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
-
-After the skill completes, read `~/.maestro/workflows/impeccable.md` and follow the harvest workflow.
-
-Skip harvest if:
-- `--skip-harvest` flag is set
-- Sub-command is `live` (interactive, no harvestable output)
-- Sub-command is unrecognized
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | Invalid sub-command (not in 23 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 |
-</error_codes>
-
-<success_criteria>
-- [ ] Sub-command recognized and routed to maestro-impeccable skill
-- [ ] Skill executed with context (spec load --category ui or load-context fallback, register identified)
-- [ ] Design changes applied to target files
-- [ ] Knowhow entry created in .workflow/knowhow/ (unless --skip-harvest or live)
-- [ ] Spec index entry created for DCS-/AST- types
-</success_criteria>
+## Input
+
+$ARGUMENTS first word determines mode:
+
+| First Word | Mode |
+|------------|------|
+| Known command (see routing table) | Direct |
+| Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain |
+| continue / next / -c | Resume |
+| search | Search: `maestro impeccable search "$REST"` |
+| Free text (concrete task) | Direct craft — has specific target + specs/reference |
+| Free text (project intent) | Intent → classify → chain |
+| (empty) | Menu: show commands by category |
+
+## Command Routing
+
+All workflows at `~/.maestro/workflows/impeccable/{command}.md`:
+
+| Command | Category | Description |
+|---------|----------|-------------|
+| craft | Build | Shape then build end-to-end — full page/component implementation |
+| shape | Build | Plan UX/UI before code — information architecture, wireframe, visual direction |
+| teach | Build | Set up PRODUCT.md — users, brand, tone, anti-references, principles |
+| document | Build | Generate DESIGN.md from existing code — extract tokens, typography, colors |
+| extract | Build | Pull tokens/components into reusable design system |
+| explore | Build | Multi-style comparison — generate variants, render prototypes, visual compare, select/mix |
+| critique | Evaluate | UX heuristic review with Nielsen scoring (/40) + P0/P1 findings |
+| audit | Evaluate | Technical quality checks — a11y, performance, responsive, code quality (/20) |
+| polish | Refine | Final quality pass — micro-adjustments, pixel perfection |
+| bolder | Refine | Amplify bland/safe designs — stronger personality, more contrast |
+| quieter | Refine | Tone down aggressive/overwhelming designs — reduce visual noise |
+| distill | Refine | Strip to essence — remove clutter, reduce cognitive load |
+| harden | Refine | Production-ready — error states, i18n, edge cases, overflow, empty states |
+| onboard | Refine | First-run flows, empty states, activation paths, progressive disclosure |
+| animate | Enhance | Add purposeful motion — transitions, micro-interactions, scroll effects |
+| colorize | Enhance | Add strategic color — OKLCH palette, contrast, color strategy |
+| typeset | Enhance | Improve typography — scale, hierarchy, font pairing, line length |
+| layout | Enhance | Fix spacing, rhythm, visual hierarchy, alignment, grid |
+| delight | Enhance | Add personality — memorable details, joy, surprise moments |
+| overdrive | Enhance | Push past conventional limits — ambitious visual effects |
+| clarify | Fix | Improve UX copy — labels, error messages, microcopy, CTAs |
+| adapt | Fix | Adapt for devices/screens — responsive, touch targets, breakpoints |
+| optimize | Fix | Fix UI performance — loading, rendering, bundle, paint/layout jank |
+| live | Iterate | Browser-based variant iteration — real-time design in DevTools |
+
+Reference files (loaded by workflow as needed, not standalone commands):
+brand.md, product.md, design.md, codex.md, heuristics-scoring.md, cognitive-load.md,
+color-and-contrast.md, interaction-design.md, motion-design.md, personas.md,
+responsive-design.md, spatial-design.md, typography.md, ux-writing.md
+
+## Chains
+
+| Chain | Steps | Scenario |
+|-------|-------|----------|
+| build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | 从零新建 |
+| redesign | document → explore → shape → craft → critique → [refine] → audit → polish | 基于现有代码重设计 |
+| improve | critique → [refine] → polish → audit | 迭代改进 |
+| enhance | {cmd...} → critique → [refine] → polish | 定向增强（支持多命令） |
+| launch | harden → adapt → optimize → audit → polish | 全方位上线准备 |
+| harden | harden → audit → polish | 边界加固 |
+| foundation | teach? → explore → document → extract | 纯设计系统建设 |
+| live | live | 实时迭代 |
+
+- `?` = conditional: teach if PRODUCT.md missing; explore if DESIGN.md missing and --skip-design not set
+- `[refine]` = quality gate loop: gate fails → auto-select fix commands from findings → re-gate
+- `{cmd...}` = enhance 支持多命令，逗号分隔：`enhance colorize,typeset landing-page`
+
+Chain flags: --threshold <N> (default 26/40), --max-loops <N> (default 3), --skip-design, --styles <N>, -y
+
+## Free Text Routing
+
+Free text 按优先级三层匹配。命中即停，不继续向下。
+
+### Layer 1: 意图匹配单个命令 → Direct
+
+将用户描述与 Command Routing 表的 Description 列语义匹配。匹配最接近的**一个**命令。
+
+| Intent signal | Command |
+|---------------|---------|
+| 评审, review, 检查UX, 评分, heuristic | critique |
+| 审计, a11y, 可访问性, 技术检查, performance audit, 代码质量 | audit |
+| 加动画, 动效, transitions, micro-interactions, 过渡 | animate |
+| 配色, 颜色, palette, 色彩, OKLCH, contrast | colorize |
+| 字体, 排版, typography, font, 字号, 行高 | typeset |
+| 布局, 间距, spacing, grid, 对齐, alignment, 视觉层次 | layout |
+| 太花, 太吵, tone down, 视觉噪音, 简洁点 | quieter |
+| 太平淡, 加强, 更大胆, more personality, 更有个性 | bolder |
+| 太复杂, 简化, strip, 去掉多余, cognitive load | distill |
+| 打磨, 微调, pixel perfect, final pass, 最终润色 | polish |
+| 文案, copy, 标签, 错误提示, UX writing, microcopy | clarify |
+| 响应式, mobile, 适配, breakpoints, touch targets | adapt |
+| 性能, loading, bundle, 卡顿, jank, 速度 | optimize |
+| 边界, error states, i18n, 溢出, 空状态加固 | harden |
+| 引导, 新手, 首次使用, onboarding, empty state, 激活 | onboard |
+| 趣味, 惊喜, personality, memorable, joy | delight |
+| 炫酷, 极限, extraordinary, 超常规, 技术极限 | overdrive |
+| 规划, plan UX, wireframe, 信息架构, 视觉方向 | shape |
+| 多风格, 变体, variants, compare styles, 风格对比 | explore |
+| 品牌定义, PRODUCT.md, 产品上下文 | teach |
+| 提取设计, DESIGN.md, 设计文档化 | document |
+| 提取组件, pull tokens, 设计系统提取 | extract |
+| 实时, browser iteration, 浏览器迭代 | live |
+
+### Layer 2: 具体构建任务 → Direct craft
+
+Layer 1 未命中，但意图是"构建/创建某个具体东西"：
+- 包含具体文件路径或目标（`d:\path`, `src/pages/`, `index.html`）
+- 包含详细视觉规格（布局、风格、配色方案）
+- 包含参考素材（`参考...`, `based on...`, `like...`）
+
+→ 路由到 **craft**（Direct）
+
+### Layer 3: 项目意图 → Chain
+
+Layer 1+2 未命中，意图是泛泛的项目方向：
+
+| Pattern | Chain |
+|---------|-------|
+| 新建, create, build, new, 从零开始 | build |
+| 重做, redesign, 重新设计, rethink, 换风格, 改版 | redesign |
+| 改进, improve, iterate, better, 迭代 | improve |
+| 增强, enhance, 视觉升级, visual upgrade | enhance |
+| 上线, launch, deploy, ship, 发布准备, production-ready | launch |
+| 加固, harden, 生产化, 边界情况 | harden |
+| 设计系统, design system, tokens, 设计规范, 设计基建 | foundation |
+| 实时, live, browser | live |
+
+Ambiguous + no `-y` → AskUserQuestion.
+
+## Prerequisites
+
+Before reading any command workflow:
+
+1. **Context**: `maestro spec load --category ui` → if empty → `maestro impeccable load-context`
+2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → execute teach first, then resume original task
+3. **Register**: identify brand/product → Read `~/.maestro/workflows/impeccable/{brand|product}.md`
+
+## Direct Execution
+
+1. Prerequisites ✓
+2. **显示执行信息**：
+   ```
+   ── Command: {command} ────────────────────
+   Category: {category} | Target: {target}
+   ─────────────────────────────────────────
+   ```
+3. Read `~/.maestro/workflows/impeccable/{command}.md`
+4. **TodoWrite 跟踪**：按 workflow 文件中的主要阶段创建 todo 项
+   - 格式：`[{command}] {phase description}`
+   - 每个阶段完成后立即标记 completed
+5. Follow workflow file instructions
+6. Post: suggest logical next command (teach→shape, shape→craft, craft→critique, etc.)
+
+## Chain Execution
+
+1. Prerequisites ✓
+2. **显示执行链**：解析 chain 定义，输出完整步骤预览：
+   ```
+   ── Chain: build ──────────────────────────
+    1. teach        (conditional: PRODUCT.md missing)
+    2. explore      (conditional: DESIGN.md missing)
+    3. shape
+    4. craft
+    5. critique     ◆ quality gate (threshold: 26/40)
+    6. [refine]     ↺ auto-fix loop (max: 3)
+    7. audit        ◆ quality gate (threshold: 14/20)
+    8. polish
+   ─────────────────────────────────────────
+   Target: {target}
+   ```
+   - `◆` 标记 quality gate 步骤，显示阈值
+   - `↺` 标记 refine loop，显示最大循环次数
+   - conditional 步骤注明触发条件
+   - 跳过的 conditional 步骤标记 `(skipped)`
+3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+   ```json
+   { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
+     "gate_history": [], "loop_count": 0, "status": "running" }
+   ```
+4. **TodoWrite 初始化**：为 chain 所有步骤创建 todo 项
+   - 每步一项，格式：`[chain] step N: {command} — {description}`
+   - conditional 步骤若跳过，立即标记 completed
+   - quality gate 步骤标注阈值：`[chain] step 5: critique ◆ gate ≥26/40`
+5. For each step:
+   - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
+   - **步骤开始**：TodoWrite 标记当前步骤 in_progress
+   - **步骤完成**：TodoWrite 标记 completed + update status.json (`current_step`, step `status`)
+   - **步骤失败**：TodoWrite 标记 completed(with note) + 记录原因
+6. **Quality gate** (critique/audit steps):
+   - Parse score: critique `**Total** | | **N/40**`, audit `**Total** | | **N/20**`
+   - Count `[P0]` / `[P1]` tags
+   - Pass: score ≥ threshold AND P0 == 0 → advance
+   - Fail: collect suggested commands from findings → execute → re-gate
+   - Max loops exceeded → force advance with warning
+   - TodoWrite：gate 结果记入当前步骤备注（score, P0/P1 count, pass/fail）
+7. Final report: scores + trend + commands executed
+
+## Resume
+
+Scan `.workflow/.maestro/ui-craft-*/status.json` for `status == "running"` → most recent → resume from `current_step`.
+
+## Quality Gate — Finding → Command Fallback
+
+When findings lack explicit suggested command:
+
+| Finding Category | Command |
+|-----------------|---------|
+| Layout, spacing, hierarchy, alignment | layout |
+| Color, contrast, palette | colorize |
+| Typography, font, readability | typeset |
+| Animation, motion, transitions | animate |
+| Copy, labels, UX writing | clarify |
+| Responsive, mobile, breakpoints | adapt |
+| Performance, loading, speed | optimize |
+| Complexity, overload, clutter | distill |
+| Bland, safe, generic | bolder |
+| Aggressive, overwhelming | quieter |
+| Onboarding, empty state | onboard |
+| Edge cases, i18n, error handling | harden |
+| Personality, memorability | delight |
+
+Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.

package/.claude/commands/maestro-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/.claude/commands/maestro-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-impeccable build |
 | View project dashboard | /manage-status |
 | Need project setup (full mode) | /maestro-init |
 </execution>

package/.claude/commands/maestro.md

@@ -119,8 +119,8 @@ S_FALLBACK:
 ### A_CLASSIFY_INTENT
 
 1. Read `~/.maestro/workflows/maestro.md` from deferred_reading
-2. Classify intent via keyword heuristics + detectTaskType/detectNextAction
-3. Select/compose command chain from chainMap
+2. Match intent to best task_type via chain catalog (semantic, AI-driven)
+3. Select chain from chainMap
 4. Determine per-step type: `internal` (Skill) or `external` (delegate)
 
 ### A_CLARIFY
@@ -155,7 +155,7 @@ S_FALLBACK:
 | maestro-analyze | `-y` | Skip scoping, auto-deepen |
 | maestro-brainstorm | `-y` | Skip questions, use defaults |
 | maestro-roadmap | `-y` | Skip questions (create/revise/review) |
-| maestro-ui-design | `-y` | Skip selection, pick top variant |
+| maestro-impeccable | `-y` | Auto-select design variant + skip confirmations |
 | maestro-plan | `-y` | Skip confirmations and clarification |
 | maestro-execute | `-y` | Skip confirmations, blocked auto-continue |
 | quality-auto-test | `-y` | Skip plan confirmation |

package/.claude/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/.claude/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/.claude/skills/maestro-help/index/catalog.json

@@ -27,7 +27,7 @@
     {"name": "maestro-ralph", "command": "/maestro-ralph", "category": "ralph", "description": "Ralph 引擎 — 自适应生命周期决策节点管理", "source": "../../commands/maestro-ralph.md"},
     {"name": "maestro-ralph-execute", "command": "/maestro-ralph-execute", "category": "ralph", "description": "Ralph 执行 — 运行自适应决策链", "source": "../../commands/maestro-ralph-execute.md"},
     {"name": "maestro-learn", "command": "/maestro-learn", "category": "core", "description": "学习 — 从执行中提取知识和模式", "source": "../../commands/maestro-learn.md"},
-    {"name": "maestro-ui-design", "command": "/maestro-ui-design", "category": "ui", "description": "UI 设计 — 设计系统原型和 Token 管理", "source": "../../commands/maestro-ui-design.md"},
+    {"name": "maestro-impeccable", "command": "/maestro-impeccable", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-impeccable.md"},
     {"name": "maestro-ui-codify", "command": "/maestro-ui-codify", "category": "ui", "description": "UI 固化 — 将设计产出转化为知识资产", "source": "../../commands/maestro-ui-codify.md"},
     {"name": "maestro-update", "command": "/maestro-update", "category": "core", "description": "版本更新 — 检查并安装最新版本", "source": "../../commands/maestro-update.md"},
     {"name": "maestro-tools-register", "command": "/maestro-tools-register", "category": "tools", "description": "MCP 工具注册 — 注册外部工具到 Maestro", "source": "../../commands/maestro-tools-register.md"},

package/.claude/skills/maestro-help/phases/01-parse-intent.md

@@ -62,7 +62,7 @@ const knownCommands = [
   "brainstorm", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
   "composer", "player", "ralph", "ralph-execute", "learn",
-  "ui-design", "ui-codify", "update",
+  "impeccable", "ui-codify", "update",
   "tools-register", "tools-execute",
   "issue", "issue-discover", "knowhow", "knowhow-capture",
   "status", "wiki", "harvest", "codebase-refresh", "codebase-rebuild",

package/.codex/skills/maestro/SKILL.md

@@ -137,39 +137,81 @@ S_FALLBACK:
 
 If matched, skip to chain resolution.
 
-**Layer 2: Structured intent extraction**
+**Layer 2: Semantic intent matching**
 
-Extract tuple from intent using LLM semantic understanding:
+Directly match user intent to the best `task_type` (maps to chain in Chain Map). Use LLM semantic understanding — no rigid keyword lookup.
+
+Extract:
 ```json
 {
-  "action":    "<create|fix|analyze|plan|execute|verify|review|test|debug|refactor|explore|manage|transition|continue|sync|learn|retrospect>",
-  "object":    "<feature|bug|issue|code|test|spec|phase|milestone|doc|performance|security|ui|memory|codebase|config>",
+  "task_type": "<from chain catalog below>",
   "scope":     "<module/file/area or null>",
-  "issue_id":  "<ISS-XXXXXXXX-NNN or null>",
-  "phase_ref": "<integer or null>",
+  "issue_id":  "<ISS-XXXXXXXX-NNN if mentioned, else null>",
+  "phase_ref": "<integer if mentioned, else null>",
   "urgency":   "<low|normal|high>"
 }
 ```
 
-Disambiguation: "问题"/"issue"/"problem" as broken → `object: "bug"` (→ debug); as tracked item (with ISS-ID or management context) → `object: "issue"` (→ issue management). When ambiguous, prefer `"bug"`.
-
-**Layer 3: action × object routing matrix**
-
-If `issue_id` present → issue pipeline directly.
-
-| action | object-specific overrides | default |
-|--------|--------------------------|---------|
-| fix | bug/code/perf/security→`debug`, issue→`issue` | `debug` |
-| create | feature→`quick`, issue→`issue`, test→`test_gen`, spec→`spec_generate`, ui→`ui_design`, config→`init` | `quick` |
-| analyze | bug/code→`analyze`, issue→`issue_analyze`, codebase→`spec_map` | `analyze` |
-| explore | issue→`issue_discover`, feature/ui→`brainstorm`/`ui_design` | `brainstorm` |
-| plan | issue→`issue_plan`, spec→`spec_generate` | `plan` |
-| execute | issue→`issue_execute` | `execute` |
-| manage | issue→`issue`, milestone→`milestone_audit`, phase→`phase_transition`, memory/doc/codebase→`memory`/`sync`/`codebase_refresh` | `status` |
-| transition | phase→`phase_transition`, milestone→`milestone_complete` | `phase_transition` |
-| verify, review, test, debug, refactor, continue, sync, learn, retrospect, release, amend, compose | — | self-named |
-
-**Clarity scoring**: 3=action+object+scope, 2=action+object, 1=action only, 0=empty.
+**Chain catalog — select by best semantic fit:**
+
+| task_type | When user intent is about... |
+|-----------|---------------------------|
+| `quick` | Simple/small task, add a feature, quick change |
+| `plan` | Plan, design, architect a phase |
+| `execute` | Implement, develop, code a phase |
+| `analyze` | Understand, investigate, evaluate code |
+| `verify` | Check goals met, validate results |
+| `review` | Code quality review |
+| `test` | Run or create tests, UAT |
+| `test_gen` | Generate tests for coverage gaps |
+| `debug` | Diagnose, troubleshoot, fix broken behavior |
+| `refactor` | Restructure, clean up, reduce tech debt |
+| `init` | Initialize project |
+| `sync` | Update/sync documentation |
+| `retrospective` | Phase review, post-mortem, 复盘 |
+| `learn` | Capture insights, record learnings |
+| `release` | Publish, ship, tag version |
+| `amend` | Revise workflow commands |
+| `compose` | Design/compose reusable workflows |
+| `overlay` | Create/edit command overlays |
+| `update` | Update maestro itself |
+| `harvest` | Extract knowledge from artifacts |
+| `wiki` | Manage wiki graph |
+| `knowhow` | Manage knowhow entries |
+| `ui_design` | UI design, build new UI |
+| `issue` | Issue CRUD — create, list, close, query |
+| `issue_discover` | Discover/find issues in codebase |
+| `issue_analyze` | Analyze a specific issue |
+| `issue_plan` | Plan fix for an issue |
+| `issue_execute` | Fix issue end-to-end (auto-upgrades to issue-full) |
+| `feature` | Standard feature: plan→execute→verify |
+| `full-lifecycle` | Complete phase: plan→execute→verify→review→test→audit→complete |
+| `brainstorm-driven` | Start from exploration/brainstorm |
+| `spec-driven` | From spec/requirements (heavy, with init) |
+| `roadmap-driven` | From requirements (light, with init) |
+| `analyze-plan-execute` | Fast track: analyze→plan→execute |
+| `execute-verify` | Resume after planning |
+| `review-fix` | Fix review-blocked issues |
+| `quality-loop` | Full quality improvement cycle |
+| `quality-loop-partial` | Partial quality fix |
+| `quality-fix` | Analyze gaps→plan→execute→verify |
+| `deploy` | Verify then release |
+| `milestone-close` | Close/transition milestone |
+| `milestone-release` | Release milestone with version tag |
+| `phase_transition` | Transition phase: audit→complete |
+| `next-milestone` | Advance to next milestone |
+| `state_continue` | Continue from current project state |
+
+**Selection priorities:**
+1. `issue_id` present → prefer issue chains
+2. UI/design/界面/页面/原型 → prefer `ui_design`
+3. Multiple lifecycle steps implied → prefer multi-step chains
+4. Single specific action → prefer single-step chains
+5. "问题" describing broken behavior → `debug`; tracked item with ISS-ID → `issue`; ambiguous → `debug`
+6. Simple task, no lifecycle context → `quick`
+7. Global fallback → `quick`
+
+**Clarity scoring**: 3=task_type+scope+phase, 2=task_type+scope, 1=task_type only, 0=empty.
 If `clarity < 2` and not `auto_mode` → transition to A_CLARIFY_INTENT.
 
 **Layer 4: State-based routing** (when `taskType === 'state_continue'`)
@@ -261,7 +303,7 @@ Read `.workflow/state.json` and route by condition:
 | `status` | `manage-status` |
 | `init` | `maestro-init` |
 | `analyze` | `maestro-analyze {phase}` |
-| `ui_design` | `maestro-ui-design {phase}` |
+| `ui_design` | `maestro-impeccable build "{phase}"` |
 | `plan` | `maestro-plan {phase}` |
 | `execute` | `maestro-execute {phase}` |
 | `verify` | `maestro-verify {phase}` |
@@ -314,7 +356,7 @@ Read `.workflow/state.json` and route by condition:
 | `deploy` | maestro-verify → maestro-milestone-release |
 | `spec-driven` | maestro-init → [B] maestro-roadmap --mode full → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
-| `ui-design-driven` | maestro-ui-design → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `next-milestone` | [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `full-lifecycle` | [B] maestro-plan → [B] maestro-execute → maestro-verify → quality-review → quality-test → maestro-milestone-audit → maestro-milestone-complete |
@@ -341,7 +383,7 @@ Read `.workflow/state.json` and route by condition:
 
 | Skill | Flag |
 |-------|------|
-| maestro-init, maestro-analyze, maestro-brainstorm, maestro-ui-design, maestro-roadmap | `-y` |
+| maestro-init, maestro-analyze, maestro-brainstorm, maestro-impeccable, maestro-roadmap | `-y` |
 | maestro-plan, maestro-execute, maestro-milestone-complete | `-y` |
 | quality-auto-test, quality-retrospective | `-y` |
 | quality-test | `-y --auto-fix` |

package/.codex/skills/maestro-brainstorm/SKILL.md

@@ -49,6 +49,7 @@ S_ROLES      — 选择 roles（-y auto / interactive）        PERSIST: —
 S_CSV_GEN    — 生成 tasks.csv                              PERSIST: tasks.csv
 S_WAVE_1     — Guidance Spec (single agent)                PERSIST: guidance-specification.md
 S_CHECK_1    — Checkpoint: 用户审阅 guidance（-y 跳过）    PERSIST: —
+S_DESIGN     — 视觉风格确定 (impeccable teach + explore)   PERSIST: DESIGN.md
 S_WAVE_2     — Role Analysis (parallel spawn)              PERSIST: role analyses
 S_CHECK_2    — Checkpoint: 用户审阅 roles（-y 跳过）       PERSIST: —
 S_WAVE_3     — Synthesis + Feature Index (single agent)    PERSIST: synthesis artifacts
@@ -63,10 +64,15 @@ S_CSV_GEN → S_WAVE_1   DO: generate tasks.csv (1 guidance + N roles + 1 synthe
 S_WAVE_1 → S_CHECK_1   WHEN: completed    DO: spawn wave-1, merge results, read guidance-spec
 S_WAVE_1 → END         WHEN: failed       DO: abort pipeline
 
-S_CHECK_1 → S_WAVE_2   WHEN: -y OR user "Proceed"
+S_CHECK_1 → S_DESIGN   WHEN: (-y OR user "Proceed") AND ui-designer in selected_roles
+S_CHECK_1 → S_WAVE_2   WHEN: (-y OR user "Proceed") AND ui-designer NOT in selected_roles
 S_CHECK_1 → S_CHECK_1  WHEN: user "Revise"    DO: edit guidance-spec, re-display
 S_CHECK_1 → END        WHEN: user "Abort"
 
+S_DESIGN → S_WAVE_2    WHEN: DESIGN.md exists OR explore completed    DO: A_DESIGN_EXPLORE
+S_DESIGN → S_WAVE_2    WHEN: DESIGN.md already exists (skip explore)
+S_DESIGN → S_WAVE_2    WHEN: explore failed → W004 → continue without
+
 S_WAVE_2 → S_CHECK_2   DO: spawn wave-2 (parallel), merge results
 S_WAVE_2 → S_WAVE_3    WHEN: all failed       DO: skip synthesis
 
@@ -88,13 +94,24 @@ S_AGGREGATE → END      DO: A_AGGREGATE
 
 **Synthesis (W3)**: Cross-role consensus/conflicts/unique → conflict tags [RESOLVED]/[SUGGESTED]/[UNRESOLVED] → feature-specs or synthesis-specification.md → feature-index.json + synthesis-changelog.md. Four-layer: Direct Reference → Structured Extraction → Conflict Distillation → Cross-Feature Annotation.
 
+### A_DESIGN_EXPLORE
+
+When ui-designer is among selected roles, establish visual direction before Wave 2:
+
+1. If `.workflow/impeccable/PRODUCT.md` missing → run `$maestro-impeccable teach`
+2. If `.workflow/impeccable/DESIGN.md` missing → run `$maestro-impeccable explore`
+3. If both already exist → skip (visual direction already locked)
+
+explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
+ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows, state design), not visual styling.
+
 ### A_AGGREGATE
 
 1. Export results.csv
 2. Generate context.md (summary, guidance, per-role findings, synthesis, feature index, next steps)
 3. Confidence scoring: 5 dimensions (role_coverage, cross_role_consistency, feature_completeness, spec_quality, design_feasibility). Quality gate: >3 UNRESOLVED → warn.
 4. Copy artifacts to target .brainstorming/
-5. Next-step routing: UI features detected → maestro-ui-design; else → maestro-analyze / maestro-plan / maestro-roadmap
+5. Next-step routing: DESIGN.md established → `maestro-impeccable build <feature>`; else UI features detected → `maestro-impeccable build <feature>`; else → maestro-analyze / maestro-plan / maestro-roadmap
 
 </actions>
 </state_machine>

package/.codex/skills/maestro-composer/SKILL.md

@@ -50,6 +50,11 @@ $ARGUMENTS — natural language workflow description, or flags.
 
 **Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
 **Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
+
+### 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>
 
 <execution>