maestro-flow 0.3.15 → 0.3.17

package/.claude/commands/maestro-plan.md

@@ -36,66 +36,15 @@ All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
 
-**Flags:**
-- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
-- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
-- `--auto` -- Skip interactive clarification (P2), use defaults
-- `--gaps` -- Gap closure mode: load verification/issue gaps, skip exploration, plan only gap fixes
-- `--dir <path>` -- Use arbitrary scratch directory as context source (e.g., from analyze session)
-- `--revise [instructions]` -- Revise existing plan. Auto-discovers latest plan for current phase from state.json, or use with `--dir` to target specific plan. If instructions provided, apply directly (e.g. `--revise "add TASK-005 for error handling"`). If omitted, ask user via AskUserQuestion. Skips P1-P3 (exploration/clarification/planning), loads existing plan.json + tasks, applies targeted modifications, re-runs P4 (plan-checker).
-- `--check <plan-dir>` -- Standalone plan verification. Run plan-checker (P4 only) against existing plan without modification. Also checks roadmap consistency and collision detection. Read-only.
+Scope routing, base flags (`--collab`, `--spec`, `--auto`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
 
-**Scope routing:**
-
-| Invocation | Precondition | Scope | Behavior |
-|-----------|-------------|-------|----------|
-| `plan` (no args) | init + roadmap | milestone | Plan all phases in current milestone |
-| `plan 1` | init + roadmap | phase | Plan phase 1 only |
-| `plan --dir scratch/analyze-xxx` | none | inherited | Plan against specified analyze session |
-| `plan --revise "instructions"` | existing plan | revise | Modify existing plan with instructions |
-| `plan --revise` | existing plan | revise | Modify existing plan, ask user for instructions |
-| `plan --check scratch/plan-xxx` | existing plan | check | Verify existing plan (read-only) |
+**Command-level flags** (extensions beyond workflow base):
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
 
 **Upstream context:**
 - Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
 - Reads `conclusions.json` if available (implementation_scope seeds task generation)
-
-**Output directory** (relative to `.workflow/`):
-
-| Scope | Directory format | Example |
-|-------|-----------------|---------|
-| Phase | `scratch/{YYYYMMDD}-plan-P{N}-{slug}/` | `20260420-plan-P1-auth` |
-| Milestone | `scratch/{YYYYMMDD}-plan-M{N}-{slug}/` | `20260420-plan-M1-mvp` |
-| Adhoc/Standalone | `scratch/{YYYYMMDD}-plan-{slug}/` | `20260420-plan-caching` |
-
-**Output structure:**
-```
-{YYYYMMDD}-plan-P{N}-{slug}/
-├── plan.json            # summary, task_ids[], waves[] with phase labels
-└── .task/
-    ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
-    ├── TASK-002.json
-    └── ...
-```
-
-**Collision detection**: After plan generation, before user confirmation, check for file overlaps with existing plans in same milestone. Non-blocking warning only.
-
-**Artifact registration**: On completion, register in `state.json.artifacts[]`:
-```jsonc
-{
-  "id": "PLN-{NNN}",
-  "type": "plan",
-  "milestone": "{current_milestone or null}",
-  "phase": "{phase_number or null}",
-  "scope": "{milestone|phase|adhoc|standalone}",
-  "path": "scratch/{YYYYMMDD}-plan-P{N}-{slug}",  // P{N} for phase, M{N} for milestone, omit for adhoc/standalone
-  "status": "completed",
-  "depends_on": "{ANL-NNN or null}",
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
 </context>
 
 <execution>
@@ -158,79 +107,9 @@ Next steps:
   /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-### Mode: Revise (`--revise [instructions]`)
-
-Incrementally modify an existing plan without rebuilding from scratch.
-
-**Plan discovery:**
-- With `--dir`: use specified plan directory
-- Without `--dir`: auto-discover latest completed plan for current phase from `state.json.artifacts[]` (type=plan, status=completed, matching phase)
-
-**Execution flow:**
-
-1. **Load existing plan**
-   - Read `plan.json` + all `.task/TASK-*.json` from discovered directory
-   - Show current plan summary: task count, waves, status per task
-
-2. **Obtain revision instructions**
-   - If `--revise "instructions"` provided → parse as change directive
-   - If `--revise` without instructions → AskUserQuestion for what to change:
-     - Add/remove tasks
-     - Modify task scope, action, implementation
-     - Reorder waves or adjust dependencies
-     - Update convergence criteria
-   - Parse instructions into concrete changes
-
-3. **Apply targeted changes**
-   - Modify affected TASK files in-place
-   - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
-   - Update plan.json summary (task count, wave structure)
-   - Preserve unmodified tasks completely
-
-4. **Re-run plan-checker (P4)**
-   - Validate modified plan with same checker as create mode
-   - Re-run collision detection against same-milestone plans
-   - Present check results for confirmation
-
-5. **Update artifact**
-   - Overwrite plan files in existing scratch directory
-   - Update artifact timestamp in state.json (no new artifact created)
-
-### Mode: Check (`--check <plan-dir>`)
-
-Read-only plan verification without modification.
-
-**Execution flow:**
-
-1. **Load plan**
-   - Read `plan.json` + `.task/TASK-*.json` from specified directory
-   - Read `.workflow/roadmap.md` for consistency comparison
-
-2. **Run checks**
-   - Plan-checker (P4 pipeline stage) — task quality, convergence criteria
-   - Roadmap consistency — plan tasks align with phase scope and requirements
-   - Collision detection — file overlaps with other plans in same milestone
-   - Dependency integrity — no broken cross-task dependencies
-
-3. **Produce check report**
-   ```
-   === PLAN CHECK ===
-   Plan: {plan_dir}/plan.json
-   Tasks: {total} ({completed} done, {pending} pending)
-
-   Checker: {PASS|WARN|FAIL} ({issues} issues)
-   Roadmap: {aligned|drift detected}
-   Collision: {clear|{N} overlaps}
-
-   Issues:
-     1. [{severity}] {description}
-
-   Suggested actions:
-     /maestro-plan --revise "fix instructions"  -- Apply fixes
-     /maestro-execute --dir {plan_dir}          -- Execute as-is
-   ```
+### Mode: Revise / Check
 
-**No file modifications.** Pure verification + report.
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-roadmap.md

@@ -59,15 +59,7 @@ Alternative heavy path (skip maestro-roadmap):
 maestro-init → maestro-spec-generate → spec package + roadmap.md
 ```
 
-**Dual modes:**
-| Mode | Strategy | Best For |
-|------|----------|----------|
-| Progressive | MVP → Usable → Refined (as **Milestones**, each with 1-2 phases) | High uncertainty, need validation |
-| Direct | Topological task sequence (1-2 phases, wave DAG handles ordering) | Clear requirements, confirmed tech |
-
-Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Direct, else → ask user.
-
-**Minimum-phase principle:** Default 1 phase per milestone. Only split into 2 phases when hard dependency exists (runtime + not parallelizable + full barrier). Max 2 phases, exceptional 3 with justification.
+Dual modes (Progressive vs Direct), auto-selection criteria, and minimum-phase principle are defined in workflow roadmap.md (Steps 2-3).
 </context>
 
 <execution>
@@ -84,101 +76,11 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 
 ### Mode: Revise (`--revise [instructions]`)
 
-Revise an existing roadmap while preserving completed phase progress.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-- `.workflow/state.json` exists (for progress tracking)
-
-**Execution flow:**
-
-1. **Load current state**
-   - Read `.workflow/roadmap.md` — parse milestones, phases, dependencies, progress markers
-   - Read `.workflow/state.json` — get artifact registry, current milestone
-   - Identify completed vs in-progress vs pending phases
-
-2. **Obtain revision instructions**
-   - If `--revise "instructions text"` provided → use directly as change directive
-   - If `--revise` without instructions → use AskUserQuestion to ask user what to change
-     - Show current roadmap summary with phase statuses
-     - Present options: add/remove/reorder phases, modify scope/criteria/deps, move between milestones
-     - Capture change instructions from response
-
-3. **Impact analysis**
-   - For each proposed change, assess impact on:
-     - Phase dependency chain (re-validate no circular deps)
-     - Requirement coverage (every Active requirement still mapped)
-     - Completed phases (warn if change invalidates completed work)
-     - Existing plan artifacts (warn if plan exists for affected phase)
-   - Present impact summary for confirmation
-
-4. **Apply revisions**
-   - Update `.workflow/roadmap.md` preserving:
-     - Completed phase progress markers (✓, completion dates)
-     - Phase numbering for completed phases (renumber only pending phases)
-     - Cross-references from state.json artifacts
-   - Update `state.json` if milestone structure changed
-   - Add revision log entry to roadmap.md metadata section
-
-5. **Post-revision validation**
-   - Re-check dependency integrity (no circular deps)
-   - Re-check requirement coverage (every Active req mapped)
-   - Verify completed phases unaffected
-
-**Next-step routing on completion:**
-- Phases changed, need re-analysis → `/maestro-analyze {phase}`
-- Phases changed, ready to plan → `/maestro-plan {phase}`
-- Only pending phases adjusted → `/maestro-plan` (continue from where left off)
+Follow workflow roadmap.md "Mode: Revise" section for full algorithm (load state, obtain instructions, impact analysis, apply revisions, post-validation).
 
 ### Mode: Review (`--review`)
 
-Read-only health assessment of the current roadmap.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-
-**Execution flow:**
-
-1. **Load roadmap + execution history**
-   - Read `.workflow/roadmap.md` — full structure
-   - Read `.workflow/state.json` — artifact registry, milestone progress
-   - Cross-reference: for each phase, check ANL/PLN/EXC/VRF artifact status
-
-2. **Assessment dimensions**
-   - **Progress tracking**: Actual vs planned per phase, milestone velocity
-   - **Drift detection**: Completed phases deviating from original scope (via verify/audit findings)
-   - **Relevance check**: Pending phases still aligned with current project goals (from project.md)
-   - **Dependency health**: Pending phase dependencies still valid given completed work
-   - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
-
-3. **Produce review report**
-   - Write to `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
-   - Format:
-     ```
-     === ROADMAP REVIEW ===
-     Date: {date}
-     Milestone: {current}
-
-     Progress: {completed}/{total} phases ({percentage}%)
-     Drift: {none|minor|significant}
-     Risk: {low|medium|high}
-
-     Phase Assessment:
-       [✓] Phase 1: {name} — completed, on-scope
-       [~] Phase 2: {name} — in-progress, {status notes}
-       [ ] Phase 3: {name} — pending, {risk/notes}
-
-     Recommendations:
-       1. {actionable recommendation}
-       2. ...
-
-     Suggested actions:
-       /maestro-roadmap --revise   — Apply recommended changes
-       /maestro-plan {phase}       — Plan next phase
-       /manage-status              — View full dashboard
-     ```
-
-**No state modifications.** Pure assessment + recommendations.
+Follow workflow roadmap.md "Mode: Review" section for full algorithm (load state, assess dimensions, produce report).
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-spec-generate.md

@@ -29,32 +29,8 @@ This is the heavy-path entry for structured decomposition: idea → spec-generat
 <context>
 $ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm session reference.
 
-**Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint (reads spec-config.json)
-- `--count N`: Limit number of exploration dimensions (default 5)
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+Flags, input types, output location, and pipeline position defined in workflow spec-generate.md.
 
-**Input types:**
-- Direct text: `"Build a real-time collaboration platform"`
-- File reference: `@requirements.md` or `@design-brief.txt`
-- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/`)
-
-**Output location:** `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
-
-**Relationship to pipeline:**
-```
-maestro-brainstorm (optional upstream)
-        ↓ guidance-specification.md
-maestro-init (REQUIRED first step — project setup)
-        ↓ project.md, state.json, config.json
-maestro-spec-generate (this command — heavy path)
-        ↓ spec package + roadmap.md → .workflow/roadmap.md
-maestro-plan → maestro-execute → maestro-verify
-
-Alternative light path (skip spec-generate):
-maestro-init → maestro-roadmap → roadmap.md directly
-```
 **Note:** `maestro-init` MUST run before this command. It creates the `.workflow/` directory and project context that spec-generate builds upon.
 </context>
 

package/.claude/commands/maestro-ui-design.md

@@ -33,86 +33,27 @@ Position in pipeline: analyze -> **ui-design** -> plan -> execute -> verify
 <context>
 $ARGUMENTS — phase number for phase mode, topic text for scratch mode, with optional flags.
 
-**Flags:**
-- `--styles N` — Number of style variants to generate (default: 3, range: 2-5)
-- `--layouts N` — Number of layout variants per target (default: 2, range: 1-3)
-- `--stack <stack>` — Tech stack for implementation guidelines (default: html-tailwind). Options: html-tailwind, react, nextjs, vue, svelte, shadcn
-- `--targets <pages>` — Comma-separated page/component targets to prototype (default: inferred from phase goal or "home")
-- `--refine` — Refinement mode: fine-tune an existing design-ref instead of generating from scratch (ui-design.md only)
-- `--persist` — Save design system with hierarchical page overrides (MASTER.md + pages/)
-- `--full` — Force full 4-layer pipeline (ui-design.md) even when ui-ux-pro-max is available
-- `-y` / `--yes` — Auto mode: skip interactive selection, pick top-scored variant
-
-**Workflow routing:**
-- Default: auto-detect ui-ux-pro-max skill → if found, use `ui-style.md` (lightweight); if not, use `ui-design.md` (self-contained)
-- `--full`: always use `ui-design.md` regardless of skill availability
-- Flags `--layouts N` and `--refine` are only effective with `ui-design.md` (full pipeline)
+Flags, workflow routing, scope modes, and output artifacts defined in the routed workflow (ui-style.md or ui-design.md).
 
 **Phase mode** (number): resolves phase directory, reads context.md/brainstorm for requirements.
 **Scratch mode** (text): creates `.workflow/scratch/{YYYYMMDD}-ui-design-{slug}/` for standalone exploration.
-
-**Output artifacts (in phase or scratch directory):**
-| Artifact | Description |
-|----------|-------------|
-| `design-ref/` | Root directory for all design outputs |
-| `design-ref/MASTER.md` | Selected design system (colors, typography, spacing, effects, anti-patterns) |
-| `design-ref/design-tokens.json` | Production-ready tokens (OKLCH colors, typography.combinations, component_styles, opacity) |
-| `design-ref/animation-tokens.json` | Animation system (duration, easing, transitions, keyframes, interactions) |
-| `design-ref/layout-templates/` | Structural layout templates per target (dom_structure + css_layout_rules) |
-| `design-ref/prototypes/` | Assembled HTML/CSS prototypes (styles x layouts x targets) |
-| `design-ref/prototypes/compare.html` | Interactive matrix comparison page |
-| `design-ref/.intermediates/` | Analysis options, user selections, exploration data |
-| `design-ref/selection.json` | User selection metadata + rationale |
-| `design-ref/pages/{page}.md` | Page-specific design overrides (if --persist) |
 </context>
 
 <execution>
-## Workflow Routing (skill detection)
-
-Detect ui-ux-pro-max skill availability:
-
-```bash
-SKILL_PATH=""
-for path in \
-  "skills/ui-ux-pro-max/scripts/search.py" \
-  "$HOME/.claude/plugins/cache/ui-ux-pro-max-skill/ui-ux-pro-max/*/scripts/search.py"; do
-  expanded=$(ls $path 2>/dev/null | tail -1)
-  if [ -n "$expanded" ]; then SKILL_PATH="$expanded"; break; fi
-done
-[ -z "$SKILL_PATH" ] && SKILL_PATH=$(find "$HOME/.claude/plugins" -path "*/ui-ux-pro-max/*/scripts/search.py" -print -quit 2>/dev/null)
-```
-
-**Route:**
+## Workflow Routing
+
+Detect ui-ux-pro-max skill availability and route to the appropriate workflow:
+
 - **`--full` flag present** → Follow '~/.maestro/workflows/ui-design.md' completely (forced full pipeline)
-- **SKILL_PATH found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight, delegates design to ui-ux-pro-max)
-- **SKILL_PATH empty** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained 4-layer pipeline fallback)
-
-Pass `SKILL_PATH` to the workflow when using ui-style.md.
-
-**Report format on completion:**
-
-```
-=== UI DESIGN READY ===
-Phase:   {phase_name}
-Styles:  {style_count} variants, #{selected} selected
-Layouts: {layout_count} per target
-Targets: {target_list}
-Stack:   {stack}
-Matrix:  {S x L x T} = {total} prototypes
-
-Design System:
-  MASTER.md:        {scratch_dir}/design-ref/MASTER.md
-  Tokens:           {scratch_dir}/design-ref/design-tokens.json
-  Animation:        {scratch_dir}/design-ref/animation-tokens.json
-  Layout Templates: {scratch_dir}/design-ref/layout-templates/
-  Prototypes:       {scratch_dir}/design-ref/prototypes/
-  Compare:          {scratch_dir}/design-ref/prototypes/compare.html
-
-Next steps:
-  /maestro-plan {phase}              -- Plan with design reference
-  /maestro-ui-design {phase} --refine -- Refine selected design
-  /maestro-analyze {phase}           -- Analyze before planning
-```
+- **ui-ux-pro-max found** → Follow '~/.maestro/workflows/ui-style.md' completely (lightweight delegation)
+- **ui-ux-pro-max not found** → Follow '~/.maestro/workflows/ui-design.md' completely (self-contained fallback)
+
+Skill detection logic, report format, and complete pipeline steps defined in the routed workflow file.
+
+**Next-step routing on completion:**
+- Plan with design reference → /maestro-plan {phase}
+- Refine selected design → /maestro-ui-design {phase} --refine
+- Analyze before planning → /maestro-analyze {phase}
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-verify.md

@@ -37,38 +37,7 @@ Registers VRF artifact in state.json on completion.
 <context>
 $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 
-**Flags:**
-- `--skip-tests` -- Skip Nyquist test coverage validation, only run Goal-Backward
-- `--skip-antipattern` -- Skip anti-pattern scan
-- `--dir <path>` -- Verify specific plan directory
-
-**Scope routing:**
-
-| Invocation | Behavior |
-|-----------|----------|
-| `verify` (no args) | Milestone-level: verify all executed plans, aggregate results |
-| `verify 1` | Phase-level: verify all executed plans for phase 1 |
-| `verify --dir scratch/plan-xxx` | Single plan: verify specific plan directory |
-
-**Single plan output**: `verification.json` appended to plan's scratch dir
-**Milestone output**: `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
-
-**Artifact registration**: On completion, register VRF artifact:
-```jsonc
-{
-  "id": "VRF-{NNN}",
-  "type": "verify",
-  "milestone": "{current_milestone or null}",
-  "phase": null,
-  "scope": "milestone",
-  "path": "scratch/{YYYYMMDD}-verify-M{N}-{slug}",  // M{N} = milestone number
-  "status": "completed",
-  "depends_on": ["EXC-001", "EXC-002", ...],
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
+Flags (`--skip-tests`, `--skip-antipattern`, `--dir`), scope routing, output paths, and VRF artifact registration schema are defined in workflow `verify.md`.
 </context>
 
 <execution>

package/.claude/commands/maestro.md

@@ -1,10 +1,11 @@
 ---
 name: maestro
-description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via Skill()
-argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>]"
+description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via Skill() or CLI delegate
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--exec auto|cli|skill] [--tool <name>]"
 allowed-tools:
   - Read
   - Write
+  - Edit
   - Bash
   - Glob
   - Grep
@@ -17,6 +18,10 @@ Two routing modes:
 1. **Intent-based**: User describes a goal → classify task type → select/compose command chain → confirm → execute
 2. **State-based**: Read .workflow/state.json → determine next logical step → suggest/execute (triggered by `continue`/`next`)
 
+Per-step execution engine (default: auto):
+- **Skill()**: Observable steps — output visible in conversation, synchronous, user can intervene
+- **CLI delegate**: Heavy execution steps — context isolation, template-driven prompts, gemini quality analysis
+
 Produces session directory at `.workflow/.maestro/{session_id}/` with status.json tracking chain progress.
 Executes commands sequentially via Skill() with artifact propagation between steps.
 </purpose>
@@ -37,6 +42,8 @@ $ARGUMENTS — user intent text, or special keywords.
 - `-c` / `--continue` — Resume previous coordinator session from `.workflow/.maestro/*/status.json`
 - `--dry-run` — Show planned chain without executing
 - `--chain <name>` — Force a specific chain (bypass intent detection). Valid: full-lifecycle, spec-driven, brainstorm-driven, execute-verify, quality-loop, milestone-close, quick, review
+- `--exec <mode>` — Execution engine: `auto` (default), `cli`, `skill`. Auto selects per step based on command complexity.
+- `--tool <name>` — CLI tool for delegate execution (default: claude). Only used when engine=cli.
 
 **State files read:**
 - `.workflow/state.json` — project state machine + artifact registry
@@ -76,32 +83,7 @@ In auto mode, maestro also:
 - Skips chain confirmation (Step 5d)
 - Auto-skips on step errors (retry once, then skip and continue)
 
-**Context cleanup hint:**
-
-After completing step 3+, proactively suggest `-c` resume:
-- Interactive mode: display `⚡ 已执行 {N} 步，上下文较重。可随时 /maestro -c 在新上下文中恢复。`
-- `-y` mode and step 4+: log one-line warning to status.json, continue.
-
-**Context window reminder:**
-
-Before each Step 7 Skill() call, if context usage is near the window limit:
-- `-y` active → print one-line warning and continue.
-- Otherwise → stop before the next step and ask the user (Continue / Pause to resume with `-c` / Abort). Wait for explicit choice.
-
-**Report format on completion:**
-
-```
-=== MAESTRO SESSION COMPLETE ===
-Session: {session_id}
-Chain:   {chain_name} ({steps_completed}/{steps_total} steps)
-Milestone: {current_milestone} (if applicable)
-Mode:    {auto | interactive}
-
-Steps:
-  [{status_icon}] {N}. {command_name} — {duration}
-
-Next: {suggested_next_action}
-```
+Context cleanup hints, context window reminders, and completion report format are defined in workflow maestro.md (Steps 7a-1, 7f).
 </execution>
 
 <error_codes>
@@ -121,10 +103,11 @@ Next: {suggested_next_action}
 - [ ] Intent classified with task_type, complexity, clarity_score
 - [ ] Project state read and incorporated into routing
 - [ ] Command chain selected and confirmed (or auto-confirmed with -y)
+- [ ] Per-step engine selected (auto routes heavy steps to CLI, observable steps to Skill)
 - [ ] Auto flags correctly propagated to supporting commands only
 - [ ] Session directory created at .workflow/.maestro/{session_id}/
-- [ ] status.json tracks per-step progress
-- [ ] All chain steps executed via Skill() with proper argument propagation
+- [ ] status.json tracks per-step progress and execution engine
+- [ ] All chain steps executed via Skill() or CLI delegate with proper argument propagation
 - [ ] Phase numbers auto-detected and passed to downstream commands
 - [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
 - [ ] Session summary displayed on completion

package/.claude/commands/manage-harvest.md

@@ -37,55 +37,18 @@ Arguments: $ARGUMENTS
 - `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
 - `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
 
-**Flags:**
-- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
-- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
-- `--recent N` — Only artifacts updated within last N days (default: 30)
-- `--dry-run` — Preview extraction and routing without writing
-- `-y` / `--yes` — Skip confirmation prompts
-- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
-
-**Source registry (scan paths):**
-| Source Type | Scan Path | Key Files |
-|-------------|-----------|-----------|
-| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
-| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
-| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
-| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
-| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
-| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
-| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
-
-**Storage written:**
-- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
-- `.workflow/harvest/harvest-report-{date}.md` — per-run report
-- Wiki entries via `maestro wiki create`
-- Spec entries via `Skill({ skill: "spec-add" })`
-- Issue entries appended to `.workflow/issues/issues.jsonl`
-
-**Storage read (never modified):**
-- All artifact source files (read-only until routing stage)
-- `.workflow/harvest/harvest-log.jsonl` (dedup check)
+Flags, source registry (scan paths), and storage locations defined in workflow harvest.md.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
-2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
-4. **Reuse existing routing infrastructure**:
-   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id> --created-by manage-harvest --source-ref HRV-<fragment_id> --category <fragment_category>`
-   - Spec: `Skill({ skill: "spec-add", args: "<category> <content>" })`
-   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
-5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
-6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
-7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
+Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 
-**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
+**Key invariants:**
+1. **Read-only until Stage 6** — extraction and classification happen in-memory.
+2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
+3. **Never modify source artifacts** — harvest is purely extractive.
 
-**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
+Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 
 **Next-step routing on completion:**
 - Review wiki entries → `maestro wiki list --type note`