4. Task Board and Dependencies

Description

You already have a team lead that coordinates and teammates that execute. But how does the team lead know which tasks exist, in what order to run them, and what depends on what? Without a task board, the team lead improvises — it assigns tasks in the order that seems logical, hopes the dependencies get resolved by chance, and has no way to report the team's status. That's exactly the manual coordination we wanted to move past.

The task board is the structure that connects the team lead to the work. It's a list of tasks with states (pending, in-progress, done, blocked), assignments (which teammate does what), dependencies (which task requires another to finish first), and priorities (what to do first when there are no dependencies). The team lead consults the task board to decide what to launch, and updates it when a teammate reports results.

In this capsule you'll learn to design task boards in the team lead's system prompt, to declare dependencies between tasks, to handle priorities, and to understand what happens when a dependency isn't met. The task board is the heart of Agent Teams — without it, you have a team lead with teammates but no plan.

⚠️ EXPERIMENTAL FEATURE

The task board implementation in Agent Teams may vary between versions of Claude Code. The concept of a task board as a coordination structure is stable and transferable. The capsule teaches the pattern regardless of the specific API.

Last check: March 2026

The Task Board: Mental Model

Think kanban

The task board works like a kanban board with automatic assignment:

BACKLOG              IN PROGRESS          DONE
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ T1: Schema  │  ──→ │ T2: GET API │  ──→ │             │
│ T3: PUT API │      │ (backend)   │      │             │
│ T4: UI Page │      └─────────────┘      │             │
│ T5: UI Form │                           │             │
│ T6: Review  │      BLOCKED              │             │
└─────────────┘      ┌─────────────┐      │             │
                     │ T4: UI Page │      │             │
                     │ waits for   │      │             │
                     │ T2          │      │             │
                     └─────────────┘      └─────────────┘

The team lead moves the cards. When T2 goes to DONE, it checks which blocked tasks get unblocked (T4 was waiting for T2) and moves them to IN PROGRESS, assigning them to the appropriate teammate.

The 5 states of a task

PENDING       → Not started, no blocking dependencies
BLOCKED       → Not started, waiting for dependencies to finish
IN_PROGRESS   → Assigned to a teammate, running
DONE          → Completed successfully
FAILED        → Failed, needs a retry or reassignment

The normal flow is: PENDING → IN_PROGRESS → DONE

With dependencies: BLOCKED → PENDING (when deps finish) → IN_PROGRESS → DONE

With failure: IN_PROGRESS → FAILED → (retry) → IN_PROGRESS → DONE

Declaring the Task Board in the System Prompt

The basic structure

The task board is defined in the team lead's system prompt as a table or structured list:

## Task Board

When you receive a request, break it into tasks using this format:

| ID | Task | Assigned To | Depends On | Priority | Status |
|----|------|-------------|------------|----------|--------|
| T1 | Define data schema | backend-agent | none | HIGH | PENDING |
| T2 | GET /profile endpoint | backend-agent | T1 | HIGH | BLOCKED |
| T3 | PUT /profile endpoint | backend-agent | T1 | MEDIUM | BLOCKED |
| T4 | ProfilePage component | frontend-agent | T2 | MEDIUM | BLOCKED |
| T5 | ProfileForm component | frontend-agent | T3, T4 | MEDIUM | BLOCKED |
| T6 | Integration review | team-lead | T2, T3, T4, T5 | LOW | BLOCKED |

Task board fields

ID — Short identifier (T1, T2, ...). The team lead and the teammates refer to tasks by ID.

Task — A concrete description of what to do. Not "frontend stuff" — "Create ProfilePage component that displays user data from GET /profile."

Assigned To — Which teammate will execute the task. The team lead assigns based on the teammates' descriptions.

Depends On — IDs of tasks that must be completed first. T4 depends on T2 means T4 can't start until T2 is DONE.

Priority — HIGH, MEDIUM, LOW. When two tasks are ready (no blocking dependencies), the higher-priority one runs first.

Status — The current state of the task.

Dependencies: The Heart of the Task Board

