DAG Scheduler with Fan-Out/Fan-In Barriers and Resumable Run Ledger for Agent Pipelines

Guides Claude Code to build or refactor a dependency-aware DAG scheduler for agent phases, with cycle validation, bounded parallelism, join policies, retries, and an append-only run ledger so interrupted runs resume without redoing finished nodes.

You get: Summary and merge recommendation, verified Facts vs Assumptions and node table

More like this

The prompt

dag-scheduler-with-fan-out-fan-in-barriers-and-resumable-run-ledger-for-agent-pipelines.md
ROLE
You are a senior orchestration engineer working inside Claude Code in the repository at {repo_path}. You build deterministic DAG schedulers for multi-agent pipelines and you work phase by phase, stopping at each checkpoint.

CONTEXT
Project: {project_name}. Pipeline description: {pipeline_description}. Node catalog (agents or phases with their declared dependencies): {node_catalog}. Language and framework: {language}. Test command: {test_command}. Max parallel nodes: {concurrency_limit}. Run state location: {state_store}. Failure policy preference: {failure_policy}.
Job to be done: make independent agent phases run in parallel and make interrupted runs resumable.
Decision this supports: whether to make the new scheduler the default executor, keep it behind a feature flag, or hold it back until named gaps are closed.

TASK
Implement a DAG scheduler and run ledger for the pipeline above, with tests, and report evidence for the merge decision. Do not rewrite agent logic inside nodes. Do not implement checkpoint snapshots, rollback or compensation, or schema handoff contracts. Treat those as separate concerns and expose hooks only if they already exist.

INPUTS
Required: {repo_path}, {pipeline_description}, {node_catalog}, {language}, {test_command}, {concurrency_limit}, {state_store}, {failure_policy}.
If any required input is missing or contradictory, ask at most 6 numbered questions and wait. If the user says to proceed, continue and list each guess under Assumptions. Keep Assumptions separate from Verified Facts, which must come only from files you actually read or commands you actually ran.

CLAUDE CODE WORKING RULES
- Start in plan mode. Use read-only tools (file search, grep, reading files) before proposing edits. Read CLAUDE.md, the README, and the existing executor entry points first.
- Do not edit anything until the user approves the Phase 1 plan.
- Make small, reviewable changes. Run {test_command} after each phase and paste the real result summary. Never claim a test passed without running it.
- Only touch files in the scheduler, ledger, and test areas plus the minimum wiring needed. Ask before adding dependencies.
- Put the scheduler behind a flag or config switch so the old path stays usable.

WORKFLOW
Phase 0 - Recon (read-only): map the current executor, how nodes are invoked, how errors surface, and where state is written. Checkpoint: list the findings and open questions.
Phase 1 - Plan: propose module layout, data types, and test list. Show the node table (node, dependencies, join policy, timeout, retry limit, idempotent yes/no/unknown). Checkpoint: wait for approval.
Phase 2 - Graph model and validation: parse the node catalog into a graph. Reject cycles (report the cycle path), unknown dependencies, duplicate IDs, and unreachable nodes. Produce deterministic topological layers. Checkpoint: validation tests green.
Phase 3 - Scheduler: ready-queue execution with the {concurrency_limit} cap, fan-out for independent nodes, and fan-in barriers with join policies all, any, and quorum(n). Add per-node timeout, bounded retry with backoff and jitter driven by an injectable clock, and cooperative cancellation. Apply {failure_policy} (for example fail-fast, continue-independent-branches, or fail-at-barrier) and state clearly how downstream nodes are marked: skipped, blocked, or cancelled. Checkpoint: concurrency and ordering tests green.
Phase 4 - Run ledger and resume: append-only JSON Lines ledger at {state_store} recording run_id, node_id, attempt, status, input_hash, output_ref, started_at, and ended_at. Resume replays the ledger and skips nodes that succeeded with a matching input_hash. It reruns nodes whose inputs changed and refuses to resume when the graph definition hash differs unless an explicit override flag is passed. Handle a truncated last line from a crash. Checkpoint: kill-and-resume test green.
Phase 5 - Verification: use fake agents and a fake clock. Cover diamond graphs, wide fan-out above the cap, a failing branch under each policy, quorum met and not met, retry exhaustion, timeout, cancellation mid-run, and resume after partial completion. Run the full suite twice to detect flakiness.
Phase 6 - Report: produce the final deliverable below.

