Skip to main content
skill CX Codex

bmad-tea-test-design — Claude Code skill: what it does, how to install

The bmad-tea-test-design skill for Claude Code builds system-level and epic-level test plans grounded in risk assessment.

MIT 882 installs ★ 118 updated 2026-11-13

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmad-tea-test-design -a claude-code
Open on GitHub

What bmad-tea-test-design does

This skill acts as a test architect inside Claude Code, Codex, Cursor, and other supported platforms. It engages when requested to design a test plan or strategy, then validates project configurations and checks for required companion modules.

The workflow requires the bmod-tea module installed alongside this skill and a project configuration file containing the modules.tea table. If these dependencies are missing, the agent halts execution until resolved.

The process runs through creation, validation, and editing modes while recording progress checkpoints in the test artifacts directory. Configuration steps rely on execution scripts via uv run at the project root.

What it helps with

  • design a system-level test plan
  • create an epic test strategy
  • validate test outputs against checklists
  • edit existing test artifacts
  • resume an interrupted test plan run

Example prompts for the agent

  • lets design test plan
  • I want to create test strategy
  • start a new test design workflow

How to install bmad-tea-test-design

1Skills CLI (Vercel)

npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmad-tea-test-design -a claude-code

2Manually: put the files in place

~/.claude/skills/bmad-tea-test-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bmad-tea-test-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bmad-tea-test-design

How to install bmad-tea-test-design in Claude Code?

Run npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmad-tea-test-design -a claude-code, then reference ~/.claude/skills/bmad-tea-test-design/SKILL.md.

What does bmad-tea-test-design do?

It generates system and epic test plans driven by risk and testability evaluations.

What is required to run bmad-tea-test-design?

It requires the bmod-tea module, a configured config.toml file with a modules.tea table, and the uv runner.

Source text

SKILL.md · MIT
---
name: bmad-tea-test-design
description: 'Create system-level or epic-level test plans. Use when the user says "lets design test plan" or "I want to create test strategy"'
---

# Test Design and Risk Assessment

**Goal:** Produce an epic-level test plan grounded in risk and testability assessment.

**Role:** You are the Master Test Architect.

You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.

## Conventions

- Bare paths (e.g. `instructions.md`) resolve from the skill root.
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents.
- `{tea-knowledge}` is the `knowledge/` folder of the `bmod-tea` skill, installed beside this one: `{skill-root}/../bmod-tea/knowledge`. `tea-index.csv` there lists every fragment by a path relative to that folder.
- `{skill-name}` resolves to the skill directory's basename.
- Resolve sibling workflow files such as `instructions.md`, `checklist.md`, `steps-c/...`, `steps-e/...`, `steps-v/...`, and templates from `{skill-root}`.

## On Activation

Before resolving customizations or running hooks, inspect `{project-root}/_bmad/custom/` for `bmad-testarch-test-design.toml` and `bmad-testarch-test-design.user.toml`. If either exists, stop and tell the user to run `npx --package=bmad-method-test-architecture-enterprise@4 tea-migrate-customizations --project-root {project-root}`. Resolve any reported manual merge, then start a fresh chat. Do not continue with default settings while legacy overrides remain.

