Brewcode:Teams

<instructions>

Teams

Manage dynamic teams of domain-specific agents with tracking framework.

Arguments: $ARGUMENTS

---

Phase 1: Parse Arguments

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/detect-mode.sh" "$ARGUMENTS" && echo "OK" || echo "FAILED"

Output: MODE:, TEAM_NAME:, PROMPT: (optional). Store all three.

---

Universal Prelude (every mode)

Step 0: Init + Validate + Confirm

1. Output: Mode: {MODE}, Team: {TEAM_NAME}

2. Load environment:

3. If team exists, verify:

   bash "${CLAUDE_SKILL_DIR}/scripts/verify-team.sh" "TEAM_NAME_HERE" && echo "PASS" || echo "FAIL"

4. Formulate action plan for current mode.

5. ASK using AskUserQuestion: "Here's my plan: {plan}. Continue?" Options: "Yes, continue" | "No, I want changes" | "Cancel"

• "changes" -> AskUserQuestion for details, revise plan
• "Cancel" -> STOP

---

Mode: CREATE (9 phases)

C1: Project Analysis

Spawn 3-5 Explore agents in ONE message via Task tool:

All via Task(subagent_type="Explore"). Consolidate into single analysis document.

C2: Team Proposal (interactive)

Based on analysis + PROMPT (if provided), propose 3 variants via AskUserQuestion:

Minimal (5 agents):
| Agent | Domain | Mission |

Balanced (10-12 agents) -- Recommended:
| Agent | Domain | Mission |

Maximum (15-20 agents):
| Agent | Domain | Mission |

Options: "Minimal (5)" | "Balanced (recommended)" | "Maximum (15-20)" | "Custom -- I'll specify"

If "Custom" -- second AskUserQuestion for free input. Final confirmation of agent list before proceeding.

C2.5: Model Selection (AskUserQuestion)

"Default model for domain agents: Opus (most reliable)."

Options: "Opus (recommended)" | "Sonnet" | "Haiku" | "Mixed -- I'll choose per agent"

If "Mixed" -- ask model per agent in C3. Store as DEFAULT_MODEL (default: opus).

C3: Agent Creation (agent-creator x N)

1. Read ${CLAUDE_SKILL_DIR}/references/agent-template.md 2. For each agent, spawn Task(subagent_type="brewcode:agent-creator") with: placement=.claude/agents/, model=DEFAULT_MODEL (or per-agent), context=template + mission + domain + project analysis + colleague list. Agent description <= 100 chars (optimal ~80), single line, role + 2-3 triggers, no <example> blocks. 3. Batch 3-4 agents in parallel per message 4. After each batch, optimize:

   Skill(skill="brewtools:text-optimize", args="-l .claude/agents/{agent-name}.md")

C4: Framework Setup + Verification

1. Create team directory:

   mkdir -p ".claude/teams/TEAM_NAME_HERE" && echo "OK" || echo "FAILED"

2. Write from ${CLAUDE_SKILL_DIR}/references/framework-files.md templates: team.md (fill with real agent data), touch trace.jsonl

3. Verify:

   bash "${CLAUDE_SKILL_DIR}/scripts/verify-team.sh" "TEAM_NAME_HERE" && echo "PASS" || echo "FAIL"

STOP if FAIL -- fix missing files before continuing.

4. AskUserQuestion: final report + suggest /brewcode:teams status {TEAM_NAME}

C5: Quorum Review

Spawn 3 reviewer agents in ONE message via Task tool:

Each reads ALL agent files in .claude/agents/ and outputs:

FILE: .claude/agents/{name}.md
SEVERITY: critical/important/minor
ISSUE: description
FIX: suggested fix

C6: Consensus Filter

Quorum threshold: 2/3 agreement = confirmed. Match criteria: same file + same area (+/- 5 lines or same section) + same category (instruction/domain/architecture/trigger).

C7: Verification

