SuperAPI AI Directory

maestro-player

General & other

View repository

Updated 10-16 05:48

About this skill

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

  1. Resolve template: absolute/relative/slug → index.json lookup
  2. Parse --context key=value, validate template JSON
  3. Collect missing required vars via request_user_input
  4. Bind {variable} placeholders (leave {N-xxx.field}/{prev_*} for runtime)

A_INIT_SESSION

  1. Generate ID: MCP-{YYYYMMDD-HHmmss}
  2. Topological sort (Kahn's) → classify barrier vs non-barrier → group into waves
  3. Build steps array, write state.json
  4. Display wave plan (template, session, context, waves with [BARRIER] markers)

A_EXECUTE_WAVE

  1. Checkpoint: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: request_user_input (Continue/Pause/Abort).

  2. 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
})
  1. Read results → map result_status → master step status; copy summary into findings and artifacts into the step artifact list
  2. Barrier analysis: read artifacts, update context per barrier table
  3. 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>