Team collaboration

BMAD started as a solo practice and most of its machinery assumes one human driving one project. Using it with a team works well for the parts BMAD models directly (shared conventions, a reviewed artifact chain, consistent agents) and requires you to supply the parts it does not (assigning who runs which phase, coordinating several humans). This page covers both honestly.

On this page

• What coordinates a team: files, not agents
• The three customization layers, and who owns each
• Six things a team commits once
• Who runs which phase
• Preventing conflicts between agents (and people)
• The honest gap: multiple humans
• Web bundles: planning on a flat rate
• Hands-on: make a repo team-ready in five files
• Under Claude Code: shared config, scopes, and policy

What coordinates a team: files, not agents

The coordination layer in BMAD is the artifact chain in git, not any messaging between agents. A PRD, an architecture doc, and a story file are how one person's decisions reach another person (and another person's agent). This is the same externalized-state principle from the memory page, applied to people: if it is in _bmad-output/ and committed, the whole team (and every agent) sees it; if it is in someone's chat, it does not exist. So the first rule of team BMAD is the commit rule from the anatomy page: commit the _bmad-output/ spec chain and the team *.toml overrides; the *.user.toml files stay personal and gitignored.

The three customization layers, and who owns each

Team behavior is shaped through three override scopes, and knowing which is which keeps personal preferences out of shared config:

Each has a .user.toml sibling for personal overrides, always gitignored. The resolver merges shipped defaults, then the team file, then the personal file, at every activation, so an individual can adjust an agent's tone without disturbing the team's rules.

Six things a team commits once

The highest-value team setup is a handful of overrides checked into main. These are the recurring org recipes:

1. Shape an agent across every workflow. Put standing rules in an agent's persistent_facts and they apply to every workflow it runs. Example: tell Amelia (dev) in bmad-agent-dev.toml to always look up library docs via your Context7 MCP tool and fall back to Linear when a story is not in the local epics. Every dev-story, quick-dev, create-story, and code-review inherits it. This is the single highest-impact pattern.
2. Enforce conventions in a workflow. A bmad-product-brief.toml or bmad-prd.toml persistent_facts entry can require certain fields or point at a conventions doc with a file: reference.
3. Publish outputs to external systems. A workflow's on_complete (runs once at the terminal step) can push the finished artifact to Confluence or open a Jira issue via MCP. Use on_complete for the one-time publish and activation_steps_append for something that should run on every activation.
4. Swap templates. Override a scalar like brief_template or prd_template to point at your enterprise template instead of the shipped one.
5. Customize the roster. In central config, rebrand an agent's description, add a fictional or specialist agent (a descriptor with no skill folder is enough for Party Mode to include it), or pin team-wide install settings like [core] document_output_language and [modules.bmm] planning_artifacts. Personal settings (user_name, communication_language, user_skill_level) stay in each developer's _bmad/config.user.toml.
6. Advanced integration. Some workflows expose external_sources (on-demand MCP knowledge lookups), external_handoffs (publish steps that degrade gracefully if a tool is offline), and doc_standards (finalize-time writing standards). bmad-prd exposes all of them; check a skill's customize.toml to see its surface.

Reinforce the load-bearing rules a second time in your IDE session file (CLAUDE.md, AGENTS.md, .cursor/rules/, or .github/copilot-instructions.md), which loads before any skill each session. Keep it short; the overrides are the source of truth, the session file is the reminder.

Who runs which phase

The common division of labor mirrors a Scrum team, which is not an accident: BMAD's personas are modeled on one.

• Planning phases in a web subscription. Brainstorm, brief, PRFAQ, PRD, UX, and research are conversation-heavy and cheap on a flat rate. Run them as web bundles (Gemini Gems or ChatGPT Custom GPTs) or in a browser agent, then commit the artifacts.
• Solutioning and implementation in the IDE. Architecture, stories, dev, and review need the codebase and the terminal, so they run where the code is.
• One owner per artifact. Assign each document an owner the way you assign code ownership: a PM owns the PRD, an architect owns the architecture spine, a dev owns a story. The owner runs the workflow; the team reviews the output in a PR.

Preventing conflicts between agents (and people)

When different people (or different agents) implement different epics, they can make incompatible technical decisions: one builds REST, another GraphQL; one uses snake_case columns, another camelCase. BMAD prevents this the same way a good team does, with shared, written decisions:

• Architecture and ADRs are the shared context every implementer reads first. Document the decisions that cross epic boundaries (API style, database, auth, state management, styling, testing) as ADRs with context, options, decision, and consequences. This is exactly why solutioning matters: an alignment issue caught here is about 10x cheaper than one found mid-sprint.
• project-context.md is the per-project constitution every implementation workflow loads, so naming, testing, and framework conventions are consistent across whoever (or whatever) is implementing.
• Review with fresh context. BMAD's review skills run adversarially and, where the platform allows, in context-free subagents that see the artifact but not the author's reasoning, so they judge the work, not the intent. That is a feature for a team: a reviewer who cannot see "what you meant" catches what a charitable reader misses.

The honest gap: multiple humans

BMAD does not yet have first-class multi-human coordination. Agents work in isolation with no central coordination point built in, and the maintainers acknowledge this openly in community discussions; an enterprise collaboration playbook has been in progress but is not finalized. Until it lands, the working patterns are:

• Coordinate through git and PRs, not through BMAD. Branch per epic or story, review the artifact chain and the code together, and resolve conflicts the ordinary way.
• Put hand-off notes in the artifacts themselves (the community workaround): an epic or story that another person or agent will pick up should say so in its text, since there is no automatic inter-agent messaging.
• Keep sprint-status.yaml as the single shared ledger of what is done, in review, and pending, and commit it so everyone (and the BMad Loop orchestrator) reads the same state.
• Treat manifest.yaml plus a documented install command as the way to keep everyone on the same BMAD version; a teammate on a different version gets subtly different behavior.

