---
title: "Agent Teams — PDD Addendum"
description: "The user enabled `--teams`. You SHOULD use Claude Code's Agent Teams feature to produce higher-quality planning artifacts through diverse perspectives and parallel investigation."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/pdd-team-addendum
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:31:51.869Z
license: CC-BY-4.0
attribution: "Agent Teams — PDD Addendum — Claudary (https://claudary.paisolsolutions.com/skills/pdd-team-addendum)"
---

# Agent Teams — PDD Addendum
The user enabled `--teams`. You SHOULD use Claude Code's Agent Teams feature to produce higher-quality planning artifacts through diverse perspectives and parallel investigation.

## Overview

# Agent Teams — PDD Addendum

The user enabled `--teams`. You SHOULD use Claude Code's Agent Teams feature to produce higher-quality planning artifacts through diverse perspectives and parallel investigation.

This addendum uses RFC 2119 language: MUST, SHOULD, MAY.

## General Constraints

These apply across all PDD phases when teams are active:

- You SHOULD use Agent Teams for research (Step 4), design review (Step 6), and plan evaluation (Step 7).
- You MAY skip teams for phases that are too small or tightly sequential (e.g., Step 1 project structure creation).
- You MUST give each teammate specific context — teammates do NOT inherit your conversation history. Include: the task, relevant file paths, output expectations, and any constraints.
- You MUST NOT have two teammates edit the same file — define clear file ownership before spawning.
- You MUST consolidate and verify teammate findings before presenting to the user.
- You SHOULD use delegate mode — coordinate and synthesize, don't duplicate the work yourself.

## Phase-Specific Team Patterns

### Research (Step 4) — Fan-Out

You SHOULD spawn 2–3 teammates, each investigating a different research sub-topic.

- Each teammate gets a focused research question and writes to a separate file in `research/` (e.g., `research/auth-libraries.md`, `research/database-options.md`).
- Teammates work in parallel — they do NOT need to see each other's output.
- You synthesize findings across all teammates before checking in with the user.

Example teammate prompt structure:

> You are researching {sub-topic} for a PDD planning session. Write your findings to `{project_dir}/research/{sub-topic}.md`. Include: overview, key options with trade-offs, recommendations, and references. Focus on {specific-angle}. Do NOT modify any other files.

### Design Review (Step 6) — Adversarial Review

After drafting the initial design, you SHOULD spawn a Devil's Advocate teammate to challenge it.

- The critic's job: challenge assumptions, identify gaps in edge case handling, propose alternatives, find failure modes.
- You incorporate valid criticisms into the design before presenting to the user.
- For complex designs, you MAY spawn additional perspective teammates (e.g., security reviewer, performance analyst).

Example critic prompt structure:

> You are a critical reviewer for a software design document at `{project_dir}/design.md`. Read the design and the requirements at `{project_dir}/requirements.md`. Write a critique to `{project_dir}/research/design-critique.md` covering: challenged assumptions, missing edge cases, alternative approaches, failure modes, and any requirements that appear under-specified. Be rigorous — your job is to find problems, not to validate.

### Implementation Plan (Step 7) — Competing Approaches

You SHOULD spawn 2 teammates to independently propose implementation plans from the same approved design.

- Each teammate reads the design and proposes a different step ordering or decomposition.
- You compare the plans: trade-offs, risk profiles, parallelization potential.
- Synthesize the best elements into the final plan presented to the user.

## Team Coordination

- **Task sizing:** Each teammate SHOULD have 1–3 focused deliverables. Vague scope leads to wasted tokens.
- **Communication:** Use direct messages to specific teammates. Do NOT broadcast — broadcasts send a separate message to every teammate and scale linearly with team size.
- **Shutdown:** Shut down teammates when their phase is complete. Do NOT let idle agents accumulate across phases.
- **Quality:** Read and verify teammate outputs before incorporating them. Teammates can make mistakes.

## When to Scale Down

- If the idea is small (single module, straightforward design), fewer teammates are appropriate.
- You MAY use a single teammate as a reviewer instead of full fan-out.
- The goal is better outcomes through diverse perspectives, not parallelism for its own sake.

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/pdd-team-addendum) · https://claudary.paisolsolutions.com