Skip to content

feat(workflows): adopt customize.toml pattern for testarch workflows #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
muratkeremozcan merged 3 commits into from
Apr 23, 2026
Merged

feat(workflows): adopt customize.toml pattern for testarch workflows #91

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
808bdff
feat(workflows): adopt customize.toml pattern for testarch workflows
bmadcode Apr 23, 2026
81ca8f1
fix: addresseed PR comments
muratkeremozcan Apr 23, 2026
467d0a2
docs: readme update
muratkeremozcan Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 28 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,26 +28,28 @@ BMad is a small **agent + workflow engine**. There is no external orchestrator

### Building Blocks

Each workflow directory contains these files, and each has a specific job:

| File | What it does | When it loads |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `SKILL.md` | Expert persona — identity, principles, critical actions, capabilities table | First — always in context |
| `workflow.yaml` | Machine-readable metadata — config variables, required tools, tags | Second — resolves `{project-root}`, `{config_source}`, `{test_artifacts}` |
| `workflow.md` | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step | Second — presents mode choice |
| `instructions.md` | Workflow-specific rules and context (optional, supplements workflow.md) | On demand |
| `steps-c/*.md` | **Create** steps — primary execution, 5-9 sequential files | One at a time (just-in-time) |
| `steps-e/*.md` | **Edit** steps — always 2 files: assess target, apply edit | One at a time |
| `steps-v/*.md` | **Validate** steps — always 1 file: evaluate against checklist | On demand |
| `checklist.md` | Validation criteria — what "done" looks like for this workflow | Read by steps-v |
| `*-template.md` | Output skeleton with `{PLACEHOLDER}` vars — steps fill these in to produce the final artifact | Read by steps-c when generating output |
| `tea-index.csv` | Knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path | Read by step-01 to decide which fragments to load |
| `knowledge/*.md` | 40 reusable fragments — standards, patterns, API references (e.g., `data-factories.md`, `pactjs-utils-overview.md`) | Selectively read into context based on tier + config flags |
TEA has two layers of files, and each has a specific job:

| File / Scope | What it does | When it loads |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `src/agents/bmad-tea/SKILL.md` | Murat's persona — identity, principles, critical actions, capabilities table | First — activates the TEA agent |
| `src/agents/bmad-tea/customize.toml` | Agent customization surface — menu items, persistent facts, activation hooks | During agent activation |
| `src/workflows/testarch/<workflow>/SKILL.md` | Workflow entrypoint — resolves workflow customization, picks mode, routes to the first step | When a TEA workflow is invoked |
| `src/workflows/testarch/<workflow>/customize.toml` | Workflow customization surface — activation hooks, persistent facts, optional `on_complete` behavior | During workflow activation |
| `src/workflows/testarch/<workflow>/workflow.yaml` | Machine-readable workflow metadata — descriptions, defaults, tool hints, output paths | Used by installer/tooling and workflow metadata lookups |
| `instructions.md` | Workflow-specific summary and operator notes | On demand |
| `steps-c/*.md` | **Create** steps — primary execution, 5-9 sequential files | One at a time (just-in-time) |
| `steps-e/*.md` | **Edit** steps — always 2 files: assess target, apply edit | One at a time |
| `steps-v/*.md` | **Validate** steps — always 1 file: evaluate against checklist | On demand |
| `checklist.md` | Validation criteria — what "done" looks like for this workflow | Read by steps-v |
| `*-template.md` | Output skeleton with `{PLACEHOLDER}` vars — steps fill these in to produce the final artifact | Read by steps-c when generating output |
| `src/agents/bmad-tea/resources/tea-index.csv` | Knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path | Read to decide which shared TEA fragments to load |
| `resources/knowledge/*.md` | Reusable fragments — standards, patterns, API references | Selectively read into context based on tier + config |

```mermaid
flowchart LR
U[User] --> A[Agent Persona]
A --> W[Workflow Entry: workflow.md]
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]
Expand All @@ -59,8 +61,8 @@ flowchart LR

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** — `workflow.yaml` resolves config variables and `workflow.md` presents the mode menu (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 (`nextStepFile: './step-02-...'`). The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
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.
Expand All @@ -84,12 +86,12 @@ BMad workflows and Claude Code Skills solve different problems at different scal

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/`). In Claude Code, `bmad-tea-testarch-automate.md` tells the LLM: "load the core workflow engine (`workflow.xml`), pass it this workflow config (`automate/workflow.yaml`), follow the instructions exactly." That launcher artifact is the bridge — it triggers the workflow entry point; the multi-step engine takes over from there.
**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.

```text
.claude/commands/ # Generated by installer
├── bmad-tea.md # /tea → loads agent persona + menu
├── bmad-tea-testarch-automate.md # /automate → loads workflow.xml + workflow.yaml
├── 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)
Expand Down Expand Up @@ -174,7 +176,12 @@ Workflows load only the fragments required for the current task to stay focused
src/
├── module.yaml
├── agents/
│ └── bmad-tea/ # Native skill: SKILL.md + bmad-skill-manifest.yaml
│ └── bmad-tea/
│ ├── SKILL.md
│ ├── customize.toml
│ └── resources/
│ ├── tea-index.csv
│ └── knowledge/
├── workflows/
│ └── testarch/
│ ├── bmad-teach-me-testing/
Expand All @@ -186,11 +193,6 @@ src/
│ ├── bmad-testarch-test-design/
│ ├── bmad-testarch-test-review/
│ └── bmad-testarch-trace/
└── agents/
└── bmad-tea/
└── resources/
├── tea-index.csv
└── knowledge/
```

## Extending TEA
Expand Down
8 changes: 5 additions & 3 deletions src/workflows/testarch/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# TEA Workflow Step Files

This folder contains the Test Architect (TEA) workflows converted to step-file architecture for strict LLM compliance. Each workflow is tri-modal (create, edit, validate) and uses small, ordered step files instead of a single monolithic instruction file.
This folder contains the Test Architect (TEA) workflows converted to skill-driven step-file architecture for strict LLM compliance. Each workflow is tri-modal (create, edit, validate) and uses small, ordered step files routed from `SKILL.md` instead of a single monolithic instruction file.

## Why Step Files

Expand All @@ -12,7 +12,8 @@ This folder contains the Test Architect (TEA) workflows converted to step-file a

```
<workflow>/
├── workflow.md # Mode routing (create / edit / validate)
├── SKILL.md # Canonical entrypoint and mode routing
├── customize.toml # Workflow customization surface
├── workflow-plan.md # Design reference for step order and intent
├── workflow.yaml # Installer metadata
├── instructions.md # Short entrypoint / summary
Expand Down Expand Up @@ -69,6 +70,7 @@ This folder contains the Test Architect (TEA) workflows converted to step-file a

## Notes

- `workflow.md` is the canonical entrypoint. `instructions.md` is a short summary for quick context.
- `SKILL.md` is the canonical entrypoint. `instructions.md` is a short summary for quick context.
- `customize.toml` defines activation hooks, persistent facts, and the optional `on_complete` hook.
- Output files typically use `{test_artifacts}` or `{project-root}` variables.
- If a workflow produces multiple artifacts (e.g., system-level vs epic-level), the step file will specify which templates and output paths to use.
Loading
Loading