| license | BSL-1.1 |
| name | dag-planner |
| description | Builds, validates, schedules, and dynamically modifies DAG execution graphs. Decomposes problems into nodes with dependencies, performs topological sorting, detects cycles, resolves conflicts, and schedules wave-based parallel execution. Use when designing a DAG structure, validating dependencies, planning execution order, or modifying a DAG at runtime. Activate on "build DAG", "plan workflow", "DAG dependencies", "topological sort", "schedule execution", "modify DAG", "replan". NOT for executing DAGs (use dag-runtime), validating outputs (use dag-quality), or matching skills to nodes (use dag-skills-matcher). |
| allowed-tools | Read,Write,Edit,Grep,Glob |
| metadata | {"category":"DAG Framework","tags":["dag","planner","build-dag","plan-workflow","dag-dependencies"]} |
| category | Agent & Orchestration |
| tags | ["dag","planning","decomposition","strategy","orchestration"] |
DAG Planner
Builds, validates, schedules, and dynamically modifies DAG execution graphs for complex multi-step tasks.
Decision Points
1. When to decompose a task into DAG nodes
Problem complexity assessment:
├── Single coherent output from one skill → No DAG needed (use direct skill)
├── 2-3 sequential steps, linear dependency → Simple pipeline (3-5 nodes)
├── Multiple parallel paths with convergence → Complex DAG (5-15 nodes)
└── Unclear requirements or multiple approaches → Start with vague nodes, refine later
2. Choosing node types by certainty level
Node type decision tree:
├── If task is well-defined with known skills → agent node
├── If task is unclear but bounded → vague node (refine during execution)
├── If requires human judgment/approval → human-gate node
└── If task needs external system → agent node with tool restrictions
3. Determining granularity (critical decision)
Node size assessment:
├── If completable in 1 LLM call with 1-3 skills → Good granularity
├── If requires 5+ sequential LLM calls → Split into multiple nodes
├── If output is 1-2 simple values → Too granular, merge with parent
└── If node does "everything" → Too coarse, decompose further
4. Handling conflicts and dependencies
Dependency resolution:
├── Data dependency (B needs A's output) → Direct edge A→B
├── Resource conflict (both modify same file) → Serialize into different waves
├── Ordering constraint (B after A for logic) → Add ordering edge A→B
└── Optional dependency (B benefits from A but can run without) → Parallel with optional input
5. Dynamic modification triggers
Modification decision tree:
├── If node repeatedly fails → Replace node (different skill/model/approach)
├── If output quality insufficient → Add quality gate node after current
├── If gap discovered in coverage → Insert new node in dependency chain
├── If path proves unnecessary → Remove node and reconnect edges
└── If multiple approaches needed → Fork into parallel paths, converge later
Failure Modes
Schema Drift
Symptoms: Downstream nodes fail with "missing field" or "unexpected format" errors
Detection: If >50% of nodes in a wave fail with schema violations
Diagnosis: Node output schemas don't match downstream input expectations
Fix: Halt execution, audit all schemas in the dependency chain, add adapter nodes if needed
Circular Dependency Trap
Symptoms: Topological sort fails, no nodes have in_degree=0 after some are processed
Detection: Validation throws CycleError during DAG build phase
: Implicit dependency created a cycle (often through shared resources)
: Trace cycle using Kahn's algorithm state, break weakest dependency (usually resource conflicts)
