maestro-flow-one 0.2.8 → 0.2.10

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
  1. package/maestro-flow/agents/impeccable-agent.md +2 -2
  2. package/maestro-flow/commands/lifecycle/analyze.md +1 -1
  3. package/maestro-flow/commands/lifecycle/brainstorm.md +1 -1
  4. package/maestro-flow/commands/lifecycle/impeccable.md +225 -447
  5. package/maestro-flow/commands/lifecycle/roadmap.md +1 -1
  6. package/package.json +1 -1
package/maestro-flow/agents/impeccable-agent.md CHANGED
@@ -64,8 +64,8 @@ These commands ask questions only "if unclear from codebase". When PRODUCT.md an
64
64
 
65
65
  1. **Load context**: Run `maestro impeccable load-context` to load PRODUCT.md and DESIGN.md
66
66
  2. **Validate command**: Check the requested command is in the allowed list above
67
- 3. **Execute**: `Skill({ skill: "maestro-impeccable", args: "{command} {target} --skip-harvest -y" })`
68
- - Always pass `-y` to auto-confirm where the skill allows
67
+ 3. **Execute**: Read `~/.maestro/workflows/impeccable/{command}.md` → follow workflow instructions
68
+ - Pass `-y` to auto-confirm where the workflow allows
69
69
  - Pass `--skip-harvest` — the caller handles harvest if needed
70
70
  4. **Report**: Return the command output (scores, changes made, findings)
71
71
 
package/maestro-flow/commands/lifecycle/analyze.md CHANGED
@@ -79,7 +79,7 @@ Phase 4: Output context.md for downstream plan --gaps
79
79
  **Next-step routing on completion:**
80
80
 
81
81
  Phase/Milestone scope:
82
- - Go recommendation, UI work needed → `/maestro-impeccable --chain build {target}`
82
+ - Go recommendation, UI work needed → `/maestro-impeccable build {target}`
83
83
  - Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
84
84
  - No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
85
85
 
package/maestro-flow/commands/lifecycle/brainstorm.md CHANGED
@@ -69,7 +69,7 @@ Auto mode:
69
69
  - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
70
70
  - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
71
71
  - `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
72
- - DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable <feature-description> --chain build` to build with the established design system"
72
+ - DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
73
73
 
74
74
  Single role mode:
75
75
  - More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
package/maestro-flow/commands/lifecycle/impeccable.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: maestro-impeccable
3
- description: Production-grade UI design with knowhow accumulation — 24 commands + chain orchestration with quality gates + integrated design search
4
- 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]"
3
+ description: Production-grade UI design — 24 commands + chain orchestration with quality gates + design search
4
+ argument-hint: "<command|chain|intent> [target] [flags]"
5
5
  allowed-tools:
6
6
  - Read
7
7
  - Write
@@ -10,462 +10,240 @@ allowed-tools:
10
10
  - Glob
11
11
  - Grep
12
12
  - Agent
13
- - Skill
14
13
  - AskUserQuestion
15
14
  - TodoWrite
16
15
  ---
17
- <purpose>
18
- Production-grade UI design system with two execution modes:
19
-
20
- **Direct Mode** — Execute any of 24 sub-commands for the full design lifecycle:
21
- Build (craft, shape, teach, document, extract, explore), Evaluate (critique, audit), Refine (polish, bolder, quieter, distill, harden, onboard),
22
- Enhance (animate, colorize, typeset, layout, delight, overdrive), Fix (clarify, adapt, optimize), Iterate (live).
23
-
24
- **Chain Mode** — Orchestrate sub-commands via intelligent intent routing + quality gate auto-iteration.
25
- 5 chains: build, improve, enhance, harden, live. Critique/audit scores drive automatic command selection and iteration loops.
26
16
 
27
- Includes integrated design-explore (multi-variant design system generation via BM25 engine, HTML prototype rendering, interactive user review)
28
- and `search` CLI subcommand for querying UI/UX design knowledge base (BM25 + 30+ CSV data files).
29
-
30
- After each command, automatically harvests design decisions into `.workflow/knowhow/` (DCS-, AST-, TIP-, REF-) for cross-session accumulation.
17
+ <purpose>
18
+ UI design command. Parse input → prerequisites → read workflow file → execute → track.
31
19
 
