Agent Teams - Parallel AI Coding with File Ownership Isolation

Large tasks leverage Claude Code’s Agent Teams feature (TeamCreate) to spawn multiple Builder teammates that code in parallel. Each Builder receives isolated file ownership, preventing conflicts.

Prerequisites

Agent Teams is an experimental Claude Code feature that requires an environment variable to enable:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Add this to the "env" section of ~/.claude/settings.json.

How It Works

Trigger Conditions

When /ccg:go selects the full-collaborate strategy, the implementation phase automatically spawns Agent Teams:

full-collaborate strategy:
  Phase 1-3: Analysis + Plan + HARD STOP
  Phase 4: ← Agent Teams triggered here
    → TeamCreate Builder-1 (owns auth/ module)
    → TeamCreate Builder-2 (owns api/ module)
    → TeamCreate Builder-3 (owns tests/)
  Phase 5-6: Quality gates + Review

File Ownership Isolation

Core rule: Each file can only be modified by one Builder at a time.

The engine generates a file ownership matrix during Phase 3 (planning):

Builder-1: src/auth/jwt.ts, src/auth/middleware.ts
Builder-2: src/api/routes.ts, src/api/controllers.ts
Builder-3: tests/auth.test.ts, tests/api.test.ts

Each Builder’s prompt explicitly states: “Only modify your assigned files. Do not expand scope.”

Context Injection

The subagent-context.js hook automatically injects the following into each Builder during TeamCreate:

• The task plan (plan.md)
• Project coding standards (relevant files from .ccg/spec/)
• The file scope assigned to that Builder
• Interface contracts (how Builders coordinate with each other)

Execution and Convergence

Main Claude (Lead)
    │
    ├── spawn Builder-1 → reports on completion
    ├── spawn Builder-2 → reports on completion
    └── spawn Builder-3 → reports on completion
    │
    ← Wait for all Builders to finish
    │
    └── Converge: review + integrate + quality gates

Builder Prompt Constraints

Every Builder’s prompt includes the following hard constraints (auto-injected by the engine):

1. Only modify assigned files — Cannot touch files outside the ownership matrix
2. No scope expansion — Must not “discover” new requirements and implement them
3. Must report verification commands — After completion, output a command that verifies the changes

Relationship to Legacy Team Commands

In v3.0, Agent Teams are automatically managed by /ccg:go’s full-collaborate strategy.

Legacy mode provides 4 standalone Team commands for manual control over each phase:

Legacy Command	Corresponds to full-collaborate Phase
/ccg:team-research	Phase 1-2 (Analysis)
/ccg:team-plan	Phase 3 (Planning)
/ccg:team-exec	Phase 4 (Parallel implementation)
/ccg:team-review	Phase 5-6 (Review)

Tip

In most cases, /ccg:go’s automatic management is sufficient. Use the Legacy Team commands only when you need fine-grained intervention between each phase.

When to Use Agent Teams

Agent Teams are ideal for:

• Feature development spanning 3+ independent modules
• Tasks requiring 2+ parallel workflows
• Large tasks with more than 10 total steps
• Low coupling between files, allowing parallel modification

Not recommended for:

• Highly coupled single-file modifications
• Migrations requiring strict sequential execution
• Simple bug fixes