Community MCP servers (see extending) partly close the gap by exposing BMAD's agents as shared, install-once tools rather than per-project file copies, but they are third-party, not official.

Web bundles: planning on a flat rate

For teams, the economics of planning matter: a PRFAQ pass and three rounds of research in a chat subscription cost zero marginal dollars, while the same work in a metered IDE session is real spend. BMAD packages its planning skills as Gemini Gems and ChatGPT Custom GPTs for exactly this.

• Install only from bmadcode.com/web-bundles: pick a bundle, download the ZIP, create a Gem or Custom GPT, upload the knowledge files, and paste the instructions block. The current shelf covers brainstorming, product brief, PRFAQ, PRD, UX, and market/industry research.
• A bundle is a SKILL.md protocol (a knowledge file) plus an INSTRUCTIONS.md persona block (pasted into the Gem/GPT). Because "the persona lives in the pasted instructions and the protocol lives in the knowledge file," you customize the persona for your org without touching the protocol, and updates are a swap-the-attachments operation.
• Prerequisites: Gemini Gems need Gemini Advanced; Custom GPTs need a paid ChatGPT plan; the research bundle needs Deep Research enabled. Web LLMs drop a persona in long sessions, so remind or restart. The work happens in Canvas and comes back to the repo as the committed artifact.
• Build your own from any BMAD skill with the bmad-os-skill-to-bundle utility.

Hands-on: make a repo team-ready in five files

Goal: paste these files, commit, and every clone activates with the same model, the same pre-approved commands, and a hook that mechanically blocks a direct push to main. This is the commit-the-team-overrides, gitignore-the-personal-ones rule from the top of this page, in Claude Code's own config.

The shared policy lives in .claude/settings.json. It pins the model, pre-approves a read-and-test command set (so no one re-approves git status every session), and wires the push guard:

{
  "model": "claude-opus-4-8",
  "includeCoAuthoredBy": true,
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-direct-push-main.sh"
          }
        ]
      }
    ]
  }
}

The guard is the hook. Claude Code runs a PreToolUse hook as a shell command: it receives the tool call as JSON on stdin and returns a decision on stdout. .claude/hooks/no-direct-push-main.sh reads .tool_input.command, and if it is a git push to main or master, emits a deny:

#!/usr/bin/env bash
# PreToolUse(Bash) hook: block a direct push to main/master.
# Reads the tool call as JSON on stdin; writes a decision as JSON on stdout.
set -euo pipefail

cmd=$(cat | jq -r '.tool_input.command // ""')

if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push' &&
   printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])(origin[[:space:]]+)?(main|master)([[:space:]]|:|$)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Direct push to main is blocked. Open a PR."
    }
  }'
fi

# No output = no decision: normal permission flow continues.
exit 0

It needs jq and the executable bit:

chmod +x .claude/hooks/no-direct-push-main.sh

Keep personal state out of the shared tree with .gitignore:

.claude/settings.local.json
CLAUDE.local.md

settings.local.json holds a developer's own model or extra allows; CLAUDE.local.md is a personal scratchpad. Both stay off main. The one shared reminder every session loads is CLAUDE.md; keep it short, since settings.json is the source of truth:

# Team baseline
Direct pushes to `main` are blocked by a hook. Open a PR. Run `npm test` before committing.

Commit the four shared paths:

git add .claude/settings.json .claude/hooks/no-direct-push-main.sh .gitignore CLAUDE.md
git commit -m "chore: shared Claude Code team baseline"

Confirm the guard by asking the agent to git push origin main:

Illustrative (run it in your own repo; not machine-verified here).

PreToolUse:Bash hook denied Bash: Direct push to main is blocked. Open a PR.

The honest limit is the one this page opened with. This baseline coordinates one developer's agent: it makes that agent obey the team's model, allowlist, and push rule. It does not coordinate the humans. Two teammates whose agents both honor the hook still reconcile through branches and PRs. The hook enforces the floor; running the review is still yours.

Under Claude Code: shared config, scopes, and policy

BMAD's team discipline (commit the shared overrides, gitignore the personal ones) maps directly onto how Claude Code splits config across a precedence stack. The same "in git or it does not exist" rule applies. A team shares its setup by committing five paths so every clone activates identically: .claude/settings.json (permissions, hooks, model), .claude/skills/, .claude/agents/ (subagents), .claude/rules/, and .mcp.json (MCP servers). Personal deviations go in .claude/settings.local.json and CLAUDE.local.md, both gitignored, so a tone tweak or a machine path never lands in shared config. That is BMAD's *.toml (team, committed) versus *.user.toml (personal, gitignored) split, one layer up.

Org-wide guardrails that no clone may override live in the enterprise managed policy: a settings.json and a CLAUDE.md at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux). It sits at the top of precedence and cannot be overridden locally, unlike BMAD's overrides, which any developer can shadow with a .user.toml. Where BMAD relies on written convention, Claude Code can enforce mechanically: a PreToolUse hook inspects the tool call and returns permissionDecision: "deny" to block a git push or a deploy for everyone on the repo. includeCoAuthoredBy controls the commit trailer. The honest gap from this chapter survives the mapping intact: Claude Code drives one developer's agent, so multi-human coordination stays in git and PRs, not in the tool.

The team layer is really just the file-and-override discipline applied to more than one person. The next page goes the other direction: making BMAD do more, through customization, MCP, custom skills, and whole new modules. 👉