maestro-flow 0.3.45 → 0.3.47

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -8,11 +8,12 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 <purpose>
 Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter. Once registered, entries are auto-discovered by downstream agents via `spec load --category` — plan agents pick up design/architecture flows, test agents pick up verification methods, coding agents pick up execution steps.
 
-Three modes:
+Four modes:
 
 1. **Extract** — Pull reusable processes from conversations/code/docs
 2. **Generate** — Create new tool definitions from user description
 3. **Optimize** — Improve existing tool spec steps, structure, clarity
+4. **Promote** — Convert existing knowhow document to tool (add `tool: true` + category in place)
 
 Short processes (<10 steps) inline; long processes (>=10 steps or with code examples) use ref mode with knowhow detail doc (RCP-/DOC-).
 </purpose>
@@ -25,6 +26,8 @@ $maestro-tools-register "extract OAuth PKCE token exchange flow from src/auth/"
 $maestro-tools-register "generate Stripe webhook idempotency verification"
 $maestro-tools-register "generate E2E checkout flow with payment gateway mock setup"
 $maestro-tools-register "optimize e2e-checkout tool"
+$maestro-tools-register "promote RCP-db-migration-rollback as test tool"
+$maestro-tools-register "promote knowhow-auth-api to coding tool"
 ```
 
 **Tool registration**: Creates knowhow documents in `knowhow/` folder with `tool: true` in YAML frontmatter. Tools are auto-discovered by `spec load` based on category + tool flag.
@@ -50,6 +53,7 @@ Step content...
 Parse $ARGUMENTS to determine mode:
 - Contains "extract" → extract mode
 - Contains "optimize/improve" → optimize mode
+- Contains "promote" or references existing knowhow doc (path/ID) → promote mode
 - Other → generate mode
 - Empty → ask user with AskUserQuestion
 
@@ -67,16 +71,34 @@ Parse $ARGUMENTS to determine mode:
 - Load existing tool: `maestro spec load --category coding --keyword <name>`
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
+**Promote mode** (existing knowhow → tool):
+- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Read document, verify it contains actionable steps (numbered list or ## Steps section)
+- If no actionable steps, suggest extract mode instead
+- Determine category (Step 3) and summary ("Use when ...")
+- Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
+- Do NOT recreate the document — modify in place
+
 **For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
 
 ### Step 3: Determine Category
 
-Infer applicable category from context, or ask user:
-- coding — execution tools (build, deploy, integrate)
-- test — testing tools (test flows, verification steps)
-- review — review tools (checklists, audit standards)
-- arch — planning tools (design flows, analysis steps)
-- debug — analysis tools (diagnostic flows, investigation steps)
+**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
+
+| Category | Consumer Agent | Decision Question | Signal Words |
+|---|---|---|---|
+| `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
+| `test` | tdd-developer, test-fix-agent | 测试者验证行为时需要这个流程吗？ | verify, validate, assert, e2e, regression, coverage, idempotency |
+| `review` | workflow-reviewer | 审查者需要这个作为 checklist 吗？ | audit, checklist, compliance, quality-gate, standard |
+| `arch` | workflow-planner | 规划者设计方案时需要这个吗？ | design, architecture, decompose, trade-off, migration-strategy |
+| `debug` | debug-explore-agent | 调试者排查问题时需要这个吗？ | diagnose, trace, investigate, root-cause, reproduce |
+
+**Multi-consumer split**: If content serves multiple consumers (e.g., API doc for both dev and test), split into separate documents:
+- API contract (what endpoints look like) → `category: coding` (AST-*, tool: false)
+- API verification steps (how to test) → `category: test` (RCP-*, tool: true)
+- Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
+
+**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
 
 ### Step 4: Decide Inline vs Ref
 

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -104,6 +104,7 @@ id,wave,title,description,agent_type,deps,status,findings,output_path,error
 </csv_schema>
 
 <invariants>
+0. **Load UI Specs**: Before extraction, load project UI conventions via `maestro spec load --category ui` (if available). Ensures extracted tokens align with existing conventions.
 1. **Start Immediately**: First action is argument parsing, then validation
 2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results are merged
 3. **CSV is Source of Truth**: Master tasks.csv holds all state

