Module 8: Project — Complete Multi-Agent System

3. Execution — Task Board, Parallel Delegation, Quality Gates

Next →

3. Execution — Task Board, Parallel Delegation, Quality Gates

Description

The configuration is ready. 5 agent files in .claude/agents/, hooks in scripts/hooks/, settings.json connecting everything, CLAUDE.md as the constitution, and a packaged plugin. Now it's time to execute.

In this capsule you design a task board of 10 tasks with real dependencies, launch the team with claude --agent team-lead, observe how frontend and backend work in parallel, how testing validates the deliverables, how docs/review analyzes quality, and how the hooks block, report, and log every action. It's the moment where everything you configured is put to the test.

When you finish this capsule you'll have seen a complete multi-agent execution cycle: from the task board to the final report. You'll know what to watch for, what can fail, and how to intervene when something doesn't work.

⚠️ EXPERIMENTAL FEATURE

Agent Teams is an experimental feature of Claude Code. The execution works the same way using the team lead as a coordinator subagent (claude --agent team-lead).

Last verified: March 2026

Designing the Task Board

The feature to implement

We'll use as an example a task management (todo list) feature with these capabilities:

  1. Endpoint to create, list, update, and delete tasks
  2. Pydantic schemas for request/response
  3. Shared types for frontend
  4. Page with a task list and creation form
  5. Individual task component with status (pending/completed)
  6. Tests for endpoints and components
  7. API documentation

Adapt this feature to your project. What matters is that it has backend operations, frontend components, and a data flow that passes through shared types.

The task board: 10 tasks

📋 Task Board: Todo List Feature

| ID  | Task                              | Agent            | Depends On | Priority | Status  |
|-----|-----------------------------------|------------------|------------|----------|---------|
| T1  | Task Pydantic schemas             | backend-agent    | none       | HIGH     | PENDING |
| T2  | Publish shared types              | backend-agent    | T1         | HIGH     | PENDING |
| T3  | CRUD endpoints (/api/tasks)       | backend-agent    | T1         | HIGH     | PENDING |
| T4  | Error handling middleware          | backend-agent    | T3         | MEDIUM   | PENDING |
| T5  | TaskList page layout/skeleton     | frontend-agent   | none       | MEDIUM   | PENDING |
| T6  | TaskCard component                | frontend-agent   | T2         | HIGH     | PENDING |
| T7  | CreateTaskForm component          | frontend-agent   | T2, T3     | HIGH     | PENDING |
| T8  | Test backend endpoints            | testing-agent    | T3, T4     | HIGH     | PENDING |
| T9  | Test frontend components          | testing-agent    | T6, T7     | HIGH     | PENDING |
| T10 | Quality review + API docs         | docs-review-agent| T8, T9     | MEDIUM   | PENDING |

Dependency graph

T1 (schemas) ──→ T2 (types) ──→ T6 (TaskCard)
    │                  │              │
    │                  └──→ T7 (CreateTaskForm) ──→ T9 (test frontend)
    │                                                      │
    └──→ T3 (endpoints) ──→ T4 (error handling) ──→ T8 (test backend)
                                                           │
T5 (skeleton) ─────────────────────────────────────────────│
                                                           │
                                              T10 (review + docs)

Execution phases

