From 4fe225feac9eb488ef565972a9b1a1e126f83c8f Mon Sep 17 00:00:00 2001 From: Gabriel Tauber Date: Wed, 22 Oct 2025 15:20:17 -0300 Subject: [PATCH] docs: update for v6-alpha workflow changes - Replace *plan-project with *prd, *tech-spec, and *gdd across 15 files - Add sprint-status documentation for Level 4 projects - Update workflow diagrams and examples throughout - Document two-tier status tracking system (workflow-status vs sprint-status) - Add consistency for prd/tech-spec alternatives in testarch docs Closes #811 Resolves documentation discrepancies introduced in commits: - b8db080 (architecture name standardization) - 419043e (sprint planning) - ddaefa3 (sprint plan for level 4) --- README.md | 18 +++++++++--- src/modules/bmm/README.md | 29 ++++++++++++++++--- src/modules/bmm/testarch/README.md | 26 ++++++++--------- .../brainstorm-game/instructions.md | 2 +- .../brainstorm-project/instructions.md | 2 +- .../document-project/instructions.md | 2 +- .../1-analysis/game-brief/instructions.md | 2 +- .../1-analysis/product-brief/instructions.md | 2 +- .../research/instructions-deep-prompt.md | 4 +-- .../research/instructions-market.md | 4 +-- .../research/instructions-technical.md | 4 +-- .../2-plan-workflows/ux/instructions-ux.md | 2 +- src/modules/bmm/workflows/README.md | 10 ++++--- .../workflows/testarch/framework/README.md | 2 +- .../workflows/testarch/test-design/README.md | 2 +- 15 files changed, 72 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 167cae0b..6108475b 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,9 @@ The BMM module follows a comprehensive four-phase methodology. Each phase adapts **PM Agent**: -- `plan-project` - Creates scale-adaptive PRD or GDD +- `prd` - Creates Product Requirements Document for Level 2-4 projects +- `tech-spec` - Creates Technical Specification for Level 0-1 projects +- `gdd` - Creates Game Design Document for game projects (via Game Designer agent) The planning workflow adapts to: @@ -239,10 +241,18 @@ The planning workflow adapts to: **Scrum Master (SM) Agent**: -Before development starts, the SM prepares each story: +Before development starts: -1. `create-story` - Generates story from tech spec and context -2. `story-context` - **πŸŽ‰ NEW!** Game-changing contextual preparation +1. **Level 4 Projects Only**: Run `sprint-planning` workflow + - Generates `sprint-status.yaml` from epic files + - Tracks all epics and stories through implementation + - Auto-detects current status based on files + - Provides single source of truth for Phase 4 progress + +Then, for each story, the SM prepares: + +2. `create-story` - Generates story from tech spec and context +3. `story-context` - **πŸŽ‰ NEW!** Game-changing contextual preparation - Real-time context gathering for the specific story - No more generic file lists - Supercharged, specialized development context diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md index 5951903d..4292ce82 100644 --- a/src/modules/bmm/README.md +++ b/src/modules/bmm/README.md @@ -31,14 +31,30 @@ The heart of BMM - structured workflows for the four development phases: - `product-brief` - Product strategy 2. **Planning Phase** (Required) - - `plan-project` - Scale-adaptive project planning + - `prd` - Product Requirements Document (Level 2-4) + - `tech-spec` - Technical Specification (Level 0-1) - Routes to appropriate documentation based on project complexity 3. **Solutioning Phase** (Level 3-4 projects) - `3-solutioning` - Architecture design - `tech-spec` - Epic-specific technical specifications -4. **Implementation Phase** (Iterative) +### Status Tracking in BMM + +BMM uses two complementary status systems: + +1. **workflow-status.md** (Phases 1-3) + - Tracks progress through Analysis, Planning, and Solutioning + - Used by `*workflow-init` and `*workflow-status` commands + - Single source of truth for project configuration + +2. **sprint-status.yaml** (Phase 4 - Level 4 only) + - Tracks implementation progress for complex projects + - Generated by `*sprint-planning` workflow + - Maintains epic and story status throughout development + - Auto-detects status based on file existence + +3. **Implementation Phase** (Iterative) - `create-story` - Story drafting (SM agent) - `story-ready` - Approve story for development (SM agent) - `story-context` - Expertise injection (SM agent) @@ -68,8 +84,13 @@ Test architecture and quality assurance components. The **[Test Architect (TEA) ```bash # Load the PM agent - either via slash command or drag and drop or @ the agent file. -# Once loaded, the agent should greet you and offer a menu of options. You can enter: -`*plan-project` +# Once loaded, the agent should greet you and offer a menu of options. + +# For Level 2-4 projects: +`*prd` + +# For Level 0-1 projects: +`*tech-spec` ``` ## Key Concepts diff --git a/src/modules/bmm/testarch/README.md b/src/modules/bmm/testarch/README.md index 0f858bc3..b5d6a7c4 100644 --- a/src/modules/bmm/testarch/README.md +++ b/src/modules/bmm/testarch/README.md @@ -1,5 +1,5 @@ --- -last-redoc-date: 2025-10-14 +last-redoc-date: 2025-10-22 --- # Test Architect (TEA) Agent Guide @@ -18,7 +18,7 @@ TEA integrates across the entire BMad development lifecycle, providing quality a β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ BMM Phase 2: PLANNING β”‚ β”‚ β”‚ -β”‚ PM: *plan-project β”‚ +β”‚ PM: *prd or *tech-spec β”‚ β”‚ ↓ β”‚ β”‚ TEA: *framework ──→ *ci ──→ *test-design β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ @@ -105,7 +105,7 @@ This complexity **requires specialized documentation** (this guide), **extensive 1. Run the core planning workflows first: - Analyst `*product-brief` - - Product Manager `*plan-project` + - Product Manager `*prd` (Level 2-4) or `*tech-spec` (Level 0-1) - 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. @@ -116,14 +116,14 @@ This complexity **requires specialized documentation** (this guide), **extensive ### Greenfield Feature Launch (Level 2) -| Phase | Test Architect | Dev / Team | Outputs | -| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -| Setup | - | Analyst `*product-brief`, PM `*plan-project`, 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) | +| Phase | Test Architect | Dev / Team | Outputs | +| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Setup | - | Analyst `*product-brief`, PM `*prd` or `*tech-spec`, Architect `*create-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`/`tech-spec.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 @@ -139,7 +139,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
Worked Example – β€œNova CRM” Greenfield Feature -1. **Planning:** Analyst runs `*product-brief`; PM executes `*plan-project` to produce PRD and epics; Architect completes `*create-architecture` for the new module. +1. **Planning:** Analyst runs `*product-brief`; PM executes `*prd` (or `*tech-spec` for simpler projects) 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. @@ -174,7 +174,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
Worked Example – β€œAtlas Payments” Brownfield Story -1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*plan-project` to update PRD, analysis, and `epics.md`; Architect triggers `*create-architecture` capturing legacy payment flows. +1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*prd` (or `*tech-spec`) 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. diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md index 5002f54f..795960c5 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md @@ -100,7 +100,7 @@ 2. Consider running: - `research` workflow for market/game research - `game-brief` workflow to formalize game vision - - Or proceed directly to `plan-project` if ready + - Or proceed directly to `gdd` workflow if ready {{#if standalone_mode != true}} Check status anytime with: `workflow-status` diff --git a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md index dc1013b1..887fbf06 100644 --- a/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md @@ -79,7 +79,7 @@ 2. Consider running: - `research` workflow for market/technical research - `product-brief` workflow to formalize product vision - - Or proceed directly to `plan-project` if ready + - Or proceed directly to `prd` (Level 2-4) or `tech-spec` (Level 0-1) if ready {{#if standalone_mode != true}} Check status anytime with: `workflow-status` diff --git a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md index 88693ac6..e95d94de 100644 --- a/src/modules/bmm/workflows/1-analysis/document-project/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/document-project/instructions.md @@ -43,7 +43,7 @@ {{warning}} - Note: This may be auto-invoked by plan-project for brownfield documentation. + Note: This may be auto-invoked by prd or tech-spec for brownfield documentation. Continue with documentation? (y/n) {{suggestion}} diff --git a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md index 35317a63..e6909cc9 100644 --- a/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/game-brief/instructions.md @@ -340,7 +340,7 @@ This brief will serve as the primary input for creating the Game Design Document 1. Review the game brief document 2. Consider creating a prototype of core mechanic -3. Run `plan-project` workflow to create GDD from this brief +3. Run `gdd` workflow to create GDD from this brief 4. Validate assumptions with target players {{#if standalone_mode != true}} diff --git a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md index 9312ec97..a284048f 100644 --- a/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md +++ b/src/modules/bmm/workflows/1-analysis/product-brief/instructions.md @@ -304,7 +304,7 @@ This brief will serve as the primary input for creating the Product Requirements 1. Review the product brief document 2. Gather any additional stakeholder input -3. Run `plan-project` workflow to create PRD from this brief +3. Run `prd` workflow to create PRD from this brief (Level 2-4 projects) {{#if standalone_mode != true}} Check status anytime with: `workflow-status` diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md index 8e832167..511374de 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md @@ -405,7 +405,7 @@ Select option (1-4): 1. Execute the research prompt with your chosen AI platform 2. Gather and analyze findings -3. Run `plan-project` to incorporate findings +3. Run `prd` or `tech-spec` to incorporate findings Check status anytime with: `workflow-status` @@ -423,7 +423,7 @@ Note: Running in standalone mode (no status file). **Next Steps:** 1. Execute the research prompt with AI platform -2. Run plan-project workflow +2. Run prd or tech-spec workflow diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md index 748a81e0..e9512926 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-market.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-market.md @@ -587,7 +587,7 @@ Create compelling executive summary with: 2. Share with stakeholders 3. Consider running: - `product-brief` or `game-brief` to formalize vision - - `plan-project` if ready to create PRD/GDD + - `prd` (software Level 2-4) or `gdd` (games) if ready to create PRD/GDD Check status anytime with: `workflow-status` @@ -607,7 +607,7 @@ To track progress across workflows, run `workflow-status` first. **Next Steps:** 1. Review research findings -2. Run product-brief or plan-project workflows +2. Run product-brief, prd, or gdd workflows diff --git a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md index 2078c4e9..4061cbdc 100644 --- a/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md +++ b/src/modules/bmm/workflows/1-analysis/research/instructions-technical.md @@ -473,7 +473,7 @@ Select option (1-5): 1. Review technical research findings 2. Share with architecture team -3. Run `plan-project` to incorporate findings into PRD +3. Run `prd` workflow to incorporate findings into PRD (Level 2-4) Check status anytime with: `workflow-status` @@ -491,7 +491,7 @@ Note: Running in standalone mode (no status file). **Next Steps:** 1. Review technical research findings -2. Run plan-project workflow +2. Run prd or tech-spec workflow diff --git a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md index 10bf8a73..df122fe8 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md +++ b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md @@ -6,7 +6,7 @@ You MUST have already loaded and processed: {installed_path}/workflow.yaml Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level} Generate all documents in {document_output_language} -This workflow creates comprehensive UX/UI specifications - can run standalone or as part of plan-project +This workflow creates comprehensive UX/UI specifications - can run standalone or as part of prd workflow Uses ux-spec-template.md for structured output generation Can optionally generate AI Frontend Prompts for tools like Vercel v0, Lovable.ai diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md index f1f228c2..fbe50bf5 100644 --- a/src/modules/bmm/workflows/README.md +++ b/src/modules/bmm/workflows/README.md @@ -1,5 +1,5 @@ --- -last-redoc-date: 2025-10-12 +last-redoc-date: 2025-10-22 --- # BMM Workflows - The Complete v6 Flow @@ -32,7 +32,7 @@ The BMM (BMAD Method Module) orchestrates software development through four dist β”‚ PHASE 2: PLANNING β”‚ β”‚ (Scale-Adaptive Router - by type) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ SOFTWARE: plan-project GAMES: gdd β”‚ +β”‚ SOFTWARE: prd (L2-4) / tech-spec (L0-1) GAMES: gdd β”‚ β”‚ β”œβ”€β”€β†’ Level 0: tech-spec only β”œβ”€β”€β†’ GDD (all levels) β”‚ β”‚ β”œβ”€β”€β†’ Level 1: tech-spec only └──→ Narrative design β”‚ β”‚ β”œβ”€β”€β†’ Level 2: PRD + tech-spec β”‚ @@ -52,6 +52,8 @@ The BMM (BMAD Method Module) orchestrates software development through four dist β”‚ PHASE 4: IMPLEMENTATION β”‚ β”‚ (Iterative Cycle) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ [Level 4 only] sprint-planning ──→ creates sprint-status.yamlβ”‚ +β”‚ ↓ β”‚ β”‚ β”Œβ”€β†’ create-story ──→ story-context ──→ dev-story ──┐ β”‚ β”‚ β”‚ ↓ β”‚ β”‚ β”‚ retrospective ←── [epic done] ←────── review-story β”‚ @@ -358,7 +360,7 @@ Status: Done (User approved via story-done, DoD complete) ### Brownfield Projects ``` -plan-project (Phase 2) +Phase 2 Planning (prd or tech-spec based on level) β”œβ”€β†’ Check: Is existing codebase documented? β”‚ β”œβ”€β†’ YES: Proceed with planning β”‚ └─→ NO: HALT with message: @@ -454,7 +456,7 @@ plan-project (Phase 2) | Creating all tech specs upfront | Use JIT approach - one epic at a time | | Skipping story-context generation | Always run after create-story | | Batching story creation | Create one story at a time | -| Ignoring scale levels | Let plan-project determine level | +| Ignoring scale levels | Use prd for L2-4, tech-spec for L0-1 | | Planning brownfield without docs | Run brownfield-analysis first | | Not running retrospectives | Schedule after every epic | diff --git a/src/modules/bmm/workflows/testarch/framework/README.md b/src/modules/bmm/workflows/testarch/framework/README.md index f8fe8307..b19a529a 100644 --- a/src/modules/bmm/workflows/testarch/framework/README.md +++ b/src/modules/bmm/workflows/testarch/framework/README.md @@ -130,7 +130,7 @@ Automatically consults TEA knowledge base: **Before framework:** -- **plan-project** (Phase 2): Determines project scope and testing needs +- **prd** or **tech-spec** (Phase 2): Determines project scope and testing needs - **workflow-status**: Verifies project readiness **After framework:** diff --git a/src/modules/bmm/workflows/testarch/test-design/README.md b/src/modules/bmm/workflows/testarch/test-design/README.md index 1363b287..49a6e6ad 100644 --- a/src/modules/bmm/workflows/testarch/test-design/README.md +++ b/src/modules/bmm/workflows/testarch/test-design/README.md @@ -304,7 +304,7 @@ Automatically consults TEA knowledge base: **Before test-design:** -- **plan-project** (Phase 2): Creates PRD and epics +- **prd** or **tech-spec** (Phase 2): Creates PRD/epics (Level 2-4) or tech-spec (Level 0-1) - **architecture** (Phase 3): Defines technical approach - **tech-spec** (Phase 3): Implementation details