### Step 1: Resolve the Workflow Block

Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`

**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. `{skill-root}/customize.toml` — defaults
2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.

### Step 2: Execute Prepend Steps

Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.

### Step 3: Load Persistent Facts

Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs resolved from `{project-root}` — expand them and load every matching file in lexical path order as facts. All other entries are facts verbatim.

### Step 4: Load Config

Run `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core --key modules.tea`. If the script fails, merge `{project-root}/_bmad/config.toml`, `{project-root}/_bmad/custom/config.toml` and `{project-root}/_bmad/custom/config.user.toml` yourself, in that order, with the merge rules above. If `_bmad/config.toml` is missing or has no `modules.tea` table, tell the user TEA is not set up, ask them to run `bmad setup tea` first, and stop.

Each `core` and `modules.tea` key is available as `{<key>}`, and as `config.<key>` in later steps. Replace `{project-root}` inside a value with the project root. Setup answers are strings: read `"true"` and `"false"` as booleans.

If `{tea-knowledge}/tea-index.csv` does not exist, the `bmod-tea` skill is not installed beside this one (`{skill-root}/../bmod-tea`). Tell the user to install `bmod-tea` in the same scope as this skill, and stop until it is there. For a skill in the project's skills folder run `npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmod-tea`; for a skill in the global skills folder add `-g`. Run the command on a yes. A headless run has no approval input: report the missing dependency and stop without running the installer. A `bmod-tea` installed in the other scope does not satisfy this skill.

### Step 5: Greet the User

Greet `{user_name}`, speaking in `{communication_language}`.

### Step 6: Execute Append Steps

Execute each entry in `{workflow.activation_steps_append}` in order.

Activation is complete. Begin the workflow below.

## Workflow Architecture

This workflow uses **tri-modal step-file architecture**:

- **Create mode (steps-c/)**: primary execution flow for new runs and resume continuation
- **Validate mode (steps-v/)**: validation against checklist
- **Edit mode (steps-e/)**: revise existing outputs

## Initialization Sequence

### 1. Mode Determination

"Welcome to the workflow. What would you like to do?"

- **[C] Create** — Run the workflow from the beginning
- **[R] Resume** — Resume an interrupted Create workflow
- **[V] Validate** — Validate existing outputs
- **[E] Edit** — Edit existing outputs

### 2. Route to First Step

- **If C:** Load `{skill-root}/steps-c/step-01-detect-mode.md`
- **If R:** Load `{skill-root}/steps-c/step-01b-resume.md` (Create-mode continuation)
- **If V:** Load `{skill-root}/steps-v/step-01-validate.md`
- **If E:** Load `{skill-root}/steps-e/step-01-assess.md`

Every output lives under `{test_artifacts}/test-design/`: the system-level `test-design-architecture.md` and `test-design-qa.md`, the epic plan `test-design-epic-{epic_num}.md`, the `{project_name}-handoff.md` document, and exploration screenshots under `exploration/`.

Each run writes its own progress checkpoint at `{test_artifacts}/test-design/test-design-progress-{run_key}.md`, where `run_key` is `system` for a system-level run and `epic-{epic_num}` for an epic-level one. Step 1 resolves it, so interrupting a run for one epic and starting another never clobbers the first epic's checkpoint.

Resume mode selects the checkpoint matching the run being resumed, asks when several exist and no scope was named, and refuses to continue a checkpoint whose `runKey` belongs to a different run. It reads explicit progress metadata (`workflowStatus`, `nextStep`, `totalSteps`) and falls back to legacy `lastStep` data when needed.

© bmad-code-org · MIT · bmad-code-org/bmad-method-test-architecture-enterprise

Similar skills

All skills for Testing and QA →

From the same set10

The whole set →
bmad-tea bmad-tea — a skill for Claude Code brings in Murat, a Master Test Architect persona. It activates when asking for the Test Architect to direct ATDD, test automation, and CI/CD quality gates. CX Codex +1 1,100installs bmod-tea The bmod-tea Claude Code skill stores the Test Architect module record. Run the bmad skill with setup tea to set up the module or check its state. CX Codex +1 1,000installs bmad-tea-automate The bmad-tea-automate skill generates tests in red or expand modes and runs and repairs new tests. The agent triggers it when users ask to automate tests or do ATDD. CX Codex +1 887installs bmad-tea-test-review bmad-tea-test-review is a Claude Code skill that evaluates test quality against best practice standards. It triggers when you request a test suite audit or quality assessment. CX Codex +1 869installs bmad-tea-evaluate The bmad-tea-evaluate Claude Code skill runs behavioral evaluations of an agent and helps address gaps. It activates when asked to evaluate an agent or provide evidence that it behaves as expected. CX Codex +1 866installs bmad-tea-trace The bmad-tea-trace Claude Code skill maps requirements or journeys to tests, assesses coverage, and returns a quality gate decision. It activates for requests to build a traceability matrix or analyze test coverage. CX Codex +1 863installs bmad-tea-framework The bmad-tea-framework Claude Code skill sets up test frameworks and CI/CD for browser, backend, or mobile projects. It activates when asked to initialize or configure testing. CX Codex +1 861installs bmad-tea-nfr bmad-tea-nfr — a Claude Code skill that checks implementation evidence for performance, security, reliability, and maintainability. Start it by asking for an NFR review when implementation evidence is available. CX Codex +1 860installs

Project sponsors

Companies that keep this analytics open