npm - maestro-flow-one - Versions diffs - 0.2.8 → 0.2.9 - Mend

maestro-flow-one 0.2.8 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/maestro-flow/agents/impeccable-agent.md +2 -2
package/maestro-flow/commands/lifecycle/analyze.md +1 -1
package/maestro-flow/commands/lifecycle/brainstorm.md +1 -1
package/maestro-flow/commands/lifecycle/impeccable.md +222 -447
package/maestro-flow/commands/lifecycle/roadmap.md +1 -1
package/package.json +1 -1

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

@@ -64,8 +64,8 @@ These commands ask questions only "if unclear from codebase". When PRODUCT.md an
 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
+3. **Execute**: Read `~/.maestro/workflows/impeccable/{command}.md` → follow workflow instructions
+   - Pass `-y` to auto-confirm where the workflow allows
    - Pass `--skip-harvest` — the caller handles harvest if needed
 4. **Report**: Return the command output (scores, changes made, findings)

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

@@ -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-impeccable --chain build {target}`
+- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
 - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
 - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`

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

@@ -69,7 +69,7 @@ Auto mode:
 - 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-impeccable <feature-description> --chain build` to build with the established design system"
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
 Single role mode:
 - More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-impeccable
-description: Production-grade UI design with knowhow accumulation — 24 commands + chain orchestration with quality gates + integrated design search
-argument-hint: "<command|intent> [target] [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [--skip-harvest] [--skip-design-explore] [--skip-design] [--styles <N>] [--stack <stack>] [-y] [-c]"
+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
@@ -10,462 +10,237 @@ allowed-tools:
   - Glob
   - Grep
   - Agent
-  - Skill
   - AskUserQuestion
   - TodoWrite
 ---
-<purpose>
-Production-grade UI design system with two execution modes:
-**Direct Mode** — Execute any of 24 sub-commands for 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).
-**Chain Mode** — Orchestrate sub-commands via intelligent intent routing + quality gate auto-iteration.
-5 chains: build, improve, enhance, harden, live. Critique/audit scores drive automatic command selection and iteration loops.
-Includes integrated design-explore (multi-variant design system generation via BM25 engine, HTML prototype rendering, interactive user review)
-and `search` CLI subcommand for querying UI/UX design knowledge base (BM25 + 30+ CSV data files).
-After each command, automatically harvests design decisions into `.workflow/knowhow/` (DCS-, AST-, TIP-, REF-) for cross-session accumulation.
+<purpose>
+UI design command. Parse input → prerequisites → read workflow file → execute → track.
-Session (chain mode): `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+- **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
-- [design stage workflow](~/.maestro/workflows/impeccable/design.md) — read when S_DESIGN_EXPLORE state entered
-- [sub-command workflow](~/.maestro/workflows/impeccable/{command}.md) — read when dispatching a sub-command
-</deferred_reading>
-<sub_commands>
-All sub-command workflows reside under `~/.maestro/workflows/impeccable/`:
-| Category | Command | Workflow File |
-|----------|---------|---------------|
-| Build | craft | `workflows/impeccable/craft.md` |
-| Build | shape | `workflows/impeccable/shape.md` |
-| Build | teach | `workflows/impeccable/teach.md` |
-| Build | document | `workflows/impeccable/document.md` |
-| Build | extract | `workflows/impeccable/extract.md` |
-| Build | explore | `workflows/impeccable/explore.md` |
-| Evaluate | critique | `workflows/impeccable/critique.md` |
-| Evaluate | audit | `workflows/impeccable/audit.md` |
-| Refine | polish | `workflows/impeccable/polish.md` |
-| Refine | bolder | `workflows/impeccable/bolder.md` |
-| Refine | quieter | `workflows/impeccable/quieter.md` |
-| Refine | distill | `workflows/impeccable/distill.md` |
-| Refine | harden | `workflows/impeccable/harden.md` |
-| Refine | onboard | `workflows/impeccable/onboard.md` |
-| Enhance | animate | `workflows/impeccable/animate.md` |
-| Enhance | colorize | `workflows/impeccable/colorize.md` |
-| Enhance | typeset | `workflows/impeccable/typeset.md` |
-| Enhance | layout | `workflows/impeccable/layout.md` |
-| Enhance | delight | `workflows/impeccable/delight.md` |
-| Enhance | overdrive | `workflows/impeccable/overdrive.md` |
-| Fix | clarify | `workflows/impeccable/clarify.md` |
-| Fix | adapt | `workflows/impeccable/adapt.md` |
-| Fix | optimize | `workflows/impeccable/optimize.md` |
-| Iterate | live | `workflows/impeccable/live.md` |
-**Reference workflows** (loaded by context, not as sub-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`
-**Search engine**: `workflows/impeccable/ui-search/` — BM25 search engine + CSV knowledge files
-</sub_commands>
-<context>
-$ARGUMENTS — sub-command, intent text, or special keywords, with optional flags.
-**Keywords:** `continue`/`next` → resume previous chain session
-**Flags (direct mode):**
-- `--skip-harvest` — Execute command without knowhow capture
-- `-y` — Auto-confirm where the skill allows
-**Flags (chain mode):**
-- `--chain <type>` — Force chain type: build, improve, enhance, harden, live
-- `--enhance <cmd>` — Specific enhance command (animate|colorize|typeset|layout|delight|overdrive|bolder)
-- `--threshold <score>` — Critique pass threshold (default: 26/40). Audit threshold auto-computed as threshold×0.5
-- `--max-loops <n>` — Maximum quality gate iterations (default: 3)
-- `-c` / `--continue` — Resume previous chain session
-- `--skip-design-explore` / `--skip-design` — Skip design-explore and bridge
-- `--styles <N>` — Number of design system variants (2-5, default 3). Build chain only
-- `--stack <stack>` — Tech stack for supplementary guidelines (default: html-tailwind)
-</context>
-<invariants>
-1. **Session before chain execution** — status.json created before any chain step runs
-2. **All chain steps via Skill** — every sub-command dispatched through `Skill({ skill: "maestro-impeccable" })`
-3. **Gate scores drive loops** — refine loop auto-selects commands from P0/P1 findings, never from hardcoded lists
-4. **Interactive gates respected** — teach, shape, craft retain their user gates; never suppress
-5. **Harvest after direct mode** — knowhow capture runs after every direct-mode command (unless --skip-harvest or live)
-</invariants>
-<chains>
-### Chain Definitions
-| Chain | Sequence | Gate Condition |
-|-------|----------|----------------|
-| **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 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
-| 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 |
-| 实时, live, browser, 浏览器, variant | live |
-Explicit `--chain` overrides routing. Ambiguous + no `-y` → AskUserQuestion.
-</chains>
-<state_machine>
-<states>
-S_PARSE      — 解析参数、模式检测、意图分类                PERSIST: —
-S_RESUME     — 扫描已有 chain session、恢复执行           PERSIST: —
-S_SETUP      — 加载 context、检查 PRODUCT.md                PERSIST: —
-S_CREATE     — 创建 session + status.json                    PERSIST: session (全量)
-S_DESIGN_EXPLORE — 委托 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
-S_REPORT     — 最终报告 + 趋势                               PERSIST: final scores, status
-</states>
-<transitions>
-S_PARSE:
-  → S_RESUME     WHEN: -c / --continue flag OR keyword "continue"/"next"
-  → S_SETUP      WHEN: chain mode detected (--chain flag or intent classified)
-  → S_PARSE      WHEN: chain mode, ambiguous AND not -y          DO: AskUserQuestion
-  → END          WHEN: direct mode → execute sub-command directly (see Direct Mode execution)
-  → END          WHEN: search mode → CLI dispatch
-  → END          WHEN: direct mode, no arguments → show command menu with categories
-  → END          WHEN: chain mode, no intent AND no target → E002
-S_RESUME:
-  → S_CHAIN      WHEN: session found                  DO: A_LOCATE_SESSION
-  → END          WHEN: no session found → E005
-S_SETUP:
-  → S_CREATE     DO: A_LOAD_CONTEXT
-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)
-  → S_CHAIN      WHEN: max loops exceeded → W002 → force advance
-S_REFINE:
-  → S_GATE       DO: execute auto-selected commands → re-run gate command
-                  GUARD: loop_count < max_loops
-S_REPORT:
-  → END          DO: A_FINAL_REPORT
-</transitions>
-<actions>
-### A_LOCATE_SESSION
-1. Scan `.workflow/.maestro/ui-craft-*/status.json`, filter `status == "running"`, sort DESC
-2. Take most recent; load into context as current session
-3. Resume from `current_step` position
-### A_LOAD_CONTEXT
+## 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.)
-1. If chain starts with `teach` → execute it first, impeccable handles context loading internally
-2. Otherwise → trigger context loading (spec load --category ui, with load-context fallback)
-3. If PRODUCT.md missing/placeholder → prepend teach, execute, then resume
-### A_CREATE_SESSION
+## Chain Execution
-1. Read `.workflow/state.json` for project context (phase, milestone)
-2. Create `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`:
+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
-   { "session_id": "ui-craft-{ts}", "source": "maestro-impeccable", "intent": "...",
-     "chain_type": "build|improve|enhance|harden|live", "target": "...",
-     "auto_mode": false, "threshold": 26, "max_loops": 3,
-     "steps": [{ "index": 0, "command": "shape", "status": "pending" }],
-     "gate_history": [], "loop_count": 0,
-     "current_step": 0, "status": "running",
-     "created_at": "ISO-8601", "updated_at": "ISO-8601" }
+   { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
+     "gate_history": [], "loop_count": 0, "status": "running" }
    ```
-3. Write status.json before executing any step
-### A_DESIGN_EXPLORE
-1. Execute: `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
-2. explore handles internally: variant generation, prototype rendering, visual comparison, user selection/mix, bridge to DESIGN.md, spec registration
-3. On completion: verify `.workflow/impeccable/DESIGN.md` exists
-4. Update status.json: `explore_completed: true`, `design_md_path`
-### A_FINAL_REPORT
-1. Read critique trend if available
-2. Update status.json with `status: "completed"` and final scores
-3. Present summary table with scores, iterations, commands executed
-</actions>
-</state_machine>
-<execution>
-## 1. Mode Detection
-1. If first argument is `search` → **Search Mode** (Section 6)
-2. If first argument matches one of the 24 sub-commands → **Direct Mode** (Section 2)
-3. If `--chain` flag present → **Chain Mode** (Section 3)
-4. If `-c` / `--continue` or keyword "continue"/"next" → **Resume** (S_RESUME)
-5. If intent text (doesn't match a sub-command) → classify intent → **Chain Mode** (Section 3)
-6. No arguments → show command menu with categories
-## 2. Direct Mode
-### 2a. 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.
-### 2b. 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
-### 2c. Post-Execution Routing
-**Pipeline context detected** (called via Skill from brainstorm, maestro, etc.):
-- Report command result and **stop** — 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
-## 3. Chain Mode
-Follow the state machine (S_PARSE → S_SETUP → S_CREATE → S_CHAIN → S_GATE → S_REFINE → S_REPORT).
-### 3a. Parse & Route
-1. If `--chain` present → use directly
-2. Otherwise → match $ARGUMENTS against intent patterns
-3. If `--enhance` present → chain = enhance, cmd = --enhance value
-4. For enhance chain without `--enhance` → infer from intent ("动画" → animate, "颜色" → colorize, etc.)
-5. Ambiguous + no `-y` → ask user to pick chain
-Create TodoWrite with chain steps.
-### 3b. Execute Chain
-For each step in chain, sequentially:
-```
-▸ Step {n}/{total}: /maestro-impeccable {command} {target}
-```
-Execute via: `Skill({ skill: "maestro-impeccable", args: "{command} {target}" })`
-After each step: update status.json `current_step` and step `status`.
-**Step-specific logic:**
-- **design_explore** (build chain only): check DESIGN.md exists → skip if yes; check --skip-design-explore → skip if set; otherwise execute `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`; verify DESIGN.md on completion
-- **teach, shape, craft** are interactive — do NOT suppress their user gates
-- Gate steps (critique/audit) → transition to quality gate logic (Section 4)
-## 4. Quality Gate
-### 4a. Execute Gate Command
-```
-Skill({ skill: "maestro-impeccable", args: "critique {target}" })
-```
-or
-```
-Skill({ skill: "maestro-impeccable", args: "audit {target}" })
-```
-### 4b. Parse Score
-From critique output, extract:
-- **score**: Nielsen's total — from `"**Total** | | **N/40**"` row
-- **P0_count**: count of `[P0]` tagged findings
-- **P1_count**: count of `[P1]` tagged findings
-- **suggested_commands**: list of `/maestro-impeccable <cmd>` from "Suggested command" fields
-From audit output, extract:
-- **score**: dimension total — from `"**Total** | | **N/20**"` row
-- **P0_count**: count of `[P0]` findings
-### 4c. Evaluate
-```
-critique_pass = (score >= threshold) AND (P0_count == 0)
-audit_pass    = (score >= threshold * 0.5) AND (P0_count == 0)
-```
-### 4d. On PASS → advance to next chain step
-### 4e. On FAIL
-1. Collect suggested commands from P0/P1 findings
-2. If no suggestions → use fallback mapping (see quality_gate_routing)
-3. De-duplicate, cap at 3 commands per iteration
-4. Sort: P0-suggested first
-5. Execute each: `Skill({ skill: "maestro-impeccable", args: "{cmd} {target}" })`
-6. Re-run gate command
-7. Increment loop_count, append to status.json `gate_history`
-### 4f. On Max Loops Exceeded → W002, force advance
-## 5. Final Report (chain mode)
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Chain complete: {chain_type}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Critique : {score}/40 (trend: {trend_line})
- Audit    : {score}/20
- Loops    : {total_iterations}
- Commands : {executed_command_list}
- Status   : {PASS | PARTIAL — N issues remain}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-If issues remain → suggest: "Run `/maestro-impeccable --chain improve {target}` to continue iteration."
-## 6. Search CLI
-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).
-</execution>
-<quality_gate_routing>
-### Finding → Command Fallback Mapping
-When critique/audit findings lack explicit "Suggested command", map by category:
+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 |
 |-----------------|---------|
-| Visual hierarchy, layout, spacing, alignment | layout |
-| Color, contrast, palette, monochromatic | colorize |
-| Typography, font, readability, hierarchy | typeset |
-| Animation, motion, transitions, micro-interaction | animate |
-| Copy, labels, error messages, UX writing | clarify |
-| Responsive, mobile, breakpoints, touch targets | adapt |
-| Performance, loading, speed, bundle, jank | optimize |
-| Complexity, overload, clutter, cognitive load | distill |
-| Bland, safe, generic, lacks personality | bolder |
-| Aggressive, overwhelming, loud, overstimulating | quieter |
-| Onboarding, empty state, first-run, activation | onboard |
-| Edge cases, i18n, error handling, overflow | harden |
-| Personality, memorability, joy, delight | delight |
-### Commands Never Auto-Selected
-| Command | Reason |
-|---------|--------|
-| teach | Project setup (run in S_SETUP only) |
-| shape | Requires user interview |
-| craft | Full build with multiple gates |
-| live | Interactive browser mode |
-| document | Generates DESIGN.md (setup) |
-| extract | Design system extraction (setup) |
-| overdrive | Requires explicit user vision |
-| critique | Gate command, not a fix |
-| audit | Gate command, not a fix |
-</quality_gate_routing>
-<error_codes>
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | Invalid sub-command (not in 24 valid commands) or impeccable skill not available |
-| E002 | error | No intent or target specified |
-| E003 | error | Invalid --chain type |
-| E004 | error | Invalid --enhance command |
-| E005 | error | Resume session not found |
-| E006 | error | Python 3 not available for design system generation |
-| E007 | error | ui-search scripts not found at expected path |
-| 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 |
-| W004 | warning | Design system generation failed, falling back to shape full interview |
-| W005 | warning | Bridge transformation failed, continuing without DESIGN.md |
-| W006 | warning | Harvest failed — design knowledge not captured (command still succeeded) |
-| W007 | warning | PRODUCT.md missing — skill will auto-trigger teach |
-| W008 | warning | Node.js not available for prototype rendering, falling back to text-only |
-</error_codes>
-<success_criteria>
-- [ ] Mode detected correctly (direct / chain / search / resume)
-- [ ] Sub-command recognized and routed (direct mode)
-- [ ] Intent classified and chain type selected (chain mode)
-- [ ] Context loaded (PRODUCT.md present or taught)
-- [ ] Session dir created with status.json before chain execution
-- [ ] All chain steps executed via Skill("maestro-impeccable", ...)
-- [ ] Quality gate evaluated with parsed scores
-- [ ] Refine loop executed when gate failed (if applicable)
-- [ ] Gate history and scores persisted to status.json
-- [ ] Knowhow entry created in .workflow/knowhow/ (unless --skip-harvest or live)
-- [ ] Progress tracked via TodoWrite throughout (chain mode)
-</success_criteria>
+| 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/maestro-flow/commands/lifecycle/roadmap.md CHANGED Viewed

@@ -104,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-impeccable --chain build |
+| Need UI design first | /maestro-impeccable build |
 | View project dashboard | /manage-status |
 | Need project setup (full mode) | /maestro-init |
 </execution>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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"