Team Code - Multi-Agent Development

Team Code implements the CAID (Centralized Asynchronous Isolated Delegation) research paradigm for coordinating multiple AI agents as a development team.

Think of it like this: instead of one developer working alone on a complex feature, you have a team of specialists working in parallel—each in their own isolated workspace, with a tech lead (manager) coordinating who works on what and when.

> ⚠️ CRITICAL WARNINGS:

> - Use Team Code from the start — Don't try solo first. Sequential attempts cost nearly 2x with minimal gain.

> - Physical branch isolation is mandatory — Shared workspaces cause silent conflicts that break everything.

> - Team size matters — 2 agents for research tasks, 4 for clear codebases, never exceed 8.

> - Higher cost, better results — Team Code improves accuracy (+26%), not speed. Worth it for important code.

The Analogy: Human Dev Team

When to Use Team Code

Perfect for:

• 🏗️ Building features that touch multiple files (auth, API, database)
• 🔄 Complex refactors with clear dependency chains
• 📚 Implementing libraries from scratch with test suites
• 🔬 Research reproductions (paper implementations)

Skip for:

• 🔧 One-line fixes or single-file changes
• 🧪 Pure exploration without clear structure
• ⏱️ Quick prototypes where "good enough" is fine

The Workflow

Phase 0: Setup (Manager = You)

Before the team starts, prepare the environment:

cd your-project

# Ensure dependencies work
pip install -r requirements.txt  # or npm install, etc.

# Create minimal stubs so imports don't fail
mkdir -p src/feature
touch src/feature/__init__.py src/feature/module_a.py src/feature/module_b.py

# Commit so team starts from known state
git add .
git commit -m "setup: initial feature structure"

Phase 1: Plan (Dependency Graph)

Analyze what needs to be built and in what order:

Your Task: "Add user authentication"

Dependencies:
  database.py ─→ models.py ─→ auth.py ─→ api.py
     (none)      (needs db)   (needs    (needs
                               models)   auth)

Round 1: database.py (foundation)
Round 2: models.py (depends on db)
Round 3: auth.py (depends on models)
Round 4: api.py (depends on auth)

Phase 2: Delegate to Agents

// Agent 1: Database (no dependencies)
await sessions_spawn({
  runtime: "subagent",
  task: `
    Implement database connection in src/feature/database.py
    - connect() function
    - Connection pooling
    - Error handling
    
    VERIFY: pytest tests/test_database.py -v
    RESTRICTED: src/feature/__init__.py
  `,
  agentId: "coding-agent",
  mode: "run",
  runTimeoutSeconds: 400
});

// Agent 2: Models (after database completes)
await sessions_spawn({
  runtime: "subagent",
  task: `
    Implement User model in src/feature/models.py
    - User class with SQLAlchemy
    - Fields: id, username, email, password_hash
    - Methods: set_password(), check_password()
    
    DEPENDS ON: database module (completed)
    VERIFY: pytest tests/test_models.py -v
    RESTRICTED: src/feature/__init__.py, src/feature/database.py
  `,
  agentId: "coding-agent",
  mode: "run",
  runTimeoutSeconds: 400
});

Phase 3: Integrate

# When agent signals completion
git checkout main
git merge feature/database

# If conflict - agent who created it resolves:
cd ../workspace-database
git pull origin main
# fix conflicts
pytest tests/test_database.py -v
git commit --amend

Phase 4: Final Review

# After all rounds complete
git checkout main
pytest tests/ -v                    # Full test suite
python -c "from src.feature import auth; print('OK')"  # Smoke test

Team Size Guide

Key Principles

1. Branch Isolation is Mandatory

# CORRECT: Physical isolation
git worktree add ../workspace-agent-1 feature/task-1
git worktree add ../workspace-agent-2 feature/task-2

# WRONG: Soft isolation (leads to conflicts)
# All agents in same directory with "don't touch each other's files"

2. Self-Verification Before Commit

Agent must run tests and fix failures BEFORE submitting:

pytest tests/test_my_module.py -v  # Must pass
git commit -m "implement: feature X"  # Only then

3. Structured Communication Only

Use JSON task specs, not conversation:

{
  "task_id": "implement-auth",
  "description": "JWT authentication",
  "files": ["src/auth/jwt.py"],
  "verify": "pytest tests/test_jwt.py -v",
  "restricted": ["src/auth/__init__.py"]
}

4. Agent Resolves Their Own Conflicts

If merge fails, the agent who wrote the code fixes it—not the manager.

Common Patterns

Pattern: Sequential Dependencies

A ─→ B ─→ C ─→ D

Start 1 agent, when done start next. Not parallel but structured.

Pattern: Parallel Foundation

  ┌──→ A ──→ C ─┐
  │              ├──→ E
  └──→ B ──→ D ─┘

A and B parallel, then C and D parallel, then E.

Pattern: Star (Common API Structure)

    ┌──→ Endpoint A
    │
DB ─┼──→ Endpoint B
    │
    └──→ Endpoint C

Database first, then all endpoints in parallel.

Trade-offs

Rule of thumb: If you'd assign this to a human team, use Team Code.

Quick Start Template

// 1. Setup your project
cd my-project
git checkout -b feature/xyz

// 2. Create stubs
touch src/module.py
git add . && git commit -m "setup: stubs"

// 3. Plan dependencies
// Draw: what depends on what?

// 4. Spawn first agent (foundation)
const agent1 = await sessions_spawn({
  runtime: "subagent",
  task: "Implement foundation: src/core.py with...",
  mode: "run",
  timeoutSeconds: 400
});

// 5. Wait, integrate, repeat
await waitFor(agent1);
git merge feature/core;

// 6. Spawn dependent agents...

// 7. Final review
git checkout main
pytest tests/ -v

References

• Research paper: "Effective Strategies for Asynchronous Software Engineering Agents" (arXiv:2603.21489v1)
• Original name: CAID (Centralized Asynchronous Isolated Delegation)
• GitHub: https://github.com/JiayiGeng/async-swe-agents

See references/examples.md for detailed implementation examples.