maestro-flow 0.3.47 → 0.3.49

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -2,11 +2,13 @@
 name: maestro-milestone-audit
 description: Audit current milestone for cross-phase integration gaps
 argument-hint: "[milestone, e.g., 'M1']"
-allowed-tools: Read, Write, Bash, Glob, Grep, Agent
+allowed-tools: spawn_agents_on_csv, Read, Write, Bash, Glob, Grep
 ---
 
 <purpose>
-Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration. Produces PASS/FAIL verdict report.
+Sequential audit based on artifact registry in state.json. Checks phase coverage (ANL->PLN->EXC chains), ad-hoc completeness, execution completeness, and cross-artifact integration via `spawn_agents_on_csv`. Produces PASS/FAIL verdict report.
+
+**Core workflow**: Load Artifacts -> Coverage Check -> Completeness Check -> CSV Wave (Integration Check) -> Verdict
 </purpose>
 
 <context>
@@ -16,14 +18,52 @@ $maestro-milestone-audit ""
 $maestro-milestone-audit "M1"
 ```
 
-**Output**: Audit report with artifact chain verification, integration analysis, and PASS/FAIL verdict
+**Output**: `.workflow/milestones/{milestone}/audit-report.md` with artifact chain verification, integration analysis, and PASS/FAIL verdict
 
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-audit-{milestone}/`
 </context>
 
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,scope,check_targets,deps,wave,status,findings,gaps_found,severity,error
+"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1","","","","",""
+"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1","","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Worker identifier: `integ-{N}` |
+| `title` | Input | Integration dimension name |
+| `description` | Input | Detailed check instructions |
+| `scope` | Input | What to examine |
+| `check_targets` | Input | Specific verification commands/grep patterns |
+| `deps` | Input | Dependencies (empty — all wave 1) |
+| `wave` | Computed | Wave number (always 1 — single parallel wave) |
+| `status` | Output | `pending` -> `pass` / `fail` / `warning` |
+| `findings` | Output | Detailed findings per dimension (max 500 chars) |
+| `gaps_found` | Output | Semicolon-separated list of integration gaps |
+| `severity` | Output | `critical` / `warning` / `info` per gap |
+| `error` | Output | Error message if check failed |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-audit-{milestone}/
++-- tasks.csv
++-- wave-1.csv (temporary)
++-- wave-1-results.csv
+```
+</csv_schema>
+
 <invariants>
 1. **Artifact registry is source of truth** — don't scan directories, read state.json
 2. **Non-blocking warnings** — missing analyze is warning, missing execute is error
-3. **Integration check is required** — always spawn checker agent
+3. **Integration check is required** — always spawn checker via CSV wave
 4. **Clear verdict** — PASS or FAIL with specific reasons
 </invariants>
 
@@ -45,9 +85,26 @@ For each phase: check for completed analyze (optional), plan (required), execute
 
 Verify all adhoc-scoped artifacts completed. For each execute artifact, verify all tasks in plan dir completed.
 
-### Step 5: Integration Check
+### Step 5: Integration Check via CSV Wave
+
+1. Create session folder: `.workflow/.csv-wave/{dateStr}-audit-{milestone}/`
+2. Build `tasks.csv` from csv_schema — populate `scope` and `check_targets` columns using phase artifacts discovered in Step 2
+3. Write `wave-1.csv` from pending rows, then execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: `You are an integration checker for milestone ${milestone}. For each row, examine the scope and check_targets. Search the codebase for inconsistencies, contract drift, and broken dependencies across phase outputs. Report findings with file:line references. Set status to pass/fail/warning. List specific gaps in gaps_found (semicolon-separated).`,
+  max_concurrency: 2, max_runtime_seconds: 600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: { id, status: [pass|fail|warning], findings, gaps_found, severity, error }
+})
+```
 
-Spawn Agent for cross-phase validation: shared interfaces, dependency chains, data contracts, API consistency. Write report to `.workflow/milestones/{milestone}/audit-report.md`.
+4. Merge results into master `tasks.csv`
+5. Parse `gaps_found` from all workers — aggregate into `.workflow/milestones/{milestone}/audit-report.md`
+6. Any worker with `status == fail` and `severity == critical` → milestone verdict = FAIL
 
 ### Step 6: Verdict
 
