maestro-flow-one 0.2.5 → 0.2.7

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

@@ -11,344 +11,169 @@ allowed-tools:
   - Grep
   - Agent
   - AskUserQuestion
+  - Skill
 ---
 <purpose>
-Interactive workflow template composer. Parses natural language into a reusable DAG template
-via 5 phases with user confirmation at each boundary. Templates saved globally at
-`~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
-
-Three entry modes:
-1. **New design**: Parse → [confirm] → Resolve → [confirm] → Enrich → Confirm pipeline → Persist
-2. **Resume design**: Load in-progress draft from `.workflow/templates/design-drafts/`
-3. **Edit template**: Load existing template, modify, re-save
+Interactive workflow template composer. Parse natural language → resolve executors → inject checkpoints → build DAG → persist to `~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Three entry modes: **New design** (default), **Resume** (`--resume`), **Edit** (`--edit <path>`).
 </purpose>
 
 <deferred_reading>
-- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve) when mapping steps to executors
-- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist) when assembling final JSON
+- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
+- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
 </deferred_reading>
 
 <context>
-$ARGUMENTS — natural language workflow description, or flags.
-
-**Flags:**
-- `--resume` — Resume in-progress design session
-- `--edit <template-path>` — Edit an existing template
-
-**Shared constants:**
-
-| Constant | Value |
-|----------|-------|
-| Session prefix | `WFD` |
-| Template dir (global) | `~/.maestro/templates/workflows/` |
-| Template index (global) | `~/.maestro/templates/workflows/index.json` |
-| Design drafts dir (local) | `.workflow/templates/design-drafts/` |
-| Template ID format | `wft-<slug>-<YYYYMMDD>` |
-| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
-| Max nodes | 20 |
-
-**Entry routing:**
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Resume design | `--resume` flag or existing WFD session | Phase 0: Resume |
-| Edit template | `--edit <template-path>` | Phase 0: Load + Edit |
-| New design | Default | Phase 1: Parse |
-</context>
-
-<execution>
-
-### Phase 0: Resume / Edit (conditional)
+$ARGUMENTS — natural language description, or flags.
 
-**Resume design session** (if `--resume`):
-1. Scan `.workflow/templates/design-drafts/WFD-*/` for in-progress designs
-2. Multiple found → AskUserQuestion for selection
-3. Load draft → skip to last incomplete phase
-
-**Edit existing template** (if `--edit <path>`):
-1. Load template from `--edit` path
-2. Show current pipeline visualization (Phase 4 format)
-3. AskUserQuestion: which nodes to modify/add/remove
-4. Re-enter at Phase 3 with edits applied
-
----
+**Flags**: `--resume` (resume in-progress design), `--edit <path>` (edit existing template)
 
-### Phase 1: Parse — Semantic Intent Extraction
+**Constants**:
+- Template dir: `~/.maestro/templates/workflows/`
+- Template index: `~/.maestro/templates/workflows/index.json`
+- Design drafts: `.workflow/templates/design-drafts/`
+- Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
+- Max nodes: 20
 
