Teambuilder

TeamBuilder v3 — AI Agent Team Generator for BMAD v6

> TeamBuilder v3.2.2 — built for BMAD Method v6.2.2 > A BMAD v6 custom module that generates tailored AI agent teams through guided discovery, paired generation with real-time quality feedback, and critical validation scoring. Includes compatibility guardrails (doctor, update, channels), runtime drift warning, and CI smoke tests.

---

Table of Contents

• [What is TeamBuilder?](#what-is-teambuilder)
• [What TeamBuilder IS](#what-teambuilder-is)
• [What TeamBuilder is NOT](#what-teambuilder-is-not)
• [How it works](#how-it-works)
• [Requirements](#requirements)
• [Installation](#installation)
• [Windows](#windows)
• [Linux / macOS](#linux--macos)
• [What the installer does](#what-the-installer-does)
• [Reinstalling, updating, uninstalling](#reinstalling-updating-uninstalling)
• [First Team — Quick Start](#first-team--quick-start)
• [The Six TeamBuilder Agents](#the-six-teambuilder-agents)
• [The Five TeamBuilder Skills](#the-five-teambuilder-skills)
• [Pattern Library](#pattern-library)
• [Generated Teams](#generated-teams)
• [Memory System](#memory-system)
• [Configuration](#configuration)
• [Project Layout After Install](#project-layout-after-install)
• [Troubleshooting](#troubleshooting)
• [Development / Contributing](#development--contributing)
• [Version History](#version-history)
• [License](#license)
• [Disclaimer](#disclaimer)

---

What is TeamBuilder?

TeamBuilder is a custom module for BMAD Method v6 that helps you create specialized AI agent teams without hand-writing agent definitions or workflows. You answer questions about what you need, and TeamBuilder generates a team with distinct personas, authentic domain expertise, and practical workflows — then validates the result before you install it.

The BMAD Method is a framework built around Claude Code that lets you compose teams of AI agents with specific roles (analyst, architect, developer, QA, etc.) into a structured collaborative process. BMAD ships with a general software-development module (bmm). TeamBuilder is where you go when bmm isn't what you need — for example:

• A domain-specific governance team (ITIL, compliance, healthcare, legal)
• A research / intelligence team with verification discipline
• A planning / strategy team with distinct lenses (risk, stakeholders, scenarios)
• A creative / content team with editorial + brand-voice roles
• An operations / Lean / Six Sigma team
• A specialty software team (security, SRE, ML, accessibility) that complements bmm rather than duplicating it

TeamBuilder is itself a BMAD v6 custom module, installed via BMAD's native --custom-content mechanism. Every team it generates is also a BMAD v6 custom module, installable into any other BMAD project the same way. This means generated teams are first-class citizens: they show up in bmad status, register in the manifest CSVs, install their agents into .claude/skills/ automatically, and use the same loading machinery as any other BMAD module.

---

What TeamBuilder IS

• ✅ A team generator. Guided 10-question discovery produces a requirements document. A collaborative pipeline of four agents then designs, generates, validates, and packages a custom team.
• ✅ A quality gate. Every generated team is scored 0–100 against 42+ validation rules covering persona distinctness, workflow practicality, team coherence, architectural compliance, and naming conventions.
• ✅ Pattern-driven. The patterns/ library contains six reference patterns (~55,000 words of v6-shape examples and composition guidance) that teach the generator. Generated teams apply these principles without copying the examples.
• ✅ A persistent-memory system. Each generated team gets its own Memory MCP file. Learnings are classified as GeneralKnowledge (reusable across projects) or ProjectKnowledge (team-specific) so cross-team knowledge can accumulate and be reused.
• ✅ A session continuity layer. Every generated team ships with a bmad-skill-save-session skill that captures tool learnings and compiles a session context file, so the next session picks up where you left off.
• ✅ A proper BMAD v6 module. Installs cleanly via --custom-content. No manual manifest editing. No .claude/commands/ stubs. No workflow file triads. Everything BMAD 6.2.2 supports natively is used; nothing is hacked around it.
• ✅ Free and open source. MIT license. Fork it, extend it, submit PRs.

What TeamBuilder is NOT

• ❌ Not a replacement for BMM. If you need a general agile software-development team (PM, architect, dev, QA, scrum master), install bmm instead — it ships with those roles and their workflows already. Use TeamBuilder for specialty teams or non-software domains.
• ❌ Not an autonomous agent. TeamBuilder generates a team for you to review, refine, and install. Nothing ships to production without your approval. Quality Guardian scores and recommends — you decide.
• ❌ Not a production-ready AI system. Generated teams are starting points. They work, they're coherent, and they're tailored, but you should still read the generated personas and workflows before using them for real work. Refine anything that doesn't match your context.
• ❌ Not a magic prompt template. Patterns are learning examples, not fill-in-the-blank templates. The generation pipeline learns composition principles from patterns and applies them to your specific domain — but that means quality depends on how specific and accurate your discovery answers are.
• ❌ Not affiliated with Anthropic or the BMAD-METHOD project. TeamBuilder is an independent community module that sits on top of BMAD. It does not speak for them and they do not endorse it.
• ❌ Not a secrets manager. Do NOT put API keys, passwords, or private data into agent personas, generated team files, or Memory MCP entries. The memory file is a plain-text JSONL file on your disk. Generated team files are committed to git by default (except memory.jsonl and session-context.md). Review the .gitignore and team files before committing.
• ❌ Not a silver bullet for bad prompts. Generated agents are as specific as your discovery answers. Vague answers → generic agents. Specific domain context with real terminology → authentic specialists.

---

How it works

TeamBuilder runs a four-phase collaborative pipeline orchestrated by the bmad-skill-collaborative-generation skill. Four agents take turns leading phases:

| Phase | Name | Lead agent(s) | What happens | |---|---|---|---| | 1 | Discovery | bmad-agent-team-architect (via bmad-skill-discover-team-needs) | 10-question guided interview with domain-specific branching. Captures task, domain, scope, concerns, team-size preference, collaboration style. Output: team-requirements-{timestamp}.md. | | 2 | Paired Generation | bmad-agent-team-architect + bmad-agent-persona-improver (real-time pair) | Team Architect drafts each agent and workflow. Persona Improver critiques immediately (2–3 exchanges per agent) before Team Architect moves on. Quality is built in during generation, not patched in after. Then bmad-agent-tool-scout researches MCP / CLI integrations. | | 3 | Critical Review | bmad-agent-quality-guardian (via bmad-skill-validate-team) | Scores 0–100 against 42+ rules: Agent quality (40%), Workflow quality (30%), Team coherence (30%). Produces VALIDATION_REPORT.md with priority issues ranked by severity. | | 4 | User Decision | bmad-agent-team-architect + bmad-agent-quality-guardian (joint presentation) | Team Architect presents structure; Quality Guardian presents score + findings. User chooses: Install / Refine / Regenerate. |

Quality bands:

• 95–100 — Exceptional. Install immediately.
• 85–94 — Good. Ready to use.
• 75–84 — Acceptable. Refinement recommended.
• 60–74 — Needs work. Refinement required.
• Do NOT install BMAD separately before running TeamBuilder's installer.** The installer handles BMAD installation itself using a pinned, tested version (6.2.2). If you already have a BMAD install in the target directory, the TeamBuilder installer will either refuse (if TeamBuilder is already installed) or add itself to the existing install (if only bmm is present).

---

Installation

Windows

Option A — Clone, then run (recommended for first-time users):

git clone https://github.com/dexusno/teambuilder.git C:\temp\teambuilder
cd C:\path\to\your\project      # any empty or bmm-only directory
C:\temp\teambuilder\scripts\install.ps1

Option B — One-liner (pulls the installer directly from GitHub):

First, create and enter your project folder (any empty or bmm-only directory works):

mkdir my-project
cd my-project

Then copy and paste this single line to download and run the installer:

iwr https://raw.githubusercontent.com/dexusno/teambuilder/main/scripts/install.ps1 -OutFile install.ps1; .\install.ps1

Installer flags:

| Flag | Effect | |---|---| | -Yes | Accept all defaults, no prompts | | -NoMcp | Skip .mcp.json creation | | -NoPlaywright | Keep Memory MCP, skip Playwright | | -Branch | Install from a specific git branch (default main) | | -LocalSource | Use a local TeamBuilder checkout instead of cloning (maintainer flow) |

Example:

.\install.ps1 -Yes -NoPlaywright

Linux / macOS

Option A — Clone, then run:

git clone https://github.com/dexusno/teambuilder.git /tmp/teambuilder
cd ~/path/to/your/project
bash /tmp/teambuilder/scripts/install.sh

Option B — One-liner:

First, create and enter your project folder:

mkdir my-project && cd my-project

Then copy and paste this single line to download and run the installer:

curl -fsSL https://raw.githubusercontent.com/dexusno/teambuilder/main/scripts/install.sh -o install.sh && chmod +x install.sh && ./install.sh

Installer flags:

| Flag | Effect | |---|---| | -y / --yes | Accept all defaults, no prompts | | --no-mcp | Skip .mcp.json creation | | --no-playwright | Keep Memory MCP, skip Playwright | | --branch NAME | Install from a specific git branch (default main) | | --local-source PATH | Use a local TeamBuilder checkout instead of cloning |

Example:

./install.sh -y --no-playwright

What the installer does

1. Checks prerequisites — Node.js, npm, git. Warns if Claude Code CLI is not on PATH (the desktop app works fine too).
2. Refuse-if-exists guard — If _bmad/teambuilder/ already exists, the installer refuses and points you at the (future) update/doctor scripts. If _bmad/ exists but teambuilder/ doesn't, it offers to add TeamBuilder to the existing BMAD install without touching core or bmm.
3. Clones this repo to a temp dir — so it always installs the right teambuilder/ module contents regardless of where you ran it from.
4. Runs BMAD's installer — npx bmad-method@6.2.2 install --directory . -y --modules bmm --tools claude-code --custom-content /teambuilder. BMAD handles everything: copying the module, generating manifest CSVs, registering agents, installing skills into .claude/skills/.
5. Writes .mcp.json — configures the Memory MCP server with MEMORY_FILE_PATH pointing at _bmad/teambuilder/memory/general-knowledge.jsonl plus Playwright MCP (unless -NoPlaywright). If .mcp.json already exists, the installer leaves it alone.
6. Creates docs/ — the team knowledge base directory. Agents read .md files from here on activation.
7. Creates or updates .gitignore — appends rules for team memory files and session contexts so local state doesn't pollute commits.
8. Cleans up the temp clone.
9. Runs post-install sanity checks — verifies _bmad/teambuilder/config.yaml, _bmad/teambuilder/agents/, _bmad/teambuilder/skills/, and the manifest CSVs are present. Counts teambuilder rows in the manifests and reports them.
10. Prints a success message with next steps and the full agent list.

Reinstalling, updating, uninstalling

• Diagnose problems — scripts/doctor.ps1 (Windows) or scripts/doctor.sh (Linux/macOS). Read-only health check that runs the full compatibility test suite plus bmad status and reports a structured pass/fail summary. Use this when something feels wrong, before filing a bug report, or after upgrading BMAD. Supports -Json / --json for scripts.
• Update TeamBuilder in place — scripts/update.ps1 (Windows) or scripts/update.sh (Linux/macOS). Snapshots the current install to _bmad/.tb-backup-{timestamp}/, runs the compatibility check, applies the update via BMAD's --custom-content quick-update, re-runs the check, and offers rollback if anything went wrong. Never touches _bmad/teams-*/ (your generated teams are preserved). Use -Yes for non-interactive, -KeepBackup to retain the snapshot, -Force to override pre-check failures.
• Reinstall from scratch — delete _bmad/ manually, then run scripts/install.* again. Warning: deleting _bmad/ also removes any generated teams stored under _bmad/teams-*/. Back them up first, or use update.* instead.
• Uninstall only TeamBuilder — delete _bmad/teambuilder/ and rerun BMAD's installer: npx bmad-method@6.2.2 install --directory . -y --modules bmm --tools claude-code. BMAD will regenerate manifests without TeamBuilder.
• Uninstall everything — npx bmad-method uninstall (BMAD's built-in uninstall command).

---

First Team — Quick Start

After installation, you should see:

+---------------------------------------------------+
|            Installation Complete!                 |
+---------------------------------------------------+

To create your first team:

1. Restart Claude Code. Skills are discovered on startup. If you had Claude Code open, close and reopen it — otherwise the new agents won't be visible.
2. Open this directory in Claude Code (the desktop app or via claude . in a terminal).
3. Invoke the TeamBuilder Guide by typing:

`` /bmad-agent-team-guide ``

1. Greet the guide and pick [CT] (Create a new AI agent team) from the menu.
2. Answer the 10 discovery questions honestly and specifically. The more domain terminology you use, the more authentic the generated team will be.
3. Let the pipeline run:

• Team Architect will design the structure (5–30 seconds)
• Paired generation with Persona Improver will produce the agents and workflows (1–3 minutes depending on team size)
• Tool Scout will research MCP/CLI integrations (10–30 seconds)
• Quality Guardian will score and report (10–20 seconds)

1. Review the validation report. If the score is ≥85, install. If 75–84, refine. If " \

-y \ --modules bmm \ --tools claude-code \ --custom-content ""

**Flag-by-flag**, all required:

| Flag | Without it |
|---|---|
| `--directory ""` | BMAD prompts "Installation directory:" and blocks |
| `-y` | BMAD prompts for module and tool confirmations |
| `--modules bmm` | BMAD may prompt "which modules?" on quick-update |
| `--tools claude-code` | BMAD may prompt "which IDE?" on quick-update |
| `--custom-content ""` | The actual install target |

Use **absolute paths** for both `--directory` and `--custom-content`. Relative paths are risky because BMAD may resolve them against a different CWD than you expect.

BMAD treats the install as a **quick-update** and adds the new module to the existing `_bmad/` install without touching `core`, `bmm`, or `teambuilder`. The generated team's agents and skills land in `.claude/skills/` automatically. Restart Claude Code to see them.

### Invoking generated team agents

Once installed, generated team agents are available as slash commands:

/bmad-agent-{role-name} #

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dexusno
• Source: dexusno/teambuilder
• License: MIT
• Homepage: https://github.com/dexusno/teambuilder

Install and usage instructions live in the source repository linked above.