32
- Session (chain mode): `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
20
+ - **Direct**: single command via workflow file
21
+ - **Chain**: orchestrate command sequence with quality gates
22
+ - **Search**: query design knowledge base via CLI
33
23
  </purpose>
34
24
 
35
- <deferred_reading>
36
- - [impeccable harvest workflow](~/.maestro/workflows/impeccable.md) — read after command execution for harvest logic
37
- - [design stage workflow](~/.maestro/workflows/impeccable/design.md) — read when S_DESIGN_EXPLORE state entered
38
- - [sub-command workflow](~/.maestro/workflows/impeccable/{command}.md) — read when dispatching a sub-command
39
- </deferred_reading>
40
-
41
- <sub_commands>
42
- All sub-command workflows reside under `~/.maestro/workflows/impeccable/`:
43
-
44
- | Category | Command | Workflow File |
45
- |----------|---------|---------------|
46
- | Build | craft | `workflows/impeccable/craft.md` |
47
- | Build | shape | `workflows/impeccable/shape.md` |
48
- | Build | teach | `workflows/impeccable/teach.md` |
49
- | Build | document | `workflows/impeccable/document.md` |
50
- | Build | extract | `workflows/impeccable/extract.md` |
51
- | Build | explore | `workflows/impeccable/explore.md` |
52
- | Evaluate | critique | `workflows/impeccable/critique.md` |
53
- | Evaluate | audit | `workflows/impeccable/audit.md` |
54
- | Refine | polish | `workflows/impeccable/polish.md` |
55
- | Refine | bolder | `workflows/impeccable/bolder.md` |
56
- | Refine | quieter | `workflows/impeccable/quieter.md` |
57
- | Refine | distill | `workflows/impeccable/distill.md` |
58
- | Refine | harden | `workflows/impeccable/harden.md` |
59
- | Refine | onboard | `workflows/impeccable/onboard.md` |
60
- | Enhance | animate | `workflows/impeccable/animate.md` |
61
- | Enhance | colorize | `workflows/impeccable/colorize.md` |
62
- | Enhance | typeset | `workflows/impeccable/typeset.md` |
63
- | Enhance | layout | `workflows/impeccable/layout.md` |
64
- | Enhance | delight | `workflows/impeccable/delight.md` |
65
- | Enhance | overdrive | `workflows/impeccable/overdrive.md` |
66
- | Fix | clarify | `workflows/impeccable/clarify.md` |
67
- | Fix | adapt | `workflows/impeccable/adapt.md` |
68
- | Fix | optimize | `workflows/impeccable/optimize.md` |
69
- | Iterate | live | `workflows/impeccable/live.md` |
70
-
71
- **Reference workflows** (loaded by context, not as sub-commands):
72
- `brand.md`, `product.md`, `design.md`, `codex.md`, `heuristics-scoring.md`, `cognitive-load.md`,
73
- `color-and-contrast.md`, `interaction-design.md`, `motion-design.md`, `personas.md`,
74
- `responsive-design.md`, `spatial-design.md`, `typography.md`, `ux-writing.md`
75
-
76
- **Search engine**: `workflows/impeccable/ui-search/` — BM25 search engine + CSV knowledge files
77
- </sub_commands>
78
-
79
- <context>
80
- $ARGUMENTS — sub-command, intent text, or special keywords, with optional flags.
81
-
82
- **Keywords:** `continue`/`next` → resume previous chain session
83
-
84
- **Flags (direct mode):**
85
- - `--skip-harvest` — Execute command without knowhow capture
86
- - `-y` — Auto-confirm where the skill allows
87
-
88
- **Flags (chain mode):**
89
- - `--chain <type>` — Force chain type: build, improve, enhance, harden, live
90
- - `--enhance <cmd>` — Specific enhance command (animate|colorize|typeset|layout|delight|overdrive|bolder)
91
- - `--threshold <score>` — Critique pass threshold (default: 26/40). Audit threshold auto-computed as threshold×0.5
92
- - `--max-loops <n>` — Maximum quality gate iterations (default: 3)
93
- - `-c` / `--continue` — Resume previous chain session
94
- - `--skip-design-explore` / `--skip-design` — Skip design-explore and bridge
95
- - `--styles <N>` — Number of design system variants (2-5, default 3). Build chain only
96
- - `--stack <stack>` — Tech stack for supplementary guidelines (default: html-tailwind)
97
- </context>
98
-
99
- <invariants>
100
- 1. **Session before chain execution** — status.json created before any chain step runs
101
- 2. **All chain steps via Skill** — every sub-command dispatched through `Skill({ skill: "maestro-impeccable" })`
102
- 3. **Gate scores drive loops** — refine loop auto-selects commands from P0/P1 findings, never from hardcoded lists
103
- 4. **Interactive gates respected** — teach, shape, craft retain their user gates; never suppress
104
- 5. **Harvest after direct mode** — knowhow capture runs after every direct-mode command (unless --skip-harvest or live)
105
- </invariants>
106
-
107
- <chains>
108
-
109
- ### Chain Definitions
110
-
111
- | Chain | Sequence | Gate Condition |
112
- |-------|----------|----------------|
113
- | **build** | teach? → **design_explore?** → shape → craft → **critique** → [refine loop] → audit → polish | critique ≥ threshold AND P0 == 0 |
114
- | **improve** | **critique** → [refine loop] → polish → audit | critique ≥ threshold AND P0 == 0 |
115
- | **enhance** | {cmd} → **critique** → polish (if needed) | critique ≥ threshold |
116
- | **harden** | harden → **audit** → polish | audit ≥ threshold×0.5 |
117
- | **live** | live | — (interactive, no gate) |
118
-
119
- - `teach?` — conditional: only if PRODUCT.md missing/placeholder
120
- - `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
121
- - `[refine loop]` — quality gate loop: extract suggested commands from critique → execute → re-critique
122
-
123
- ### Intent → Chain Routing
124
-
125
- | Intent Pattern | Chain |
126
- |---------------|-------|
127
- | 新建, create, build, new, 从零, landing, feature, page | build |
128
- | 设计, design, 风格, style, 设计系统, design system, 视觉, theme | build |
129
- | 改进, improve, fix, 优化, iterate, better, 迭代 | improve |
130
- | 动画, 颜色, 排版, animate, color, type, bold, delight, enhance | enhance |
131
- | 生产, production, harden, 上线, ship, edge case, i18n | harden |
132
- | 实时, live, browser, 浏览器, variant | live |
133
-
134
- Explicit `--chain` overrides routing. Ambiguous + no `-y` → AskUserQuestion.
135
-
136
- </chains>
137
-
138
- <state_machine>
139
-
140
- <states>
141
- S_PARSE — 解析参数、模式检测、意图分类 PERSIST: —
142
- S_RESUME — 扫描已有 chain session、恢复执行 PERSIST: —
143
- S_SETUP — 加载 context、检查 PRODUCT.md PERSIST: —
144
- S_CREATE — 创建 session + status.json PERSIST: session (全量)
145
- S_DESIGN_EXPLORE — 委托 explore：多变体生成、原型对比、选型/混搭、自动 bridge 到 DESIGN.md PERSIST: explore_completed, design_md_path
146
- S_CHAIN — 按序执行 chain 步骤 PERSIST: step progress, executed commands
147
- S_GATE — 质量门控：解析评分、决策 PERSIST: scores, loop count
148
- S_REFINE — 执行自动选取的 refine 命令 PERSIST: refine commands, loop state
149
- S_REPORT — 最终报告 + 趋势 PERSIST: final scores, status
150
- </states>
151
-
152
- <transitions>
153
-
154
- S_PARSE:
155
- → S_RESUME WHEN: -c / --continue flag OR keyword "continue"/"next"
156
- → S_SETUP WHEN: chain mode detected (--chain flag or intent classified)
157
- → S_PARSE WHEN: chain mode, ambiguous AND not -y DO: AskUserQuestion
158
- → END WHEN: direct mode → execute sub-command directly (see Direct Mode execution)
159
- → END WHEN: search mode → CLI dispatch
160
- → END WHEN: direct mode, no arguments → show command menu with categories
161
- → END WHEN: chain mode, no intent AND no target → E002
162
-
163
- S_RESUME:
164
- → S_CHAIN WHEN: session found DO: A_LOCATE_SESSION
165
- → END WHEN: no session found → E005
166
-
167
- S_SETUP:
168
- → S_CREATE DO: A_LOAD_CONTEXT
169
-
170
- S_CREATE:
171
- → S_CHAIN DO: A_CREATE_SESSION
172
-
173
- S_CHAIN:
174
- → S_DESIGN_EXPLORE WHEN: current step is 'design_explore' AND DESIGN.md missing AND --skip-design-explore not set AND --skip-design not set
175
- → S_GATE WHEN: current step is gate command (critique/audit)
176
- → S_CHAIN WHEN: step is design_explore but skip conditions met → advance
177
- → S_CHAIN WHEN: step is normal command → execute → advance
178
- → S_REPORT WHEN: all steps complete
179
-
180
- S_DESIGN_EXPLORE:
181
- → S_CHAIN WHEN: explore completed (DESIGN.md produced) → advance to shape
182
- → S_CHAIN WHEN: explore failed → W004 → advance to shape (full interview fallback)
183
-
184
- S_GATE:
185
- → S_CHAIN WHEN: PASS (score ≥ threshold AND P0 == 0) → advance to next step
186
- → S_REFINE WHEN: FAIL (score < threshold OR P0 > 0)
187
- → S_CHAIN WHEN: max loops exceeded → W002 → force advance
188
-
189
- S_REFINE:
190
- → S_GATE DO: execute auto-selected commands → re-run gate command
191
- GUARD: loop_count < max_loops
192
-
193
- S_REPORT:
194
- → END DO: A_FINAL_REPORT
195
-
196
- </transitions>
197
-
198
- <actions>
199
-
200
- ### A_LOCATE_SESSION
201
-
202
- 1. Scan `.workflow/.maestro/ui-craft-*/status.json`, filter `status == "running"`, sort DESC
203
- 2. Take most recent; load into context as current session
204
- 3. Resume from `current_step` position
205
-
206
- ### A_LOAD_CONTEXT
25
+ ## Input
26
+
27
+ $ARGUMENTS first word determines mode:
28
+
29
+ | First Word | Mode |
30
+ |------------|------|
31
+ | Known command (see routing table) | Direct |
32
+ | Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain |
33
+ | continue / next / -c | Resume |
34
+ | search | Search: `maestro impeccable search "$REST"` |
35
+ | Free text (concrete task) | Direct craft — has specific target + specs/reference |
36
+ | Free text (project intent) | Intent → classify → chain |
37
+ | (empty) | Menu: show commands by category |
38
+
39
+ ## Command Routing
40
+
41
+ All workflows at `~/.maestro/workflows/impeccable/{command}.md`:
42
+
43
+ | Command | Category | Description |
44
+ |---------|----------|-------------|
45
+ | craft | Build | Shape then build end-to-end — full page/component implementation |
46
+ | shape | Build | Plan UX/UI before code — information architecture, wireframe, visual direction |
47
+ | teach | Build | Set up PRODUCT.md — users, brand, tone, anti-references, principles |
48
+ | document | Build | Generate DESIGN.md from existing code — extract tokens, typography, colors |
49
+ | extract | Build | Pull tokens/components into reusable design system |
50
+ | explore | Build | Multi-style comparison — generate variants, render prototypes, visual compare, select/mix |
51
+ | critique | Evaluate | UX heuristic review with Nielsen scoring (/40) + P0/P1 findings |
52
+ | audit | Evaluate | Technical quality checks — a11y, performance, responsive, code quality (/20) |
53
+ | polish | Refine | Final quality pass — micro-adjustments, pixel perfection |
54
+ | bolder | Refine | Amplify bland/safe designs — stronger personality, more contrast |
55
+ | quieter | Refine | Tone down aggressive/overwhelming designs — reduce visual noise |
56
+ | distill | Refine | Strip to essence — remove clutter, reduce cognitive load |
57
+ | harden | Refine | Production-ready — error states, i18n, edge cases, overflow, empty states |
58
+ | onboard | Refine | First-run flows, empty states, activation paths, progressive disclosure |
59
+ | animate | Enhance | Add purposeful motion — transitions, micro-interactions, scroll effects |
60
+ | colorize | Enhance | Add strategic color — OKLCH palette, contrast, color strategy |
61
+ | typeset | Enhance | Improve typography — scale, hierarchy, font pairing, line length |
62
+ | layout | Enhance | Fix spacing, rhythm, visual hierarchy, alignment, grid |
63
+ | delight | Enhance | Add personality — memorable details, joy, surprise moments |
64
+ | overdrive | Enhance | Push past conventional limits — ambitious visual effects |
65
+ | clarify | Fix | Improve UX copy — labels, error messages, microcopy, CTAs |
66
+ | adapt | Fix | Adapt for devices/screens — responsive, touch targets, breakpoints |
67
+ | optimize | Fix | Fix UI performance — loading, rendering, bundle, paint/layout jank |
68
+ | live | Iterate | Browser-based variant iteration — real-time design in DevTools |
69
+
70
+ Reference files (loaded by workflow as needed, not standalone commands):
71
+ brand.md, product.md, design.md, codex.md, heuristics-scoring.md, cognitive-load.md,
72
+ color-and-contrast.md, interaction-design.md, motion-design.md, personas.md,
73
+ responsive-design.md, spatial-design.md, typography.md, ux-writing.md
74
+
75
+ ## Chains
76
+
77
+ | Chain | Steps | Scenario |
78
+ |-------|-------|----------|
79
+ | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
80
+ | redesign | document → explore → shape → craft → critique → [refine] → audit → polish | Redesign existing code |
81
+ | improve | critique → [refine] → polish → audit | Iterative improvement |
82
+ | enhance | {cmd...} → critique → [refine] → polish | Targeted enhancement (multi-command) |
83
+ | launch | harden → adapt → optimize → audit → polish | Full production readiness |
84
+ | harden | harden → audit → polish | Edge case hardening |
85
+ | foundation | teach? → explore → document → extract | Design system setup |
86
+ | live | live | Real-time iteration |
87
+
88
+ - `?` = conditional: teach if PRODUCT.md missing; explore if DESIGN.md missing and --skip-design not set
89
+ - `[refine]` = quality gate loop: gate fails → auto-select fix commands from findings → re-gate
90
+ - `{cmd...}` = enhance supports multiple commands, comma-separated: `enhance colorize,typeset landing-page`
91
+
92
+ Chain flags: --threshold <N> (default 26/40), --max-loops <N> (default 3), --skip-design, --styles <N>, -y
93
+
94
+ ## Free Text Routing
95
+
96
+ Three-layer priority matching. Stop on first match — do not continue to lower layers.
97
+
98
+ ### Layer 1: Single command intent → Direct
99
+
100
+ Semantically match user description against the Command Routing table's Description column. Match the closest **single** command.
101
+
102
+ **Skip condition**: If the prompt also contains a Layer 2 chain keyword AND does not focus on a single design dimension, skip this layer.
103
+ Example: `enhance colors and typography` — "enhance" is a chain keyword + multiple design dimensions → skip to Layer 2.
104
+
105
+ | Intent signal | Command |
106
+ |---------------|---------|
107
+ | review, check UX, score, heuristic, evaluate usability | critique |
108
+ | audit, a11y, accessibility, technical check, performance audit, code quality | audit |
109
+ | add animation, motion, transitions, micro-interactions | animate |
110
+ | color, palette, OKLCH, contrast, color scheme | colorize |
111
+ | font, typography, type scale, line height, font pairing | typeset |
112
+ | layout, spacing, grid, alignment, visual hierarchy | layout |
113
+ | too loud, tone down, visual noise, make it simpler, too busy | quieter |
114
+ | too bland, bolder, more personality, stronger, more contrast | bolder |
115
+ | too complex, simplify, strip, remove clutter, cognitive load | distill |
116
+ | polish, fine-tune, pixel perfect, final pass, refine details | polish |
117
+ | copy, labels, error messages, UX writing, microcopy, CTAs | clarify |
118
+ | responsive, mobile, adapt, breakpoints, touch targets | adapt |
119
+ | performance, loading, bundle, jank, speed, rendering | optimize |
120
+ | edge cases, error states, i18n, overflow, empty state hardening | harden |
121
+ | onboarding, first-run, empty state, activation, progressive disclosure | onboard |
122
+ | fun, surprise, personality, memorable, joy, delight | delight |
123
+ | extraordinary, push limits, ambitious effects, cutting-edge | overdrive |
124
+ | plan UX, wireframe, information architecture, visual direction | shape |
125
+ | multi-style, variants, compare styles, style comparison | explore |
126
+ | brand definition, PRODUCT.md, product context | teach |
127
+ | extract design, DESIGN.md, document design system | document |
128
+ | pull tokens, extract components, design system extraction | extract |
129
+ | real-time, browser iteration, live editing | live |
130
+
131
+ ### Layer 2: Project intent → Chain
132
+
133
+ Layer 1 did not match. Check for chain-level keywords — even if the prompt also contains a specific target/path, chain matching takes priority.
134
+
135
+ | Pattern | Chain |
136
+ |---------|-------|
137
+ | new, create, build, from scratch, start fresh | build |
138
+ | redo, redesign, rethink, restyle, overhaul, revamp | redesign |
139
+ | improve, iterate, better, refine overall | improve |
140
+ | enhance, visual upgrade, level up | enhance |
141
+ | launch, deploy, ship, production-ready, go live | launch |
142
+ | harden, production-harden, edge cases | harden |
143
+ | design system, tokens, design foundation, design infrastructure | foundation |
144
+ | real-time, live, browser | live |
145
+
146
+ Ambiguous + no `-y` → AskUserQuestion.
147
+
148
+ ### Layer 3: Concrete build task → Direct craft
149
+
150
+ Layer 1+2 both did not match, but intent is to build/create a specific thing:
151
+ - Contains a specific file path or target (`d:\path`, `src/pages/`, `index.html`)
152
+ - Contains detailed visual specs (layout, style, color scheme)
153
+ - Contains reference material (`based on...`, `like...`, `similar to...`)
154
+
155
+ → Route to **craft** (Direct)
156
+
157
+ ## Prerequisites
158
+
159
+ Before reading any command workflow:
160
+
161
+ 1. **Context**: `maestro spec load --category ui` → if empty → `maestro impeccable load-context`
162
+ 2. **PRODUCT.md**: missing/placeholder (<200 chars / `[TODO]`) → execute teach first, then resume original task
163
+ 3. **Register**: identify brand/product → Read `~/.maestro/workflows/impeccable/{brand|product}.md`
164
+
165
+ ## Direct Execution
166
+
167
+ 1. Prerequisites ✓
168
+ 2. **Display execution info**:
169
+ ```
170
+ ── Command: {command} ────────────────────
171
+ Category: {category} | Target: {target}
172
+ ─────────────────────────────────────────
173
+ ```
174
+ 3. Read `~/.maestro/workflows/impeccable/{command}.md`
175
+ 4. **TodoWrite tracking**: create todo items for each major phase in the workflow file
176
+ - Format: `[{command}] {phase description}`
177
+ - Mark each phase completed immediately upon finishing
178
+ 5. Follow workflow file instructions
179
+ 6. Post: suggest logical next command (teach→shape, shape→craft, craft→critique, etc.)
207
180
 
