dag-orchestration

name	dag-orchestration
description	YAML-based DAG workflow engine with topological execution and failure strategies
scope	core
context	fork
user-invocable	false

DAG Orchestration Skill

Defines and executes directed acyclic graph (DAG) workflows. The orchestrator uses this skill to plan multi-step tasks with dependencies, execute them in topologically-sorted order, and handle failures.

Orchestrator-only — only the main conversation uses this skill (R010). Subagents execute individual nodes.

Workflow Spec Format

# .codex/workflows/<name>.yaml or inline in conversation
workflow:
  name: feature-implementation
  description: Implement a new feature with tests and docs

nodes:
  - id: analyze
    agent: Explore
    model_lane: spark
    model_reasoning_effort: low
    prompt: "Analyze codebase for integration points"

  - id: implement
    agent: lang-typescript-expert
    model_lane: frontier
    model_reasoning_effort: medium
    prompt: "Implement the feature"
    depends_on: [analyze]

  - id: test
    agent: qa-engineer
    model_lane: frontier
    model_reasoning_effort: medium
    prompt: "Write and run tests"
    depends_on: [implement]

  - id: review
    agent: lang-typescript-expert
    model_lane: frontier
    model_reasoning_effort: high
    prompt: "Code review"
    depends_on: [implement]

  - id: docs
    agent: arch-documenter
    model_lane: frontier
    model_reasoning_effort: medium
    prompt: "Update documentation"
    depends_on: [implement]

  - id: commit
    agent: mgr-gitnerd
    model_lane: frontier
    model_reasoning_effort: medium
    prompt: "Commit changes"
    depends_on: [test, review, docs]

config:
  max_parallel: 4          # R009 soft default (hard cap: 5)
  failure_strategy: stop   # stop | skip | retry
  retry_count: 2           # Max retries per node (if strategy=retry)
  timeout_per_node: 300    # Seconds per node (0 = no limit)

Execution Algorithm — Kahn's Topological Sort

