DAG Orchestrator
Transforms natural-language tasks into proposed agent graphs and execution contracts. Use Orchestration Authority and Lifecycle: a graph is not a running system, and a controller must not claim dispatch, cancellation, join, or effect semantics without receipts from its executor.
Decision Points
1. Initial Decomposition Strategy
flowchart TD
A[Task contract] --> B[Name outputs, authority, acceptance, and effects]
B --> F{Requirements or authority unresolved?}
F -->|Yes| G[Halt for clarification or research]
F -->|No| C{Artifacts become independent after declared prerequisites?}
C -->|Yes| D[Propose parallel siblings after prerequisites with join and merge rules]
C -->|No| E[Propose ordered prerequisites]
2. AND vs OR Composition Logic
flowchart LR
A[Parent acceptance condition] --> B{All child receipts required?}
B -->|Yes| C[AND join with failure policy]
B -->|No| D{Any child may satisfy a stated criterion?}
D -->|Yes| E[OR join with independent evaluator]
D -->|No| F[Declare mixed/fallback semantics and effect containment]
3. Max Depth Calibration
flowchart TD
A[Proposed decomposition] --> B{Each leaf has bounded artifact and acceptance test?}
B -->|No| C[Refine or request missing contract]
B -->|Yes| D{Depth or fan-out exceeds local resource policy?}
D -->|Yes| E[Split into phases with revisioned handoff]
D -->|No| F[Retain explicit graph]
4. Parallelization Safety Check
flowchart LR
A[Candidate parallel wave] --> B[Check files, mutable resources, authority, and external effects]
B --> C{Shared scarce or mutable boundary?}
C -->|Yes| D[Serialize or grant a scoped lease]
C -->|No| E[Parallel proposal with cancellation and join policy]
5. Failure Recovery Strategy
flowchart TD
A[Executor receipt or timeout] --> B{Effect and completion state known?}
B -->|No| C[Contain or cancel future work; reconcile before retry or dependent release]
B -->|Yes| D{Acceptance condition satisfied?}
D -->|Yes| E[Release dependents under declared policy]
D -->|No| F[Contain dependents, propose revision, or escalate]
Failure Modes
Schema Bloat
Symptoms: DAG scope prevents clear ownership, contracts, or join semantics under its declared resource policy
Detection: A graph cannot state bounded artifacts, contracts, ownership, or join rules under its local resource policy
Fix: Split into revisioned phases or reduce scope; node count and estimates are planning inputs, not universal limits.
Circular Dependencies
Symptoms: Topological sort fails, "cyclic dependency" error in wave computation
Detection: Compare the processed-node count from Kahn's algorithm with the total node count, or retain a DFS back-edge witness; an acyclic prefix can exist before a cycle.
Fix: Preserve the cycle witness and ask the contract owner to revise the dependency or decompose an explicit intermediate artifact. Never delete an edge merely to make a sort succeed.
Premature Parallelization
Symptoms: File conflicts, race conditions, inconsistent final state
Detection: if conflictingFiles.length > 0 || inconsistentOutputs
Fix: Add explicit dependencies, use sequential waves for conflicting operations
Infinite Decomposition
Symptoms: Depth keeps increasing, same task fails repeatedly at leaf level
Detection: A decomposition repeats the same unresolved obligation without a changed contract or evidence
Fix: Halt and request a new requirement, capability, or human decision rather than expanding depth by rule.
Context Loss Cascade
Symptoms: Later waves fail due to missing information from earlier waves
Detection: if waveN.inputs.missing.length > 0
Fix: Ensure explicit context passing between waves, add context aggregation nodes
Worked Examples
Example: "Build authentication system for web app"
Initial Assessment: This is an illustrative authentication contract. Propose a revisioned graph only after naming its acceptance tests, credential/effect policy, and diagnosed component complexity.
Wave 0 Decomposition:
// Initial breakdown
subtasks = [
"Design user data schema", // skill: database-architect
"Specify authentication acceptance tests", // skill: test-engineer
"Create login/signup API candidate", // skill: api-architect
"Build frontend auth candidate", // skill: react-developer
"Propose credential-policy candidate" // skill: security-engineer
]
Dependency Analysis:
- The illustrative data, credential and effect contracts are prerequisites for the acceptance fixtures.
- The acceptance-test specification is a prerequisite for implementation candidates; executed evidence is evaluated before artifacts are accepted.
- API and frontend candidates may run after the frozen interface and fixtures only when their shared resources and effects have a valid coordination policy; their combined artifact is checked before acceptance.
Illustrative dependency and acceptance graph:
flowchart TD
C[Define data, credential, and effect contracts] --> T[Specify acceptance fixtures]
T --> A[Implement API candidate]
T --> F[Implement frontend candidate against frozen interface]
A --> J[Join compatible artifacts with attributed receipts]
F --> J
J --> R[Run component and integration checks]
R --> X{All declared acceptance conditions established?}
X -->|Yes| D[Accept artifacts under the named policy]
X -->|No or unknown| E[Preserve findings and revise or escalate]
Execution with Failure:
// An observed failure alone does not establish that decomposition is appropriate.
if (failureDiagnosis.complexityEvidence && effectStatus === "reconciled") {
// Propose a revision after the task owner confirms the diagnosed complexity,
// revised graph, authority, and acceptance checks.
const apiSubtasks = [
"Define authentication routes",
"Implement password hashing",
"Add session management",
"Create user CRUD operations"
];
// A separate runner may execute the approved revision and emit receipts.
}
Expert vs Novice:
- Novice: Assumes a familiar component order proves safe execution.
- Expert: Names the local contract, verifies prerequisites and effects, evaluates acceptance evidence before release, and revises only from a diagnosed condition.
Quality Gates
NOT-FOR Boundaries
Don't use DAG Orchestrator for:
- Single-skill tasks → Use direct skill invocation
- Simple workflows whose artifacts, authority, and acceptance can be stated directly → use sequential task calls
- Real-time interactive tasks → Use conversational agents instead
- Tasks requiring human creativity/judgment → Use human-in-loop workflows
- Debugging/troubleshooting → Use diagnostic-specialist skill
- Data analysis/visualization → Use data-analyst skill
Delegate instead:
- Code reviews → Use code-reviewer skill
- Writing/editing → Use copywriter or technical-writer
- Research synthesis → Use research-synthesizer skill
- UI/UX design → Use ui-ux-designer skill