diff --git a/bmad/_cfg/files-manifest.csv b/bmad/_cfg/files-manifest.csv
index 439c019c..f6adf593 100644
--- a/bmad/_cfg/files-manifest.csv
+++ b/bmad/_cfg/files-manifest.csv
@@ -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/redoc/instructions.md","21dd93b64455f8dd475b508ae9f1076d7e179e99fb6f197476071706b78e3592"
"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/workflows/convert-legacy/README.md","2c11bcf8d974e4f0e0e03f948df42097592751a3aeb9c443fa6cecf05819d49b"
"md","README","bmb","bmad/bmb/workflows/create-agent/README.md","f4da5c16fb4847252b09b82d70f027ae08e78b75bb101601f2ca3d2c2c884736"
diff --git a/bmad/bmm/docs/README.md b/bmad/bmm/docs/README.md
index 0b483833..6308475a 100644
--- a/bmad/bmm/docs/README.md
+++ b/bmad/bmm/docs/README.md
@@ -156,7 +156,7 @@ For detailed technical documentation on specific complex workflows:
Quality assurance guidance:
-- **[Test Architect Guide](../testarch/README.md)** - Comprehensive testing strategy
+- **[Test Architect Guide](./tea-README.md)** - Comprehensive testing strategy
- Test design workflows
- Quality gates
- Risk assessment
diff --git a/bmad/bmm/docs/brownfield-guide.md b/bmad/bmm/docs/brownfield-guide.md
index e185db2d..ad564c8d 100644
--- a/bmad/bmm/docs/brownfield-guide.md
+++ b/bmad/bmm/docs/brownfield-guide.md
@@ -751,7 +751,7 @@ flowchart TD
**Documentation:**
- [BMM Workflows Guide](../workflows/README.md)
-- [Test Architect Guide](../testarch/README.md)
+- [Test Architect Guide](./tea-README.md)
- [BMM Module README](../README.md)
---
diff --git a/bmad/bmm/docs/tea-README.md b/bmad/bmm/docs/tea-README.md
new file mode 100644
index 00000000..efda1375
--- /dev/null
+++ b/bmad/bmm/docs/tea-README.md
@@ -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:
+
+
+Cross-Phase Integration & Workflow Complexity
+
+### 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).
+
+
+
+## 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) |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Nova CRM” Greenfield Feature
+
+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.
+
+
+
+### 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 |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Atlas Payments” Brownfield Story
+
+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.
+
+
+
+### 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 |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Helios Ledger” Enterprise Release
+
+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.
+
+
+
+## Command Catalog
+
+
+Optional Playwright MCP Enhancements
+
+**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.
+
+
+
+
+
+| 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:
+
+
+Unique Architecture Pattern & Rationale
+
+### 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.
+
+
diff --git a/bmad/bmm/docs/troubleshooting.md b/bmad/bmm/docs/troubleshooting.md
index 93592855..b18acffe 100644
--- a/bmad/bmm/docs/troubleshooting.md
+++ b/bmad/bmm/docs/troubleshooting.md
@@ -545,7 +545,7 @@ To change locations, edit config.yaml then re-run workflows.
- Read docs/architecture.md (from document-project)
- Understand current system design
3. **For Level 3-4**:
- - Run architecture-review workflow before planning
+ - Run validate-architecture workflow before planning
- Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture:
- How new components fit existing structure
diff --git a/bmad/bmm/tasks/daily-standup.xml b/bmad/bmm/tasks/daily-standup.xml
index 4fa9fa34..d41c362c 100644
--- a/bmad/bmm/tasks/daily-standup.xml
+++ b/bmad/bmm/tasks/daily-standup.xml
@@ -64,7 +64,7 @@
Primary: Sarah (PO), Bob (SM), James (Dev)
Secondary: Murat (TEA)
-
+
Primary: Winston (Architect), James (Dev), Murat (TEA)
Secondary: Sarah (PO)
diff --git a/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md b/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md
index 027eb18e..a64c4969 100644
--- a/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md
+++ b/bmad/bmm/workflows/testarch/atdd/atdd-checklist-template.md
@@ -355,8 +355,8 @@ See `tea-index.csv` for complete knowledge fragment mapping.
- Ask in team standup
- Tag @{tea_agent_username} in Slack/Discord
-- Refer to `testarch/README.md` for workflow documentation
-- Consult `testarch/knowledge/` for testing best practices
+- Refer to `./bmm/docs/tea-README.md` for workflow documentation
+- Consult `./bmm/testarch/knowledge` for testing best practices
---
diff --git a/package-lock.json b/package-lock.json
index adf6696e..4de233c1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bmad-method",
- "version": "6.0.0-alpha.3",
+ "version": "6.0.0-alpha.5",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bmad-method",
- "version": "6.0.0-alpha.3",
+ "version": "6.0.0-alpha.5",
"license": "MIT",
"dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1",
diff --git a/src/modules/bmm/docs/README.md b/src/modules/bmm/docs/README.md
index 0b483833..a4c99264 100644
--- a/src/modules/bmm/docs/README.md
+++ b/src/modules/bmm/docs/README.md
@@ -36,7 +36,7 @@ Understanding how BMM adapts to your needs:
---
-## 🤖 Agents & Collaboration
+## 🤖 Agents and Collaboration
Complete guide to BMM's AI agent team:
@@ -127,7 +127,7 @@ Comprehensive documentation for all BMM workflows organized by phase:
- Complete story lifecycle
- 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
- TEA agent and test healing
- BMad-integrated vs standalone modes
@@ -152,15 +152,16 @@ For detailed technical documentation on specific complex workflows:
---
-## 🧪 Testing & Quality
+## 🧪 Testing and Quality
Quality assurance guidance:
-- **[Test Architect Guide](../testarch/README.md)** - Comprehensive testing strategy
- - Test design workflows
- - Quality gates
- - Risk assessment
- - NFR validation
+
+
+- Test design workflows
+- Quality gates
+- Risk assessment
+- NFR validation
---
@@ -178,7 +179,7 @@ Understanding BMM components:
## 🌐 External Resources
-### Community & Support
+### Community and Support
- **[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
diff --git a/src/modules/bmm/docs/agents-guide.md b/src/modules/bmm/docs/agents-guide.md
index 86996871..331a5008 100644
--- a/src/modules/bmm/docs/agents-guide.md
+++ b/src/modules/bmm/docs/agents-guide.md
@@ -996,7 +996,7 @@ Quick reference for agent selection:
- [Phase 2: Planning Workflows](./workflows-planning.md)
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
- [Phase 4: Implementation Workflows](./workflows-implementation.md)
-- [Testing & QA Workflows](./workflows-testing.md)
+
**Advanced References:**
diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md
index e185db2d..4db898de 100644
--- a/src/modules/bmm/docs/brownfield-guide.md
+++ b/src/modules/bmm/docs/brownfield-guide.md
@@ -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
-See [Workflows Guide](../workflows/README.md) for details.
+See the [Workflows section in BMM README](../README.md) for details.
### Phase 2: Planning (Required)
@@ -736,11 +736,11 @@ flowchart TD
- **[Glossary](./glossary.md)** - Key terminology
- **[FAQ](./faq.md)** - Common questions
- **[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:**
@@ -750,9 +750,8 @@ flowchart TD
**Documentation:**
-- [BMM Workflows Guide](../workflows/README.md)
-- [Test Architect Guide](../testarch/README.md)
-- [BMM Module README](../README.md)
+- [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
+- [BMM Module README](../README.md) - Complete module and workflow reference
---
diff --git a/src/modules/bmm/docs/enterprise-agentic-development.md b/src/modules/bmm/docs/enterprise-agentic-development.md
index 125bcd98..d82a8e0d 100644
--- a/src/modules/bmm/docs/enterprise-agentic-development.md
+++ b/src/modules/bmm/docs/enterprise-agentic-development.md
@@ -9,7 +9,7 @@
## Table of Contents
- [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)
- [Team Collaboration Patterns](#team-collaboration-patterns)
- [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
@@ -672,7 +672,7 @@ PMs write BMad PRDs → Stories auto-fed to cloud AI agents → Parallel impleme
- [FAQ](./faq.md) - Common questions
- [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained
- [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
---
diff --git a/src/modules/bmm/docs/faq.md b/src/modules/bmm/docs/faq.md
index ee8bd5bd..45ee66d6 100644
--- a/src/modules/bmm/docs/faq.md
+++ b/src/modules/bmm/docs/faq.md
@@ -8,11 +8,11 @@ Quick answers to common questions about the BMad Method Module.
- [Getting Started](#getting-started)
- [Choosing the Right Level](#choosing-the-right-level)
-- [Workflows & Phases](#workflows--phases)
+- [Workflows and Phases](#workflows-and-phases)
- [Planning Documents](#planning-documents)
- [Implementation](#implementation)
- [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
- 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?
@@ -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?
@@ -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?
@@ -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.
-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?
diff --git a/src/modules/bmm/docs/glossary.md b/src/modules/bmm/docs/glossary.md
index 59652d1a..1c12ee3d 100644
--- a/src/modules/bmm/docs/glossary.md
+++ b/src/modules/bmm/docs/glossary.md
@@ -7,11 +7,11 @@ Comprehensive terminology reference for the BMad Method Module.
## Navigation
- [Core Concepts](#core-concepts)
-- [Scale & Complexity](#scale--complexity)
+- [Scale and Complexity](#scale-and-complexity)
- [Planning Documents](#planning-documents)
-- [Workflow & Phases](#workflow--phases)
-- [Agents & Roles](#agents--roles)
-- [Status & Tracking](#status--tracking)
+- [Workflow and Phases](#workflow-and-phases)
+- [Agents and Roles](#agents-and-roles)
+- [Status and Tracking](#status-and-tracking)
- [Project Types](#project-types)
- [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
@@ -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)
@@ -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)
@@ -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
diff --git a/src/modules/bmm/docs/quick-spec-flow.md b/src/modules/bmm/docs/quick-spec-flow.md
index f69832a6..05ac4629 100644
--- a/src/modules/bmm/docs/quick-spec-flow.md
+++ b/src/modules/bmm/docs/quick-spec-flow.md
@@ -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:
@@ -543,7 +543,7 @@ Quick Spec Flow is **fully standalone**:
---
-## Tips & Best Practices
+## Tips and Best Practices
### 1. **Be Specific in Discovery**
@@ -643,7 +643,7 @@ Quick Spec Flow is your **fast path from idea to implementation** for:
## Next Steps
- **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
- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
diff --git a/src/modules/bmm/docs/quick-start.md b/src/modules/bmm/docs/quick-start.md
index 8e943402..67aa559e 100644
--- a/src/modules/bmm/docs/quick-start.md
+++ b/src/modules/bmm/docs/quick-start.md
@@ -37,9 +37,9 @@ The interactive installer will guide you through setup and create a `bmad/` fold
### 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:
- - [Claude Code](../docs/ide-info/claude-code.md)
- - [VS Code/Cursor/Windsurf](../docs/ide-info/) - Check your IDE folder
+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](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/ide-info/claude-code.md)
+ - [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
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
@@ -107,7 +107,7 @@ The next TRULY REQUIRED step is:
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
3. **Tell the agent** to run it using any of these formats:
- 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
- **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)
---
diff --git a/src/modules/bmm/docs/scale-adaptive-system.md b/src/modules/bmm/docs/scale-adaptive-system.md
index 84f91edf..63cc2bf0 100644
--- a/src/modules/bmm/docs/scale-adaptive-system.md
+++ b/src/modules/bmm/docs/scale-adaptive-system.md
@@ -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
- **[Glossary](./glossary.md)** - Complete terminology
- **[FAQ](./faq.md)** - Common questions
-- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
+- **[Workflows Guide](./README.md#-workflow-guides)** - Complete workflow reference
---
diff --git a/src/modules/bmm/docs/test-architecture.md b/src/modules/bmm/docs/test-architecture.md
new file mode 100644
index 00000000..1e9dcb59
--- /dev/null
+++ b/src/modules/bmm/docs/test-architecture.md
@@ -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["Phase 2: PLANNING"]
+ PM["PM: *prd"]
+ Framework["TEA: *framework"]
+ CI["TEA: *ci"]
+ TestDesign["TEA: *test-design"]
+ PM --> Framework
+ Framework --> CI
+ CI --> TestDesign
+ SetupNote["Setup once per project"]
+ TestDesign -.-> SetupNote
+ end
+
+ subgraph Phase4["Phase 4: IMPLEMENTATION - Per Story Cycle"]
+ CreateStory["SM: *create-story"]
+ ATDD["TEA: *atdd (optional, before dev)"]
+ DevImpl["DEV: implements story"]
+ Automate["TEA: *automate"]
+ TestReview1["TEA: *test-review (optional)"]
+ Trace1["TEA: *trace (refresh coverage)"]
+
+ CreateStory --> ATDD
+ ATDD --> DevImpl
+ DevImpl --> Automate
+ Automate --> TestReview1
+ TestReview1 --> Trace1
+ Trace1 -.->|next story| CreateStory
+ end
+
+ subgraph Gate["EPIC/RELEASE GATE"]
+ NFR["TEA: *nfr-assess (if not done earlier)"]
+ TestReview2["TEA: *test-review (final audit, optional)"]
+ TraceGate["TEA: *trace - Phase 2: Gate"]
+ GateDecision{"Gate Decision"}
+
+ NFR --> TestReview2
+ TestReview2 --> TraceGate
+ TraceGate --> GateDecision
+ GateDecision -->|PASS| Pass["PASS ✅"]
+ GateDecision -->|CONCERNS| Concerns["CONCERNS ⚠️"]
+ GateDecision -->|FAIL| Fail["FAIL ❌"]
+ GateDecision -->|WAIVED| Waived["WAIVED ⏭️"]
+ 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:
+
+
+Cross-Phase Integration & Workflow Complexity
+
+### 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).
+
+
+
+## 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) |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Nova CRM” Greenfield Feature
+
+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.
+
+
+
+### 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 |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Atlas Payments” Brownfield Story
+
+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.
+
+
+
+### 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 |
+
+
+Execution Notes
+
+- 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.
+
+
+
+
+Worked Example – “Helios Ledger” Enterprise Release
+
+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.
+
+
+
+## Command Catalog
+
+
+Optional Playwright MCP Enhancements
+
+**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.
+
+
+
+
+
+| 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:
+
+
+Unique Architecture Pattern & Rationale
+
+### 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.
+
+
diff --git a/src/modules/bmm/docs/troubleshooting.md b/src/modules/bmm/docs/troubleshooting.md
index 93592855..f411d98b 100644
--- a/src/modules/bmm/docs/troubleshooting.md
+++ b/src/modules/bmm/docs/troubleshooting.md
@@ -30,18 +30,18 @@ flowchart TD
## Table of Contents
-- [Setup & Installation Issues](#setup--installation-issues)
+- [Setup and Installation Issues](#setup-and-installation-issues)
- [Level Detection Problems](#level-detection-problems)
- [Workflow Issues](#workflow-issues)
-- [Context & Documentation Issues](#context--documentation-issues)
+- [Context and Documentation Issues](#context-and-documentation-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)
- [Integration Issues (Brownfield)](#integration-issues-brownfield)
---
-## Setup & Installation Issues
+## Setup and Installation Issues
### 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)
@@ -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
@@ -545,7 +545,7 @@ To change locations, edit config.yaml then re-run workflows.
- Read docs/architecture.md (from document-project)
- Understand current system design
3. **For Level 3-4**:
- - Run architecture-review workflow before planning
+ - Run validate-architecture workflow before planning
- Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture:
- How new components fit existing structure
diff --git a/src/modules/bmm/docs/workflows-analysis.md b/src/modules/bmm/docs/workflows-analysis.md
index 42eaaf36..b23d01af 100644
--- a/src/modules/bmm/docs/workflows-analysis.md
+++ b/src/modules/bmm/docs/workflows-analysis.md
@@ -1,7 +1,5 @@
# BMM Analysis Workflows (Phase 1)
-**Reading Time:** ~12 minutes
-
## 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.
@@ -17,17 +15,61 @@ Phase 1 (Analysis) workflows are **optional** exploration and discovery tools th
- Continuing an existing project with clear requirements
- 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["CREATIVE EXPLORATION"]
+ direction TB
+ BrainstormProject["Analyst: brainstorm-project
Multi-track solution exploration"]
+ BrainstormGame["Analyst: brainstorm-game
Game concept generation"]
+ end
+
+ subgraph Strategic["STRATEGIC PLANNING"]
+ direction TB
+ ProductBrief["Analyst: product-brief
Product vision and strategy"]
+ GameBrief["Game Designer: game-brief
Game vision capture"]
+ end
+
+ subgraph Research["RESEARCH AND INVESTIGATION"]
+ direction TB
+ ResearchWF["Analyst: research
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
-| Workflow | Agent | Duration | Required | Purpose |
-| ------------------ | ------- | --------- | ----------- | ----------------------------------------------------------- |
-| brainstorm-project | Analyst | 30-60 min | No | Explore solution approaches and architectures |
-| brainstorm-game | Analyst | 45-90 min | No | Generate game concepts using creative techniques |
-| product-brief | PM | 60-90 min | Recommended | Define product vision and strategy |
-| game-brief | PM | 60-90 min | Recommended | Capture game vision before GDD |
-| research | Analyst | Varies | No | Multi-type research system (market, technical, competitive) |
+| Workflow | Agent | Required | Purpose |
+| ------------------ | ------------- | ----------- | ----------------------------------------------------------- |
+| brainstorm-project | Analyst | No | Explore solution approaches and architectures |
+| brainstorm-game | Analyst | No | Generate game concepts using creative techniques |
+| product-brief | Analyst | Recommended | Define product vision and strategy |
+| game-brief | Game Designer | Recommended | Capture game vision before GDD |
+| 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
**Phase:** 1 (Analysis)
**Required:** No
-**Typical Duration:** 30-60 minutes
### When to Use
@@ -125,7 +166,6 @@ Generate and refine game concepts through systematic creative exploration using
**Agent:** Analyst
**Phase:** 1 (Analysis)
**Required:** No
-**Typical Duration:** 45-90 minutes
### 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.
-**Agent:** PM
+**Agent:** Analyst
**Phase:** 1 (Analysis)
**Required:** Recommended (skip only if PRD already exists)
-**Typical Duration:** 60-90 minutes (Interactive), 20-30 minutes (YOLO)
### When to Use
@@ -222,13 +261,13 @@ Interactive product brief creation that guides users through defining their prod
- Step-by-step collaborative development
- Probing questions to refine thinking
- Deep exploration of problem/solution fit
-- 60-90 minutes with high-quality output
+- High-quality output with thorough exploration
**YOLO Mode**:
- AI generates complete draft from initial context
- 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
### 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.
-**Agent:** PM
+**Agent:** Game Designer
**Phase:** 1 (Analysis)
**Required:** Recommended for game projects
-**Typical Duration:** 60-90 minutes
### When to Use
@@ -338,15 +376,14 @@ Lightweight, interactive brainstorming and planning session that captures game v
### Comparison: Game Brief vs GDD
-| Aspect | Game Brief | GDD |
-| --------------- | --------------------------- | ------------------------- |
-| Purpose | Validate concept | Design for implementation |
-| Detail Level | High-level vision | Detailed specifications |
-| Time Investment | 1-2 hours | 4-10 hours |
-| Audience | Self, team, stakeholders | Development team |
-| Scope | Concept validation | Implementation roadmap |
-| Format | Conversational, exploratory | Structured, comprehensive |
-| Output | 3-5 pages | 10-30+ pages |
+| Aspect | Game Brief | GDD |
+| ------------ | --------------------------- | ------------------------- |
+| Purpose | Validate concept | Design for implementation |
+| Detail Level | High-level vision | Detailed specifications |
+| Audience | Self, team, stakeholders | Development team |
+| Scope | Concept validation | Implementation roadmap |
+| Format | Conversational, exploratory | Structured, comprehensive |
+| Output | Concise vision document | Comprehensive design doc |
### Comparison: Game Brief vs Product Brief
@@ -441,7 +478,6 @@ Comprehensive, adaptive multi-type research system that consolidates various res
**Agent:** Analyst
**Phase:** 1 (Analysis)
**Required:** No
-**Typical Duration:** Varies by type (Quick: 30-60 min, Standard: 2-4 hours, Comprehensive: 4-8 hours)
### Research Types
diff --git a/src/modules/bmm/docs/workflows-implementation.md b/src/modules/bmm/docs/workflows-implementation.md
index 9545eeb6..f4df3cd1 100644
--- a/src/modules/bmm/docs/workflows-implementation.md
+++ b/src/modules/bmm/docs/workflows-implementation.md
@@ -1,1758 +1,284 @@
# BMM Implementation Workflows (Phase 4)
-**Reading Time:** ~20 minutes
+**Reading Time:** ~8 minutes
## Overview
-Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle. This phase uses a **story-centric workflow** where each story moves through a defined lifecycle from creation to completion.
+Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle using a **story-centric workflow** where each story moves through a defined lifecycle from creation to completion.
**Key principle:** One story at a time, move it through the entire lifecycle before starting the next.
+---
+
+## Phase 4 Workflow Lifecycle
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
+graph TB
+ subgraph Setup["SPRINT SETUP - Run Once"]
+ direction TB
+ SprintPlanning["SM: sprint-planning
Initialize sprint status file"]
+ end
+
+ subgraph EpicCycle["EPIC CYCLE - Repeat Per Epic"]
+ direction TB
+ EpicContext["SM: epic-tech-context
Generate epic technical guidance"]
+ ValidateEpic["SM: validate-epic-tech-context
(Optional validation)"]
+
+ EpicContext -.->|Optional| ValidateEpic
+ ValidateEpic -.-> StoryLoopStart
+ EpicContext --> StoryLoopStart[Start Story Loop]
+ end
+
+ subgraph StoryLoop["STORY LIFECYCLE - Repeat Per Story"]
+ direction TB
+
+ CreateStory["SM: create-story
Create next story from queue"]
+ ValidateStory["SM: validate-create-story
(Optional validation)"]
+ StoryContext["SM: story-context
Assemble dynamic context"]
+ StoryReady["SM: story-ready-for-dev
Mark ready without context"]
+ ValidateContext["SM: validate-story-context
(Optional validation)"]
+ DevStory["DEV: develop-story
Implement with tests"]
+ CodeReview["DEV: code-review
Senior dev review"]
+ StoryDone["DEV: story-done
Mark complete, advance queue"]
+
+ CreateStory -.->|Optional| ValidateStory
+ ValidateStory -.-> StoryContext
+ CreateStory --> StoryContext
+ CreateStory -.->|Alternative| StoryReady
+ StoryContext -.->|Optional| ValidateContext
+ ValidateContext -.-> DevStory
+ StoryContext --> DevStory
+ StoryReady -.-> DevStory
+ DevStory --> CodeReview
+ CodeReview -.->|Needs fixes| DevStory
+ CodeReview --> StoryDone
+ StoryDone -.->|Next story| CreateStory
+ end
+
+ subgraph EpicClose["EPIC COMPLETION"]
+ direction TB
+ Retrospective["SM: epic-retrospective
Post-epic lessons learned"]
+ end
+
+ subgraph Support["SUPPORTING WORKFLOWS"]
+ direction TB
+ CorrectCourse["SM: correct-course
Handle mid-sprint changes"]
+ WorkflowStatus["Any Agent: workflow-status
Check what's next"]
+ end
+
+ Setup --> EpicCycle
+ EpicCycle --> StoryLoop
+ StoryLoop --> EpicClose
+ EpicClose -.->|Next epic| EpicCycle
+ StoryLoop -.->|If issues arise| CorrectCourse
+ StoryLoop -.->|Anytime| WorkflowStatus
+ EpicCycle -.->|Anytime| WorkflowStatus
+
+ style Setup fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#000
+ style EpicCycle fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
+ style StoryLoop fill:#f3e5f5,stroke:#6a1b9a,stroke-width:3px,color:#000
+ style EpicClose fill:#ffcc80,stroke:#e65100,stroke-width:3px,color:#000
+ style Support fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#000
+
+ style SprintPlanning fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
+ style EpicContext fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
+ style ValidateEpic fill:#c5e1a5,stroke:#33691e,stroke-width:1px,color:#000
+ style CreateStory fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+ style ValidateStory fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
+ style StoryContext fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+ style StoryReady fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
+ style ValidateContext fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
+ style DevStory fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
+ style CodeReview fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
+ style StoryDone fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
+ style Retrospective fill:#ffb74d,stroke:#e65100,stroke-width:2px,color:#000
+```
+
+---
+
## Quick Reference
-| Workflow | Agent | Duration | Purpose |
-| --------------------- | ------- | -------------- | ------------------------------------ |
-| **sprint-planning** | SM | 30-60 min | Initialize sprint tracking file |
-| **epic-tech-context** | SM | 15-30 min/epic | Epic-specific technical guidance |
-| **create-story** | SM | 10-20 min | Create next story from epics |
-| **story-context** | PM | 10-15 min | Assemble dynamic story context |
-| **dev-story** | DEV | 2-8 hours | Implement story with tests |
-| **code-review** | DEV | 30-60 min | Senior dev review of completed story |
-| **correct-course** | SM | 30-90 min | Handle mid-sprint changes |
-| **retrospective** | SM | 60-90 min | Post-epic review and lessons |
-| **workflow-status** | All | 2-5 min | Check "what should I do now?" |
-| **document-project** | Analyst | 1-3 hours | Document brownfield projects |
+| Workflow | Agent | When | Purpose |
+| ------------------------------ | ----- | -------------------------------- | ------------------------------------------- |
+| **sprint-planning** | SM | Once at Phase 4 start | Initialize sprint tracking file |
+| **epic-tech-context** | SM | Per epic | Generate epic-specific technical guidance |
+| **validate-epic-tech-context** | SM | Optional after epic-tech-context | Validate tech spec against checklist |
+| **create-story** | SM | Per story | Create next story from epic backlog |
+| **validate-create-story** | SM | Optional after create-story | Independent validation of story draft |
+| **story-context** | SM | Optional per story | Assemble dynamic story context XML |
+| **validate-story-context** | SM | Optional after story-context | Validate story context against checklist |
+| **story-ready-for-dev** | SM | Optional per story | Mark story ready without generating context |
+| **develop-story** | DEV | Per story | Implement story with tests |
+| **code-review** | DEV | Per story | Senior dev quality review |
+| **story-done** | DEV | Per story | Mark complete and advance queue |
+| **epic-retrospective** | SM | After epic complete | Review lessons and extract insights |
+| **correct-course** | SM | When issues arise | Handle significant mid-sprint changes |
+| **workflow-status** | Any | Anytime | Check "what should I do now?" |
---
-## Understanding the Implementation Phase
+## Agent Roles
-### Story Lifecycle
+### SM (Scrum Master) - Primary Implementation Orchestrator
-Every story moves through this lifecycle:
+**Workflows:** sprint-planning, epic-tech-context, validate-epic-tech-context, create-story, validate-create-story, story-context, validate-story-context, story-ready-for-dev, epic-retrospective, correct-course
-```
-1. TODO (Not Started)
- ↓ [sprint-planning creates status file]
+**Responsibilities:**
-2. IN PROGRESS (Being Implemented)
- ↓ [create-story generates story file]
- ↓ [story-context assembles context]
- ↓ [dev-story implements with tests]
+- Initialize and maintain sprint tracking
+- Generate technical context (epic and story level)
+- Orchestrate story lifecycle with optional validations
+- Mark stories ready for development
+- Handle course corrections
+- Facilitate retrospectives
-3. READY FOR REVIEW (Implementation Complete)
- ↓ [code-review validates quality]
+### DEV (Developer) - Implementation and Quality
-4. DONE (Accepted)
- ↓ [story-done marks complete]
- ↓ [Repeat for next story]
-```
+**Workflows:** develop-story, code-review, story-done
-### Sprint-Based Development Model
+**Responsibilities:**
-**Sprint Structure:**
-
-- **Sprint 0 (Planning)**: Phases 1-3 complete
-- **Sprint 1**: Epic 1 stories (P0/P1)
-- **Sprint 2**: Epic 2 stories (P0/P1)
-- **Sprint 3**: Epic 3+ stories (P0/P1)
-- **Sprint N**: P2/P3 stories, polish
-
-**Typical Sprint Timeline:**
-
-- Week 1-2: Epic 1 implementation
-- Week 3-4: Epic 2 implementation
-- Week 5-6: Epic 3 implementation
-- Week 7+: Refinement, P2/P3, polish
-
-### Multi-Agent Workflow
-
-Phase 4 involves coordination between agents:
-
-| Agent | Primary Workflows | Role |
-| ----------- | ------------------------------------------------------------------------------- | -------------------------- |
-| **SM** | sprint-planning, epic-tech-context, create-story, correct-course, retrospective | Orchestration, tracking |
-| **PM** | story-context | Context assembly |
-| **DEV** | dev-story, code-review | Implementation, quality |
-| **Analyst** | document-project | Documentation (brownfield) |
+- Implement stories with tests
+- Perform senior developer code reviews
+- Mark stories complete and advance queue
+- Ensure quality and adherence to standards
---
-## sprint-planning
+## Story Lifecycle States
-### Purpose
+Stories move through these states in the sprint status file:
-Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle.
-
-**Agent:** SM (Scrum Master)
-**Phase:** 4 (Implementation)
-**Required:** Yes (first step of Phase 4)
-**Typical Duration:** 30-60 minutes
-
-### When to Use
-
-Run **once at the start of Phase 4** after solutioning-gate-check passes (or after PRD for Level 0-2).
-
-**Trigger Points:**
-
-- solutioning-gate-check PASS (Level 3-4)
-- PRD complete (Level 2)
-- tech-spec complete (Level 0-1)
-
-### Purpose of Sprint Planning
-
-**Creates:**
-
-- Sprint status tracking file (`sprint-status.yaml`)
-- Story queue (ordered by priority and dependencies)
-- Epic-level tracking
-- Sprint assignments
-
-**Enables:**
-
-- workflow-status to answer "what's next?"
-- Progress tracking throughout implementation
-- Dependency management
-- Velocity measurement
-
-### Process Overview
-
-**Phase 1: Context Loading (Step 1)**
-
-- Load epics.md
-- Load individual epic files
-- Load architecture.md (if exists)
-- Extract all stories
-
-**Phase 2: Story Extraction (Steps 2-3)**
-
-- Parse stories from epic files
-- Extract acceptance criteria
-- Identify priorities (P0/P1/P2/P3)
-- Extract dependencies
-
-**Phase 3: Sprint Assignment (Steps 4-5)**
-
-- Group stories by epic
-- Sequence by priority and dependencies
-- Assign to sprints (Sprint 1, 2, 3, etc.)
-- Calculate sprint capacity estimates
-
-**Phase 4: Status File Creation (Step 6)**
-
-- Generate sprint-status.yaml
-- Initialize all stories as TODO
-- Document sprint plan
-- Save to output folder
-
-### Inputs
-
-Required:
-
-- epics.md
-- Epic files (epic-1-_.md, epic-2-_.md, etc.)
-
-Optional:
-
-- architecture.md (for technical dependencies)
-- Team velocity data (for sprint sizing)
-
-### Outputs
-
-**Primary Output:** `sprint-status.yaml`
-
-**File Structure:**
-
-```yaml
-metadata:
- project_name: 'E-Commerce Platform'
- total_epics: 3
- total_stories: 24
- current_sprint: 1
- sprint_start_date: '2025-11-02'
-
-sprints:
- sprint_1:
- name: 'Epic 1: Authentication'
- start_date: '2025-11-02'
- end_date: '2025-11-15'
- capacity_points: 40
- stories:
- - id: '1.1'
- title: 'User can register with email'
- status: 'TODO'
- priority: 'P0'
- epic: 1
- estimated_hours: 8
- assigned_to: null
- dependencies: []
- - id: '1.2'
- title: 'User can login with email'
- status: 'TODO'
- priority: 'P0'
- epic: 1
- estimated_hours: 6
- assigned_to: null
- dependencies: ['1.1']
-
- sprint_2:
- name: 'Epic 2: Product Catalog'
- # ...
-
-story_queue:
- - '1.1' # No dependencies, P0
- - '1.2' # Depends on 1.1, P0
- - '1.3' # Depends on 1.2, P0
- # ...
-
-epics:
- - id: 1
- name: 'Authentication'
- total_stories: 8
- completed_stories: 0
- status: 'IN_PROGRESS'
- - id: 2
- name: 'Product Catalog'
- total_stories: 10
- completed_stories: 0
- status: 'TODO'
- - id: 3
- name: 'Shopping Cart'
- total_stories: 6
- completed_stories: 0
- status: 'TODO'
-```
-
-### Example Scenario
-
-**Input:** 3 epics with 24 total stories
-
-**Output:**
-
-- **Sprint 1**: Epic 1 (8 stories, 2 weeks)
-- **Sprint 2**: Epic 2 (10 stories, 2 weeks)
-- **Sprint 3**: Epic 3 (6 stories, 1 week)
-
-**Story Queue:**
-
-1. Story 1.1 (P0, no deps) → Start here
-2. Story 1.2 (P0, deps: 1.1)
-3. Story 1.3 (P0, deps: 1.2)
-4. Story 2.1 (P0, no deps) → Can parallelize with 1.x
- ...
-
-### Related Workflows
-
-- **solutioning-gate-check** (Phase 3) - Must PASS before sprint-planning
-- **workflow-status** - Uses sprint-status.yaml to answer "what's next?"
-- **create-story** - Uses story_queue to determine next story
+1. **TODO** - Story identified but not started
+2. **IN PROGRESS** - Story being implemented (create-story → story-context → dev-story)
+3. **READY FOR REVIEW** - Implementation complete, awaiting code review
+4. **DONE** - Accepted and complete
---
-## epic-tech-context
+## Typical Sprint Flow
-### Purpose
+### Sprint 0 (Planning Phase)
-Generate epic-specific technical context document that provides implementation guidance, patterns, and technical decisions for a single epic. Bridges architecture and story implementation.
+- Complete Phases 1-3 (Analysis, Planning, Solutioning)
+- PRD/GDD + Architecture + Epics ready
-**Agent:** SM (Scrum Master)
-**Phase:** 4 (Implementation)
-**Required:** Optional (recommended for Level 3-4)
-**Typical Duration:** 15-30 minutes per epic
+### Sprint 1+ (Implementation Phase)
-### When to Use
+**Start of Phase 4:**
-Run **once per epic** before starting epic stories.
+1. SM runs `sprint-planning` (once)
-**Trigger Points:**
+**Per Epic:**
-- Before implementing first story of an epic
-- When starting a new epic in a sprint
-- When architecture guidance is needed
+1. SM runs `epic-tech-context`
+2. SM optionally runs `validate-epic-tech-context`
-**Skip if:**
+**Per Story (repeat until epic complete):**
-- Level 0-1 (no epics)
-- Level 2 (simple epics, architecture is straightforward)
+1. SM runs `create-story`
+2. SM optionally runs `validate-create-story`
+3. SM runs `story-context` OR `story-ready-for-dev` (choose one)
+4. SM optionally runs `validate-story-context` (if story-context was used)
+5. DEV runs `develop-story`
+6. DEV runs `code-review`
+7. If code review passes: DEV runs `story-done`
+8. If code review finds issues: DEV fixes in `develop-story`, then back to code-review
-### Purpose of Epic Tech Context
+**After Epic Complete:**
-**Provides:**
+- SM runs `epic-retrospective`
+- Move to next epic (start with `epic-tech-context` again)
-- Epic-specific technical guidance
-- Code patterns and examples
-- Integration points
-- Testing strategy for epic
-- Epic-level architectural decisions
+**As Needed:**
-**Prevents:**
-
-- Re-reading entire architecture.md for each story
-- Inconsistent implementations within epic
-- Missing epic-level integration patterns
-
-### Process Overview
-
-**Phase 1: Context Loading (Step 1)**
-
-- Load architecture.md
-- Load epic file (epic-X-\*.md)
-- Load sprint-status.yaml
-- Identify epic stories
-
-**Phase 2: Technical Extraction (Steps 2-4)**
-
-- Extract relevant architecture sections for epic
-- Identify epic-specific ADRs
-- Determine code patterns
-- Identify integration points
-
-**Phase 3: Implementation Guidance (Steps 5-7)**
-
-- Define directory structure for epic
-- Specify testing approach
-- Provide code examples
-- Document epic-level constants/config
-
-**Phase 4: Documentation (Step 8)**
-
-- Generate epic-tech-context.md
-- Save to output folder
-- Update sprint-status.yaml with context path
-
-### Inputs
-
-Required:
-
-- architecture.md
-- epic-X-\*.md (specific epic file)
-- sprint-status.yaml
-
-### Outputs
-
-**Primary Output:** `epic-{N}-tech-context.md`
-
-**Document Structure:**
-
-1. Epic Overview
-2. Relevant Architecture Decisions
- - ADRs applicable to this epic
- - Technology selections
-3. Directory Structure
- - Files to create/modify
- - Module organization
-4. Code Patterns
- - Epic-specific patterns
- - Code examples
-5. Integration Points
- - APIs to create/consume
- - Database interactions
- - Third-party services
-6. Testing Strategy
- - Test levels for epic (E2E, API, Unit)
- - Test fixtures needed
- - Mock strategies
-7. Configuration
- - Environment variables
- - Feature flags
- - Constants
-
-### Example: Epic 1 Tech Context (Authentication)
-
-```markdown
-# Epic 1 Tech Context: Authentication
-
-## Architecture Decisions
-
-**ADR-001: Use NextAuth.js**
-
-- All stories in this epic use NextAuth.js
-- Database adapter: PostgreSQL (via Prisma)
-- Session strategy: Database sessions (not JWT)
-
-**ADR-003: Password Security**
-
-- Use bcrypt with 12 rounds
-- Minimum password length: 8 characters
-- Require: uppercase, lowercase, number
-
-## Directory Structure
-```
-
-/pages/api/auth/
-[...nextauth].ts # Story 1.1
-register.ts # Story 1.2
-verify-email.ts # Story 1.3
-
-/lib/auth/
-validation.ts # Story 1.2
-email-service.ts # Story 1.3
-
-/prisma/schema.prisma
-User model # Story 1.1
-Session model # Story 1.1
-
-````
-
-## Code Patterns
-
-**User Registration (Story 1.2):**
-```typescript
-// /lib/auth/validation.ts
-export const validatePassword = (password: string) => {
- const minLength = 8;
- const hasUppercase = /[A-Z]/.test(password);
- const hasLowercase = /[a-z]/.test(password);
- const hasNumber = /\d/.test(password);
-
- if (password.length < minLength) {
- throw new Error('Password too short');
- }
- // ...
-};
-````
-
-## Integration Points
-
-**Database:**
-
-- Create User table with Prisma migration (Story 1.1)
-- Create Session table with Prisma migration (Story 1.1)
-
-**Third-Party Services:**
-
-- SendGrid for email verification (Story 1.3)
- - API Key: SENDGRID_API_KEY env variable
- - From email: no-reply@example.com
-
-## Testing Strategy
-
-**E2E Tests:**
-
-- Story 1.1: Full registration flow
-- Story 1.2: Login flow
-- Story 1.3: Email verification flow
-
-**API Tests:**
-
-- All /api/auth/\* endpoints
-- Error cases: duplicate email, invalid password
-
-**Unit Tests:**
-
-- validation.ts functions
-- email-service.ts functions
-
-**Test Fixtures:**
-
-- Create `tests/fixtures/auth.fixture.ts`
-- Provide: createTestUser(), loginTestUser(), cleanupTestUser()
-
-## Configuration
-
-**Environment Variables:**
-
-```
-DATABASE_URL=postgresql://...
-NEXTAUTH_URL=http://localhost:3000
-NEXTAUTH_SECRET=
-SENDGRID_API_KEY=SG.xxx
-```
-
-**Constants:**
-
-```typescript
-// /lib/auth/constants.ts
-export const PASSWORD_MIN_LENGTH = 8;
-export const BCRYPT_ROUNDS = 12;
-export const EMAIL_VERIFICATION_EXPIRY_HOURS = 24;
-```
-
-````
-
-### Related Workflows
-- **architecture** (Phase 3) - Source of technical guidance
-- **story-context** - Uses epic-tech-context as input
-- **dev-story** - References epic-tech-context during implementation
+- Run `workflow-status` anytime to check progress
+- Run `correct-course` if significant changes needed
---
-## create-story
+## Key Principles
-### Purpose
-Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder.
+### One Story at a Time
-**Agent:** SM (Scrum Master)
-**Phase:** 4 (Implementation)
-**Required:** Yes (for each story)
-**Typical Duration:** 10-20 minutes per story
+Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality.
-### When to Use
-Run **before implementing each story** to generate story file.
+### Epic-Level Technical Context
-**Trigger Points:**
-- Before starting work on a new story
-- When story_queue identifies next story
-- After completing previous story
+Generate detailed technical guidance per epic (not per story) using `epic-tech-context`. This provides just-in-time architecture without upfront over-planning.
-### Process Overview
+### Story Context (Optional)
-**Phase 1: Story Selection (Step 1)**
-- Load sprint-status.yaml
-- Read story_queue
-- Select next story (first in queue with dependencies met)
+Use `story-context` to assemble focused context XML for each story, pulling from PRD, architecture, epic context, and codebase docs. Alternatively, use `story-ready-for-dev` to mark a story ready without generating context XML.
-**Phase 2: Story Extraction (Steps 2-3)**
-- Load epic file for selected story
-- Extract story details
-- Extract acceptance criteria
-- Extract dependencies
+### Quality Gates
-**Phase 3: Context Gathering (Steps 4-5)**
-- Load PRD/GDD for product context
-- Load architecture for technical context
-- Load epic-tech-context (if exists)
+Every story goes through `code-review` before being marked done. No exceptions.
-**Phase 4: Story File Creation (Step 6)**
-- Generate story markdown using template
-- Include acceptance criteria
-- Include technical notes
-- Save to stories/ folder
+### Continuous Tracking
-**Phase 5: Status Update (Step 7)**
-- Update sprint-status.yaml
-- Move story from TODO → IN PROGRESS
-- Update workflow-status.md
-
-### Inputs
-Required:
-- sprint-status.yaml (story queue)
-- epic-X-*.md (for story details)
-- PRD.md or GDD.md
-
-Optional:
-- architecture.md
-- epic-tech-context.md
-
-### Outputs
-
-**Primary Output:** `story-{epic}.{num}-{title}.md`
-
-**Story File Structure:**
-```markdown
-# Story {Epic}.{Num}: {Title}
-
-**Epic:** {Epic Name}
-**Priority:** P0/P1/P2/P3
-**Status:** IN PROGRESS
-**Estimated Hours:** {Hours}
-**Dependencies:** {Story IDs or "None"}
-
-## User Story
-
-As a {user type},
-I want to {action},
-So that {benefit}.
-
-## Acceptance Criteria
-
-- [ ] AC-1: {Criterion}
-- [ ] AC-2: {Criterion}
-- [ ] AC-3: {Criterion}
-
-## Technical Notes
-
-{From architecture/epic-tech-context}
-
-## Implementation Checklist
-
-- [ ] Read story-context.xml for dynamic context
-- [ ] Implement feature code
-- [ ] Write tests (unit, integration, E2E as needed)
-- [ ] Update documentation
-- [ ] Run tests locally
-- [ ] Verify acceptance criteria
-- [ ] Mark story as READY FOR REVIEW
-
-## Definition of Done
-
-- [ ] All acceptance criteria met
-- [ ] Tests written and passing
-- [ ] Code reviewed
-- [ ] Documentation updated
-- [ ] No regressions in existing features
-````
-
-### Example: Story 1.2 - User Can Login
-
-```markdown
-# Story 1.2: User Can Login with Email
-
-**Epic:** Epic 1 - Authentication
-**Priority:** P0
-**Status:** IN PROGRESS
-**Estimated Hours:** 6
-**Dependencies:** Story 1.1 (User Registration)
-
-## User Story
-
-As a registered user,
-I want to login with my email and password,
-So that I can access my account.
-
-## Acceptance Criteria
-
-- [ ] AC-1: User can enter email and password on login page
-- [ ] AC-2: Valid credentials redirect to dashboard
-- [ ] AC-3: Invalid credentials show error message
-- [ ] AC-4: Error message does not reveal if email exists (security)
-- [ ] AC-5: Login creates session that persists across page refreshes
-
-## Technical Notes
-
-**From Architecture (ADR-001):**
-
-- Use NextAuth.js with database session strategy
-- Session stored in PostgreSQL via Prisma
-
-**From Epic Tech Context:**
-
-- Implement /pages/api/auth/[...nextauth].ts
-- Use bcrypt.compare() for password validation
-- Return generic error for security (don't reveal "email not found" vs "wrong password")
-
-## Implementation Checklist
-
-- [ ] Read story-context.xml
-- [ ] Create /pages/login.tsx
-- [ ] Configure NextAuth.js credentials provider
-- [ ] Implement password comparison logic
-- [ ] Write E2E test: Valid login → Dashboard
-- [ ] Write E2E test: Invalid login → Error
-- [ ] Write API test: POST /api/auth/callback/credentials
-- [ ] Verify AC-1 through AC-5
-- [ ] Mark READY FOR REVIEW
-
-## Definition of Done
-
-- [ ] Login page exists and is styled
-- [ ] Valid credentials authenticate successfully
-- [ ] Invalid credentials show error
-- [ ] Session persists across page loads
-- [ ] Tests pass (2 E2E, 3 API)
-- [ ] Code reviewed
-```
-
-### Related Workflows
-
-- **sprint-planning** - Creates story_queue
-- **story-context** - Run after create-story
-- **dev-story** - Implements the story
+The `sprint-status.yaml` file is the single source of truth for all implementation progress.
---
-## story-context
+## Common Patterns
-### Purpose
-
-Assemble dynamic story context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story.
-
-**Agent:** PM (Project Manager)
-**Phase:** 4 (Implementation)
-**Required:** Yes (before implementing story)
-**Typical Duration:** 10-15 minutes per story
-
-### When to Use
-
-Run **after create-story** and **before dev-story** for each story.
-
-**Trigger Points:**
-
-- Immediately after create-story generates story file
-- Before DEV agent starts implementation
-
-### Purpose of Story Context
-
-**Problem Without Context:**
-
-- DEV agent re-reads entire PRD, architecture, epic files (100+ pages)
-- Slow context loading
-- Irrelevant information clutters thinking
-
-**Solution With Context:**
-
-- PM assembles **only relevant** context for this story
-- DEV agent receives focused, story-specific information
-- Fast, targeted implementation
-
-### Process Overview
-
-**Phase 1: Story Loading (Step 1)**
-
-- Load story file (story-{epic}.{num}-{title}.md)
-- Extract story ID, epic, dependencies
-- Extract acceptance criteria
-
-**Phase 2: Documentation Context (Steps 2-4)**
-
-- Load relevant PRD/GDD sections
-- Load relevant architecture sections
-- Load epic-tech-context (if exists)
-- Load dependent story files
-
-**Phase 3: Code Context (Steps 5-6)**
-
-- Identify existing code files related to story
-- Load relevant library code (models, services, utils)
-- Load related test files
-
-**Phase 4: Context Assembly (Step 7)**
-
-- Generate story-context.xml
-- Organize context by type (docs, code, tests)
-- Include only relevant sections
-- Save to output folder
-
-### Inputs
-
-Required:
-
-- story-{epic}.{num}-{title}.md
-
-Optional (loaded as needed):
-
-- PRD.md or GDD.md
-- architecture.md
-- epic-tech-context.md
-- Existing codebase files
-
-### Outputs
-
-**Primary Output:** `story-{epic}.{num}-context.xml`
-
-**XML Structure:**
-
-```xml
-
-
-
- User can enter email and password on login page
- Valid credentials redirect to dashboard
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-```
-
-### Example: Story 1.2 Context Assembly
-
-**Story 1.2: User Can Login**
-
-**Context Assembled:**
-
-1. **Product Context** (from PRD):
- - Authentication requirements section (2 pages)
- - User personas: Primary user is buyer
-
-2. **Architecture Context** (from architecture.md):
- - ADR-001: Use NextAuth.js (full ADR)
- - Authentication Architecture section (1 page)
-
-3. **Epic Context** (from epic-1-tech-context.md):
- - Code patterns for login
- - Integration points (NextAuth.js config)
- - Testing strategy
-
-4. **Code Context** (existing files):
- - `/prisma/schema.prisma` - User and Session models
- - `/lib/auth/validation.ts` - Password validation (from Story 1.1)
- - `/pages/api/auth/[...nextauth].ts` - Auth config (created in Story 1.1)
-
-5. **Dependency Context** (Story 1.1):
- - Summary: User registration creates User in DB
- - Dependency: User table must exist
-
-**Result:** DEV agent receives 8-10 pages of **focused** context instead of 100+ pages of full documentation.
-
-### Related Workflows
-
-- **create-story** - Creates story file that story-context uses
-- **dev-story** - Consumes story-context.xml
-
----
-
-## dev-story
-
-### Purpose
-
-Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria.
-
-**Agent:** DEV (Developer)
-**Phase:** 4 (Implementation)
-**Required:** Yes (for each story)
-**Typical Duration:** 2-8 hours per story (varies by complexity)
-
-### When to Use
-
-Run **after story-context** to implement the story.
-
-**Trigger Points:**
-
-- After story-context.xml is generated
-- When story status is IN PROGRESS
-- For each story in story_queue
-
-### Process Overview
-
-**Phase 1: Context Loading (Step 1)**
-
-- Load story file
-- Load story-context.xml
-- Review acceptance criteria
-- Review technical notes
-
-**Phase 2: Implementation Planning (Steps 2-3)**
-
-- Break story into tasks
-- Identify files to create/modify
-- Plan test strategy
-- Estimate implementation approach
-
-**Phase 3: Implementation (Steps 4-6)**
-
-- Write code to satisfy acceptance criteria
-- Follow architecture decisions
-- Apply code patterns from epic-tech-context
-- Write tests (unit, integration, E2E as needed)
-
-**Phase 4: Validation (Steps 7-8)**
-
-- Run tests locally
-- Verify all acceptance criteria met
-- Check for regressions
-- Ensure code quality
-
-**Phase 5: Documentation (Step 9)**
-
-- Update story file (check off AC items)
-- Document any deviations
-- Mark story as READY FOR REVIEW
-- Update sprint-status.yaml
-
-### Inputs
-
-Required:
-
-- story-{epic}.{num}-{title}.md
-- story-{epic}.{num}-context.xml
-
-### Outputs
-
-- Implementation code (multiple files)
-- Test files
-- Updated story file (AC checked off)
-- Updated sprint-status.yaml (status: READY FOR REVIEW)
-
-### Example: Implementing Story 1.2 (Login)
-
-**Phase 1: Planning**
-Tasks identified:
-
-1. Create /pages/login.tsx (UI)
-2. Configure NextAuth credentials provider
-3. Implement password verification logic
-4. Write E2E test: Valid login
-5. Write E2E test: Invalid login
-6. Write API test: /api/auth/callback/credentials
-
-**Phase 2: Implementation**
-Files created/modified:
-
-- `/pages/login.tsx` (new)
-- `/pages/api/auth/[...nextauth].ts` (modified - add credentials provider)
-- `/lib/auth/password.ts` (new - password verification)
-- `/tests/e2e/auth-login.spec.ts` (new)
-- `/tests/api/auth-api.spec.ts` (modified - add login tests)
-
-**Phase 3: Testing**
-
-```bash
-npm run test:e2e
-npm run test:api
-npm run test:unit
-```
-
-All tests pass ✅
-
-**Phase 4: Verification**
-
-- [x] AC-1: Login page exists with email/password inputs
-- [x] AC-2: Valid credentials → Dashboard
-- [x] AC-3: Invalid credentials → Error message
-- [x] AC-4: Error message generic (security)
-- [x] AC-5: Session persists across page refreshes
-
-**Phase 5: Documentation**
-Update story file:
-
-```markdown
-## Acceptance Criteria
-
-- [x] AC-1: User can enter email and password on login page
-- [x] AC-2: Valid credentials redirect to dashboard
-- [x] AC-3: Invalid credentials show error message
-- [x] AC-4: Error message does not reveal if email exists (security)
-- [x] AC-5: Login creates session that persists across page refreshes
-
-## Implementation Summary
-
-Files Created:
-
-- /pages/login.tsx
-- /lib/auth/password.ts
-- /tests/e2e/auth-login.spec.ts
-
-Files Modified:
-
-- /pages/api/auth/[...nextauth].ts
-- /tests/api/auth-api.spec.ts
-
-Tests Added:
-
-- 2 E2E tests (valid/invalid login)
-- 3 API tests (credentials endpoint)
-
-**Status:** READY FOR REVIEW
-```
-
-### Related Workflows
-
-- **story-context** - Provides focused context
-- **code-review** - Next step after implementation
-- **correct-course** - If changes needed mid-story
-
----
-
-## code-review
-
-### Purpose
-
-Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic-tech-context, repo docs, MCP servers for latest best-practices, and web search as fallback.
-
-**Agent:** DEV (Senior Developer persona)
-**Phase:** 4 (Implementation)
-**Required:** Recommended (especially for P0/P1 stories)
-**Typical Duration:** 30-60 minutes per story
-
-### When to Use
-
-Run **after dev-story** when story status is READY FOR REVIEW.
-
-**Trigger Points:**
-
-- Story status: READY FOR REVIEW
-- Before marking story as DONE
-- For P0/P1 stories (required)
-- For P2/P3 stories (optional but recommended)
-
-### Process Overview
-
-**Phase 1: Context Loading (Step 1)**
-
-- Load story file
-- Load story-context.xml
-- Load implementation files
-- Load test files
-
-**Phase 2: Review Criteria (Steps 2-5)**
-
-- **Acceptance Criteria**: All AC met?
-- **Architecture Alignment**: Follows architecture decisions?
-- **Code Quality**: Readable, maintainable, follows conventions?
-- **Test Coverage**: Sufficient tests, tests passing?
-- **Best Practices**: Uses latest framework patterns?
-
-**Phase 3: Knowledge Loading (Steps 6-7)**
-
-- Load repository documentation (CONTRIBUTING.md, CODE_STYLE.md)
-- Use MCP servers for framework best practices (if available)
-- Web search for latest patterns (fallback)
-
-**Phase 4: Review Execution (Steps 8-10)**
-
-- Review each file changed
-- Identify issues (critical, high, medium, low)
-- Suggest improvements
-- Verify tests
-
-**Phase 5: Review Report (Step 11)**
-
-- Generate code-review.md
-- Append to story file
-- Update sprint-status.yaml
-
-### Review Criteria
-
-**Acceptance Criteria Validation:**
-
-- [ ] All AC items checked off in story file
-- [ ] AC validated through tests
-- [ ] AC validated manually (if needed)
-
-**Architecture Alignment:**
-
-- [ ] Follows ADRs
-- [ ] Uses specified technology choices
-- [ ] Follows directory structure conventions
-- [ ] Follows code patterns from epic-tech-context
-
-**Code Quality:**
-
-- [ ] Readable and maintainable
-- [ ] Follows repository conventions
-- [ ] No code smells (long functions, god classes, etc.)
-- [ ] Appropriate error handling
-- [ ] Security best practices followed
-
-**Test Coverage:**
-
-- [ ] Tests exist for all AC
-- [ ] Tests pass locally
-- [ ] Edge cases covered
-- [ ] Tests follow framework best practices
-- [ ] No flaky tests
-
-**Best Practices:**
-
-- [ ] Uses latest framework patterns
-- [ ] Avoids deprecated APIs
-- [ ] Performance considerations addressed
-- [ ] Accessibility requirements met (if applicable)
-
-### Inputs
-
-Required:
-
-- story-{epic}.{num}-{title}.md (with READY FOR REVIEW status)
-- story-{epic}.{num}-context.xml
-- Implementation files (code)
-- Test files
-
-Optional:
-
-- Repository documentation (CONTRIBUTING.md, CODE_STYLE.md)
-- MCP servers for best practices
-- Web search for latest patterns
-
-### Outputs
-
-**Primary Output:** Code review appended to story file
-
-**Review Structure:**
-
-````markdown
----
-
-## Code Review - {Date}
-
-**Reviewer:** DEV (Senior Developer)
-**Status:** APPROVED / REQUEST CHANGES / APPROVED WITH COMMENTS
-
-### Summary
-
-{Overall assessment}
-
-### Acceptance Criteria Validation
-
-- [x] AC-1: Validated ✅
-- [x] AC-2: Validated ✅
-- [x] AC-3: Validated ✅
-- [x] AC-4: Validated ✅
-- [x] AC-5: Validated ✅
-
-### Architecture Alignment
-
-✅ Follows ADR-001 (NextAuth.js)
-✅ Uses database session strategy
-✅ Follows epic-tech-context patterns
-
-### Code Quality Issues
-
-**Critical Issues (Must Fix):**
-None
-
-**High Priority (Should Fix Before Merge):**
-
-1. /lib/auth/password.ts:15 - Use constant for bcrypt rounds instead of magic number
-
- ```typescript
- // Current:
- const hash = await bcrypt.hash(password, 12);
-
- // Suggested:
- import { BCRYPT_ROUNDS } from './constants';
- const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
- ```
-````
-
-**Medium Priority (Address in Follow-up):**
-
-1. /pages/login.tsx:42 - Consider extracting form validation to custom hook
-2. Add JSDoc comments to public functions in /lib/auth/password.ts
-
-**Low Priority (Nice to Have):**
-
-1. Consider using react-hook-form for login form (reduces boilerplate)
-
-### Test Coverage
-
-✅ E2E tests cover happy and sad paths
-✅ API tests cover error cases
-⚠️ Consider adding unit test for password validation edge cases
-
-### Best Practices
-
-✅ Uses latest Next.js 14 patterns
-✅ Follows React best practices
-✅ Accessibility: Form has labels and error messages
-
-### Recommendation
-
-**APPROVED WITH COMMENTS** - Address high priority issue #1, then merge.
-
-Medium/low priority items can be addressed in future stories.
-
-````
-
-### Review Outcomes
-
-**APPROVED** ✅
-- All criteria met
-- No critical/high issues
-- Story can be marked DONE
-- **Action**: Run story-done workflow
-
-**APPROVED WITH COMMENTS** ✅⚠️
-- Minor issues noted
-- Suggestions for improvement
-- Story can be marked DONE
-- **Action**: Address comments in follow-up (optional)
-
-**REQUEST CHANGES** ❌
-- Critical or high-priority issues found
-- Changes required before merge
-- Story remains READY FOR REVIEW
-- **Action**: Fix issues, re-request review
-
-### Related Workflows
-- **dev-story** - Implementation that's being reviewed
-- **story-done** - Next step if approved
-- **correct-course** - If significant changes needed
-
----
-
-## correct-course
-
-### Purpose
-Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation.
-
-**Agent:** SM (Scrum Master)
-**Phase:** 4 (Implementation)
-**Required:** As needed
-**Typical Duration:** 30-90 minutes
-
-### When to Use
-Run when **significant changes** occur mid-sprint:
-
-**Trigger Scenarios:**
-- New requirements discovered during implementation
-- Architecture decision needs revision
-- Story dependencies change
-- External factors impact sprint (API changes, platform updates)
-- Critical bug discovered requiring immediate attention
-
-**Don't Use For:**
-- Minor clarifications → Clarify in story file
-- Small scope adjustments → Adjust AC in story
-- Typical development blockers → Resolve within team
-
-### Process Overview
-
-**Phase 1: Change Analysis (Steps 1-3)**
-- Identify change type (requirements, technical, external)
-- Assess impact (stories, epics, architecture)
-- Determine urgency (blocking, high, medium, low)
-
-**Phase 2: Impact Assessment (Steps 4-6)**
-- Stories affected
-- Epics affected
-- Architecture changes needed
-- Timeline impact
-
-**Phase 3: Solution Proposal (Steps 7-9)**
-- **Option A**: Adjust scope (remove stories, defer features)
-- **Option B**: Adjust architecture (revise decisions)
-- **Option C**: Adjust timeline (extend sprint)
-- **Option D**: Combination approach
-
-**Phase 4: Decision and Routing (Steps 10-12)**
-- Consult stakeholders (if needed)
-- Select solution
-- Route to appropriate workflow:
- - Requirements change → Update PRD → Re-run create-story
- - Architecture change → Update architecture → Re-run epic-tech-context
- - Story change → Update story file → Continue dev-story
-- Update sprint-status.yaml
-
-### Change Types
-
-**Requirements Change:**
-- New AC discovered
-- AC invalidated by new information
-- Feature scope expansion/reduction
-
-**Technical Change:**
-- Architecture decision no longer viable
-- Technology choice needs revision
-- Integration approach changed
-
-**External Change:**
-- Third-party API changed
-- Platform update breaks implementation
-- Regulatory requirement introduced
-
-### Inputs
-Required:
-- Description of change
-- Current story/epic affected
-- Current sprint-status.yaml
-
-### Outputs
-- Change impact analysis document
-- Updated documentation (PRD/architecture/stories)
-- Updated sprint-status.yaml
-- Routing recommendations
-
-### Example: API Change Mid-Sprint
-
-**Change:** SendGrid deprecated email API, requires migration to new API
-
-**Impact Analysis:**
-- **Stories Affected**: Story 1.3 (Email Verification) - IN PROGRESS
-- **Epics Affected**: Epic 1 (Authentication)
-- **Architecture Impact**: ADR-004 (Email Service) needs revision
-- **Timeline Impact**: +1 day (API migration work)
-
-**Solution Options:**
-
-**Option A:** Continue with deprecated API, plan migration for later
-- **Pros**: No sprint disruption
-- **Cons**: Technical debt, API sunset in 6 months
-
-**Option B:** Migrate to new API now
-- **Pros**: No technical debt, future-proof
-- **Cons**: +1 day to sprint
-
-**Option C:** Defer email verification to next sprint
-- **Pros**: No disruption to current sprint
-- **Cons**: Story 1.3 incomplete, Epic 1 not done
-
-**Decision:** Option B (Migrate now)
-
-**Actions:**
-1. Update architecture.md (ADR-004: Use SendGrid v4 API)
-2. Update epic-1-tech-context.md (new email patterns)
-3. Update Story 1.3 acceptance criteria (new API endpoints)
-4. Continue dev-story with new approach
-5. Extend sprint by 1 day
-
-### Related Workflows
-- **architecture** - May need updates
-- **create-story** - May need to create new stories
-- **sprint-planning** - May need to re-prioritize
-- **retrospective** - Document learnings
-
----
-
-## retrospective
-
-### Purpose
-Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic.
-
-**Agent:** SM (Scrum Master)
-**Phase:** 4 (Implementation)
-**Required:** Recommended (after each epic)
-**Typical Duration:** 60-90 minutes
-
-### When to Use
-Run **after completing an epic** (all stories DONE).
-
-**Trigger Points:**
-- Epic status: DONE
-- All epic stories completed
-- Before starting next epic
-- Before final release (after all epics)
-
-### Process Overview
-
-**Phase 1: Data Gathering (Steps 1-3)**
-- Load sprint-status.yaml
-- Load completed story files
-- Load code-review feedback
-- Gather metrics (velocity, story cycle time)
-
-**Phase 2: Review Execution (Steps 4-7)**
-- **What Went Well**: Successes and wins
-- **What Didn't Go Well**: Challenges and issues
-- **Lessons Learned**: Actionable insights
-- **Process Improvements**: Changes for next epic
-
-**Phase 3: Technical Insights (Steps 8-10)**
-- Architecture decisions review
-- Technology choices validation
-- Code quality assessment
-- Test coverage and quality
-
-**Phase 4: Planning Insights (Steps 11-13)**
-- Estimation accuracy
-- Requirements clarity
-- Dependency management
-- Scope changes
-
-**Phase 5: Action Items (Step 14)**
-- Process changes for next epic
-- Architecture updates needed
-- Documentation improvements
-- Training or knowledge gaps
-
-### Inputs
-Required:
-- sprint-status.yaml (epic completion data)
-- Completed story files
-- code-review feedback
-
-Optional:
-- Team velocity data
-- CI/CD metrics
-- Bug reports
-
-### Outputs
-
-**Primary Output:** `retrospective-epic-{N}-{date}.md`
-
-**Document Structure:**
-1. Epic Summary
- - Stories completed
- - Time taken
- - Velocity achieved
-2. What Went Well
-3. What Didn't Go Well
-4. Lessons Learned
-5. Technical Insights
-6. Planning Insights
-7. Action Items for Next Epic
-8. Process Improvements
-
-### Example: Epic 1 Retrospective
-
-```markdown
-# Retrospective: Epic 1 - Authentication
-
-**Date:** 2025-11-15
-**Duration:** 2 weeks (planned), 2.5 weeks (actual)
-**Stories Completed:** 8/8
-**Velocity:** 48 points (target: 60 points)
-
-## What Went Well
-
-✅ **Architecture decisions solid**
-- NextAuth.js choice worked well
-- Database sessions simpler than JWT
-
-✅ **Test coverage excellent**
-- All stories have E2E + API tests
-- No critical bugs in production
-
-✅ **Team collaboration strong**
-- Code reviews thorough
-- Knowledge sharing effective
-
-## What Didn't Go Well
-
-❌ **Estimation inaccurate**
-- Stories took 20% longer than estimated
-- Story 1.3 (Email Verification) took 2 days instead of 1
-
-❌ **Third-party integration surprise**
-- SendGrid API deprecation discovered mid-sprint
-- Required correct-course workflow
-
-❌ **Testing setup overhead**
-- Test fixtures took longer than expected to set up
-- Should have created fixtures earlier
-
-## Lessons Learned
-
-💡 **Buffer time for integrations**
-- Add 25% buffer to stories with third-party APIs
-- Research API stability before committing
-
-💡 **Test fixtures upfront**
-- Create test fixtures in first story of epic
-- Reuse across all stories
-
-💡 **Architecture review cadence**
-- Mid-epic architecture check-in would have caught issues earlier
-
-## Technical Insights
-
-**Architecture:**
-- ADR-001 (NextAuth.js) validated ✅
-- ADR-004 (SendGrid) needed revision (v3 → v4)
-
-**Code Quality:**
-- Average code-review score: 8.5/10
-- No critical issues
-- 3 high-priority issues (all addressed)
-
-**Test Coverage:**
-- E2E: 95% of critical paths
-- API: 100% of endpoints
-- Unit: 85% of business logic
-
-## Planning Insights
-
-**Estimation Accuracy:**
-- Estimated: 60 points
-- Actual: 72 points
-- Variance: +20%
-- **Adjustment**: Use 1.2× multiplier for next epic
-
-**Requirements Clarity:**
-- PRD was clear ✅
-- Architecture was thorough ✅
-- Story AC needed refinement in 2 stories
-
-**Dependency Management:**
-- Story dependencies well-sequenced
-- No blocking issues
-
-## Action Items for Epic 2
-
-1. **Create test fixtures first** (Story 2.1)
- - Owner: DEV
- - Timeline: First story of Epic 2
-
-2. **Add 25% buffer to integration stories**
- - Owner: SM
- - Apply in epic-2 estimates
-
-3. **Mid-epic architecture check-in**
- - Owner: Architect
- - Schedule after 50% epic completion
-
-4. **Research third-party API stability**
- - Owner: DEV
- - Before starting stories with external APIs
-
-## Process Improvements
-
-**For Next Epic:**
-- ✅ Run architecture review mid-epic
-- ✅ Create test fixtures in first story
-- ✅ Add buffer time to estimates
-- ✅ Document third-party API versions in architecture
-
-**For Future Projects:**
-- Document API stability research process
-- Create reusable test fixture templates
-````
-
-### Related Workflows
-
-- **sprint-planning** - Next epic planning
-- **architecture** - May need updates from insights
-- **create-story** - Apply lessons to story creation
-
----
-
-## Utility Workflows
-
-### workflow-status
-
-**Purpose:** Check "what should I do now?" for any agent.
-
-**Agent:** All
-**Duration:** 2-5 minutes
-**When to Use:** Anytime you're unsure of next step
-
-**How It Works:**
-
-1. Loads sprint-status.yaml
-2. Determines current phase
-3. Identifies next workflow to run
-4. Provides clear recommendation
-
-**Example Output:**
+### Level 0-1 (Quick Flow)
```
-Current Phase: 4 (Implementation)
-Current Epic: Epic 1 (Authentication)
-Current Sprint: Sprint 1
-
-Next Story: Story 1.3 (Email Verification)
-Status: TODO
-Dependencies: Story 1.2 (DONE) ✅
-
-**Recommendation:** Run `create-story` to generate Story 1.3
-
-After create-story:
-1. Run story-context
-2. Run dev-story
-3. Run code-review
-4. Run story-done
+tech-spec (PM)
+ → sprint-planning (SM)
+ → story loop (SM/DEV)
```
-See: [workflow-status README](../workflows/workflow-status/README.md)
-
----
-
-### document-project
-
-**Purpose:** Analyze and document brownfield projects by scanning codebase, architecture, and patterns.
-
-**Agent:** Analyst
-**Duration:** 1-3 hours
-**When to Use:** Brownfield projects without documentation
-
-**How It Works:**
-
-1. Scans codebase structure
-2. Identifies architecture patterns
-3. Documents technology stack
-4. Creates reference documentation
-5. Generates PRD-like document from existing code
-
-**Output:** `project-documentation-{date}.md`
-
-**When to Run:**
-
-- Before starting work on legacy project
-- When inheriting undocumented codebase
-- Creating onboarding documentation
-
-See: [document-project README](../workflows/document-project/README.md)
-
----
-
-## Story Lifecycle Visualization
+### Level 2-4 (BMad Method / Enterprise)
```
-┌─────────────────────────────────────────────────────────────┐
-│ PHASE 4: IMPLEMENTATION (Iterative Story Lifecycle) │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────┐
-│ Sprint Planning │ → Creates sprint-status.yaml
-└────────┬────────┘ Defines story queue
- │
- ├──────────────────────────────────────────┐
- │ │
- ▼ │
-┌─────────────────────┐ │
-│ Epic Tech Context │ → Optional per epic │
-│ (Once per epic) │ Provides technical │
-└─────────────────────┘ guidance │
- │ │
- ▼ │
-┌─────────────────────────────────────────────────┤
-│ FOR EACH STORY IN QUEUE: │
-├─────────────────────────────────────────────────┤
- │ │
- ▼ │
-┌─────────────────┐ │
-│ Create Story │ → Generates story file │
-│ (TODO → IN PROGRESS) │
-└────────┬────────┘ │
- │ │
- ▼ │
-┌─────────────────┐ │
-│ Story Context │ → Assembles focused context │
-└────────┬────────┘ │
- │ │
- ▼ │
-┌─────────────────┐ │
-│ Dev Story │ → Implements + tests │
-│ (IN PROGRESS) │ │
-└────────┬────────┘ │
- │ │
- ▼ │
-┌─────────────────┐ │
-│ Code Review │ → Senior dev review │
-│ (IN PROGRESS → │ │
-│ READY FOR REVIEW) │
-└────────┬────────┘ │
- │ │
- ┌────┴────┐ │
- │ Result? │ │
- └────┬────┘ │
- │ │
- ┌────┼────────────────────┐ │
- │ │ │ │
- ▼ ▼ ▼ │
-APPROVED APPROVED REQUEST │
- WITH COMMENTS CHANGES │
- │ │ │ │
- └─────────┴───────────────────┘ │
- │ │
- ▼ │
- ┌─────────────────┐ │
- │ Story Done │ → READY FOR REVIEW → DONE│
- └────────┬────────┘ │
- │ │
- ├─────────────────────────────────────┘
- │ More stories?
- │
- ▼
- ┌────────────────┐
- │ Epic Complete? │
- └────────┬───────┘
- │
- ┌────┼────┐
- │ │
- Yes No
- │ └──> Continue to next story
- │
- ▼
-┌─────────────────┐
-│ Retrospective │ → Review epic, lessons learned
-└─────────────────┘
- │
- ▼
- All epics done?
- │
- Yes → PROJECT COMPLETE
+PRD + Architecture (PM/Architect)
+ → solutioning-gate-check (Architect)
+ → sprint-planning (SM, once)
+ → [Per Epic]:
+ epic-tech-context (SM)
+ → story loop (SM/DEV)
+ → epic-retrospective (SM)
+ → [Next Epic]
```
---
-## Best Practices for Phase 4
+## Related Documentation
-### 1. One Story at a Time
-
-**Focus on completing stories fully** before starting new ones. Don't parallelize stories unless you have multiple developers.
-
-### 2. Always Run story-context
-
-Don't skip context assembly. DEV agent performs better with focused, relevant context.
-
-### 3. Write Tests First (ATDD)
-
-For P0/P1 stories, write failing tests first (acceptance test-driven development), then implement to make them pass.
-
-### 4. Code Review P0/P1 Stories
-
-Always review critical stories. P2/P3 can be optional reviews.
-
-### 5. Run Retrospectives
-
-Don't skip retrospectives. They provide valuable insights that improve velocity in subsequent epics.
-
-### 6. Use workflow-status
-
-When unsure what to do next, run workflow-status. It will guide you.
-
-### 7. Document Deviations
-
-If you deviate from architecture or PRD, document why in story file.
+- [Phase 2: Planning Workflows](./workflows-planning.md)
+- [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
+- [Quick Spec Flow](./quick-spec-flow.md) - Level 0-1 fast track
+- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project levels
---
-## Common Anti-Patterns
+## Troubleshooting
-### ❌ Starting Multiple Stories Simultaneously
+**Q: Which workflow should I run next?**
+A: Run `workflow-status` - it reads the sprint status file and tells you exactly what to do.
-"Let's parallelize 5 stories to go faster."
-→ **Result**: Context switching, incomplete stories, harder to track
+**Q: Story needs significant changes mid-implementation?**
+A: Run `correct-course` to analyze impact and route appropriately.
-### ❌ Skipping story-context
+**Q: Do I run epic-tech-context for every story?**
+A: No! Run once per epic, not per story. Use `story-context` or `story-ready-for-dev` per story instead.
-"The DEV agent can just read the full PRD."
-→ **Result**: Slow context loading, irrelevant info, slower implementation
+**Q: Do I have to use story-context for every story?**
+A: No, it's optional. You can use `story-ready-for-dev` to mark a story ready without generating context XML.
-### ❌ No Code Reviews
+**Q: Can I work on multiple stories in parallel?**
+A: Not recommended. Complete one story's full lifecycle before starting the next. Prevents context switching and ensures quality.
-"Code reviews slow us down, skip them."
-→ **Result**: Technical debt, inconsistent quality, bugs in production
+**Q: What if code review finds issues?**
+A: DEV runs `develop-story` to make fixes, re-runs tests, then runs `code-review` again until it passes.
-### ❌ Skipping Retrospectives
-
-"We're too busy shipping, no time for retros."
-→ **Result**: Repeat mistakes, no process improvement, lower velocity
-
-### ✅ Correct Approach
-
-- Focus on one story at a time
-- Always assemble story context
-- Review P0/P1 stories
-- Run retrospectives after epics
-- Use workflow-status for guidance
+**Q: When do I run validations?**
+A: Validations are optional quality gates. Use them when you want independent review of epic tech specs, story drafts, or story context before proceeding.
---
-## Summary
-
-Phase 4 Implementation follows a **story-centric workflow**:
-
-| Workflow | Purpose | Frequency |
-| --------------------- | ------------------- | ----------------- |
-| **sprint-planning** | Initialize tracking | Once at start |
-| **epic-tech-context** | Technical guidance | Once per epic |
-| **create-story** | Generate story file | Per story |
-| **story-context** | Assemble context | Per story |
-| **dev-story** | Implement story | Per story |
-| **code-review** | Review quality | Per story (P0/P1) |
-| **correct-course** | Handle changes | As needed |
-| **retrospective** | Learn and improve | After each epic |
-
-**Key Takeaway:** Implementation is iterative and incremental. Move one story through its full lifecycle before starting the next. Use retrospectives to continuously improve.
-
-**Next:** Testing & QA (testarch workflows) run in parallel with implementation.
-
-See: [workflows-testing.md](./workflows-testing.md)
+_Phase 4 Implementation - One story at a time, done right._
diff --git a/src/modules/bmm/docs/workflows-planning.md b/src/modules/bmm/docs/workflows-planning.md
index d08d818f..ca830f88 100644
--- a/src/modules/bmm/docs/workflows-planning.md
+++ b/src/modules/bmm/docs/workflows-planning.md
@@ -1,25 +1,90 @@
# BMM Planning Workflows (Phase 2)
-**Reading Time:** ~15 minutes
-
## 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.
**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["START: plan-project
Discovery and routing"]
+
+ subgraph QuickFlow["QUICK FLOW (Levels 0-1)"]
+ TechSpec["PM: tech-spec
Lightweight spec for simple changes"]
+ end
+
+ subgraph StandardFlow["STANDARD PLANNING (Levels 2-4)"]
+ PRD["PM: prd
Strategic PRD"]
+ GDD["Game Designer: gdd
Game design document"]
+ Narrative["Game Designer: narrative
Story-driven design"]
+ UXDesign["UX Designer: ux
UX-first specification"]
+
+ Epics["PM: create-epics-and-stories
Break requirements into epics and stories"]
+ end
+
+ subgraph Updates["STORY UPDATES (Anytime After Epics Created)"]
+ CorrectCourse["PM/SM: correct-course
Update epics/stories mid-stream"]
+ end
+
+ Entry -->|Level 0-1
Simple| QuickFlow
+ Entry -->|Level 2-4
Software| PRD
+ Entry -->|Level 2-4
Game| GDD
+ Entry -->|Level 2-4
Story-driven| Narrative
+ Entry -->|Level 2-4
UX-first| UXDesign
+
+ PRD --> Epics
+ GDD --> Epics
+ Narrative --> Epics
+ UXDesign -.->|May update| Epics
+
+ Epics --> Phase3["Phase 3: Architecture"]
+ Phase3 -.->|May update| Epics
+
+ QuickFlow --> Phase4["Phase 4: Implementation"]
+ 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
-| Workflow | Project Levels | Duration | Purpose |
-| ------------- | -------------- | ---------- | --------------------------------------- |
-| **prd** | 2-4 | 2-6 hours | Strategic PRD + tactical epic breakdown |
-| **tech-spec** | 0-1 | 30-90 min | Lightweight technical specification |
-| **gdd** | 2-4 (games) | 4-10 hours | Complete game design document |
-| **narrative** | 2-4 (story) | 3-8 hours | Story-driven game/experience design |
-| **ux** | 2-4 (UX-heavy) | 3-6 hours | UX-first design specification |
+| Workflow | Agent | Project Levels | Purpose |
+| ---------------------------- | ------------- | -------------- | ---------------------------------------------------- |
+| **prd** | PM | 2-4 | Strategic PRD |
+| **create-epics-and-stories** | PM | 2-4 | Break PRD/GDD into epics and stories (standalone OK) |
+| **tech-spec** | PM | 0-1 | Lightweight technical specification |
+| **gdd** | Game Designer | 2-4 (games) | Complete game design document |
+| **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.
+**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
@@ -73,7 +138,6 @@ Single unified entry point for all planning workflows. Uses conversational disco
**Agent:** PM (orchestrates other agents as needed)
**Phase:** 2 (Planning)
**Required:** Yes (for all projects)
-**Typical Duration:** Varies by target workflow
### When to Use
@@ -161,28 +225,24 @@ ELSE:
- **Input**: "Fix null pointer exception in user service"
- **Discovery**: Level 0 (single atomic change)
- **Route**: tech-spec (Quick Spec Flow)
-- **Duration**: 20 minutes
**Scenario 2: E-commerce Checkout**
- **Input**: "Build complete checkout flow with payment processing"
- **Discovery**: Level 3 (large feature set), feature-focused
- **Route**: prd (Standard depth)
-- **Duration**: 4 hours
**Scenario 3: Roguelike Card Game**
- **Input**: "Roguelike card battler with emotional narrative"
- **Discovery**: Level 3 (large feature set), game project
- **Route**: gdd
-- **Duration**: 6 hours
**Scenario 4: Story-Driven Adventure**
- **Input**: "Narrative adventure game with branching story"
- **Discovery**: Level 3, story-central
- **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
**Phase:** 2 (Planning)
**Project Levels:** 0-1
-**Typical Duration:** 30-90 minutes
### 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)
**Phase:** 2 (Planning)
**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
@@ -488,11 +542,6 @@ Complete game design document for Levels 2-4 game projects, adapted from industr
**Agent:** PM (Game Designer persona)
**Phase:** 2 (Planning)
**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
@@ -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)
**Phase:** 2 (Planning)
**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
@@ -825,11 +869,6 @@ UX specification workflow for projects where user experience is the primary diff
**Agent:** UX Designer
**Phase:** 2 (Planning)
**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
diff --git a/src/modules/bmm/docs/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md
index c28f69c5..5f54991d 100644
--- a/src/modules/bmm/docs/workflows-solutioning.md
+++ b/src/modules/bmm/docs/workflows-solutioning.md
@@ -1,19 +1,56 @@
# BMM Solutioning Workflows (Phase 3)
-**Reading Time:** ~8 minutes
-
## 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.
**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["FROM Phase 2
PRD/GDD/Narrative/UX complete"]
+
+ subgraph Solutioning["PHASE 3: SOLUTIONING"]
+ direction TB
+ Architecture["Architect: architecture
Technical design and decisions"]
+ GateCheck["Architect: solutioning-gate-check
Validation before implementation"]
+ end
+
+ subgraph Optional["OPTIONAL PATHS"]
+ direction LR
+ Level2Skip["Level 2:
Skip if straightforward"]
+ end
+
+ FromPRD --> Architecture
+ Architecture --> GateCheck
+ GateCheck -->|PASS| Phase4["Phase 4: Implementation"]
+ 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
-| Workflow | Project Levels | Duration | Purpose |
-| -------------------------- | -------------- | --------- | ------------------------------------------- |
-| **architecture** | 2-4 | 2-6 hours | Technical architecture and design decisions |
-| **solutioning-gate-check** | 3-4 | 15-30 min | Validate planning/solutioning completeness |
+| Workflow | Project Levels | Purpose |
+| -------------------------- | -------------- | ------------------------------------------- |
+| **architecture** | 2-4 | Technical architecture and design decisions |
+| **solutioning-gate-check** | 3-4 | Validate planning/solutioning completeness |
**When to Skip Solutioning:**
@@ -86,11 +123,6 @@ Collaborative architectural decision facilitation that produces a decision-focus
**Phase:** 3 (Solutioning)
**Project Levels:** 2-4
**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
@@ -341,7 +373,6 @@ Systematically validate that all planning and solutioning phases are complete an
**Phase:** 3 (Solutioning)
**Project Levels:** 3-4
**Required:** Level 3-4 only
-**Typical Duration:** 15-30 minutes
### When to Use
@@ -544,21 +575,20 @@ Optional:
1. **Critical**: Architecture missing security architecture section
- **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
- **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
- **Impact**: Risk of story scope creep
- - **Recommendation**: Split into 2 stories (30 min)
+ - **Recommendation**: Split into 2 stories
**Gate Decision:** CONCERNS ⚠️
- **Rationale**: Critical and high gaps block Epic 1 and Epic 4
- **Action**: Resolve gaps #1 and #2 before starting implementation
-- **Timeline**: Address in 3 hours, then re-run gate check
**Next Steps:**
diff --git a/src/modules/bmm/tasks/daily-standup.xml b/src/modules/bmm/tasks/daily-standup.xml
index 4fa9fa34..d41c362c 100644
--- a/src/modules/bmm/tasks/daily-standup.xml
+++ b/src/modules/bmm/tasks/daily-standup.xml
@@ -64,7 +64,7 @@
Primary: Sarah (PO), Bob (SM), James (Dev)
Secondary: Murat (TEA)
-
+
Primary: Winston (Architect), James (Dev), Murat (TEA)
Secondary: Sarah (PO)
diff --git a/src/modules/bmm/workflows/techdoc/documentation-standards.md b/src/modules/bmm/workflows/techdoc/documentation-standards.md
index ffc878cd..e5f73e4e 100644
--- a/src/modules/bmm/workflows/techdoc/documentation-standards.md
+++ b/src/modules/bmm/workflows/techdoc/documentation-standards.md
@@ -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.
+### 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
**Headers:**
@@ -194,6 +216,7 @@ Apply in this hierarchy:
Before finalizing ANY documentation:
- [ ] CommonMark compliant (no violations)
+- [ ] NO time estimates anywhere (Critical Rule 2)
- [ ] Headers in proper hierarchy
- [ ] All code blocks have language tags
- [ ] Links work and have descriptive text
diff --git a/src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md b/src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md
index 027eb18e..a64c4969 100644
--- a/src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md
+++ b/src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md
@@ -355,8 +355,8 @@ See `tea-index.csv` for complete knowledge fragment mapping.
- Ask in team standup
- Tag @{tea_agent_username} in Slack/Discord
-- Refer to `testarch/README.md` for workflow documentation
-- Consult `testarch/knowledge/` for testing best practices
+- Refer to `./bmm/docs/tea-README.md` for workflow documentation
+- Consult `./bmm/testarch/knowledge` for testing best practices
---
diff --git a/tools/schema/agent.js b/tools/schema/agent.js
index a7c4671a..704600ad 100644
--- a/tools/schema/agent.js
+++ b/tools/schema/agent.js
@@ -176,6 +176,8 @@ function buildMenuItemSchema() {
tmpl: createNonEmptyString('agent.menu[].tmpl').optional(),
data: createNonEmptyString('agent.menu[].data').optional(),
'run-workflow': createNonEmptyString('agent.menu[].run-workflow').optional(),
+ checklist: createNonEmptyString('agent.menu[].checklist').optional(),
+ document: createNonEmptyString('agent.menu[].document').optional(),
})
.strict()
.superRefine((value, ctx) => {