ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

Merge branch 'main' into fix/posix-newline-compliance

This commit is contained in:
Brian 2025-11-04 20:16:31 -06:00 committed by GitHub
parent c32afa0260 ba5f76c37d
commit 4571428941
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
27 changed files with 1112 additions and 1815 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
bmad/_cfg/files-manifest.csv
View File

@ -35,6 +35,7 @@ type,name,module,path,hash
"md","instructions","bmb","bmad/bmb/workflows/module-brief/instructions.md","e2275373850ea0745f396ad0c3aa192f06081b52d98777650f6b645333b62926" "md","instructions","bmb","bmad/bmb/workflows/module-brief/instructions.md","e2275373850ea0745f396ad0c3aa192f06081b52d98777650f6b645333b62926"
"md","instructions","bmb","bmad/bmb/workflows/redoc/instructions.md","21dd93b64455f8dd475b508ae9f1076d7e179e99fb6f197476071706b78e3592" "md","instructions","bmb","bmad/bmb/workflows/redoc/instructions.md","21dd93b64455f8dd475b508ae9f1076d7e179e99fb6f197476071706b78e3592"
"md","module-structure","bmb","bmad/bmb/workflows/create-module/module-structure.md","3bdf1d55eec2fccc2c9f44a08f4e0dc489ce47396ff39fa59a82836a911faa54" "md","module-structure","bmb","bmad/bmb/workflows/create-module/module-structure.md","3bdf1d55eec2fccc2c9f44a08f4e0dc489ce47396ff39fa59a82836a911faa54"
"md","tea-README","bmm","bmad/bmm/docs/tea-README.md","2ae906adc1edde5ba3af2a20d78d9cef640897347ec46453233d611115c3e1ac"
"md","README","bmb","bmad/bmb/README.md","aa2beac1fb84267cbaa6d7eb541da824c34177a17cd227f11b189ab3a1e06d33" "md","README","bmb","bmad/bmb/README.md","aa2beac1fb84267cbaa6d7eb541da824c34177a17cd227f11b189ab3a1e06d33"
"md","README","bmb","bmad/bmb/workflows/convert-legacy/README.md","2c11bcf8d974e4f0e0e03f948df42097592751a3aeb9c443fa6cecf05819d49b" "md","README","bmb","bmad/bmb/workflows/convert-legacy/README.md","2c11bcf8d974e4f0e0e03f948df42097592751a3aeb9c443fa6cecf05819d49b"
"md","README","bmb","bmad/bmb/workflows/create-agent/README.md","f4da5c16fb4847252b09b82d70f027ae08e78b75bb101601f2ca3d2c2c884736" "md","README","bmb","bmad/bmb/workflows/create-agent/README.md","f4da5c16fb4847252b09b82d70f027ae08e78b75bb101601f2ca3d2c2c884736"

1 type name module path hash
35 md instructions bmb bmad/bmb/workflows/module-brief/instructions.md e2275373850ea0745f396ad0c3aa192f06081b52d98777650f6b645333b62926
36 md instructions bmb bmad/bmb/workflows/redoc/instructions.md 21dd93b64455f8dd475b508ae9f1076d7e179e99fb6f197476071706b78e3592
37 md module-structure bmb bmad/bmb/workflows/create-module/module-structure.md 3bdf1d55eec2fccc2c9f44a08f4e0dc489ce47396ff39fa59a82836a911faa54
38 md tea-README bmm bmad/bmm/docs/tea-README.md 2ae906adc1edde5ba3af2a20d78d9cef640897347ec46453233d611115c3e1ac
39 md README bmb bmad/bmb/README.md aa2beac1fb84267cbaa6d7eb541da824c34177a17cd227f11b189ab3a1e06d33
40 md README bmb bmad/bmb/workflows/convert-legacy/README.md 2c11bcf8d974e4f0e0e03f948df42097592751a3aeb9c443fa6cecf05819d49b
41 md README bmb bmad/bmb/workflows/create-agent/README.md f4da5c16fb4847252b09b82d70f027ae08e78b75bb101601f2ca3d2c2c884736

2
bmad/bmm/docs/README.md
View File

@ -156,7 +156,7 @@ For detailed technical documentation on specific complex workflows:
Quality assurance guidance: Quality assurance guidance:
- **[Test Architect Guide](../testarch/README.md)** - Comprehensive testing strategy - **[Test Architect Guide](./tea-README.md)** - Comprehensive testing strategy
- Test design workflows - Test design workflows
- Quality gates - Quality gates
- Risk assessment - Risk assessment

2
bmad/bmm/docs/brownfield-guide.md
View File

@ -751,7 +751,7 @@ flowchart TD
**Documentation:** **Documentation:**
- [BMM Workflows Guide](../workflows/README.md) - [BMM Workflows Guide](../workflows/README.md)
- [Test Architect Guide](../testarch/README.md) - [Test Architect Guide](./tea-README.md)
- [BMM Module README](../README.md) - [BMM Module README](../README.md)
--- ---

311
bmad/bmm/docs/tea-README.md Normal file
View File

