Skill: simoncatbot/team-code (version 1.0.0)

--- name: team-code description: 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 parallel on different parts of your codebase—each in their own isolated branch, with automatic integration and verification. Use for multi-file features, complex refactors, or any project where parallel development beats solo coding. Works like pair programming, but with as many agents as your task needs (2-4 recommended, max 8). --- # 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: ```bash 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 ```javascript // 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 }); ``` ```javascript // 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 ```bash # 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 ```bash # 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** ```bash # 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: ```bash 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: ```json { "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 ```javascript // 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](references/examples.md) for detailed implementation examples.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)