package/.codex/skills/maestro-ui-craft/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: maestro-ui-craft
+description: Chain maestro-impeccable commands with intelligent routing and quality gate loops for automated UI production
+argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [-y] [-c]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, request_user_input
+---
+<purpose>
+Orchestrate maestro-impeccable skill commands via intelligent intent routing + quality gate auto-iteration.
+Chain: Build → Evaluate → Auto-Refine → Re-evaluate → Verify.
+
+Core innovation: critique/audit scores drive automatic command selection and iteration loops.
+maestro-impeccable has 23 commands across 6 categories -- this command chains them into automated pipelines
+with quality gates that loop until design quality meets the threshold.
+
+Prerequisite: maestro-impeccable skill available (auto-discovered by harness).
+
+Session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
+</purpose>
+
+<invariants>
+1. **Session before execution** -- status.json created before any chain step runs
+2. **All steps via Skill** -- every impeccable command dispatched through `$maestro-impeccable`
+3. **Gate scores drive loops** -- refine loop auto-selects commands from P0/P1 findings, never from hardcoded lists
+4. **Interactive gates respected** -- teach, shape, craft retain their user gates; never suppress
+</invariants>
+
+<context>
+$ARGUMENTS -- intent description or target path, with optional flags.
+
+**Keywords:** `continue`/`next` → resume previous session
+
+**Usage:**
+
+```bash
+$maestro-ui-craft "create a landing page"
+$maestro-ui-craft "improve the dashboard" --chain improve
+$maestro-ui-craft "add animations" --chain enhance --enhance animate
+$maestro-ui-craft "production ready" --chain harden
+$maestro-ui-craft -c                               # resume previous session
+$maestro-ui-craft -y "create pricing page --chain build"
+```
+
+**Flags:**
+- `--chain <type>` -- Force chain type: build, improve, enhance, harden, live
+- `--enhance <cmd>` -- Specific enhance command (animate|colorize|typeset|layout|delight|overdrive|bolder)
+- `--threshold <score>` -- Critique pass threshold (default: 26/40). Audit threshold auto-computed as threshold*0.5
+- `--max-loops <n>` -- Maximum quality gate iterations (default: 3)
+- `-c` / `--continue` -- Resume previous ui-craft session
+- `-y` -- Auto mode: auto-select at ambiguous routing, skip confirmations where maestro-impeccable allows
+</context>
+
+<chains>
+
+### Chain Definitions
+
+| Chain | Sequence | Gate Condition |
+|-------|----------|----------------|
+| **build** | teach? → shape → craft → **critique** → [refine loop] → audit → polish | critique >= threshold AND P0 == 0 |
+| **improve** | **critique** → [refine loop] → polish → audit | critique >= threshold AND P0 == 0 |
+| **enhance** | {cmd} → **critique** → polish (if needed) | critique >= threshold |
+| **harden** | harden → **audit** → polish | audit >= threshold*0.5 |
+| **live** | live | -- (interactive, no gate) |
+
+- `teach?` -- conditional: only if PRODUCT.md missing/placeholder
+- `[refine loop]` -- quality gate loop: extract suggested commands from critique → execute → re-critique
+
+### Intent → Chain Routing
+
+| Intent Pattern | Chain |
+|---------------|-------|
+| create, build, new, landing, feature, page | build |
+| improve, fix, iterate, better, optimize | improve |
+| animate, color, type, bold, delight, enhance | enhance |
+| production, harden, ship, edge case, i18n | harden |
+| live, browser, variant | live |
+
+Explicit `--chain` overrides routing. Ambiguous + no `-y` → `request_user_input`.
+
+</chains>
+
+<state_machine>
+
+<states>
+S_PARSE      -- parse args, intent classification, chain selection       PERSIST: --
+S_RESUME     -- scan existing ui-craft sessions, resume execution         PERSIST: --
+S_SETUP      -- load context, check PRODUCT.md                           PERSIST: --
+S_CREATE     -- create session + status.json                              PERSIST: session (full)
+S_CHAIN      -- execute chain steps in sequence                           PERSIST: step progress, executed commands
+S_GATE       -- quality gate: parse scores, decide                        PERSIST: scores, loop count
+S_REFINE     -- execute auto-selected refine commands                     PERSIST: refine commands, loop state
+S_REPORT     -- final report + trend                                      PERSIST: final scores, status
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_RESUME     WHEN: -c / --continue flag OR keyword "continue"/"next"
+  → S_SETUP      WHEN: chain selected (explicit or routed)
+  → S_PARSE      WHEN: ambiguous AND not -y          DO: request_user_input
+  → END          WHEN: no intent AND no target → E002
+
+S_RESUME:
+  → S_CHAIN      WHEN: session found                  DO: A_LOCATE_SESSION
+  → END          WHEN: no session found → E005
+
+S_SETUP:
+  → S_CREATE     DO: A_LOAD_CONTEXT
+
+S_CREATE:
+  → S_CHAIN      DO: A_CREATE_SESSION
+
+S_CHAIN:
+  → S_GATE       WHEN: current step is gate command (critique/audit)
+  → S_CHAIN      WHEN: step is normal command → execute → advance
+  → S_REPORT     WHEN: all steps complete
+
+S_GATE:
+  → S_CHAIN      WHEN: PASS (score >= threshold AND P0 == 0) → advance
+  → S_REFINE     WHEN: FAIL (score < threshold OR P0 > 0)
+  → S_CHAIN      WHEN: max loops exceeded → W002 → force advance
+
+S_REFINE:
+  → S_GATE       DO: execute auto-selected commands → re-run gate command
+                  GUARD: loop_count < max_loops
+
+S_REPORT:
+  → END          DO: A_FINAL_REPORT
+
+</transitions>
+
+<actions>
+
+### A_LOCATE_SESSION
+
+1. Scan `.workflow/.maestro/ui-craft-*/status.json`, filter `status == "running"`, sort DESC
+2. Take most recent; load into context as current session
+3. Resume from `current_step` position
+
+### A_LOAD_CONTEXT
+
+1. Trigger impeccable context loading: `$maestro-impeccable teach`
+   - Impeccable's own setup auto-discovers and loads PRODUCT.md / DESIGN.md from `.workflow/impeccable/`
+   - If PRODUCT.md missing/placeholder, impeccable teach handles the interview
+2. If teach was not in the chain but PRODUCT.md is missing:
+   - Prepend `teach` to chain start
+   - Announce: W001
+3. Context is now loaded for subsequent commands
+
+### A_CREATE_SESSION
+
+1. Read `.workflow/state.json` for project context (phase, milestone)
+2. Create `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`:
+   ```json
+   { "session_id": "ui-craft-{ts}", "source": "ui-craft", "intent": "...",
+     "chain_type": "build|improve|enhance|harden|live", "target": "...",
+     "auto_mode": false, "threshold": 26, "max_loops": 3,
+     "steps": [{ "index": 0, "command": "shape", "status": "pending" }],
+     "gate_history": [], "loop_count": 0,
+     "current_step": 0, "status": "running",
+     "created_at": "ISO-8601", "updated_at": "ISO-8601" }
+   ```
+3. Write status.json before executing any step
+
+### A_FINAL_REPORT
+
+1. Read critique trend if available (impeccable's critique persists snapshots automatically)
+2. Update status.json with `status: "completed"` and final scores
+3. Present summary table with scores, iterations, commands executed
+
+</actions>
+
+</state_machine>
+
+<execution>
+
+## 1. Parse & Route
+
+1. If `-c` / `--continue` or keyword "continue"/"next" → S_RESUME
+2. If `--chain` present → use directly
+3. Otherwise → match $ARGUMENTS against intent patterns
+4. If `--enhance` present → chain = enhance, cmd = --enhance value
+5. For enhance chain without `--enhance` → infer from intent
+6. Ambiguous + no `-y` → `request_user_input`:
+   ```json
+   { "questions": [{ "id": "chain_select", "header": "Chain", "question": "Which workflow?", "options": [
+     { "label": "Build (Recommended)", "description": "New UI from scratch: shape → craft → critique → refine → audit" },
+     { "label": "Improve", "description": "Iterate existing: critique → refine → polish → audit" },
+     { "label": "Enhance", "description": "Targeted improvement: specific command → critique → polish" },
+     { "label": "Harden", "description": "Production-ready: harden → audit → polish" }
+   ]}] }
+   ```
+
+## 2. Setup Context
+
+1. If chain starts with `teach` → execute it first, maestro-impeccable handles context loading internally
+2. Otherwise → invoke `$maestro-impeccable` with no args to trigger setup (context + register)
+3. If maestro-impeccable reports PRODUCT.md missing → prepend teach, execute, then resume
+
+## 3. Create Session
+
+Write `.workflow/.maestro/ui-craft-{ts}/status.json` with chain steps before any execution.
+
+## 4. Execute Chain
+
+For each step in chain, sequentially:
+
+```
+Step {n}/{total}: $maestro-impeccable {command} {target}
+```
+
+After each step: update status.json `current_step` and step `status`.
+
+**Rules:**
+- `teach`, `shape`, `craft` are interactive -- do NOT suppress their user gates
+- After `teach` completes → re-run context loader for fresh PRODUCT.md
+- After `craft` completes → the build exists, ready for evaluation
+- Gate steps (critique/audit) → transition to quality gate logic
+
+## 5. Quality Gate
+
+When chain reaches a gate step (critique or audit):
+
+### 5a. Execute Gate Command
+
+```
+$maestro-impeccable critique {target}
+```
+or
+```
+$maestro-impeccable audit {target}
+```
+
+### 5b. Parse Score
+
+From critique output, extract:
+- **score**: Nielsen's total (N/40) -- from "**Total** | | **N/40**" row
+- **P0_count**: count of `[P0]` tagged findings
+- **P1_count**: count of `[P1]` tagged findings
+- **suggested_commands**: list of "$maestro-impeccable <cmd>" from "Suggested command" fields
+
+From audit output, extract:
+- **score**: dimension total (N/20) -- from "**Total** | | **N/20**" row
+- **P0_count**: count of `[P0]` findings
+
+### 5c. Evaluate
+
+```
+critique_pass = (score >= threshold) AND (P0_count == 0)
+audit_pass    = (score >= threshold * 0.5) AND (P0_count == 0)
+```
+
+### 5d. On PASS
+
+→ advance to next chain step
+
+### 5e. On FAIL
+
+1. Collect suggested commands from P0/P1 findings
+2. If no suggestions found → use fallback mapping (see quality_gate_routing)
+3. De-duplicate, cap at 3 commands per iteration
+4. Sort: P0-suggested first
+5. Execute each: `$maestro-impeccable {cmd} {target}`
+6. Re-run gate command (critique/audit)
+7. Increment loop_count
+8. Append to status.json `gate_history`
+
+### 5f. On Max Loops Exceeded
+
+→ force advance to next chain step with warning
+
+## 6. Final Report
+
+Present summary: chain type, critique score with trend, audit score, loop count, commands executed, pass/partial status.
+
+Update status.json: `status: "completed"`, `final_scores`, `completed_at`.
+
+If issues remain → suggest: "Run `$maestro-ui-craft --chain improve {target}` to continue iteration."
+
+</execution>
+
+<quality_gate_routing>
+
+### Finding → Command Fallback Mapping
+
+When critique/audit findings lack explicit "Suggested command", map by category:
+
+| Finding Category | Command |
+|-----------------|---------|
+| Visual hierarchy, layout, spacing, alignment | layout |
+| Color, contrast, palette, monochromatic | colorize |
+| Typography, font, readability, hierarchy | typeset |
+| Animation, motion, transitions, micro-interaction | animate |
+| Copy, labels, error messages, UX writing | clarify |
+| Responsive, mobile, breakpoints, touch targets | adapt |
+| Performance, loading, speed, bundle, jank | optimize |
+| Complexity, overload, clutter, cognitive load | distill |
+| Bland, safe, generic, lacks personality | bolder |
+| Aggressive, overwhelming, loud, overstimulating | quieter |
+| Onboarding, empty state, first-run, activation | onboard |
+| Edge cases, i18n, error handling, overflow | harden |
+| Personality, memorability, joy, delight | delight |
+
+### Commands Never Auto-Selected
+
+| Command | Reason |
+|---------|--------|
+| teach | Project setup (run in S_SETUP only) |
+| shape | Requires user interview |
+| craft | Full build with multiple gates |
+| live | Interactive browser mode |
+| document | Generates DESIGN.md (setup) |
+| extract | Design system extraction (setup) |
+| overdrive | Requires explicit user vision |
+| critique | Gate command, not a fix |
+| audit | Gate command, not a fix |
+
+</quality_gate_routing>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | error | maestro-impeccable skill not found |
+| E002 | error | No intent or target specified |
+| E003 | error | Invalid --chain type |
+| E004 | error | Invalid --enhance command |
+| E005 | error | Resume session not found |
+| W001 | warning | PRODUCT.md missing, prepending teach to chain |
+| W002 | warning | Max quality gate loops exceeded, forcing continue |
+| W003 | warning | Could not parse score from critique/audit output |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain type selected
+- [ ] Context loaded (PRODUCT.md present or taught)
+- [ ] Session dir created with status.json before execution
+- [ ] All chain steps executed via $maestro-impeccable
+- [ ] Quality gate evaluated with parsed scores
+- [ ] Refine loop executed when gate failed (if applicable)
+- [ ] Gate history and scores persisted to status.json
+- [ ] Final report with scores and trend presented
+</success_criteria>

package/.codex/skills/maestro-ui-design/SKILL.md

@@ -60,6 +60,16 @@ When `--yes` or `-y`: Skip interactive selection, auto-pick top-scored variant,
 
 <execution>
 
+### Step 0: Load UI Specs
+
+Load project UI conventions before generating designs:
+
+```bash
+maestro spec load --category ui
+```
+
+If specs not initialized, continue without — the workflow still produces valid output.
+
 ### Step 1: Parse Input and Resolve Target
 
 1. Parse flags from `$ARGUMENTS`: `--styles N`, `--stack`, `--targets`, `--persist`, `--full`, `-y`