bmad-method-test-architecture-enterprise 1.22.0 → 1.22.1

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test automation, CI/CD quality gates, and structured testing education. Part of the BMad Method ecosystem.",
-      "version": "1.22.0",
+      "version": "1.22.1",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/.github/ISSUE_TEMPLATE/config.yaml

@@ -1,11 +1,8 @@
 blank_issues_enabled: false
 contact_links:
   - name: 📚 Documentation
-    url: https://test-architect.bmad-method.org
-    about: Check the docs first — tutorials, guides, and reference
-  - name: 💬 GitHub Discussions
-    url: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/discussions
-    about: Ask questions and discuss TEA usage before opening an issue
+    url: https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/
+    about: Check the docs first for tutorials, guides, and reference
   - name: 🐛 Troubleshooting Guide
-    url: https://test-architect.bmad-method.org/reference/troubleshooting
+    url: https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/troubleshooting/
     about: Common issues and solutions

package/.github/ISSUE_TEMPLATE/issue.md

@@ -54,7 +54,7 @@ Before submitting, please check:
 
 - [ ] I've read the [Troubleshooting Guide](https://test-architect.bmad-method.org/reference/troubleshooting)
 - [ ] I've verified TEA is installed: `ls -la _bmad/tea/`
-- [ ] I'm using the correct command namespace: `/bmad:tea:*` not `/bmad:bmm:tea:*`
+- [ ] I'm using the current invocation: `/bmad-testarch-*` (Claude Code, Cursor, Windsurf) or `$bmad-testarch-*` (Codex)
 - [ ] I've checked for existing issues on GitHub
 
 **Contribution**

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.22.1] - 2026-08-13
+
+### Removed
+
+- `user_skill_level` from `docs/reference/configuration.md`. It was documented with a full "Impact on TEA" behavior table and exists nowhere in `src/`, `cli/`, `tools/`, or `test/`.
+- The `## Maintainability Assessment` section from `nfr-report-template.md` and `checklist.md`. No maintainability worker exists; `steps-c/step-04-evaluate-and-score.md` dispatches security, performance, reliability, and scalability, and throws if a domain's output is missing. Scalability, which is audited by `steps-c/step-04d-subagent-scalability.md`, is promoted from a subsection of Performance to a top-level assessment.
+- The `.claude/commands/` directory tree from `README.md`. The installer generates no commands directory for Claude Code; only `github-copilot` and `opencode` declare a `commands_target_dir`.
+
 ### Added
 
 - Stable releases now convert `[Unreleased]` into a dated version section on their own. The publish workflow runs `tools/stamp-changelog.js` after the version bump and commits `CHANGELOG.md` with it, so the GitHub Release step finds an exact version heading instead of falling back to an `[Unreleased]` block that grows across releases. Contributors keep writing under `[Unreleased]` exactly as before. Covered by `npm run test:changelog`.