Types of dependencies

1. Direct dependency (A → B):

T1: Define schema    →    T2: Create endpoint (uses the schema)

T2 can't start without T1 because it needs the schema defined.

2. Multiple dependency (A, B → C):

T2: GET endpoint  ─┐
                    ├──→  T5: ProfileForm (uses both endpoints)
T3: PUT endpoint  ─┘

T5 requires that BOTH T2 and T3 be complete.

3. Dependency chain (A → B → C):

T1: Schema  →  T2: Endpoint  →  T4: Component  →  T5: Form

T5 depends on T4, which depends on T2, which depends on T1. Modifying T1 can affect the whole chain.

4. Independent parallel dependencies:

T1: Schema  →  T2: GET endpoint
            →  T3: PUT endpoint

T2 and T3 depend on T1 but not on each other — they can run in parallel once T1 is DONE.

Visualizing dependencies as a graph

T1 (Schema)
├──→ T2 (GET /profile)
│    └──→ T4 (ProfilePage)
│         └──→ T5 (ProfileForm) ←─┐
└──→ T3 (PUT /profile) ──────────┘

T6 (Integration review) waits for T2, T3, T4, T5

This graph tells the team lead:

1. Start with T1 (no dependencies)
2. When T1 finishes → launch T2 and T3 in parallel
3. When T2 finishes → launch T4
4. When T3 and T4 finish → launch T5
5. When T2, T3, T4, T5 finish → run T6

Dependency resolution instructions for the team lead

## Dependency Resolution

When processing the task board:

1. SCAN: Find all tasks with status PENDING (no blocked dependencies)
2. PARALLEL: If multiple tasks are PENDING and assigned to different
   teammates, launch them in parallel
3. WAIT: When a teammate completes a task, update status to DONE
4. UNBLOCK: Check all BLOCKED tasks — if all their dependencies
   are now DONE, change status to PENDING
5. ASSIGN: Pick the highest-priority PENDING task and assign it
6. REPEAT until all tasks are DONE or FAILED

### Dependency Rules
- NEVER assign a BLOCKED task
- When a task becomes PENDING, assign it immediately if its
  teammate is idle
- If a task's dependency FAILED, mark the task as BLOCKED with
  reason: "dependency T[x] failed"
- Maximum dependency chain depth: 5 (if deeper, flag for review)

Prioritization: What to Do First

When priority matters

Priority only matters when there are multiple PENDING tasks (no blocking dependencies) and you have to decide which one to run first. If there's only one PENDING task, there's no decision.

Priority system

## Priority System

HIGH:   Critical path — other tasks depend on this
MEDIUM: Important but won't block other tasks
LOW:    Nice to have, can be skipped if time is limited

When two tasks have the same priority:
1. Prefer the one that unblocks more downstream tasks
2. Prefer the one assigned to an idle teammate
3. If still tied, prefer the lower task ID (T2 before T3)

Prioritization example

Current state of the task board:

| ID | Task | Depends On | Priority | Status |
|----|------|------------|----------|--------|
| T2 | GET endpoint | T1 ✅ | HIGH | PENDING |
| T3 | PUT endpoint | T1 ✅ | MEDIUM | PENDING |
| T4 | Logging setup | none | LOW | PENDING |

Team lead's decision:
1. T2 (HIGH, unblocks T4→T5) → assign to backend-agent
2. T3 (MEDIUM, unblocks T5) → assign to backend-agent in parallel if possible
3. T4 (LOW, unblocks nothing) → assign only if there's an idle teammate

Creating the Task Board Dynamically

The team lead generates the task board

In practice, the team lead doesn't receive a pre-defined task board — it generates one when it receives a request:

## Task Board Generation

When you receive a user request:

1. ANALYZE: Read the codebase to understand current state
2. DECOMPOSE: Break the request into 4-8 specific tasks
3. ASSIGN: Match each task to the best teammate
4. DEPENDENCIES: Identify which tasks depend on others
5. PRIORITIZE: Set priority based on critical path
6. PRESENT: Show the task board to the user before executing