208
- 1. If chain starts with `teach` → execute it first, impeccable handles context loading internally
209
- 2. Otherwise → trigger context loading (spec load --category ui, with load-context fallback)
210
- 3. If PRODUCT.md missing/placeholder → prepend teach, execute, then resume
211
-
212
- ### A_CREATE_SESSION
181
+ ## Chain Execution
213
182
 
214
- 1. Read `.workflow/state.json` for project context (phase, milestone)
215
- 2. Create `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`:
183
+ 1. Prerequisites ✓
184
+ 2. **Display chain preview**: parse chain definition, output full step preview:
185
+ ```
186
+ ── Chain: build ──────────────────────────
187
+ 1. teach (conditional: PRODUCT.md missing)
188
+ 2. explore (conditional: DESIGN.md missing)
189
+ 3. shape
190
+ 4. craft
191
+ 5. critique ◆ quality gate (threshold: 26/40)
192
+ 6. [refine] ↺ auto-fix loop (max: 3)
193
+ 7. audit ◆ quality gate (threshold: 14/20)
194
+ 8. polish
195
+ ─────────────────────────────────────────
196
+ Target: {target}
197
+ ```
198
+ - `◆` marks quality gate steps with threshold
199
+ - `↺` marks refine loop with max iteration count
200
+ - Conditional steps show trigger condition
201
+ - Skipped conditional steps marked `(skipped)`
202
+ 3. Create session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
216
203
  ```json
217
- { "session_id": "ui-craft-{ts}", "source": "maestro-impeccable", "intent": "...",
218
- "chain_type": "build|improve|enhance|harden|live", "target": "...",
219
- "auto_mode": false, "threshold": 26, "max_loops": 3,
220
- "steps": [{ "index": 0, "command": "shape", "status": "pending" }],
221
- "gate_history": [], "loop_count": 0,
222
- "current_step": 0, "status": "running",
223
- "created_at": "ISO-8601", "updated_at": "ISO-8601" }
204
+ { "chain_type": "...", "target": "...", "steps": [...], "current_step": 0,
205
+ "gate_history": [], "loop_count": 0, "status": "running" }
224
206
  ```
