graph-orchestrator

name

graph-orchestrator

description

Use when a task needs multiple subagents or workstreams, when several tasks can run concurrently, or when blockers, shared files, mutable resources, handoffs, verification, and merge conflicts must be modeled explicitly — for planning-only requests as well as execution requests, on Claude Code, Codex, or another AI agent runtime; do not use for small, exploratory, or genuinely sequential work where orchestration overhead exceeds the benefit.

Graph Orchestrator: Graph Engineering for AI Agents

Turn complex Claude Code, Codex, or other AI agent work into an explicit task graph, remove fake dependencies, and coordinate only the nodes that are safe and useful to run in parallel.

Operating Rules

• Keep the parent agent responsible for scope, graph state, dispatch, conflict resolution, synthesis, and user communication.
• Treat each node as one bounded job with explicit inputs, outputs, ownership, completion evidence, and failure behavior.
• Create an edge only when a downstream node needs data, approval, authority, or a mutable resource held by an upstream node.
• Model hidden conflicts. Two nodes that write the same file, change the same external object, consume the same scarce quota, or make incompatible decisions are not independent.
• Run only ready nodes: all dependencies satisfied, required inputs available, and mutable resources unclaimed.
• Give one node one owner. Avoid duplicate assignments unless independent redundancy is intentional.
• Keep workers isolated when possible. Use non-overlapping files, worktrees, branches, or read-only scopes.
• Never let a worker verify its own result. Use a fresh-context verifier and objective anchors.
• Count expected versus received outputs before every merge. Never present partial synthesis as complete.
• Bound concurrency, retries, discovery depth, time, and cost. Start narrow and widen only when evidence supports it.
• Preserve user authority. Planning does not authorize execution; execution does not authorize unrelated writes, publication, deployment, destructive actions, or other external side effects.

Workflow

1. Decide Whether to Build a Graph

Use a graph when the work has at least two useful independent nodes, spans distinct contexts or specialties, or needs explicit blocker/conflict management.

Prefer one agent or a simple loop when the task is small, exploratory, tightly coupled, or dominated by one sequential critical path. Apply the fake-edge test: if task B does not consume anything from task A and they do not contend for a shared resource, remove the edge.

Read graph-design.md when decomposition or dependency choice is non-trivial.

2. Inspect the Execution Surface

Before assigning work:

1. Read applicable repository instructions and inspect relevant state.
2. Identify available subagent tools, concurrency slots, context-fork options, and permission boundaries.
3. Record shared mutable surfaces: files, directories, branches, databases, APIs, documents, deployment targets, and user-visible decisions.
4. Separate planning-only work from authorized execution.

If subagent tools are unavailable, still return the graph as a workstream plan and execute locally only when the user requested execution.

3. Build the Graph

Create a node table with:

Field	Required content
ID	Stable short identifier
Job	One bounded action
Depends on	Node IDs whose outputs or gates are required
Inputs	Concrete artifacts, facts, or approvals
Output	Fixed shape and destination
Owns	Files/resources this node may mutate
Done when	Observable evidence
Verify	Fresh check or objective anchor
On failure	Retry, fallback, skip, or escalate

Reject cycles unless the user needs a bounded discovery or repair loop. For loops, define a convergence signal and a hard cap.

Use node-contract-template.md for delegated tasks and graph-spec-template.md for the complete plan.

4. Audit Edges and Conflicts

For every proposed edge, name the artifact, approval, authority, or resource it carries. Delete edges that carry nothing.

For every pair of ready nodes, check:

• overlapping writes;
• read-after-write or write-after-write hazards;
• shared rate limits, credentials, devices, or singleton tools;
• contradictory decision authority;
• one node invalidating assumptions used by another.

Add an ordering edge, narrow ownership, isolate workspaces, or reserve the resource. Read execution-control.md for arbitration and blocker rules.

5. Present the Plan Before Dispatch

Show the user a compact graph or node table when the graph is materially complex. State:

• critical path;
• first ready wave;
• blockers and human gates;
• ownership boundaries;
• concurrency and cost caps;
• what will be verified and how.

For planning-only requests, stop after delivering the graph and recommended first wave.

6. Execute in Ready Waves

When execution is authorized:

1. Mark nodes pending, ready, running, blocked, failed, verified, or complete.
2. Dispatch only the highest-value ready nodes up to the concurrency cap.
3. Give each subagent the minimum context needed, the node contract, absolute paths where relevant, and a do-not-touch list.
4. Continue useful local orchestration work while subagents run.
5. Collect outputs, validate their declared shape, and update graph state.
6. Unlock dependents only after required verification passes.
7. Keep independent branches moving when another branch blocks.

Use the runtime's native agent tools. Do not simulate parallelism by merely listing jobs. Do not spawn agents speculatively “for later.”

Track execution with run-ledger-template.md.

7. Handle Blockers and Failures

Classify each problem:

• Local failure: retry once with a corrected bounded instruction when the cause is understood.
• Missing input: block the node and its descendants; continue unrelated branches.
• Resource conflict: serialize, reassign ownership, or isolate the resource.
• Spec conflict: parent agent arbitrates from user intent and evidence.
• Permission or human gate: stop that branch and request the exact decision or authority needed.
• No progress: stop after the declared retry/convergence cap; do not create an unbounded agent loop.

Never silently drop a failed node. Record its effect on downstream completeness.

8. Verify and Synthesize

Use a verifier that did not inherit the worker's reasoning when the runtime supports fresh contexts. Pass the artifact and acceptance criteria, not the worker's chat.

Prefer anchors that cannot be argued into passing: executed tests, schema validation, resolved source links, file diffs, counts, checksums, deployment status, or user approval.

Before synthesis:

1. Compare expected and received node outputs.
2. Flag missing, failed, stale, or unverified inputs.
3. Deduplicate overlapping findings.
4. Layer fan-in when outputs are too large: summarize batches, verify summaries, then merge.
5. Report residual uncertainty and incomplete branches.

Read verification-and-synthesis.md for detailed gates.

Deliverable

For a plan, return the graph, first wave, critical path, conflicts, gates, caps, and definitions of done.

For execution, return:

• completed and verified nodes;
• files or external state changed;
• validation evidence;
• blocked or failed branches and downstream impact;
• remaining nodes or user decisions;
• final synthesis only from accounted-for inputs.

Resources

• graph-design.md: decomposition, contracts, fake-edge test, diamonds, loops, and graph selection.
• execution-control.md: scheduling, ownership, conflicts, blockers, retries, and human gates.
• verification-and-synthesis.md: fresh-context checking, anchors, completeness, and layered fan-in.
• worked-patterns.md: reusable research, code-audit, launch-kit, and discovery-loop patterns.
• graph-spec-template.md: copyable graph plan.
• node-contract-template.md: copyable delegation contract.
• run-ledger-template.md: copyable execution state ledger.
• conflict-matrix-template.md: copyable shared-resource audit.

Source

This skill adapts the graph-engineering guidance in Anatoli Kopadze's X article, “Graph Engineering explained: what it is, when to use it and when not to”. The operational scheduler, state model, ownership rules, and platform-neutral tool guidance extend that guidance for reliable agent execution.