Task Dependency Graph for Team Templates

[AntonLi-PM]

RFC: Task Dependency Graph for Team Templates

Summary

This RFC proposes adding explicit task dependency support to ClawTeam's TOML team templates, enabling the spawn scheduler to respect execution order, parallelize independent tasks, and block dependent tasks until prerequisites complete.

The change is backward-compatible: existing templates without dependency fields behave exactly as they do today.

Motivation

Right now, when a leader agent calls clawteam spawn --team my-team, all workers are created at roughly the same time. This works well for tasks that are genuinely independent (e.g., the hedge fund template where each analyst examines a different stock). But many real-world workflows have inherent ordering constraints:

• A frontend engineer can't build UI components until the system architect defines the API contracts.
• An integration tester can't start until both frontend and backend are at least partially working.
• A technical writer shouldn't draft documentation for an API that hasn't been designed yet.

Today, the leader agent handles this implicitly through its own reasoning — it knows it should probably spawn the architect first. But this ordering logic lives entirely inside the LLM's head, which means:

1. It's invisible. You can't inspect or verify the execution plan before it runs.
2. It's inconsistent. Different LLMs (or even the same LLM on different runs) might decompose the same goal differently.
3. It's not portable. You can't encode a proven workflow as a reusable template that guarantees correct ordering.

Making dependencies explicit in the template format solves all three problems without taking autonomy away from the leader — the leader still decides what to do, but the template can encode structural constraints that the leader shouldn't have to re-derive every time.

Proposed Design

Template Schema Changes

Add two optional fields to the [[agents]] table:

[[agents]]
name = "architect"
role = "Design system architecture and define API contracts"
depends_on = []       # runs immediately (same as omitting the field)

[[agents]]
name = "frontend"
role = "Build React frontend based on the architecture"
depends_on = ["architect"]  # waits for architect to finish

[[agents]]
name = "backend"
role = "Implement API backend based on the architecture"
depends_on = ["architect"]  # also waits for architect; runs parallel with frontend

[[agents]]
name = "tester"
role = "Run integration tests across frontend and backend"
depends_on = ["frontend", "backend"]  # waits for BOTH

The depends_on field is a list of agent name strings within the same team. If omitted or empty, the agent has no dependencies and is spawned immediately (preserving current behavior).

Spawn Scheduler

The current spawn logic creates all workers in a loop. The proposed change wraps this in a lightweight DAG scheduler:

1. Parse the template and build an adjacency list from `depends_on` fields.
2. Validate: check for missing references and cycles (fail fast with a clear error).
3. Identify all agents with no dependencies → spawn them as Phase 0.
4. When an agent completes (detected via transport layer status messages),
   check if any blocked agents now have all dependencies satisfied → spawn them.
5. Repeat until all agents have been spawned and completed.

This is essentially a topological sort with phased execution — nothing exotic. The key constraint is that it needs to hook into the existing transport layer to detect worker completion, which aligns well with the transport abstraction work planned for v0.3.

Interaction with Leader Agent

An important design question: should the leader be required to follow the DAG, or should it be advisory?

I'd argue for required by default, with an override flag. If someone took the time to encode dependencies in a template, they probably want them enforced. But for exploratory work, the leader should be able to bypass them:

# Normal: respect dependencies
clawteam spawn --team fullstack-dev

# Override: spawn everything immediately (current behavior)
clawteam spawn --team fullstack-dev --ignore-deps

Visualization (Optional, But Valuable)

Once tasks have explicit dependencies, we can trivially generate a preview:

$ clawteam preview --team fullstack-dev

Task Execution Plan:
  Phase 0: architect
  Phase 1: frontend, backend  (parallel)
  Phase 2: tester
  Phase 3: deployer

Dependencies:
  architect ─┬─→ frontend ──┬─→ tester ──→ deployer
              └─→ backend  ──┘

This could be a simple CLI output — no need for a graphical UI at this stage. Just knowing the execution order before committing would be a significant UX improvement.

Prior Art

Several multi-agent frameworks have explored dependency-aware scheduling:

• MetaGPT uses a role-based pipeline where each role subscribes to specific message types, creating implicit ordering. This works but makes the dependency graph hard to reason about from outside the code.
• ChatDev follows a fixed waterfall of phases (design → coding → testing → review). Ordering is built into the framework itself, not configurable per-project.
• MASFactory (arXiv 2603.06007) models workflows as directed computation graphs where nodes are agents/tools and edges encode data dependencies. Their "Vibe Graphing" approach compiles natural language into these graphs. The graph-as-workflow idea is sound, though their implementation targets a different execution model (in-process LLM agents rather than CLI processes).
• Airflow / Prefect / Dagster — the data engineering world solved DAG scheduling years ago. We don't need to reinvent their scheduling algorithms, just adapt the core idea (dependency declaration + topological execution) to ClawTeam's process-based model.

