<purpose> Orchestrate all maestro commands based on user intent and project state. Classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.

Entry points:

/maestro "intent" — Intent-based: classify → chain → execute
/maestro -c — Resume previous session
/maestro --dry-run "intent" — Show chain, no execution
/maestro --super "intent" — Production-ready mode (read maestro-super.md)

Session: .workflow/.maestro/{session_id}/status.json — 工作流唯一真源。session_id 格式 maestro-{YYYYMMDD-HHmmss}（本 command 创建，静态链）或 ralph-{YYYYMMDD-HHmmss}（/maestro-ralph 创建，自适应链）。两类都由 /maestro-ralph-execute 推进；schema 与 ralph 共用（含 ralph_protocol_version: "1" + active_step_index）。 </purpose>

<deferred_reading>

maestro.md — read at execution start for intent analysis + chain selection
maestro-super.md — read when --super flag active </deferred_reading>

<context> $ARGUMENTS — user intent text, or special keywords.

Keywords: continue/next/go → state-based routing; status → Skill("manage-status")

Flags:

-y / --yes — Auto mode: skip clarification, skip confirmation, auto-skip on errors
-c / --continue — Resume previous session
--dry-run — Show chain without executing
--super — Read and follow maestro-super.md </context>

<invariants> 1. **All chains dispatch via maestro-ralph-execute** — maestro never executes steps directly 2. **Session before execution** — status.json created before any step runs 3. **Auto flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args 4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS` 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单 6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）；decision 节点不走 CLI，走 `Skill("maestro-ralph")` handoff 7. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定 8. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查 9. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入 10. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选 </invariants>

<state_machine>

<states> S_PARSE — 解析参数、检测 flags PERSIST: — S_RESUME — 扫描已有 session、恢复执行 PERSIST: — S_CLASSIFY — 意图分类、chain 选择 PERSIST: — S_DECOMPOSE — 边界澄清、写执行准则+子目标清单 PERSIST: session.boundary_contract, .execution_criteria, .task_decomposition S_CREATE — 创建 session + status.json PERSIST: session (全量) S_DRY_RUN — 显示 chain 后结束 PERSIST: — S_CONFIRM — 用户确认（auto_mode 跳过） PERSIST: — S_DISPATCH — 移交 maestro-ralph-execute PERSIST: — S_FALLBACK — 意图无法分类、请求输入 PERSIST: — </states> <transitions>

S_PARSE: → S_RESUME WHEN: -c / --continue flag → S_CLASSIFY WHEN: intent text present → S_CLASSIFY WHEN: keyword "continue"/"next"/"go" DO: A_STATE_BASED_ROUTE → S_FALLBACK WHEN: no intent AND no flags

S_RESUME: → S_DISPATCH WHEN: session found DO: A_LOCATE_SESSION → S_FALLBACK WHEN: no session found

S_CLASSIFY: → S_DECOMPOSE WHEN: chain resolved DO: A_CLASSIFY_INTENT → S_FALLBACK WHEN: no match AND auto_mode → S_CLASSIFY WHEN: no match AND not auto_mode DO: A_CLARIFY GUARD: max 2 clarification rounds → S_FALLBACK

S_DECOMPOSE: → S_CREATE DO: A_DECOMPOSE_TASKS GUARD: broad intent (重构/全面/重写/迁移/overhaul/migrate/rewrite) on a multi-step lifecycle chain → MUST clarify even if auto_mode GUARD: single-step chain OR narrow intent OR chain ∈ {status,init,quick} → skip decomposition (pass through)

S_CREATE: → S_DRY_RUN WHEN: --dry-run flag DO: A_CREATE_SESSION → S_CONFIRM WHEN: not auto_mode DO: A_CREATE_SESSION → S_DISPATCH WHEN: auto_mode DO: A_CREATE_SESSION

S_DRY_RUN: → END DO: display chain with step types

S_CONFIRM: → S_DISPATCH WHEN: user confirms → S_PARSE WHEN: user wants to modify → END WHEN: user cancels

S_DISPATCH: → END DO: Skill({ skill: "maestro-ralph-execute" })

S_FALLBACK: → S_CLASSIFY WHEN: user provides new intent DO: AskUserQuestion → END WHEN: user cancels

</transitions> <actions>

A_STATE_BASED_ROUTE

Read .workflow/state.json → determine next logical step
Convert to equivalent intent for chain classification

A_LOCATE_SESSION

Scan .workflow/.maestro/*/status.json, filter status == "running", sort DESC
Take most recent; if not found → S_FALLBACK

A_CLASSIFY_INTENT

Read ~/.maestro/workflows/maestro.md from deferred_reading
Match intent to task_type via chain catalog (semantic)
Select chain from chainMap，遵循拓扑约束：
- 头脑风暴/探索 → brainstorm
- 正式规格/spec-generate/7-phase → blueprint
- 项目初始化 → init
- 宽/中等意图 + 无数字 phase → analyze-macro（产 scope_verdict，由 ralph 在 post-analyze-scope 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
- 数字 phase 上下文 → analyze {phase} → plan {phase} → execute {phase} → verify {phase} → quality pipeline
- 已有 analyze artifact 想直达执行 → plan --from analyze:{ANL_ID} → execute → verify
- 已有 blueprint artifact → plan --from blueprint:{BLP_ID} → execute → verify
执行 step：Bash("maestro ralph skills --json --quiet") 预校验 skill 名，命中写绝对路径到 command_path，未命中标 missing；同时写 step.stage / step.scope / step.source_artifact_ref。decision 节点不解析 command_path

A_CLARIFY

AskUserQuestion with parsed intent + available chain options
Re-classify with user response

A_DECOMPOSE_TASKS

与 maestro-ralph A_DECOMPOSE_TASKS 共享分解契约。Condensed:

分类意图广度。narrow / 单步 / {status,init,quick} 链跳过
broad/medium → AskUserQuestion ≤3 轮：Scope / Constraints / Definition of Done
派生 execution_criteria + task_decomposition（每个 sub-goal 含 done_when + evidence + lifecycle + completion_confirmed: false）
status.json 唯一真源：写入 boundary_contract / execution_criteria / task_decomposition；不生成 markdown 清单
在最后一个 evidence-producing stage（verify/review/test）之后、milestone-complete 之前追加 decision:post-goal-audit。ralph-execute 在该节点按需动态生长 steps[]

输出 /goal 绑定提示词（不阻塞，用户可在执行过程中随时输入）：

📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：

/goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。

A_CREATE_SESSION

Read .workflow/state.json 获取 phase / milestone（含 D-007 反查 phase_slugs）；读最新 macro analyze artifact 注入 scope_verdict + analyze_macro_id（如存在）；读最新 blueprint artifact 注入 blueprint_id

Create .workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json（与 ralph 共用 schema）：

{
  "session_id", "source": "maestro", "intent", "task_type", "chain_name",
  "ralph_protocol_version": "1", "active_step_index": null,
  "phase", "phase_is_new": false, "milestone": "",
  "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
  "auto_mode": false, "cli_tool": "claude",
  "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null,
    "brainstorm_dir": null, "blueprint_dir": null, "issue_id": null },
  "steps": [{
    "index": 0, "skill": "", "args": "",
    "stage": "", "scope": null, "decision": null,
    "command_scope": "global|project|missing|null", "command_path": "<abs> | null",
    "milestone_id": null, "source_artifact_ref": null,
    "status": "pending", "goal_ref": null,
    "completion_confirmed": false, "completion_status": null,
    "completion_evidence": null, "completed_at": null,
    "deferred_reads": [], "load": null
  }],
  "waves": [], "current_step": 0, "status": "running",
  "boundary_contract": {}, "execution_criteria": [],
  "task_decomposition": [], "task_decomposition_all_done": false
}

Validate: 所有 step 的 command_scope != "missing"，否则 raise E005 列出缺失 skill
Initialize tracking via TodoWrite
If --super: read maestro-super.md, follow it completely

</actions>

</state_machine>

Error Codes

Code	Severity	Description	Recovery
E001	error	No intent and project not initialized	Prompt or suggest maestro-init
E002	error	Clarity too low after 2 rounds	Show parsed intent, ask rephrase
E003	error	Chain step failed + user abort	Record partial, suggest -c resume
E004	error	Resume session not found	Show available sessions
E005	error	command_scope == "missing" for one or more steps	List missing skills, abort build
W001	warning	Ambiguous intent, multiple chains	Present options
W002	warning	Step completed with warnings	Log and continue
W003	warning	State suggests different chain	Show discrepancy

Success Criteria

</appendix>

maestro

details