@ -0,0 +1,311 @@
---
last-redoc-date: 2025-10-14
---
# Test Architect (TEA) Agent Guide
## Overview
- **Persona:** Murat, Master Test Architect and Quality Advisor focused on risk-based testing, fixture architecture, ATDD, and CI/CD governance.
- **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project level and compliance demands.
- **Use When:** Project level ≥2, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required.
## TEA Workflow Lifecycle
TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase:
```
┌──────────────────────────────────────────────────────────┐
│ BMM Phase 2: PLANNING │
│ │
│ PM: *prd │
│ ↓ │
│ TEA: *framework ──→ *ci ──→ *test-design │
│ └─────────┬─────────────┘ │
│ │ (Setup once per project) │
└─────────────────┼──────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ BMM Phase 4: IMPLEMENTATION │
│ (Per Story Cycle) │
│ │
│ ┌─→ SM: *create-story │
│ │ ↓ │
│ │ TEA: *atdd (optional, before dev) │
│ │ ↓ │
│ │ DEV: implements story │
│ │ ↓ │
│ │ TEA: *automate ──→ *test-review (optional) │
│ │ ↓ │
│ │ TEA: *trace (refresh coverage) │
│ │ ↓ │
│ └───[next story] │
└─────────────────┼──────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ EPIC/RELEASE GATE │
│ │
│ TEA: *nfr-assess (if not done earlier) │
│ ↓ │
│ TEA: *test-review (final audit, optional) │
│ ↓ │
│ TEA: *trace (Phase 2: Gate) ──→ PASS | CONCERNS | FAIL | WAIVED │
│ │
└──────────────────────────────────────────────────────────┘
```
### TEA Integration with BMad v6 Workflow
TEA operates **across all four BMad phases**, unlike other agents that are phase-specific:
<details>
<summary><strong>Cross-Phase Integration & Workflow Complexity</strong></summary>
### Phase-Specific Agents (Standard Pattern)
- **Phase 1 (Analysis)**: Analyst agent
- **Phase 2 (Planning)**: PM agent
- **Phase 3 (Solutioning)**: Architect agent
- **Phase 4 (Implementation)**: SM, DEV agents
### TEA: Cross-Phase Quality Agent (Unique Pattern)
TEA is **the only agent that spans all phases**:
```
Phase 1 (Analysis) → [TEA not typically used]
↓
Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup)
↓
Phase 3 (Solutioning) → [TEA validates architecture testability]
↓
Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story)
↓
Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
```
### Why TEA Needs 8 Workflows
**Standard agents**: 1-3 workflows per phase
**TEA**: 8 workflows across 3+ phases
| Phase | TEA Workflows | Frequency | Purpose |
| ----------- | -------------------------------------- | ---------------- | -------------------------------- |
| **Phase 2** | *framework, *ci, \*test-design | Once per project | Establish quality infrastructure |
| **Phase 4** | *atdd, *automate, *test-review, *trace | Per story/sprint | Continuous quality validation |
| **Release** | *nfr-assess, *trace (Phase 2: gate) | Per epic/release | Go/no-go decision |
**Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow.
This complexity **requires specialized documentation** (this guide), **extensive knowledge base** (19+ fragments), and **unique architecture** (`testarch/` directory).
</details>
## Prerequisites and Setup
1. Run the core planning workflows first:
- Analyst `*product-brief`
- Product Manager `*prd`
- Architect `*create-architecture`
2. Confirm `bmad/bmm/config.yaml` defines `project_name`, `output_folder`, `dev_story_location`, and language settings.
3. Ensure a test test framework setup exists; if not, use `*framework` command to create a test framework setup, prior to development.
4. Skim supporting references (knowledge under `testarch/`, command workflows under `workflows/testarch/`).
- `tea-index.csv` + `knowledge/*.md`
## High-Level Cheat Sheets
### Greenfield Feature Launch (Level 2)
| Phase | Test Architect | Dev / Team | Outputs |
| ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Setup | - | Analyst `*product-brief`, PM `*prd`, Architect `*create-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`, `epics.md`, `architecture.md` |
| Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design` | Review risk/design/CI guidance, align backlog | Test scaffold, CI pipeline, risk and coverage strategy |
| Story Prep | - | Scrum Master `*create-story`, `*story-context` | Story markdown + context XML |
| Implementation | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist | Failing acceptance tests + implementation checklist |
| Post-Dev | Execute `*automate`, (Optional) `*test-review`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, quality report, refreshed coverage matrix |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary (owners, waivers) |
<details>
<summary>Execution Notes</summary>
- Run `*framework` only once per repo or when modern harness support is missing.
- `*framework` followed by `*ci` establishes install + pipeline; `*test-design` then handles risk scoring, mitigations, and scenario planning in one pass.
- Use `*atdd` before coding when the team can adopt ATDD; share its checklist with the dev agent.
- Post-implementation, keep `*trace` current, expand coverage with `*automate`, optionally review test quality with `*test-review`. For release gate, run `*trace` with Phase 2 enabled to get deployment decision.
- Use `*test-review` after `*atdd` to validate generated tests, after `*automate` to ensure regression quality, or before gate for final audit.
</details>
<details>
<summary>Worked Example – “Nova CRM” Greenfield Feature</summary>
1. **Planning:** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD and epics; Architect completes `*create-architecture` for the new module.
2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans.
3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*solutioning-gate-check`.
4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan.
5. **Post-Dev and Release:** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled to generate both traceability and gate decision.
</details>
### Brownfield Feature Enhancement (Level 3–4)
| Phase | Test Architect | Dev / Team | Outputs |
| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet |
| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix |
| Story Prep | - | Scrum Master `*create-story` | Updated story markdown |
| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist |
| Post-Dev | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, quality report, refreshed coverage matrix, NFR report |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Product Owner `*solutioning-gate-check`, share release notes | Quality audit, Gate YAML + release summary |
<details>
<summary>Execution Notes</summary>
- Lead with `*trace` so remediation plans target true coverage gaps. Ensure `*framework` and `*ci` are in place early in the engagement; if the brownfield lacks them, run those setup steps immediately after refreshing context.
- `*test-design` should highlight regression hotspots, mitigations, and P0 scenarios.
- Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation.
- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier.
- Use `*test-review` to validate existing brownfield tests or audit new tests before gate.
- Product Owner `*solutioning-gate-check` confirms the team has artifacts before handoff or release.
</details>
<details>
<summary>Worked Example – “Atlas Payments” Brownfield Story</summary>
1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*prd` to update PRD, analysis, and `epics.md`; Architect triggers `*create-architecture` capturing legacy payment flows.
2. **Baseline Coverage:** TEA executes `*trace` to record current coverage in `docs/qa/assessments/atlas-payment-trace.md`.
3. **Risk and Design:** `*test-design` flags settlement edge cases, plans mitigations, and allocates new API/E2E scenarios with P0 priorities.
4. **Story Prep:** Scrum Master generates `stories/story-1.1.md` via `*create-story`, automatically pulling updated context.
5. **ATDD First:** TEA runs `*atdd`, producing failing Playwright specs under `tests/e2e/payments/` plus an implementation checklist.
6. **Implementation:** Dev pairs with the checklist/tests to deliver the story.
7. **Post-Implementation:** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled, performs `*nfr-assess` to validate SLAs. The `*trace` Phase 2 output marks PASS with follow-ups.
</details>
### Enterprise / Compliance Program (Level 4)
| Phase | Test Architect | Dev / Team | Outputs |
| ------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| Strategic Planning | - | Analyst/PM/Architect standard workflows | Enterprise-grade PRD, epics, architecture |
| Quality Planning | Run `*framework`, `*test-design`, `*nfr-assess` | Review guidance, align compliance requirements | Harness scaffold, risk + coverage plan, NFR documentation |
| Pipeline Enablement | Configure `*ci` | Coordinate secrets, pipeline approvals | `.github/workflows/test.yml`, helper scripts |
| Execution | Enforce `*atdd`, `*automate`, `*test-review`, `*trace` per story | Implement stories, resolve TEA findings | Tests, fixtures, quality reports, coverage matrices |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, archive artifacts | Quality audit, updated assessments, gate YAML, audit trail |
<details>
<summary>Execution Notes</summary>
- Use `*atdd` for every story when feasible so acceptance tests lead implementation in regulated environments.
- `*ci` scaffolds selective testing scripts, burn-in jobs, caching, and notifications for long-running suites.
- Enforce `*test-review` per story or sprint to maintain quality standards and ensure compliance with testing best practices.
- Prior to release, rerun coverage (`*trace`, `*automate`), perform final quality audit with `*test-review`, and formalize the decision with `*trace` Phase 2 (gate decision); store everything for audits. Call `*nfr-assess` here if compliance/performance requirements weren't captured during planning.
</details>
<details>
<summary>Worked Example – “Helios Ledger” Enterprise Release</summary>
1. **Strategic Planning:** Analyst/PM/Architect complete PRD, epics, and architecture using the standard workflows.
2. **Quality Planning:** TEA runs `*framework`, `*test-design`, and `*nfr-assess` to establish mitigations, coverage, and NFR targets.
3. **Pipeline Setup:** TEA configures CI via `*ci` with selective execution scripts.
4. **Execution:** For each story, TEA enforces `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings.
5. **Release:** TEA re-checks coverage, performs final quality audit with `*test-review`, and logs the final gate decision via `*trace` Phase 2, archiving artifacts for compliance.
</details>
## Command Catalog
<details>
<summary><strong>Optional Playwright MCP Enhancements</strong></summary>
**Two Playwright MCP servers** (actively maintained, continuously updated):
- `playwright` - Browser automation (`npx @playwright/mcp@latest`)
- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`)
**How MCP Enhances TEA Workflows**:
MCP provides additional capabilities on top of TEA's default AI-based approach:
1. `*test-design`:
- Default: Analysis + documentation
- **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
Benefit:Discover actual functionality, edge cases, undocumented features
2. `*atdd`, `*automate`:
- Default: Infers selectors and interactions from requirements and knowledge fragments
- **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app
Benefit: Accurate selectors from real DOM, verified behavior, refined test code
3. `*automate`:
- Default: Pattern-based fixes from error messages + knowledge fragments
- **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator`
Benefit: Visual failure context, live DOM inspection, root cause discovery
**Config example**:
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"playwright-test": {
"command": "npx",
"args": ["playwright", "run-test-mcp-server"]
}
}
}
```
**To disable**: Set `tea_use_mcp_enhancements: false` in `bmad/bmm/config.yaml` OR remove MCPs from IDE config.
</details>
<br></br>
| Command | Workflow README | Primary Outputs | Notes | With Playwright MCP Enhancements |
| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `*framework` | [📖](../workflows/testarch/framework/README.md) | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | - |
| `*ci` | [📖](../workflows/testarch/ci/README.md) | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | - |
| `*test-design` | [📖](../workflows/testarch/test-design/README.md) | Combined risk assessment, mitigation plan, and coverage strategy | Risk scoring + optional exploratory mode | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality) |
| `*atdd` | [📖](../workflows/testarch/atdd/README.md) | Failing acceptance tests + implementation checklist | TDD red phase + optional recording mode | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM) |
| `*automate` | [📖](../workflows/testarch/automate/README.md) | Prioritized specs, fixtures, README/script updates, DoD summary | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
| `*test-review` | [📖](../workflows/testarch/test-review/README.md) | Test quality review report with 0-100 score, violations, fixes | Reviews tests against knowledge base patterns | - |
| `*nfr-assess` | [📖](../workflows/testarch/nfr-assess/README.md) | NFR assessment report with actions | Focus on security/performance/reliability | - |
| `*trace` | [📖](../workflows/testarch/trace/README.md) | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision | - |
**📖** = Click to view detailed workflow documentation
## Why TEA is Architecturally Different
TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`). This intentional design pattern reflects TEA's unique requirements:
<details>
<summary><strong>Unique Architecture Pattern & Rationale</strong></summary>
### Directory Structure
```
src/modules/bmm/
├── agents/
│ └── tea.agent.yaml # Agent definition (standard location)
├── workflows/
│ └── testarch/ # TEA workflows (standard location)
└── testarch/ # Knowledge base (UNIQUE!)
├── knowledge/ # 21 production-ready test pattern fragments
├── tea-index.csv # Centralized knowledge lookup (21 fragments indexed)
└── README.md # This guide
```
### Why TEA Gets Special Treatment
TEA uniquely requires **extensive domain knowledge** (21 fragments, 12,821 lines: test patterns, CI/CD, fixtures, quality practices, healing strategies), a **centralized reference system** (`tea-index.csv` for on-demand fragment loading), **cross-cutting concerns** (domain-specific patterns vs project-specific artifacts like PRDs/stories), and **optional MCP integration** (healing, exploratory, verification modes). Other BMM agents don't require this architecture.
</details>

2
bmad/bmm/docs/troubleshooting.md
View File

@ -545,7 +545,7 @@ To change locations, edit config.yaml then re-run workflows.
- Read docs/architecture.md (from document-project) - Read docs/architecture.md (from document-project)
- Understand current system design - Understand current system design
3. **For Level 3-4**: 3. **For Level 3-4**:
- Run architecture-review workflow before planning - Run validate-architecture workflow before planning
- Use integration-planning workflow - Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture: 4. **Explicitly document integration strategy** in architecture:
- How new components fit existing structure - How new components fit existing structure

2
bmad/bmm/tasks/daily-standup.xml
View File

