---

name: multi-agent-builder description: Build a reusable multi-agent team in OpenClaw from a user goal (e.g., "create a product-engineering team", "build a marketing ops team"). Use when the user wants role analysis, role confirmation, agent-by-agent creation plan, collaboration protocol, handoff flow, and channel-binding checklist. Mirror the user's language (English/Chinese/other) throughout the interaction and outputs.

Team Builder

Overview

Design and bootstrap a multi-agent team with clear roles, dependency-aware workflow, and reliable collaboration rules. Start with role discovery, confirm scope with the user, then produce an implementation-ready team plan.

Workflow

1) Mirror language and capture mission

• Detect and mirror the user's language.
• Follow minimal-question strategy from references/dialog-flow.md.
• Ask only missing items: team objective, expected outputs, constraints (timeline, tools, compliance), preferred channels.
• If user intent is broad, propose a default operating model first, then refine.
• Reuse language prompts from references/language-templates.md.

2) Propose a complete role set (then let user prune)

• Generate a comprehensive but practical role catalog for the mission.
• Always include team-leader as mandatory core role.
• Apply auto-completion and anti-overdesign rules from references/dialog-flow.md.
• Apply split/merge criteria from references/splitting-principles.md.
• Mark roles as:
  • Core (required)
  • Optional (context-dependent)
  • Not needed now (defer)
• During role confirmation, use user language and show role names/functions only (no agent IDs at this stage).
• Ask user to confirm additions/removals before any build steps.
• For role suggestions, use references/role-catalog.md as baseline patterns.
• Only in the final creation report show: role name + agent ID + responsibilities.

3) Define each agent contract

For each confirmed role, define:

• Agent ID (stable, short, lowercase-hyphen)
• team-leader id must be team-prefixed (e.g., <team>-team-leader)
• Role mission
• Inputs consumed
• Outputs produced
• Decision authority
• Upstream/downstream dependencies
• Escalation target

Use the table format in references/output-templates.md.

4) Define collaboration protocol (must be explicit)

Do not rely on vague "work together" instructions. Specify:

• Task delegation envelope (goal, context, deliverable, deadline)
• Status states (accepted, blocked, done)
• Completion callback requirement (explicit return to delegator)
• Long-task update cadence
• Timeout/retry/escalation policy
• No-raw-bulk-output rule (summary + artifact path only)
• Mid-process visibility: show who is working on what at each stage

Use references/collaboration-protocol.md.

5) Produce implementation + provisioning bundle

Return a concrete package for execution:

1. Team roster and responsibilities
2. Agent interaction flow (ordered steps)
3. Collaboration protocol summary
4. Files to create/update (SOUL/AGENTS/IDENTITY guidance snippets)
5. Provisioning plan (tools/skills/permissions per role)
6. Team creation report (mandatory; includes stage deliverables+paths and security-check summary)
7. Channel binding blueprints (provided automatically after the report)
8. Smoke-test script (simple end-to-end validation prompt)

Mandatory execution path (programmatic, not prompt-only):

• run single entrypoint: scripts/create_team.mjs
• this entrypoint must internally execute materialize -> validate -> emit_report
• if validate != ready, must return partially_ready/blocked and stop

Mandatory: run post-creation materialization checks via references/materialization-checklist.md. Do not mark team as ready if role files are still placeholders.

Use:

• references/capability-matrix.md
• references/permission-profiles.md
• references/provisioning-playbook.md
• references/final-deliverable-sample.md
• references/channel-binding-blueprints.md
• references/materialization-checklist.md

6) Safe execution guardrails

Before any external-effect action, apply this confirmation policy:

• No confirmation needed for internal deterministic setup:
  • creating/updating agents in openclaw.json
  • setting A2A/subagents permissions
• Confirmation required for channel/bot credential binding and other irreversible external effects.

For skill installation, run security pre-check first and block high-risk items. Never auto-restart gateway during creation flow. If restart is required, ask user first or provide manual restart instruction. If anything is ambiguous, pause and ask.

7) Failure handling and recovery

When setup/collaboration fails, apply references/failure-modes.md. Prioritize fast recovery with minimal blast radius:

• preserve completed work
• recover from last checkpoint
• keep user status accurate (ready vs partially ready)
• never auto-install skills that fail security checks

Quality bar

• Prefer fewer roles with crisp boundaries over many overlapping roles.
• Every role must have a measurable output.
• Every dependency must have a return path.
• Deliverables must be immediately actionable by an operator.
• Role docs must be rich enough to represent domain-expert behavior (not one-line placeholders).
• team-leader must orchestrate only and must not produce specialist implementation deliverables.
• All specialist outputs must be saved under team shared directory.
• Reuse patterns from references/examples.md when user goals match known team archetypes.

Creation phase details

After role confirmation, follow references/create-playbook.md exactly. Use references/snippet-templates.md to produce reusable SOUL/AGENTS append snippets. Format final user handoff using references/final-deliverable-sample.md.

Resources

• references/role-catalog.md: cross-domain role starter sets.
• references/role-display-mapping.json: locale-based role display names for confirmation stage.
• references/dialog-flow.md: minimal-question discovery flow and auto-completion rules.
• references/language-templates.md: bilingual/locale-aware prompt templates.
• references/splitting-principles.md: when to split/merge roles during discovery.
• references/examples.md: end-to-end examples for common team archetypes.
• references/channel-binding-blueprints.md: Single-Bot vs Multi-Bot Group binding plans and group config guidance.
• references/capability-matrix.md: role-to-tools/skills mapping baselines.
• references/permission-profiles.md: least-privilege profiles.
• references/provisioning-playbook.md: auto install + permission setup flow (with skill-vetter-first security scanning).
• references/security-report-schema.md: machine-readable security report and install decision schema.
• references/collaboration-protocol.md: explicit multi-agent coordination protocol.
• references/output-templates.md: final output templates and checklists.
• references/create-playbook.md: execution-ready creation sequence.
• references/snippet-templates.md: reusable injection/confirmation snippets.
• references/role-soul-blueprints.md: expert-level SOUL depth blueprint per role.
• references/team-leader-template.md: fixed team-leader SOUL template (copied at creation).
• references/team-leader-agents-template.md: fixed team-leader AGENTS template (copied at creation).
• references/final-deliverable-sample.md: standardized user handoff format.
• references/failure-modes.md: failure scenarios and recovery actions.
• references/materialization-checklist.md: post-creation role-file completion gate.
• references/config-materialization-checklist.md: mandatory openclaw.json agent/binding/A2A completion gate.