### Decomposition Rules
- Each task should be completable in 1-5 files
- Each task should have a single clear deliverable
- Tasks should be assigned to a single teammate
- If a task is too large, split it
- If a task is trivial (1 line change), merge it with another

### Presenting the Task Board
Before executing, show:

📋 Task Board for: [request summary]

Dependency graph: T1 → T2 → T4 → T3 → T5

Ready to execute? [Proceed / Modify]

This gives the user visibility and the chance to adjust before the team starts executing.

What Happens When a Dependency Isn't Met

Scenario: a teammate fails

T1: Schema      → DONE ✅
T2: GET endpoint → FAILED ❌  (backend-agent reported an error)
T4: ProfilePage  → BLOCKED 🔒 (depends on T2)

The team lead has several options:

Option 1: Retry — Reassign T2 to the same teammate with the error information:

When a task FAILS:
1. Read the teammate's error report
2. If the error is recoverable (wrong approach, missing context):
   - Provide additional context and retry
   - Maximum 2 retries per task
3. If the error is not recoverable (missing dependency, wrong assignment):
   - Reassign to a different teammate if one is capable
   - If no teammate can handle it, report to user

Option 2: Reassign — If the backend-agent can't resolve the error, try with another teammate (if one has the capability).

Option 3: Escalate — Report to the user that T2 failed, T4 and T5 are blocked, and the team can't continue without intervention.

Scenario: circular dependency

T2 depends on T3
T3 depends on T2

This is a deadlock — no task can start. The team lead must detect it:

## Circular Dependency Detection

Before starting execution:
1. Trace each dependency chain to verify it terminates
2. If task A depends on B and B depends on A (directly or
   indirectly), STOP and report:
   "Circular dependency detected: T2 ↔ T3. Cannot proceed.
    Suggest: remove one dependency or merge tasks."

Scenario: partially met dependency

T5 depends on T3 (DONE ✅) and T4 (PARTIAL ⚠️)

T4 was completed partially — the frontend-agent created the component but couldn't implement a prop because it was missing a type. Does it launch T5?

## Partial Completion Handling

If a dependency task reports PARTIAL:
1. Read what was completed and what's missing
2. If T5 can proceed with what's available, unblock T5
3. If T5 needs the missing parts, keep T5 BLOCKED
4. Create a new task (T4b) for the missing parts
5. Update T5's dependencies: depends on T3, T4b

Task Board Patterns

Pattern: Linear pipeline

T1 → T2 → T3 → T4

Each task depends on the previous one. Simple but slow — no parallelism.

Use: When each step needs the complete output of the previous one
Example: Schema → Migration → Endpoint → Tests

Pattern: Fan-out / Fan-in

      ┌→ T2 ─┐
T1 ──┤       ├──→ T5
      └→ T3 ─┤
      └→ T4 ─┘

T1 produces a result. T2, T3, T4 work in parallel on different aspects. T5 integrates the results.

Use: When the work can be split into independent parts
Example: Schema → (GET endpoint || PUT endpoint || DELETE endpoint) → Tests

Pattern: Diamond

T1 ──→ T2 ──→ T4
  └──→ T3 ──┘

T2 and T3 depend on T1 and run in parallel. T4 depends on both.

Use: Frontend and backend work in parallel after a design phase
Example: Design → (Frontend || Backend) → Integration

Pattern: Staged pipeline

Stage 1:  T1
Stage 2:  T2, T3     (parallel, both depend on T1)
Stage 3:  T4, T5     (parallel, T4 dep T2, T5 dep T3)
Stage 4:  T6         (depends on T4, T5)

Multiple stages, each with parallel tasks.

Use: Large projects with clear development phases
Example: Data models → (API + UI skeleton) → (API logic + UI components) → Integration

Manual Alternative: Task Board Without Agent Teams

If Agent Teams isn't available, implement the task board in the coordinator's system prompt:

---
name: coordinator
tools: Agent(frontend-agent), Agent(backend-agent), Read, Glob, Grep
model: sonnet
maxTurns: 60
---

