Skip to content
🤖 Consolidated, AI-optimized BMAD docs: llms-full.txt. Fetch this plain text file for complete context.
🚀 Build your own BMad modules and share them with the community! Get started or submit to the marketplace.
Test Architect (TEA)

Extend TEA with Custom Workflows

Extend TEA with Custom Workflows

Section titled “Extend TEA with Custom Workflows”

TEA is a standalone module now. That means custom workflows are still supported, but they are not automatically folded into TEA core during updates.

The Supported Model

Section titled “The Supported Model”

Use one of these approaches:

  1. Package the workflow as custom content or a custom module.
  2. Add a menu entry to bmad-tea through BMAD agent customization.
  3. Reinstall or quick-update BMAD so the workflow and menu entry are registered.

This keeps your TEA extensions compatible with upstream updates.

Section titled “Recommended Approach”

1. Create the workflow as custom content

Section titled “1. Create the workflow as custom content”

Use BMad Builder or your own custom module structure to create a workflow that lives outside TEA core.

  • BMAD supports custom modules during install/update.
  • BMad Builder is the recommended path for creating reusable custom agents and workflows.

See:

2. Attach the workflow to bmad-tea

Section titled “2. Attach the workflow to bmad-tea”

After TEA is installed, use the generated agent customization file for bmad-tea under _bmad/_config/agents/ and append a menu item:

menu:
  - trigger: my-custom-workflow
    workflow: 'my-custom/workflows/my-custom-workflow.yaml'
    description: My custom TEA extension workflow

This keeps the bmad-tea chat/menu experience intact while routing to your custom workflow.

3. Reinstall or quick-update BMAD

Section titled “3. Reinstall or quick-update BMAD”

Run:

Terminal window
npx bmad-method install

Then choose a normal update path so BMAD re-applies the customization and refreshes the workflow registration.

What Not to Do

Section titled “What Not to Do”
  • Do not patch TEA core files directly if the workflow is project-specific.
  • Do not rely on old embedded-TEA behavior where local workflows appeared to be attached automatically.
  • Do not keep custom workflow logic only in chat instructions. Put it in a real workflow or module so it survives updates.

Path-Safe Authoring for GitHub Copilot and Other Workspace-Root Runtimes

Section titled “Path-Safe Authoring for GitHub Copilot and Other Workspace-Root Runtimes”

Some IDE skill runners, including GitHub Copilot slash commands in VS Code, execute commands from the workspace root, not from the folder that contains the installed SKILL.md.

Author custom TEA skills and workflows with that constraint in mind:

  • Use {skill-root} for files that live inside the installed skill package.
  • Use {project-root} for files that live in the target repository.
  • Do not assume scripts/..., workflow.md, ./instructions.md, or steps-c/... will resolve relative to the current markdown file unless you explicitly anchor them.

Use patterns like these:

Read `{skill-root}/workflow.md` and follow it exactly.
Load `{skill-root}/steps-c/step-01-preflight.md`.
Run: `python3 {skill-root}/scripts/resolve_customization.py --key inject`
Read `{project-root}/_bmad/tea/config.yaml`.

Avoid patterns like these:

Read `workflow.md`
Load `steps-c/step-01-preflight.md`
Run: `python3 scripts/resolve_customization.py --key inject`

This keeps the same skill portable across Codex, Claude Code, GitHub Copilot, and other runtimes that install skills into different directories.

When to Use Which Approach

Section titled “When to Use Which Approach”
  • Project-specific workflow: add custom content and attach it to bmad-tea
  • Reusable internal workflow: package it as a custom module
  • Reusable public workflow: consider publishing a standalone BMAD module
Section titled “Related Docs”