maestro-flow 0.3.49 → 0.4.2

package/.claude/agents/impeccable-agent.md

@@ -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/.claude/commands/maestro-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-craft --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}`
 
@@ -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-craft/plan for Go, brainstorm for No-Go)
+- [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 </success_criteria>

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

@@ -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-ui-craft <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/.claude/commands/maestro-impeccable.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-impeccable
-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]"
+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,118 +9,241 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Skill
+  - Agent
   - AskUserQuestion
+  - TodoWrite
 ---
-<purpose>
-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.
+<purpose>
+UI design command. Parse input → prerequisites → read workflow file → execute → track.
 
-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.
+- **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** (24):
-
-| Category | Commands |
-|----------|----------|
-| 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 |
-
-**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. 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" })
-```
-
-The skill handles: context loading (spec load --category ui, with load-context fallback), register detection (brand/product),
-reference file loading, and command execution.
-
-## 3. 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
-
-## 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 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 |
-</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 | New from scratch |
+| redesign | document → explore → shape → craft → critique → [refine] → audit → polish | Redesign existing code |
+| improve | critique → [refine] → polish → audit | Iterative improvement |
+| enhance | {cmd...} → critique → [refine] → polish | Targeted enhancement (multi-command) |
+| launch | harden → adapt → optimize → audit → polish | Full production readiness |
+| harden | harden → audit → polish | Edge case hardening |
+| foundation | teach? → explore → document → extract | Design system setup |
+| live | live | Real-time iteration |
+
+- `?` = 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 supports multiple commands, comma-separated: `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
+
+Three-layer priority matching. Stop on first match — do not continue to lower layers.
+
+### Layer 1: Single command intent → Direct
+
+Semantically match user description against the Command Routing table's Description column. Match the closest **single** command.
+
+**Skip condition**: If the prompt also contains a Layer 2 chain keyword AND does not focus on a single design dimension, skip this layer.
+Example: `enhance colors and typography` — "enhance" is a chain keyword + multiple design dimensions → skip to Layer 2.
+
+| Intent signal | Command |
+|---------------|---------|
+| review, check UX, score, heuristic, evaluate usability | critique |
+| audit, a11y, accessibility, technical check, performance audit, code quality | audit |
+| add animation, motion, transitions, micro-interactions | animate |
+| color, palette, OKLCH, contrast, color scheme | colorize |
+| font, typography, type scale, line height, font pairing | typeset |
+| layout, spacing, grid, alignment, visual hierarchy | layout |
+| too loud, tone down, visual noise, make it simpler, too busy | quieter |
+| too bland, bolder, more personality, stronger, more contrast | bolder |
+| too complex, simplify, strip, remove clutter, cognitive load | distill |
+| polish, fine-tune, pixel perfect, final pass, refine details | polish |
+| copy, labels, error messages, UX writing, microcopy, CTAs | clarify |
+| responsive, mobile, adapt, breakpoints, touch targets | adapt |
+| performance, loading, bundle, jank, speed, rendering | optimize |
+| edge cases, error states, i18n, overflow, empty state hardening | harden |
+| onboarding, first-run, empty state, activation, progressive disclosure | onboard |
+| fun, surprise, personality, memorable, joy, delight | delight |
+| extraordinary, push limits, ambitious effects, cutting-edge | overdrive |
+| plan UX, wireframe, information architecture, visual direction | shape |
+| multi-style, variants, compare styles, style comparison | explore |
+| brand definition, PRODUCT.md, product context | teach |
+| extract design, DESIGN.md, document design system | document |
+| pull tokens, extract components, design system extraction | extract |
+| real-time, browser iteration, live editing | live |
+
+### Layer 2: Project intent → Chain
+
+Layer 1 did not match. Check for chain-level keywords — even if the prompt also contains a specific target/path, chain matching takes priority.
+
+| Pattern | Chain |
+|---------|-------|
+| new, create, build, from scratch, start fresh | build |
+| redo, redesign, rethink, restyle, overhaul, revamp | redesign |
+| improve, iterate, better, refine overall | improve |
+| enhance, visual upgrade, level up | enhance |
+| launch, deploy, ship, production-ready, go live | launch |
+| harden, production-harden, edge cases | harden |
+| design system, tokens, design foundation, design infrastructure | foundation |
+| real-time, live, browser | live |
+
+Ambiguous + no `-y` → AskUserQuestion.
+
+### Layer 3: Concrete build task → Direct craft
+
+Layer 1+2 both did not match, but intent is to build/create a specific thing:
+- Contains a specific file path or target (`d:\path`, `src/pages/`, `index.html`)
+- Contains detailed visual specs (layout, style, color scheme)
+- Contains reference material (`based on...`, `like...`, `similar to...`)
+
+→ Route to **craft** (Direct)
+
+## 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. **Display execution info**:
+   ```
+   ── Command: {command} ────────────────────
+   Category: {category} | Target: {target}
+   ─────────────────────────────────────────
+   ```
+3. Read `~/.maestro/workflows/impeccable/{command}.md`
+4. **TodoWrite tracking**: create todo items for each major phase in the workflow file
+   - Format: `[{command}] {phase description}`
+   - Mark each phase completed immediately upon finishing
+5. Follow workflow file instructions
+6. Post: suggest logical next command (teach→shape, shape→craft, craft→critique, etc.)
+
+## Chain Execution
+
+1. Prerequisites ✓
+2. **Display chain preview**: parse chain definition, output full step preview:
+   ```
+   ── 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}
+   ```
+   - `◆` marks quality gate steps with threshold
+   - `↺` marks refine loop with max iteration count
+   - Conditional steps show trigger condition
+   - Skipped conditional steps marked `(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 init**: create todo items for all chain steps
+   - One item per step, format: `[chain] step N: {command} — {description}`
+   - If conditional step is skipped, immediately mark completed
+   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+5. For each step:
+   - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
+   - **Step start**: TodoWrite marks current step in_progress
+   - **Step done**: TodoWrite marks completed + update status.json (`current_step`, step `status`)
+   - **Step failed**: TodoWrite marks completed (with note) + record reason
+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: record gate result in current step notes (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-roadmap.md

@@ -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-ui-craft --chain build |
+| 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-craft | `-y` | Auto-select design variant + skip confirmations |
+| 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/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-craft", "command": "/maestro-ui-craft", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-ui-craft.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-craft", "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-craft "{phase}" --chain build` |
+| `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-craft-build` | maestro-ui-craft --chain build → [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-craft, 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

@@ -111,7 +111,7 @@ ui-designer agents in Wave 2 then focus on UX analysis only (interaction flows,
 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: DESIGN.md established → `maestro-ui-craft <feature> --chain build`; else UI features detected → `maestro-ui-craft <feature> --chain build`; 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-help/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-craft", "command": "/maestro-ui-craft", "category": "ui", "description": "UI 生产管线 — 设计系统原型、自动化生产和质量门控", "source": "../../commands/maestro-ui-craft.md"},
+    {"name": "maestro-impeccable", "command": "/maestro-impeccable", "category": "ui", "description": "UI 生产管线 — 设计系统原型、自动化生产和质量门控", "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"},