deploy-team

name

deploy-team

description

Dispatch a small team of Claude agents to think through a problem in parallel and return a combined report. Use for research gauntlets (brainstorm / research / attack / validate), pre-launch code audits (security / correctness / simplicity), post-run analysis (positive / adversarial / contextualizer), or blog-coherence audits. Local only — uses Claude Max subscription, no API key, no GPU. Triggers on "deploy a team", "run the gauntlet", "get multiple perspectives on", "audit this before running", "throw agents at this".

/deploy-team — configurable agent teams via Claude CLI

Spawns N claude CLI processes in parallel, each with a distinct role prompt, shared access to a thread, and (optionally) shared context files. Returns a concatenated report the main agent reads and synthesizes.

When to use a team vs a single subagent

• Single subagent (via native Agent tool): focused, single-responsibility work with a known output shape. Example: "research agent: find 3 recent papers on X and summarize."
• Team (/deploy-team): multi-perspective work where agents should see each other's findings and challenge them. Example: "gauntlet a new experiment idea — brainstorm, research, attack, validate."

Invocation

python3 .claude/skills/deploy-team/runtime/orchestrator.py \
    --template gauntlet \
    --topic "should we run the quadratic readout PC control next?" \
    [--context matrix-thinking/KILL_LIST.md EXPERIMENT_LOG.md] \
    [--max-minutes 15]

Or with a custom config instead of a template:

python3 .claude/skills/deploy-team/runtime/orchestrator.py \
    --config path/to/custom-team.json \
    --topic "..."

Templates

• gauntlet — 4 agents: brainstormer, researcher, attacker, validator. For: new ideas. The attacker tries to kill; validator checks survivors.
• pre-launch-audit — 3 agents: security, correctness, simplicity. For: reviewing experiment scripts / new code before GPU time.
• post-run-analysis — 3 agents: positive, adversarial, contextualizer. For: interpreting a completed run from multiple angles.
• blog-coherence — 2 agents: style, factual-alignment. For: verifying a new finding doesn't contradict existing site content.

Custom templates live in .claude/skills/deploy-team/templates/*.json.

Run artifacts

Each run creates .team-runs/<run-id>/:

• config.json — resolved config (template + topic + context)
• thread.md — shared append-only thread (agents post findings for peers)
• context/ — symlinked context files agents can read
• agents/<name>/
  • prompt.txt — the exact prompt sent
  • output.md — agent's final written findings
  • events.jsonl — raw stream-json events (debug)
• REPORT.md — combined report generated by the orchestrator

The main agent reads REPORT.md to act on team output. Run artifacts are gitignored (per-developer, ephemeral).

Hard rules

• Agents are dispatched in parallel by default. They can see each other's thread posts mid-run because the orchestrator re-serves the latest thread.md to each agent on their next iteration (Ralph-loop pattern).
• Agents are instructed to emit AGENT_DONE when finished. The orchestrator terminates each agent on that sentinel OR on max_iterations.
• Context files are exposed via --add-dir <run-dir>/context/ so agents have read access to files outside their working directory. Never use absolute paths outside the run dir in agent prompts.
• Never run this against the GPU pod. Agents are all local, no external compute.
• Default budget: 3 iterations per agent, 8 minutes total wall time. Increase only when an agent genuinely needs more turns.

Failure modes to watch

• Agent hangs on a tool call — watch events.jsonl for >2min silence. Orchestrator kills after max-minutes.
• Agent writes to a path outside its working directory and the write is rejected silently — check for Write tool errors in events.
• Claude CLI rate-limiting — if you hit it, reduce parallel count or wait.