Teams Setup

---
name: teams-setup
description: "Creates and manages dynamic teams of domain agents. Triggers: create team, agent team, team status, cleanup team."
---

# Codex team coordination

Use collaboration agents only when the user or project instructions explicitly request a team. Split work into bounded independent tasks, keep one owner per file or surface, exchange evidence through collaboration messages, and synthesize results in the parent session. Do not invent unsupported agent parameters or create persistent team configuration unless requested.

<!-- brewcode-meta: version=6.1.4 content_version=6.1.0 generated_by=brewcode:teams-setup -->

## Native authority

Manage persistent project teams under `.codex/teams/{TEAM_NAME}/` and agents under `.codex/agents/`. Domain agents are native TOML parsed with Python `tomllib`, never renamed Markdown. Each has exactly the three string keys `name`, `description`, and `developer_instructions`; `description` is one nonempty line of at most 100 characters. Read applicable `AGENTS.md`, preserve unrelated files, use only adjacent scripts/references, and never edit installed caches.

Before every `team.md` write, resolve `REPORT_ROOT` from the narrowest applicable durable project guidance; an exact declared project-relative path wins, and guidance silence falls back to `.codex/reports`. Every slash-separated segment must match `^[A-Za-z0-9._-]+$` and must not equal `.` or `..`; reject absolute/home-relative paths, doubled slashes, unresolved tokens, control characters, and shell metacharacters including `$()`, backticks, `;`, `&`, and `|`. Equal-specificity conflicting report-root directives -> STOP instead of selecting either. Dusk guidance therefore resolves exactly `.codex/reports`, never a tool-default path.

## Invocation and approval

Resolve exactly one mode in this order: `status`, `install`, `upgrade`, `enable`, `disable`, `uninstall`, `purge`. An explicit mode wins. With no mode, choose `status` when the named team exists; otherwise choose `install` and team name `default` only when no name was supplied. Invalid detector output stops the run.

Before any action, print one `PLAN — brewcode:teams-setup` block with `INPUT`, resolved `MODE` and reason, `SCOPE` (team, roster, exact paths), `DO`, and `RESULT`. `status` asks nothing. Every mutating mode requires `request_user_input` approval after the plan and before the first write; changed scope requires a revised plan and approval. Destructive modes additionally name every deletion.

Run `scripts/detect-mode.sh`, inventory `.codex/teams/` and `.codex/agents/`, read an existing roster/trace, and run `scripts/verify-team.sh {TEAM_NAME}` when the team exists. A missing team stops every mode except `install`; an existing team stops `install` unless the user approves routing to `upgrade`.

An absent `trace.jsonl` is valid before the first event or after cleanup: status reports zero events, verification remains read-only, and `trace-ops.sh add` creates it safely on the first write. A present trace target must be a non-symlink regular file.

Before any team mutation, run the read-only, offline preflight `python3 -I -S scripts/prepare-tokenizer.py check`. If the prerequisite is missing, retain and report its repair command; `status` does not run team verification, while a mutating mode waits for its explicit approval. Only after that approval, run `python3 -I -S scripts/prepare-tokenizer.py prepare && python3 -I -S scripts/prepare-tokenizer.py check`; this is the sole tokenizer network/install path, and failure stops the mode. `verify-team.sh` and token counts use isolated `prepare-tokenizer.py run count-tokens.py` without network, installation, fallback, host Python injection, or an unverified runtime.

## Mode: status

Read `team.md` and `trace.jsonl` through `scripts/trace-ops.sh read`. Report domain-agent count, active/disabled/missing state, took/refused/completed/failed totals, success rate, issues by severity, insights, last activity, per-agent health, policy, verifier result, and actionable recommendations. Do not write, delegate, or request approval.

## Mode: install

### C1-C2: analysis and approved roster

Analyze current architecture, domains, stack, tests/CI, existing Codex agents, project guidance, and cross-team name ownership. Use bounded collaboration only because this invoked skill explicitly requests a team. Propose minimal, balanced, and maximum domain rosters plus fixed review-only `intent-guard`; show unique names, domains, missions, exclusions, and conflicts. The user must approve the final roster before any team or agent file is written. Recheck every approved name with `scripts/agent-owners.sh`; a taken, invalid, parked, or unknown owner stops creation.

### C2.6: shared-contract bootstrap

Before any domain agent write, instantiate `references/framework-files.md` into `.codex/teams/{TEAM_NAME}/team.md` with metadata, validated `REPORT_ROOT`, policy `required`, the exact shared sentence "`intent-guard` is review-only, keeps its own output contract, and never implements.", the fixed guard row, and zero domain rows. Initialize trace storage, copy the project-local tracer, and substitute every placeholder. Then call `<plugin-root>/skills/superreview-setup/scripts/emit-intent-guard.sh <project-root>` so the create-only emitter atomically creates the absent guard before the full `verify-team.sh` bootstrap check. A non-symlink regular file is reused only after exact normalized allowlist validation; invalid regular files, symlinks, and nonregular targets stop creation without mutation.