-**Step 1.1** — Parse `$ARGUMENTS` as description. If empty, AskUserQuestion:
-```
-"Describe the workflow you want to automate.
-Include: what steps to run, in what order, and what varies each time (inputs).
-Example: 'analyze the code, then plan, implement, and test the feature'"
-```
-
-**Step 1.2** — Extract sequential actions as candidate nodes using semantic understanding:
-
-| Signal | Candidate Type |
-|--------|---------------|
-| "analyze", "review", "explore" | analysis (cli) |
-| "plan", "design", "spec" | planning (skill) |
-| "implement", "build", "code", "fix" | execution (skill) |
-| "test", "validate", "verify" | testing (skill) |
-| "brainstorm", "ideate" | brainstorm (skill) |
-| "review code" | review (skill) |
-| "then", "next", "after" | sequential edge |
-| "parallel", "simultaneously" | parallel edge |
-
-**Step 1.3** — Extract variables (inputs that vary per run). Detect from: direct mentions, `{var}` patterns, implicit from task type.
-
-**Step 1.4** — Classify task type: `bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap | refactor | auto-test | quick-task | custom`
-
-**Step 1.5** — Assess complexity: `simple` (1-3 nodes), `medium` (4-7), `complex` (8+)
-
-**Step 1.6** — Write `intent.json` to `.workflow/templates/design-drafts/WFD-<slug>-<date>/`.
-
-**Step 1.7 — Interactive confirmation**:
-
-Display parsed intent summary:
-```
-============================================================
-  COMPOSER — Intent Parsed
-============================================================
-  Description: "<original input>"
-  Task type:   <type>
-  Complexity:  <level>
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
+</context>
 
-  Detected steps:
-    1. <description>  →  <type_hint>
-    2. <description>  →  <type_hint>
-    3. <description>  →  <type_hint>
+<state_machine>
 
-  Variables:
-    - goal (required): <inferred description>
+<states>
+S_ROUTE        — 入口路由（new/resume/edit）               PERSIST: —
+S_PARSE        — 语义意图提取                               PERSIST: intent.json
+S_CONFIRM_1    — 确认解析结果                               PERSIST: —
+S_RESOLVE      — 映射步骤到 executor 节点                   PERSIST: nodes.json
+S_CONFIRM_2    — 确认节点映射                               PERSIST: —
+S_ENRICH       — 注入 checkpoint + 构建 DAG                 PERSIST: dag.json
+S_CONFIRM_3    — 可视化 pipeline + 用户审批                  PERSIST: —
+S_PERSIST      — 组装 JSON + 保存模板                       PERSIST: template file + index
+</states>
 
-  Draft: .workflow/templates/design-drafts/WFD-<slug>-<date>/
-============================================================
-```
+<transitions>
 
-AskUserQuestion:
-```
-options:
-  - "Looks good, continue to resolution"  → Phase 2
-  - "Edit steps"                           → re-describe, re-parse
-  - "Add a step"                           → append, re-parse
-  - "Cancel"                               → save draft, exit
-```
+S_ROUTE:
+  → S_PARSE       WHEN: no flags (new design)
+  → S_RESOLVE     WHEN: --resume                           DO: load draft, skip to last incomplete phase
+  → S_CONFIRM_3   WHEN: --edit <path>                      DO: load template, show pipeline, ask edits
 
----
+S_PARSE:
+  → S_CONFIRM_1   DO: A_PARSE_INTENT
 
-### Phase 2: Resolve — Map Steps to Executor Nodes
+S_CONFIRM_1:
+  → S_RESOLVE     WHEN: user confirms "Looks good"
+  → S_PARSE       WHEN: user selects "Edit steps" or "Add step"
+  → END           WHEN: user cancels                       DO: save draft
 
-**Read deferred**: `~/.maestro/templates/workflows/specs/node-catalog.md` — load node catalog for executor mapping.
+S_RESOLVE:
+  → S_CONFIRM_2   DO: A_RESOLVE_NODES (read deferred: node-catalog)
 
-If the spec file does not exist, use the built-in fallback mapping:
+S_CONFIRM_2:
+  → S_ENRICH      WHEN: user confirms "Continue"
+  → S_RESOLVE     WHEN: user changes executor or node type
+  → S_PARSE       WHEN: user selects "Back to intent"
+  → END           WHEN: user cancels                       DO: save draft
 
-| type_hint | Default executor type | Default executor |
-|-----------|----------------------|------------------|
-| `planning` | skill | `maestro-plan` |
-| `execution` | skill | `maestro-execute` |
-| `testing` | skill | `quality-test` |
-| `review` | skill | `quality-review` |
-| `brainstorm` | skill | `maestro-brainstorm` |
-| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
-| `verify` | skill | `maestro-verify` |
-| `refactor` | skill | `quality-refactor` |
-| `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-roadmap --mode full` |
-| `checkpoint` | checkpoint | — |
+S_ENRICH:
+  → S_CONFIRM_3   DO: A_BUILD_DAG
 
