teams-setup — install an agent team

Quick reference

Field	Value
Command	/brewcode:teams-setup
Arguments	[status [name] | install [name] [prompt] | upgrade [name] | enable [name] | disable [name] | uninstall [name] | purge [name]]
No-arg default	status of the first existing team, install of a team named default when none exists
enable / disable	Park/unpark the roster’s agent files (renamed to/from <agent>.md.disabled) — intent-guard is exempt
Version stamping	team.md header + agent frontmatter carry the plugin version; write is refused if the version cannot be resolved
Model	opus
Tools	Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill

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; install or upgrade that agent
• Maintenance — status to see health, upgrade to tune underperformers, uninstall to archive trace data and drop inactive agents, purge to remove the team entirely

Examples

# Install a balanced team for the current project
/brewcode:teams-setup install my-team

# Install with a free-form hint about what matters
/brewcode:teams-setup install my-team "focus on API and data pipeline domains"

# Check team health and success rates
/brewcode:teams-setup status my-team

# Tune agents that are underperforming
/brewcode:teams-setup upgrade my-team

# Park the roster's agent files without deleting anything
/brewcode:teams-setup disable my-team

# Bring a parked team back
/brewcode:teams-setup enable my-team

# Archive trace data, remove inactive agents
/brewcode:teams-setup uninstall my-team

# Delete the team outright — agents, framework dir, trace and its archive
/brewcode:teams-setup purge my-team

Modes

Mode	Command	What it does
status	/brewcode:teams-setup status <name>	Read-only health report: success rates, open issues, insights, recommendations
install	/brewcode:teams-setup install <name> [prompt]	Analyze codebase → propose team (+ fixed intent-guard) → create agents → quorum review → framework setup
upgrade	/brewcode:teams-setup upgrade <name>	Read trace data → classify agents → tune or replace underperformers
enable	/brewcode:teams-setup enable <name>	Move each roster member’s agent file from <agent>.md.disabled back to <agent>.md — reactivates without touching team.md or trace data
disable	/brewcode:teams-setup disable <name>	Park each roster member’s agent file as <agent>.md.disabled — Claude Code stops discovering it, nothing is deleted
uninstall	/brewcode:teams-setup uninstall <name>	Archive trace entries, remove inactive agents, reset cursor
purge	/brewcode:teams-setup purge <name>	Total removal, no menus and no archive: every domain agent from the team.md roster, then .claude/teams/<name>/ including trace-archive.jsonl. One explicit confirmation, not recoverable

purge never deletes .claude/agents/intent-guard.md. That file is shared with /brewcode:superreview-setup and may belong to an install that has nothing to do with this team; purge reports it as kept. A team name that does not exist stops the run — nothing is “purged” that was never installed.

Flow

Delegation

One subagent = ONE bounded unit — here, ONE agent file: roughly 5 files, roughly 10 steps. A 12-agent roster is 12 spawns, batched 3–4 per message in parallel; the C5 review and the C8 fix pass fan out the same way.

Every spawn prompt carries six fields. A bare one-line task is never enough:

Field	Content
GOAL	the overall task and why it exists — the point beyond the file edit
ROLE	what this agent owns; what it must NOT touch
SCOPE	exact paths/commands in bounds + explicit out-of-bounds
CONTEXT	what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs
CONSUMER	who or what uses the result next, and the shape it must fit
DONE	acceptance criteria + the exact report shape you want back

In C3 that means each agent-creator owns exactly .claude/agents/{name}.md, is told which colleagues its batch-mates are building (stay off their domains, do not duplicate their triggers), and knows its description line lands in the team.md roster row. In C8 the fixer is told the finding is already verified by 2/3 reviewers plus the C7 double-check — do not re-litigate it — and that C9 will re-verify the same file for regressions.

Every code/test spawn brief in this skill also carries the etalon-first instruction verbatim: find the closest well-built counterpart in the repo and follow its principles, in addition to conventions, rules and docs — never instead of them.

Intent guard

Property	Value
Counted in the roster size?	No — outside 5 / 10-12 / 15-20, cannot be dropped
Compares	What was ASKED (tracker ticket, Slack thread, quoted requirements, the user’s verbatim words, or the chat request itself) against what was DELIVERED
Source hierarchy	Five tiers; tier 1 (external/original) always wins and is labeled in the report. An absent tier 1 is normal — the chat request becomes the top source. Sources are never invented
Evidence	Cheap only: session transcript, file/directory names, git diff --stat, dependency manifests, doc headings — never full-file code reads, builds, tests, or linters
Drift it hunts	Building something other than asked, over-engineering for an unplanned scale, interface/factory bloat where a direct implementation was requested, file explosion, test bloat against a minimal-tests policy, an unnecessary dependency, architecture substitution, ignored CLAUDE.md/rules instructions, silent skips, over-claimed completion, unrequested artifacts — open-ended examples, not a closed checklist
Tools	Read-only. Invoked explicitly by name at review time only — never competes for auto-activation with the team’s development agents