Task(subagent_type="brewcode:reviewer", prompt="
  Verify these findings against actual agent files. For each:
  1. Read the agent file
  2. Check if the issue actually exists
  3. Mark: VERIFIED or FALSE_POSITIVE
  {confirmed_findings}
")

Filter out false positives. Final list = verified critical + important issues.

C8: Fix

For each verified critical/important issue:

Task(subagent_type="brewcode:agent-creator", prompt="
  Fix this issue in {agent_file}:
  ISSUE: {description}
  FIX: {suggested_fix}
  SEVERITY: {severity}
  Read the file, apply the fix, validate.
")

Batch: up to 3 parallel per message. Minor issues skipped.

C9: Re-verify

Task(subagent_type="brewcode:reviewer", prompt="
  Re-verify these fixes. For each:
  1. Read the fixed agent file
  2. Check original issue is resolved
  3. Check no regression introduced
  Mark: FIXED or REGRESSION
  {fixes_applied}
")

To skip review pipeline: add --skip-review to create arguments.

To run review on existing team: /brewcode:teams update {TEAM_NAME} --review

---

Mode: STATUS (read-only)

No modifications. Read + report only.

1. Read .claude/teams/{TEAM_NAME}/team.md 2. Read trace data:

   bash "${CLAUDE_SKILL_DIR}/scripts/trace-ops.sh" read ".claude/teams/{TEAM_NAME}" && echo "OK" || echo "FAILED"

Parse JSONL: group by src (agent) and k (kind). Compute per-agent stats from k=track (took/refused/completed/failed counts), issues from k=issue, insights from k=insight.

Output:

# Team Status: {TEAM_NAME}

## Summary
| Metric | Value |
|--------|-------|
| Agents | {N} |
| Tasks tracked | {N} |
| Success rate | {%} |
| Open issues | {N} (high: {N}, critical: {N}) |
| Insights | {N} |
| Last activity | {date} |

## Per Agent
| Agent | Tasks | Success | Refused | Issues | Insights | Health |
|-------|-------|---------|---------|--------|----------|--------|

## Recommendations

Health:

Recommendations: underperformers -> suggest /brewcode:teams update; >200 trace rows -> suggest cleanup; 0 activity -> suggest review.

No AskUserQuestion -- purely informational.

---

Mode: UPDATE (self-reflection)

U1: Load & Parse

CURSOR=$(bash "${CLAUDE_SKILL_DIR}/scripts/trace-ops.sh" cursor ".claude/teams/{TEAM_NAME}")
bash "${CLAUDE_SKILL_DIR}/scripts/trace-ops.sh" read ".claude/teams/{TEAM_NAME}" --since "$CURSOR" && echo "OK" || echo "FAILED"

If cursor empty: all entries returned. If team not found -> STOP. If cursor exists and <10 post-cursor entries: expand to last 30 days.

U2: Analyze Performance

Filter post-cursor trace: k=track for task stats, k=issue for problems, k=insight for patterns.

U3: Present & Confirm

ASK using AskUserQuestion with analysis table and proposed actions (Update/Delete/No changes per agent). Options: "Apply all" | "Let me choose" | "Show detailed analysis"

If "Let me choose" -> AskUserQuestion per agent. If "Show detailed" -> output full stats, then re-ask.

U4: Apply Changes

Immutable traits (Name, Base Role) -> delete + create new. Mutable traits (Character, Instructions) -> update during tuning.

Update team.md with current state and Last update date.

Set cursor:

bash "${CLAUDE_SKILL_DIR}/scripts/trace-ops.sh" cursor ".claude/teams/{TEAM_NAME}" set "$(date -u +%Y-%m-%dT%H:%M:%SZ)" && echo "✅" || echo "❌ FAILED"

---

Mode: CLEANUP

Read ${CLAUDE_SKILL_DIR}/references/cleanup-flow.md and execute step by step:

1. Overview scan -> show trace.jsonl entry counts by kind 2. AskUserQuestion: what to clean (all / trace data / agents / step-by-step) 3. Trace cleanup (if selected) -- AskUserQuestion with archive options 4. Agents review (if selected) -- AskUserQuestion per agent if needed 5. Summary report

Archive: entries appended to .claude/teams/{TEAM_NAME}/trace-archive.jsonl. Cursor reset after cleanup.

---

Universal Epilogue (every mode)

Step E1: Update CLAUDE.md (conditional)

Only for modes that change team composition (CREATE, UPDATE with removals, CLEANUP with agent removal):

ASK using AskUserQuestion: "Update team info in CLAUDE.md?" Options: "Yes, in project CLAUDE.md" | "Yes, in .claude/CLAUDE.local.md" | "No, skip"

Format to write:

## Teams

Team: {TEAM_NAME} | Agents: {N} | Status: active

| Agent | Domain | Mission |
|-------|--------|---------|

Protocol: agents self-select tasks, trace in `.claude/teams/{TEAM_NAME}/trace.jsonl`.
Manage: `/brewcode:teams [status|update|cleanup]`

Step E2: Final Status

Always run STATUS mode logic after all changes: read team.md + trace.jsonl, compute stats, output Team Status table.

---

Output Format

# teams [{MODE}]

## Detection
| Field | Value |
|-------|-------|
| Arguments | `{raw args}` |
| Mode | `{MODE}` |
| Team | `{TEAM_NAME}` |
| Prompt | `{PROMPT or none}` |

## Results
{Mode-specific output}

## Next Steps
- {recommendations}

---

Error Handling

</instructions>

Teams

Create and manage dynamic teams of domain-specific agents with a tracking framework. Analyzes your project, proposes 5-20 specialized agents, creates them, and sets up performance tracking.

Quick Start

/brewcode:teams create my-project

Analyzes the project, proposes agent variants (minimal/balanced/maximum), creates agents in .claude/agents/, and sets up a tracking framework.

Modes

Examples

# Create a team
/brewcode:teams create backend

# Create with a guiding prompt
/brewcode:teams create api-team "Focus on REST API, auth, and database layers"

# Check performance
/brewcode:teams status backend

# Tune agents based on tracking data
/brewcode:teams update backend

# Clean up after a long project phase
/brewcode:teams cleanup backend

Common Mistakes

# BAD: No team name
/brewcode:teams create
# -> Team name is required

# BAD: Update on team with no tracking data
/brewcode:teams update new-team
# -> All agents classified as Inactive -- run some tasks first

# BAD: Status on non-existent team
/brewcode:teams status ghost-team
# -> Error: "Team not found. Run /brewcode:teams create ghost-team"

File Structure

After /brewcode:teams create my-team:

.claude/
  agents/
    agent-one.md          # Created agents (5-20 depending on variant)
    agent-two.md
  teams/
    my-team/
      team.md             # Roster: agent list, domains, missions, status
      trace.jsonl         # Unified log: tasks, issues, insights (append-only JSONL)

How Agents Work

Created agents follow the Task Acceptance Protocol -- they self-select tasks based on domain fit, record acceptance/refusal in trace.jsonl via trace-ops.sh, and log issues and insights as they work.

The update mode uses this data to tune agent instructions, replace underperformers, or remove inactive agents.

CREATE Flow

/brewcode:teams create my-project
    |
    v
[C1] Project Analysis --- 3-5 Explore agents in parallel
    |
    v
[C2] Team Proposal ------ 3 variants + user confirmation
    |
    v
[C2.5] Model Selection -- opus / sonnet / haiku / mixed
    |
    v
[C3] Agent Creation ----- agent-creator x N (batches of 3-4)
    |
    v
[C4] Framework Setup ---- team.md + trace.jsonl + verification
    |
    v
[C5] Quorum Review ------ 3 domain expert reviewers in parallel
    |
    v
[C6] Consensus Filter --- 2/3 quorum, skip minor issues
    |
    v
[C7] Verification ------- cross-check confirmed findings vs actual files
    |
    v
[C8] Fix ---------------- agent-creator fixes critical + important
    |
    v
[C9] Re-verify ---------- check fixes, retry if regression (max 2 cycles)
    |
    v
[E1] CLAUDE.md Update --- optional, user-confirmed
[E2] Final Status ------- always runs STATUS

Review and Fix Pipeline (C5-C9)

After agent creation, a quality pipeline validates the team:

1. Quorum Review (C5) — 3 independent reviewer agents (domain experts matching the team) analyze every created agent in parallel: instruction quality, domain accuracy, tool selection, triggers, model fit 2. Consensus Filter (C6) — issues confirmed by 2/3 reviewers pass quorum. Minor (cosmetic) issues are logged but skipped. Only critical and important proceed 3. Verification (C7) — verification agent cross-checks each finding against actual agent files. False positives filtered. Severity: critical (broken) / important (degraded) / minor (cosmetic) 4. Fix (C8) — agent-creator fixes critical and important issues. Minor skipped 5. Re-verify (C9) — verification agent re-checks every fix. Regression goes back to Fix (max 2 cycles)

Skip with --skip-review. Run separately: /brewcode:teams update <name> --review

Task Acceptance Protocol

Each agent follows a 3-step self-selection before accepting a task:

Accept flow: All 3 checks pass -> accept task -> execute -> log to trace.jsonl -> complete/fail

Refuse flow: Any check fails -> log refusal reason to trace.jsonl -> suggest alternative agent

Dynamic Agent Resolution

When other skills (spec, plan, start, convention, standards-review) spawn agents, they check for team agents first:

If a team agent refuses a task (Task Acceptance Protocol), the skill re-delegates to the next priority level. Max 2 retries before falling back to plugin agents.

Related Skills

Documentation

Full docs: teams

<!-- TEMPLATE for agent-creator. Fill {PLACEHOLDERS} based on project analysis. Model: opus (default, confirmed by user during C2.5 step). Placement: .claude/agents/{agent-name}.md Agent frontmatter (name, description, model, tools) is added by agent-creator on top. description: <= 100 chars (optimal ~80), single line, role + 2-3 triggers, no <example> blocks. -->

{AGENT_NAME}

Mission: {one sentence} Domain: {area of responsibility} Character: {brief characteristic -- CAN change during update} Last Updated: {ISO_DATE}

Immutable Traits (do NOT change during update)

• Name: {AGENT_NAME}
• Base Role: {role -- if role doesn't fit, delete agent and create a new one}

Update Protocol

Managed by /brewcode:teams update. Manual edits to trace.jsonl not recommended — use trace-ops.sh. On update: character and instructions may be updated based on trace data.

Task Acceptance Protocol

Before accepting ANY task:

Tracing (optional — 1 attempt max)

Read BC_PLUGIN_ROOT value from the TOP of your prompt (injected by hook as plain text, e.g. BC_PLUGIN_ROOT=/Users/.../brewcode).

If present — substitute the literal path into the bash commands below (do NOT use $BC_PLUGIN_ROOT as a shell variable — it is NOT an env var).

If NOT present or bash fails — skip tracing silently and proceed to your task.

On Refuse:

1. Trace (optional): bash "<BC_PLUGIN_ROOT value>/skills/teams/scripts/trace-ops.sh" add ".claude/teams/{TEAM}" "$SID" "{AGENT_NAME}" "track" "refused" "<reason>" 2. Return to manager immediately

On Accept:

1. Trace (optional): bash "<BC_PLUGIN_ROOT value>/skills/teams/scripts/trace-ops.sh" add ".claude/teams/{TEAM}" "$SID" "{AGENT_NAME}" "track" "took" "<task>" 2. Execute the task — this is the priority, do NOT block on trace failure

On Completion:

1. Trace (optional): bash "<BC_PLUGIN_ROOT value>/skills/teams/scripts/trace-ops.sh" add ".claude/teams/{TEAM}" "$SID" "{AGENT_NAME}" "track" "completed" "<result>" (or "failed")

Domain Instructions

{Domain-specific instructions -- filled by agent-creator}

Trace Instructions (optional — best effort)

BC_PLUGIN_ROOT is injected as plain text in your prompt (NOT a shell env var).

Read the value from the top of your prompt and substitute it literally.

If not available or bash fails — skip silently, do NOT retry.

All entries via Bash tool (no Read required, 1 attempt max):

Status: took / refused / completed / failed Severity: low / medium / high / critical Category: pattern / architecture / performance / security / convention / debt

$SID — session ID (8 chars), injected by hook. BC_PLUGIN_ROOT — plugin path, injected as plain text by hook (read from prompt, not env).

Colleagues

{table -- filled when creating the team}

Cleanup Flow

Overview

Interactive cleanup of team trace data and agents. Every destructive action requires user confirmation via AskUserQuestion.

Order of Operations

1. Overview scan — show sizes 2. Trace cleanup (if selected) 3. Agents review (if selected) 4. Summary report

Step 1: Overview Scan

Read trace.jsonl via trace-ops.sh read, calculate entry counts by kind.

AskUserQuestion:
  question: |
    Cleanup for team {TEAM_NAME}:
    
    | Data | Entries | Size |
    | trace.jsonl (track) | {N} entries | — |
    | trace.jsonl (issue) | {N} entries | — |
    | trace.jsonl (insight) | {N} entries | — |
    | Total | {N} entries | {KB} |
    | Agents | {N} agents | — |
    
    What to clean?
  options:
    - "All — full cleanup"
    - "Trace data only"
    - "Agents review only"
    - "Let me choose step by step"

Step 2: Trace Cleanup

AskUserQuestion:
  question: |
    trace.jsonl: {N} entries
    Oldest: {date}, Newest: {date}
    By kind: track={N}, issue={N}, insight={N}
    
    Options:
  options:
    - "Archive all → trace-archive.jsonl, start fresh"
    - "Keep last 30 days, archive rest"
    - "Keep last 50 entries, archive rest"
    - "Keep only issues + insights, archive track entries"
    - "Skip"

Archive logic:

• Read current trace.jsonl
• Split into keep/archive based on selection
• Append archived entries to trace-archive.jsonl (create if not exists)
• Rewrite trace.jsonl with kept entries only
• Reset trace.cursor via trace-ops.sh cursor <dir> set ""

EXECUTE using Bash tool:

# Example: archive all, start fresh
cat ".claude/teams/{TEAM}/trace.jsonl" >> ".claude/teams/{TEAM}/trace-archive.jsonl" && \
printf '' > ".claude/teams/{TEAM}/trace.jsonl" && \
bash "$BC_PLUGIN_ROOT/skills/teams/scripts/trace-ops.sh" cursor ".claude/teams/{TEAM}" set "" && \
echo "✅ Archived" || echo "❌ FAILED"

Step 3: Agents Review

Show inactive/problematic agents:

AskUserQuestion:
  question: |
    Inactive agents (0 tasks or last activity >30 days):
    | Agent | Last activity | Tasks total |
    | ... | ... | ... |
    
    Action?
  options:
    - "Delete all inactive"
    - "Let me choose per agent"
    - "Keep all"

If "per agent" — loop AskUserQuestion for each:

AskUserQuestion:
  question: "Agent {name}: {domain}, last active {date}, {N} tasks total. Delete?"
  options: ["Delete", "Keep"]

On delete:

1. Remove .claude/agents/{name}.md 2. Update team.md: set status to removed 3. Record via trace-ops.sh: bash "$BC_PLUGIN_ROOT/skills/teams/scripts/trace-ops.sh" add ".claude/teams/{TEAM}" "$SID" "system" "track" "completed" "removed {name}: cleanup"

Step 4: Summary

Output report:

# Cleanup Summary: {TEAM_NAME}

| Action | Details |
|--------|---------|
| Trace entries archived | {N} |
| Trace entries kept | {N} |
| Agents removed | {list or "none"} |
| Archive file | trace-archive.jsonl |
| Cursor | reset |

Archive File Format

Archive files live in .claude/teams/{TEAM_NAME}/ alongside trace.jsonl.

trace-archive.jsonl — same JSONL format as trace.jsonl. Entries appended on each cleanup. Multiple cleanups accumulate in the same archive file.

Framework Files Reference

Templates for .claude/teams/{TEAM_NAME}/ directory. All placeholders ({TEAM_NAME}, {DATE}, {N}, {CWD}) replaced at creation time. DATE format: YYYY-MM-DD.

team.md uses Edit tool. trace.jsonl is append-only via Bash (trace-ops.sh add).

---

1. team.md

# Team: {TEAM_NAME}

| Field | Value |
|-------|-------|
| Created | {DATE} |
| Last update | {DATE} |
| Agents | {N} |
| Project | {CWD} |

## Agents

| Agent | Domain | Mission | Status | Updated |
|-------|--------|---------|--------|---------|

Status values: active, inactive, updating, removed

---

2. trace.jsonl

Empty file at creation. Agents append via trace-ops.sh add.

Format: JSONL — one JSON object per line: