dag-graph-builder

1. Problem Decomposition

• Analyze complex requests to identify atomic subtasks
• Recognize natural boundaries between independent work streams
• Identify dependencies and data flow requirements
• Determine optimal granularity for parallelization

2. Node Creation

• Create DAG nodes with clear input/output specifications
• Assign appropriate node types (skill, agent, mcp-tool, composite, conditional)
• Define timeout, retry, and resource limit configurations
• Ensure nodes are self-contained and independently testable

3. Dependency Mapping

• Identify explicit dependencies (output → input)
• Recognize implicit dependencies (shared resources, ordering)
• Detect potential deadlock patterns
• Map critical paths through the graph

```typescript

interface DAGNode {

id: NodeId;

type: 'skill' | 'agent' | 'mcp-tool' | 'composite' | 'conditional';

skillId?: string; // For skill nodes

agentDefinition?: object; // For agent nodes

mcpTool?: string; // For mcp-tool nodes

dependencies: NodeId[]; // Nodes that must complete first

inputMappings: InputMapping[];

config: TaskConfig;

}

```

Pattern 1: Fan-Out (Parallel Branches)

```

┌── Node B ──┐

Node A ├── Node C ──┼── Node F

└── Node D ──┘

```

Use when: Multiple independent operations can occur after a shared prerequisite.

Pattern 2: Fan-In (Aggregation)

```

Node A ──┐

Node B ──┼── Node D (aggregator)

Node C ──┘

```

Use when: Multiple outputs need to be combined or synthesized.

Pattern 3: Diamond (Diverge-Converge)

```

┌── Node B ──┐

Node A ┤ ├── Node D

└── Node C ──┘

```

Use when: A single input needs parallel processing with unified output.

Pattern 4: Pipeline (Sequential)

```

Node A → Node B → Node C → Node D

```

Use when: Each step must complete before the next can begin.

Pattern 5: Conditional Branching

```

┌── Node B (condition=true)

Node A ──┤

└── Node C (condition=false)

```

Use when: Different paths based on runtime conditions.

Step 1: Understand the Goal

• What is the final deliverable?
• What are the constraints (time, resources, quality)?
• Are there any hard dependencies on external systems?

Step 2: Identify Work Streams

• What can be done independently?
• What requires sequential processing?
• Where are the natural parallelization boundaries?

Step 3: Create Node Specifications

For each node, define:

• ID: Unique identifier (e.g., validate-input, fetch-data)
• Type: skill, agent, mcp-tool, composite, conditional
• SkillId: Which skill should execute this node
• Dependencies: Which nodes must complete first
• Inputs: What data this node needs
• Outputs: What data this node produces
• Config: Timeout, retries, resource limits

Step 4: Validate Graph Structure

• Ensure no cycles exist (DAG property)
• Verify all dependencies are defined
• Check input/output compatibility between nodes
• Identify and document the critical path

When building a DAG, output in this format:

```yaml

dag:

id:

name:

description:

nodes:

- id: node-1

type: skill

skillId:

dependencies: []

config:

timeoutMs: 30000

maxRetries: 3

- id: node-2

type: skill

skillId:

dependencies: [node-1]

inputMappings:

- from: node-1.output.data

to: input.data

config:

maxParallelism: 3

defaultTimeout: 30000

errorHandling: stop-on-failure

```

Request: "Research a topic, analyze findings, and produce a report"

Built DAG:

```yaml

dag:

id: research-analysis-pipeline

name: Research and Analysis Pipeline

nodes:

- id: gather-sources

type: skill

skillId: research-analyst

dependencies: []

- id: validate-sources

type: skill

skillId: dag-output-validator

dependencies: [gather-sources]

- id: extract-key-points

type: skill

skillId: research-analyst

dependencies: [validate-sources]

- id: identify-patterns

type: skill

skillId: dag-pattern-learner

dependencies: [extract-key-points]

- id: generate-insights

type: skill

skillId: research-analyst

dependencies: [extract-key-points, identify-patterns]

- id: format-report

type: skill

skillId: technical-writer

dependencies: [generate-insights]

config:

maxParallelism: 2

defaultTimeout: 60000

errorHandling: retry-then-skip

```

1. Maximize Parallelism: Structure graphs to allow concurrent execution
2. Minimize Node Size: Smaller nodes = better parallelization
3. Clear Dependencies: Explicit is better than implicit
4. Defensive Configuration: Set appropriate timeouts and retries
5. Document Critical Paths: Identify bottlenecks early

After building the graph:

1. Pass to dag-dependency-resolver for validation and topological sort
2. Use dag-semantic-matcher to assign skills to nodes if needed
3. Hand off to dag-task-scheduler for execution planning

---

Transform chaos into structure. Build graphs that flow.