Session: .workflow/.maestro/MCP-{YYYYMMDD-HHmmss}/state.json
Output boundary: ALL file writes MUST target .workflow/.maestro/MCP-*/ (session state) and .workflow/.csv-wave/ (wave CSVs). Template files at ~/.maestro/templates/workflows/ are read-only during playback.
Flags: --context key=value (repeatable), -c [session-id] (resume), --list, --dry-run
Entry routing:
| Condition | Handler |
|---|---|
--list or no args |
Scan index.json, display templates |
-c [session-id] |
S_RESUME |
| Template slug/path | S_LOAD |
Barrier nodes (solo wave, coordinator reads artifacts after):
| Node type | Artifacts to read | Context updates |
|---|---|---|
| checkpoint | — | last_checkpoint |
| maestro-plan | plan.json, .task/ | plan_dir, task_count |
| maestro-execute | results.csv | exec_status |
| maestro-analyze | context.md | analysis_dir, gaps |
| maestro-brainstorm | .brainstorming/ | brainstorm_dir |
| maestro-roadmap | specs/ | spec_session_id |
state.json schema:
{
"id": "MCP-<YYYYMMDD>-<HHmmss>",
"intent": "<template_name> with context",
"chain": "<template_id>",
"template_path": "<path>",
"auto_yes": false,
"status": "in_progress|paused|completed|aborted",
"context": { "goal": "...", "phase": null, "plan_dir": null, "last_checkpoint": null },
"waves": [],
"steps": [{
"step_n": 1, "node_id": "N-001", "skill": "<executor>",
"args": "<args_template>", "type": "skill|cli|checkpoint",
"is_barrier": true, "status": "pending|completed|failed|skipped",
"wave_n": null, "findings": null, "artifacts": null
}]
}
Runtime reference resolution (before each wave CSV):
{key}→ context[key]{N-xxx.field}→ completed step with matching node_id{prev_field}→ most recently completed non-checkpoint step
CSV schemas:
wave-{N}.csv (input): id,skill_call,topic
wave-{N}-results.csv (output): from spawn_agents_on_csv result schema
Terminal Pipeline Solo Barrier: If a node's skill specifies orchestration_kind="terminal_pipeline" (e.g. team-lifecycle-v4), it must run as a solo terminal barrier. The player must write lifecycle_owner="" and checkpoint_owner="" to session context, then only monitor its progress. No outer plan/execute/test/review should be run concurrently on the same scope.
<state_machine>
S_ROUTE: → handleList WHEN: --list or no args → S_RESUME WHEN: -c flag → S_LOAD WHEN: template provided
S_RESUME: → S_WAVE_LOOP WHEN: session found DO: load state, resume from next pending wave → ERROR(E005) WHEN: no session found
S_LOAD: → S_CONFIRM WHEN: not auto_mode DO: A_LOAD_AND_BIND → S_INIT WHEN: auto_mode DO: A_LOAD_AND_BIND
S_CONFIRM: → S_INIT WHEN: user confirms → END WHEN: user cancels GUARD: display wave plan (template, session, context, waves with [BARRIER] markers), request_user_input to confirm execution. Do NOT write status.json or spawn agents before confirmation.
S_INIT: → END WHEN: --dry-run DO: display wave plan with [BARRIER] markers → S_WAVE_LOOP DO: A_INIT_SESSION
S_WAVE_LOOP: → S_WAVE_LOOP WHEN: 1+ completed in wave, more pending DO: A_EXECUTE_WAVE → advance (propagate incomplete marker if partial failures) → S_COMPLETE WHEN: all steps completed → END WHEN: checkpoint pause DO: set status=paused → S_WAVE_LOOP WHEN: all failed in wave, retry available DO: retry same wave (retry_count++, max 1 retry per wave) → END WHEN: all failed in wave, retry exhausted DO: set status=aborted, record retry_count and evidence_incomplete GUARD: checkpoint nodes → handle inline (no spawn), save snapshot, optional user pause. Partial failures (1+ completed, some failed) → continue with incomplete marker, do NOT mark failed rows as completed.
S_COMPLETE: → END DO: display per-wave results, set status=completed
A_LOAD_AND_BIND
- Resolve template: absolute/relative/slug → index.json lookup
- Parse --context key=value, validate template JSON
- Collect missing required vars via request_user_input
- Bind {variable} placeholders (leave {N-xxx.field}/{prev_*} for runtime)
A_INIT_SESSION
- Generate ID: MCP-{YYYYMMDD-HHmmss}
- Topological sort (Kahn's) → classify barrier vs non-barrier → group into waves
- Build steps array, write state.json
- Display wave plan (template, session, context, waves with [BARRIER] markers)
A_EXECUTE_WAVE
-
Checkpoint: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: request_user_input (Continue/Pause/Abort).
-
Skill nodes: resolve runtime references → write wave-{N}.csv (only rows with status == "pending") → spawn:
spawn_agents_on_csv({
csv_path: "wave-{N}.csv", id_column: "id",
instruction: SUB_AGENT_INSTRUCTION,
max_concurrency: waveSteps.length, max_runtime_seconds: 3600,
output_csv_path: "wave-{N}-results.csv", output_schema: RESULT_SCHEMA
})
- Read results → map
result_status→ master stepstatus; copysummaryinto findings andartifactsinto the step artifact list - Barrier analysis: read artifacts, update context per barrier table
- Append wave record to state.waves[], persist state.json
SUB_AGENT_INSTRUCTION
你是 CSV job 子 agent。
先原样执行技能调用:{skill_call}
然后基于结果完成任务说明:{topic}
限制:不要修改 .workflow/.maestro/ 下的 state 文件
最后必须调用 report_agent_job_result(无论成功/失败/超时都必须上报)。
TERMINATION CONTRACT(强制):
- 成功:result_status = completed,summary 描述产出
- 失败:result_status = failed,error 写明原因
- 超时:临近 max_runtime_seconds 时立即上报 result_status = failed,error = "timeout"
- 禁止:无限循环、静默退出、跳过 report_agent_job_result
OUTPUT(必须匹配 output_schema):
{"id":"<row id>","result_status":"completed|failed","skill_call":"...","summary":"一句话","artifacts":"路径或空","error":"原因或空"}
RESULT_SCHEMA
{
"type": "object",
"properties": {
"id": { "type": "string" },
"result_status": { "type": "string", "enum": ["completed", "failed"] },
"skill_call": { "type": "string" },
"summary": { "type": "string", "maxLength": 500 },
"artifacts": { "type": "string" },
"error": { "type": "string" }
},
"required": ["id", "result_status", "summary"]
}
</state_machine>
<error_codes>
| Code | Condition | Recovery |
|---|---|---|
| E001 | Template not found | Show --list |
| E002 | Template JSON invalid | Point to file |
| E004 | DAG cycle | Suggest maestro-composer --edit |
| E005 | Resume session not found | List sessions |
| E007 | Barrier artifact not found | Retry once, then abort |
| </error_codes> |
<success_criteria>
- DAG nodes grouped into barrier (solo) / non-barrier (parallel) waves
- Every skill via spawn_agents_on_csv, none in coordinator
- Barrier artifacts read and context updated before next wave
- Failed step → remaining skipped → abort reported
- -c resumes from last completed wave </success_criteria>