Test Architect (TEA)

TEA (Test Engineering Architect) is a standalone BMAD module that delivers risk-based test strategy, test automation guidance, and release gate decisions. It provides a single expert agent (Murat, Master Test Architect and Quality Advisor) and nine workflows spanning Teach Me Testing (TEA Academy), framework setup, test design, ATDD, automation, traceability, NFR assessment, CI guidance, and test review.

Docs: https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/

Why TEA

• Risk-based testing with measurable quality gates
• Consistent, knowledge-base driven outputs
• Clear prioritization (P0-P3) and traceability
• Optional Playwright Utils, CLI, and MCP browser automation

How BMad Works

BMad works because it turns big, fuzzy work into repeatable workflows. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a shared knowledge base (standards and patterns) so outputs are consistent, not random. In short: structured steps + shared standards = reliable results.

How TEA Fits In

TEA plugs into BMad the same way a specialist plugs into a team. It uses the same step‑by‑step workflow engine and shared standards, but focuses exclusively on testing and quality gates. That means you get a risk‑based test plan, automation guidance, and go/no‑go decisions that align with the rest of the BMad process.

Architecture & Flow

BMad is a small agent + workflow engine. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.

Building Blocks

TEA has two layers of files, and each has a specific job:

Workflow resource directories intentionally duplicate the TEA knowledge base. Each workflow skill must stay self-contained so it can be installed, copied, or invoked without reaching across skill boundaries. When knowledge changes, propagate the intended updates to the affected workflow resource directories instead of replacing them with a central runtime path.

