From c20ead1acb4b9263995bcfb46180eca3d0f4b5b8 Mon Sep 17 00:00:00 2001 From: Murat K Ozcan <34237651+muratkeremozcan@users.noreply.github.com> Date: Wed, 5 Nov 2025 13:37:51 -0600 Subject: [PATCH 1/2] refactor: update TEA documentation to align with BMad 4-phase methodology (#870) * refactor: update TEA documentation to align with BMad 4-phase methodology * reafactor: address review comments --------- Co-authored-by: Murat Ozcan --- .gitignore | 2 +- .../paths/enterprise-brownfield.yaml | 29 +- .../paths/enterprise-greenfield.yaml | 29 +- src/modules/bmm/docs/test-architecture.md | 309 +++++++++++------- src/modules/bmm/docs/workflows-solutioning.md | 17 +- .../paths/enterprise-brownfield.yaml | 29 +- .../paths/enterprise-greenfield.yaml | 29 +- 7 files changed, 269 insertions(+), 175 deletions(-) diff --git a/.gitignore b/.gitignore index 9eff8ef1..e55e43e0 100644 --- a/.gitignore +++ b/.gitignore @@ -34,7 +34,7 @@ Thumbs.db .bmad*/.cursor/ # AI assistant files -CLAUDE.md +# CLAUDE.md # we need this for Claude Code reviews .ai/* cursor .gemini diff --git a/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml b/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml index 7e4d0d73..a05527b1 100644 --- a/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml +++ b/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml @@ -77,26 +77,33 @@ phases: output: "Integration architecture with enterprise considerations" note: "Distills brownfield context + adds security/scalability/compliance design" + - id: "framework" + optional: true + agent: "tea" + command: "framework" + output: "Test framework scaffold (Playwright/Cypress)" + note: "Modernize test framework AFTER architecture defines integration approach" + + - id: "ci" + optional: true + agent: "tea" + command: "ci" + output: "CI/CD test pipeline configuration" + note: "Configure CI pipeline AFTER architecture and framework decisions" + - id: "create-security-architecture" - required: true + optional: true agent: "architect" command: "create-security-architecture" output: "Security architecture for brownfield integration" - note: "Future workflow - threat model, auth integration, audit requirements" + note: "Future workflow - optional extended enterprise workflow for threat model, auth integration, audit requirements" - id: "create-devops-strategy" - required: true + optional: true agent: "architect" command: "create-devops-strategy" output: "DevOps strategy for brownfield deployment" - note: "Future workflow - CI/CD integration, deployment strategy, monitoring" - - - id: "create-test-strategy" - required: true - agent: "tea" - command: "create-test-strategy" - output: "Test strategy including regression testing" - note: "Future workflow - critical for brownfield to prevent breaking existing functionality" + note: "Future workflow - optional extended enterprise workflow for CI/CD integration, deployment strategy, monitoring" - id: "validate-architecture" optional: true diff --git a/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml b/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml index f5584d2c..bb743071 100644 --- a/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml +++ b/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml @@ -65,26 +65,33 @@ phases: output: "Enterprise-grade system architecture" note: "Includes scalability, multi-tenancy, integration architecture" + - id: "framework" + optional: true + agent: "tea" + command: "framework" + output: "Test framework scaffold (Playwright/Cypress)" + note: "Initialize test framework AFTER architecture defines technology stack" + + - id: "ci" + optional: true + agent: "tea" + command: "ci" + output: "CI/CD test pipeline configuration" + note: "Configure CI pipeline AFTER architecture and framework choices are made" + - id: "create-security-architecture" - required: true + optional: true agent: "architect" command: "create-security-architecture" output: "Security architecture and threat model" - note: "Future workflow - security design, auth, compliance" + note: "Future workflow - optional extended enterprise workflow for security design, auth, compliance" - id: "create-devops-strategy" - required: true + optional: true agent: "architect" command: "create-devops-strategy" output: "DevOps pipeline and infrastructure plan" - note: "Future workflow - CI/CD, deployment, monitoring" - - - id: "create-test-strategy" - required: true - agent: "tea" - command: "create-test-strategy" - output: "Comprehensive test strategy" - note: "Future workflow - test approach, automation, quality gates" + note: "Future workflow - optional extended enterprise workflow for CI/CD, deployment, monitoring" - id: "validate-architecture" optional: true diff --git a/src/modules/bmm/docs/test-architecture.md b/src/modules/bmm/docs/test-architecture.md index 1e9dcb59..57d3eca6 100644 --- a/src/modules/bmm/docs/test-architecture.md +++ b/src/modules/bmm/docs/test-architecture.md @@ -1,5 +1,5 @@ --- -last-redoc-date: 2025-10-14 +last-redoc-date: 2025-11-05 --- # Test Architect (TEA) Agent Guide @@ -7,29 +7,37 @@ last-redoc-date: 2025-10-14 ## 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. +- **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project complexity and compliance demands. +- **Use When:** BMad Method or Enterprise track projects, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required. (Quick Flow projects typically don't require TEA) ## TEA Workflow Lifecycle -TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase: +TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4): ```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 + PM["PM: *prd (creates PRD + epics)"] + PlanNote["Business requirements phase"] + PM -.-> PlanNote end - subgraph Phase4["Phase 4: IMPLEMENTATION - Per Story Cycle"] + subgraph Phase3["Phase 3: SOLUTIONING"] + Architecture["Architect: *architecture"] + Framework["TEA: *framework"] + CI["TEA: *ci"] + GateCheck["Architect: *solutioning-gate-check"] + Architecture --> Framework + Framework --> CI + CI --> GateCheck + Phase3Note["Test infrastructure AFTER architecture
defines technology stack"] + Framework -.-> Phase3Note + end + + subgraph Phase4["Phase 4: IMPLEMENTATION - Per Epic Cycle"] + SprintPlan["SM: *sprint-planning"] + TestDesign["TEA: *test-design (per epic)"] CreateStory["SM: *create-story"] ATDD["TEA: *atdd (optional, before dev)"] DevImpl["DEV: implements story"] @@ -37,12 +45,16 @@ graph TB TestReview1["TEA: *test-review (optional)"] Trace1["TEA: *trace (refresh coverage)"] + SprintPlan --> TestDesign + TestDesign --> CreateStory CreateStory --> ATDD ATDD --> DevImpl DevImpl --> Automate Automate --> TestReview1 TestReview1 --> Trace1 Trace1 -.->|next story| CreateStory + TestDesignNote["Test design: 'How do I test THIS epic?'
Creates test-design-epic-N.md per epic"] + TestDesign -.-> TestDesignNote end subgraph Gate["EPIC/RELEASE GATE"] @@ -60,10 +72,12 @@ graph TB GateDecision -->|WAIVED| Waived["WAIVED ⏭️"] end - Phase2 --> Phase4 + Phase2 --> Phase3 + Phase3 --> Phase4 Phase4 --> Gate style Phase2 fill:#bbdefb,stroke:#0d47a1,stroke-width:3px,color:#000 + style Phase3 fill:#c8e6c9,stroke:#2e7d32,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 @@ -72,82 +86,129 @@ graph TB style Waived fill:#9c27b0,stroke:#4a148c,stroke-width:3px,color:#000 ``` -### TEA Integration with BMad v6 Workflow +**Phase Numbering Note:** BMad uses a 4-phase methodology with optional Phase 0/1: -TEA operates **across all four BMad phases**, unlike other agents that are phase-specific: +- **Phase 0** (Optional): Documentation (brownfield prerequisite - `*document-project`) +- **Phase 1** (Optional): Discovery/Analysis (`*brainstorm`, `*research`, `*product-brief`) +- **Phase 2** (Required): Planning (`*prd` creates PRD + epics) +- **Phase 3** (Track-dependent): Solutioning (`*architecture` → TEA: `*framework`, `*ci` → `*solutioning-gate-check`) +- **Phase 4** (Required): Implementation (`*sprint-planning` → per-epic: `*test-design` → per-story: dev workflows) + +**TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` runs per-epic in Phase 4. Output: `test-design-epic-N.md`. + +Quick Flow track skips Phases 0, 1, and 3. BMad Method and Enterprise use all phases based on project needs. + +### Why TEA is Different from Other BMM Agents + +TEA is the only BMM agent that operates in **multiple phases** (Phase 3 and Phase 4) and has its own **knowledge base architecture**.
-Cross-Phase Integration & Workflow Complexity +Cross-Phase Operation & Unique Architecture ### Phase-Specific Agents (Standard Pattern) +Most BMM agents work in a single phase: + - **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: Multi-Phase Quality Agent (Unique Pattern) -TEA is **the only agent that spans all phases**: +TEA is **the only agent that operates in multiple phases**: ``` Phase 1 (Analysis) → [TEA not typically used] ↓ -Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup) +Phase 2 (Planning) → [PM defines requirements - TEA not active] ↓ -Phase 3 (Solutioning) → [TEA validates architecture testability] +Phase 3 (Solutioning) → TEA: *framework, *ci (test infrastructure AFTER architecture) ↓ -Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story) +Phase 4 (Implementation) → TEA: *test-design (per epic: "how do I test THIS feature?") + → TEA: *atdd, *automate, *test-review, *trace (per story) ↓ Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision) ``` -### Why TEA Needs 8 Workflows +### TEA's 8 Workflows Across Phases **Standard agents**: 1-3 workflows per phase -**TEA**: 8 workflows across 3+ phases +**TEA**: 8 workflows across Phase 3, Phase 4, and Release Gate -| 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 | +| Phase | TEA Workflows | Frequency | Purpose | +| ----------- | ----------------------------------------------------- | ---------------- | ---------------------------------------------- | +| **Phase 2** | (none) | - | Planning phase - PM defines requirements | +| **Phase 3** | *framework, *ci | Once per project | Setup test infrastructure AFTER architecture | +| **Phase 4** | *test-design, *atdd, *automate, *test-review, \*trace | Per epic/story | Test planning per epic, then per-story testing | +| **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). +### Unique Directory Architecture + +TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`): + +``` +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 covering test patterns, CI/CD, fixtures, quality practices, healing strategies +- **Centralized reference system**: `tea-index.csv` for on-demand fragment loading during workflow execution +- **Cross-cutting concerns**: Domain-specific testing patterns (vs project-specific artifacts like PRDs/stories) +- **Optional MCP integration**: Healing, exploratory, and verification modes for enhanced testing capabilities + +This architecture enables TEA to maintain consistent, production-ready testing patterns across all BMad projects while operating across multiple development phases.
-## 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) +These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks** across the **4-Phase Methodology** (Phase 1: Analysis, Phase 2: Planning, Phase 3: Solutioning, Phase 4: Implementation). -| 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) | +**Note:** Quick Flow projects typically don't require TEA (covered in Overview). These cheat sheets focus on BMad Method and Enterprise tracks where TEA adds value. + +**Legend for Track Deltas:** + +- ➕ = New workflow or phase added (doesn't exist in baseline) +- 🔄 = Modified focus (same workflow, different emphasis or purpose) +- 📦 = Additional output or archival requirement + +### Greenfield - BMad Method (Simple/Standard Work) + +**Planning Track:** BMad Method (PRD + Architecture) +**Use Case:** New projects with standard complexity + +| Workflow Stage | Test Architect | Dev / Team | Outputs | +| -------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| **Phase 1**: Discovery | - | Analyst `*product-brief` (optional) | `product-brief.md` | +| **Phase 2**: Planning | - | PM `*prd` (creates PRD + epics) | PRD, epics | +| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, test scaffold, CI pipeline | +| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories | +| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic (per-epic test plan) | Review epic scope | `test-design-epic-N.md` with risk assessment and test plan | +| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation | +| **Phase 4**: Story Review | Execute `*test-review` (optional), re-run `*trace` | Address recommendations, update code/tests | Quality report, refreshed coverage matrix | +| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary |
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. +- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to setup test infrastructure based on architectural decisions. +- **Phase 4 starts**: After solutioning is complete, sprint planning loads all epics. +- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create a test plan for THAT specific epic/feature. Output: `test-design-epic-N.md`. - 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. @@ -157,79 +218,110 @@ This complexity **requires specialized documentation** (this guide), **extensive
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. +1. **Planning (Phase 2):** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD and epics. +2. **Solutioning (Phase 3):** Architect completes `*architecture` for the new module; TEA sets up test infrastructure via `*framework` and `*ci` based on architectural decisions; gate check validates planning completeness. +3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status. +4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` to create test plan for Epic 1, producing `test-design-epic-1.md` with risk assessment. +5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA optionally runs `*atdd`; Dev implements with guidance from failing tests. +6. **Post-Dev (Phase 4):** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage. +7. **Release Gate:** TEA runs `*trace` with Phase 2 enabled to generate gate decision.
-### Brownfield Feature Enhancement (Level 3–4) +### Brownfield - BMad Method or Enterprise (Simple or Complex) -| 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 | +**Planning Tracks:** BMad Method or Enterprise Method +**Use Case:** Existing codebases - simple additions (BMad Method) or complex enterprise requirements (Enterprise Method) + +**🔄 Brownfield Deltas from Greenfield:** + +- ➕ Phase 0 (Documentation) - Document existing codebase if undocumented +- ➕ Phase 2: `*trace` - Baseline existing test coverage before planning +- 🔄 Phase 4: `*test-design` - Focus on regression hotspots and brownfield risks +- 🔄 Phase 4: Story Review - May include `*nfr-assess` if not done earlier + +| Workflow Stage | Test Architect | Dev / Team | Outputs | +| ----------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- | +| **Phase 0**: Documentation ➕ | - | Analyst `*document-project` (if undocumented) | Comprehensive project documentation | +| **Phase 1**: Discovery | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` | +| **Phase 2**: Planning | Run ➕ `*trace` (baseline coverage) | PM `*prd` (creates PRD + epics) | PRD, epics, ➕ coverage baseline | +| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, test framework, CI pipeline | +| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories | +| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (regression hotspots) | Review epic scope and brownfield risks | `test-design-epic-N.md` with brownfield risk assessment and mitigation | +| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation | +| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report | +| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, 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. +- Lead with `*trace` during Planning (Phase 2) to baseline existing test coverage before architecture work begins. +- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to modernize test infrastructure. For brownfield, framework may need to integrate with or replace existing test setup. +- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics. +- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to identify regression hotspots, integration risks, and mitigation strategies for THAT specific epic/feature. Output: `test-design-epic-N.md`. - 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. +1. **Planning (Phase 2):** PM executes `*prd` to update PRD and `epics.md` (Epic 1: Payment Processing); TEA runs `*trace` to baseline existing coverage. +2. **Solutioning (Phase 3):** Architect triggers `*architecture` capturing legacy payment flows and integration architecture; TEA sets up `*framework` and `*ci` based on architectural decisions; gate check validates planning. +3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load Epic 1 into sprint status. +4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` for Epic 1 (Payment Processing), producing `test-design-epic-1.md` that flags settlement edge cases, regression hotspots, and mitigation plans. +5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA runs `*atdd` producing failing Playwright specs; Dev implements with guidance from tests and checklist. +6. **Post-Dev (Phase 4):** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage. +7. **Release Gate:** TEA performs `*nfr-assess` to validate SLAs, runs `*trace` with Phase 2 enabled to generate gate decision (PASS/CONCERNS/FAIL).
-### Enterprise / Compliance Program (Level 4) +### Greenfield - Enterprise Method (Enterprise/Compliance Work) -| 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 | +**Planning Track:** Enterprise Method (BMad Method + extended security/devops/test strategies) +**Use Case:** New enterprise projects with compliance, security, or complex regulatory requirements + +**🏢 Enterprise Deltas from BMad Method:** + +- ➕ Phase 1: `*research` - Domain and compliance research (recommended) +- ➕ Phase 2: `*nfr-assess` - Capture NFR requirements early (security/performance/reliability) +- 🔄 Phase 4: `*test-design` - Enterprise focus (compliance, security architecture alignment) +- 📦 Release Gate - Archive artifacts and compliance evidence for audits + +| Workflow Stage | Test Architect | Dev / Team | Outputs | +| -------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------ | +| **Phase 1**: Discovery | - | Analyst ➕ `*research`, `*product-brief` | Domain research, compliance analysis, product brief | +| **Phase 2**: Planning | Run ➕ `*nfr-assess` | PM `*prd` (creates PRD + epics), UX `*create-design` | Enterprise PRD, epics, UX design, ➕ NFR documentation | +| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, test framework, CI pipeline | +| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint plan with all epics | +| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (compliance focus) | Review epic scope and compliance requirements | `test-design-epic-N.md` with security/performance/compliance focus | +| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices | +| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | 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. +- `*nfr-assess` runs early in Planning (Phase 2) to capture compliance, security, and performance requirements upfront. +- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` with enterprise-grade configurations (selective testing, burn-in jobs, caching, notifications). +- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics. +- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create an enterprise-focused test plan for THAT specific epic, ensuring alignment with security architecture, performance targets, and compliance requirements. Output: `test-design-epic-N.md`. +- Use `*atdd` for stories when feasible so acceptance tests can lead implementation. +- Use `*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); archive artifacts for compliance audits.
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. +1. **Planning (Phase 2):** Analyst runs `*research` and `*product-brief`; PM completes `*prd` creating PRD and epics; TEA runs `*nfr-assess` to establish NFR targets. +2. **Solutioning (Phase 3):** Architect completes `*architecture` with enterprise considerations; TEA sets up `*framework` and `*ci` with enterprise-grade configurations based on architectural decisions; gate check validates planning completeness. +3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status. +4. **Per-Epic (Phase 4):** For each epic, TEA runs `*test-design` to create epic-specific test plan (e.g., `test-design-epic-1.md`, `test-design-epic-2.md`) with compliance-focused risk assessment. +5. **Per-Story (Phase 4):** For each story, TEA uses `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings. +6. **Release Gate:** 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.
@@ -251,7 +343,7 @@ MCP provides additional capabilities on top of TEA's default AI-based approach: - Default: Analysis + documentation - **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation - Benefit:Discover actual functionality, edge cases, undocumented features + Benefit: Discover actual functionality, edge cases, undocumented features 2. `*atdd`, `*automate`: - Default: Infers selectors and interactions from requirements and knowledge fragments @@ -300,30 +392,3 @@ MCP provides additional capabilities on top of TEA's default AI-based approach: | `*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/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md index 875301ff..f1a38e18 100644 --- a/src/modules/bmm/docs/workflows-solutioning.md +++ b/src/modules/bmm/docs/workflows-solutioning.md @@ -32,9 +32,8 @@ graph TB subgraph Optional["ENTERPRISE ADDITIONS (Optional)"] direction LR - TestArch["TEA: test-architecture
(Future)"] - SecArch["Architect: security-architecture"] - DevOps["Architect: devops-strategy"] + SecArch["Architect: security-architecture
(Future)"] + DevOps["Architect: devops-strategy
(Future)"] end GateCheck["Architect: solutioning-gate-check
Validation before Phase 4"] @@ -69,7 +68,6 @@ graph TB style SkipArch fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000 style Architecture fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000 - style TestArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000 style SecArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000 style DevOps fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000 style GateCheck fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000 @@ -352,13 +350,14 @@ Planning (prd by PM) ``` Planning (prd by PM - same as BMad Method) → architecture (Architect) - → Optional: test-architecture (TEA, future) - → Optional: security-architecture (Architect) - → Optional: devops-strategy (Architect) + → Optional: security-architecture (Architect, future) + → Optional: devops-strategy (Architect, future) → solutioning-gate-check (Architect) → Phase 4 (Implementation) ``` +**Note on TEA (Test Architect):** TEA is fully operational with 8 workflows across all phases. TEA validates architecture testability during Phase 3 reviews but does not have a dedicated solutioning workflow. TEA's primary setup occurs in Phase 2 (`*framework`, `*ci`, `*test-design`) and testing execution in Phase 4 (`*atdd`, `*automate`, `*test-review`, `*trace`, `*nfr-assess`). + **Note:** Enterprise uses the same planning and architecture as BMad Method. The only difference is optional extended workflows added AFTER architecture but BEFORE gate check. ### Solutioning → Implementation Handoff @@ -422,11 +421,13 @@ Architecture documents are living. Update them as you learn during implementatio ### Enterprise - **Planning:** prd (PM) - same as BMad Method -- **Solutioning:** architecture (Architect) → Optional extended workflows (test-architecture, security-architecture, devops-strategy) → solutioning-gate-check (Architect) +- **Solutioning:** architecture (Architect) → Optional extended workflows (security-architecture, devops-strategy) → solutioning-gate-check (Architect) - **Implementation:** sprint-planning → epic-tech-context → dev-story **Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE gate check. Everything else is identical to BMad Method. +**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](./test-architecture.md) for TEA's full lifecycle integration. + --- ## Common Anti-Patterns diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml index 7e4d0d73..a1cedcac 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml @@ -66,6 +66,20 @@ phases: command: "create-design" note: "Recommended - must integrate with existing UX patterns" + - id: "framework" + optional: true + agent: "tea" + command: "framework" + output: "Test framework scaffold (Playwright/Cypress)" + note: "Initialize or modernize test framework - critical if brownfield lacks proper test infrastructure" + + - id: "ci" + optional: true + agent: "tea" + command: "ci" + output: "CI/CD test pipeline configuration" + note: "Establish or enhance CI pipeline with regression testing strategy" + - phase: 2 name: "Solutioning" required: true @@ -78,25 +92,18 @@ phases: note: "Distills brownfield context + adds security/scalability/compliance design" - id: "create-security-architecture" - required: true + optional: true agent: "architect" command: "create-security-architecture" output: "Security architecture for brownfield integration" - note: "Future workflow - threat model, auth integration, audit requirements" + note: "Future workflow - optional extended enterprise workflow for threat model, auth integration, audit requirements" - id: "create-devops-strategy" - required: true + optional: true agent: "architect" command: "create-devops-strategy" output: "DevOps strategy for brownfield deployment" - note: "Future workflow - CI/CD integration, deployment strategy, monitoring" - - - id: "create-test-strategy" - required: true - agent: "tea" - command: "create-test-strategy" - output: "Test strategy including regression testing" - note: "Future workflow - critical for brownfield to prevent breaking existing functionality" + note: "Future workflow - optional extended enterprise workflow for CI/CD integration, deployment strategy, monitoring" - id: "validate-architecture" optional: true diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml index f5584d2c..47028ae9 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml @@ -54,6 +54,20 @@ phases: command: "create-design" note: "Highly recommended for enterprise - design system and patterns" + - id: "framework" + optional: true + agent: "tea" + command: "framework" + output: "Test framework scaffold (Playwright/Cypress)" + note: "Initialize production-ready test framework - run once per project" + + - id: "ci" + optional: true + agent: "tea" + command: "ci" + output: "CI/CD test pipeline configuration" + note: "Scaffold CI workflow with selective testing, burn-in, caching" + - phase: 2 name: "Solutioning" required: true @@ -66,25 +80,18 @@ phases: note: "Includes scalability, multi-tenancy, integration architecture" - id: "create-security-architecture" - required: true + optional: true agent: "architect" command: "create-security-architecture" output: "Security architecture and threat model" - note: "Future workflow - security design, auth, compliance" + note: "Future workflow - optional extended enterprise workflow for security design, auth, compliance" - id: "create-devops-strategy" - required: true + optional: true agent: "architect" command: "create-devops-strategy" output: "DevOps pipeline and infrastructure plan" - note: "Future workflow - CI/CD, deployment, monitoring" - - - id: "create-test-strategy" - required: true - agent: "tea" - command: "create-test-strategy" - output: "Comprehensive test strategy" - note: "Future workflow - test approach, automation, quality gates" + note: "Future workflow - optional extended enterprise workflow for CI/CD, deployment, monitoring" - id: "validate-architecture" optional: true From bc76d25be61199edf93856ad11a85d0f9ee179cc Mon Sep 17 00:00:00 2001 From: Murat K Ozcan <34237651+muratkeremozcan@users.noreply.github.com> Date: Wed, 5 Nov 2025 14:14:31 -0600 Subject: [PATCH 2/2] chore: added CC PR review (#871) * chore: added CC PR review * remove CLAUDE.md --------- Co-authored-by: Murat Ozcan --- .github/workflows/claude-code-review.yaml | 203 ++++++++++++++++++++ .github/workflows/lint.yaml | 61 ------ .github/workflows/quality.yaml | 123 +++++++++++++ .gitignore | 2 +- .husky/pre-commit | 4 + README.md | 60 +++++- package-lock.json | 4 +- package.json | 6 +- test/test-installation-components.js | 214 ++++++++++++++++++++++ 9 files changed, 610 insertions(+), 67 deletions(-) create mode 100644 .github/workflows/claude-code-review.yaml delete mode 100644 .github/workflows/lint.yaml create mode 100644 .github/workflows/quality.yaml create mode 100644 test/test-installation-components.js diff --git a/.github/workflows/claude-code-review.yaml b/.github/workflows/claude-code-review.yaml new file mode 100644 index 00000000..da0b6b59 --- /dev/null +++ b/.github/workflows/claude-code-review.yaml @@ -0,0 +1,203 @@ +# Sample Claude Code Review Workflow +# +# This is a template workflow that demonstrates how to set up automated code reviews +# using Claude via GitHub Actions. Customize the prompt and focus areas for your project. +# +# To use this workflow: +# 1. Use Claude Code command in your terminal: /install-github-app , this holds your hand throughout the setup +# 2. Copy this file over to your repository's .github/workflows/claude-code-review.yml , which gets auto-generated +# 3. Add ANTHROPIC_API_KEY to your repository secrets +# 4. Customize the prompt section for your project's specific needs +# 5. Adjust the focus areas, tools, and model as needed + +name: Claude Code Review - BMAD Method + +on: + pull_request: + types: [opened, synchronize, ready_for_review, reopened] + +# if this branch is pushed back to back, cancel the older branch's workflow +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} + cancel-in-progress: true + +jobs: + claude-review: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + issues: read + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code Review + id: claude-review + uses: anthropics/claude-code-action@v1 + with: + # Using API key for per-token billing plan + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + + # Track progress creates a comment showing review progress + track_progress: true + + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + # BMAD-METHOD Repository - AI Agent Framework + + IMPORTANT: Skip reviewing files in these directories: + - docs/ (user-facing documentation) + - bmad/ (compiled installation output, not source) + - test/fixtures/ (test data files) + - node_modules/ (dependencies) + + **Context:** This is BMAD-CORE, a universal human-AI collaboration framework with YAML-based agent definitions and XML-tagged workflow instructions. + + Perform comprehensive code review focusing on BMAD-specific patterns: + + ## 1. Agent YAML Schema Compliance (CRITICAL) + + **For files in `src/modules/*/agents/*.agent.yaml`:** + - ✅ Required fields: metadata (id, name, title, icon, module), persona (role, identity, communication_style, principles), menu items + - ✅ Menu triggers must reference valid workflow paths: `{project-root}/bmad/{module}/workflows/{path}/workflow.yaml` + - ✅ Critical actions syntax (if TEA agent): Must reference tea-index.csv and knowledge fragments + - ✅ Schema validation: Run `npm run validate:schemas` to verify compliance + - ❌ No hardcoded file paths outside {project-root} or {installed_path} + - ❌ No duplicate menu triggers within an agent + + ## 2. Workflow Definition Integrity + + **For files in `src/modules/*/workflows/**/workflow.yaml`:** + - ✅ Required fields: name, config_source, instructions, default_output_file (if template-based) + - ✅ Variable resolution: Use {config_source}, {project-root}, {installed_path}, {output_folder} + - ✅ Instructions path must exist: `{installed_path}/instructions.md` + - ✅ Template path (if template workflow): `{installed_path}/template.md` + - ❌ No absolute paths - use variable placeholders + + **For `instructions.md` files:** + - ✅ XML tag syntax: ``, ``, `section`, `` + - ✅ Steps must have sequential numbering (1, 2, 3...) + - ✅ All XML tags must close properly (e.g., ``, ``) + - ✅ Template-output tags reference actual template sections + - ❌ No malformed XML that breaks workflow execution engine + + ## 3. TEA Knowledge Base Integrity + + **For changes in `src/modules/bmm/testarch/`:** + - ✅ tea-index.csv must match knowledge/ directory (21 fragments indexed) + - ✅ Fragment file names match csv entries exactly + - ✅ TEA agent critical_actions reference tea-index.csv correctly + - ✅ Knowledge fragments maintain consistent format + - ❌ Don't break the index-fragment relationship + + ## 4. Documentation Consistency (Phase & Track Terminology) + + **For changes in `src/modules/bmm/docs/`:** + - ✅ Use 3-track terminology: Quick Flow, BMad Method, Enterprise Method (not Level 0-4) + - ✅ Phase numbering: Phase 1 (Analysis), Phase 2 (Planning), Phase 3 (Solutioning), Phase 4 (Implementation) + - ✅ TEA operates in Phase 2 and Phase 4 only (not "all phases") + - ✅ `*test-design` is per-epic in Phase 4 (not per-project in Phase 2/3) + - ❌ Don't mix YAML phase numbers (0-indexed) with doc phase numbers (1-indexed) without context + + **For changes in workflow-status YAML paths:** + - ✅ Only include phase-gate workflows (prd, architecture, sprint-planning) + - ❌ Don't include per-epic/per-story workflows (test-design, create-story, atdd, automate) + - Note: Per-epic/per-story workflows tracked in sprint-status.yaml, not workflow-status.yaml + + ## 5. Cross-Module Dependencies + + - ✅ Verify workflow invocations reference valid paths + - ✅ Module dependencies declared in installer-manifest.yaml + - ✅ Shared task references resolve correctly + - ❌ No circular dependencies between modules + + ## 6. Compilation & Installation + + **For changes affecting `tools/cli/`:** + - ✅ Agent compilation: YAML → Markdown/XML for both IDE and web bundle targets + - ✅ forWebBundle flag changes compilation behavior (inline vs file paths) + - ✅ Manifest generation creates agent-manifest.csv and workflow-manifest.csv + - ✅ Platform-specific hooks execute for IDE integrations + + ## 7. Code Quality (Node.js/JavaScript) + + - ✅ Modern JavaScript (ES6+, async/await, proper error handling) + - ✅ Schema validation with Zod where applicable + - ✅ Proper YAML parsing with js-yaml + - ✅ File operations use fs-extra for better error handling + - ❌ No synchronous file I/O in async contexts + + ## Review Guidelines + + - Reference CLAUDE.md for repository architecture + - Check CONTRIBUTING.md for contribution guidelines + - **Validation commands** (deterministic tests): + - `npm test` - Comprehensive quality checks (all validations + linting + formatting) + - `npm run test:schemas` - Agent schema validation tests (fixture-based) + - `npm run test:install` - Installation component tests (compilation) + - `npm run validate:schemas` - YAML schema validation + - `npm run validate:bundles` - Web bundle integrity + - `npm run lint` - ESLint compliance + - `npm run format:check` - Prettier formatting + - Prioritize issues: **Critical** (breaks workflows/compilation) > **High** (schema violations) > **Medium** (inconsistency) > **Low** (style) + - Be specific with file paths and line numbers + + Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR. + + # Using Sonnet 4.5 for comprehensive reviews + # Available models: claude-opus-4-1-20250805, claude-sonnet-4-5-20250929, etc. + # Tools can be restricted based on what review actions you want to allow + claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"' + + # SETUP INSTRUCTIONS +# ================== +# +# 1. Repository Secrets Setup: +# - Go to your repository � Settings � Secrets and variables � Actions +# - Click "New repository secret" +# - Name: ANTHROPIC_API_KEY +# - Value: Your Anthropic API key (get one from https://console.anthropic.com/) +# +# 2. Permissions: +# - The workflow needs 'pull-requests: write' to comment on PRs +# - The workflow needs 'contents: read' to access repository code +# - The workflow needs 'issues: read' for GitHub CLI operations +# +# 3. Customization: +# - Update the prompt section to match your project's needs +# - Add project-specific file/directory exclusions +# - Customize the focus areas based on your tech stack +# - Adjust the model (opus for more thorough reviews, sonnet for faster) +# - Modify allowed tools based on what actions you want Claude to perform +# +# 4. Testing: +# - Create a test PR to verify the workflow runs correctly +# - Check that Claude can comment on the PR +# - Ensure the review quality meets your standards +# +# 5. Advanced Customization: +# - Add conditional logic based on file types or changes +# - Integrate with other GitHub Actions (linting, testing, etc.) +# - Set up different review levels based on PR size or author +# - Add custom review templates for different types of changes +# +# TROUBLESHOOTING +# =============== +# +# Common Issues: +# - "Authentication failed" � Check ANTHROPIC_API_KEY secret +# - "Permission denied" � Verify workflow permissions in job definition +# - "No comments posted" � Check allowed tools and gh CLI permissions +# - "Review too generic" � Customize prompt with project-specific guidance +# +# For more help: +# - GitHub Actions documentation: https://docs.github.com/en/actions +# - Claude Code Action: https://github.com/anthropics/claude-code-action +# - Anthropic API documentation: https://docs.anthropic.com/ diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml deleted file mode 100644 index 6d8fab2a..00000000 --- a/.github/workflows/lint.yaml +++ /dev/null @@ -1,61 +0,0 @@ -name: lint - -"on": - pull_request: - branches: ["**"] - workflow_dispatch: - -jobs: - prettier: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node - uses: actions/setup-node@v4 - with: - node-version-file: ".nvmrc" - cache: "npm" - - - name: Install dependencies - run: npm ci - - - name: Prettier format check - run: npm run format:check - - eslint: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node - uses: actions/setup-node@v4 - with: - node-version-file: ".nvmrc" - cache: "npm" - - - name: Install dependencies - run: npm ci - - - name: ESLint - run: npm run lint - - schema-validation: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node - uses: actions/setup-node@v4 - with: - node-version-file: ".nvmrc" - cache: "npm" - - - name: Install dependencies - run: npm ci - - - name: Validate YAML schemas - run: npm run validate:schemas diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml new file mode 100644 index 00000000..7a32718b --- /dev/null +++ b/.github/workflows/quality.yaml @@ -0,0 +1,123 @@ +name: Quality & Validation + +# Runs comprehensive quality checks on all PRs: +# - Prettier (formatting) +# - ESLint (linting) +# - Schema validation (YAML structure) +# - Agent schema tests (fixture-based validation) +# - Installation component tests (compilation) +# - Bundle validation (web bundle integrity) + +"on": + pull_request: + branches: ["**"] + workflow_dispatch: + +jobs: + prettier: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Prettier format check + run: npm run format:check + + eslint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: ESLint + run: npm run lint + + schema-validation: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Validate YAML schemas + run: npm run validate:schemas + + agent-schema-tests: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Run agent schema validation tests + run: npm run test:schemas + + installation-components: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Test agent compilation components + run: npm run test:install + + bundle-validation: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: Validate web bundles + run: npm run validate:bundles diff --git a/.gitignore b/.gitignore index e55e43e0..9eff8ef1 100644 --- a/.gitignore +++ b/.gitignore @@ -34,7 +34,7 @@ Thumbs.db .bmad*/.cursor/ # AI assistant files -# CLAUDE.md # we need this for Claude Code reviews +CLAUDE.md .ai/* cursor .gemini diff --git a/.husky/pre-commit b/.husky/pre-commit index 7e617c2c..1397d511 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,3 +1,7 @@ #!/usr/bin/env sh +# Auto-fix changed files and stage them npx --no-install lint-staged + +# Validate everything +npm test diff --git a/README.md b/README.md index e9151d4e..d9e8c690 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,15 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo - [C.O.R.E. Philosophy](#core-philosophy) - [Modules](#modules) - [BMad Method (BMM) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development) + - [v6 Highlights](#v6-highlights) + - [🚀 Quick Start](#-quick-start) - [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions) - [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity) - - [🚀 Quick Start](#-quick-start) - [Installation](#installation) - [🎯 Working with Agents \& Commands](#-working-with-agents--commands) + - [Method 1: Agent Menu (Recommended for Beginners)](#method-1-agent-menu-recommended-for-beginners) + - [Method 2: Direct Slash Commands](#method-2-direct-slash-commands) + - [Method 3: Party Mode Execution](#method-3-party-mode-execution) - [Key Features](#key-features) - [🎨 Update-Safe Customization](#-update-safe-customization) - [🚀 Intelligent Installation](#-intelligent-installation) @@ -47,6 +51,10 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo - [📄 Document Sharding (Advanced)](#-document-sharding-advanced) - [Documentation](#documentation) - [Community \& Support](#community--support) + - [Development \& Quality Checks](#development--quality-checks) + - [Testing \& Validation](#testing--validation) + - [Code Quality](#code-quality) + - [Build \& Development](#build--development) - [Contributing](#contributing) - [License](#license) @@ -352,6 +360,56 @@ Optional optimization for large projects (BMad Method and Enterprise tracks): --- +## Development & Quality Checks + +**For contributors working on the BMAD codebase:** + +**Requirements:** Node.js 22+ (see `.nvmrc`). Run `nvm use` to switch to the correct version. + +### Testing & Validation + +```bash +# Run all quality checks (comprehensive - use before pushing) +npm test + +# Individual test suites +npm run test:schemas # Agent schema validation (fixture-based) +npm run test:install # Installation component tests (compilation) +npm run validate:schemas # YAML schema validation +npm run validate:bundles # Web bundle integrity +``` + +### Code Quality + +```bash +# Lint check +npm run lint + +# Auto-fix linting issues +npm run lint:fix + +# Format check +npm run format:check + +# Auto-format all files +npm run format:fix +``` + +### Build & Development + +```bash +# Bundle for web deployment +npm run bundle + +# Test local installation +npm run install:bmad +``` + +**Pre-commit Hook:** Auto-fixes changed files (lint-staged) + validates everything (npm test) +**CI:** GitHub Actions runs all quality checks in parallel on every PR + +--- + ## Contributing We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for: diff --git a/package-lock.json b/package-lock.json index 4de233c1..c7a06422 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bmad-method", - "version": "6.0.0-alpha.5", + "version": "6.0.0-alpha.6", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "bmad-method", - "version": "6.0.0-alpha.5", + "version": "6.0.0-alpha.6", "license": "MIT", "dependencies": { "@kayvan/markdown-tree-parser": "^1.6.1", diff --git a/package.json b/package.json index eb9a75c0..41f56180 100644 --- a/package.json +++ b/package.json @@ -39,8 +39,10 @@ "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor", "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch", "release:watch": "gh run watch", - "test": "node test/test-agent-schema.js", - "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js", + "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check", + "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas", + "test:install": "node test/test-installation-components.js", + "test:schemas": "node test/test-agent-schema.js", "validate:bundles": "node tools/validate-bundles.js", "validate:schemas": "node tools/validate-agent-schema.js" }, diff --git a/test/test-installation-components.js b/test/test-installation-components.js new file mode 100644 index 00000000..464ca613 --- /dev/null +++ b/test/test-installation-components.js @@ -0,0 +1,214 @@ +/** + * Installation Component Tests + * + * Tests individual installation components in isolation: + * - Agent YAML → XML compilation + * - Manifest generation + * - Path resolution + * - Customization merging + * + * These are deterministic unit tests that don't require full installation. + * Usage: node test/test-installation-components.js + */ + +const path = require('node:path'); +const fs = require('fs-extra'); +const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder'); +const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator'); + +// ANSI colors +const colors = { + reset: '\u001B[0m', + green: '\u001B[32m', + red: '\u001B[31m', + yellow: '\u001B[33m', + cyan: '\u001B[36m', + dim: '\u001B[2m', +}; + +let passed = 0; +let failed = 0; + +/** + * Test helper: Assert condition + */ +function assert(condition, testName, errorMessage = '') { + if (condition) { + console.log(`${colors.green}✓${colors.reset} ${testName}`); + passed++; + } else { + console.log(`${colors.red}✗${colors.reset} ${testName}`); + if (errorMessage) { + console.log(` ${colors.dim}${errorMessage}${colors.reset}`); + } + failed++; + } +} + +/** + * Test Suite + */ +async function runTests() { + console.log(`${colors.cyan}========================================`); + console.log('Installation Component Tests'); + console.log(`========================================${colors.reset}\n`); + + const projectRoot = path.join(__dirname, '..'); + + // ============================================================ + // Test 1: YAML → XML Agent Compilation (In-Memory) + // ============================================================ + console.log(`${colors.yellow}Test Suite 1: Agent Compilation${colors.reset}\n`); + + try { + const builder = new YamlXmlBuilder(); + const pmAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/pm.agent.yaml'); + + // Create temp output path + const tempOutput = path.join(__dirname, 'temp-pm-agent.md'); + + try { + const result = await builder.buildAgent(pmAgentPath, null, tempOutput, { includeMetadata: true }); + + assert(result && result.outputPath === tempOutput, 'Agent compilation returns result object with outputPath'); + + // Read the output + const compiled = await fs.readFile(tempOutput, 'utf8'); + + assert(compiled.includes(' tag'); + + assert(compiled.includes(''), 'Compiled agent contains tag'); + + assert(compiled.includes(''), 'Compiled agent contains tag'); + + assert(compiled.includes('Product Manager'), 'Compiled agent contains agent title'); + + // Cleanup + await fs.remove(tempOutput); + } catch (error) { + assert(false, 'Agent compilation succeeds', error.message); + } + } catch (error) { + assert(false, 'YamlXmlBuilder instantiates', error.message); + } + + console.log(''); + + // ============================================================ + // Test 2: Customization Merging + // ============================================================ + console.log(`${colors.yellow}Test Suite 2: Customization Merging${colors.reset}\n`); + + try { + const builder = new YamlXmlBuilder(); + + // Test deepMerge function + const base = { + agent: { + metadata: { name: 'John', title: 'PM' }, + persona: { role: 'Product Manager', style: 'Analytical' }, + }, + }; + + const customize = { + agent: { + metadata: { name: 'Sarah' }, // Override name only + persona: { style: 'Concise' }, // Override style only + }, + }; + + const merged = builder.deepMerge(base, customize); + + assert(merged.agent.metadata.name === 'Sarah', 'Deep merge overrides customized name'); + + assert(merged.agent.metadata.title === 'PM', 'Deep merge preserves non-overridden title'); + + assert(merged.agent.persona.role === 'Product Manager', 'Deep merge preserves non-overridden role'); + + assert(merged.agent.persona.style === 'Concise', 'Deep merge overrides customized style'); + } catch (error) { + assert(false, 'Customization merging works', error.message); + } + + console.log(''); + + // ============================================================ + // Test 3: Path Resolution + // ============================================================ + console.log(`${colors.yellow}Test Suite 3: Path Variable Resolution${colors.reset}\n`); + + try { + const builder = new YamlXmlBuilder(); + + // Test path resolution logic (if exposed) + // This would test {project-root}, {installed_path}, {config_source} resolution + + const testPath = '{project-root}/bmad/bmm/config.yaml'; + const expectedPattern = /\/bmad\/bmm\/config\.yaml$/; + + assert( + true, // Placeholder - would test actual resolution + 'Path variable resolution pattern matches expected format', + 'Note: This test validates path resolution logic exists', + ); + } catch (error) { + assert(false, 'Path resolution works', error.message); + } + + console.log(''); + + // ============================================================ + // Test 5: TEA Agent Special Handling + // ============================================================ + console.log(`${colors.yellow}Test Suite 5: TEA Agent Compilation${colors.reset}\n`); + + try { + const builder = new YamlXmlBuilder(); + const teaAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/tea.agent.yaml'); + const tempOutput = path.join(__dirname, 'temp-tea-agent.md'); + + try { + const result = await builder.buildAgent(teaAgentPath, null, tempOutput, { includeMetadata: true }); + const compiled = await fs.readFile(tempOutput, 'utf8'); + + assert(compiled.includes('tea-index.csv'), 'TEA agent compilation includes critical_actions with tea-index.csv reference'); + + assert(compiled.includes('testarch/knowledge'), 'TEA agent compilation includes knowledge base path'); + + assert(compiled.includes('*test-design'), 'TEA agent menu includes test-design workflow'); + + // Cleanup + await fs.remove(tempOutput); + } catch (error) { + assert(false, 'TEA agent compiles successfully', error.message); + } + } catch (error) { + assert(false, 'TEA compilation test setup', error.message); + } + + console.log(''); + + // ============================================================ + // Summary + // ============================================================ + console.log(`${colors.cyan}========================================`); + console.log('Test Results:'); + console.log(` Passed: ${colors.green}${passed}${colors.reset}`); + console.log(` Failed: ${colors.red}${failed}${colors.reset}`); + console.log(`========================================${colors.reset}\n`); + + if (failed === 0) { + console.log(`${colors.green}✨ All installation component tests passed!${colors.reset}\n`); + process.exit(0); + } else { + console.log(`${colors.red}❌ Some installation component tests failed${colors.reset}\n`); + process.exit(1); + } +} + +// Run tests +runTests().catch((error) => { + console.error(`${colors.red}Test runner failed:${colors.reset}`, error.message); + console.error(error.stack); + process.exit(1); +});