Video 20.8: Plan Approval and Quality Gates

Course: Claude Code - Parallel Agent Development Section: S20 - Agent Teams Video Length: 5 minutes Presenter: Daniel Treasure

Opening Hook

A team that moves fast without oversight is a team that builds in the wrong direction. Plan approval and quality gates let you maintain standards while keeping your team autonomous. This is how you scale without losing control.

Key Talking Points

What to say:

The Control Problem at Scale - One person coding: you review your own work (implicit quality control) - One person with three teammates: you can't review everything they do in real-time - Without checkpoints, teammates might implement something that doesn't fit your vision - But over-controlling stifles autonomy and creates bottlenecks - Solution: Plan approval and quality gates—structured checkpoints

Plan Approval Concept - Before a teammate implements something, they present their approach - You review and approve the plan - Only after approval do they write code - This prevents wasted effort and keeps implementation aligned with vision - Example: "Architect proposes the system design. Lead reviews and approves. Then other teammates implement."

How Plan Approval Works

Spawn with Plan Approval Requirement
You specify at team spawn: "Require plan approval before implementation"
Teammates work read-only initially
They can't write code, they can only propose and discuss
Teammate Presents a Plan
Teammate drafts their approach: architecture, tech choices, implementation strategy
They explain the plan in a message or proposal
They wait for the lead to review
Lead Reviews
You read and understand the proposal
You ask clarifying questions if needed
You approve or request changes
Lead Approves
Once you approve, the teammate gets write access
They can now implement according to the approved plan
They move from read-only to active implementation
Teammate Implements
Now they code based on the approved plan
You trust that they'll follow the approach you agreed on
If they deviate, it's a conversation, not a surprise

Quality Gates Using Hooks

Hooks are automated checks that run at key moments:

TeammateIdle Hook
Fires when a teammate is about to go idle (finished their work or stuck)
You can require quality checks before they stop
Example: "Don't let them stop until the tests pass"
Exit code 0 = allow idle; Exit code 2 = block with feedback
TaskCompleted Hook
Fires when a task is marked complete
You can verify the work meets standards
Example: "Lint must pass, tests must pass, code review approved"
Exit code 0 = allow completion; Exit code 2 = block and ask for fixes

Example Quality Gate Workflow

Teammate finishes API implementation
  ↓
TeammateIdle hook fires
  ↓
Quality gate runs: npm lint, npm test
  ↓
If both pass: Teammate can go idle (exit 0)
If either fails: Feedback sent, teammate must fix (exit 2)
  ↓
Teammate sees the feedback and fixes issues
  ↓
Hook runs again, now passes
  ↓
Teammate goes idle successfully

Hook Configuration - Hooks are defined in the team config at ~/.claude/teams/{team-name}/config.json - Each hook specifies a command to run - The command receives JSON input: teammate_name, team_name, cwd, session_id - Exit code determines success (0) or failure (2) - You can set up hooks at team spawn time or add them later

Example Hooks

{
  "team_name": "sprint-build",
  "hooks": {
    "TeammateIdle": {
      "command": "npm test && npm run lint"
    },
    "TaskCompleted": {
      "command": "npm run validate && npm run security-check"
    }
  }
}

When to Use Plan Approval

