maestro-flow 0.3.14 → 0.3.16

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Execute plan with wave-based parallel execution and atomic commits
-argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>]"
+argument-hint: "[phase] [--auto-commit] [--method agent|codex|gemini|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
 allowed-tools:
   - Read
   - Write
@@ -30,61 +30,7 @@ Invoked after /maestro-plan produces a confirmed plan. When called without args
 <context>
 $ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
 
-**Flags:**
-- `--auto-commit` -- Automatically commit after each task completion
-- `--method agent|cli|auto` -- Override execution method (default: from config.json)
-- `--executor <tool>` -- Default CLI tool: gemini|codex|qwen|opencode|claude
-- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/20260420-plan-auth`)
-
-**Scope routing:**
-
-| Invocation | Behavior |
-|-----------|----------|
-| `execute` (no args) | Find all pending plans for current milestone, execute sequentially |
-| `execute 1` | Find pending plans for phase 1, execute sequentially |
-| `execute --dir scratch/plan-xxx` | Execute the specific plan |
-
-**Resolution logic (no-args / phase):**
-```
-1. Read state.json.artifacts
-2. Filter: milestone=target, type=plan, status=completed, AND no corresponding EXC artifact
-3. If phase specified: further filter by phase=target
-4. Sort by phase dependency order (roadmap phase order), adhoc last
-5. Execute each plan sequentially
-```
-
-**Output**: Task summaries written to plan's scratch dir:
-```
-{YYYYMMDD}-plan-P{N}-{slug}/            # phase-scoped
-{YYYYMMDD}-plan-M{N}-{slug}/           # milestone-wide
-{YYYYMMDD}-plan-{slug}/                # adhoc/standalone
-├── plan.json
-├── .task/
-│   ├── TASK-001.json    # status updated to completed|blocked
-│   └── TASK-002.json
-└── .summaries/          ← execute writes here
-    ├── TASK-001-summary.md
-    └── TASK-002-summary.md
-```
-
-**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`execute`). Mark artifact `harvested: true`.
-
-**Artifact registration**: For each plan executed, register in `state.json.artifacts[]`:
-```jsonc
-{
-  "id": "EXC-{NNN}",
-  "type": "execute",
-  "milestone": "{current_milestone or null}",
-  "phase": "{phase or null}",
-  "scope": "{inherited from plan}",
-  "path": "{same as plan path}",  // inherits plan directory name with scope prefix
-  "status": "completed",
-  "depends_on": "PLN-{NNN}",
-  "harvested": false,
-  "created_at": "...",
-  "completed_at": "..."
-}
-```
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
 </context>
 
 <execution>

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

@@ -32,62 +32,15 @@ Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- milestone name and optional flags.
+$ARGUMENTS -- milestone number and optional flags.
 
-**Modes:**
-
-| Mode | Trigger | Behavior |
-|------|---------|----------|
-| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
-| Sync | `-m 2 --sync` | Sync existing milestone 2 worktree with main branch |
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to `state.json.milestones[]`)
-- `--base <branch>`: Override base branch for worktree creation (default: HEAD)
-- `--sync`: Sync mode — pull main into existing worktree, re-copy shared artifacts
-
-**Milestone resolution:** `state.json.milestones[N-1]` → `{id, name, status}`
-
-**Worktree layout:**
-```
-.worktrees/m{N}-{slug}/
-├── .workflow/
-│   ├── worktree-scope.json     (milestone scope marker)
-│   ├── state.json              (scoped — only this milestone's artifacts)
-│   ├── project.md              (read-only copy)
-│   ├── roadmap.md              (read-only copy)
-│   ├── config.json             (read-only copy)
-│   ├── specs/                  (read-only copy)
-│   └── scratch/                (milestone's existing + new artifacts)
-│       ├── analyze-auth-2026-04-20/
-│       ├── plan-auth-2026-04-20/
-│       └── ...
-└── <source code>               (git worktree checkout)
-```
-
-**Artifact scoping:**
-Fork copies scratch artifacts that belong to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work in the worktree creates scratch artifacts normally; they are registered in the worktree's local `state.json`.
+Modes (`Fork` / `Sync`), flags (`-m`, `--base`, `--sync`), milestone resolution, worktree layout, and artifact scoping are defined in workflow `fork.md`.
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/fork.md' completely.
 
-**Fork flow:**
-1. Validate: project initialized, roadmap exists, not inside worktree, milestone not already forked
-2. Resolve milestone: `state.json.milestones[N-1]`
-3. Create git worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
-4. Copy `.workflow/` into worktree:
-   - Shared files (read-only): `project.md`, `roadmap.md`, `config.json`, `specs/`
-   - Milestone scratch artifacts: filter `state.json.artifacts[]` by `milestone == target`, copy each `scratch/{path}`
-5. Write scope marker: `worktree-scope.json` with milestone number and main path
-6. Write scoped `state.json`: only this milestone's artifacts, `current_milestone` set
-7. Update main: `worktrees.json` registry, mark milestone as `"forked"` in `state.json.milestones[]`
-
-**Sync flow:**
-1. Find worktree from `worktrees.json`
-2. `cd worktree && git merge main`
-3. Re-copy shared files: `project.md`, `roadmap.md`, `config.json`, `specs/`
-4. Report conflicts if any
+Fork and sync algorithm steps are defined in workflow `fork.md`.
 
 **Next-step routing on completion:**
 

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

@@ -23,33 +23,9 @@ Includes registry health check, pre-merge rebase (pull main into worktree to min
 </required_reading>
 
 <context>
-$ARGUMENTS -- milestone name and optional flags.
+$ARGUMENTS -- milestone number and optional flags.
 
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
-- `--force`: Merge even if milestone has incomplete artifacts
-- `--dry-run`: Show what would be merged without executing
-- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
-- `--continue`: Resume a merge that was paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check (remove stale worktree entries)
-2. Validate milestone artifact completeness (all EXC artifacts completed)
-3. Pre-merge rebase (`git merge main` in worktree)
-4. Phase 1: Git merge (source code only)
-5. Phase 2: Scratch artifact sync (only after git merge succeeds)
-6. Atomic artifact registry reconciliation
-7. Cleanup (worktree remove + branch delete)
-
-**Phase 2 — Artifact sync detail:**
-- Copy worktree `scratch/*` dirs back to main `.workflow/scratch/`
-- Merge worktree `state.json.artifacts[]` entries into main `state.json.artifacts[]`
-  - Dedup by artifact id; worktree version wins for same id
-- Update milestone status in main `state.json.milestones[]` (remove "forked" flag)
-- Mark `harvested` status from worktree artifacts
-
-**Conflict handling:**
-If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
+Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
 </context>
 
 <execution>

package/.claude/commands/maestro-milestone-audit.md

@@ -41,11 +41,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 <execution>
 Follow '~/.maestro/workflows/milestone-audit.md' completely.
 
-**Audit checklist (from architecture):**
-1. Phase coverage: each phase in roadmap has analyze → plan → execute chain
-2. Ad-hoc completeness: all adhoc artifacts completed or skipped
-3. Execution completeness: all tasks in executed plans completed
-4. Cross-artifact integration: interface compatibility, data contracts, config consistency
+Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
 
 **Next-step routing on completion:**
 - Verdict PASS → `/maestro-milestone-complete {milestone}`

package/.claude/commands/maestro-milestone-complete.md

@@ -34,13 +34,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 <execution>
 Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
-**Archive flow:**
-1. Validate audit passed + all artifacts completed
-2. Move scratch dirs to `milestones/{M}/artifacts/`
-3. Move artifact entries to `milestone_history[M].archived_artifacts`
-4. Extract learnings from summaries → `specs/learnings.md`
-5. Update state.json: advance to next milestone, clear artifacts[]
-6. Clean scratch dirs
+Archive flow steps (validation, directory archival, artifact history, learning extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
 
 ### Knowledge Promotion Inquiry