225
- 3. Write status.json before executing any step
226
-
227
- ### A_DESIGN_EXPLORE
228
-
229
- 1. Execute: `Skill({ skill: "maestro-impeccable", args: "explore --styles {styles_count}" })`
230
- 2. explore handles internally: variant generation, prototype rendering, visual comparison, user selection/mix, bridge to DESIGN.md, spec registration
231
- 3. On completion: verify `.workflow/impeccable/DESIGN.md` exists
232
- 4. Update status.json: `explore_completed: true`, `design_md_path`
233
-
234
- ### A_FINAL_REPORT
235
-
236
- 1. Read critique trend if available
237
- 2. Update status.json with `status: "completed"` and final scores
238
- 3. Present summary table with scores, iterations, commands executed
239
-
240
- </actions>
241
-
242
- </state_machine>
243
-
244
- <execution>
245
-
246
- ## 1. Mode Detection
247
-
248
- 1. If first argument is `search` → **Search Mode** (Section 6)
249
- 2. If first argument matches one of the 24 sub-commands → **Direct Mode** (Section 2)
250
- 3. If `--chain` flag present → **Chain Mode** (Section 3)
251
- 4. If `-c` / `--continue` or keyword "continue"/"next" → **Resume** (S_RESUME)
252
- 5. If intent text (doesn't match a sub-command) → classify intent → **Chain Mode** (Section 3)
253
- 6. No arguments → show command menu with categories
254
-
255
- ## 2. Direct Mode
256
-
257
- ### 2a. Invoke Skill
258
-
259
- ```
260
- Skill({ skill: "maestro-impeccable", args: "$ARGUMENTS" })
261
- ```
262
-
263
- The skill handles: context loading (spec load --category ui, with load-context fallback), register detection (brand/product),
264
- reference file loading, and command execution.
265
-
266
- ### 2b. Harvest
267
-
268
- After the skill completes, read `~/.maestro/workflows/impeccable.md` and follow the harvest workflow.
269
-
270
- Skip harvest if:
271
- - `--skip-harvest` flag is set
272
- - Sub-command is `live` (interactive, no harvestable output)
273
- - Sub-command is unrecognized
274
-
275
- ### 2c. Post-Execution Routing
276
-
277
- **Pipeline context detected** (called via Skill from brainstorm, maestro, etc.):
278
- - Report command result and **stop** — the calling flow owns what happens next
279
-
280
- **Standalone invocation** (user directly ran `/maestro-impeccable`):
281
- - Show next-step suggestions based on what was executed:
282
- - `teach` → suggest `explore` or `shape`
283
- - `explore` → suggest `shape` → `craft`
284
- - `shape` → suggest `craft`
285
- - `craft` → suggest `critique`
286
- - `critique`/`audit` → suggest commands from findings
287
- - Enhancement/fix commands → suggest `critique` to re-evaluate
288
-
289
- ## 3. Chain Mode
290
-
291
- Follow the state machine (S_PARSE → S_SETUP → S_CREATE → S_CHAIN → S_GATE → S_REFINE → S_REPORT).
292
-
293
- ### 3a. Parse & Route
294
-
295
- 1. If `--chain` present → use directly
296
- 2. Otherwise → match $ARGUMENTS against intent patterns
297
- 3. If `--enhance` present → chain = enhance, cmd = --enhance value
298
- 4. For enhance chain without `--enhance` → infer from intent ("动画" → animate, "颜色" → colorize, etc.)
299
- 5. Ambiguous + no `-y` → ask user to pick chain
300
-
301
- Create TodoWrite with chain steps.
302
-
303
- ### 3b. Execute Chain
304
-
305
- For each step in chain, sequentially:
306
-
307
- ```
308
- ▸ Step {n}/{total}: /maestro-impeccable {command} {target}
309
- ```
310
-
311
- Execute via: `Skill({ skill: "maestro-impeccable", args: "{command} {target}" })`
312
-
313
- After each step: update status.json `current_step` and step `status`.
314
-
315
- **Step-specific logic:**
316
-
317
- - **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
318
- - **teach, shape, craft** are interactive — do NOT suppress their user gates
319
- - Gate steps (critique/audit) → transition to quality gate logic (Section 4)
320
-
321
- ## 4. Quality Gate
322
-
323
- ### 4a. Execute Gate Command
324
-
325
- ```
326
- Skill({ skill: "maestro-impeccable", args: "critique {target}" })
327
- ```
328
- or
329
- ```
330
- Skill({ skill: "maestro-impeccable", args: "audit {target}" })
331
- ```
332
-
333
- ### 4b. Parse Score
334
-
335
- From critique output, extract:
336
- - **score**: Nielsen's total — from `"**Total** | | **N/40**"` row
337
- - **P0_count**: count of `[P0]` tagged findings
338
- - **P1_count**: count of `[P1]` tagged findings
339
- - **suggested_commands**: list of `/maestro-impeccable <cmd>` from "Suggested command" fields
340
-
341
- From audit output, extract:
342
- - **score**: dimension total — from `"**Total** | | **N/20**"` row
343
- - **P0_count**: count of `[P0]` findings
344
-
345
- ### 4c. Evaluate
346
-
347
- ```
348
- critique_pass = (score >= threshold) AND (P0_count == 0)
349
- audit_pass = (score >= threshold * 0.5) AND (P0_count == 0)
350
- ```
351
-
352
- ### 4d. On PASS → advance to next chain step
353
-
354
- ### 4e. On FAIL
355
-
356
- 1. Collect suggested commands from P0/P1 findings
357
- 2. If no suggestions → use fallback mapping (see quality_gate_routing)
358
- 3. De-duplicate, cap at 3 commands per iteration
359
- 4. Sort: P0-suggested first
360
- 5. Execute each: `Skill({ skill: "maestro-impeccable", args: "{cmd} {target}" })`
361
- 6. Re-run gate command
362
- 7. Increment loop_count, append to status.json `gate_history`
363
-
364
- ### 4f. On Max Loops Exceeded → W002, force advance
365
-
366
- ## 5. Final Report (chain mode)
367
-
368
- ```
369
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
370
- Chain complete: {chain_type}
371
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
372
-
373
- Critique : {score}/40 (trend: {trend_line})
374
- Audit : {score}/20
375
- Loops : {total_iterations}
376
- Commands : {executed_command_list}
377
-
378
- Status : {PASS | PARTIAL — N issues remain}
379
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
380
- ```
381
-
382
- If issues remain → suggest: "Run `/maestro-impeccable --chain improve {target}` to continue iteration."
383
-
384
- ## 6. Search CLI
385
-
386
- Direct CLI dispatch (no Skill, no harvest):
387
-
388
- ```bash
389
- maestro impeccable search "<query>" [options]
390
- ```
391
-
392
- Options: `-d <domain>`, `-s <stack>`, `-n <max>`, `--design-system`, `-p <name>`, `-f <fmt>`, `--persist`, `--page <page>`, `-o <dir>`
393
-
394
- Domains: style, color, chart, landing, product, ux, typography, icons, react, web, google-fonts.
395
- Stacks: react, nextjs, vue, svelte, astro, swiftui, react-native, flutter, html-tailwind, shadcn, + more.
396
-
397
- Search uses `workflows/impeccable/ui-search/search.py` (BM25 engine + 30+ CSV knowledge files).
398
-
399
- </execution>
400
-
401
- <quality_gate_routing>
402
-
403
- ### Finding → Command Fallback Mapping
404
-
405
- When critique/audit findings lack explicit "Suggested command", map by category:
207
+ 4. **TodoWrite init**: create todo items for all chain steps
208
+ - One item per step, format: `[chain] step N: {command} — {description}`
209
+ - If conditional step is skipped, immediately mark completed
210
+ - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
211
+ 5. For each step:
212
+ - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
213
+ - **Step start**: TodoWrite marks current step in_progress
214
+ - **Step done**: TodoWrite marks completed + update status.json (`current_step`, step `status`)
215
+ - **Step failed**: TodoWrite marks completed (with note) + record reason
216
+ 6. **Quality gate** (critique/audit steps):
217
+ - Parse score: critique `**Total** | | **N/40**`, audit `**Total** | | **N/20**`
218
+ - Count `[P0]` / `[P1]` tags
219
+ - Pass: score ≥ threshold AND P0 == 0 → advance
220
+ - Fail: collect suggested commands from findings → execute → re-gate
221
+ - Max loops exceeded → force advance with warning
222
+ - TodoWrite: record gate result in current step notes (score, P0/P1 count, pass/fail)
223
+ 7. Final report: scores + trend + commands executed
224
+
225
+ ## Resume
226
+
227
+ Scan `.workflow/.maestro/ui-craft-*/status.json` for `status == "running"` → most recent → resume from `current_step`.
228
+
229
+ ## Quality Gate — Finding → Command Fallback
230
+
231
+ When findings lack explicit suggested command:
406
232
 
407
233
  | Finding Category | Command |
408
234
  |-----------------|---------|
409
- | Visual hierarchy, layout, spacing, alignment | layout |
410
- | Color, contrast, palette, monochromatic | colorize |
411
- | Typography, font, readability, hierarchy | typeset |
412
- | Animation, motion, transitions, micro-interaction | animate |
413
- | Copy, labels, error messages, UX writing | clarify |
414
- | Responsive, mobile, breakpoints, touch targets | adapt |
415
- | Performance, loading, speed, bundle, jank | optimize |
416
- | Complexity, overload, clutter, cognitive load | distill |
417
- | Bland, safe, generic, lacks personality | bolder |
418
- | Aggressive, overwhelming, loud, overstimulating | quieter |
419
- | Onboarding, empty state, first-run, activation | onboard |
420
- | Edge cases, i18n, error handling, overflow | harden |
421
- | Personality, memorability, joy, delight | delight |
422
-
423
- ### Commands Never Auto-Selected
424
-
425
- | Command | Reason |
426
- |---------|--------|
427
- | teach | Project setup (run in S_SETUP only) |
428
- | shape | Requires user interview |
429
- | craft | Full build with multiple gates |
430
- | live | Interactive browser mode |
431
- | document | Generates DESIGN.md (setup) |
432
- | extract | Design system extraction (setup) |
433
- | overdrive | Requires explicit user vision |
434
- | critique | Gate command, not a fix |
435
- | audit | Gate command, not a fix |
436
-
437
- </quality_gate_routing>
438
-
439
- <error_codes>
440
- | Code | Severity | Description |
441
- |------|----------|-------------|
442
- | E001 | error | Invalid sub-command (not in 24 valid commands) or impeccable skill not available |
443
- | E002 | error | No intent or target specified |
444
- | E003 | error | Invalid --chain type |
445
- | E004 | error | Invalid --enhance command |
446
- | E005 | error | Resume session not found |
447
- | E006 | error | Python 3 not available for design system generation |
448
- | E007 | error | ui-search scripts not found at expected path |
449
- | W001 | warning | PRODUCT.md missing, prepending teach to chain |
450
- | W002 | warning | Max quality gate loops exceeded, forcing continue |
451
- | W003 | warning | Could not parse score from critique/audit output |
452
- | W004 | warning | Design system generation failed, falling back to shape full interview |
453
- | W005 | warning | Bridge transformation failed, continuing without DESIGN.md |
454
- | W006 | warning | Harvest failed — design knowledge not captured (command still succeeded) |
455
- | W007 | warning | PRODUCT.md missing — skill will auto-trigger teach |
456
- | W008 | warning | Node.js not available for prototype rendering, falling back to text-only |
457
- </error_codes>
458
-
459
- <success_criteria>
460
- - [ ] Mode detected correctly (direct / chain / search / resume)
461
- - [ ] Sub-command recognized and routed (direct mode)
462
- - [ ] Intent classified and chain type selected (chain mode)
463
- - [ ] Context loaded (PRODUCT.md present or taught)
464
- - [ ] Session dir created with status.json before chain execution
465
- - [ ] All chain steps executed via Skill("maestro-impeccable", ...)
466
- - [ ] Quality gate evaluated with parsed scores
467
- - [ ] Refine loop executed when gate failed (if applicable)
468
- - [ ] Gate history and scores persisted to status.json
469
- - [ ] Knowhow entry created in .workflow/knowhow/ (unless --skip-harvest or live)
470
- - [ ] Progress tracked via TodoWrite throughout (chain mode)
471
- </success_criteria>
235
+ | Layout, spacing, hierarchy, alignment | layout |
236
+ | Color, contrast, palette | colorize |
237
+ | Typography, font, readability | typeset |
238
+ | Animation, motion, transitions | animate |
239
+ | Copy, labels, UX writing | clarify |
240
+ | Responsive, mobile, breakpoints | adapt |
241
+ | Performance, loading, speed | optimize |
242
+ | Complexity, overload, clutter | distill |
243
+ | Bland, safe, generic | bolder |
244
+ | Aggressive, overwhelming | quieter |
245
+ | Onboarding, empty state | onboard |
246
+ | Edge cases, i18n, error handling | harden |
247
+ | Personality, memorability | delight |
248
+
249
+ Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.
package/maestro-flow/commands/lifecycle/roadmap.md CHANGED
@@ -104,7 +104,7 @@ Follow `~/.maestro/workflows/spec-generate.md` completely.
104
104
  |-----------|-----------|
105
105
  | Roadmap approved, need analysis | /maestro-analyze 1 |
106
106
  | Simple project, ready to plan | /maestro-plan 1 |
107
- | Need UI design first | /maestro-impeccable --chain build |
107
+ | Need UI design first | /maestro-impeccable build |
108
108
  | View project dashboard | /manage-status |
109
109
  | Need project setup (full mode) | /maestro-init |
110
110
  </execution>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "maestro-flow-one",
3
- "version": "0.2.8",
3
+ "version": "0.2.10",
4
4
  "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
5
5
  "bin": {
6
6
  "maestro-flow": "bin/maestro-flow.js"