One writer, shared with superreview. teams-setup does not author intent-guard.md. It runs generate.sh emit-agent from the sibling /brewcode:superreview-setup skill, which creates-or-reuses the file and prints INTENT_GUARD: CREATED or INTENT_GUARD: REUSE. A USABLE existing agent is reused untouched — usable meaning non-empty, carrying name: intent-guard frontmatter, and free of unresolved placeholders. An empty, truncated or placeholder-laden file is treated as absent and recreated. agent-creator is spawned only on CREATED, to replace three seeded generic blocks (project invariants, drift examples, evidence commands) with project-specific content; it never authors the file.

Excluded from:

Flow	Why
Quorum reviewer role (C5/C7/C9)	Not a general reviewer — no code domain to judge others by
Implementation ownership	Never accepts a build/fix task
uninstall inactive-agent sweep	Emits no trace records by design; zero activity is normal, not grounds for deletion
text-optimize post-processing	Would reword its deliberately short, review-only description into a normal domain description

Legacy teams. verify-team.sh does not hard-fail a team created before this change: missing team.md row → WARN with a runnable remediation command, still passes. Row listed but .claude/agents/intent-guard.md missing → real FAIL.

Tracing

Every generated agent logs what it took, refused, completed or failed to .claude/teams/<name>/trace.jsonl, and that log is the only input status and upgrade have. The agent reaches it through a project-local copy of the tracer:

bash ".claude/teams/<name>/trace-ops.sh" add ".claude/teams/<name>" "$SID" "<agent>" "track" "took" "<task>"

The path is repo-relative on purpose. A file in .claude/agents/ is not plugin-owned, so ${CLAUDE_PLUGIN_ROOT} is not substituted inside it and no *_PLUGIN_ROOT environment variable exists there — a plugin path in a generated agent resolves to nothing and the call silently no-ops. Install step C4 therefore cps trace-ops.sh into the team directory and stops the run if the copy fails.

Guardrails in every team agent

The agent template carries two blocks, so every DOMAIN member of the team inherits them (intent-guard comes from a different template — see the third row):

Guardrail	Applies to	What it says
Return Contract	Every team agent, unconditionally	A named ## Return Contract section: verdict first, <=30 lines, path:line, no file bodies / command output / logs / preamble. Bulk material goes to .claude/reports/<YYYYMMDD-HHMMSS>_<name>/ and only the path returns. When /brewtools:agent-return-setup is installed, the same guard enforces it at the token level (~1000 est-tokens blocks for compression, ~2500 routes the detail to a report).
Scope Fit	Only agents whose domain writes code, scripts, SQL, schemas or infra	Build for the actual scale and the problems that exist today, not imagined load or speculative abstraction — a 10-user app does not need hardening against DB lock contention. After finishing, one pass: can this be simpler — fewer files, less config, less indirection?
Etalon-first	Same gating as Scope Fit — code/script/SQL/schema/infra domains only	Before writing a class, module or test, find the closest well-built existing one in this repo (.claude/convention/* checked first) and take its principles — additive to conventions, rules and docs, never a replacement
Anti-drift review	intent-guard only — not built from these two blocks	Compares ASKED vs DELIVERED at review time, explicit invocation only — see Intent guard above

agent-creator deletes the Scope Fit and Etalon-first pair together for research, docs, and review-only domain members; the Return Contract stays in all team agents, including intent-guard, which carries it via its own ## Output section rather than this one. This matters most on a 12-agent roster, where a single verbose member can cost more context than the rest of the batch combined.

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-ops.sh	The tracer itself, copied from the plugin at install (C4) and re-copied on every upgrade. The only tracing path a generated agent can resolve. Deleted by purge, kept by uninstall.
.claude/teams/<name>/trace-archive.jsonl	Archived entries after uninstall. Cursor reset after archiving. purge deletes this file along with everything else.

Version and ownership

Field	Where	Value
Header rows	team.md: | Version |, | Generated by |, | Last update |	Plugin version, brewcode:teams-setup, install/upgrade date
Frontmatter	Each .claude/agents/<member>.md	doc_type: llm, version: "X.Y.Z", generated_by: "brewcode:teams-setup", last_updated: "YYYY-MM-DD"
Source	detect-mode.sh reads .claude-plugin/plugin.json	Resolves before any write; if it cannot, the run exits 1 (ERROR:cannot resolve plugin version) instead of stamping a fake value
Staleness check	/brewcode:setup-status	Reads the | Version | row and flags a team installed at an older plugin version than the one currently running

Task Acceptance Protocol

Every generated agent contains a self-selection protocol. When a task arrives, the agent evaluates three questions before accepting:

1. Domain check — “Is this my domain?” If not, refuses and names a better-suited colleague from team.md.
2. Duplicate check — “Has this been done?” If yes, refuses and links the existing result in trace.jsonl.
3. 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 upgrade
Red	<30% success or inactive	Replace or remove via upgrade

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 any skill that spawns domain work when matching domains are found. Priority: team agent → project agent → plugin agent.