-**Step 2.1** — Load `intent.json`.
+S_CONFIRM_3:
+  → S_PERSIST     WHEN: user confirms "Confirm & Save"
+  → S_CONFIRM_3   WHEN: user edits/adds/removes node       DO: apply change, re-render
+  → S_ENRICH      WHEN: user selects "Re-run checkpoints"
+  → END           WHEN: user cancels                       DO: save draft
 
-**Step 2.2** — Map each step to executor. Resolution: match `type_hint` → catalog → semantic fit → fallback `cli`.
+S_PERSIST:
+  → END           DO: A_SAVE_TEMPLATE (read deferred: template-schema)
 
-**Step 2.3** — Build `args_template` with variable placeholders. Context injection:
-- Planning after analysis → `--context {prev_output_path}`
-- Execution after planning → `--resume-session {prev_session_id}`
-- Testing after execution → `--session {prev_session_id}`
+</transitions>
 
-**Step 2.4** — Assign `parallel_group` for steps with `parallel_with` set.
+<actions>
 
-**Step 2.5** — Write `nodes.json`.
+### A_PARSE_INTENT
 
-**Step 2.6 — Interactive confirmation**:
+1. Parse description (if empty: AskUserQuestion for workflow description)
+2. Extract candidate nodes via semantic signals:
 
-Display resolved nodes:
-```
-============================================================
-  COMPOSER — Nodes Resolved
-============================================================
-  N-001  [skill]    maestro-plan          "{goal}"
-  N-002  [skill]    maestro-execute       {phase}
-  N-003  [skill]    quality-test          {phase}
+| Signal | Type hint |
+|--------|-----------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
 
-  Parallel groups: none
-============================================================
-```
+3. Extract variables (inputs that vary per run)
+4. Classify: task type + complexity (simple 1-3 / medium 4-7 / complex 8+)
+5. Write `intent.json` to design drafts dir
+6. Display: parsed steps, variables, task type, complexity
 
-AskUserQuestion:
-```
-options:
-  - "Continue to checkpoint injection"  → Phase 3
-  - "Change executor for a node"        → select node, pick new executor
-  - "Change node type"                  → skill/cli/agent/command
-  - "Back to intent"                    → Phase 1
-  - "Cancel"                            → save draft, exit
-```
+### A_RESOLVE_NODES
 
----
+Read deferred `node-catalog.md` (fallback to built-in mapping):
 
-### Phase 3: Enrich — Inject Checkpoints + Build DAG
+| Type hint | Default executor |
+|-----------|-----------------|
+| planning | `maestro-plan` |
+| execution | `maestro-execute` |
+| testing | `quality-test` |
+| review | `quality-review` |
+| brainstorm | `maestro-brainstorm` |
+| analysis | `maestro delegate --role analyze` |
+| verify | `maestro-verify` |
+| refactor | `quality-refactor` |
+| debug | `quality-debug` |
 
-**Step 3.1** — Load `nodes.json`.
+Build `args_template` with variable placeholders. Context injection: planning-after-analysis → `--context {prev_output_path}`, execution-after-planning → `--resume-session {prev_session_id}`.
+Write `nodes.json`. Display resolved node list.
 
-**Step 3.2** — Build sequential edges (N-001 → N-002 → ...). For parallel groups: fan-out/fan-in.
+### A_BUILD_DAG
 
-**Step 3.3** — Auto-inject checkpoint nodes. Inject if ANY rule triggers:
+1. Build sequential edges (fan-out/fan-in for parallel groups)
+2. Auto-inject checkpoints:
 
 | Rule | Condition |
 |------|-----------|
-| Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
-| Execution gate | Target executor contains `execute` |
-| Agent spawn | Target type is `agent` |
+| Artifact boundary | Source outputs plan/spec/analysis/review |
+| Execution gate | Target contains `execute` |
 | Long-running | Target is maestro-plan, maestro-roadmap --mode full |
