From 84ec72fb94f4dd376469323ebc3a79fe2c5abe6e Mon Sep 17 00:00:00 2001 From: Murat K Ozcan <34237651+muratkeremozcan@users.noreply.github.com> Date: Tue, 4 Nov 2025 10:31:36 -0600 Subject: [PATCH 1/2] fix: tea-readme 3 (#855) * fix: tea-readme 3 * fix: tea-readme 3 --------- Co-authored-by: Murat Ozcan --- bmad/_cfg/files-manifest.csv | 1 + bmad/bmm/docs/README.md | 2 +- bmad/bmm/docs/brownfield-guide.md | 2 +- bmad/bmm/docs/tea-README.md | 311 ++++++++++++++++++ .../testarch/atdd/atdd-checklist-template.md | 4 +- package-lock.json | 4 +- src/modules/bmm/docs/README.md | 2 +- src/modules/bmm/docs/brownfield-guide.md | 2 +- .../testarch/atdd/atdd-checklist-template.md | 4 +- tools/schema/agent.js | 2 + 10 files changed, 324 insertions(+), 10 deletions(-) create mode 100644 bmad/bmm/docs/tea-README.md 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/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..5a556dac 100644 --- a/src/modules/bmm/docs/README.md +++ b/src/modules/bmm/docs/README.md @@ -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](./tea-README.md)** - Comprehensive quality assurance (1,420 lines) - Test strategy, automation, quality gates - TEA agent and test healing - BMad-integrated vs standalone modes diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md index e185db2d..06c1a69e 100644 --- a/src/modules/bmm/docs/brownfield-guide.md +++ b/src/modules/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](../../../../bmad/bmm/docs/tea-README.md) - [BMM Module README](../README.md) --- 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) => { From ba5f76c37db6ea9fe3d4214e8ed19806fc9f55c0 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 4 Nov 2025 15:02:19 -0600 Subject: [PATCH 2/2] Doc cleanup and mermaid diagram drafts added --- bmad/bmm/docs/troubleshooting.md | 2 +- bmad/bmm/tasks/daily-standup.xml | 2 +- src/modules/bmm/docs/README.md | 19 +- src/modules/bmm/docs/agents-guide.md | 2 +- src/modules/bmm/docs/brownfield-guide.md | 11 +- .../docs/enterprise-agentic-development.md | 6 +- src/modules/bmm/docs/faq.md | 12 +- src/modules/bmm/docs/glossary.md | 16 +- src/modules/bmm/docs/quick-spec-flow.md | 6 +- src/modules/bmm/docs/quick-start.md | 10 +- src/modules/bmm/docs/scale-adaptive-system.md | 2 +- src/modules/bmm/docs/test-architecture.md | 329 +++ src/modules/bmm/docs/troubleshooting.md | 14 +- src/modules/bmm/docs/workflows-analysis.md | 92 +- .../bmm/docs/workflows-implementation.md | 1876 ++--------------- src/modules/bmm/docs/workflows-planning.md | 109 +- src/modules/bmm/docs/workflows-solutioning.md | 62 +- src/modules/bmm/tasks/daily-standup.xml | 2 +- .../techdoc/documentation-standards.md | 25 +- 19 files changed, 790 insertions(+), 1807 deletions(-) create mode 100644 src/modules/bmm/docs/test-architecture.md 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/src/modules/bmm/docs/README.md b/src/modules/bmm/docs/README.md index 5a556dac..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](./tea-README.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 06c1a69e..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](../../../../bmad/bmm/docs/tea-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