teams — set up agent batch
Caution
Generic agents handle everything — and excel at nothing. A frontend task routed to a generic backend agent loses domain context, triggers wrong tools, and produces half-correct results. Claude Code has no native way to scope agents to domains or enforce routing between them.
Tip
/brewcode:teams create analyzes your codebase, proposes agent variants (Minimal / Balanced / Maximum), creates each agent via quorum-reviewed scaffolding, and sets up a trace.jsonl log so the team self-improves via /brewcode:teams update.
Quick reference
| Field | Value |
|---|---|
| Command | /brewcode:teams |
| Arguments | create <name> [prompt], status <name>, update <name>, cleanup <name> |
| Model | opus |
| Tools | Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion |
When to use
- New project onboarding — turn architectural analysis into a ready-to-use agent roster
- Large codebase — split domains (API, data, frontend, infra, testing) so each agent stays focused
- Repeated failures — a specific domain keeps producing poor results;
createorupdatethat agent - Maintenance —
statusto see health,updateto tune underperformers,cleanupto archive old trace data
Examples
# Create a balanced team for the current project
/brewcode:teams create my-team
# Create with a free-form hint about what matters
/brewcode:teams create my-team "focus on API and data pipeline domains"
# Check team health and success rates
/brewcode:teams status my-team
# Tune agents that are underperforming
/brewcode:teams update my-team
# Archive old trace data, remove inactive agents
/brewcode:teams cleanup my-teamModes
| Mode | Command | What it does |
|---|---|---|
create | /brewcode:teams create <name> [prompt] | Analyze codebase → propose team → create agents → quorum review → framework setup |
update | /brewcode:teams update <name> | Read trace data → classify agents → tune or replace underperformers |
status | /brewcode:teams status <name> | Read-only health report: success rates, open issues, insights, recommendations |
cleanup | /brewcode:teams cleanup <name> | Archive trace entries, remove inactive agents, reset cursor |
Flow
- Parse + confirm
Mode, team name, and optional prompt are extracted from arguments. Current team state (if any) and agent roster are loaded. The plan is shown via
AskUserQuestionbefore any mutation. - Project analysis
3–5 Explore agents run in parallel: code structure, existing agents, tech stack, CI/CD, domain boundaries. Results are consolidated into a single analysis document before the team proposal.
- Team proposal + model selection
Three variants presented: Minimal (5 agents), Balanced (10–12, recommended), Maximum (15–20). User selects variant and default model (Opus / Sonnet / Haiku / Mixed). Final agent list confirmed before creation.
- Agent creation
Agents created in batches of 3–4 in parallel via
agent-creator. Each receives: unified template, domain mission, colleague list, project context. After each batch,/brewtools:text-optimizecompresses agent instructions. - Quorum review pipeline (C5–C9)
3 reviewers analyze all agents in parallel (instruction quality, domain accuracy, architecture consistency). Issues confirmed by 2/3 pass the threshold. A verification agent filters false positives.
agent-creatorfixes critical and important findings. Re-verify confirms no regressions. Skip with—skip-review. - Framework setup
.claude/teams/<name>/team.md(roster) andtrace.jsonl(empty log) created.verify-team.shvalidates structure — stops if anything is missing. - Epilogue: CLAUDE.md + final status
Optionally writes a Teams section to project or local CLAUDE.md. Always outputs the full Team Status table (agents, tasks tracked, success rate, open issues) so you know exactly what was created.
Internals
Framework files
| File | Purpose |
|---|---|
.claude/teams/<name>/team.md | Agent roster: names, domains, missions, health status. Source of truth for team composition. |
.claude/teams/<name>/trace.jsonl | JSONL log per session: tasks (took/refused/completed/failed), issues (by severity), insights (by category). Written via trace-ops.sh add — append-only, ~96% token savings vs full reads. |
.claude/teams/<name>/trace-archive.jsonl | Archived entries after cleanup. Cursor reset after archiving. |
Task Acceptance Protocol
Every generated agent contains a self-selection protocol. When a task arrives, the agent evaluates three questions before accepting:
- Domain check — “Is this my domain?” If not, refuses and names a better-suited colleague from
team.md. - Duplicate check — “Has this been done?” If yes, refuses and links the existing result in
trace.jsonl. - Best candidate — “Is a colleague better suited?” If yes, redirects without accepting.
Agent health classification
| Health | Criteria | Action |
|---|---|---|
| Green | >70% success, active in recent tasks | No action needed |
| Yellow | 30–70% success or many refusals | Tune instructions via update |
| Red | <30% success or inactive | Replace or remove via update |
Immutable vs mutable traits
| Trait | Mutable? | If wrong |
|---|---|---|
| Name | No | Delete + create new |
| Base role | No | Delete + create new |
| Character | Yes | Update during tuning |
| Instructions | Yes | Update during tuning |
Integration with core skills
Team agents are preferred by /brewcode:spec, /brewcode:plan, and /brewcode:start when matching domains are found. Priority: team agent → project agent → plugin agent.
Agents skill
Create individual domain agents — the same scaffolding teams use under the hood.
E2E skill
End-to-end task execution using a team: spec → plan → start in one flow.
GitHub source
Source code, scripts, and framework file templates.
Brewcode overview
All brewcode skills — setup, spec, plan, start, review, and more.
Updating plugins
/brewtools:plugin-update to check and update the brewcode plugin suite in one command.
See the FAQ for details.