Sequential interactive flow (no spawn_agents_on_csv — this is design, not execution):
Parse NL → [confirm] → Resolve to nodes → [confirm] → Inject checkpoints → Confirm pipeline → Persist
Three entry modes:
- New design: Phase 1-5
- Resume design: Load draft from
.workflow/templates/design-drafts/ - Edit template: Load existing, modify, re-save
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 | --resume flag explicitly set |
Phase 0: Resume |
| Edit | --edit <path> |
Phase 0: Load + Edit |
| New | Description text provided (non-empty args without flags) | Phase 1: Parse |
| Empty | No args, no flags | Phase 0: check for existing WFD drafts → if found, ask user via request_user_input whether to resume or start new; if none, Phase 1 |
IMPORTANT: An existing WFD draft does NOT auto-resume when new description text is provided. New intent always starts Phase 1 fresh. Auto-resume only triggers with explicit --resume or empty args with user confirmation.
Node catalog: Read ~/.maestro/templates/workflows/specs/node-catalog.md at Phase 2 (deferred).
Template schema: Read ~/.maestro/templates/workflows/specs/template-schema.md at Phase 5 (deferred).
Pre-load specs
- Architecture specs: Run
maestro load --type spec --category archto load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns. - Coding specs: Run
maestro load --type spec --category codingto load coding conventions. Informs executor argument defaults and context injection. - Optional — proceed without if unavailable.
Output boundary: ALL file writes MUST target ~/.maestro/templates/workflows/ (final templates) and .workflow/templates/design-drafts/ (in-progress drafts). NEVER modify source code, .claude/commands/, or .codex/skills/.
Phase 0: Resume / Edit (conditional)
Resume (--resume):
- Scan
.workflow/templates/design-drafts/WFD-*/for in-progress designs - Multiple → request_user_input for selection
- Load draft → skip to last incomplete phase
Edit (--edit <path>):
- Load template JSON
- Show pipeline visualization (Phase 4 format)
- request_user_input: which nodes to modify/add/remove
- Re-enter at Phase 3
Phase 1: Parse — Semantic Intent Extraction
Step 1.1 — Parse $ARGUMENTS. If empty, request_user_input:
"Describe the workflow you want to automate.
Include: what steps to run, in what order, and what varies each time.
Example: 'analyze the code, then plan, implement, and test the feature'"
Step 1.2 — Extract sequential actions as candidate nodes:
| 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).
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 description, task type, complexity, detected steps (numbered with type_hint), and variables. request_user_input: Continue to resolution / Edit steps / Add a step / Cancel
Phase 2: Resolve — Map Steps to Executor Nodes
Read deferred: ~/.maestro/templates/workflows/specs/node-catalog.md
If spec not found, use built-in fallback:
| type_hint | executor type | 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 claude --mode analysis |
refactor |
skill | quality-refactor |
debug |
skill | quality-debug |
spec |
skill | maestro-blueprint |
checkpoint |
checkpoint | — |
Step 2.1 — Load intent.json, map each step to executor.
Step 2.2 — Build args_template with variable placeholders and context injection:
- Planning after analysis →
--context {prev_output_path} - Execution after planning → inherit phase
- Testing after execution → inherit phase
Step 2.3 — Assign parallel_group for parallel steps.
Step 2.4 — Write nodes.json.
Step 2.5 — Interactive confirmation: Display resolved nodes table (ID, type, executor, args) and parallel groups. request_user_input: Continue to checkpoint injection / Change executor / Change node type / Back to intent / Cancel
Phase 3: Enrich — Inject Checkpoints + Build DAG
Step 3.1 — Load nodes.json. Build sequential edges. For parallel groups: fan-out/fan-in.
Step 3.2 — Auto-inject checkpoint nodes:
| 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-roadmap |
| 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.3 — Finalize context_schema, validate DAG (no cycles, no orphans).
Step 3.4 — Write dag.json. → Proceed to Phase 4.
Phase 4: Confirm — Visualize + User Approval
Step 4.1 — Render ASCII pipeline: vertical node chain with | connectors showing each node (ID, type, executor, args) and checkpoint nodes (auto-continue vs pause-for-user). Footer: required variables, checkpoint counts, node counts.
Step 4.2 — request_user_input: Confirm & Save / Edit a node / Add a node / Remove a node / Rename template / Re-run checkpoint injection / Cancel
Step 4.3 — Loop edits until Confirm or Cancel.
Phase 5: Persist — Assemble + Save Template
Read deferred: ~/.maestro/templates/workflows/specs/template-schema.md
Step 5.1 — Load intent.json + dag.json. Assemble template JSON.
Step 5.2 — Determine slug (kebab-case). If exists, append -v2.
Step 5.3 — Write ~/.maestro/templates/workflows/<slug>.json.
Step 5.4 — Update ~/.maestro/templates/workflows/index.json.
Step 5.5 — Output summary: path, template ID, node/checkpoint counts, required variables. Include usage commands: $maestro-player <slug> --context goal="...", $maestro-composer --edit <path>, $maestro-player --list.
Step 5.6 — Clean up design draft directory.
<error_codes>
| Code | Severity | Condition | Recovery |
|---|---|---|---|
| E001 | error | Empty description and no flags | request_user_input for description |
| E002 | error | 0 steps extracted | Ask to rephrase with action verbs |
| E003 | error | Node count exceeds 20 | Suggest splitting into sub-workflows |
| E004 | error | DAG cycle detected | Show cycle, ask to resolve |
| E005 | error | Resume session not found | Show available drafts |
| E006 | error | Edit template not found | Show available templates |
| W001 | warning | Ambiguous executor mapping | Show candidates, let user choose |
| W002 | warning | No checkpoint rules triggered | Warn, offer manual add |
| W003 | warning | Deferred spec not found | Use built-in fallback |
| </error_codes> |
<success_criteria>
- Intent parsed and confirmed by user (Phase 1 gate)
- Nodes resolved and confirmed by user (Phase 2 gate)
- DAG built with auto-injected checkpoints
- Pipeline visualized and confirmed by user (Phase 4 gate)
- Template JSON written to
~/.maestro/templates/workflows/<slug>.json - Template index updated
- Deferred specs loaded only when phase needs them </success_criteria>