Builder-Validator Agent Teams

Problem: Parallel Claude Code agents are fast. Without clear roles, though, they hand back uneven output and you end up checking every line yourself. What you want is agents that grade each other's work.

Looking for native Agent Teams? Claude Code now has a built-in Agent Teams feature for multi-agent collaboration. This post covers the DIY approach using Task tools, which works without any experimental features enabled.

Quick Win: Paste this builder-validator chain into your next multi-file task. The validator runs read-only, right after the builder wraps:

TaskCreate(subject="Build auth middleware", description="Create JWT validation middleware in src/middleware/auth.ts. Export verifyToken and requireAuth functions.")
TaskCreate(subject="Validate auth middleware", description="Read src/middleware/auth.ts. Verify: exports exist, error handling covers expired/malformed tokens, no hardcoded secrets. Report issues only. Do NOT modify files.")
TaskUpdate(taskId="2", addBlockedBy=["1"])

Task 2 holds until Task 1 finishes. The validator reads, never writes. Two agents. One output you trust.

Why Pairs Beat Solo Agents

Agent fundamentals covered what sub-agents are. Task distribution covered running them in parallel for speed. Sub-agent best practices covered routing. This post covers something else: giving agents roles and pairing them into teams.

Solo agents have a simple flaw. An agent that wrote the code is the worst pick to review it. Same blind spots, same assumptions, same shortcuts. Drop in an independent validator and you catch what the builder missed, because the validator starts clean.

It's the same reason human teams don't let the author be the only reviewer. You bring in another set of eyes.

The Builder-Validator Pattern

Builders write code. Validators read code. The jobs never overlap.

Builder prompt - scoped to creation:

You are a builder agent. Your job:
 
1. Read the task description carefully
2. Implement the solution in the specified files
3. Run any relevant tests
4. Mark your task complete
 
Rules:
 
- Only modify files listed in your task
- Do not modify test files (validators handle test verification)
- If you hit a blocker, document it in the task description and mark complete

Validator prompt - scoped to verification:

You are a validator agent. Your job:
 
1. Read all files the builder created or modified
2. Check against the acceptance criteria in the task description
3. Run the test suite
4. Report findings as a new task if issues exist
 
Rules:
 
- Do NOT modify any source files
- Do NOT create new implementation code
- You may only create or update task entries to report issues
- Use Read and Bash (for tests) only - never Edit or Write

The key constraint: validators can't write code. That forces them to surface real problems, not quietly patch things and skip the review. When a validator spots an issue, it creates a new task that bounces back to a builder. You can harden this at the tool level with custom agent definitions plus disallowedTools, which strips Edit and Write from validators entirely.

Dependency Chains for Build-Then-Validate

The addBlockedBy parameter on TaskUpdate is what glues this pattern together. Validators wait on their builder with no extra wiring:

// Phase 1: Parallel builders
TaskCreate(subject="Build user API routes", description="Create CRUD endpoints in src/api/users.ts...")
TaskCreate(subject="Build user database schema", description="Create migration in src/db/migrations/...")

// Phase 2: Validators blocked by their builders
TaskCreate(subject="Validate API routes", description="Read src/api/users.ts. Verify REST conventions, error handling, input validation...")
TaskCreate(subject="Validate database schema", description="Read migration files. Verify column types, indexes, foreign keys...")

TaskUpdate(taskId="3", addBlockedBy=["1"])
TaskUpdate(taskId="4", addBlockedBy=["2"])

Tasks 1 and 2 run side by side because they touch different files. Tasks 3 and 4 each wait on their own builder. Parallel speed on the build phase. Independent checks on each output.

Cross-cutting checks that need everything built first just stack multiple blockers:

TaskCreate(subject="Integration validation", description="Verify API routes correctly reference the database schema. Check that all referenced tables and columns exist.")
TaskUpdate(taskId="5", addBlockedBy=["1", "2"])

One Meta-Prompt That Builds the Whole Plan

Hand-rolling task chains gets old. A meta-prompt in CLAUDE.md can turn a feature request into a full team plan on the spot:

## Team Plan Generation
 
When I say "team plan: [feature]", generate a task structure:
 
For each component:
 
1. TaskCreate a builder task with specific files and acceptance criteria
2. TaskCreate a validator task scoped to read-only verification
3. TaskUpdate to chain validator behind its builder
 
After all component pairs, add one integration validator blocked by ALL builders.
 
Format each task description with:
 
- **Files**: exact paths to create or read
- **Criteria**: measurable acceptance conditions
- **Constraints**: what this agent must NOT do

Now you can just say: "team plan: add Stripe webhook handler." Claude returns the full dependency graph, pairs every component with its validator, and drops an integration validator at the end. You read the plan, say go, agents run.

This is the orchestrator pattern, live. Your main Claude session coordinates. It writes the plan, wires up the blockers, and dispatches the agents. It does not hand-write the application code itself.

When a Validation Fails

The loop continues when a validator flags a problem:

Validator files a fix task that says what's broken
A builder agent picks up the fix task
A fresh validator task chains behind the fix

// Validator found missing error handling
TaskCreate(subject="Fix: add error handling to user API", description="The GET /users/:id endpoint returns 500 on invalid ID format. Add input validation and return 400 for malformed IDs.")
TaskCreate(subject="Re-validate user API error handling", description="Verify GET /users/:id returns 400 for non-UUID strings, 404 for valid UUID not found, 200 for valid existing user.")
TaskUpdate(taskId="7", addBlockedBy=["6"])

Every cycle tightens the scope. The first builder handles the whole feature. Later builders handle one bug each. The loop walks the code toward correct without you hand-debugging the middle steps.

For tougher checks, hooks can run automated rules on every file change, so issues get caught before the validator agent even wakes up. You can push further by baking validation straight into agent definitions, which makes the quality check part of the agent's identity.

Start With One Pair

Don't rip up your whole workflow. Pick the next feature that touches two or more files. Make one builder task. Make one validator task with addBlockedBy. Watch the validator flag something the builder walked past.

Once you've seen it work, stack it: parallel builders with chained validators, meta-prompts writing the plan, integration validators tying everything together. Build your agent setup around clean role boundaries. Let the task system handle the order. You keep the decisions.