@ -64,7 +64,7 @@
<i>Primary: Sarah (PO), Bob (SM), James (Dev)</i> <i>Primary: Sarah (PO), Bob (SM), James (Dev)</i>
<i>Secondary: Murat (TEA)</i> <i>Secondary: Murat (TEA)</i>
</context> </context>
<context type="architecture-review"> <context type="validate-architecture">
<i>Primary: Winston (Architect), James (Dev), Murat (TEA)</i> <i>Primary: Winston (Architect), James (Dev), Murat (TEA)</i>
<i>Secondary: Sarah (PO)</i> <i>Secondary: Sarah (PO)</i>
</context> </context>

4
bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md
View File

@ -355,8 +355,8 @@ See `tea-index.csv` for complete knowledge fragment mapping.
- Ask in team standup - Ask in team standup
- Tag @{tea_agent_username} in Slack/Discord - Tag @{tea_agent_username} in Slack/Discord
- Refer to `testarch/README.md` for workflow documentation - Refer to `./bmm/docs/tea-README.md` for workflow documentation
- Consult `testarch/knowledge/` for testing best practices - Consult `./bmm/testarch/knowledge` for testing best practices
--- ---

4
package-lock.json generated
View File

@ -1,12 +1,12 @@
{ {
"name": "bmad-method", "name": "bmad-method",
"version": "6.0.0-alpha.3", "version": "6.0.0-alpha.5",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "bmad-method", "name": "bmad-method",
"version": "6.0.0-alpha.3", "version": "6.0.0-alpha.5",
"license": "MIT", "license": "MIT",
"dependencies": { "dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1", "@kayvan/markdown-tree-parser": "^1.6.1",

11
src/modules/bmm/docs/README.md
View File

@ -36,7 +36,7 @@ Understanding how BMM adapts to your needs:
--- ---
## 🤖 Agents & Collaboration ## 🤖 Agents and Collaboration
Complete guide to BMM's AI agent team: Complete guide to BMM's AI agent team:
@ -127,7 +127,7 @@ Comprehensive documentation for all BMM workflows organized by phase:
- Complete story lifecycle - Complete story lifecycle
- One-story-at-a-time discipline - One-story-at-a-time discipline
- **[Testing & QA Workflows](./workflows-testing.md)** - Comprehensive quality assurance (1,420 lines) - **[Testing & QA Workflows](./test-architecture.md)** - Comprehensive quality assurance (1,420 lines)
- Test strategy, automation, quality gates - Test strategy, automation, quality gates
- TEA agent and test healing - TEA agent and test healing
- BMad-integrated vs standalone modes - BMad-integrated vs standalone modes
@ -152,11 +152,12 @@ For detailed technical documentation on specific complex workflows:
--- ---
## 🧪 Testing & Quality ## 🧪 Testing and Quality
Quality assurance guidance: Quality assurance guidance:
- **[Test Architect Guide](../testarch/README.md)** - Comprehensive testing strategy <!-- Test Architect documentation to be added -->
- Test design workflows - Test design workflows
- Quality gates - Quality gates
- Risk assessment - Risk assessment
@ -178,7 +179,7 @@ Understanding BMM components:
## 🌐 External Resources ## 🌐 External Resources
### Community & Support ### Community and Support
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help from the community (#general-dev, #bugs-issues) - **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help from the community (#general-dev, #bugs-issues)
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features - **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features

2
src/modules/bmm/docs/agents-guide.md
View File

@ -996,7 +996,7 @@ Quick reference for agent selection:
- [Phase 2: Planning Workflows](./workflows-planning.md) - [Phase 2: Planning Workflows](./workflows-planning.md)
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
- [Phase 4: Implementation Workflows](./workflows-implementation.md) - [Phase 4: Implementation Workflows](./workflows-implementation.md)
- [Testing & QA Workflows](./workflows-testing.md) <!-- Testing & QA Workflows documentation to be added -->
**Advanced References:** **Advanced References:**

11
src/modules/bmm/docs/brownfield-guide.md
View File

@ -277,7 +277,7 @@ It's better to spend 10-30 minutes generating fresh, accurate docs than to waste
**When to skip:** Bug fixes, well-understood features, time-sensitive changes **When to skip:** Bug fixes, well-understood features, time-sensitive changes
See [Workflows Guide](../workflows/README.md) for details. See the [Workflows section in BMM README](../README.md) for details.
### Phase 2: Planning (Required) ### Phase 2: Planning (Required)
@ -736,11 +736,11 @@ flowchart TD
- **[Glossary](./glossary.md)** - Key terminology - **[Glossary](./glossary.md)** - Key terminology
- **[FAQ](./faq.md)** - Common questions - **[FAQ](./faq.md)** - Common questions
- **[Troubleshooting](./troubleshooting.md)** - Problem resolution - **[Troubleshooting](./troubleshooting.md)** - Problem resolution
- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference - **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference
--- ---
## Support & Resources ## Support and Resources
**Community:** **Community:**
@ -750,9 +750,8 @@ flowchart TD
**Documentation:** **Documentation:**
- [BMM Workflows Guide](../workflows/README.md) - [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
- [Test Architect Guide](../testarch/README.md) - [BMM Module README](../README.md) - Complete module and workflow reference
- [BMM Module README](../README.md)
--- ---

6
src/modules/bmm/docs/enterprise-agentic-development.md
View File

@ -9,7 +9,7 @@
## Table of Contents ## Table of Contents
- [The Paradigm Shift](#the-paradigm-shift) - [The Paradigm Shift](#the-paradigm-shift)
- [The Evolving Role of Product Managers & UX Designers](#the-evolving-role-of-product-managers--ux-designers) - [The Evolving Role of Product Managers and UX Designers](#the-evolving-role-of-product-managers-and-ux-designers)
- [How BMad Method Enables PM/UX Technical Evolution](#how-bmad-method-enables-pmux-technical-evolution) - [How BMad Method Enables PM/UX Technical Evolution](#how-bmad-method-enables-pmux-technical-evolution)
- [Team Collaboration Patterns](#team-collaboration-patterns) - [Team Collaboration Patterns](#team-collaboration-patterns)
- [Work Distribution Strategies](#work-distribution-strategies) - [Work Distribution Strategies](#work-distribution-strategies)
@ -59,7 +59,7 @@
--- ---
## The Evolving Role of Product Managers & UX Designers ## The Evolving Role of Product Managers and UX Designers
### The Future is Now ### The Future is Now
@ -672,7 +672,7 @@ PMs write BMad PRDs → Stories auto-fed to cloud AI agents → Parallel impleme
- [FAQ](./faq.md) - Common questions - [FAQ](./faq.md) - Common questions
- [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained - [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained
- [Quick Start Guide](./quick-start.md) - Getting started - [Quick Start Guide](./quick-start.md) - Getting started
- [Workflows Guide](../workflows/README.md) - Complete workflow reference - [Workflow Documentation](./README.md#-workflow-guides) - Complete workflow reference
- [Agents Guide](./agents-guide.md) - Understanding BMad agents - [Agents Guide](./agents-guide.md) - Understanding BMad agents
--- ---

12
src/modules/bmm/docs/faq.md
View File

@ -8,11 +8,11 @@ Quick answers to common questions about the BMad Method Module.
- [Getting Started](#getting-started) - [Getting Started](#getting-started)
- [Choosing the Right Level](#choosing-the-right-level) - [Choosing the Right Level](#choosing-the-right-level)
- [Workflows & Phases](#workflows--phases) - [Workflows and Phases](#workflows-and-phases)
- [Planning Documents](#planning-documents) - [Planning Documents](#planning-documents)
- [Implementation](#implementation) - [Implementation](#implementation)
- [Brownfield Development](#brownfield-development) - [Brownfield Development](#brownfield-development)
- [Tools & Technical](#tools--technical) - [Tools and Technical](#tools-and-technical)
--- ---
@ -26,7 +26,7 @@ Quick answers to common questions about the BMad Method Module.
- Creates the tracking status file - Creates the tracking status file
- Routes you to the correct starting workflow - Routes you to the correct starting workflow
For experienced users: use the [Quick Reference](./quick-start.md#quick-reference-agent--document-mapping) to go directly to the right agent/workflow. For experienced users: use the [Quick Reference](./quick-start.md#quick-reference-agent-document-mapping) to go directly to the right agent/workflow.
### Q: Why do I need fresh chats for each workflow? ### Q: Why do I need fresh chats for each workflow?
@ -108,7 +108,7 @@ The overlap (5-10 stories) is intentional. Choose based on:
--- ---
## Workflows & Phases ## Workflows and Phases
### Q: What's the difference between workflow-status and workflow-init? ### Q: What's the difference between workflow-status and workflow-init?
@ -339,7 +339,7 @@ BMM respects your choice - it won't force modernization, but it will offer it.
--- ---
## Tools & Technical ## Tools and Technical
### Q: Why are my Mermaid diagrams not rendering? ### Q: Why are my Mermaid diagrams not rendering?
@ -399,7 +399,7 @@ Use them together for best results.
**Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality. **Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality.
See [IDE Setup Guides](../../../docs/ide-info/) for configuration specifics. See [IDE Setup Guides](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for configuration specifics.
### Q: Can I customize agents? ### Q: Can I customize agents?

16
src/modules/bmm/docs/glossary.md
View File

@ -7,11 +7,11 @@ Comprehensive terminology reference for the BMad Method Module.
## Navigation ## Navigation
- [Core Concepts](#core-concepts) - [Core Concepts](#core-concepts)
- [Scale & Complexity](#scale--complexity) - [Scale and Complexity](#scale-and-complexity)
- [Planning Documents](#planning-documents) - [Planning Documents](#planning-documents)
- [Workflow & Phases](#workflow--phases) - [Workflow and Phases](#workflow-and-phases)
- [Agents & Roles](#agents--roles) - [Agents and Roles](#agents-and-roles)
- [Status & Tracking](#status--tracking) - [Status and Tracking](#status-and-tracking)
- [Project Types](#project-types) - [Project Types](#project-types)
- [Implementation Terms](#implementation-terms) - [Implementation Terms](#implementation-terms)
@ -41,7 +41,7 @@ A multi-step guided process that orchestrates AI agent activities to produce spe
--- ---
## Scale & Complexity ## Scale and Complexity
### Quick Flow Track ### Quick Flow Track
@ -99,7 +99,7 @@ Game development equivalent of PRD, created by Game Designer agent for game proj
--- ---
## Workflow & Phases ## Workflow and Phases
### Phase 0: Documentation (Prerequisite) ### Phase 0: Documentation (Prerequisite)
@ -135,7 +135,7 @@ Dynamic technical guidance generated for each story via epic-tech-context and st
--- ---
## Agents & Roles ## Agents and Roles
### PM (Product Manager) ### PM (Product Manager)
@ -183,7 +183,7 @@ Multi-agent collaboration feature where all installed agents (19+ from BMM, CIS,
--- ---
## Status & Tracking ## Status and Tracking
### bmm-workflow-status.yaml ### bmm-workflow-status.yaml

6
src/modules/bmm/docs/quick-spec-flow.md
View File

@ -277,7 +277,7 @@ For user-facing changes, Quick Spec Flow captures:
--- ---
## Auto-Validation & Quality Assurance ## Auto-Validation and Quality Assurance
Quick Spec Flow **automatically validates** everything: Quick Spec Flow **automatically validates** everything:
@ -543,7 +543,7 @@ Quick Spec Flow is **fully standalone**:
--- ---
## Tips & Best Practices ## Tips and Best Practices
### 1. **Be Specific in Discovery** ### 1. **Be Specific in Discovery**
@ -643,7 +643,7 @@ Quick Spec Flow is your **fast path from idea to implementation** for:
## Next Steps ## Next Steps
- **Try it now:** Load PM agent and describe a small change - **Try it now:** Load PM agent and describe a small change
- **Learn more:** See `src/modules/bmm/workflows/README.md` for full BMM workflow guide - **Learn more:** See the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation
- **Need help deciding?** Run `workflow-init` to get a recommendation - **Need help deciding?** Run `workflow-init` to get a recommendation
- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj - **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj

10
src/modules/bmm/docs/quick-start.md
View File

@ -37,9 +37,9 @@ The interactive installer will guide you through setup and create a `bmad/` fold
### Step 1: Initialize Your Workflow ### Step 1: Initialize Your Workflow
1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](../docs/ide-info/) for how to activate agents: 1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for how to activate agents:
- [Claude Code](../docs/ide-info/claude-code.md) - [Claude Code](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/ide-info/claude-code.md)
- [VS Code/Cursor/Windsurf](../docs/ide-info/) - Check your IDE folder - [VS Code/Cursor/Windsurf](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) - Check your IDE folder
- Other IDEs also supported - Other IDEs also supported
2. **Wait for the agent's menu** to appear 2. **Wait for the agent's menu** to appear
3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number 3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
@ -107,7 +107,7 @@ The next TRULY REQUIRED step is:
When an agent tells you to run a workflow (like `prd`): When an agent tells you to run a workflow (like `prd`):
1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](../docs/ide-info/) for your IDE's specific instructions 1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for your IDE's specific instructions
2. **Wait for the menu** to appear 2. **Wait for the menu** to appear
3. **Tell the agent** to run it using any of these formats: 3. **Tell the agent** to run it using any of these formats:
- Type the shorthand: `*prd` - Type the shorthand: `*prd`
@ -350,7 +350,7 @@ A: Yes, once you learn the flow. Use the Quick Reference in Step 2 to go directl
- **During workflows**: Agents guide you with questions and explanations - **During workflows**: Agents guide you with questions and explanations
- **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues - **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
- **Complete guide**: [BMM Workflows README](../src/modules/bmm/workflows/README.md) - **Complete guide**: [BMM Workflow Documentation](./README.md#-workflow-guides)
- **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode) - **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
--- ---

2
src/modules/bmm/docs/scale-adaptive-system.md
View File

@ -592,7 +592,7 @@ Run `workflow-init` on existing projects to migrate to new tracking system. It d
- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows - **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
- **[Glossary](./glossary.md)** - Complete terminology - **[Glossary](./glossary.md)** - Complete terminology
- **[FAQ](./faq.md)** - Common questions - **[FAQ](./faq.md)** - Common questions
- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference - **[Workflows Guide](./README.md#-workflow-guides)** - Complete workflow reference
--- ---

329
src/modules/bmm/docs/test-architecture.md Normal file
View File

@ -0,0 +1,329 @@
---
last-redoc-date: 2025-10-14
---
# Test Architect (TEA) Agent Guide
## Overview
- **Persona:** Murat, Master Test Architect and Quality Advisor focused on risk-based testing, fixture architecture, ATDD, and CI/CD governance.
- **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project level and compliance demands.
- **Use When:** Project level ≥2, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required.
## TEA Workflow Lifecycle
TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase:
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
subgraph Phase2["<b>Phase 2: PLANNING</b>"]
PM["<b>PM: *prd</b>"]
Framework["<b>TEA: *framework</b>"]
CI["<b>TEA: *ci</b>"]
TestDesign["<b>TEA: *test-design</b>"]
PM --> Framework
Framework --> CI
CI --> TestDesign
SetupNote["<b>Setup once per project</b>"]
TestDesign -.-> SetupNote
end
subgraph Phase4["<b>Phase 4: IMPLEMENTATION - Per Story Cycle</b>"]
CreateStory["<b>SM: *create-story</b>"]
ATDD["<b>TEA: *atdd (optional, before dev)</b>"]
DevImpl["<b>DEV: implements story</b>"]
Automate["<b>TEA: *automate</b>"]
TestReview1["<b>TEA: *test-review (optional)</b>"]
Trace1["<b>TEA: *trace (refresh coverage)</b>"]
CreateStory --> ATDD
ATDD --> DevImpl
DevImpl --> Automate
Automate --> TestReview1
TestReview1 --> Trace1
Trace1 -.->|next story| CreateStory
end
subgraph Gate["<b>EPIC/RELEASE GATE</b>"]
NFR["<b>TEA: *nfr-assess (if not done earlier)</b>"]
TestReview2["<b>TEA: *test-review (final audit, optional)</b>"]
TraceGate["<b>TEA: *trace - Phase 2: Gate</b>"]
GateDecision{"<b>Gate Decision</b>"}
NFR --> TestReview2
TestReview2 --> TraceGate
TraceGate --> GateDecision
GateDecision -->|PASS| Pass["<b>PASS ✅</b>"]
GateDecision -->|CONCERNS| Concerns["<b>CONCERNS ⚠️</b>"]
GateDecision -->|FAIL| Fail["<b>FAIL ❌</b>"]
GateDecision -->|WAIVED| Waived["<b>WAIVED ⏭️</b>"]
end
Phase2 --> Phase4
Phase4 --> Gate
style Phase2 fill:#bbdefb,stroke:#0d47a1,stroke-width:3px,color:#000
style Phase4 fill:#e1bee7,stroke:#4a148c,stroke-width:3px,color:#000
style Gate fill:#ffe082,stroke:#f57c00,stroke-width:3px,color:#000
style Pass fill:#4caf50,stroke:#1b5e20,stroke-width:3px,color:#000
style Concerns fill:#ffc107,stroke:#f57f17,stroke-width:3px,color:#000
style Fail fill:#f44336,stroke:#b71c1c,stroke-width:3px,color:#000
style Waived fill:#9c27b0,stroke:#4a148c,stroke-width:3px,color:#000
```
### TEA Integration with BMad v6 Workflow
TEA operates **across all four BMad phases**, unlike other agents that are phase-specific:
<details>
<summary><strong>Cross-Phase Integration & Workflow Complexity</strong></summary>
### Phase-Specific Agents (Standard Pattern)
- **Phase 1 (Analysis)**: Analyst agent
- **Phase 2 (Planning)**: PM agent
- **Phase 3 (Solutioning)**: Architect agent
- **Phase 4 (Implementation)**: SM, DEV agents
### TEA: Cross-Phase Quality Agent (Unique Pattern)
TEA is **the only agent that spans all phases**:
```
Phase 1 (Analysis) → [TEA not typically used]
↓
Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup)
↓
Phase 3 (Solutioning) → [TEA validates architecture testability]
↓
Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story)
↓
Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
```
### Why TEA Needs 8 Workflows
**Standard agents**: 1-3 workflows per phase
**TEA**: 8 workflows across 3+ phases
| Phase | TEA Workflows | Frequency | Purpose |
| ----------- | -------------------------------------- | ---------------- | -------------------------------- |
| **Phase 2** | *framework, *ci, \*test-design | Once per project | Establish quality infrastructure |
| **Phase 4** | *atdd, *automate, *test-review, *trace | Per story/sprint | Continuous quality validation |
| **Release** | *nfr-assess, *trace (Phase 2: gate) | Per epic/release | Go/no-go decision |
**Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow.
This complexity **requires specialized documentation** (this guide), **extensive knowledge base** (19+ fragments), and **unique architecture** (`testarch/` directory).
</details>
## Prerequisites and Setup
1. Run the core planning workflows first:
- Analyst `*product-brief`
- Product Manager `*prd`
- Architect `*create-architecture`
2. Confirm `bmad/bmm/config.yaml` defines `project_name`, `output_folder`, `dev_story_location`, and language settings.
3. Ensure a test test framework setup exists; if not, use `*framework` command to create a test framework setup, prior to development.
4. Skim supporting references (knowledge under `testarch/`, command workflows under `workflows/testarch/`).
- `tea-index.csv` + `knowledge/*.md`
## High-Level Cheat Sheets
### Greenfield Feature Launch (Level 2)
| Phase | Test Architect | Dev / Team | Outputs |
| ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Setup | - | Analyst `*product-brief`, PM `*prd`, Architect `*create-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`, `epics.md`, `architecture.md` |
| Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design` | Review risk/design/CI guidance, align backlog | Test scaffold, CI pipeline, risk and coverage strategy |
| Story Prep | - | Scrum Master `*create-story`, `*story-context` | Story markdown + context XML |
| Implementation | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist | Failing acceptance tests + implementation checklist |
| Post-Dev | Execute `*automate`, (Optional) `*test-review`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, quality report, refreshed coverage matrix |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary (owners, waivers) |
<details>
<summary>Execution Notes</summary>
- Run `*framework` only once per repo or when modern harness support is missing.
- `*framework` followed by `*ci` establishes install + pipeline; `*test-design` then handles risk scoring, mitigations, and scenario planning in one pass.
- Use `*atdd` before coding when the team can adopt ATDD; share its checklist with the dev agent.
- Post-implementation, keep `*trace` current, expand coverage with `*automate`, optionally review test quality with `*test-review`. For release gate, run `*trace` with Phase 2 enabled to get deployment decision.
- Use `*test-review` after `*atdd` to validate generated tests, after `*automate` to ensure regression quality, or before gate for final audit.
</details>
<details>
<summary>Worked Example – “Nova CRM” Greenfield Feature</summary>
1. **Planning:** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD and epics; Architect completes `*create-architecture` for the new module.
2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans.
3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*solutioning-gate-check`.
4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan.
5. **Post-Dev and Release:** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled to generate both traceability and gate decision.
</details>
### Brownfield Feature Enhancement (Level 3–4)
| Phase | Test Architect | Dev / Team | Outputs |
| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
| Refresh Context | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
| Baseline Coverage | Run `*trace` to inventory existing tests | Review matrix, flag hotspots | Coverage matrix + initial gate snippet |
| Risk Targeting | Run `*test-design` | Align remediation/backlog priorities | Brownfield risk memo + scenario matrix |
| Story Prep | - | Scrum Master `*create-story` | Updated story markdown |
| Implementation | (Optional) Run `*atdd` before dev | Implement story, referencing checklist/tests | Failing acceptance tests + implementation checklist |
| Post-Dev | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests | Regression specs, quality report, refreshed coverage matrix, NFR report |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Product Owner `*solutioning-gate-check`, share release notes | Quality audit, Gate YAML + release summary |
<details>
<summary>Execution Notes</summary>
- Lead with `*trace` so remediation plans target true coverage gaps. Ensure `*framework` and `*ci` are in place early in the engagement; if the brownfield lacks them, run those setup steps immediately after refreshing context.
- `*test-design` should highlight regression hotspots, mitigations, and P0 scenarios.
- Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation.
- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier.
- Use `*test-review` to validate existing brownfield tests or audit new tests before gate.
- Product Owner `*solutioning-gate-check` confirms the team has artifacts before handoff or release.
</details>
<details>
<summary>Worked Example – “Atlas Payments” Brownfield Story</summary>
1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*prd` to update PRD, analysis, and `epics.md`; Architect triggers `*create-architecture` capturing legacy payment flows.
2. **Baseline Coverage:** TEA executes `*trace` to record current coverage in `docs/qa/assessments/atlas-payment-trace.md`.
3. **Risk and Design:** `*test-design` flags settlement edge cases, plans mitigations, and allocates new API/E2E scenarios with P0 priorities.
4. **Story Prep:** Scrum Master generates `stories/story-1.1.md` via `*create-story`, automatically pulling updated context.
5. **ATDD First:** TEA runs `*atdd`, producing failing Playwright specs under `tests/e2e/payments/` plus an implementation checklist.
6. **Implementation:** Dev pairs with the checklist/tests to deliver the story.
7. **Post-Implementation:** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled, performs `*nfr-assess` to validate SLAs. The `*trace` Phase 2 output marks PASS with follow-ups.
</details>
### Enterprise / Compliance Program (Level 4)
| Phase | Test Architect | Dev / Team | Outputs |
| ------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| Strategic Planning | - | Analyst/PM/Architect standard workflows | Enterprise-grade PRD, epics, architecture |
| Quality Planning | Run `*framework`, `*test-design`, `*nfr-assess` | Review guidance, align compliance requirements | Harness scaffold, risk + coverage plan, NFR documentation |
| Pipeline Enablement | Configure `*ci` | Coordinate secrets, pipeline approvals | `.github/workflows/test.yml`, helper scripts |
| Execution | Enforce `*atdd`, `*automate`, `*test-review`, `*trace` per story | Implement stories, resolve TEA findings | Tests, fixtures, quality reports, coverage matrices |
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, archive artifacts | Quality audit, updated assessments, gate YAML, audit trail |
<details>
<summary>Execution Notes</summary>
- Use `*atdd` for every story when feasible so acceptance tests lead implementation in regulated environments.
- `*ci` scaffolds selective testing scripts, burn-in jobs, caching, and notifications for long-running suites.
- Enforce `*test-review` per story or sprint to maintain quality standards and ensure compliance with testing best practices.
- Prior to release, rerun coverage (`*trace`, `*automate`), perform final quality audit with `*test-review`, and formalize the decision with `*trace` Phase 2 (gate decision); store everything for audits. Call `*nfr-assess` here if compliance/performance requirements weren't captured during planning.
</details>
<details>
<summary>Worked Example – “Helios Ledger” Enterprise Release</summary>
1. **Strategic Planning:** Analyst/PM/Architect complete PRD, epics, and architecture using the standard workflows.
2. **Quality Planning:** TEA runs `*framework`, `*test-design`, and `*nfr-assess` to establish mitigations, coverage, and NFR targets.
3. **Pipeline Setup:** TEA configures CI via `*ci` with selective execution scripts.
4. **Execution:** For each story, TEA enforces `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings.
5. **Release:** TEA re-checks coverage, performs final quality audit with `*test-review`, and logs the final gate decision via `*trace` Phase 2, archiving artifacts for compliance.
</details>
## Command Catalog
<details>
<summary><strong>Optional Playwright MCP Enhancements</strong></summary>
**Two Playwright MCP servers** (actively maintained, continuously updated):
- `playwright` - Browser automation (`npx @playwright/mcp@latest`)
- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`)
**How MCP Enhances TEA Workflows**:
MCP provides additional capabilities on top of TEA's default AI-based approach:
1. `*test-design`:
- Default: Analysis + documentation
- **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
Benefit:Discover actual functionality, edge cases, undocumented features
2. `*atdd`, `*automate`:
- Default: Infers selectors and interactions from requirements and knowledge fragments
- **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app
Benefit: Accurate selectors from real DOM, verified behavior, refined test code
3. `*automate`:
- Default: Pattern-based fixes from error messages + knowledge fragments
- **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator`
Benefit: Visual failure context, live DOM inspection, root cause discovery
**Config example**:
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"playwright-test": {
"command": "npx",
"args": ["playwright", "run-test-mcp-server"]
}
}
}
```
**To disable**: Set `tea_use_mcp_enhancements: false` in `bmad/bmm/config.yaml` OR remove MCPs from IDE config.
</details>
<br></br>
| Command | Workflow README | Primary Outputs | Notes | With Playwright MCP Enhancements |
| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `*framework` | [📖](../workflows/testarch/framework/README.md) | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs | Use when no production-ready harness exists | - |
| `*ci` | [📖](../workflows/testarch/ci/README.md) | CI workflow, selective test scripts, secrets checklist | Platform-aware (GitHub Actions default) | - |
| `*test-design` | [📖](../workflows/testarch/test-design/README.md) | Combined risk assessment, mitigation plan, and coverage strategy | Risk scoring + optional exploratory mode | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality) |
| `*atdd` | [📖](../workflows/testarch/atdd/README.md) | Failing acceptance tests + implementation checklist | TDD red phase + optional recording mode | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM) |
| `*automate` | [📖](../workflows/testarch/automate/README.md) | Prioritized specs, fixtures, README/script updates, DoD summary | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
| `*test-review` | [📖](../workflows/testarch/test-review/README.md) | Test quality review report with 0-100 score, violations, fixes | Reviews tests against knowledge base patterns | - |
| `*nfr-assess` | [📖](../workflows/testarch/nfr-assess/README.md) | NFR assessment report with actions | Focus on security/performance/reliability | - |
| `*trace` | [📖](../workflows/testarch/trace/README.md) | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision | - |
**📖** = Click to view detailed workflow documentation
## Why TEA is Architecturally Different
TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`). This intentional design pattern reflects TEA's unique requirements:
<details>
<summary><strong>Unique Architecture Pattern & Rationale</strong></summary>
### Directory Structure
```
src/modules/bmm/
├── agents/
│ └── tea.agent.yaml # Agent definition (standard location)
├── workflows/
│ └── testarch/ # TEA workflows (standard location)
└── testarch/ # Knowledge base (UNIQUE!)
├── knowledge/ # 21 production-ready test pattern fragments
├── tea-index.csv # Centralized knowledge lookup (21 fragments indexed)
└── README.md # This guide
```
### Why TEA Gets Special Treatment
TEA uniquely requires **extensive domain knowledge** (21 fragments, 12,821 lines: test patterns, CI/CD, fixtures, quality practices, healing strategies), a **centralized reference system** (`tea-index.csv` for on-demand fragment loading), **cross-cutting concerns** (domain-specific patterns vs project-specific artifacts like PRDs/stories), and **optional MCP integration** (healing, exploratory, verification modes). Other BMM agents don't require this architecture.
</details>

14
src/modules/bmm/docs/troubleshooting.md
View File

@ -30,18 +30,18 @@ flowchart TD
## Table of Contents ## Table of Contents
- [Setup & Installation Issues](#setup--installation-issues) - [Setup and Installation Issues](#setup-and-installation-issues)
- [Level Detection Problems](#level-detection-problems) - [Level Detection Problems](#level-detection-problems)
- [Workflow Issues](#workflow-issues) - [Workflow Issues](#workflow-issues)
- [Context & Documentation Issues](#context--documentation-issues) - [Context and Documentation Issues](#context-and-documentation-issues)
- [Implementation Issues](#implementation-issues) - [Implementation Issues](#implementation-issues)
- [File & Path Issues](#file--path-issues) - [File and Path Issues](#file-and-path-issues)
- [Agent Behavior Issues](#agent-behavior-issues) - [Agent Behavior Issues](#agent-behavior-issues)
- [Integration Issues (Brownfield)](#integration-issues-brownfield) - [Integration Issues (Brownfield)](#integration-issues-brownfield)
--- ---
## Setup & Installation Issues ## Setup and Installation Issues
### Problem: BMM not found after installation ### Problem: BMM not found after installation
@ -238,7 +238,7 @@ workflow-init asks: "Is this work in progress or previous effort?"
--- ---
## Context & Documentation Issues ## Context and Documentation Issues
### Problem: AI agents lack codebase understanding (Brownfield) ### Problem: AI agents lack codebase understanding (Brownfield)
@ -393,7 +393,7 @@ For most brownfield projects, **Deep scan is sufficient**.
--- ---
## File & Path Issues ## File and Path Issues
### Problem: Output files in wrong location ### Problem: Output files in wrong location
@ -545,7 +545,7 @@ To change locations, edit config.yaml then re-run workflows.
- Read docs/architecture.md (from document-project) - Read docs/architecture.md (from document-project)
- Understand current system design - Understand current system design
3. **For Level 3-4**: 3. **For Level 3-4**:
- Run architecture-review workflow before planning - Run validate-architecture workflow before planning
- Use integration-planning workflow - Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture: 4. **Explicitly document integration strategy** in architecture:
- How new components fit existing structure - How new components fit existing structure

80
src/modules/bmm/docs/workflows-analysis.md
View File

@ -1,7 +1,5 @@
# BMM Analysis Workflows (Phase 1) # BMM Analysis Workflows (Phase 1)
**Reading Time:** ~12 minutes
## Overview ## Overview
Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help you understand your project space before committing to detailed planning. These workflows facilitate creative thinking, market validation, and strategic alignment. Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help you understand your project space before committing to detailed planning. These workflows facilitate creative thinking, market validation, and strategic alignment.
@ -17,17 +15,61 @@ Phase 1 (Analysis) workflows are **optional** exploration and discovery tools th
- Continuing an existing project with clear requirements - Continuing an existing project with clear requirements
- Working on well-defined features with known solutions - Working on well-defined features with known solutions
- Operating under strict time constraints where discovery is complete - Working under strict constraints where discovery is complete
---
## Phase 1 Workflow Map
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
subgraph Creative["<b>CREATIVE EXPLORATION</b>"]
direction TB
BrainstormProject["<b>Analyst: brainstorm-project</b><br/>Multi-track solution exploration"]
BrainstormGame["<b>Analyst: brainstorm-game</b><br/>Game concept generation"]
end
subgraph Strategic["<b>STRATEGIC PLANNING</b>"]
direction TB
ProductBrief["<b>Analyst: product-brief</b><br/>Product vision and strategy"]
GameBrief["<b>Game Designer: game-brief</b><br/>Game vision capture"]
end
subgraph Research["<b>RESEARCH AND INVESTIGATION</b>"]
direction TB
ResearchWF["<b>Analyst: research</b><br/>Market, technical, competitive analysis"]
end
Creative -.->|Software projects| ProductBrief
Creative -.->|Game projects| GameBrief
BrainstormProject -.->|May inform| ResearchWF
BrainstormGame -.->|May inform| ResearchWF
ResearchWF -.->|Feeds into| ProductBrief
ResearchWF -.->|Feeds into| GameBrief
style Creative fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000
style Strategic fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000
style Research fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
style BrainstormProject fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000
style BrainstormGame fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000
style ProductBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000
style GameBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000
style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000
```
---
## Quick Reference ## Quick Reference
| Workflow | Agent | Duration | Required | Purpose | | Workflow | Agent | Required | Purpose |
| ------------------ | ------- | --------- | ----------- | ----------------------------------------------------------- | | ------------------ | ------------- | ----------- | ----------------------------------------------------------- |
| brainstorm-project | Analyst | 30-60 min | No | Explore solution approaches and architectures | | brainstorm-project | Analyst | No | Explore solution approaches and architectures |
| brainstorm-game | Analyst | 45-90 min | No | Generate game concepts using creative techniques | | brainstorm-game | Analyst | No | Generate game concepts using creative techniques |
| product-brief | PM | 60-90 min | Recommended | Define product vision and strategy | | product-brief | Analyst | Recommended | Define product vision and strategy |
| game-brief | PM | 60-90 min | Recommended | Capture game vision before GDD | | game-brief | Game Designer | Recommended | Capture game vision before GDD |
| research | Analyst | Varies | No | Multi-type research system (market, technical, competitive) | | research | Analyst | No | Multi-type research system (market, technical, competitive) |
--- ---
@ -40,7 +82,6 @@ Generate multiple solution approaches for software projects through parallel ide
**Agent:** Analyst **Agent:** Analyst
**Phase:** 1 (Analysis) **Phase:** 1 (Analysis)
**Required:** No **Required:** No
**Typical Duration:** 30-60 minutes
### When to Use ### When to Use
@ -125,7 +166,6 @@ Generate and refine game concepts through systematic creative exploration using
**Agent:** Analyst **Agent:** Analyst
**Phase:** 1 (Analysis) **Phase:** 1 (Analysis)
**Required:** No **Required:** No
**Typical Duration:** 45-90 minutes
### When to Use ### When to Use
@ -196,10 +236,9 @@ Each method generates distinct artifacts that are then evaluated against design
Interactive product brief creation that guides users through defining their product vision with multiple input sources and conversational collaboration. Interactive product brief creation that guides users through defining their product vision with multiple input sources and conversational collaboration.
**Agent:** PM **Agent:** Analyst
**Phase:** 1 (Analysis) **Phase:** 1 (Analysis)
**Required:** Recommended (skip only if PRD already exists) **Required:** Recommended (skip only if PRD already exists)
**Typical Duration:** 60-90 minutes (Interactive), 20-30 minutes (YOLO)
### When to Use ### When to Use
@ -222,13 +261,13 @@ Interactive product brief creation that guides users through defining their prod
- Step-by-step collaborative development - Step-by-step collaborative development
- Probing questions to refine thinking - Probing questions to refine thinking
- Deep exploration of problem/solution fit - Deep exploration of problem/solution fit
- 60-90 minutes with high-quality output - High-quality output with thorough exploration
**YOLO Mode**: **YOLO Mode**:
- AI generates complete draft from initial context - AI generates complete draft from initial context
- User reviews and refines sections iteratively - User reviews and refines sections iteratively
- 20-30 minutes for rapid draft - Faster for rapid draft generation
- Best for time-constrained situations or when you have clear vision - Best for time-constrained situations or when you have clear vision
### Process Overview ### Process Overview
@ -317,10 +356,9 @@ Interactive product brief creation that guides users through defining their prod
Lightweight, interactive brainstorming and planning session that captures game vision before diving into detailed Game Design Documents. Lightweight, interactive brainstorming and planning session that captures game vision before diving into detailed Game Design Documents.
**Agent:** PM **Agent:** Game Designer
**Phase:** 1 (Analysis) **Phase:** 1 (Analysis)
**Required:** Recommended for game projects **Required:** Recommended for game projects
**Typical Duration:** 60-90 minutes
### When to Use ### When to Use
@ -339,14 +377,13 @@ Lightweight, interactive brainstorming and planning session that captures game v
### Comparison: Game Brief vs GDD ### Comparison: Game Brief vs GDD
| Aspect | Game Brief | GDD | | Aspect | Game Brief | GDD |
| --------------- | --------------------------- | ------------------------- | | ------------ | --------------------------- | ------------------------- |
| Purpose | Validate concept | Design for implementation | | Purpose | Validate concept | Design for implementation |
| Detail Level | High-level vision | Detailed specifications | | Detail Level | High-level vision | Detailed specifications |
| Time Investment | 1-2 hours | 4-10 hours |
| Audience | Self, team, stakeholders | Development team | | Audience | Self, team, stakeholders | Development team |
| Scope | Concept validation | Implementation roadmap | | Scope | Concept validation | Implementation roadmap |
| Format | Conversational, exploratory | Structured, comprehensive | | Format | Conversational, exploratory | Structured, comprehensive |
| Output | 3-5 pages | 10-30+ pages | | Output | Concise vision document | Comprehensive design doc |
### Comparison: Game Brief vs Product Brief ### Comparison: Game Brief vs Product Brief
@ -441,7 +478,6 @@ Comprehensive, adaptive multi-type research system that consolidates various res
**Agent:** Analyst **Agent:** Analyst
**Phase:** 1 (Analysis) **Phase:** 1 (Analysis)
**Required:** No **Required:** No
**Typical Duration:** Varies by type (Quick: 30-60 min, Standard: 2-4 hours, Comprehensive: 4-8 hours)
### Research Types ### Research Types

1876
src/modules/bmm/docs/workflows-implementation.md
View File

File diff suppressed because it is too large Load Diff

109
src/modules/bmm/docs/workflows-planning.md
View File

@ -1,25 +1,90 @@
# BMM Planning Workflows (Phase 2) # BMM Planning Workflows (Phase 2)
**Reading Time:** ~15 minutes
## Overview ## Overview
Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements that guide implementation. BMM uses a **scale-adaptive planning system** where the workflow automatically selects the right level of detail based on project complexity. Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements that guide implementation. BMM uses a **scale-adaptive planning system** where the workflow automatically selects the right level of detail based on project complexity.
**Key principle:** One workflow to rule them all - `plan-project` intelligently routes to the appropriate planning flow based on project characteristics. **Key principle:** One workflow to rule them all - `plan-project` intelligently routes to the appropriate planning flow based on project characteristics.
---
## Phase 2 Planning Flow
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
Entry["<b>START: plan-project</b><br/>Discovery and routing"]
subgraph QuickFlow["<b>QUICK FLOW (Levels 0-1)</b>"]
TechSpec["<b>PM: tech-spec</b><br/>Lightweight spec for simple changes"]
end
subgraph StandardFlow["<b>STANDARD PLANNING (Levels 2-4)</b>"]
PRD["<b>PM: prd</b><br/>Strategic PRD"]
GDD["<b>Game Designer: gdd</b><br/>Game design document"]
Narrative["<b>Game Designer: narrative</b><br/>Story-driven design"]
UXDesign["<b>UX Designer: ux</b><br/>UX-first specification"]
Epics["<b>PM: create-epics-and-stories</b><br/>Break requirements into epics and stories"]
end
subgraph Updates["<b>STORY UPDATES (Anytime After Epics Created)</b>"]
CorrectCourse["<b>PM/SM: correct-course</b><br/>Update epics/stories mid-stream"]
end
Entry -->|Level 0-1<br/>Simple| QuickFlow
Entry -->|Level 2-4<br/>Software| PRD
Entry -->|Level 2-4<br/>Game| GDD
Entry -->|Level 2-4<br/>Story-driven| Narrative
Entry -->|Level 2-4<br/>UX-first| UXDesign
PRD --> Epics
GDD --> Epics
Narrative --> Epics
UXDesign -.->|May update| Epics
Epics --> Phase3["<b>Phase 3: Architecture</b>"]
Phase3 -.->|May update| Epics
QuickFlow --> Phase4["<b>Phase 4: Implementation</b>"]
Phase3 --> Phase4
Phase4 -.->|Significant changes| CorrectCourse
CorrectCourse -.->|Updates| Epics
style Entry fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
style StandardFlow fill:#e1bee7,stroke:#6a1b9a,stroke-width:3px,color:#000
style Updates fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#000
style Phase3 fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000
style TechSpec fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
style PRD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style GDD fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style Narrative fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style UXDesign fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
style Epics fill:#ba68c8,stroke:#6a1b9a,stroke-width:3px,color:#000
style CorrectCourse fill:#ef5350,stroke:#c62828,stroke-width:2px,color:#000
```
---
## Quick Reference ## Quick Reference
| Workflow | Project Levels | Duration | Purpose | | Workflow | Agent | Project Levels | Purpose |
| ------------- | -------------- | ---------- | --------------------------------------- | | ---------------------------- | ------------- | -------------- | ---------------------------------------------------- |
| **prd** | 2-4 | 2-6 hours | Strategic PRD + tactical epic breakdown | | **prd** | PM | 2-4 | Strategic PRD |
| **tech-spec** | 0-1 | 30-90 min | Lightweight technical specification | | **create-epics-and-stories** | PM | 2-4 | Break PRD/GDD into epics and stories (standalone OK) |
| **gdd** | 2-4 (games) | 4-10 hours | Complete game design document | | **tech-spec** | PM | 0-1 | Lightweight technical specification |
| **narrative** | 2-4 (story) | 3-8 hours | Story-driven game/experience design | | **gdd** | Game Designer | 2-4 (games) | Complete game design document |
| **ux** | 2-4 (UX-heavy) | 3-6 hours | UX-first design specification | | **narrative** | Game Designer | 2-4 (story) | Story-driven game/experience design |
| **ux** | UX Designer | 2-4 (UX-heavy) | UX-first design specification |
**Note:** The `plan-project` workflow is your single entry point. It automatically routes to the right planning workflow based on your answers to discovery questions. **Note:** The `plan-project` workflow is your single entry point. It automatically routes to the right planning workflow based on your answers to discovery questions.
**Critical:** After PRD/GDD/Narrative complete, you must run `create-epics-and-stories` to generate user stories (can be done in same chat or separate chat later). These stories can be updated anytime via UX-Design, Architecture decisions, or `correct-course` during implementation.
--- ---
## Understanding Scale-Adaptive Planning ## Understanding Scale-Adaptive Planning
@ -73,7 +138,6 @@ Single unified entry point for all planning workflows. Uses conversational disco
**Agent:** PM (orchestrates other agents as needed) **Agent:** PM (orchestrates other agents as needed)
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Required:** Yes (for all projects) **Required:** Yes (for all projects)
**Typical Duration:** Varies by target workflow
### When to Use ### When to Use
@ -161,28 +225,24 @@ ELSE:
- **Input**: "Fix null pointer exception in user service" - **Input**: "Fix null pointer exception in user service"
- **Discovery**: Level 0 (single atomic change) - **Discovery**: Level 0 (single atomic change)
- **Route**: tech-spec (Quick Spec Flow) - **Route**: tech-spec (Quick Spec Flow)
- **Duration**: 20 minutes
**Scenario 2: E-commerce Checkout** **Scenario 2: E-commerce Checkout**
- **Input**: "Build complete checkout flow with payment processing" - **Input**: "Build complete checkout flow with payment processing"
- **Discovery**: Level 3 (large feature set), feature-focused - **Discovery**: Level 3 (large feature set), feature-focused
- **Route**: prd (Standard depth) - **Route**: prd (Standard depth)
- **Duration**: 4 hours
**Scenario 3: Roguelike Card Game** **Scenario 3: Roguelike Card Game**
- **Input**: "Roguelike card battler with emotional narrative" - **Input**: "Roguelike card battler with emotional narrative"
- **Discovery**: Level 3 (large feature set), game project - **Discovery**: Level 3 (large feature set), game project
- **Route**: gdd - **Route**: gdd
- **Duration**: 6 hours
**Scenario 4: Story-Driven Adventure** **Scenario 4: Story-Driven Adventure**
- **Input**: "Narrative adventure game with branching story" - **Input**: "Narrative adventure game with branching story"
- **Discovery**: Level 3, story-central - **Discovery**: Level 3, story-central
- **Route**: narrative (then gdd for mechanics) - **Route**: narrative (then gdd for mechanics)
- **Duration**: 8 hours total
--- ---
@ -195,7 +255,6 @@ Lightweight technical specification for Levels 0-1 projects (single changes, sim
**Agent:** Architect **Agent:** Architect
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Project Levels:** 0-1 **Project Levels:** 0-1
**Typical Duration:** 30-90 minutes
### When to Use ### When to Use
@ -322,11 +381,6 @@ Strategic PRD with tactical epic breakdown for Levels 2-4 projects. Unified work
**Agent:** PM (with Architect and Analyst support) **Agent:** PM (with Architect and Analyst support)
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Project Levels:** 2-4 **Project Levels:** 2-4
**Typical Duration:**
- Level 2: 2-3 hours (Lightweight)
- Level 3: 3-5 hours (Standard)
- Level 4: 5-8 hours (Comprehensive)
### When to Use ### When to Use
@ -488,11 +542,6 @@ Complete game design document for Levels 2-4 game projects, adapted from industr
**Agent:** PM (Game Designer persona) **Agent:** PM (Game Designer persona)
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Project Levels:** 2-4 (games) **Project Levels:** 2-4 (games)
**Typical Duration:**
- Level 2: 3-4 hours (Small indie game)
- Level 3: 5-7 hours (Medium game)
- Level 4: 8-12 hours (Large/commercial game)
### When to Use ### When to Use
@ -666,11 +715,6 @@ Story-driven design workflow for games and experiences where narrative is centra
**Agent:** PM (Narrative Designer persona) + Creative Problem Solver (CIS) **Agent:** PM (Narrative Designer persona) + Creative Problem Solver (CIS)
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Project Levels:** 2-4 (story-driven projects) **Project Levels:** 2-4 (story-driven projects)
**Typical Duration:**
- Level 2: 2-4 hours (Linear narrative)
- Level 3: 4-6 hours (Branching narrative)
- Level 4: 6-10 hours (Complex branching with multiple arcs)
### When to Use ### When to Use
@ -825,11 +869,6 @@ UX specification workflow for projects where user experience is the primary diff
**Agent:** UX Designer **Agent:** UX Designer
**Phase:** 2 (Planning) **Phase:** 2 (Planning)
**Project Levels:** 2-4 (UX-heavy projects) **Project Levels:** 2-4 (UX-heavy projects)
**Typical Duration:**
- Level 2: 2-3 hours (Single feature UX)
- Level 3: 4-5 hours (Multi-screen experience)
- Level 4: 6-8 hours (Platform-wide UX system)
### When to Use ### When to Use

62
src/modules/bmm/docs/workflows-solutioning.md
View File

@ -1,19 +1,56 @@
# BMM Solutioning Workflows (Phase 3) # BMM Solutioning Workflows (Phase 3)
**Reading Time:** ~8 minutes
## Overview ## Overview
Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into **how** to build it (technical design). This phase is **required for Levels 3-4** and **optional for Level 2** projects. Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into **how** to build it (technical design). This phase is **required for Levels 3-4** and **optional for Level 2** projects.
**Key principle:** Prevent agent conflicts by making architectural decisions explicit and documented before implementation begins. **Key principle:** Prevent agent conflicts by making architectural decisions explicit and documented before implementation begins.
---
## Phase 3 Solutioning Flow
```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
FromPRD["<b>FROM Phase 2</b><br/>PRD/GDD/Narrative/UX complete"]
subgraph Solutioning["<b>PHASE 3: SOLUTIONING</b>"]
direction TB
Architecture["<b>Architect: architecture</b><br/>Technical design and decisions"]
GateCheck["<b>Architect: solutioning-gate-check</b><br/>Validation before implementation"]
end
subgraph Optional["<b>OPTIONAL PATHS</b>"]
direction LR
Level2Skip["<b>Level 2:</b><br/>Skip if straightforward"]
end
FromPRD --> Architecture
Architecture --> GateCheck
GateCheck -->|PASS| Phase4["<b>Phase 4: Implementation</b>"]
GateCheck -->|CONCERNS/FAIL| Architecture
FromPRD -.->|Level 2 only| Level2Skip
Level2Skip -.-> Phase4
style FromPRD fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000
style Solutioning fill:#90caf9,stroke:#0d47a1,stroke-width:3px,color:#000
style Optional fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000
style Architecture fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
style GateCheck fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
style Level2Skip fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000
```
---
## Quick Reference ## Quick Reference
| Workflow | Project Levels | Duration | Purpose | | Workflow | Project Levels | Purpose |
| -------------------------- | -------------- | --------- | ------------------------------------------- | | -------------------------- | -------------- | ------------------------------------------- |
| **architecture** | 2-4 | 2-6 hours | Technical architecture and design decisions | | **architecture** | 2-4 | Technical architecture and design decisions |
| **solutioning-gate-check** | 3-4 | 15-30 min | Validate planning/solutioning completeness | | **solutioning-gate-check** | 3-4 | Validate planning/solutioning completeness |
**When to Skip Solutioning:** **When to Skip Solutioning:**
@ -86,11 +123,6 @@ Collaborative architectural decision facilitation that produces a decision-focus
**Phase:** 3 (Solutioning) **Phase:** 3 (Solutioning)
**Project Levels:** 2-4 **Project Levels:** 2-4
**Required:** Level 3-4, Optional Level 2 **Required:** Level 3-4, Optional Level 2
**Typical Duration:**
- Level 2: 1-2 hours (Simple architecture)
- Level 3: 2-4 hours (Standard architecture)
- Level 4: 4-8 hours (Complex architecture with ADRs)
### When to Use ### When to Use
@ -341,7 +373,6 @@ Systematically validate that all planning and solutioning phases are complete an
**Phase:** 3 (Solutioning) **Phase:** 3 (Solutioning)
**Project Levels:** 3-4 **Project Levels:** 3-4
**Required:** Level 3-4 only **Required:** Level 3-4 only
**Typical Duration:** 15-30 minutes
### When to Use ### When to Use
@ -544,21 +575,20 @@ Optional:
1. **Critical**: Architecture missing security architecture section 1. **Critical**: Architecture missing security architecture section
- **Impact**: Epic 1 (Auth) and Epic 4 (Checkout) lack security guidance - **Impact**: Epic 1 (Auth) and Epic 4 (Checkout) lack security guidance
- **Recommendation**: Complete security architecture (2 hours) - **Recommendation**: Complete security architecture
2. **High**: Payment gateway not selected 2. **High**: Payment gateway not selected
- **Impact**: Epic 4 (Checkout) cannot proceed - **Impact**: Epic 4 (Checkout) cannot proceed
- **Recommendation**: Add ADR for payment gateway selection (1 hour) - **Recommendation**: Add ADR for payment gateway selection
3. **Medium**: Epic 2, Story 3 too large 3. **Medium**: Epic 2, Story 3 too large
- **Impact**: Risk of story scope creep - **Impact**: Risk of story scope creep
- **Recommendation**: Split into 2 stories (30 min) - **Recommendation**: Split into 2 stories
**Gate Decision:** CONCERNS ⚠️ **Gate Decision:** CONCERNS ⚠️
- **Rationale**: Critical and high gaps block Epic 1 and Epic 4 - **Rationale**: Critical and high gaps block Epic 1 and Epic 4
- **Action**: Resolve gaps #1 and #2 before starting implementation - **Action**: Resolve gaps #1 and #2 before starting implementation
- **Timeline**: Address in 3 hours, then re-run gate check
**Next Steps:** **Next Steps:**

2
src/modules/bmm/tasks/daily-standup.xml
View File

@ -64,7 +64,7 @@
<i>Primary: Sarah (PO), Bob (SM), James (Dev)</i> <i>Primary: Sarah (PO), Bob (SM), James (Dev)</i>
<i>Secondary: Murat (TEA)</i> <i>Secondary: Murat (TEA)</i>
</context> </context>
<context type="architecture-review"> <context type="validate-architecture">
<i>Primary: Winston (Architect), James (Dev), Murat (TEA)</i> <i>Primary: Winston (Architect), James (Dev), Murat (TEA)</i>
<i>Secondary: Sarah (PO)</i> <i>Secondary: Sarah (PO)</i>
</context> </context>

25
src/modules/bmm/workflows/techdoc/documentation-standards.md
View File

@ -5,10 +5,32 @@
--- ---
## CRITICAL RULE: CommonMark Strict Compliance ## CRITICAL RULES
### Rule 1: CommonMark Strict Compliance
ALL documentation MUST follow CommonMark specification exactly. No exceptions. ALL documentation MUST follow CommonMark specification exactly. No exceptions.
### Rule 2: NO TIME ESTIMATES
NEVER document time estimates, durations, or completion times for any workflow, task, or activity. This includes:
- Workflow execution time (e.g., "30-60 min", "2-8 hours")
- Task duration estimates
- Reading time estimates
- Implementation time ranges
- Any temporal measurements
Time varies dramatically based on:
- Project complexity
- Team experience
- Tooling and environment
- Context switching
- Unforeseen blockers
**Instead:** Focus on workflow steps, dependencies, and outputs. Let users determine their own timelines.
### CommonMark Essentials ### CommonMark Essentials
**Headers:** **Headers:**
@ -194,6 +216,7 @@ Apply in this hierarchy:
Before finalizing ANY documentation: Before finalizing ANY documentation:
- [ ] CommonMark compliant (no violations) - [ ] CommonMark compliant (no violations)
- [ ] NO time estimates anywhere (Critical Rule 2)
- [ ] Headers in proper hierarchy - [ ] Headers in proper hierarchy
- [ ] All code blocks have language tags - [ ] All code blocks have language tags
- [ ] Links work and have descriptive text - [ ] Links work and have descriptive text

4
src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md
View File

@ -355,8 +355,8 @@ See `tea-index.csv` for complete knowledge fragment mapping.
- Ask in team standup - Ask in team standup
- Tag @{tea_agent_username} in Slack/Discord - Tag @{tea_agent_username} in Slack/Discord
- Refer to `testarch/README.md` for workflow documentation - Refer to `./bmm/docs/tea-README.md` for workflow documentation
- Consult `testarch/knowledge/` for testing best practices - Consult `./bmm/testarch/knowledge` for testing best practices
--- ---

2
tools/schema/agent.js
View File

@ -176,6 +176,8 @@ function buildMenuItemSchema() {
tmpl: createNonEmptyString('agent.menu[].tmpl').optional(), tmpl: createNonEmptyString('agent.menu[].tmpl').optional(),
data: createNonEmptyString('agent.menu[].data').optional(), data: createNonEmptyString('agent.menu[].data').optional(),
'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(), 'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(),
checklist: createNonEmptyString('agent.menu[].checklist').optional(),
document: createNonEmptyString('agent.menu[].document').optional(),
}) })
.strict() .strict()
.superRefine((value, ctx) => { .superRefine((value, ctx) => {