Phase 1 — Foundations (parallel):
  Backend: T1 (schemas)
  Frontend: T5 (skeleton — doesn't depend on the backend)

Phase 2 — Core Implementation (partially parallel):
  Backend: T2 (types), T3 (endpoints) — sequential
  Frontend: waits for T2 for T6

Phase 3 — Advanced Implementation:
  Backend: T4 (error handling) — after T3
  Frontend: T6 (TaskCard) + T7 (CreateTaskForm) — after T2, T3

Phase 4 — Testing (sequential per agent):
  Testing: T8 (test backend) — after T3, T4
  Testing: T9 (test frontend) — after T6, T7

Phase 5 — Review:
  Docs/Review: T10 (quality review + API docs) — after T8, T9

Launching the Team

Preparation

Before launching, verify that everything is ready:

ls .claude/agents/*.md | wc -l
# Should be 5

cat .claude/settings.json | jq '.hooks | keys'
# Should show PreToolUse, PostToolUse, SubagentStop

cat CLAUDE.md | head -3
# Should show the CLAUDE.md title

chmod +x scripts/hooks/*.sh

The execution prompt

Start the team lead:

claude --agent team-lead

Once inside, send the feature prompt:

Implement a task management (todo list) feature with the
following capabilities:

1. Pydantic schemas for Task: id, title, description, status
   (pending/completed), created_at, updated_at
2. CRUD endpoints: POST /api/tasks, GET /api/tasks, GET /api/tasks/{id},
   PUT /api/tasks/{id}, DELETE /api/tasks/{id}
3. Shared types published in src/types/
4. Error handling middleware with a standard format
5. TaskList page that displays all the tasks
6. TaskCard component that displays an individual task with a status
   toggle
7. CreateTaskForm to create new tasks
8. Tests for all the endpoints (happy path + error cases)
9. Tests for the frontend components (render + interactions)
10. Quality review of the code + API documentation

Generate the task board with 10 tasks, show it to me, and when I confirm,
execute the complete team.

Observing the Execution

Phase 1: Task Board and Approval

The team lead should:

  1. Read the codebase (Glob, Read on key files)
  2. Read CLAUDE.md to understand conventions
  3. Generate a task board similar to the one designed above
  4. Show the dependency graph
  5. Wait for your confirmation

What to check before approving:

  • Are the dependencies logical? (schemas before endpoints, types before components)
  • Is each task assigned to the correct agent?
  • Does testing have dependencies on implementation tasks?
  • Is docs/review the last to execute?
  • Are there frontend tasks that can start in parallel with the backend?

If everything looks good, confirm with "Proceed" or "Execute".

Phase 2: Parallel Execution

Observe the flow:

[Team Lead] Assigning T1 to backend-agent and T5 to frontend-agent (parallel)
  │
  ├── [Backend Agent] T1: Creating Pydantic schemas...
  │   └── Files: src/schemas/task.py → TaskCreate, TaskUpdate, TaskResponse
  │
  └── [Frontend Agent] T5: Creating TaskList layout...
      └── Files: src/components/TaskList/index.tsx → skeleton with loading state

What you should see:

  • Backend and frontend start simultaneously (T1 + T5)
  • The team lead doesn't wait for T5 to finish to assign T2 (T2 only depends on T1)
  • When T1 finishes, T2 and T3 are unblocked
  • The team lead forwards the T1 schemas as context for T6 and T7

Phase 3: Context Forwarding in Action

When the backend-agent completes T1 and T2, the team lead should forward context to the frontend:

[Team Lead → Frontend Agent]
"Task T6: Implement TaskCard component.

Context from backend:
- Types published at: src/types/task.ts
- TaskResponse: { id: string, title: string, description: string,
  status: 'pending' | 'completed', created_at: string, updated_at: string }
- GET /api/tasks → returns TaskResponse[]
- PUT /api/tasks/{id} → accepts TaskUpdate { title?: string,
  description?: string, status?: string }

Read src/types/task.ts and import types from there.
Do NOT define types inline."

What you should verify:

  • Did the team lead include the exact types?
  • Did it include the relevant endpoints?
  • Did it instruct the frontend-agent to use types from src/types/?
  • Does the frontend-agent actually read src/types/ before implementing?

Phase 4: Quality Gates in Action

While the agents work, the hooks fire automatically:

PreToolUse — Validation:

[Hook] PreToolUse → Bash command: "python -m pytest" → ALLOWED (exit 0)
[Hook] PreToolUse → Write file: "src/api/routes/tasks.py" → ALLOWED (exit 0)
[Hook] PreToolUse → Bash command: "rm -rf /" → BLOCKED (exit 2)

PostToolUse — Auto-lint:

[Hook] PostToolUse → Write "src/schemas/task.py"
  → Running ruff check... PASS (exit 0)

[Hook] PostToolUse → Edit "src/api/routes/tasks.py"
  → Running ruff check... FAIL (exit 1)
  → "Line 23: unused import 'Optional'"
  → Claude receives error, fixes it

SubagentStop — Logging:

[Hook] SubagentStop → backend-agent completed (12340ms)
  → Logged to logs/agents/agent-activity.log

Phase 5: Testing

When the implementation tasks finish, the testing-agent activates:

[Team Lead] All implementation tasks DONE. Assigning T8 to testing-agent.

[Testing Agent] T8: Testing backend endpoints...
  Reading: src/api/routes/tasks.py
  Reading: src/schemas/task.py
  Creating: tests/test_tasks_api.py
  Running: python -m pytest tests/test_tasks_api.py -v

  Results:
  - test_create_task_success ✅
  - test_create_task_missing_title ✅
  - test_list_tasks_empty ✅
  - test_list_tasks_with_data ✅
  - test_get_task_not_found ✅
  - test_update_task_success ✅
  - test_delete_task_success ✅
  Total: 7 passed, 0 failed

If a test fails:

[Testing Agent] Bug found: PUT /api/tasks/{id} returns 200 instead
of 404 when task doesn't exist.
File: src/api/routes/tasks.py, line 45
Status: PARTIAL — 6/7 tests pass

[Team Lead] Bug detected in T3 (endpoints). Reassigning fix to
backend-agent with context from testing-agent.

[Backend Agent] Fixing: Added existence check before update.
  Modified: src/api/routes/tasks.py (line 45)

[Team Lead] Fix applied. Re-running T8.

[Testing Agent] All 7 tests pass.

Phase 6: Review

Finally, the docs/review agent analyzes everything:

[Team Lead] All tests pass. Assigning T10 to docs-review-agent.

[Docs/Review Agent] Reviewing all files produced by team...

Quality Review:
- src/schemas/task.py — Grade: A (clean Pydantic models, good naming)
- src/api/routes/tasks.py — Grade: B (missing docstring on delete handler)
- src/components/TaskCard/index.tsx — Grade: A (proper types, good states)
- src/components/CreateTaskForm/index.tsx — Grade: B+ (missing aria-label
  on submit button)

Issues:
- WARNING: src/api/routes/tasks.py:52 — No docstring on delete_task handler
- SUGGESTION: src/components/CreateTaskForm — Add aria-label="Create task"

Documentation created:
- docs/api/tasks.md — Full API reference for /api/tasks endpoints

Handling Failures and Reassignment

Scenario 1: Agent can't complete the task

[Frontend Agent] Task T7: BLOCKED
Reason: "Cannot determine the API endpoint URL. Types are published
but no endpoint URL was provided."

[Team Lead] T7 blocked. Missing context.
  Reading T3 output to find endpoint URLs...
  Reassigning T7 with additional context:
  "POST /api/tasks — Request body: TaskCreate { title, description }
   Response: TaskResponse { id, title, ... }"

Lesson: If an agent gets blocked for lack of context, the team lead must forward the missing information. If it keeps failing after a retry, it escalates to the user.

Scenario 2: Type conflict

[Testing Agent] Bug: Frontend component expects 'status' as boolean,
but backend publishes 'status' as string enum ('pending' | 'completed').

[Team Lead] Type conflict detected.
  Resolution: Backend is source of truth (per CLAUDE.md).
  Frontend-agent must update TaskCard to use string enum, not boolean.
  Reassigning fix to frontend-agent.

Lesson: CLAUDE.md establishes that the backend is the source of truth for API contracts. The team lead applies this rule without ambiguity.

Scenario 3: Hook blocks a legitimate operation

[Hook] PreToolUse → BLOCKED: Bash command "rm tests/test_old.py"
Reason: "Destructive command detected"

[Team Lead] Hook blocked a legitimate operation.
User intervention needed: approve removal of obsolete test file.

Lesson: Hooks can be too strict. If a block is legitimate but incorrect, adjust the hook or approve manually.

Scenario 4: Agent runs out of turns

[Backend Agent] Task T3: PARTIAL — Created 3/5 endpoints.
maxTurns (25) reached.

[Team Lead] T3 partially completed. Creating follow-up task:
  T3b: "Complete remaining endpoints: PUT and DELETE for /api/tasks"
  Agent: backend-agent
  Context: T3 output (3 endpoints already created)

Lesson: If an agent runs out of turns, the team lead creates a follow-up task with the context of what was already completed.

The Execution Prompt: Advanced Version

If you want more control over the execution, use a more detailed prompt:

Implement a task management feature. Here is my task board:

| ID  | Task                              | Agent            | Depends On |
|-----|-----------------------------------|------------------|------------|
| T1  | Task Pydantic schemas (TaskCreate, TaskUpdate, TaskResponse) | backend-agent | none |
| T2  | Publish types to src/types/task.ts | backend-agent    | T1         |
| T3  | CRUD endpoints POST/GET/PUT/DELETE /api/tasks | backend-agent | T1 |
| T4  | Error handling middleware          | backend-agent    | T3         |
| T5  | TaskList page skeleton with loading state | frontend-agent | none |
| T6  | TaskCard component (display + status toggle) | frontend-agent | T2 |
| T7  | CreateTaskForm (title + description inputs) | frontend-agent | T2, T3 |
| T8  | Test all 5 endpoints              | testing-agent    | T3, T4     |
| T9  | Test TaskCard and CreateTaskForm   | testing-agent    | T6, T7     |
| T10 | Quality review + API docs          | docs-review-agent| T8, T9     |

Execution rules:
1. Start T1 + T5 in parallel (no dependencies)
2. When T1 done → start T2, T3 sequentially for backend
3. When T2 done → start T6 for frontend
4. When T2 + T3 done → start T7 for frontend
5. When T3 + T4 done → start T8 for testing
6. When T6 + T7 done → start T9 for testing
7. When T8 + T9 done → start T10 for docs/review
8. Forward ALL type definitions and endpoint URLs between agents
9. If any test fails → report the bug and reassign fix

Execute this task board now.

This version gives you full control: you define the tasks, the order, the dependencies, and the execution rules. The team lead executes your plan instead of generating its own.

Observing in Real Time

Agent logs

While the team executes, the hooks generate logs in logs/agents/agent-activity.log:

[2026-03-13T14:22:01Z] Agent: backend-agent | Duration: 18230ms | Status: completed
[2026-03-13T14:22:15Z] Agent: frontend-agent | Duration: 8450ms | Status: completed
[2026-03-13T14:23:42Z] Agent: backend-agent | Duration: 22100ms | Status: completed
[2026-03-13T14:24:18Z] Agent: frontend-agent | Duration: 15670ms | Status: completed
[2026-03-13T14:25:33Z] Agent: frontend-agent | Duration: 12340ms | Status: completed
[2026-03-13T14:26:45Z] Agent: testing-agent | Duration: 25890ms | Status: completed
[2026-03-13T14:27:12Z] Agent: testing-agent | Duration: 19450ms | Status: completed
[2026-03-13T14:28:30Z] Agent: docs-review-agent | Duration: 16780ms | Status: completed

To monitor in real time in another terminal:

tail -f logs/agents/agent-activity.log

Verify created files

After the execution, verify what was created:

echo "=== Backend ==="
find src/api src/models src/services src/schemas src/types -type f 2>/dev/null

echo "=== Frontend ==="
find src/components src/pages src/hooks -type f 2>/dev/null

echo "=== Tests ==="
find tests -type f -name "*.py" 2>/dev/null

echo "=== Docs ==="
find docs -type f 2>/dev/null

Execution Success Checklist

✅ Task board generated with 8-10 tasks and correct dependencies
✅ Dependencies respected: backend before frontend where applicable
✅ At least one round of parallel execution (T1 + T5)
✅ Context forwarding: frontend received types from the backend
✅ Types from src/types/ used by frontend (not defined inline)
✅ PostToolUse hooks fired (lint after edits)
✅ PreToolUse hooks blocked at least one command (or validated without blocking)
✅ SubagentStop logs recorded in agent-activity.log
✅ Testing-agent ran tests and reported results
✅ Docs/review-agent produced a quality review
✅ Team lead did not write code directly
✅ Final report with all results consolidated
✅ If there were failures, the team lead managed them (retry or escalation)

Exercises

Exercise 1: Execute with your own feature (Medium)

Repeat the complete execution but with a different feature from your real project. Design the task board of 8-10 tasks, execute with the team lead, and compare the results with the example execution.

Exercise 2: Force a conflict (Medium)

Temporarily modify the backend-agent to publish a type with a field called is_done (boolean), and the frontend-agent to expect status (string enum). Execute and observe how the team lead (or you) resolves the type conflict.

Exercise 3: Pre-defined task board vs auto-generated (Medium)

Execute the same feature twice: once letting the team lead generate the task board automatically, and once passing it the predefined task board (as in "Advanced Version"). Compare: which was more efficient? Which produced a better result?

Exercise 4: Add a strict quality gate (Hard)

Create an additional PostToolUse hook that runs python -m pytest tests/ -x --tb=short after each edit in src/. If any test fails, the hook reports the error (exit 1). This means every code change is tested automatically. Execute the team with this hook and observe the impact on the execution.

Exercise 5: Execution without the team lead (Hard)

Execute the 10 tasks manually: start each agent separately (claude --agent backend-agent), pass it a task, collect the output, and forward it to the next agent. Compare the effort with the execution via team lead. How much time did the team lead save?

Exercise 6: Scale to 12 tasks (Hard)

Add 2 more tasks to the task board: one for caching (backend-agent adds cache with Redis for GET /api/tasks) and one for performance testing (testing-agent measures response times). Adjust the dependencies and execute. Does the team lead handle the additional complexity well?

Troubleshooting

"The team lead doesn't generate a task board — it starts executing directly"

Cause: The system prompt isn't emphatic about generating and waiting for approval.

Solution: Reinforce in the team lead:

MANDATORY: ALWAYS generate the task board FIRST and present it.
WAIT for the user to say "Proceed" or "Execute" before delegating.
NEVER start execution without explicit approval.

"Frontend starts before it has the backend types"

Cause: The team lead didn't verify dependencies before assigning.

Solution: Add an explicit check:

Before assigning ANY task:
1. Read its "Depends On" field
2. For EACH dependency, verify status is DONE
3. If ANY dependency is not DONE → DO NOT assign
4. Log: "T[x] waiting on T[y] (status: [status])"

"The testing-agent's tests fail because the code doesn't exist yet"

Cause: The testing-agent received a task before the implementation finished.

Solution: The testing-agent's dependencies must include ALL the implementation tasks it tests. In the task board, T8 depends on T3 AND T4, not just T3.

"The final report is incomplete"

Cause: The team lead lost context of the first tasks due to context window saturation.

Solution: The team lead must maintain a running summary (defined in its system prompt):

T1 [DONE] — Schemas created (src/schemas/task.py)
T2 [DONE] — Types published (src/types/task.ts)
...

"The execution takes too long (>30 minutes)"

Cause: Too many tasks, agents with high maxTurns, or slow hooks.

Solution:

  1. Reduce to 6-8 tasks by combining similar ones
  2. Lower the implementation agents' maxTurns to 20
  3. Verify that the hooks finish in <2 seconds
  4. If an agent takes more than 5 minutes on a task, check whether the prompt is too vague

Anatomy of a Successful Execution

The 5 key moments

Every multi-agent execution has 5 moments that determine whether the result will be successful:

Moment 1: Task board quality

The task board defines success. If the dependencies are incorrect, the agents get blocked. If the tasks are too big, the agents run out of turns. If they're too small, the coordination overhead exceeds the real work.

Rule: 8-10 tasks for a medium feature. Each task produces 1-3 files. The dependencies follow the data flow (schemas → types → endpoints → components → tests → review).

Moment 2: First parallel round

The first round determines the system's speed. If only one agent can start (everything depends on something), the system is serial disguised as parallel. Always look for frontend tasks that don't depend on the backend: layout, skeleton, reusable components, generic hooks.

Rule: at least 2 agents should be active in the first round.

Moment 3: Context forwarding

When the backend finishes and the frontend starts, the quality of the context forwarding determines whether the frontend produces something useful or gets blocked. The exact types, the endpoint URLs, the error format — everything must be forwarded explicitly.

Rule: the team lead includes endpoint URLs, response schemas with all fields, and the exact path of the published types.

Moment 4: First test failure

The testing-agent will find bugs. How the team lead handles that first failure — reassigning to the correct agent, forwarding the bug context, re-running the tests — defines the maturity of the system.

Rule: the team lead identifies the responsible agent (backend or frontend), passes it the exact test error, and asks it for a specific fix. Then it re-runs the tests.

Moment 5: Final report

The final report is the evidence of the system's value. If it's complete (files, endpoints, components, tests, quality score), the system demonstrated its value. If it's incomplete, the team lead lost context due to context window saturation.

Rule: the team lead maintains an up-to-date running summary after each task, and uses it for the final report.

Comparison: Manual Execution vs Team Lead vs Predefined Task Board

AspectManual (each agent separately)Team Lead auto-generatesPredefined Task Board
ControlTotal (you decide everything)Low (team lead decides)High (you define tasks)
EffortHigh (manual forwarding)Low (automatic)Medium (you design the board)
ParallelismManualAutomaticAutomatic
Context forwardingYou copy/pasteTeam lead forwardsTeam lead forwards
Error handlingYou reassignTeam lead reassignsTeam lead reassigns
Best forDebugging, learningRoutine executionsWell-defined features

Summary

  • The task board has 10 tasks with real dependencies that follow the flow: schemas → types → endpoints → components → tests → review
  • Parallel execution starts in Phase 1: backend (T1) and frontend (T5) work simultaneously
  • Context forwarding is critical: the team lead must forward exact types, endpoints, and schemas between agents
  • The quality gates (hooks) fire automatically: PreToolUse validates, PostToolUse lints, SubagentStop logs
  • If a test fails, the team lead detects the bug, identifies the responsible agent, and reassigns the fix
  • The agent logs (agent-activity.log) record the activity in real time
  • The team lead can auto-generate the task board or receive a predefined one — both work
  • The complete execution produces: functional endpoints, UI components, passing tests, quality review, and API documentation
  • The common failures are: insufficient context, dependencies not respected, and hooks that are too strict

Additional Resources

  1. Create Custom Subagents (Anthropic Docs) — Coordination between agents, task delegation
  2. Claude Code Hooks — Exit codes, matchers, and hook events
  3. Claude Code CLI Reference — Flag --agent, agent execution
  4. Claude Code Best Practices — Effective delegation and coordination
  5. Multi-Agent Orchestration — Parallelism and dependency management patterns
  6. Prompt Engineering: System Prompts — Prompts for coordination between agents

Next capsule: In capsule 04 you'll build the SDK script that monitors the team's progress in real time, configure remote control to approve critical operations, and generate an execution dashboard with per-agent metrics. The execution already works — now you add observability to it.

← Previous2. Team Configuration — 5 Agents, Plugin, Hooks, CLAUDE.mdNext →4. Monitoring — SDK for Observability, Remote Control for Approvals