@@ -17,6 +25,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Codex invocation is `$bmad-testarch-<workflow>`, not `$bmad-tea-testarch-<workflow>`. The installer derives a skill's `canonicalId` from its directory name with no module prefix, requires the `SKILL.md` `name` to equal that directory name, and installs to `<target_dir>/<canonicalId>`, so the prefixed form resolves to nothing on any platform. `cli/lib/resolve-skill.js` already probed the unprefixed path. Roughly 24 occurrences corrected, including the ones introduced across nine how-to guides and the quickstart.
+- Removed the remaining `/bmad:tea:*` and `/bmad:bmm:tea:*` namespace from `README.md`, `docs/explanation/tea-overview.md`, `docs/reference/commands.md`, `docs/reference/troubleshooting.md`, and the issue template. Roughly 20 occurrences.
+- Removed the BMad v4 `*<workflow>` syntax from the templates, checklists, and step files that write it into generated artifacts, so a traceability matrix or NFR report no longer instructs the reader to run a command that does not exist. `*gate` named a workflow that has never existed in this module; the NFR report now routes to `/bmad-testarch-trace` Phase 2, which is what the `GATE` menu entry actually does.
+- Code samples imported `@seontechnologies/playwright-utils/fixtures`, which is absent from the package's `exports` map and raises `ERR_PACKAGE_PATH_NOT_EXPORTED`. 113 occurrences across the knowledge base and `docs/how-to/` now use the real per-module subpaths. Related defects in the same samples: `expect` was imported from `api-request/fixtures`, which does not export it; several samples destructured fixtures from a module their import did not provide; and `log.info()` was called on the `log` fixture, which is a plain function rather than the root export's logger object.
+- `nfr-assess` audits scalability, not maintainability. Corrected in `docs/reference/commands.md` and `docs/how-to/workflows/run-nfr-assess.md`, which documented thresholds, evidence sources, and a full report section for a domain the workflow never evaluates.
+- The knowledge base holds 54 fragments, not 42. Corrected in 21 places, including a `wc -l` check in the troubleshooting guide that told the reader to expect 43 lines from a 55-line file. `docs/reference/knowledge-base.md` documented 44 of the 54 and now indexes all of them, with a tier column checked against `tea-index.csv` and fragment ids matching the manifest.
+- `docs/reference/commands.md` described the `test-review` score as four weighted categories. The workflow uses a deduction ledger over 14 criteria with six bonus lines, and `steps-c/step-03f-aggregate-scores.md` explicitly forbids substituting a weighted average.
+- `trace` writes `gate-decision.json`, not `gate-decision-{gate_type}-{story_id}.md`. Corrected in `commands.md` and `configuration.md`, along with the omitted `e2e-trace-summary.json` and the undocumented system-level `test-design/{project_name}-handoff.md`.
+- The troubleshooting guide pointed at `_bmad/tea/module.yaml` for user configuration; workflows read `_bmad/tea/config.yaml`. It also named `@muratkeremozcan/playwright-utils` for a package published as `@seontechnologies/playwright-utils`, used `test-results/` for an artifacts directory that defaults to `_bmad-output/test-artifacts`, and shipped an installation-validation script that reported every workflow missing on a correct install because it looped over pre-rename directory names.
+- Removed published commands that fail when run: `npx playwright install --with-deps chromium@1.40.0` (Playwright has no version-pinning syntax there), six `npm run test:*` scripts the `framework` workflow never generates, `bmad --version`, `npx bmad-method install --verbose` and `--interactive` (neither flag exists), `export TEST_ARTIFACTS` (read by nothing), `node tools/validate-agent-schema.js` (a repo-dev tool absent from a consumer install), and a `DEBUG=bmad:tea:*` mode with no implementation.
+- `https://test-architect.bmad-method.org` has no DNS record. Replaced with the published site URL in the quickstart, the troubleshooting guide, and the issue-template contact links. `CONTRIBUTING.md` pointed its clone URL and both issue-template links at an unrelated repository, and three places linked GitHub Discussions, which is disabled here.
+- `tools/validate-doc-links.js` only matched hrefs beginning with `/`, so relative links were never checked and the gate reported "All links valid" against nine broken ones. It now resolves `./`, `../`, and bare-filename links against the containing file and validates anchors on them.
+- `tools/validate-tea-workflow-descriptions.js` globbed `workflow.md`, a filename removed repo-wide, so `bmad-teach-me-testing` was silently unvalidated while the script's docstring claimed coverage. It now reads `SKILL.md`.
+- A code fence in `docs/how-to/workflows/run-nfr-assess.md` closed 254 lines early, so `## What You Get`, `## Tips`, and two subheadings rendered inside a code block on the published site.
+- `docs/tutorials/tea-lite-quickstart.md` claimed TodoMVC exposes no test IDs and taught CSS-class selectors on that basis. The app ships `data-testid` on every interactive element, so the tutorial taught the pattern `test-review` scores down. The rewritten spec uses `getByTestId` and `getByRole` and was executed against the live app. The tutorial's first actionable step also referenced an installation guide that does not exist, leaving no way to start it.
+- `README.md` claimed support for "10+ platforms" against 45 in the installer's platform table, and a "40-50%" context reduction that measures parallel-subagent speed elsewhere in the docs rather than context. Unverifiable fragment-line counts removed.
+- Fixed workflow invocation instructions across tutorials and how-to guides to use valid slash commands (e.g. `/bmad-tea`, `/bmad-testarch-framework`, `/bmad-testarch-test-design`, `/bmad-testarch-automate`), Codex skill syntax (`$bmad-tea`), and agent menu shortcodes (`TF`, `TD`, `TA`, etc.), replacing invalid bare strings.
+- Updated BMad installation instructions in `tea-lite-quickstart.md` tutorial to explicitly instruct selecting BMad Test Architect alongside BMad Method.
 - `trace` no longer treats "a matching test file exists" as the only shape coverage can take. A requirement verified by running the system produced no file, so trace marked it uncovered and a P0 among them failed the gate, which meant verifying a story scored worse than not verifying it. Trace now reads recorded runtime verification from `{test_artifacts}/live-verification-results.json` as a `live` coverage level. Only a `pass` recorded against the commit under trace counts; `stale`, `unverifiable`, `fail`, `contradicted`, `blocked`, `skipped`, `unmatched`, and `invalid` records are reported as blockers with reasons and count as no coverage. A requirement covered only by live evidence caps the gate at CONCERNS through the same overlay that already caps inferred-oracle coverage, so live evidence can never produce an unconditional PASS. Trace remains a consumer only: it never produces the file and never runs anything to produce it.
 - Aligned forced-unscorable candidate handling in `cli/lib/build-prompt.js` and `cli/lib/parse-report.js`: candidates without matching criteria rows are removed from `## Reviewed Files` when excluded in `## Excluded From Review Set`. Added end-to-end stub-agent coverage in `test/test-test-review-cli.js`.
 - Corrected shared-account guidance in `mobile-test-strategy.md` to recommend per-run accounts/data or explicit backend reset when server state changes.