-| User-defined | Step had `type_hint: checkpoint` |
-| Post-testing | Source executor contains `test` or `auto-test` |
-
-Set `auto_continue: false` for checkpoints before user-facing deliverables.
-
-**Step 3.4** — Insert checkpoint edges (A → B becomes A → CP-X → B).
-
-**Step 3.5** — Finalize `context_schema` from all `{variable}` references.
-
-**Step 3.6** — Validate: no cycles, no orphans, all nodes reachable.
-
-**Step 3.7** — Write `dag.json`.
-
-→ Proceed directly to Phase 4 (confirm is the pipeline visualization).
-
----
-
-### Phase 4: Confirm — Visualize + User Approval
-
-**Step 4.1** — Render ASCII pipeline from `dag.json`:
-```
-============================================================
-  COMPOSER — Pipeline Review
-============================================================
-Pipeline: <template-name>
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- N-001  [skill]       maestro-plan              "{goal}"
-   |
- CP-01  [checkpoint]  After Plan                auto-continue
-   |
- N-002  [skill]       maestro-execute           {phase}
-   |
- CP-02  [checkpoint]  Before Tests              pause-for-user
-   |
- N-003  [skill]       quality-test              {phase}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Variables (required):  goal
-Checkpoints:           2  (1 auto, 1 pause)
-Nodes:                 3 work + 2 checkpoints
-============================================================
-```
-
-For parallel groups show fan-out/fan-in:
-```
- N-003a [skill]  quality-review  ─┐
-                                   ├─ N-004 [skill] quality-test
- N-003b [cli]    cli analysis     ─┘
-```
-
-**Step 4.2** — AskUserQuestion:
-```
-options:
-  - "Confirm & Save"                    → Phase 5
-  - "Edit a node"                       → select node ID, modify executor/args, re-render
-  - "Add a node"                        → insert position + description, re-resolve + re-enrich, re-render
-  - "Remove a node"                     → select node, re-wire edges, re-render
-  - "Rename template"                   → new name
-  - "Re-run checkpoint injection"       → back to Phase 3.3
-  - "Cancel"                            → save draft, output resume command
-```
-
-**Step 4.3** — On edit: apply change, re-render, re-ask. Loop until Confirm or Cancel.
-
-**Step 4.4** — On Confirm: freeze dag.json, proceed to Phase 5. On Cancel: save draft, output `/maestro-composer --resume`.
-
----
-
-### Phase 5: Persist — Assemble + Save Template
-
-**Read deferred**: `~/.maestro/templates/workflows/specs/template-schema.md` — load full JSON schema for template assembly.
-
-If the spec file does not exist, use the built-in template structure:
-```json
-{
-  "template_id": "wft-<slug>-<YYYYMMDD>",
-  "name": "<name>", "description": "<desc>", "version": "1.0",
-  "created_at": "<ISO>", "source_session": "WFD-<slug>-<date>",
-  "tags": [], "context_schema": {},
-  "nodes": [], "edges": [], "checkpoints": [],
-  "execution_mode": "serial",
-  "metadata": { "node_count": 0, "checkpoint_count": 0 }
-}
-```
-
-**Step 5.1** — Load `intent.json` + `dag.json`.
-
-**Step 5.2** — Determine template name (from Phase 4 or derive from task_type + description). Slug = kebab-case. If file exists with different content, append `-v2`, `-v3`.
-
-**Step 5.3** — Assemble template JSON.
-
-**Step 5.4** — Ensure `~/.maestro/templates/workflows/` exists. Write `<slug>.json`.
-
-**Step 5.5** — Update `~/.maestro/templates/workflows/index.json`.
+| Post-testing | Source contains `test` or `auto-test` |
+| User-defined | type_hint == checkpoint |
 
-**Step 5.6** — Output summary:
-```
-============================================================
-  COMPOSER — Template Saved
-============================================================
-  Path:      ~/.maestro/templates/workflows/<slug>.json
-  ID:        wft-<slug>-<date>
-  Nodes:     <n> work + <n> checkpoints
-  Variables: <required vars>
+3. Finalize context_schema from {variable} references
+4. Validate: no cycles, no orphans, all reachable
+5. Write `dag.json`
+6. Display ASCII pipeline visualization
 
-  To execute:
-    /maestro-player <slug> --context goal="<your goal>"
+### A_SAVE_TEMPLATE
 
-  To edit later:
-    /maestro-composer --edit ~/.maestro/templates/workflows/<slug>.json
+Read deferred `template-schema.md` (fallback to built-in structure).
+Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
+Write to `~/.maestro/templates/workflows/<slug>.json`. Update index.json.
+Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
 
-  To list all templates:
-    /maestro-player --list
-============================================================
-```
+</actions>
 