## Task Board Management

You maintain a task board mentally. When you receive a request:

1. Generate the task board (list of tasks with dependencies)
2. Show it to the user for approval
3. Execute tasks in dependency order:
   a. Find all tasks with no unmet dependencies
   b. For tasks assigned to different teammates: delegate in parallel
   c. Wait for results
   d. Update statuses and check what's unblocked
   e. Repeat until all tasks are DONE or FAILED

## Status Tracking

After each round, display:

📋 Progress Update T1 [DONE] ✅ — Schema defined T2 [IN_PROGRESS] 🔄 — backend-agent working... T3 [BLOCKED] 🔒 — waiting for T1 T4 [PENDING] ⏳ — ready but teammate busy

## Dependency Check (before each assignment)

For each task to assign:
- List its dependencies
- Verify each dependency is DONE
- If any dependency is not DONE → do NOT assign, mark BLOCKED
- If all dependencies are DONE → assign to teammate

The difference from Agent Teams: here the coordinator keeps the state mentally and reports it in text. With Agent Teams, the task board is a formal structure the team lead manages with system primitives.

Troubleshooting

"The team lead runs tasks without respecting dependencies"

Cause: The dependency resolution instructions aren't explicit, or the team lead doesn't verify before assigning.

Solution: Add an emphatic rule:

CRITICAL RULE: Before assigning ANY task, you MUST:
1. List the task's dependencies by ID
2. Check the status of each dependency
3. If ANY dependency is not DONE, DO NOT assign the task
4. Log: "Task T[x] blocked — waiting for T[y] (status: [status])"

"The team lead creates too many tasks (10+)"

Cause: Excessively granular decomposition.

Solution: Add a sizing rule:

## Task Sizing Rules
- Minimum: 2 files affected per task (if less, merge with adjacent)
- Maximum: 6 files affected per task (if more, split)
- Total tasks: 4-8 for a typical feature request
- If you generate more than 8 tasks, consolidate related ones

"The priorities don't affect the execution order"

Cause: The team lead processes tasks by ID (T1, T2...) instead of by priority.

Solution: Make the priority part of the selection process:

When selecting the next task to assign:
1. Filter: only PENDING tasks (dependencies met)
2. Sort by: Priority (HIGH > MEDIUM > LOW)
3. Break ties by: which task unblocks more downstream tasks
4. Assign the first task in the sorted list

"The task board isn't shown to the user before executing"

Cause: The system prompt doesn't include the presentation step.

Solution: Add a mandatory presentation step:

## Pre-Execution Step (MANDATORY)

After generating the task board and BEFORE executing any task:
1. Display the complete task board to the user
2. Show the dependency graph
3. Ask: "Ready to execute? Say 'proceed' or suggest changes."
4. Only proceed after confirmation

"I can't see the progress while the team executes"

Cause: The team lead doesn't report intermediate progress.

Solution: Add progress reports after each completed task:

After EACH task completion, display:
📋 Progress: [completed]/[total] tasks
- T[x] [DONE] ✅ — [1-line summary]
- T[y] [IN PROGRESS] 🔄 — [teammate] working
- T[z] [UNBLOCKED] → ready to assign

Exercises

Exercise 1: Design a basic task board (Easy)

Given the request "Add a contact page with a form that sends an email," create a task board with 4-5 tasks, assignments to frontend-agent and backend-agent, and dependencies.

| ID | Task | Assigned To | Depends On | Priority | Status |
|----|------|-------------|------------|----------|--------|
| T1 | Create email service in src/services/ | backend-agent | none | HIGH | PENDING |
| T2 | POST /contact endpoint | backend-agent | T1 | HIGH | BLOCKED |
| T3 | ContactPage layout | frontend-agent | none | MEDIUM | PENDING |
| T4 | ContactForm component with validation | frontend-agent | T2, T3 | MEDIUM | BLOCKED |
| T5 | Success/error feedback UI | frontend-agent | T4 | LOW | BLOCKED |