@@ -48,6 +74,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Documentation sweep for correctness and concision across `docs/`, `README.md`, and the workflow templates that emit text into generated artifacts. `docs/` drops from 17,608 to 12,273 lines with no workflow, parameter, footgun, or caveat removed. `docs/reference/troubleshooting.md` 837 to 315, `docs/reference/configuration.md` 1,149 to 531, `docs/tutorials/learn-testing-tea-academy.md` 258 to 67 (it was a second copy of the how-to and is now a tutorial), and `docs/explanation/` down 29% by collapsing arguments that were stated in full in three to six places into one owner plus pointers.
+- `docs/explanation/subagent-architecture.md` merged into `docs/explanation/step-file-architecture.md`. The two documented one subsystem from opposite sides and neither was complete alone: the worker-split map lived in one and the resulting speedups in the other.
+- The nine `docs/how-to/workflows/*` guides no longer repeat a 9 to 13 line invocation preamble each. `docs/reference/commands.md` gains `## Invoking a TEA Workflow` as the single canonical description of the three invocation surfaces, and the guides point at it. The reference had also kept documenting the superseded weighted-average `test-review` score after `steps-c/step-03f-aggregate-scores.md` moved to the deduction ledger, and kept documenting maintainability as an NFR domain after the workflow moved to scalability.
 - Removed `test:cli` from the default `npm test` script (and Husky pre-commit hook) to keep local git hooks fast, running `test:cli` as part of CI validation in `quality.yaml` and `publish.yaml`.
 - `test-review` now has a single scoring model. The deduction ledger printed in `test-review-template.md` (Critical -10, High -5, Medium -2, Low -1, plus six bonus categories worth 0 or 5 each) is authoritative, and `steps-c/step-03f-aggregate-scores.md` no longer computes a competing weighted average of the four quality dimensions. Grades are limited to A/B/C/D/F. Two live runs over an identical file set had returned 83 and 92 under the old ambiguity, one of them printing a breakdown that did not sum to its own total.
 - `tea-test-review` recomputes the ledger from the report's own violation counts and rejects a report whose published score contradicts its breakdown, whose bonus total is not a multiple of 5 within 0-30, or that omits the `## Quality Score Breakdown` section. The prompt states the same arithmetic, so the strict check never demands a shape the reviewer was not told to produce.

package/CONTRIBUTING.md