-**Step 5.7** — Clean up design draft directory.
-</execution>
+</state_machine>
 
 <error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | Empty description and no flags | AskUserQuestion for workflow description |
-| E002 | error | Step extraction found 0 steps | Ask user to rephrase with action verbs |
-| E003 | error | Node count exceeds max (20) | Suggest splitting into sub-workflows |
-| E004 | error | DAG cycle detected | Show cycle, ask user to resolve |
-| E005 | error | Resume session not found | Show available design drafts |
-| E006 | error | Edit template not found | Show available templates |
-| W001 | warning | Ambiguous step-to-executor mapping | Show candidates, let user choose |
-| W002 | warning | No checkpoint injection rules triggered | Warn user, offer to add manually |
-| W003 | warning | Deferred spec file not found | Use built-in fallback, continue |
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | 0 steps extracted | Ask user to rephrase with action verbs |
+| E003 | Node count > 20 | Suggest splitting into sub-workflows |
+| E005 | DAG cycle detected | Show cycle, ask user to resolve |
+| E006 | Edit template not found (--edit) | Show available templates |
+| W001 | Ambiguous step→executor mapping | Show candidates, let user choose |
 </error_codes>
 
 <success_criteria>
-- [ ] Intent parsed and confirmed by user (Phase 1 interactive gate)
-- [ ] Nodes resolved and confirmed by user (Phase 2 interactive gate)
-- [ ] DAG built with auto-injected checkpoints
-- [ ] Pipeline visualized and confirmed by user (Phase 4 interactive gate)
-- [ ] Template JSON written to `~/.maestro/templates/workflows/<slug>.json`
-- [ ] Template index updated at `~/.maestro/templates/workflows/index.json`
-- [ ] Deferred specs loaded only when phase needs them (not upfront)
+- [ ] Each phase has interactive confirmation gate
+- [ ] Template JSON written with nodes, edges, checkpoints, context_schema
+- [ ] Index updated; deferred specs loaded only when phase needs them
 </success_criteria>

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

@@ -37,15 +37,11 @@ Scope routing, flags, resolution logic, output directory format, artifact regist
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
 2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
 3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
-4. All are optional — proceed without if unavailable (log warning).
+4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
+5. All are optional — proceed without if unavailable (log warning).
 
 ### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category coding`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
+`maestro wiki list --category coding` → select relevant → `maestro wiki load`
 </context>
 
 <execution>
@@ -61,18 +57,15 @@ Follow '~/.maestro/workflows/execute.md' completely.
 
 ### Post-task Knowledge Inquiry
 
-After each task completes, evaluate inquiry triggers:
+After each task completion, check triggers:
 
-1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
-   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
+| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
+| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
 
-2. **Retry success**: If task required ≥2 retries before completion:
-   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
-
-3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
-   → Ask: "Design decision detected. Should it be recorded as knowhow? (`/spec-add learning`)"
-
-If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
+On confirm → `Skill("spec-add", "<category> <content>")`.
 
 ### Issue Status Sync
 

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

@@ -0,0 +1,126 @@
+---
+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]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - AskUserQuestion
+---
+<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.
+
+Includes integrated `search` CLI subcommand for querying the UI/UX design knowledge base
+(BM25 search engine + 30+ CSV data files covering styles, colors, typography, UX guidelines, charts, stacks).
+Search is invoked directly via `maestro impeccable search`, not through the Skill dispatch.
+</purpose>
+
+<deferred_reading>
+- [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>

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

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

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

@@ -47,12 +47,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 - Reads `conclusions.json` if available (implementation_scope seeds task generation)
 
 ### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
+`maestro wiki list --category arch` → select relevant → `maestro wiki load`
 </context>
 
 <execution>