Dependency graph:
T1 → T2 ──→ T4 → T5
T3 ────────┘

Parallel opportunities:
- T1 and T3 can run simultaneously (no dependencies)
- T4 waits for both T2 and T3

Exercise 2: Detect incorrect dependencies (Easy)

This task board has 3 dependency problems. Find them:

| ID | Task | Depends On |
|----|------|------------|
| T1 | Create model | none |
| T2 | Create endpoint | T3 |
| T3 | Create migration | T2 |
| T4 | Write tests | T1 |
| T5 | Deploy | T4 |

| ID | Task | Depends On |
|----|------|------------|
| T1 | Create model | none |
| T3 | Create migration | T1 |
| T2 | Create endpoint | T3 |
| T4 | Write tests | T2 |
| T5 | Deploy | T2, T4 |

Exercise 3: Task board with fan-out/fan-in (Medium)

Design a task board for "Implement a notification system with push, email, and in-app" using the fan-out/fan-in pattern. It should have a design phase, three parallel implementations, and an integration phase.

| ID | Task | Assigned To | Depends On | Priority |
|----|------|-------------|------------|----------|
| T1 | Design notification interface | backend-agent | none | HIGH |
| T2 | Push notification service | backend-agent | T1 | HIGH |
| T3 | Email notification service | backend-agent | T1 | HIGH |
| T4 | In-app notification service | backend-agent | T1 | MEDIUM |
| T5 | Notification preferences UI | frontend-agent | T1 | MEDIUM |
| T6 | Notification center component | frontend-agent | T4 | MEDIUM |
| T7 | Integration: unified send API | backend-agent | T2, T3, T4 | HIGH |
| T8 | E2E test all channels | team-lead | T6, T7 | LOW |

Graph:
         ┌→ T2 (push) ────────┐
T1 ──────┤→ T3 (email) ───────├──→ T7 (unified API) → T8
         ├→ T4 (in-app) ──┬───┘                        ↑
         └→ T5 (prefs UI) │                             │
                           └→ T6 (notification center) ─┘

Parallelism:
- Stage 1: T1
- Stage 2: T2, T3, T4, T5 (all parallel)
- Stage 3: T6 (after T4), T7 (after T2, T3, T4)
- Stage 4: T8 (after T6, T7)

Exercise 4: Handling a chain failure (Medium)

T1 → T2 → T4 → T5, and T2 fails. Write the step-by-step instructions the team lead should follow. Include: what to do with T4 and T5, when to retry, and when to escalate to the user.

## When T2 FAILS:

### Step 1: Assess the failure
- Read T2's error report
- Classify: recoverable (wrong approach) or blocking (missing resource)

### Step 2: Impact analysis
- T4 depends on T2 → mark T4 as BLOCKED (reason: T2 failed)
- T5 depends on T4 → mark T5 as BLOCKED (reason: T4 blocked)
- No other tasks affected

### Step 3: Recovery attempt
IF recoverable:
  - Provide T2 with error context and additional guidance
  - Retry T2 (attempt 2 of max 2)
  - If retry succeeds → unblock T4 → proceed normally
  - If retry fails → go to Step 4

IF blocking:
  - Go to Step 4

### Step 4: Escalation
Report to user:
"Task T2 (GET /profile endpoint) failed after 2 attempts.
 Error: [error description]
 Impact: T4 (ProfilePage) and T5 (ProfileForm) are blocked.
 Options:
 1. Provide additional guidance for T2
 2. Skip T2 and its dependents
 3. Manually resolve and continue"

### Step 5: Update task board
Display current state clearly:
T1 [DONE] ✅
T2 [FAILED] ❌ — [error summary]
T3 [DONE] ✅ (independent)
T4 [BLOCKED] 🔒 — waiting for T2
T5 [BLOCKED] 🔒 — waiting for T4

Exercise 5: Optimize an inefficient task board (Hard)

This task board has everything in series. Reorganize it to maximize parallelism without breaking logical dependencies:

T1: Create User model → T2: Create migration → T3: GET /users →
T4: POST /users → T5: User list component → T6: User form component →
T7: Write tests