flowchart LR
  U[User] --> A[Agent Persona]
  A --> W[Workflow Entry: workflow SKILL.md]
  W --> S[Step Files: steps-c / steps-e / steps-v]
  S --> K[Knowledge Fragments<br/>tea-index.csv → knowledge/*.md]
  S --> T[Templates & Checklists<br/>*-template.md, checklist.md]
  S --> O[Outputs: docs/tests/reports<br/>when a step writes output]
  O --> V[Validation: checklist + report]

How It Works at Runtime

1. Trigger — Direct commands are /bmad:tea:automate (Claude/Cursor/Windsurf) and $bmad-tea-testarch-automate (Codex). Load the conversational TEA menu with $bmad-tea in Codex. TA is an agent-menu trigger available only after TEA is activated; the capabilities table in SKILL.md maps TA to the bmad-testarch-automate skill.
2. Agent loads — SKILL.md injects the persona (identity, principles, critical actions) into the context window.
3. Workflow loads — The workflow's SKILL.md becomes the entrypoint. It resolves the workflow block from customize.toml, loads persistent facts and config, decides the mode (Create / Edit / Validate), then routes to the first step file.
4. Step-by-step execution — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one with a {skill-root}-anchored path. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
5. Knowledge injection — Step-01 reads tea-index.csv and selectively loads fragments by tier (core = always, extended = on-demand, specialized = only when relevant) and config flags (e.g., tea_use_pactjs_utils). This is deliberate context engineering: a backend project loads ~1,800 lines of fragments; a fullstack project loads ~4,500 lines. Conditional loading cuts context usage by 40-50%.
6. Templates — When a step produces output (e.g., a traceability matrix or test review report), it reads the *-template.md file and fills in the {PLACEHOLDER} values with computed results. The template provides consistent structure; the step provides the content.
7. Subagent isolation — Heavy workflows (e.g., automate) spawn parallel subagents that each run in an isolated context. Subagents write structured JSON to temp files. An aggregation step reads the JSON outputs — only the results enter the main context, not the full subagent history.
8. Progress tracking — Each step appends to an output file with YAML frontmatter (stepsCompleted, lastStep, lastSaved). Resume mode reads this frontmatter and routes to the next incomplete step.
9. Validation — The steps-v/ mode reads checklist.md and evaluates the workflow's output against its criteria, producing a pass/fail validation report.

Workflows vs Skills

BMad workflows and Claude Code Skills solve different problems at different scales:

The key insight is that there is no external runtime engine — the LLM is the engine. BMad workflows are structured markdown that the LLM follows as instructions: "read this file, execute it completely, save your output, load the next file." Skills are a single tool in a toolbox; BMad workflows are a workshop with a process manual.

How workflows become commands. When you run npx bmad-method install, the installer generates tool-specific artifacts for your runtime (for example, Claude Code uses .claude/commands/, while Codex uses .agents/skills/). Those launchers bridge into the installed TEA agent or workflow package. Once invoked, the workflow's SKILL.md is the conversational entrypoint, and the step-file process takes over from there.

.claude/commands/                         # Generated by installer
├── bmad-tea.md                           # /tea → loads agent persona + menu
├── bmad-tea-testarch-automate.md         # /automate → invokes the automate workflow package
├── bmad-tea-testarch-test-design.md      # /test-design → ...
├── bmad-bmm-create-prd.md               # /create-prd → BMM workflow
└── ... (61 commands total across all installed modules)

The BMAD-METHOD source repo also has standalone .claude/skills/ (e.g., bmad-os-release-module, bmad-os-gh-triage) for its own maintenance workflows. External tools can register skills too (e.g., playwright-cli install --skills). The installer supports 10+ platforms: Claude Code, Cursor, GitHub Copilot, Codex, Gemini, Windsurf, Cline, and more.

Install

npx bmad-method install
# Select: Test Architect (TEA)

Note: TEA is automatically added to party mode after installation. Use /party to collaborate with TEA alongside other BMad agents.

Tool-specific invocation

Quickstart

1. Install TEA (above)
2. Load the TEA menu with $bmad-tea if you want a conversational entrypoint.
3. Run one of the core workflows:
   • TD / /bmad:tea:test-design / $bmad-tea-testarch-test-design — test design and risk assessment
   • AT / /bmad:tea:atdd / $bmad-tea-testarch-atdd — failing acceptance tests first (TDD red phase)
   • TA / /bmad:tea:automate / $bmad-tea-testarch-automate — expand automation coverage
4. Or use in party mode: /party to include TEA with other agents

Engagement Models

• No TEA: Use your existing testing approach
• TEA Solo: Standalone use on non-BMad projects
• TEA Lite: Start with automate only for fast onboarding
• Integrated (BMad Method / Enterprise): Use TEA in Phases 3–4 and release gates

Workflows

Configuration

TEA variables are defined in src/module.yaml and prompted during install:

• test_artifacts — base output folder for test artifacts
• tea_use_playwright_utils — enable Playwright Utils integration (boolean)
• tea_use_pactjs_utils — enable Pact.js Utils integration for contract testing when your project explicitly uses Pact (boolean)
• tea_pact_mcp — SmartBear MCP for PactFlow/Broker interaction when broker integration is needed: mcp, none (string)
• tea_browser_automation — browser automation mode: auto, cli, mcp, none (string)
• test_framework — detected or configured test framework (Playwright, Cypress, Jest, Vitest, pytest, JUnit, Go test, dotnet test, RSpec)
• test_stack_type — detected or configured stack type (frontend, backend, fullstack)
• ci_platform — CI platform (auto, github-actions, gitlab-ci, jenkins, azure-devops, harness, circle-ci)
• risk_threshold — risk cutoff for mandatory testing (future)
• test_design_output, test_review_output, trace_output — subfolders under test_artifacts

Knowledge Base

TEA relies on a curated testing knowledge base:

• Index: src/agents/bmad-tea/resources/tea-index.csv
• Fragments: src/agents/bmad-tea/resources/knowledge/

Workflows load only the fragments required for the current task to stay focused and compliant.

Module Structure

src/
├── module.yaml
├── agents/
│   └── bmad-tea/
│       ├── SKILL.md
│       ├── customize.toml
│       └── resources/
│           ├── tea-index.csv
│           └── knowledge/
├── workflows/
│   └── testarch/
│       ├── bmad-teach-me-testing/
│       ├── bmad-testarch-atdd/
│       ├── bmad-testarch-automate/
│       ├── bmad-testarch-ci/
│       ├── bmad-testarch-framework/
│       ├── bmad-testarch-nfr/
│       ├── bmad-testarch-test-design/
│       ├── bmad-testarch-test-review/
│       └── bmad-testarch-trace/

Extending TEA

Custom workflows are still compatible with TEA, but they are no longer implicitly absorbed into TEA core. The supported path is:

1. Package the workflow as custom content or a custom module.
2. Attach it to bmad-tea using the agent customization flow.
3. Reinstall/update BMAD so the new menu item and workflow are registered.

See Extend TEA with Custom Workflows and the BMAD customization guide at BMAD-METHOD/docs/how-to/customize-bmad.md.

Contributing

See CONTRIBUTING.md for guidelines.

# Publish the next prerelease from current main
npm run release:next

# Publish a stable patch release
npm run release:patch

# Publish a stable minor release
npm run release:minor

# Publish a stable major release
npm run release:major

npm view bmad-method-test-architecture-enterprise
npm view bmad-method-test-architecture-enterprise dist-tags

npx bmad-method install
# Select "Test Architect (TEA)"

# In your project
tea              # Load agent
test-design      # Test workflow

# Unpublish specific version (within 72 hours)
npm unpublish bmad-method-test-architecture-enterprise@1.13.2-next.0

# Deprecate version (preferred for older releases)
npm deprecate bmad-method-test-architecture-enterprise@1.13.2-next.0 "Use version X.Y.Z instead"

Community

• Discord — Get help, share ideas, collaborate
• YouTube — Tutorials, master class, and more
• X / Twitter
• Website

Support BMad

BMad is free for everyone and always will be. Star this repo, buy me a coffee, or email contact@bmadcode.com for corporate sponsorship.

License

See LICENSE.