The common pattern across all of these: explicit dependency declaration leads to better reproducibility and debuggability. The specific mechanism varies, but the principle is consistent.

Alternatives Considered

1. Let the LLM figure it out (status quo)

This is what we do today. It works surprisingly well for simple tasks, but breaks down when:

• The task has 5+ agents with non-obvious dependencies
• You need reproducible execution order across runs
• You want to hand off a workflow to someone who didn't write the original prompt

Not proposing we remove this capability — it should remain the default for ad-hoc tasks. But templates should support something more structured.

2. Full DAG engine with conditional branching and loops

We could build a complete workflow engine with conditionals (if agent_a.output contains "error" then skip agent_b) and loops (retry agent_c up to 3 times). This would be powerful but:

• Significantly more complex to implement and test
• Requires a DSL or expression language in TOML, which gets ugly fast
• Probably overkill for v0.3; better to start with simple dependencies and extend later

3. Priority-based ordering instead of explicit dependencies

Instead of depends_on, we could add a priority integer field where lower numbers run first:

[[agents]]
name = "architect"
priority = 1

[[agents]]
name = "frontend"
priority = 2

This is simpler but less expressive — you can't say "frontend depends on architect but NOT on backend." Priority ordering also can't express parallelism within the same priority level (do agents with priority=2 run in parallel or sequentially?). Dependencies are more explicit and avoid these ambiguities.

Implementation Plan

Phase 1: Schema + Validation (small, safe PR)

• Add depends_on as an optional field in the Pydantic model for team templates
• Add validation: check for unknown agent references and cycle detection
• Unit tests for validation logic
• No behavior change — just parsing and validating

Phase 2: Phased Spawn Scheduler

• Implement topological sort for spawn ordering
• Hook into transport layer for completion detection
• Add --ignore-deps flag
• Integration tests with a multi-phase template

Phase 3: Preview Command

• clawteam preview --team <name> outputs execution plan
• ASCII visualization of the dependency graph
• Estimated phase count and parallelism

Open Questions

1. How should we detect agent completion? The transport layer currently supports message passing, but does it have a reliable "I'm done" signal? This might need to be addressed as part of the v0.3 transport abstraction.

2. What happens if a dependency fails? Options: (a) abort all downstream agents, (b) spawn them anyway with a warning, (c) let the leader decide. I'd lean toward (a) with an override flag, but this deserves discussion.

3. Should depends_on support external dependencies? For example, "wait for this file to exist" or "wait for this API to respond." Probably out of scope for now, but worth considering for the future.

---

I'm happy to start with a Phase 1 PR (schema + validation) if this direction makes sense. Would be great to hear thoughts from maintainers on the completion detection question in particular.

[ChonSong]

test

[ChonSong]

ADR-001: Runtime Task Cascade (complement to RFC #57)

RFC #57 addresses spawn-time dependency via depends_on in templates. ADR-001 addresses runtime cascade: when a task completes, auto-unblock tasks that had it as their sole blocked_by.

The Gap

RFC #57 Phase 2: When an agent completes, check if blocked agents can now be spawned.
ADR-001: When a task transitions to completed, automatically unblock any task with it as its sole blocked_by.

These are complementary - RFC #57 covers spawn-time dependency graph for agent orchestration; ADR-001 covers runtime cascade for task-level work items within a team.

ADR-001 Summary

Core behavior: When Task A completes, any task B with blocked_by=[A] automatically gets status=pending if it has no other remaining blockers.

Integration point: TaskWaiter.wait() - the existing poll loop already checks task status. Add _cascade_unblock() there.

Config:
[cascade]
enabled = true # default: false
notify = true # default: false

Proposal

Align ADR-001 with RFC #57 Phase 2 (Phased Spawn Scheduler), since both need to detect agent/task completion:

1. ADR-001 _cascade_unblock() as the mechanism RFC Task Dependency Graph for Team Templates #57 spawn scheduler calls on agent completion
2. Keeps cascade logic isolated and testable while giving RFC Task Dependency Graph for Team Templates #57 a reusable primitive

Questions for Maintainers

1. Is there an existing hook in the transport layer that fires on agent completion? ADR-001 could subscribe rather than poll.
2. Should cascade respect the depends_on graph from team templates, or operate independently on the task store?

Happy to submit a PR for ADR-001 as a follow-up to RFC #57 Phase 1 (schema + validation).