1. Parse workflow YAML
2. Build adjacency list and in-degree map
3. Validate: detect cycles (error if found)
4. Initialize queue with nodes where in-degree = 0
5. While queue is not empty:
   a. Dequeue up to max_parallel nodes
   b. Execute nodes in parallel via Codex native subagents (R009)
   c. On completion:
      - Success → decrement in-degree of dependents
      - Failure → apply failure_strategy
   d. Stall check:
      - If running node duration > 2x average completed duration
      - AND pending nodes exist with in-degree = 0 (ignoring stalled node's edges)
      - THEN enqueue those independent nodes immediately (adaptive split)
   e. Enqueue newly-ready nodes (in-degree = 0)
6. Verify all nodes executed (detect unreachable nodes)

Sensitive-Path Delegation

Sensitive-path compatibility note: if this skill delegates work that touches .claude/**, .claude/outputs/**, templates/.claude/**, or read-only measurements of those paths, keep .codex/** edits on the normal Codex path. On Claude Code v2.1.121+ with bypassPermissions, direct writes to .claude/skills/, .claude/agents/, and .claude/commands/ are allowed; on v2.1.126+ that extends to broader protected paths. Only use /tmp/{skill}-{timestamp}.md as a legacy fallback when the target runtime is older or still prompts.

Execution Rules

Rule	Detail
Max parallel	5 concurrent nodes max, 4 default (R009)
Agent Teams gate	3+ parallel nodes → check R018 eligibility
Orchestrator only	DAG scheduling runs in main conversation (R010)
Node execution	Each node = one Codex native subagent task to specified role
State tracking	/tmp/.codex-dag-$PPID.json
Stall detection	Running node > 2x avg completed duration → enqueue independent pending nodes early

Failure Strategies

Strategy	Behavior
stop	Halt entire DAG on first failure (default)
skip	Mark failed node as skipped, continue dependents with warning
retry	Retry failed node up to retry_count times, then stop

State File Format

{
  "workflow": "feature-implementation",
  "started_at": "2026-03-07T10:00:00Z",
  "status": "running",
  "nodes": {
    "analyze": {"status": "completed", "started": "...", "completed": "..."},
    "implement": {"status": "running", "started": "..."},
    "test": {"status": "pending"},
    "review": {"status": "pending"},
    "docs": {"status": "pending"},
    "commit": {"status": "blocked", "blocked_by": ["test", "review", "docs"]}
  },
  "execution_order": [["analyze"], ["implement"], ["test", "review", "docs"], ["commit"]]
}

Display Format

[DAG] feature-implementation — 6 nodes
[Layer 0] analyze ← running
[Layer 1] implement ← pending (depends: analyze)
[Layer 2] test, review, docs ← pending (parallel, depends: implement)
[Layer 3] commit ← blocked (depends: test, review, docs)

Progress:

[DAG Progress] 3/6 nodes completed
  ✓ analyze (12s)
  ✓ implement (45s)
  → test (running)
  → review (running)
  → docs (running)
  ○ commit (blocked)

Common Workflow Templates

Feature Implementation

nodes: [analyze → implement → [test, review, docs] → commit]

Code Review + Fix

nodes: [review → fix → re-review → commit]
failure_strategy: retry

Multi-Language Project

nodes: [
  analyze → [impl-frontend, impl-backend, impl-db] → integration-test → commit
]

Refactoring

nodes: [
  analyze → plan → [refactor-1, refactor-2, refactor-3] → test → review → commit
]

Integration

Rule	Integration
R009	Max 4 parallel nodes; independent nodes MUST parallelize
R010	DAG scheduler runs only in orchestrator
R015	Display DAG plan before execution
R018	3+ parallel nodes → check Agent Teams eligibility
model-escalation	Node failures feed into task-outcome-recorder
stuck-recovery	Repeated node failures trigger stuck detection

Inline DAG

For ad-hoc workflows without a YAML file:

[DAG Plan]
1. analyze (Explore:spark/low)
2. implement (lang-typescript-expert:frontier/medium) ← depends: 1
3. test (qa-engineer:frontier/medium) ← depends: 2
4. review (lang-typescript-expert:frontier/high) ← depends: 2
5. commit (mgr-gitnerd:frontier/medium) ← depends: 3, 4

Execute? [Y/n]

The orchestrator builds the DAG from this inline format and executes using the same algorithm.

State Management via tracker-checkpoint

Pipeline and DAG state is delegated to the tracker-checkpoint agent.

Flow

1. Pipeline start: orchestrator delegates to tracker-checkpoint to create an initial state file (/tmp/.codex-pipeline-{name}-{PPID}.json)
2. After each step: tracker-checkpoint updates step state with atomic writes
3. Step failure: tracker-checkpoint freezes the state as halted
4. /pipeline resume: tracker-checkpoint loads state and returns restore options to the orchestrator

Integration

• PPID-scoped pipeline state path: /tmp/.codex-pipeline-{name}-{PPID}.json
• PPID-scoped DAG state path: /tmp/.codex-dag-{PPID}.json
• Delegate before and after step execution when resume support is required
• On resume, rebuild the DAG from checkpoint state and continue from incomplete steps

See .codex/agents/tracker-checkpoint.md for the agent contract.

Limitations

• No cycles allowed (DAG = acyclic)
• Max 20 nodes per workflow (complexity guard)
• Nested DAGs not supported (flatten instead)
• Cross-workflow dependencies not supported

External References

Multica — Managed Agent Platform

Reference: Multica — managed agent platform for Claude Code/Codex. Verdict: INTEGRATE (external reference, not internalize)

Multica's task lifecycle pattern (enqueue → claim → start → complete/fail) is a useful reference for DAG node state management:

Multica State	DAG Equivalent	Notes
enqueue	pending	Node waiting for dependencies
claim	ready	Dependencies resolved, ready to execute
start	running	Agent spawned and executing
complete	completed	Node finished successfully
fail	failed	Node execution failed

Consider this pattern when extending DAG node state tracking or implementing retry logic.