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: Configure Permissions Before Spawning

Start from the lead session's permission settings and inspect the installed Agent tool schema before spawning. Current builds can accept a per-spawn mode; use a safe non-interactive mode such as dontAsk/auto with narrow allow rules when available. If the host does not expose that field, the teammate inherits the lead. Permission requests may bubble up to the lead.

Do not launch the lead with --dangerously-skip-permissions merely to avoid team prompts. Reserve that mode for an explicitly trusted, externally sandboxed environment.

See references/permissions-and-isolation.md for the permission and file-ownership model.

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
native-desktop	bopen-tools:native-desktop	Native SDK, Zig, WebViews, menu-bar apps, signed DMGs
designer	bopen-tools:designer	UI, game HUDs, TV shells, directional focus, Tailwind, accessibility
agent-builder	bopen-tools:agent-builder	AI SDK v7 agents, durable runtime selection, conditional eve evaluation
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	Expo-first React Native, Swift, Kotlin, Flutter
payments	bopen-tools:payments	Stripe, billing, financial transactions
marketer	product-skills: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",
  name: "designer",
  mode: "dontAsk",
  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

• Use the safest effective permission mode: pre-approve only the operations teammates need; never default to bypass
• 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 hits permission prompts	Pre-approve the specific safe operation in the lead's settings, then retry
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 — inherited permissions and safe file partitioning
• 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