# Teambuilder

> Custom BMAD v6 module that generates tailored AI agent teams via guided discovery, paired real-time quality feedback, and validation scoring. Includes compatibility guardrails (doctor, update, channels) and CI smoke tests.

- **Type:** MCP server
- **Install:** `agentstack add mcp-dexusno-teambuilder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dexusno](https://agentstack.voostack.com/s/dexusno)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dexusno](https://github.com/dexusno)
- **Source:** https://github.com/dexusno/teambuilder
- **Website:** https://github.com/dexusno/teambuilder

## Install

```sh
agentstack add mcp-dexusno-teambuilder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/bmad-code-org/BMAD-METHOD)** 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):

```powershell
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):

```powershell
mkdir my-project
cd my-project
```

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

```powershell
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:

```powershell
.\install.ps1 -Yes -NoPlaywright
```

### Linux / macOS

**Option A — Clone, then run:**

```bash
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:

```bash
mkdir my-project && cd my-project
```

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

```bash
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:

```bash
./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
   ```
4. **Greet the guide** and pick `[CT]` (Create a new AI agent team) from the menu.
5. **Answer the 10 discovery questions** honestly and specifically. The more domain terminology you use, the more authentic the generated team will be.
6. **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)
7. **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](https://github.com/dexusno)
- **Source:** [dexusno/teambuilder](https://github.com/dexusno/teambuilder)
- **License:** MIT
- **Homepage:** https://github.com/dexusno/teambuilder

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dexusno-teambuilder
- Seller: https://agentstack.voostack.com/s/dexusno
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.