### C3-C4: creation and roster finalization

Create one approved `.codex/agents/{name}.toml` per bounded owner from `references/agent-template.md`. Parse before and after writing. Enforce every live or parked domain member description as one nonempty line of at most 100 characters. `developer_instructions` has only the ordered headings `Mission`, `Owned surfaces`, `Exclusions`, `Must-load references`, `Unique invariants`, `Unique verification`; the first must-load item is `.codex/teams/{TEAM_NAME}/team.md`, occurring once. Enforce <=3200 UTF-8 bytes and <=800 exact `tiktoken==0.13.0` `o200k_base` tokens.

For policy `required`, the bootstrap already called the create-only intent-guard emitter: an approved existing non-symlink regular file was reused byte-identically, or an absent target was published atomically without replacement. Invalid, symlink, nonregular, or lost concurrent-create paths fail closed without mutation. Never author or overwrite the guard here. `legacy-absent` exists only on upgrades and gets no guard.

Finalize only successfully parsed agents. Domain names are unique; `Agents` counts domain rows only. `required` has exactly one fixed review-only guard row and its exact shared guard sentence; `legacy-absent` has neither row nor any shared-contract mention of a phantom guard. The complete substituted `team.md` must stay <=2800 characters and <=700 exact `tiktoken==0.13.0` `o200k_base` tokens. `verify-team.sh` fails closed if that pinned tokenizer is unavailable or mismatched and never installs it.

### C5-C7: independent review

C5: spawn three independent reviewers, distinct from creators and never `intent-guard`, to inspect all actual TOML plus `team.md`: one checks schema/headings/ceilings/shared-reference, one domain and trigger accuracy, one overlap/routing/shared-contract placement. C6: retain only same-file, same-area, same-category findings confirmed by at least 2/3; log one-off and minor items without fixing. C7: spawn a new verifier not used in C5 or creation to check each retained finding against the files and mark `VERIFIED` or `FALSE_POSITIVE`. Only verified important/critical issues reach repair.

### C8-C9: repair and reverify

Repair one owned artifact per bounded task, preserve roster identity and foreign work, then use an independent verifier for the original issue and regression checks. Allow at most two repair cycles. Run `verify-team.sh` after every cycle; unresolved checks remain failures and review cannot be skipped.

## Mode: upgrade

Reject parked or live-plus-parked members before writes. Capture an immutable UTC upgrade cutoff before the initial cursor and trace reads; after all work set the cursor to that captured cutoff, never to a new completion-time timestamp, so concurrent trace entries are not skipped. Migrate the shared contract first, re-resolving `REPORT_ROOT` from current project guidance, recording an existing guard row as `required` and absence as `legacy-absent`; required gets the exact shared guard sentence, while legacy-absent gets no guard mention and never synthesizes the role. Preserve legacy agent bytes until this gate passes. Analyze trace evidence, present per-agent keep/tune/replace/remove actions, and obtain approval for roster actions. Touch only approved domain agents, use atomic three-key TOML writes and the current six-heading contract, preserve untouched bytes, re-copy the tracer, update metadata/cursor, then run C5-C9 for touched artifacts.

## Mode: enable

Run `scripts/toggle-team.sh {TEAM_NAME} enable --dry-run`, stop on conflicts/missing members, then restore domain `.toml.disabled` files byte-identically. Never move `intent-guard`. Update roster status/metadata without changing per-agent versions and verify; an all-live team is a no-op.

## Mode: disable

Dry-run the same script, show every move, and after approval park domain `.toml` files as `.toml.disabled` byte-identically. Keep roster, trace, archive, and guard. Update roster status/metadata and verify; an all-parked team is a no-op.

## Mode: uninstall

Route to `references/cleanup-flow.md` interactive cleanup: inventory trace, let the user choose trace/archive and owned domain-agent removals, recheck identifier and cross-team ownership before each deletion, never delete `intent-guard`, preserve declined/foreign files, and report the archive/cursor/result.

## Mode: purge

Route only to `references/cleanup-flow.md` Step P. Enumerate exact domain files and team-directory bytes, request explicit irreversible-purge approval, recheck identifiers/ownership, delete both live and parked owned domain profiles, keep `intent-guard`, then delete only `.codex/teams/{TEAM_NAME}/`. A skipped shared/unknown agent is reported, never forced.

## Completion

After every mutation except a completed purge, run the full `status` control flow and `verify-team.sh`; after purge, prove the team directory is absent. Report exact changed paths, counts, policy, review verdicts, and failures. Agent discovery changes take effect in the next session.