| ID | Task | Depends On | Parallel Group |
|----|------|------------|----------------|
| T1 | Create User model | none | Stage 1 |
| T2 | Create migration | T1 | Stage 2 |
| T3 | GET /users endpoint | T2 | Stage 3a |
| T4 | POST /users endpoint | T2 | Stage 3a (parallel) |
| T5 | User list component | T3 | Stage 4a |
| T6 | User form component | T4 | Stage 4a (parallel) |
| T7 | Write tests | T3, T4 | Stage 4b |

Graph:
T1 → T2 → T3 → T5
         → T4 → T6
         → T3, T4 → T7

Execution:
Stage 1: T1
Stage 2: T2
Stage 3: T3 + T4 (parallel!)
Stage 4: T5 + T6 + T7 (all parallel!)

Original: 7 stages (all serial)
Optimized: 4 stages (with parallelism)

Exercise 6: Complete task board with 3 teammates (Hard)

Design a task board for "Implement authentication with registration, login, and profile" with 3 teammates (db-dev, api-dev, frontend-agent). At least 6 tasks, real dependencies, justified priorities, and the dependency graph.

| ID | Task | Agent | Depends | Pri | Justification |
|----|------|-------|---------|-----|---------------|
| T1 | User model + migration | db-dev | none | HIGH | Everything needs the model |
| T2 | Auth service (hash, JWT) | api-dev | T1 | HIGH | Core auth logic |
| T3 | POST /register | api-dev | T2 | HIGH | First user flow |
| T4 | POST /login + token | api-dev | T2 | HIGH | Second user flow |
| T5 | GET /profile (protected) | api-dev | T4 | MEDIUM | Needs auth middleware |
| T6 | Register form + page | frontend-agent | T3 | MEDIUM | Uses register endpoint |
| T7 | Login form + page | frontend-agent | T4 | MEDIUM | Uses login endpoint |
| T8 | Profile page (protected) | frontend-agent | T5, T7 | LOW | Needs login + profile API |

Graph:
T1 → T2 → T3 → T6
         → T4 → T5 → T8
              → T7 ──┘

Parallel opportunities:
Stage 1: T1
Stage 2: T2
Stage 3: T3 + T4 (parallel)
Stage 4: T5 + T6 + T7 (parallel, different agents!)
Stage 5: T8

Total stages: 5 (vs 8 if all serial)

Summary

• The task board is the central structure of Agent Teams — it connects the team lead to the team's work
• Each task has: ID, description, assignment, dependencies, priority, and status
• Dependencies determine the execution order — the team lead never assigns a task whose dependencies aren't DONE
• The 5 states: PENDING → IN_PROGRESS → DONE (normal), BLOCKED (waiting on deps), FAILED (error)
• There are 4 common patterns: linear pipeline, fan-out/fan-in, diamond, and staged pipeline
• Priority only matters when there are multiple PENDING tasks — HIGH runs before MEDIUM
• When a dependency fails, the team lead has 3 options: retry, reassign, or escalate
• Circular dependencies are a deadlock — the team lead must detect them before executing
• Without Agent Teams, the task board is implemented in the coordinator's system prompt with the same logic

Additional Resources

1. Create Custom Subagents (Anthropic Docs) — Official documentation of agent files and coordination
2. Claude Code Best Practices — Delegation and task management best practices
3. Claude Code CLI Reference — CLI reference for running agent files
4. Multi-Agent Orchestration — Multi-agent coordination patterns
5. Prompt Engineering: System Prompts — Techniques for coordination system prompts
6. DAG (Directed Acyclic Graph) — The theoretical foundation of dependency graphs
7. Kanban Method — The mental model behind the task board
8. Claude Code Overview — General context of Claude Code

Next capsule: In capsule 05 you'll learn how the teammates communicate with each other and how the team lead resolves conflicts. You'll see what happens when two teammates produce contradictory results, how to handle the case of a teammate that finishes before the others (TeammateIdle), and the most common failure modes of an agent team.