Maestro Impeccable

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

Input

$ARGUMENTS first word determines mode:

Disambiguation for overlapping names (harden, live): bare keyword without target → Chain; keyword + explicit target/path → Direct. Override: --chain forces Chain, --direct forces Direct.

| Chain name: build, redesign, improve, enhance, launch, harden, foundation, live | Chain | | continue / next / -c | Resume | | search | Search: maestro impeccable search "$REST" | | Free text (any) | Free Text Routing (3-layer system below) | | (empty) | Menu: show commands by category |

Command Routing

All workflows at ~/.maestro/workflows/impeccable/{command}.md:

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 step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the impeccable: prefix (e.g. impeccable:craft, impeccable:critique). The bare names in this table refer to the workflow file at ~/.maestro/workflows/impeccable/{name}.md that the chain step reads.

• ? = 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 (default 26/40), --max-loops (default 3), --skip-design, --styles , -y (skip Layer 2 ambiguity user prompt — select first matching chain; skip chain session confirmation; skip quality gate refine confirmations. Does NOT skip prerequisite checks.)

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 matches a Layer 2 chain keyword AND matches MORE THAN ONE row in the Layer 1 intent signal table, skip this layer. Example: enhance colors and typography — "enhance" is a chain keyword + multiple design dimensions → skip to Layer 2.

Layer 2: Project intent → Chain

Override: if the user explicitly uses a chain name as the primary verb (improve, enhance, redesign, build, launch), prefer Layer 2 chain even if Layer 1 matched a single command.

Layer 1 did not match. Check for chain-level keywords — even if the prompt also contains a specific target/path, chain matching takes priority.

Ambiguous + no -y:

[@ask] AskUserQuestion (single-select, header: "意图确认"):

• Options: top 2-3 matched chains from Layer 2 table, each with label = chain name, description = matched keywords
• Last option: "直接构建" — skip chain, route to Layer 3 craft

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 ≥2 specific visual attributes (e.g., exact color values, font names, spacing numbers, layout structure description)
• Contains reference material (based on..., like..., similar to...)

→ Route to craft (Direct)

If all three layers produce no match → E001 (No command or intent resolved). Before raising E001, attempt [@ask] user prompt with top 2-3 closest matches from Layer 1+2 tables.

Prerequisites

Before reading any command workflow:

1. Context: maestro load --type spec --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 steps prefixed impeccable: to disambiguate from Direct commands):

   ── Chain: build ──────────────────────────
    1. impeccable:teach        (conditional: PRODUCT.md missing)
    2. impeccable:explore      (conditional: DESIGN.md missing)
    3. impeccable:shape
    4. impeccable:craft
    5. impeccable:critique     ◆ quality gate (threshold: 26/40)
    6. impeccable:[refine]     ↺ auto-fix loop (max: 3)
    7. impeccable:audit        ◆ quality gate (threshold: 14/20)
    8. impeccable: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. Confirm chain session: [@ask] user prompt "Create chain session for '{chain_type}' targeting '{target}'?" — proceed only if user confirms. On decline, abort chain. Create session: .workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.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: impeccable:{command} — {description} (use impeccable: prefix to disambiguate from Direct command items)
   • If conditional step is skipped, immediately mark completed
   • Quality gate steps include threshold: [chain] step 5: impeccable: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
   • Failure classification:
     • Blocking (chain stops): craft, shape, teach (if PRODUCT.md required)
     • Non-blocking (chain continues with W003): polish, delight, animate, colorize, typeset, layout, clarify, adapt, optimize, bolder, quieter, distill, harden, onboard
     • Gate steps (critique/audit): gate failure triggers refine loop, not step failure
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

Codify Execution

Trigger: first word is --codify or codify. Also reachable when the foundation chain reaches its document/extract steps and the user wants full reverse-extraction with knowhow persistence.

Arguments: --codify <source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]

• <source-path> (required): Directory containing CSS/SCSS/JS/TS/HTML source files
• --package-name <name>: Package name for reference output (default: auto-generated from source directory)
• --output-dir <path>: Output directory for reference package (default: .workflow/reference_style)
• --overwrite: Allow overwriting existing package directory

Output boundary: ALL file writes MUST target the --output-dir path (default: .workflow/reference_style/) for reference packages, and .workflow/knowhow/ for knowledge assets (manifest-driven direct writes per ui-codify-knowhow). NEVER modify the source directory being analyzed.

Codify Invariants

1. Source read-only — the source path being analyzed MUST NOT be modified; extraction is purely read-only
2. Phase-sequential loading — workflow files (ui-codify-extract, ui-codify-package, ui-codify-knowhow) MUST be read only when their phase starts; NEVER load all phases eagerly
3. User confirmation before knowhow — Phase 3→4 gate MUST present [@ask] user prompt before generating knowledge assets; NEVER auto-proceed to knowhow generation
4. Overwrite protection — existing package directory MUST NOT be overwritten without --overwrite flag (E102)
5. Artifact completeness — all 5 required artifacts MUST exist before reporting completion; NEVER skip artifact verification
6. Token-first extraction — design-tokens.json MUST be generated before layout-templates.json; layout extraction depends on token foundation

