deploy-agent-team

Deploy Agent Team

Deploy a coordinated team of specialized agents from the bopen-tools kit using Claude Code's agent team system. Agents work in parallel on independent tasks and communicate through a shared task list and message bus.

Prerequisites

Agent teams require this env var to be set:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Add to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Without this, TeamCreate will fail.

Critical: Set mode on Every Agent Spawn

WARNING: The default permission mode will block teammates waiting for permission prompts that never arrive, stalling the whole team.

Always set mode: "bypassPermissions" when spawning teammates:

Agent(
  subagent_type: "bopen-tools:designer",
  team_name: "feature-billing",
  name: "designer",
  mode: "bypassPermissions",   # ← REQUIRED
  prompt: "..."
)

See references/permissions-and-isolation.md for all mode options and worktree isolation.

Available Agent Roster (Abbreviated)

Agent	subagent_type	Best for
researcher	bopen-tools:researcher	Libraries, APIs, docs, competitive analysis
nextjs	bopen-tools:nextjs	Next.js, React, Vercel, RSC, app router
designer	bopen-tools:designer	UI, Tailwind, shadcn/ui, accessibility
agent-builder	bopen-tools:agent-builder	AI agent systems, LLM integration, Vercel AI SDK
database	bopen-tools:database	Schema, queries, PostgreSQL, Redis, Convex
integration-expert	bopen-tools:integration-expert	REST APIs, webhooks, third-party services
code-auditor	bopen-tools:code-auditor	Security review, vulnerability scanning
tester	bopen-tools:tester	Unit, integration, e2e tests, CI
documentation-writer	bopen-tools:documentation-writer	READMEs, API docs, PRDs, guides
devops	bopen-tools:devops	Vercel+Railway+Bun, CI/CD, monitoring
optimizer	bopen-tools:optimizer	Bundle analysis, Lighthouse, Core Web Vitals
architecture-reviewer	bopen-tools:architecture-reviewer	System design, refactoring strategy, tech debt
mobile	bopen-tools:mobile	React Native, Swift, Kotlin, Flutter
payments	bopen-tools:payments	Stripe, billing, financial transactions
marketer	bopen-tools:marketer	CRO, SEO, copy, launch strategy
legal	product-skills:legal	Privacy, compliance, ToS
mcp	bopen-tools:mcp	MCP server setup, config, diagnostics

Full roster with per-agent skills to mention in spawn prompts: references/agent-roster.md

Full Team Lifecycle

Step 1: Decompose the task

Before calling any tools, identify:

• What domains are involved? (frontend, backend, testing, docs, security...)
• Which tasks can run in parallel vs. must be sequential?
• What are the dependencies? (schema before API, API before tests)

Step 2: Create the team

TeamCreate(
  team_name: "feature-billing",
  description: "Implement Stripe billing with UI, API, tests, and docs"
)

Step 3: Create tasks upfront

Set dependencies with addBlockedBy where order matters:

TaskCreate(
  subject: "Design billing UI components",
  description: "Create PricingCard, BillingHistory, UpgradeModal using shadcn/ui.
  Repo: ~/code/myapp. Tailwind v4. Output: src/components/billing/.",
  activeForm: "Designing billing UI"
) → id: "1"

TaskCreate(
  subject: "Implement Stripe integration",
  description: "Set up webhooks, subscription creation, customer portal.
  Repo: ~/code/myapp. API routes in app/api/billing/.",
  activeForm: "Implementing Stripe integration"
) → id: "2"

TaskCreate(
  subject: "Write billing test suite",
  description: "Vitest tests for all billing API routes and webhook handler.
  Repo: ~/code/myapp. Tests in __tests__/billing/.",
  activeForm: "Writing billing tests"
) → id: "3"

TaskUpdate(taskId: "3", addBlockedBy: ["2"])  # tests wait for Stripe impl

Step 4: Spawn teammates

Agent(
  subagent_type: "bopen-tools:designer",
  team_name: "feature-billing",
  name: "designer",
  mode: "bypassPermissions",
  prompt: "..."  # see references/spawn-prompt-guide.md
)

Every spawn prompt must be self-contained — teammates have zero conversation history. See references/spawn-prompt-guide.md for the full template and how to list each agent's available skills.

Step 5: Monitor and coordinate

Messages from teammates arrive automatically. Check progress:

TaskList()

Answer a blocked teammate:

SendMessage(
  type: "message",
  recipient: "backend",
  content: "Stripe webhook secret is STRIPE_WEBHOOK_SECRET in .env.local",
  summary: "Stripe secret location"
)

Step 6: Shutdown and cleanup

SendMessage(type: "shutdown_request", recipient: "designer", content: "Work complete")
SendMessage(type: "shutdown_request", recipient: "backend", content: "Work complete")
SendMessage(type: "shutdown_request", recipient: "tester", content: "Work complete")

# Wait for each shutdown_response, then:
TeamDelete()

Task Decomposition Patterns

Feature implementation

Parallel from the start:
├── researcher: research best practices / prior art
├── designer: UI components
├── nextjs or integration-expert: API / server logic
└── database: schema changes

Blocked until implementation complete:
├── tester: test suite
└── documentation-writer: feature docs

Security audit + fix

Parallel:
├── code-auditor: full vulnerability scan (Semgrep, CodeQL)
└── architecture-reviewer: structural/design issues

Blocked until audit complete:
├── nextjs or integration-expert: fix findings
└── tester: regression tests

Launch prep

Parallel:
├── code-auditor: security review
├── tester: coverage audit
├── optimizer: Lighthouse + bundle
├── documentation-writer: user-facing docs
└── legal: privacy / ToS

Blocked until all above complete:
└── devops: deploy pipeline

Key Rules

• mode: "bypassPermissions" on every Agent spawn or teammates block
• Self-contained prompts: teammates get zero conversation history — include repo path, conventions, and full context
• Mention agent skills in spawn prompts — each agent has specialized skills; tell them which to use
• One task at a time: claim → complete → claim next. No parallel hoarding
• No JSON in messages: use TaskUpdate for status. SendMessage is plain text only
• Idle is normal: teammates go idle between tasks. Send a message to wake them
• No nested teams: only the lead calls TeamCreate
• Shutdown before TeamDelete: TeamDelete fails if any teammate is still active
• Broadcast sparingly: each broadcast = one API call per teammate

Troubleshooting

Problem	Fix
TeamCreate fails	Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set
Teammate blocks/stalls	Missing mode: "bypassPermissions" — always set this
Teammate not claiming tasks	Check blockedBy deps with TaskGet
Teammate idle and unresponsive	Send a direct SendMessage — idle agents wake on receipt
TeamDelete fails	Teammates still running. Send shutdown_request to each
Teammate went off-script	Send correction via SendMessage. If severe, shutdown and respawn

References

• references/permissions-and-isolation.md — mode parameter options, worktree isolation for parallel edits
• references/agent-roster.md — full roster table + which skills to mention per agent in spawn prompts
• references/spawn-prompt-guide.md — complete spawn prompt template with skills section