@@ -81,7 +138,7 @@ Display structured audit report.
 - [ ] Artifact registry loaded and filtered by milestone
 - [ ] Phase coverage matrix generated
 - [ ] Ad-hoc and execution completeness verified
-- [ ] Integration check performed via agent
+- [ ] Integration check performed via spawn_agents_on_csv (2 parallel workers)
 - [ ] Audit report written to milestones/ directory
 - [ ] Clear PASS/FAIL verdict with specific reasons
 </success_criteria>

package/.codex/skills/maestro-quick/SKILL.md

@@ -2,7 +2,7 @@
 name: maestro-quick
 description: Quick task execution, skip optional agents
 argument-hint: "\"task description\" [--discuss] [--full]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>

package/.codex/skills/maestro-ralph/SKILL.md

@@ -156,17 +156,28 @@ S_FALLBACK -> S_PARSE_ROUTE WHEN: user input | -> END WHEN: cancel
 | Has .workflow/ but no state.json | init |
 | Has state.json | artifact-based inference |
 
-**Artifact-based**: filter by current_milestone + target phase. Latest artifact type: none->analyze, analyze->plan, plan->execute, execute->verify, verify->refine from result files:
+**Artifact-based inference:** Filter by current_milestone + target phase:
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] non-empty | verify-failed |
-| passed==true, no review.json, has auto-test report | review |
-| passed==true, no review.json, no auto-test report | business-test (full) / review (standard/quick) |
-| review.json: verdict=="BLOCK" | review-failed |
-| review.json: verdict!="BLOCK" | test |
-| uat.md: all passed | milestone-audit |
-| uat.md: has failures | test-failed |
+| no milestones defined or no roadmap.md | `roadmap` |
+| no artifacts for target phase | `analyze` |
+| latest artifact = analyze | `plan` |
+| latest artifact = plan | `execute` |
+| latest artifact = execute | `verify` |
+| latest artifact = verify | → refine from result files |
+
+**Refine from verify results:**
+
+| Condition | Position |
+|-----------|----------|
+| verification.json: passed==false or gaps[] non-empty | `verify-failed` |
+| passed==true, no review.json, has auto-test report | `review` |
+| passed==true, no review.json, no auto-test report | `business-test` (full) / `review` (standard/quick) |
+| review.json: verdict=="BLOCK" | `review-failed` |
+| review.json: verdict!="BLOCK" | `test` |
+| uat.md: all passed | `milestone-audit` |
+| uat.md: has failures | `test-failed` |
 
 ### A_RESOLVE_PHASE
 
@@ -182,23 +193,32 @@ Priority: regex from intent `phase\s*(\d+)` -> latest in-progress artifact's pha
 
 ### A_BUILD_STEPS
 