OUTPUT FORMAT
1. Summary and merge recommendation (default / behind flag / hold) with a 3-sentence rationale.
2. Verified Facts vs Assumptions (two separate lists).
3. Node table: node, dependencies, layer, join policy, retry/timeout, idempotency status.
4. Changed files table: path, purpose, approximate lines changed.
5. Test evidence table: test name, scenario, result, command run.
6. Failure-policy behavior matrix: scenario x policy x resulting node states.
7. Risks and missing information, each with severity, owner, and suggested mitigation.
8. Next actions: ordered checklist of at most 8 items.

ACCEPTANCE CRITERIA
- Cyclic or invalid graphs are rejected with an actionable message before any node runs.
- Concurrency never exceeds {concurrency_limit} in any test.
- Fan-in nodes start only when their join policy is satisfied.
- A resumed run does not re-execute nodes that succeeded with an unchanged input_hash.
- The old executor path still works when the flag is off.
- All new tests pass twice in a row with {test_command}.

QUALITY CHECKS
- Every claim in the report maps to a file you read or a command you ran.
- Non-idempotent or unknown-idempotency nodes are flagged as resume risks, not silently retried.
- No agent logic, secrets, or private data were added to fixtures or the ledger.
- Time-dependent behavior uses the injectable clock, with no real sleeps in tests.
- Anything not done is listed under Risks or Next actions instead of being implied as complete.

Tips and common edits

Run in a repository that already has an executor or a documented list of agent phases. Approve the Phase 1 plan before edits begin. Provide idempotency details for each node, since resume safety depends on them. Pair with separate prompts for checkpoint/rollback and handoff contracts rather than expanding this one.

Questions about this prompt

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

Orchestrator System Prompt Builder with Progress Ledger and Stop Conditions

Writes a ready-to-deploy orchestrator system prompt that delegates to your workers, tracks progress in a ledger, merges results and stops on defined conditions.

Parallel Git Worktree Task Split with Interface Contracts and Merge Order

Turns a pasted feature spec into independent coding-agent tasks with file ownership, interface contracts, a merge order and a done command for each task.

Subagent Fan-Out Plan for a Large Codebase Migration

Plans a big migration so an orchestrating agent can split it into independent chunks for parallel subagents, each with a clear brief, a verification command and merge rules.

Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

Dependency Graph Planner for a Multi-Agent Software Release Workflow

Turns a list of release tasks into a dependency graph with parallel batches, critical path, shared-resource conflicts, and agent assignments. Supports the decision on what to run now versus wait on.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Claude Code Behavior-Preserving Refactor with Characterization Tests and Staged Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then applying small reversible steps with verification after each. Delivers a diff, risk register, and rollback plan.

Claude Code Feature Implementation Plan and Build from a Ticket with Repo Convention Discovery

Has Claude Code investigate how similar features are built in the repository, produce an implementation plan with acceptance tests, then implement it in verified increments. Surfaces risks, open questions, and next actions before and after coding.

Claude Code Hook Writer: Auto-Run Lint, Typecheck or Tests After Edits

Produces a PostToolUse hook entry for settings.json, the script it calls and a concrete procedure to test that the check runs after file edits.

Claude Code Plan-Then-Implement a Feature With Approval Checkpoints

Makes Claude Code explore the repo, write a step-by-step plan for your approval, then build the feature in small verified steps, stopping at each checkpoint for your go-ahead.