maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/maestro-analyze/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: maestro-analyze
+description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
+argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Perform multi-dimensional analysis of a technical proposal, decision, or architecture choice through iterative CLI-assisted exploration and interactive discussion. Produces a discussion timeline (discussion.md) with evolving understanding, multi-perspective findings, Decision Recording Protocol, Intent Coverage tracking, and a final conclusions package with Go/No-Go recommendation.
+
+Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
+
+Use `-q` for quick decision extraction only (skip exploration + scoring).
+
+Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyze). Loads issues from issues.jsonl, performs CLI exploration against issue context/location, synthesizes root cause into issue.analysis, and outputs context.md for downstream `plan --gaps`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/analyze.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone mode, no args for milestone-wide.
+
+**Flags:**
+- `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
+- `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
+- `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
+
+Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).
+
+### Role Knowledge
+`maestro wiki list --category debug` → select relevant → `maestro wiki load`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/analyze.md' completely.
+
+### --gaps Mode (Issue Root Cause Analysis)
+
+When `--gaps` flag is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard analyze pipeline:
+
+```
+Phase 1: Load issues from .workflow/issues/issues.jsonl
+  - If ISS-ID provided: load single issue
+  - If no ISS-ID: filter issues where status = open | registered
+  - Validate: at least 1 issue loaded, else error E_NO_ISSUES
+
+Phase 2: CLI exploration per issue
+  - For each issue: build exploration prompt from issue.title, description, context, related_files
+  - Run maestro delegate --role analyze --mode analysis with codebase context
+  - Gather affected files, call chains, root cause evidence
+
+Phase 3: Root cause synthesis → write issue.analysis
+  - Parse CLI output into analysis record: { root_cause, affected_files, impact_scope, fix_direction, confidence, analyzed_at, tool, depth }
+  - Write analysis record to issue in issues.jsonl
+  - Append history entry: { action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }
+
+Phase 4: Output context.md for downstream plan --gaps
+  - Aggregate all analyzed issues into context.md with root causes and fix directions
+  - Register ANL artifact in state.json
+```
+
+**Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions). In --gaps mode, context.md contains issue root causes for `plan --gaps` consumption.
+
+**Next-step routing on completion:**
+
+Phase/Milestone scope:
+- Go recommendation, UI work needed → `/maestro-impeccable build {target}`
+- Go recommendation, ready to plan → `/maestro-plan` or `/maestro-plan {phase}`
+- No-Go recommendation → revisit requirements or `/maestro-brainstorm {topic}`
+
+Adhoc/Standalone scope:
+- Ready to plan → `/maestro-plan --dir {scratch_dir}`
+- Need more exploration → `/maestro-analyze {topic} -c`
+
+Gaps scope:
+- Issues analyzed → `/maestro-plan --gaps` (plan fix tasks linked to issues)
+- Need more context → `/maestro-analyze --gaps {ISS-ID}` (re-analyze specific issue)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Prompt user for topic text or create roadmap first |
+| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
+| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
+| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
+| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+| E_NO_ISSUES | error | --gaps but no open/registered issues found | Suggest `/manage-issue-discover` or `/manage-issue create` |
+| E_ISSUE_NOT_FOUND | error | --gaps with ISS-ID but issue not found | Suggest `/manage-issue list` to find valid IDs |
+</error_codes>
+
+<success_criteria>
+Full mode:
+- [ ] CLI exploration completed with code anchors and call chains
+- [ ] discussion.md created with full timeline, TOC, Current Understanding
+- [ ] analysis.md written with all 6 dimensions scored with evidence
+- [ ] conclusions.json created with recommendations and decision trail
+- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
+- [ ] Confidence tracking initialized (Step 4.6) and re-scored each round (Step 5.8)
+- [ ] Readiness gate checked before synthesis (Step 5.10)
+- [ ] Pressure pass completed ≥ 1 time before Step 6
+- [ ] Confidence summary with factor decomposition written to analysis.md
+
+Gaps mode:
+- [ ] Issues loaded from issues.jsonl (all open/registered, or single ISS-ID)
+- [ ] CLI exploration executed per issue with codebase context
+- [ ] Analysis record attached to each issue in issues.jsonl
+- [ ] context.md written with aggregated root causes for plan --gaps
+
+Both modes (full + quick):
+- [ ] context.md written with all decisions classified as Locked/Free/Deferred
+- [ ] Gray areas identified through phase-specific analysis
+- [ ] Decision Recording Protocol applied to all decisions
+- [ ] Scope creep redirected to Deferred section
+- [ ] Deferred items auto-created as issues (if any)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
+</success_criteria>

package/.agents/skills/maestro-brainstorm/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: maestro-brainstorm
+description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → invoke_skill({ skill: "maestro-init" })
+- Project initialized, need spec package → invoke_skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → invoke_skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → invoke_skill({ skill: "maestro-analyze", args: "{topic}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
+
+Single role mode:
+- More roles needed → invoke_skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → invoke_skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
+- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+- [ ] Confidence scored per role completion and after cross-role analysis
+- [ ] Readiness gate checked before spec generation
+- [ ] Pressure pass completed on at least 1 feature spec
+- [ ] Confidence summary appended to synthesis-changelog.md
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/.agents/skills/maestro-collab/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: maestro-collab
+description: Use when a question needs cross-verification from multiple CLI tools or diverse analytical perspectives
+argument-hint: "<requirement> [--tools gemini,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+<purpose>
+Fan-out requirement to multiple CLI tools in parallel → cross-verify for consensus/conflicts → synthesize into unified report with downstream artifacts (context.md + conclusions.json).
+</purpose>
+
+<context>
+$ARGUMENTS — requirement text and optional flags.
+
+**Flags**:
+- `--tools <list>`: Comma-separated CLI tools (default: first 3 enabled)
+- `--mode analysis|write`: Delegate mode (default: analysis)
+- `--rule <template>`: Shared rule template for all delegates
+- `-y`: Skip plan confirmation
+
+**Pre-load** (optional): `maestro spec load --category arch` + `maestro wiki list --category arch` → include in delegate prompts.
+
+**Output**: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/`
+- `collab-report.md` — merged findings with consensus/conflict/unique tags
+- `context.md` — Locked/Free/Deferred decisions (plan compatible)
+- `conclusions.json` — structured: session_id, tools[], consensus_level, recommendation, confidence, dimensions[], decisions[]
+- `per-tool/{tool}-output.md` — raw outputs
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE           — 解析参数、提取 flags                      PERSIST: —
+S_DISCOVER        — 发现可用 CLI 工具                          PERSIST: —
+S_CONFIRM         — 展示计划、用户确认（-y 跳过）              PERSIST: —
+S_FANOUT          — 构建 prompt、并行启动 delegate、STOP       PERSIST: —
+S_COLLECT         — 回调到达、收集结果                          PERSIST: per-tool outputs
+S_CROSS_VERIFY    — 分类发现（共识/冲突/独有）                  PERSIST: —
+S_SYNTHESIZE      — 解决冲突、生成 3 个输出文件                 PERSIST: outputs
+S_REGISTER        — 注册 CLB artifact                          PERSIST: state.json
+S_REPORT          — 显示摘要 + next-step routing               PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_DISCOVER    WHEN: requirement non-empty              DO: extract requirement, tools, mode, rule, autoYes
+  → S_PARSE       WHEN: requirement empty                  DO: ask_user for requirement
+
+S_DISCOVER:
+  → S_CONFIRM     WHEN: eligible tools >= 2                DO: A_DISCOVER_TOOLS
+  → ERROR(E002)   WHEN: eligible tools < 2
+
+S_CONFIRM:
+  → S_FANOUT      WHEN: autoYes                            DO: A_SETUP_SESSION
+  → S_FANOUT      WHEN: user confirms "执行"               DO: A_SETUP_SESSION
+  → S_DISCOVER    WHEN: user selects "修改工具选择"         DO: re-select tools, validate >= 2
+  → END           WHEN: user cancels
+
+S_FANOUT:
+  → S_COLLECT     DO: A_PARALLEL_DELEGATE then STOP — wait for callbacks
+
+S_COLLECT:
+  → S_CROSS_VERIFY  WHEN: all callbacks arrived            DO: A_COLLECT_OUTPUTS
+  → ERROR(E004)     WHEN: all delegates failed
+  GUARD: 1+ succeeded → continue with partial results (W001)
+
+S_CROSS_VERIFY:
+  → S_SYNTHESIZE    DO: A_CLASSIFY_FINDINGS
+
+S_SYNTHESIZE:
+  → S_REGISTER      DO: A_GENERATE_OUTPUTS
+
+S_REGISTER:
+  → S_REPORT        DO: append CLB artifact to state.json (type: collab, scope: adhoc)
+
+S_REPORT:
+  → END             DO: display summary (requirement, tools, consensus_level, per-tool status, artifact id, output dir)
+
+</transitions>
+
+<actions>
+
+### A_DISCOVER_TOOLS
+
+```
+shell("maestro tools list --json 2>/dev/null || cat ~/.maestro/cli-tools.json")
+```
+Filter: enabled == true. If --mode write: exclude type == "api-endpoint".
+Auto-select (no --tools): first 3 eligible in config order.
+
+### A_SETUP_SESSION
+
+Create: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/` + `per-tool/`.
+
+### A_PARALLEL_DELEGATE
+
+1. Build shared prompt:
+   ```
+   PURPOSE: {requirement}; success = actionable findings with evidence
+   TASK: {auto-decomposed into 3-5 specific verbs}
+   MODE: {delegateMode}
+   CONTEXT: @**/*
+   EXPECTED: Structured findings with file:line refs, confidence (0-100), prioritized recommendations
+   CONSTRAINTS: {from requirement}
+   ```
+2. Launch ALL delegates in ONE message — multiple `shell(run_in_background: true)`:
+   ```
+   maestro delegate "${prompt}" --to {tool} --mode ${mode} [--rule ${rule}]
+   ```
+3. **STOP immediately after launch. Wait for background callbacks.**
+
+### A_COLLECT_OUTPUTS
+
+On each callback: `maestro delegate output <id>` → write `per-tool/{tool}-output.md`.
+
+### A_CLASSIFY_FINDINGS
+
+Read all per-tool outputs. For each finding:
+
+| Condition | Tag |
+|-----------|-----|
+| 2+ tools agree | CONSENSUS |
+| Tools disagree | CONFLICT |
+| 1 tool only | UNIQUE |
+
+consensus_level = consensus_count / total_findings * 100.
+If consensus_level < 40%: W003.
+
+### A_GENERATE_OUTPUTS
+
+Resolve conflicts via evidence-weighted voting:
+- Higher confidence wins; more specific evidence (file:line) wins over general; tied → SUGGESTED
+
+Write 3 files:
+1. **collab-report.md**: Summary, Consensus Findings, Resolved Conflicts, Unresolved Items, Unique Insights, Recommendations, Per-Tool Confidence table
+2. **context.md**: Locked (CONSENSUS items), Free (UNIQUE with strong evidence), Deferred (UNRESOLVED conflicts). Standard Locked/Free/Deferred format for plan compatibility.
+3. **conclusions.json**: session_id, subject, mode, tools[], consensus_level, recommendation (Go/No-Go/Conditional), confidence, dimensions[{name, score, findings}], decisions[{title, classification, source_tools, rationale}]
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Fewer than 2 eligible tools | Check cli-tools.json, enable more tools |
+| E004 | All delegates failed | Abort with per-tool error details |
+| W001 | One tool failed | Continue with remaining (partial degradation) |
+| W003 | consensus_level < 40% | Flag in summary, recommend manual review |
+</error_codes>
+
+<success_criteria>
+- [ ] All delegates launched in parallel via shell(run_in_background: true), STOP after launch
+- [ ] Cross-verification: consensus/conflict/unique classification with consensus_level
+- [ ] 3 output files produced (collab-report.md, context.md, conclusions.json)
+- [ ] CLB artifact registered in state.json
+- [ ] Partial degradation: continued if 1+ tools succeeded
+</success_criteria>
+
+<next_step_routing>
+- Deep feasibility → `/maestro-analyze "{topic}"`
+- Plan from conclusions → `/maestro-plan --dir {dir}`
+- Expand → `/maestro-brainstorm "{topic}"`
+</next_step_routing>

package/.agents/skills/maestro-composer/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: maestro-composer
+description: Compose reusable workflow templates from natural language
+argument-hint: "<workflow-description> [--resume] [--edit <template-path>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+  - invoke_skill
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Interactive workflow template composer. Parse natural language → resolve executors → inject checkpoints → build DAG → persist to `~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Three entry modes: **New design** (default), **Resume** (`--resume`), **Edit** (`--edit <path>`).
+</purpose>
+
+<deferred_reading>
+- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
+- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — natural language description, or flags.
+
+**Flags**: `--resume` (resume in-progress design), `--edit <path>` (edit existing template)
+
+**Constants**:
+- Template dir: `~/.maestro/templates/workflows/`
+- Template index: `~/.maestro/templates/workflows/index.json`
+- Design drafts: `.workflow/templates/design-drafts/`
+- Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
+- Max nodes: 20
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
+</context>
+
+<state_machine>
+
+<states>
+S_ROUTE        — 入口路由（new/resume/edit）               PERSIST: —
+S_PARSE        — 语义意图提取                               PERSIST: intent.json
+S_CONFIRM_1    — 确认解析结果                               PERSIST: —
+S_RESOLVE      — 映射步骤到 executor 节点                   PERSIST: nodes.json
+S_CONFIRM_2    — 确认节点映射                               PERSIST: —
+S_ENRICH       — 注入 checkpoint + 构建 DAG                 PERSIST: dag.json
+S_CONFIRM_3    — 可视化 pipeline + 用户审批                  PERSIST: —
+S_PERSIST      — 组装 JSON + 保存模板                       PERSIST: template file + index
+</states>
+
+<transitions>
+
+S_ROUTE:
+  → S_PARSE       WHEN: no flags (new design)
+  → S_RESOLVE     WHEN: --resume                           DO: load draft, skip to last incomplete phase
+  → S_CONFIRM_3   WHEN: --edit <path>                      DO: load template, show pipeline, ask edits
+
+S_PARSE:
+  → S_CONFIRM_1   DO: A_PARSE_INTENT
+
+S_CONFIRM_1:
+  → S_RESOLVE     WHEN: user confirms "Looks good"
+  → S_PARSE       WHEN: user selects "Edit steps" or "Add step"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_RESOLVE:
+  → S_CONFIRM_2   DO: A_RESOLVE_NODES (read deferred: node-catalog)
+
+S_CONFIRM_2:
+  → S_ENRICH      WHEN: user confirms "Continue"
+  → S_RESOLVE     WHEN: user changes executor or node type
+  → S_PARSE       WHEN: user selects "Back to intent"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_ENRICH:
+  → S_CONFIRM_3   DO: A_BUILD_DAG
+
+S_CONFIRM_3:
+  → S_PERSIST     WHEN: user confirms "Confirm & Save"
+  → S_CONFIRM_3   WHEN: user edits/adds/removes node       DO: apply change, re-render
+  → S_ENRICH      WHEN: user selects "Re-run checkpoints"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_PERSIST:
+  → END           DO: A_SAVE_TEMPLATE (read deferred: template-schema)
+
+</transitions>
+
+<actions>
+
+### A_PARSE_INTENT
+
+1. Parse description (if empty: ask_user for workflow description)
+2. Extract candidate nodes via semantic signals:
+
+| Signal | Type hint |
+|--------|-----------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+3. Extract variables (inputs that vary per run)
+4. Classify: task type + complexity (simple 1-3 / medium 4-7 / complex 8+)
+5. Write `intent.json` to design drafts dir
+6. Display: parsed steps, variables, task type, complexity
+
+### A_RESOLVE_NODES
+
+Read deferred `node-catalog.md` (fallback to built-in mapping):
+
+| Type hint | Default executor |
+|-----------|-----------------|
+| planning | `maestro-plan` |
+| execution | `maestro-execute` |
+| testing | `quality-test` |
+| review | `quality-review` |
+| brainstorm | `maestro-brainstorm` |
+| analysis | `maestro delegate --role analyze` |
+| verify | `maestro-verify` |
+| refactor | `quality-refactor` |
+| debug | `quality-debug` |
+
+Build `args_template` with variable placeholders. Context injection: planning-after-analysis → `--context {prev_output_path}`, execution-after-planning → `--resume-session {prev_session_id}`.
+Write `nodes.json`. Display resolved node list.
+
+### A_BUILD_DAG
+
+1. Build sequential edges (fan-out/fan-in for parallel groups)
+2. Auto-inject checkpoints:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source outputs plan/spec/analysis/review |
+| Execution gate | Target contains `execute` |
+| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| Post-testing | Source contains `test` or `auto-test` |
+| User-defined | type_hint == checkpoint |
+
+3. Finalize context_schema from {variable} references
+4. Validate: no cycles, no orphans, all reachable
+5. Write `dag.json`
+6. Display ASCII pipeline visualization
+
+### A_SAVE_TEMPLATE
+
+Read deferred `template-schema.md` (fallback to built-in structure).
+Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
+Write to `~/.maestro/templates/workflows/<slug>.json`. Update index.json.
+Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | 0 steps extracted | Ask user to rephrase with action verbs |
+| E003 | Node count > 20 | Suggest splitting into sub-workflows |
+| E005 | DAG cycle detected | Show cycle, ask user to resolve |
+| E006 | Edit template not found (--edit) | Show available templates |
+| W001 | Ambiguous step→executor mapping | Show candidates, let user choose |
+</error_codes>
+
+<success_criteria>
+- [ ] Each phase has interactive confirmation gate
+- [ ] Template JSON written with nodes, edges, checkpoints, context_schema
+- [ ] Index updated; deferred specs loaded only when phase needs them
+</success_criteria>