maestro

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/workflows/codex-run-mode.md </required_reading>

<deferred_reading>

maestro.md — read at execution start for intent analysis + chain selection
maestro-super.md — read when --super flag active
node-catalog — read at A_COMPOSE_TEMPLATE node resolution (--compose)
template-schema — read at A_COMPOSE_TEMPLATE persist step (--compose) and A_PLAY_TEMPLATE load step (--play) </deferred_reading>

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. -c is reserved for --continue across all maestro commands — downstream skills MUST NOT redefine -c for other purposes to prevent collision via transparent forwarding.
--dry-run — Show chain without executing
--super — Read and follow maestro-super.md
--compose [--edit <path>] — Compose a reusable workflow template (NL → DAG) instead of running a live chain. Routes to A_COMPOSE_TEMPLATE.
--play <template-slug|path> [--context k=v...] [--list] [--dry-run] — Execute a saved workflow template through the ralph chain runner. Routes to A_PLAY_TEMPLATE.

<state_machine>

S_PARSE: → S_COMPOSE WHEN: --compose flag → S_PLAY WHEN: --play flag → 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_COMPOSE: → END DO: A_COMPOSE_TEMPLATE

S_PLAY: → S_DISPATCH WHEN: template resolved DO: A_PLAY_TEMPLATE (build DAG steps → status.json) → S_FALLBACK WHEN: template not found / --list DO: list templates from index.json

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 (refactor/comprehensive/rewrite/migrate/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: spawn_agent({ task_name: "maestro_ralph", message: "Execute skill maestro-ralph" })

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

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_COMPOSE_TEMPLATE

Compose a reusable workflow template (natural language → DAG). --edit <path> loads an existing template for revision.

Parse intent → candidate nodes (verb signals: analyze/review→analysis-cli, plan/design→planning, implement/build→execution, test→testing; then/next→sequential edge, parallel→fan-out) + variables + complexity. Confirm parse via request_user_input.
Resolve nodes → map each step to an executor. Read deferred node-catalog.md (fallback: planning→plan, execution→execute, testing→test, review→review, analysis→maestro delegate --to <tool> --mode analysis). Build args_template with {variable} placeholders. Confirm mapping.
Build DAG → sequential/fan-out edges, auto-inject checkpoints (artifact boundaries, before any execute, after any test), finalize context_schema. Validate: ≤20 nodes, acyclic, no orphans. Display ASCII pipeline; confirm via request_user_input.
Persist → read deferred template-schema.md; assemble template JSON (template_id: wft-<slug>-<date>, nodes, edges, checkpoints, context_schema) → write to ~/.maestro/templates/workflows/<slug>.json + update index.json. All writes target ~/.maestro/templates/workflows/ only. Abandoning any gate saves a draft to .workflow/templates/design-drafts/.
Output: template path/ID + /maestro --play <template-id> to run it.

A_PLAY_TEMPLATE

Execute a saved workflow template through the ralph chain runner. Flags: --context k=v (repeatable), --list, --dry-run.

Resolve template: absolute path → as-is; slug → ~/.maestro/templates/workflows/index.json lookup. --list → display index and END. Read deferred template-schema.md to validate (template_id, nodes, edges, context_schema required).
Bind context: parse --context k=v; collect missing required variables via request_user_input; bind {variable} placeholders (leave {N-xxx.field} and {prev_*} for runtime resolution by maestro-ralph).
Topological sort (Kahn) template nodes → linear steps[] (parallel nodes share a batch index). Each step carries skill/args/type (skill|cli|agent|checkpoint) resolved as in A_CREATE_SESSION; cli nodes run async via Bash(run_in_background) + STOP, checkpoints pause with resume via -c.
Create session: write .workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json (source: "maestro", template_id, bound context, topologically-ordered steps[]). --dry-run → display plan and END.
Dispatch to maestro-ralph (S_DISPATCH) — the runner honors checkpoints, resume-safety, and per-step completion_confirmed exactly as for classified chains.

A_CLASSIFY_INTENT

Read ~/.maestro/workflows/maestro.md from deferred_reading
Match intent to task_type via chain catalog (semantic)
Select chain from chainMap, following topological constraints:
- stress test/interrogate/validate assumptions/grill/stress-test → grill（-y mode passthrough -y to grill, grill executes in Auto mode, does not skip）
- brainstorm/explore → brainstorm
- learn/read code/follow along/follow → Skill("learn", "follow"); investigate/why/investigate → Skill("learn", "investigate"); decompose/mode/decompose → Skill("learn", "decompose"); review/challenge/second-opinion → Skill("learn", "consult"); retro/retro → step retrospective（maestro run prepare --platform codex retrospective + maestro run create retrospective --session YYYYMMDD-retrospective-{topic} --intent "{goal}"）
- formal spec/spec-generate/7-phase → blueprint
- project init → init
- broad/medium intent + no session context → analyze-macro(produces scope_verdict, ralph decides at post-analyze-scope whether to insert roadmap+analyze or jump directly to plan --from analyze)
- session context → analyze --session {session} → plan --session {session} → execute --session {session} → quality pipeline
- already have analyze artifact and want direct execution → plan --from analyze:{ANL_ID} → execute → quality pipeline
- already have blueprint artifact → plan --from blueprint:{BLP_ID} → execute → quality pipeline
Execute step:Bash("maestro ralph skills --platform codex --json --quiet") pre-validate skill name, on hit write absolute path to command_path, on miss mark missing; also write step.stage / step.scope / step.source_artifact_ref. decision nodes do not resolve command_path

A_CLARIFY

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

A_DECOMPOSE_TASKS

Set session.decomposition_owner = "maestro". Downstream ralph only consumes, does not ask again (invariant 4). Condensed:

Classify intent breadth. narrow / single-step / {status,init,quick} chain skip
broad/medium → request_user_input ≤3 rounds: Scope / Constraints / Definition of Done
Derive execution_criteria + task_decomposition(each sub-goal contains done_when + evidence + lifecycle + completion_confirmed: false）
status.json single source of truth: write boundary_contract / execution_criteria / task_decomposition; do not generate markdown checklist
After the last evidence-producing stage (execute/review/test), append decision:post-goal-audit(session termination audit node). maestro-ralph dynamically grows as needed at this node steps[]

Output /goal bound prompt (non-blocking, user can input at any time during execution):

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

/goal 完成以下子目标：
{for each G in task_decomposition:}
- {G.id}: {G.goal} — 完成条件: {G.done_when}
{end for}
达成条件: {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

Specs precheck: when chain contains analyze-macro / analyze / plan / execute and other execution stages and .workflow/specs/ directory does not exist, insert at the very front of steps spec-setup（stage=spec-setup, no decision). Ensure downstream can obtain project constraint rule injection. Skip when chain ∈ {grill, brainstorm, blueprint, init, status, quick}
Read .workflow/state.json obtain active_session_id / match sessions[](including D-007-S session resolution); read latest macro analyze artifact and inject scope_verdict + analyze_macro_id(if exists); read latest blueprint artifact and inject blueprint_id

Create .workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json(shares schema with ralph):

{
  "session_id", "source": "maestro", "intent", "task_type", "chain_name",
  "ralph_protocol_version": "2", "active_step_index": null,
  "session_ref": "", "session_is_new": false,
  "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
  "auto_mode": false, "decomposition_owner": "maestro", "cli_tool": "claude",
  "context": { "run_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",
    "session_ref": null, "source_artifact_ref": null,
    "status": "pending", "goal_ref": null,
    "completion_confirmed": false, "completion_status": null,
    "completion_evidence": null,
    "completion_summary": null, "completion_decisions": null,
    "completion_caveats": null, "completion_deferred": null,
    "completed_at": null,
    "deferred_reads": [], "load": null
  }],
  "waves": [], "current_step": 0, "status": "running",
  "boundary_contract": {}, "execution_criteria": [],
  "task_decomposition": [{ "status": "pending|done|superseded",
    "superseded_by": null, "superseded_at": null, "origin": null }],
  "task_decomposition_all_done": false,
  "goal_changelog": []
}

Validate: all steps' command_scope != "missing", otherwise raise E005 listing missing skills
Initialize tracking via update_plan
If --super: read maestro-super.md, follow it completely

</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

Intent classified with task_type, complexity, clarity_score
Chain catalog covers grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan (three paths) / execute / quality pipeline
-y mode passthrough -y to grill (grill executes with Auto mode code answering on behalf, stage does not skip)
D-007-S: session step's session_ref via state.json.sessions[] session_id or intent slug match
macro analyze followed by decision:post-analyze-scope(downstream chain determined by ralph-evaluated scope_verdict)
plan supports --session {session} / --from analyze:{ANL_ID} / --from blueprint:{BLP_ID} three paths;source_artifact_ref write to step
Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
status.json sole source of truth; no markdown checklist; post-goal-audit node appended when decomposed; /goal prompt uses status.json as criterion
Specs precheck: chain contains execution stage + .workflow/specs/ does not exist → insert at the very front of steps spec-setup
Chain selected and confirmed (or auto-confirmed)
Session dir created with status.json before execution; decomposition fields additive-only
execution step contains command_scope + command_path + completion_confirmed; decision step identified by step.decision identified by
command_scope/command_path by maestro ralph skills --platform codex --json --quiet pre-validated (project overrides global)
Session schema contains ralph_protocol_version: "2" + active_step_index: null + step.load placeholder
when user passes in -y pass through to skill args
All chains dispatched via maestro-ralph
Low-complexity intents routed to step quick
(super) Requirements validated before roadmap
(super) Each session scored >= 80%
(compose) --compose produces a validated template (≤20 nodes, acyclic, no orphans) written to ~/.maestro/templates/workflows/ + index; drafts preserved on abandon
(play) --play <template> binds context, topologically sorts nodes → steps[], and dispatches via maestro-ralph; --list/--dry-run short-circuit