Team Code

Coordinate multiple AI agents as a development team to tackle complex coding projects faster and more accurately. Like having a team of engineers working in...

Security Scan

The skill's instructions and requirements are broadly consistent with its stated purpose (coordinating multiple agents to work in isolated git worktrees), but the SKILL.md assumes local and network developer tools and permissions that the registry metadata does not declare — review those operational assumptions before running it on sensitive repositories.

Purpose & Capability

The skill is an instruction-only coordinator for multi-agent development and the instructions align with that purpose (task planning, spawning subagents, using git worktrees, self-verification, merging). However the manifest declares no required binaries or credentials while the instructions clearly assume availability of git (worktree, commit, merge, push/pull), a runtime (python/node), test runners (pytest), and network/git remote access. This mismatch is an operational omission worth noting.

Instruction Scope

SKILL.md stays within development workflow scope: it tells the manager how to prepare worktrees, spawn agents, run tests, commit, and merge. The instructions do cause agents to run shell commands, access the repo, run tests, and perform network operations (git push/pull), which are consistent with the stated purpose. There are no instructions to read unrelated system files or exfiltrate data to third-party endpoints.

Install Mechanism

No install spec or code files are present (instruction-only), so nothing is written to disk or downloaded by the skill itself. This minimizes supply-chain/install risk.

Credentials

The manifest requests no environment variables or credentials. In practice the workflow expects the agent/manager to have git credentials and network access (push/pull), as well as access to language runtimes and test tooling. Those implicit privileges (repo write access, ability to run arbitrary commands in worktrees) are proportional to the task but should be explicitly acknowledged by the user before granting or running the skill.

Persistence & Privilege

The skill is not always-enabled, does not request special platform privileges in metadata, and does not attempt to modify other skills or system-wide agent settings. It relies on the manager/agent to perform git commits and merges in the user's repositories — a normal operational behavior for a dev coordination tool.

Assessment

This skill is coherent with its goal of coordinating multiple coding agents, but before using it: (1) ensure your environment has git, git-worktree support, the appropriate runtimes (python/node), and test tools (pytest), since SKILL.md assumes them though the manifest does not declare them; (2) run it on a disposable or non-sensitive repo first — agents will create worktrees, run arbitrary commands, commit, merge, and push/pull to remotes using whatever git credentials are available; (3) restrict remote access or use throwaway credentials if you do not want automatic pushes to upstream repos; (4) review agent-generated commits and merge resolutions manually (or via CI) before accepting into main; (5) if you need tighter guarantees, ask for the skill to explicitly document required binaries, network requirements, and any platform APIs it assumes (e.g., sessions_spawn) before broad adoption.

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

Human Team	Team Code
Tech lead assigns tasks	Manager builds dependency graph
Developers work in branches	Agents work in git worktrees
Pull requests for review	Self-verification before commit
Merge conflicts resolved by author	Agent resolves their own conflicts
Code review before shipping	Manager final review

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

Task Type	Team Size	Why
Research/paper reproduction	2	Complex dependencies, manager heavy
Library implementation	4	Clear file structure, parallelizable
API + frontend feature	2-3	Frontend/backend parallel
Simple multi-file refactor	2	Limited parallelism
Never exceed	8	Coordination tax exceeds gains

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

Aspect	Solo Agent	Team Code
Speed	Faster wall-clock	Similar/slower
Accuracy	42-57%	59-68% (+14-26%)
Cost	Lower	Higher
Best for	Quick fixes	Important code

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.