Use When: - You have clear architectural decisions that must be made upfront - Teammates might choose different tech stacks or approaches - Rework is expensive (wrong database choice can't be undone easily) - You're mentoring and want to guide their thinking - The project has strict standards or compliance requirements

Don't Use When: - You trust your team implicitly - Changes are cheap and easy to undo - You're prototyping and speed is paramount - Your teammates are domain experts who know better than you

When to Use Quality Gates

Use When: - You have objective quality criteria (tests, linting, type checking) - You want to enforce standards automatically - You don't want to manually review every completion - You want to prevent technical debt from accumulating

Don't Use When: - Quality is subjective (design, UX choices) - Automated checks don't capture what matters - You're in a very early stage where standards aren't set yet

Combining Plan Approval and Quality Gates - Plan approval: "Are we building the right thing?" - Quality gates: "Are we building it well?" - Together: complete quality pipeline - Plan approval → implementation → quality gates → completion

Lead's Role in the Approval Process

Set expectations upfront: "I'll require plan approval for architectural decisions"
Review quickly: Don't be a bottleneck; review within a reasonable time
Give clear feedback: Approve or explain what needs to change
Trust the process: Once approved, step back and let teammates work
Enforce gates fairly: Quality gates apply to everyone equally

Feedback Cycle - Teammate proposes plan A - You reject: "We're using PostgreSQL, not MongoDB" - Teammate updates to plan B (PostgreSQL-based) - You approve - Teammate implements - At completion, gates check tests/lint/security - If gates fail, teammate fixes and reruns - When gates pass, task is complete

What to show on screen:

Terminal with a team spawned with plan approval enabled
Show a teammate's initial proposal/plan
Demonstrate the read-only access they have initially
Show the lead reviewing the plan
Show the lead approving the plan
Show the teammate transitioning to implementation
Demonstrate a quality gate running (tests, lint, etc.)
Show a gate failure and the feedback
Show the teammate fixing and re-running
Show final approval after gates pass

Demo Plan

0:00-0:45 - Spawn a Team with Plan Approval - Use natural language: "Create a team with 1 architect and 2 developers. Require plan approval before implementation." - Watch the team spawn - Narrate: "Notice that the architect can't write code yet. They're in a read-only mode" - Show the interface indicating "plan approval required" - Explain: "The architect needs to propose their approach first"

0:45-1:45 - Architect Proposes a Plan - Show the architect drafting their system design proposal - Have them outline: "I propose a monolithic Node.js backend with PostgreSQL, Redis for caching, and React frontend" - Show the proposal appearing in the team context - Narrate: "The architect can think and propose, but can't write code. This forces clear communication upfront" - The proposal might include architecture diagrams or detailed descriptions (text) - Show the proposal is now waiting for lead approval

1:45-2:30 - Lead Reviews and Approves - Navigate to the lead context - Read the architect's proposal: "Looks good. One question: why Redis instead of in-process cache?" - The architect responds: "Redis allows scaling across multiple servers later" - Lead approves: "Approved. Let's go with this approach" - Narrate: "This is the approval checkpoint. The lead ensures the plan aligns with the vision" - Show the access change: architect transitions from read-only to full write access

2:30-3:30 - Implementation and Quality Gates - Show the team implementing - Have them write code, commit, etc. - Simulate the completion of a task: "API implementation done" - Trigger the quality gate: tests and lint must pass - Show the gate running: "npm test", "npm lint" - First run: something fails (e.g., test failure: "Expected status 200, got 500") - Narrate: "Quality gates catch issues before they become problems"

3:30-4:15 - Teammate Fixes and Re-runs - Show the teammate seeing the gate failure - They fix the bug: "Oops, forgot to handle error case in API endpoint" - They re-run the gate: tests pass, lint passes - Show both checks passing - Task marked complete - Narrate: "Now that everything passes, the task is truly done. No surprises later"

4:15-5:00 - Lead-out and Reflection - Recap: plan approval ensures alignment, quality gates ensure standards - Emphasize: this is about scale without losing control - Confirm: not every team needs both (customize to your needs) - Next steps: you now have a full toolkit for agent teams - Tease: reflection on the entire agent teams journey

Code Examples & Commands

Spawn a Team with Plan Approval

# In Claude Code:
> Create a team with 1 architect teammate and 2 developer teammates.
> Require plan approval before they can write code.

Team Config with Plan Approval (Auto-Generated)

{
  "team_name": "sprint-build",
  "lead_model": "claude-opus-4-6",
  "plan_approval_required": true,
  "teammates": [
    {
      "name": "architect",
      "model": "claude-opus-4-6",
      "role": "System Architecture",
      "read_only_until_approval": true
    },
    {
      "name": "dev_1",
      "model": "claude-sonnet-4-20250514",
      "role": "Backend Implementation"
    },
    {
      "name": "dev_2",
      "model": "claude-sonnet-4-20250514",
      "role": "Frontend Implementation"
    }
  ]
}

Team Config with Quality Gate Hooks

{
  "team_name": "sprint-build",
  "lead_model": "claude-opus-4-6",
  "teammates": [
    {
      "name": "api_dev",
      "model": "claude-sonnet-4-20250514",
      "role": "API Development"
    }
  ],
  "hooks": {
    "TeammateIdle": {
      "command": "npm test && npm run lint && npm run type-check",
      "description": "Ensure all tests pass, linting passes, and types are valid before teammate goes idle"
    },
    "TaskCompleted": {
      "command": "npm run security-audit && npm run coverage-check",
      "description": "Verify security and test coverage before marking task complete"
    }
  }
}

Approving a Plan

# After reviewing the proposal:
> I approve this plan. You can proceed with implementation.

# Or with specific notes:
> Approved with the following modifications:
> - Use PostgreSQL as specified
> - Add Redis caching layer
> - Document the API with OpenAPI spec

Rejecting and Requesting Changes

# Provide specific feedback:
> I'd like to see a different approach here:
> - Use microservices instead of monolithic (we have multiple teams)
> - Add an API Gateway for routing
> - Include load balancing in the design

> Revise the plan and resubmit when ready.

Hook Input Format (Reference)

{
  "teammate_name": "api_dev",
  "team_name": "sprint-build",
  "cwd": "/path/to/project",
  "session_id": "abc123",
  "status": "idle",
  "reason": "task_completed"
}

Example Hook Script (Bash)

#!/bin/bash
# Quality gate: ensure tests and lint pass

npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Aborting."
  exit 2
fi

npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Aborting."
  exit 2
fi

echo "All quality checks passed."
exit 0

Gotchas & Tips

Gotchas: - Plan approval slows things down; use it only when it's truly necessary - Quality gates that are too strict (requiring 100% test coverage) might frustrate teammates - Hooks with long-running commands (e.g., heavy security scans) delay feedback; keep them fast - If a hook is broken, teammates get stuck; test hooks before applying to the team - Read-only mode for plan approval is binary; you can't let them write some files and not others - Changing hooks mid-team requires editing the config; not all changes apply immediately

Tips: - Use plan approval for architectural decisions and major tech choices, not every small task - Keep quality gates focused: one hook for tests, one for lint, one for security - Make hook feedback clear and actionable: "Test failure on line 42 of api.test.js: expected 200, got 500" - Test your hooks in isolation before adding them to the team - Document your quality standards: "All code must have tests. Lint must pass. No console.logs in production." - For first-time teams, skip plan approval and quality gates; add them once you have a rhythm - Quality gates are cheaper than finding bugs in production; invest in them - Consider a "dry run" of the hooks on existing code to ensure they're reasonable

Lead-out

You've now learned the complete Agent Teams toolkit: spawning, communication, task management, display modes, and quality control. You have everything you need to build and scale teams that work autonomously while maintaining your standards. This is the future of development with AI.

Reference URLs

Claude Agent SDK Hook Documentation: https://sdk.anthropic.com/docs/agent-teams/hooks
Quality Gates in CI/CD: https://www.anthropic.com/research/quality-assurance
Team Leadership and Delegation: https://www.anthropic.com/research/team-coordination
Best Practices for Distributed Teams: https://www.anthropic.com/claude-code/guides/team-best-practices

Prep Reading

Review the concept of CI/CD pipelines and automated quality checks
Understand exit codes and how scripts communicate success/failure
Think about what quality standards matter for your project
Consider what architectural decisions need upfront planning vs what can be flexible

Notes for Daniel

This is the final Agent Teams video; make it feel complete and empowering. Plan approval and quality gates might seem like "process overhead," but frame them as tools that enable speed and autonomy at scale. The key insight is that control doesn't come from micro-managing; it comes from clear checkpoints and automated verification. Show the natural conversation between lead and architect (not a formal review, but a quick alignment). The quality gate demo should feel smooth: gate runs, something fails, teammate fixes, gate runs again, passes. This is the virtuous cycle of good development. End on the note that viewers now have everything they need to scale development with AI teams. Tone should be confident and forward-looking.

Risk: if test suites or linting are slow, the gate might take time. Have a simple, fast gate example (e.g., just a type check) that runs quickly so the demo doesn't feel like dead air. Alternatively, pre-run the gates so you can show the results crisply rather than waiting for real execution.

Quick Reference