@@ -69,7 +69,7 @@ Every contribution should strengthen human-AI collaboration. Ask yourself: **"Do
 ### Suggesting Features or New Modules
 
 1. **Discuss first in Discord** (#suggestions-feedback channel) - the feature request template asks if you've done this
-2. **Check existing issues and discussions** to avoid duplicates
+2. **Check existing issues** to avoid duplicates
 3. **Use the feature request template** when creating an issue
 4. **Be specific** about why this feature would benefit the BMad community and strengthen human-AI collaboration
 
@@ -130,7 +130,7 @@ Example breakdown:
 If you're new to GitHub or pull requests, here's a quick guide:
 
 1. **Fork the repository** - Click the "Fork" button on GitHub to create your own copy
-2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-module-creative-intelligence-suite.git`
+2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/bmad-method-test-architecture-enterprise.git`
 3. **Create a new branch** - Never work on `main` directly!
    ```bash
    git checkout -b fix/description
@@ -255,9 +255,9 @@ By participating in this project, you agree to abide by our Code of Conduct. We
   - **#bmad-development** - Technical questions and discussions
   - **#suggestions-feedback** - Feature ideas and suggestions
   - **#report-bugs-and-issues** - Get help with bugs before filing issues
-- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/issues/new?template=bug_report.md)
-- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/issues/new?template=feature_request.md)
-- 📖 Browse the [GitHub Discussions](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite/discussions)
+- 🐛 Report bugs using the [bug report template](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues/new?template=issue.md)
+- 💡 Suggest features using the [feature request template](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues/new?template=feature_request.md)
+- 📖 Browse [open and closed issues](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/issues)
 
 ---
 

package/README.md

@@ -1,9 +1,11 @@
-# Test Architect (TEA)
+# TEA: Test Engineering Architect
 
 [![Node Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-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), test design, framework setup, CI guidance, ATDD, automation, test review, NFR Evidence Audit, and traceability.
+**TEA** stands for **Test Engineering Architect**. The npm package and repository slug `bmad-method-test-architecture-enterprise` is a package name and never an expansion of the acronym.
+
+TEA 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), test design, framework setup, CI guidance, ATDD, automation, test review, NFR Evidence Audit, and traceability.
 
 TEA is two layers. **TEA Core** decides what must be verified, at what depth, with what evidence, and whether that evidence is sufficient to release; it assumes nothing about your language, framework, or platform. **Execution targets** turn those decisions into runnable tests on a specific stack, and that layer is swappable. See [Verification Architecture](./docs/explanation/verification-architecture.md) for the split, and [Execution Targets](./docs/reference/execution-targets.md) for exactly which stacks are covered at which depth.
 
@@ -27,28 +29,28 @@ TEA plugs into BMad the same way a specialist plugs into a team. It uses the sam
 
 ## Architecture & Flow
 
-BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
+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:
 
-| 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`      | Agent-level knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path   | Read by the TEA agent for direct recommendations        |
-| `src/workflows/testarch/<workflow>/resources/`     | Workflow-local knowledge index and fragments                                                         | Read by workflow steps from that workflow's skill root  |
-| `resources/knowledge/*.md`                         | Reusable fragments — standards, patterns, API references                                             | Selectively read into context based on tier + config    |
+| File / Scope                                       | What it does                                                                                                       | When it loads                                           |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| `src/agents/bmad-tea/SKILL.md`                     | Murat's persona — identity, principles, critical actions; renders the `{agent.menu}` placeholder                   | First — activates the TEA agent                         |
+| `src/agents/bmad-tea/customize.toml`               | Agent customization surface — `[[agent.menu]]` items (two-letter code → skill), 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`      | Agent-level knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path                 | Read by the TEA agent for direct recommendations        |
+| `src/workflows/testarch/<workflow>/resources/`     | Workflow-local knowledge index and fragments                                                                       | Read by workflow steps from that workflow's skill root  |
+| `resources/knowledge/*.md`                         | Reusable fragments — standards, patterns, API references                                                           | Selectively read into context based on tier + config    |
 
 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.
 
@@ -65,45 +67,12 @@ flowchart LR
 
 ### 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:
-
-| Capability        | Claude Code Skills          | BMad Workflows                                                               |
-| ----------------- | --------------------------- | ---------------------------------------------------------------------------- |
-| **Execution**     | Single prompt, one shot     | 5-9 sequential steps with explicit handoffs                                  |
-| **State**         | Stateless                   | YAML frontmatter tracking (`stepsCompleted`, `lastStep`) with resume         |
-| **Knowledge**     | Whatever fits in one prompt | Tiered index (54 fragments), conditional loading by config + stack detection |
-| **Context mgmt**  | Everything in one shot      | Just-in-time step loading, subagent isolation (separate contexts)            |
-| **Output**        | Freeform                    | Templates with `{PLACEHOLDER}` vars filled by specific steps                 |
-| **Validation**    | None                        | Dedicated mode (`steps-v/`) evaluating against checklists                    |
-| **Configuration** | None                        | `module.yaml` with prompted config flags driving conditional behavior        |
-| **Modes**         | None                        | Create / Edit / Validate — three separate step chains per workflow           |
+1. **Trigger** — Direct commands are `/bmad-testarch-automate` (Claude Code, Cursor, Windsurf) and `$bmad-testarch-automate` (Codex). Load the conversational TEA menu with `/bmad-tea` or `$bmad-tea`. `TA` is an agent-menu code available only after TEA is activated; the `[[agent.menu]]` entries in `src/agents/bmad-tea/customize.toml` map `TA` to the `bmad-testarch-automate` skill, and `SKILL.md` renders that menu at runtime from the `{agent.menu}` placeholder.
+2. **Step files carry everything after that.** The workflow's `SKILL.md` resolves its `customize.toml` block, picks the mode (Create / Edit / Validate), and routes to the first step; each step loads on its own, pulls only the knowledge fragments its tier and config flags call for (a backend project pulls ~1,800 lines of Playwright Utils fragments; a fullstack project pulls the browser fragments too), fills any `*-template.md` placeholders, and names the next step. Progress lands in the output file's YAML frontmatter (`stepsCompleted`, `lastStep`, `lastSaved`), so an interrupted run resumes at the next incomplete step, and `steps-v/` scores a finished output against `checklist.md`.
 
-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.
+See [Step-File Architecture](./docs/explanation/step-file-architecture.md) for the loading model, subagent isolation, and the per-workflow step patterns.
 
-**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 → 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.
+**How workflows become commands.** `npx bmad-method install` copies each TEA skill into your tool's skills directory under its own name: `.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Cursor, and Windsurf. Invoking that name loads the skill, and the step-file process takes over. The installer covers 45 platforms, and the skill name is identical on every one of them.
 
 ## Install
 
@@ -116,19 +85,19 @@ npx bmad-method install
 
 ### Tool-specific invocation
 
-| Tool                            | Invocation style                | Example                                      |
-| ------------------------------- | ------------------------------- | -------------------------------------------- |
-| Claude Code / Cursor / Windsurf | Slash command                   | `/bmad:tea:automate`                         |
-| Codex                           | `$` skill from `.agents/skills` | `$bmad-tea` or `$bmad-tea-testarch-automate` |
+| Tool                            | Invocation style                | Example                                  |
+| ------------------------------- | ------------------------------- | ---------------------------------------- |
+| Claude Code / Cursor / Windsurf | Slash command                   | `/bmad-testarch-automate`                |
+| Codex                           | `$` skill from `.agents/skills` | `$bmad-tea` or `$bmad-testarch-automate` |
 
 ## Quickstart
 
 1. Install TEA (above)
-2. Load the TEA menu with `$bmad-tea` if you want a conversational entrypoint.
+2. Load the TEA menu with `/bmad-tea` or `$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, risk assessment, and NFR planning
-   - `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
+   - `TD` / `/bmad-testarch-test-design` / `$bmad-testarch-test-design` — test design, risk assessment, and NFR planning
+   - `AT` / `/bmad-testarch-atdd` / `$bmad-testarch-atdd` — failing acceptance tests first (TDD red phase)
+   - `TA` / `/bmad-testarch-automate` / `$bmad-testarch-automate` — expand automation coverage
 4. Or use in party mode: `/party` to include TEA with other agents
 
 ## Engagement Models
@@ -140,17 +109,20 @@ npx bmad-method install
 
 ## Workflows
 
-| Trigger | Slash Command                | Codex Skill                      | Purpose                                                           |
-| ------- | ---------------------------- | -------------------------------- | ----------------------------------------------------------------- |
-| TMT     | `/bmad:tea:teach-me-testing` | `$bmad-tea-teach-me-testing`     | Teach Me Testing (TEA Academy)                                    |
-| TD      | `/bmad:tea:test-design`      | `$bmad-tea-testarch-test-design` | System-level or epic-level test design and NFR planning           |
-| TF      | `/bmad:tea:framework`        | `$bmad-tea-testarch-framework`   | Scaffold test framework (frontend, backend, fullstack, or mobile) |
-| CI      | `/bmad:tea:ci`               | `$bmad-tea-testarch-ci`          | Set up CI/CD quality pipeline (multi-platform)                    |
-| AT      | `/bmad:tea:atdd`             | `$bmad-tea-testarch-atdd`        | Generate failing acceptance tests + checklist                     |
-| TA      | `/bmad:tea:automate`         | `$bmad-tea-testarch-automate`    | Expand test automation coverage                                   |
-| RV      | `/bmad:tea:test-review`      | `$bmad-tea-testarch-test-review` | Review test quality and score                                     |
-| NR      | `/bmad:tea:nfr-assess`       | `$bmad-tea-testarch-nfr`         | Audit implemented NFR evidence                                    |
-| TR      | `/bmad:tea:trace`            | `$bmad-tea-testarch-trace`       | Trace requirements to tests + gate decision                       |
+| Trigger | Slash Command                | Codex Skill                  | Purpose                                                                     |
+| ------- | ---------------------------- | ---------------------------- | --------------------------------------------------------------------------- |
+| TMT     | `/bmad-teach-me-testing`     | `$bmad-teach-me-testing`     | Teach Me Testing (TEA Academy)                                              |
+| TD      | `/bmad-testarch-test-design` | `$bmad-testarch-test-design` | System-level or epic-level test design and NFR planning                     |
+| TF      | `/bmad-testarch-framework`   | `$bmad-testarch-framework`   | Scaffold test framework (frontend, backend, fullstack, or mobile)           |
+| CI      | `/bmad-testarch-ci`          | `$bmad-testarch-ci`          | Set up CI/CD quality pipeline (multi-platform)                              |
+| AT      | `/bmad-testarch-atdd`        | `$bmad-testarch-atdd`        | Generate failing acceptance tests + checklist                               |
+| TA      | `/bmad-testarch-automate`    | `$bmad-testarch-automate`    | Expand test automation coverage                                             |
+| RV      | `/bmad-testarch-test-review` | `$bmad-testarch-test-review` | Review test quality and score                                               |
+| NR      | `/bmad-testarch-nfr`         | `$bmad-testarch-nfr`         | Audit implemented NFR evidence                                              |
+| TR      | `/bmad-testarch-trace`       | `$bmad-testarch-trace`       | Trace requirements to tests + gate decision                                 |
+| GATE    | agent menu only              | agent menu only              | Route the release gate: test review, NFR evidence audit, then trace Phase 2 |
+
+`GATE` is a routing prompt on the agent menu, so it has no standalone command. Load the agent with `/bmad-tea` or `$bmad-tea` and pick it there.
 
 ## Configuration
 
@@ -178,7 +150,7 @@ Workflows load only the fragments required for the current task to stay focused
 
 ## Module Structure
 
-```
+```text
 src/
 ├── module.yaml
 ├── agents/
@@ -331,14 +303,15 @@ npx bmad-method install
 # Select "Test Architect (TEA)"
 ```
 
-**Test Workflows:**
+**Test Workflows:** type these in the assistant chat, not in a shell.
 
-```bash
-# In your project
-tea              # Load agent
-test-design      # Test workflow
+```text
+/bmad-tea                     # load the agent persona and menu
+/bmad-testarch-test-design    # run a workflow directly
 ```
 
+Codex uses `$` in place of `/`.
+
 ### Rollback a Release (if needed)
 
 If you need to unpublish a version: