--- name: maestro-graph description: Drive a pre-known multi-agent path as a maestro graph - run it by name or from a file you just wrote, pull each agent node with graph next, spawn it as a sub-agent under its maestro- definition, hand the result back with graph result, repeat until the verdict. Author a new graph from the reference when no preset fits. review-date: 2026-11-28 --- # maestro-graph Use when a task is a pre-known path with several agent steps: a review gate, a research sweep, a judge panel, a fix loop. The path is one markdown graph file; maestro holds the run, executes the deterministic nodes itself and hands you only the agent and human nodes to spawn. maestro never starts a model (Hub d78), so the loop below is yours on every harness. Design, diagnosis and the SLP seat protocol stay outside graphs. ## Pick or write the graph - `maestro graph list` shows every graph across the repo (`/.maestro/graphs`), the room (`~/maestro/graphs`) and the shipped set; a nearer file shadows a farther one by name. `maestro graph show ` prints one. - A shipped preset fits: run it by name. `review-gate` takes `range=` and `tier=light|full`; `fix-loop` takes `scope=` and `check=` and drives a writing fixer for at most three rounds; `council` takes `brief=` and `tier=lens|debate|debate-with-proof|high-risk` and runs the maestro-council protocol with you (the Lead) answering the draft and verdict nodes. - Nothing fits: write a graph for the task from [references/authoring.md](references/authoring.md) and run it with `--file `. Keep a good one by copying the file into a graphs directory (Hub d100; there is no save verb). ## The pull loop (executor subagent) ```text maestro graph run |--file [key=value ...] [--limit k=v] --json loop: envelope = the JSON just returned (or maestro graph next --json) if envelope.done: stop; the verdict, LIMIT stop or failed node is in it for each node in envelope.nodes (all at once, they are independent): kind human -> stop and ask the user the prompt; feed the answer back kind agent -> spawn a sub-agent with the node's profile and prompt for each returned sub-agent: maestro graph result --file |--text "" maestro graph next --json ``` - `run` returns the first envelope, so the first `next` is implicit. - Every node in `nodes` is ready now; spawn them in parallel. Nodes that depend on one of them appear on a later `next`, as soon as their own inputs are in: only a `join` waits for a whole fan-out (Hub d82). - `ref` is the node id, or `node@key` for one instance of a foreach. - A node with a `schema` must return JSON of that shape. Write the sub-agent's answer to a file and pass `--file`; maestro extracts the first JSON block from prose or a fence. `PARSE_FAILED` with `retry: true` means re-ask that sub-agent once for JSON matching the schema carried in the error; the second failure marks the node failed and the run ends with `failed`. - `stopped: "LIMIT"` ends the run at a structural limit (`nodes`, `loops`, `fanout`, Hub d84) with `partial` state; rerun with `--limit =` when the cap, not the graph, was wrong. - `GRAPH_UNTRUSTED` on a repo graph's function node: review the file the error names, then run the `maestro graph trust` command it gives and `graph next` again. Home and shipped graphs never ask. - `maestro trace ` is the journal: every node transition and round. ## Spawning an agent node The profile is a definition `maestro install` rendered for both harnesses (Hub d83): `~/.claude/agents/maestro-.md` and `~/.codex/agents/maestro-.toml`. - Claude Code: the `Agent` tool with `subagent_type: "maestro-"`, `model: "opus"`, and the node's `prompt` verbatim as the task. - Codex: `spawn_agent` with agent type `maestro-` and the node's `prompt` verbatim. Send the prompt as maestro rendered it; it already carries the run state the graph author placed in it. Add only what the harness needs to return the answer (for example, "write your JSON answer to "). Never merge two nodes into one spawn and never run a function node's command yourself; maestro already did. ## Executor team `graph run` reports `executor` in every envelope (Hub d88): `subagent` from a plain session, `claude -p`, `codex exec` or a desktop app; `team` when the driver is a role pane of a running SLP team. Under `team` the Lead is the driver and each agent node is one Peer work item (Hub d89); the Lead is never a node and maestro still spawns nothing. ```text Team Supervisor: maestro work add "run graph " \ --acceptance "the run's verdict" Lead: maestro work take maestro graph run [key=value ...] --json loop: envelope = the JSON just returned (or maestro graph next --json) if envelope.done: maestro work return ""; stop for each node in envelope.nodes without a work field: kind human -> answer it yourself: maestro graph result --text "" kind agent -> maestro work add "" --to peer- \ --acceptance "one JSON object matching the node schema" --json maestro graph result --work for each node with a work field whose workState is RETURNED: read it (maestro status ), then maestro work accept (or maestro work note "" --rework for one retake) maestro graph next --json Team Supervisor: maestro work accept ``` - One pane per profile: `--to peer-` opens the Peer lazily on the first item and queues later nodes of that profile on the same pane. - A bound node stays in `nodes` with `work` and `workState` until its item is DONE; `next` then parses the item's returned body like any result (schema and all) and issues what depended on it. A cancelled item fails the node. - Bound nodes count toward `limits.fanout`; keep the fan-out under the number of Peers you are willing to open. - Prompts to a Peer must open with a lowercase plain sentence; a brief that opens "You are ..." is swallowed as a slash command. The node prompts in the shipped presets already do. - The graph runtime writes no SLP state: every `work add`, `accept` and `return` above is yours (A7). ## Hand-off The verdict is the run's evidence on its work item (`maestro work show `); quote it in the return that asked for the gate. A graph that misbehaved is a finding for the handback, not a card.