Step 1: Load UI Specs

maestro load --type spec --category ui

Step 2: Execute Workflow

Route to ~/.maestro/workflows/ui-codify.md and follow completely. The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files (see <deferred_reading>). Each phase reads its workflow file only when execution reaches that phase.

Codify Phase Gates (MANDATORY, BLOCKING)

GATE Phase 1 → Phase 2: Validation → Extraction

• REQUIRED: Source path validated and file discovery completed.
• REQUIRED: design-tokens.json generated with color, typography, spacing tokens.
• BLOCKED if missing: source path invalid (E101) or design-tokens.json not generated — extraction cannot proceed without token foundation.

GATE Phase 2 → Phase 3: Extraction → Package

• REQUIRED: layout-templates.json generated with component patterns.
• BLOCKED if missing: layout-templates.json absent — package generation requires component patterns as input.

GATE Phase 3 → Phase 4: Package → Knowhow

• REQUIRED: preview.html + preview.css generated as interactive showcase.
• BLOCKED if missing: preview artifacts not generated — knowhow phase needs rendered reference for validation.
• REQUIRED: [@ask] user prompt confirmation before proceeding to knowhow generation:

  question: "Preview 生成完成。是否继续将设计系统持久化为 knowhow 知识资产？"
  options:
    - label: "继续生成 knowhow"
      description: "按 knowhow-manifest.json 写入 AST/DCS assets 和 spec entries"
    - label: "仅保留 preview，跳过 knowhow"
      description: "保留 preview.html + preview.css，不写入知识库"
  

GATE Phase 4 → Completion: Knowhow → Done

• REQUIRED: knowhow-manifest.json created with AST/DCS assets and spec entries.
• REQUIRED: knowledge assets persisted — knowhow files + spec entries written to .workflow/knowhow/ and .workflow/specs/ per ui-codify-knowhow Step 4.4 (after user confirmation at Phase 3→4 gate).
• BLOCKED if missing: knowhow-manifest.json absent or knowledge assets not persisted.

Artifact Verification (before completion)

REQUIRED_ARTIFACTS = [
  "design-tokens.json",      // Phase 1
  "layout-templates.json",   // Phase 2
  "preview.html",            // Phase 3
  "preview.css",             // Phase 3
  "knowhow-manifest.json"    // Phase 4
]

If any artifact is missing: DO NOT report completion.

Resume

Scan .workflow/.maestro/ui-craft-*/status.json for status == "running" || status == "paused" → most recent → resume from current_step.

Quality Gate — Finding → Command Fallback

When findings lack explicit suggested command:

Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.

Chain Phase Gates (MANDATORY for chain mode)

GATE: Quality Gate Step → Next Step

• REQUIRED: Score parsed from critique/audit output (not assumed or estimated).
• REQUIRED: P0 count extracted from findings — P0 == 0 required for pass.
• REQUIRED: If gate fails, refine commands executed and re-gate attempted.
• BLOCKED if: score not parsed from actual output, or P0 > 0 and max refine loops not exhausted — do not advance past gate.
• Do NOT skip quality gate steps or mark as "passed" without parsing actual score.
• If score unparseable from output: retry the gate step once. If still unparseable → treat as gate fail (enter refine loop). Emit W005.

GATE: Chain → Completion

• REQUIRED: All non-skipped steps executed (TodoWrite all completed).
• REQUIRED: status.json updated with status: "completed" and final scores.
• REQUIRED: If any step failed: documented in status.json with reason.
• BLOCKED if missing: steps not all completed or status.json not updated — chain is incomplete.

Chain mode:

• Chain steps resolved and preview displayed
• Session status.json created in .workflow/.maestro/ui-craft-*/
• TodoWrite items created for all chain steps
• Each step executed with workflow file read
• Quality gates parsed with actual scores (not estimated)
• Refine loops executed when gate fails (up to max-loops)
• status.json updated with status: "completed" and final scores
• Final report with scores, trend, and commands executed

Codify mode:

• UI specs loaded via maestro load --type spec --category ui (if available)
• Source path validated and file discovery completed
• design-tokens.json generated with color, typography, spacing tokens
• layout-templates.json generated with component patterns (universal/specialized)
• animation-tokens.json generated (optional, W004 if missing)
• preview.html + preview.css generated as interactive showcase
• knowhow-manifest.json created with AST/DCS assets and spec entries
• knowledge assets persisted (knowhow + spec entries written per ui-codify-knowhow Step 4.4, after Phase 3→4 confirmation)
• Temporary workspace cleaned up