b-open-io/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