-Lifecycle stages (start from position, skip completed, filter by quality_mode):
-
-| Stage | Skill | Barrier | Decision after |
-|-------|-------|---------|----------------|
-| brainstorm | maestro-brainstorm | yes | -- |
-| init | maestro-init | no | -- |
-| roadmap | maestro-roadmap | yes | -- |
-| analyze | maestro-analyze | yes | -- |
-| plan | maestro-plan | yes | -- |
-| execute | maestro-execute | yes | -- |
-| verify | maestro-verify | no | post-verify |
-| business-test | quality-auto-test | no | post-business-test (full) |
-| review | quality-review | no | post-review |
-| test-gen | quality-auto-test | no | -- (full; standard if coverage<80%) |
-| test | quality-test | no | post-test |
-| milestone-audit | maestro-milestone-audit | no | -- |
-| milestone-complete | maestro-milestone-complete | no | post-milestone |
+**Lifecycle stages:**
+
+| Stage | Skill | Barrier | Quality Mode | Decision after |
+|-------|-------|---------|-------------|----------------|
+| brainstorm | maestro-brainstorm "{intent}" | yes | all | — |
+| init | maestro-init | no | all | — |
+| roadmap | maestro-roadmap "{intent}" | yes | all | — |
+| analyze | maestro-analyze {phase} | yes | all | — |
+| plan | maestro-plan {phase} | yes | all | — |
+| execute | maestro-execute {phase} | yes | all | — |
+| verify | maestro-verify {phase} | no | all | post-verify |
+| business-test | quality-auto-test {phase} | no | full only | post-business-test |
+| review | quality-review {phase} | no | all (quick: --tier quick) | post-review |
+| test-gen | quality-auto-test {phase} | no | full; standard if coverage<80% | — |
+| test | quality-test {phase} | no | full, standard | post-test |
+| milestone-audit | maestro-milestone-audit | no | all | — |
+| milestone-complete | maestro-milestone-complete | no | all | post-milestone |
+
+**Build rules:**
+1. Start from `lifecycle_position`, end at `milestone-complete`
+2. Skip stages with existing completed artifacts (check state.json)
+3. Filter stages by `quality_mode` — skip non-applicable stages (see Quality Mode column)
+4. Quick mode: `review` appends `--tier quick`; skips `business-test`, `test-gen`, `test`
+5. Insert decision node after each stage with non-empty Decision column: `{ type: "decision", decision: "<gate>", retry_count: 0, max_retries: 2 }`
+6. Args use placeholders `{phase}`, `{intent}`, `{dirs}` — resolved at wave execution time
+7. Append `-y` to all skill args when `auto_mode` is true (see -y propagation table in context)
 
 ### A_BUILD_AND_SPAWN_WAVE
 

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -158,7 +158,7 @@ Build prev_context from wave 1. Inject strategy + --phases constraint (light mod
    +-- readiness-report.md
    ```
 7. Update state.json milestones + current_milestone
-8. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-ui-design; full mode setup -> maestro-init
+8. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-ui-craft --chain build; full mode setup -> maestro-init
 
 </actions>
 

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

@@ -2,7 +2,7 @@
 name: maestro-tools-execute
 description: Load and execute tool specs by role or name
 argument-hint: "[tool-name | --category <category>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>

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

@@ -2,7 +2,7 @@
 name: maestro-tools-register
 description: Register tool specs - extract, generate, or optimize reusable process definitions
 argument-hint: "[description or intent]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>

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

@@ -1,17 +1,20 @@
 ---
 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
+argument-hint: "<intent|target> [--chain build|improve|enhance|harden|live] [--enhance <cmd>] [--threshold <score>] [--max-loops <n>] [--skip-design-explore] [--skip-design] [--styles <N>] [--stack <stack>] [-y] [-c]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, 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
+maestro-impeccable has 24 commands across 6 categories -- this command chains them into automated pipelines
 with quality gates that loop until design quality meets the threshold.
 
+Includes integrated design-explore: delegates to `impeccable explore` for multi-variant design system generation,
+HTML prototype rendering for visual comparison, and automatic bridge to DESIGN.md format.
+
 Prerequisite: maestro-impeccable skill available (auto-discovered by harness).
 
 Session: `.workflow/.maestro/ui-craft-{YYYYMMDD-HHmmss}/status.json`
@@ -47,6 +50,9 @@ $maestro-ui-craft -y "create pricing page --chain build"
 - `--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
+- `--skip-design-explore` / `--skip-design` -- Skip design-explore (prototype comparison) and bridge (use existing DESIGN.md or full shape interview)
+- `--styles <N>` -- Number of design system variants to generate (2-5, default 3). Only used in build chain design step
+- `--stack <stack>` -- Tech stack for supplementary guidelines (default: html-tailwind). Passed to ui-search
 </context>
 
 <chains>
@@ -55,13 +61,14 @@ $maestro-ui-craft -y "create pricing page --chain build"
 
 | Chain | Sequence | Gate Condition |
 |-------|----------|----------------|
-| **build** | teach? → shape → craft → **critique** → [refine loop] → audit → polish | critique >= threshold AND P0 == 0 |
+| **build** | teach? → **design_explore?** → 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
+- `design_explore?` -- conditional: only if DESIGN.md missing AND `--skip-design-explore` not set. Delegates to `impeccable explore` which handles variant generation, prototype rendering, visual comparison, user selection/mix, AND bridge to DESIGN.md internally
 - `[refine loop]` -- quality gate loop: extract suggested commands from critique → execute → re-critique
 
 ### Intent → Chain Routing
@@ -69,6 +76,7 @@ $maestro-ui-craft -y "create pricing page --chain build"
 | Intent Pattern | Chain |
 |---------------|-------|
 | create, build, new, landing, feature, page | build |
+| design, style, theme, visual, design system | build |
 | improve, fix, iterate, better, optimize | improve |
 | animate, color, type, bold, delight, enhance | enhance |
 | production, harden, ship, edge case, i18n | harden |
@@ -85,6 +93,7 @@ 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_DESIGN_EXPLORE -- delegate to impeccable explore: multi-variant generation, prototype comparison, selection/mix, auto bridge to DESIGN.md  PERSIST: explore_completed, design_md_path
 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
@@ -110,10 +119,16 @@ S_CREATE:
   → S_CHAIN      DO: A_CREATE_SESSION
 
 S_CHAIN:
+  → S_DESIGN_EXPLORE  WHEN: current step is 'design_explore' AND DESIGN.md missing AND --skip-design-explore not set AND --skip-design not set
   → S_GATE       WHEN: current step is gate command (critique/audit)
+  → S_CHAIN      WHEN: step is design_explore but skip conditions met → advance
   → S_CHAIN      WHEN: step is normal command → execute → advance
   → S_REPORT     WHEN: all steps complete
 
+S_DESIGN_EXPLORE:
+  → S_CHAIN      WHEN: explore completed (DESIGN.md produced) → advance to shape
+  → S_CHAIN      WHEN: explore failed → W004 → advance to shape (full interview fallback)
+
 S_GATE:
   → S_CHAIN      WHEN: PASS (score >= threshold AND P0 == 0) → advance
   → S_REFINE     WHEN: FAIL (score < threshold OR P0 > 0)
@@ -161,6 +176,15 @@ S_REPORT:
    ```
 3. Write status.json before executing any step
 
+### A_DESIGN_EXPLORE
+
+Delegate to impeccable explore as a black-box command. The explore command internally handles:
+variant generation, prototype rendering, visual comparison, user review, mix protocol, rejected variant harvest, bridge to DESIGN.md, and spec registration.
+
+1. Execute: `$maestro-impeccable explore --styles {styles_count}`
+2. On completion: verify `.workflow/impeccable/DESIGN.md` exists
+3. Update status.json: `explore_completed: true`, `design_md_path`
+
 ### A_FINAL_REPORT
 
 1. Read critique trend if available (impeccable's critique persists snapshots automatically)
@@ -210,11 +234,26 @@ Step {n}/{total}: $maestro-impeccable {command} {target}
 
 After each step: update status.json `current_step` and step `status`.
 
-**Rules:**
+**Step-specific logic:**
+
+### 4a. Design-explore step (build chain only)
+
+When current step is `design_explore`:
+
+1. Check if `.workflow/impeccable/DESIGN.md` already exists → skip, advance to shape
+2. Check if `--skip-design-explore` or `--skip-design` is set → skip, advance to shape
+3. Otherwise → execute A_DESIGN_EXPLORE:
+   - `$maestro-impeccable explore --styles {styles_count}`
+   - explore handles everything internally: variant generation, prototype rendering, visual comparison, user selection/mix, bridge to DESIGN.md, spec registration
+4. On completion → verify DESIGN.md exists, advance to shape
+5. On failure → W004, advance to shape (full interview fallback, no DESIGN.md)
+
+### 4c. Normal steps
+
 - `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
+- Gate steps (critique/audit) → transition to quality gate logic (Section 5)
 
 ## 5. Quality Gate
 
@@ -313,6 +352,7 @@ When critique/audit findings lack explicit "Suggested command", map by category:
 | overdrive | Requires explicit user vision |
 | critique | Gate command, not a fix |
 | audit | Gate command, not a fix |
+| explore | Design system exploration (setup, has own user interaction) |
 
 </quality_gate_routing>
 
@@ -327,6 +367,11 @@ When critique/audit findings lack explicit "Suggested command", map by category:
 | 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 |
+| E006 | error | Python 3 not available for design system generation |
+| E007 | error | ui-search scripts not found at expected path |
+| W004 | warning | Design system generation failed, skipping design+bridge |
+| W005 | warning | Bridge transformation failed, continuing without DESIGN.md |
+| W008 | warning | Node.js not available for prototype rendering, falling back to text-only variant comparison |
 </error_codes>
 
 <success_criteria>

package/.codex/skills/quality-refactor/SKILL.md

@@ -2,11 +2,13 @@
 name: quality-refactor
 description: Reduce tech debt with reflection-driven iteration
 argument-hint: "<phase|--dir path> [--max-iterations N]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---
 
 <purpose>
-Iterative refactoring cycle: analyze scope for tech debt -> plan refactoring tasks -> execute each with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
+Iterative refactoring cycle via `spawn_agents_on_csv`: analyze scope for tech debt -> plan refactoring tasks -> execute each as single-row CSV wave with test verification -> reflect on strategy per round -> repeat if needed. Every change is verified against existing tests. Failed changes are reverted and retried with adjusted strategy.
+
+**Core workflow**: Parse Scope -> Analyze -> Plan -> CSV Wave-by-Wave Execution -> Reflect -> Verdict
 </purpose>
 
 <context>
@@ -28,8 +30,61 @@ $quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume e
 - `--max-iterations N`: Max refactoring rounds (default: 3)
 
 **Output**: `.workflow/scratch/refactor-{slug}-{date}/` with index.json, plan.json, reflection-log.md, .task/, .summaries/
+
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-refactor-{slug}/`
 </context>
 
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,category,scope,convergence_criteria,read_first,verification_cmd,risk,deps,wave,status,findings,files_modified,tests_passed,retry_count,strategy_adjustment,error
+"TASK-001","Extract shared validation","Extract duplicated email/phone validation logic into shared utils module","duplication","src/auth/login.ts;src/auth/register.ts","src/utils/validation.ts contains export function validateEmail(; grep -r 'validateEmail' shows single import source","src/auth/login.ts;src/auth/register.ts;src/utils/","npm test","low","","1","","","","","0","",""
+"TASK-002","Simplify token refresh","Reduce cyclomatic complexity in token refresh handler from 12 to <6","complexity","src/auth/token.ts","src/auth/token.ts function refreshToken has no more than 2 levels of nesting","src/auth/token.ts;src/auth/types.ts","npm test -- --grep token","medium","","2","","","","","0","",""
+"TASK-003","Remove dead session code","Remove unused session cleanup functions identified in analysis","dead_code","src/session/","grep -r 'cleanupExpired' returns 0 matches outside test files","src/session/cleanup.ts","npm test","low","","1","","","","","0","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Task ID (TASK-NNN, from plan.json) |
+| `title` | Input | Short refactoring task title |
+| `description` | Input | What to refactor and why |
+| `category` | Input | Tech debt category: duplication / complexity / naming / dependencies / dead_code / pattern_violations |
+| `scope` | Input | Semicolon-separated target files/directories |
+| `convergence_criteria` | Input | Grep-verifiable completion criteria (semicolon-separated) |
+| `read_first` | Input | Files to read before implementing (context) |
+| `verification_cmd` | Input | Test command to run after change |
+| `risk` | Input | `low` / `medium` / `high` |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `wave` | Computed | Wave number — same-risk independent tasks can share a wave |
+| `status` | Output | `pending` -> `completed` / `failed` / `blocked` / `skipped` |
+| `findings` | Output | Implementation notes (max 500 chars) |
+| `files_modified` | Output | Semicolon-separated list of changed files |
+| `tests_passed` | Output | `true` / `false` — verification result |
+| `retry_count` | State | Current retry count (max 2) |
+| `strategy_adjustment` | State | Strategy change note for retry |
+| `error` | Output | Error message if failed |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates `wave-{N}.csv` with extra `prev_context` column populated from predecessor task findings.
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-refactor-{slug}/
++-- tasks.csv
++-- results.csv
++-- discoveries.ndjson
++-- reflection-log.md
++-- wave-{N}.csv (temporary)
++-- wave-{N}-results.csv
+```
+</csv_schema>
+
 <invariants>
 1. **Test after every change** -- zero regressions tolerated
 2. **Revert on failure** -- never leave broken state
@@ -37,7 +92,7 @@ $quality-refactor "--dir .workflow/scratch/refactor-auth-2026-03-18"  # resume e
 4. **Reflection-driven** -- every round records strategy, outcome, adjustment
 5. **User approval required** before execution (Step 4)
 6. **Quick wins first** -- order by risk (low first) and dependency
-7. **Agent calls use `run_in_background: false`** for synchronous execution
+7. **CSV waves execute synchronously** — each refactoring task dispatched as single-row wave, wait for completion before next
 8. **Incremental safety** -- each task is independently safe to apply or revert
 </invariants>
 
@@ -88,28 +143,62 @@ Confirm with user before proceeding.
 4. Update `index.json` plan fields
 5. Present plan to user via AskUserQuestion -- show affected files, risk areas, ask for approval
 
-### Step 5: Execute with Reflection
-
-Initialize `reflection-log.md` if not exists.
+### Step 5: Execute with Reflection via CSV Waves
+
+Initialize session folder `.workflow/.csv-wave/{dateStr}-refactor-{slug}/`.
+Initialize `reflection-log.md` and `discoveries.ndjson` in session folder.
+Build `tasks.csv` from plan.json tasks using csv_schema columns.
+
+**Wave computation**: Group independent same-risk tasks into shared waves. Dependent tasks go to later waves. Low-risk tasks wave first, high-risk last.
+
+For each wave N in ascending order:
+
+**5a. Build and spawn wave:**
+
+1. Extract wave N pending rows from master `tasks.csv`
+2. Build `prev_context` per task from completed predecessor findings
+3. Write `wave-{N}.csv`, then execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-${N}.csv`,
+  id_column: "id",
+  instruction: `You are a refactoring executor. For each task:
+1. Read files listed in read_first to understand context
+2. Apply refactoring described in description targeting scope files
+3. Verify convergence_criteria via grep (all criteria must pass)
+4. Run verification_cmd and report test result
+5. If tests fail: revert ALL changes for this task, set status=failed
+6. Append discoveries to ${sessionFolder}/discoveries.ndjson
+Report: files_modified (semicolon-separated), tests_passed (true/false), findings (what was changed and why)`,
+  max_concurrency: 1, max_runtime_seconds: 1800,
+  output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
+  output_schema: { id, status: [completed|failed|blocked], findings, files_modified, tests_passed, error }
+})
+```
 
-For each task in order:
+4. Merge results into master `tasks.csv`, delete `wave-{N}.csv`
 
-**5a. Execute refactoring:** Spawn Agent to implement the refactoring — read `read_first` files, apply changes to targets, follow convergence criteria exactly.
+**5b. Reflect per wave:**
 
-**5b. Run test suite** (npm test / pytest / go test as appropriate).
+Append to `reflection-log.md`:
+- Wave number, tasks attempted, pass/fail counts
+- Per-task: title, strategy, outcome, test result, files changed
+- Strategy adjustment notes for failed tasks
 
-**5c. Record in reflection-log.md:** Round number, task title, strategy, result (pass/fail), test outcome, adjustment for next round, files changed.
+**5c. Handle failures (retry loop):**
 
-**5d. Handle test failures:**
-1. Revert the change
-2. Record failure + strategy adjustment in reflection-log.md
-3. Retry with adjusted strategy (max 2 retries per task)
-4. If still failing: mark task "blocked", continue to next
+For each failed task in wave results:
+1. Increment `retry_count` in master CSV
+2. If `retry_count < 2`:
+   - Record failure analysis in `strategy_adjustment` column
+   - Re-add to next wave with adjusted description incorporating failure learnings
+3. If `retry_count >= 2`: mark task `blocked`, skip dependents
 
-**5e. Update state:**
-- `.task/TASK-{NNN}.json` status -> "completed" or "blocked"
-- `.summaries/TASK-{NNN}-summary.md` written
-- `index.json` execution and reflection fields updated
+**5d. Update state per wave:**
+- `.task/TASK-{NNN}.json` status synced from CSV
+- `.summaries/TASK-{NNN}-summary.md` written per completed task
+- `index.json` execution and reflection counters updated
 
 ### Step 6: Final Verification
 
@@ -143,9 +232,12 @@ Display report: scope, tasks completed/blocked, reflection rounds, strategy adju
 - [ ] Scope resolved and scratch directory created
 - [ ] Tech debt analysis completed with categorized findings
 - [ ] Refactoring plan approved by user
-- [ ] Each task executed with test verification
-- [ ] Failed changes reverted, retried with adjusted strategy
-- [ ] Reflection log records every round's strategy and outcome
+- [ ] tasks.csv built from plan with proper wave assignment
+- [ ] Each wave executed via spawn_agents_on_csv with test verification
+- [ ] Failed tasks reverted, retried with strategy adjustment (max 2 retries)
+- [ ] Reflection log records every wave's strategy and outcome
+- [ ] discoveries.ndjson append-only throughout execution
 - [ ] Final test suite passes with zero regressions
+- [ ] results.csv exported with all task outcomes
 - [ ] Completion report with key learnings displayed
 </success_criteria>

package/chains/_intent-map.json

@@ -36,7 +36,7 @@
       "type": "ui_design",
       "regex": "ui.*design|design.*ui|prototype|设计.*原型|UI.*风格",
       "flags": "i",
-      "route": { "graph": "ui-design-driven" }
+      "route": { "graph": "ui-craft-build" }
     },
     {
       "type": "init",

package/chains/singles/ui-design.json

@@ -2,7 +2,7 @@
   "$schema": "../chain-graph.schema.json",
   "id": "singles/ui-design",
   "name": "UI Design",
-  "description": "Generate UI design prototypes with multiple styles via ui-ux-pro-max",
+  "description": "UI design-driven production via maestro-ui-craft build chain",
   "version": "1.0.0",
   "tags": [
     "maestro",
@@ -18,11 +18,11 @@
   "nodes": {
     "ui_design": {
       "type": "command",
-      "cmd": "maestro-ui-design",
+      "cmd": "maestro-ui-craft",
       "next": "done",
       "analyze": false,
-      "args": "{phase}",
-      "description": "Generate UI design prototypes with multiple styles via ui-ux-pro-max"
+      "args": "\"{phase}\" --chain build",
+      "description": "UI design-driven production via maestro-ui-craft build chain"
     },
     "done": {
       "type": "terminal",

package/chains/{ui-design-driven.json → ui-craft-build.json}

@@ -1,8 +1,8 @@
 {
   "$schema": "./chain-graph.schema.json",
-  "id": "ui-design-driven",
-  "name": "UI Design-Driven",
-  "description": "UI Design -> Plan -> Execute -> Verify pipeline",
+  "id": "ui-craft-build",
+  "name": "UI Craft Build",
+  "description": "UI Craft Build -> Plan -> Execute -> Verify pipeline",
   "version": "1.0.0",
   "tags": ["lifecycle", "ui-design"],
   "entry": "ui_design",
@@ -13,9 +13,9 @@
   "nodes": {
     "ui_design": {
       "type": "command",
-      "cmd": "maestro-ui-design",
-      "description": "Generate UI design prototypes with multiple styles, user selects winner",
-      "args": "{phase}",
+      "cmd": "maestro-ui-craft",
+      "description": "UI design-driven production via maestro-ui-craft build chain",
+      "args": "\"{phase}\" --chain build",
       "auto_flag": "-y",
       "next": "plan"
     },
@@ -53,12 +53,12 @@
     "done": {
       "type": "terminal",
       "status": "success",
-      "summary": "UI design-driven pipeline completed successfully"
+      "summary": "UI craft build pipeline completed successfully"
     },
     "done_with_issues": {
       "type": "terminal",
       "status": "paused",
-      "summary": "UI design-driven pipeline completed with verification issues"
+      "summary": "UI craft build pipeline completed with verification issues"
     }
   }
 }