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

# .claude/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: haiku
    prompt: "Analyze codebase for integration points"

  - id: implement
    agent: lang-typescript-expert
    model: sonnet
    prompt: "Implement the feature"
    depends_on: [analyze]

  - id: test
    agent: qa-engineer
    model: sonnet
    prompt: "Write and run tests"
    depends_on: [implement]

  - id: review
    agent: lang-typescript-expert
    model: opus
    prompt: "Code review"
    depends_on: [implement]

  - id: docs
    agent: arch-documenter
    model: sonnet
    prompt: "Update documentation"
    depends_on: [implement]

  - id: commit
    agent: mgr-gitnerd
    model: sonnet
    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 Task tool (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)

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 Task tool call to specified agent
State tracking	/tmp/.claude-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:haiku)
2. implement (lang-typescript-expert:sonnet) ← depends: 1
3. test (qa-engineer:sonnet) ← depends: 2
4. review (lang-typescript-expert:opus) ← depends: 2
5. commit (mgr-gitnerd:sonnet) ← 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 상태는 tracker-checkpoint 에이전트로 위임됩니다.

Flow

1. Pipeline 시작 → orchestrator가 tracker-checkpoint 호출 → 초기 state 파일 생성 (/tmp/.claude-pipeline-{name}-{PPID}.json)
2. 각 step 후 → tracker-checkpoint가 state 업데이트 (atomic write)
3. step 실패 → tracker-checkpoint가 halted 상태로 freeze
4. /pipeline resume → tracker-checkpoint가 state 로드 → orchestrator에 복원 옵션 제공

Integration

• PPID-scoped state file 경로: /tmp/.claude-pipeline-{name}-{PPID}.json
• step 실행 전후로 tracker-checkpoint delegation
• resume 시 checkpoint → dag 재빌드 → 미완료 step부터 재개

See .claude/agents/tracker-checkpoint.md for agent spec.

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.