Merge 02f2955c09 into a50d82df1c

- Add BUG-TRACKING.md to gitignore for fork-specific documentation
- Improve implement workflow doc update tasks with return instructions
  - PRD, architecture, and UX update tasks now remind to return to /implement
  - Ensures implementation proceeds after doc updates complete

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -71,3 +71,6 @@ bmad-custom-src/
 website/.astro/
 website/dist/
 build/
+
+# Fork-specific documentation (not committed)
+BUG-TRACKING.md

docs/bug-tracking/bug-tracking-workflow-README.md

@@ -0,0 +1,536 @@
+# Bug Tracking Workflow Wireframe
+
+## Quick Reference
+
+```
+COMMANDS:
+  /triage              - Triage new bugs from bugs.md
+  /implement bug-NNN   - Implement a bug fix
+  /implement feature-N - Implement a feature
+  /verify              - List pending verification
+  /verify bug-NNN      - Verify and close specific bug
+  /verify all          - Batch verify all
+
+FILES:
+  docs/bugs.md         - Human-readable bug tracking
+  docs/bugs.yaml       - Agent-readable metadata
+
+SEVERITY → COMPLEXITY → WORKFLOW ROUTING:
+  ┌──────────┬─────────┬─────────┬─────────┬─────────┐
+  │          │ TRIVIAL │ SMALL   │ MEDIUM  │ COMPLEX │
+  ├──────────┼─────────┼─────────┼─────────┼─────────┤
+  │ CRITICAL │ correct-course (any complexity)       │
+  ├──────────┼─────────┼─────────┼─────────┼─────────┤
+  │ HIGH     │direct-fx│tech-spec│corr-crs │corr-crs │
+  ├──────────┼─────────┼─────────┼─────────┼─────────┤
+  │ MEDIUM   │direct-fx│tech-spec│corr-crs │corr-crs │
+  ├──────────┼─────────┼─────────┼─────────┼─────────┤
+  │ LOW      │direct-fx│ backlog │ backlog │ backlog │
+  └──────────┴─────────┴─────────┴─────────┴─────────┘
+
+SEVERITY:
+  critical - Core broken, crashes, data loss
+  high     - Major feature blocked, workaround exists
+  medium   - Partial breakage, minor impact
+  low      - Cosmetic, edge case
+
+COMPLEXITY:
+  trivial  - One-liner, minimal change
+  small    - Single file change
+  medium   - Multi-file change
+  complex  - Architectural change
+
+STATUS FLOW:
+  reported → triaged → [routed] → in-progress → fixed/implemented → verified → closed
+
+STATUS VALUES:
+  triaged      - Analyzed, routed, awaiting implementation
+  routed       - Sent to tech-spec or correct-course workflow
+  in-progress  - Developer actively working
+  fixed        - Code complete, awaiting verification (bugs)
+  implemented  - Code complete, awaiting verification (features)
+  closed       - Verified and closed
+  backlog      - Deferred to future sprint
+  blocked      - Cannot proceed until issue resolved
+```
+
+---
+
+## Part 1: System Architecture
+
+### System Overview
+
+```
+                              INPUT SOURCES
+  +-------------------+     +-------------------+     +-------------------+
+  |   IN-APP MODAL    |     |   MANUAL ENTRY    |     |  EXTERNAL ISSUE   |
+  |   (Optional API)  |     |   (bugs.md)       |     |  TRACKER IMPORT   |
+  +--------+----------+     +--------+----------+     +--------+----------+
+           |                         |                         |
+           +------------+------------+-------------------------+
+                        |
+                        v
+           +============================+
+           |     /triage (WORKFLOW)     |
+           +============================+
+                        |
+        +---------------+---------------+---------------+
+        |               |               |               |
+        v               v               v               v
+   direct-fix      tech-spec     correct-course     backlog
+        |               |               |               |
+        v               v               v               v
+   /implement      /tech-spec     /correct-course   (deferred)
+        |               |               |
+        +---------------+---------------+
+                        |
+                        v
+                   /verify → CLOSED
+```
+
+### File Architecture
+
+```
+{project-root}/
+  docs/
+    bugs.md              <-- User-facing: informal bug reports & tracking
+    bugs.yaml            <-- Agent-facing: structured metadata database
+    epics.md             <-- Context: for mapping bugs to stories
+  _bmad/bmm/
+    config.yaml          <-- Project configuration
+    workflows/
+      bug-tracking/      <-- Triage workflow files
+      implement/         <-- Implementation workflow
+      verify/            <-- Verification workflow
+```
+
+### bugs.md Structure
+
+```markdown
+# Bug Tracking - {project_name}
+
+# manual input
+## Bug: Login fails on iOS Safari
+Description of the bug...
+Reported by: User Name
+Date: 2025-01-15
+
+- **Crash on startup (Android)**: App crashes immediately. CRITICAL.
+
+1. Form validation missing - No validation on email field
+
+---
+
+# Tracked Bugs
+### bug-001: Login fails on iOS Safari
+Brief description...
+- **Severity:** high
+- **Complexity:** small
+- **Workflow:** tech-spec
+- **Related:** story-2-3
+**Notes:** Triage reasoning...
+
+---
+
+# Tracked Feature Requests
+### feature-001: Dark mode toggle
+Brief description...
+- **Priority:** medium
+- **Complexity:** medium
+- **Workflow:** tech-spec
+
+---
+
+# Fixed Bugs
+[IMPLEMENTED] bug-003: Header alignment [Sev: low, Fixed: 2025-01-18, Verified: pending]
+  - Fix: Adjusted flexbox styling
+  - File(s): src/components/Header.tsx
+
+bug-002: Form submission error [Sev: medium, Fixed: 2025-01-15, Verified: 2025-01-16, CLOSED]
+  - Fix: Added error boundary
+
+---
+
+# Implemented Features
+[IMPLEMENTED] feature-002: Export to CSV [Impl: 2025-01-20, Verified: pending]
+  - Files: src/export.ts, src/utils/csv.ts
+```
+
+---
+
+## Part 2: Workflow Operations
+
+### Slash Command Reference
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `/triage` | Main workflow - triage user-reported bugs | When new bugs are in bugs.md |
+| `/implement bug-NNN` | Implement a specific bug fix | After triage, routed for direct-fix |
+| `/implement feature-NNN` | Implement a feature request | After feature is triaged |
+| `/verify` | List all pending verification | After implementation, before closing |
+| `/verify bug-NNN` | Verify and close specific bug | After testing confirms fix works |
+| `/verify all` | Batch verify all pending items | Bulk close multiple fixes |
+
+### /triage Workflow
+
+```
+USER INVOKES: /triage
+         |
+         v
++---------------------------+
+| STEP 1: INITIALIZATION    |
++---------------------------+
+| - Load config.yaml        |
+| - Check for bugs.yaml     |
+| - Detect existing session |
++------------+--------------+
+             |
+    +--------+--------+
+    |                 |
+    v                 v
++-------------+   +-------------+
+| Has pending |   | Fresh start |
+| triaged work|   +------+------+
++------+------+          |
+       |                 v
+       v          +-------------+
++-------------+   | Scan manual |
+| Show status |   | input section|
+| [T/I/V/L/Q] |   +------+------+
++-------------+          |
+                         v
+                  +-------------+
+                  | [S/C/Q]     |
+                  | Sync/Cont/Q |
+                  +------+------+
+                         |
+         +---------------+---------------+
+         v               v               v
+    [S] API Sync    [C] Continue    [Q] Quit
+
++---------------------------+
+| STEP 2: API SYNC          |  (Optional - if [S] selected)
++---------------------------+
+| GET /api/bug-reports/pending
+| - Fetch, format, insert to bugs.md
+| - POST /mark-synced
++---------------------------+
+
++---------------------------+
+| STEP 3: PARSE             |
++---------------------------+
+| Read "# manual input" only
+| - Parse headers, bullets, numbered lists
+| - Extract: title, desc, reporter, platform
+| - Compare with bugs.yaml (NEW vs EXISTING)
++------------+--------------+
+             |
+    +--------+--------+
+    v                 v
+No new bugs      {N} new bugs
+   [HALT]        [C] Continue
+                      |
+                      v
++---------------------------+
+| STEP 4: TRIAGE (per bug)  |
++---------------------------+
+| FOR EACH NEW BUG:
+| 1. Generate bug-NNN ID
+| 2. Assess SEVERITY (critical|high|med|low)
+| 3. Assess COMPLEXITY (trivial|small|med|complex)
+| 4. Apply ROUTING MATRIX → workflow
+| 5. Map to story/epic if applicable
+| 6. Assess DOC IMPACT (prd|architecture|ux)
+| 7. Add triage notes
+| 8. Present: [A]ccept/[M]odify/[S]kip/[N]ext
++---------------------------+
+             |
+             v (after all bugs)
++---------------------------+
+| STEP 5: UPDATE FILES      |
++---------------------------+
+| bugs.yaml: Add entries, update stats
+| bugs.md: Remove from manual input,
+|          Add to Tracked Bugs/Features
++---------------------------+
+             |
+             v
++---------------------------+
+| STEP 6: COMPLETE          |
++---------------------------+
+| Show summary + next steps:
+| /implement bug-NNN
+| /verify bug-NNN
++---------------------------+
+```
+
+### /implement Workflow
+
+```
+USER INVOKES: /implement bug-NNN
+                    |
+                    v
+    +-------------------------------+
+    | STEP 1-2: Load Context        |
+    +-------------------------------+
+    | - Parse ID (bug-NNN/feature-NNN)
+    | - Load from bugs.yaml
+    | - Check status (halt if backlog/blocked/deferred)
+    +---------------+---------------+
+                    |
+                    v
+    +-------------------------------+
+    | STEP 3: Check Workflow Route  |
+    +-------------------------------+
+                    |
+        +-----------+-----------+-----------+
+        v           v           v           v
+   correct-    tech-spec   direct-fix   ambiguous
+   course                                   |
+       |           |           |        Apply Matrix
+       v           v           |
+   [ROUTES TO  [ROUTES TO      |
+   /correct-   /tech-spec      |
+    course]     workflow]      |
+       |           |           |
+       v           v           v
+   Creates     Creates    +--------+
+   story       spec       | STEP 4:|
+                          | Confirm|
+                          +---+----+
+                              |
+                              v
+                      +---------------+
+                      | STEP 5:       |
+                      | IMPLEMENT     |
+                      +---------------+
+                      | Dev Agent:    |
+                      | - Read files  |
+                      | - Make changes|
+                      | - Minimal fix |
+                      +-------+-------+
+                              |
+                              v
+                      +---------------+
+                      | STEP 6: Check |
+                      | npm run check |
+                      +-------+-------+
+                              |
+                              v
+                      +---------------+
+                      | STEP 7-8:     |
+                      | Update Files  |
+                      +---------------+
+                      | bugs.yaml:    |
+                      |  status: fixed|
+                      | bugs.md:      |
+                      |  [IMPLEMENTED]|
+                      +-------+-------+
+                              |
+                              v
+                      +---------------+
+                      | STEP 9:       |
+                      | "Run /verify" |
+                      +---------------+
+```
+
+### /verify Workflow
+
+```
+USER INVOKES: /verify [bug-NNN]
+                    |
+        +-----------+-----------+
+        v                       v
++---------------+       +---------------+
+| No ID given   |       | ID provided   |
++-------+-------+       +-------+-------+
+        |                       |
+        v                       |
++---------------+               |
+| List pending  |               |
+| [IMPLEMENTED] |               |
+| items         |               |
++-------+-------+               |
+        |                       |
+        +-------+---------------+
+                |
+                v
++-------------------------------+
+| STEP 2: Load & Validate       |
++-------------------------------+
+| - Verify status: fixed/implemented
+| - Check file sync
++---------------+---------------+
+                |
+                v
++-------------------------------+
+| STEP 3: Confirm Verification  |
++-------------------------------+
+| Show: Title, type, date, files
+| "Has this been tested?"
+| [yes | no | skip]
++---------------+---------------+
+                |
+    +-----------+-----------+
+    v           v           v
++-------+   +-------+   +-------+
+| YES   |   | NO    |   | SKIP  |
++---+---+   +---+---+   +---+---+
+    |           |           |
+    v           v           v
+Step 4      Add note    Next item
+            "rework"
+
++-------------------------------+
+| STEP 4-5: Update Files        |
++-------------------------------+
+| bugs.yaml: status: closed,
+|            verified_date
+| bugs.md: Remove [IMPLEMENTED],
+|          Add CLOSED tag
++-------------------------------+
+                |
+                v
++-------------------------------+
+| STEP 6: Summary               |
+| "bug-NNN VERIFIED and CLOSED" |
++-------------------------------+
+```
+
+---
+
+## Part 3: Routing & Agent Delegation
+
+### Workflow Routing by Type
+
+| Workflow | Trigger Conditions | Pre-Implement Phase | Implementation Phase |
+|----------|-------------------|---------------------|---------------------|
+| **direct-fix** | high/med + trivial | None | Dev Agent in /implement Step 5 |
+| **tech-spec** | high/med + small | Architect creates spec | /dev-story per spec |
+| **correct-course** | critical (any) OR med/complex+ OR doc_impact | PM→Architect→SM create story | /dev-story per story |
+| **backlog** | low + small+ | None (deferred) | Awaits sprint promotion |
+
+### Agent Responsibilities
+
+```
+                         /triage
+                            |
+                            v
+               +------------------------+
+               |   SM AGENT (Scrum      |
+               |   Master Facilitator)  |
+               +------------------------+
+               | - Runs triage workflow |
+               | - Assesses severity    |
+               | - Routes to workflows  |
+               +-----------+------------+
+                           |
+       +-------------------+-------------------+
+       v                   v                   v
++------------+      +------------+      +------------+
+| Direct-Fix |      | Tech-Spec  |      | Correct-   |
++-----+------+      +-----+------+      | Course     |
+      |                   |             +-----+------+
+      v                   v                   |
++------------+      +------------+            v
+| DEV AGENT  |      | ARCHITECT  |      +------------+
+| /implement |      | /tech-spec |      | PM AGENT   |
+| Step 5     |      +-----+------+      | + ARCHITECT|
++------------+            |             | + SM       |
+                          v             +-----+------+
+                    +------------+            |
+                    | DEV AGENT  |            v
+                    | /dev-story |      +------------+
+                    +------------+      | DEV AGENT  |
+                                        | /dev-story |
+                                        +------------+
+```
+
+### Doc Impact Routing
+
+When `doc_impact` flags are detected during /implement:
+
+| Flag | Agent | Action |
+|------|-------|--------|
+| PRD | PM Agent | Update PRD.md |
+| Architecture | Architect Agent | Update architecture.md |
+| UX | UX Designer Agent | Update UX specs |
+
+User is prompted: `[update-docs-first | proceed-anyway | cancel]`
+
+---
+
+## Part 4: State & Lifecycle
+
+### File State Transitions
+
+```
+═══════════════════════════════════════════════════════════════════════════════
+         DIRECT-FIX        TECH-SPEC       CORRECT-COURSE      BACKLOG
+═══════════════════════════════════════════════════════════════════════════════
+
+ENTRY    # manual input     # manual input   # manual input    # manual input
+         (informal text)    (informal text)  (informal text)   (informal text)
+              │                  │                │                 │
+              ▼                  ▼                ▼                 ▼
+─────────────────────────────────────────────────────────────────────────────────
+TRIAGE   # Tracked Bugs     # Tracked Bugs   # Tracked Bugs    # Tracked Bugs
+         bug-NNN            bug-NNN          bug-NNN           bug-NNN
+         wf: direct-fix     wf: tech-spec    wf: correct-crs   wf: backlog
+              │                  │                │                 │
+              ▼                  ▼                ▼                 │
+─────────────────────────────────────────────────────────────────────────────────
+ROUTE    (skip)             /tech-spec       /correct-course   (waiting)
+                            creates spec     creates story          │
+              │                  │                │                 │
+              ▼                  ▼                ▼                 │
+─────────────────────────────────────────────────────────────────────────────────
+CODE     /implement         /dev-story       /dev-story        (waiting)
+         Step 5             per spec         per story              │
+              │                  │                │                 │
+              ▼                  ▼                ▼                 │
+─────────────────────────────────────────────────────────────────────────────────
+IMPL     # Fixed Bugs       # Fixed Bugs     # Fixed Bugs      (unchanged)
+         [IMPLEMENTED]      [IMPLEMENTED]    [IMPLEMENTED]          │
+         bug-NNN            bug-NNN          bug-NNN                │
+              │                  │                │                 │
+              ▼                  ▼                ▼                 │
+─────────────────────────────────────────────────────────────────────────────────
+VERIFY   /verify            /verify          /verify           (waiting)
+         bug-NNN            bug-NNN          bug-NNN                │
+              │                  │                │                 │
+              ▼                  ▼                ▼                 ▼
+─────────────────────────────────────────────────────────────────────────────────
+DONE     CLOSED ✓           CLOSED ✓         CLOSED ✓          WAITING ◷
+═══════════════════════════════════════════════════════════════════════════════
+
+FILE STATE SUMMARY:
+┌──────────┬─────────────────────────────┬──────────────────────────────────┐
+│ STAGE    │ bugs.md                     │ bugs.yaml                        │
+├──────────┼─────────────────────────────┼──────────────────────────────────┤
+│ Entry    │ # manual input              │ (no entry)                       │
+├──────────┼─────────────────────────────┼──────────────────────────────────┤
+│ Triage   │ → # Tracked Bugs/Features   │ status: triaged + metadata       │
+├──────────┼─────────────────────────────┼──────────────────────────────────┤
+│ Implement│ → # Fixed [IMPLEMENTED]     │ status: fixed/implemented        │
+├──────────┼─────────────────────────────┼──────────────────────────────────┤
+│ Verify   │ [IMPLEMENTED] → CLOSED      │ status: closed + verified_date   │
+└──────────┴─────────────────────────────┴──────────────────────────────────┘
+```
+
+---
+
+## Appendix: Optional Extensions
+
+### In-App Bug Reporting API
+
+Optional integration for apps with built-in bug reporting UI:
+
+1. **User submits** via in-app modal → `POST /api/bug-reports`
+2. **Database stores** with `status: 'new'`
+3. **During /triage Step 2** (if [S]ync selected):
+   - `GET /api/bug-reports/pending` fetches new reports
+   - Formats as markdown, inserts to `# manual input`
+   - `POST /api/bug-reports/mark-synced` prevents re-fetch
+
+This is optional - manual entry to bugs.md works without any API.

docs/explanation/agents/index.md

@@ -7,11 +7,10 @@ Comprehensive guides to BMad's AI agents — their roles, capabilities, and how
 
 ## Agent Guides
 
-| Agent | Description |
-|-------|-------------|
-| **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)** | Overview of all BMM agent roles and responsibilities |
-| **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** | The dedicated agent for rapid development |
-| **[Game Development Agents](/docs/explanation/game-dev/agents.md)** | Complete guide to BMGD's specialized game dev agents |
+| Agent                                                                           | Description                                          |
+| ------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| **[Agent Roles](/docs/explanation/core-concepts/agent-roles.md)**               | Overview of all BMM agent roles and responsibilities |
+| **[Quick Flow Solo Dev (Barry)](/docs/explanation/agents/barry-quick-flow.md)** | The dedicated agent for rapid development            |
 
 ## Getting Started
 

docs/explanation/core-concepts/what-are-modules.md

@@ -13,7 +13,7 @@ A module is a self-contained package that includes:
 - **Configuration** - Module-specific settings
 - **Documentation** - Usage guides and reference
 
-## Official Modules
+## Official BMad Method and Builder Modules
 
 :::note[Core is Always Installed]
 The Core module is automatically included with every BMad installation. It provides the foundation that other modules build upon.
@@ -37,17 +37,24 @@ Create custom solutions:
 - Workflow authoring tools
 - Module scaffolding
 
+## Additional Official BMad Modules
+
+These are officially maintained modules by BMad but have their own repo's and docs.
+These give a good idea also of what can be done with the BMad builder and creating your own custom modules.
+
 ### Creative Intelligence Suite (CIS)
 Innovation and creativity:
 - Creative thinking techniques
 - Innovation strategy workflows
 - Storytelling and ideation
+- [Available Here](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)
 
 ### BMad Game Dev (BMGD)
 Game development specialization:
 - Game design workflows
 - Narrative development
 - Performance testing frameworks
+- [Available Here](https://github.com/bmad-code-org/bmad-module-game-dev-studio)
 
 ## Module Structure
 

docs/explanation/core-concepts/what-are-workflows.md

@@ -163,7 +163,7 @@ Before building a workflow, answer these questions:
 
 The best way to understand workflows is to study real examples. Look at the official BMad modules:
 
-- **BMB (Module Builder)**: Workflow and agent creation workflows
+- **BMB (Module Builder)**: Module, Workflow and Agent creation workflows
 - **BMM (Business Method Module)**: Complete software development pipeline from brainstorming through sprint planning
 - **BMGD (Game Development Module)**: Game design briefs, narratives, architecture
 - **CIS (Creativity, Innovation, Strategy)**: Brainstorming, design thinking, storytelling, innovation strategy

docs/explanation/creative-intelligence/index.md

@@ -1,103 +0,0 @@
----
-title: "Creative Intelligence Suite (CIS)"
-description: AI-powered creative facilitation with the Creative Intelligence Suite
----
-
-AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
-
-## Core Capabilities
-
-CIS provides structured creative methodologies through distinctive agent personas who act as master facilitators, drawing out insights through strategic questioning rather than generating solutions directly.
-
-## Specialized Agents
-
-- **Carson** - Brainstorming Specialist (energetic facilitator)
-- **Maya** - Design Thinking Maestro (jazz-like improviser)
-- **Dr. Quinn** - Problem Solver (detective-scientist hybrid)
-- **Victor** - Innovation Oracle (bold strategic precision)
-- **Sophia** - Master Storyteller (whimsical narrator)
-
-## Interactive Workflows
-
-**5 Workflows** with **150+ Creative Techniques:**
-
-### Brainstorming
-
-36 techniques across 7 categories for ideation:
-- Divergent/convergent thinking
-- Lateral connections
-- Forced associations
-
-### Design Thinking
-
-Complete 5-phase human-centered process:
-- Empathize → Define → Ideate → Prototype → Test
-- User journey mapping
-- Rapid iteration
-
-### Problem Solving
-
-Systematic root cause analysis:
-- 5 Whys, Fishbone diagrams
-- Solution generation
-- Impact assessment
-
-### Innovation Strategy
-
-Business model disruption:
-- Blue Ocean Strategy
-- Jobs-to-be-Done
-- Disruptive innovation patterns
-
-### Storytelling
-
-25 narrative frameworks:
-- Hero's Journey
-- Story circles
-- Compelling pitch structures
-
-## Quick Start
-
-### Direct Workflow
-
-```bash
-workflow brainstorming
-
-workflow design-thinking --data /path/to/context.md
-```
-
-### Agent-Facilitated
-
-```bash
-agent cis/brainstorming-coach
-
-> *brainstorm
-```
-
-## Key Differentiators
-
-- **Facilitation Over Generation** - Guides discovery through questions
-- **Energy-Aware Sessions** - Adapts to engagement levels
-- **Context Integration** - Domain-specific guidance support
-- **Persona-Driven** - Unique communication styles
-- **Rich Method Libraries** - 150+ proven techniques
-
-## Integration Points
-
-CIS workflows integrate with:
-
-- **BMM** - Powers project brainstorming
-- **BMB** - Creative module design
-- **Custom Modules** - Shared creative resource
-
-## Best Practices
-
-1. **Set clear objectives** before starting sessions
-2. **Provide context documents** for domain relevance
-3. **Trust the process** - Let facilitation guide you
-4. **Take breaks** when energy flags
-5. **Document insights** as they emerge
-
-:::tip[Learn More]
-See [Facilitation Over Generation](/docs/explanation/philosophy/facilitation-over-generation.md) for the core philosophy behind CIS.
-:::

docs/explanation/faq/tools-faq.md

@@ -9,21 +9,45 @@ Quick answers to common questions about tools, IDEs, and advanced topics in the
 
 **Tools and Technical**
 
-- [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering)
-- [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools)
-- [What IDEs/tools support BMM?](#what-idestools-support-bmm)
-- [Can I customize agents?](#can-i-customize-agents)
-- [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation)
-- [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects)
+- [Questions](#questions)
+- [Tools and Technical](#tools-and-technical)
+  - [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering)
+  - [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools)
+  - [What IDEs/tools support BMM?](#what-idestools-support-bmm)
+  - [Can I customize agents?](#can-i-customize-agents)
+  - [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation)
+  - [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects)
+- [Advanced](#advanced)
+  - [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3)
+  - [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches)
+  - [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint)
+  - [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations)
+  - [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project)
+  - [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it)
+- [Getting Help](#getting-help)
+  - [Where do I get help if my question isn't answered here?](#where-do-i-get-help-if-my-question-isnt-answered-here)
+  - [How do I report a bug or request a feature?](#how-do-i-report-a-bug-or-request-a-feature)
 
 **Advanced**
 
-- [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3)
-- [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches)
-- [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint)
-- [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations)
-- [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project)
-- [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it)
+- [Questions](#questions)
+- [Tools and Technical](#tools-and-technical)
+  - [Why are my Mermaid diagrams not rendering?](#why-are-my-mermaid-diagrams-not-rendering)
+  - [Can I use BMM with GitHub Copilot / Cursor / other AI tools?](#can-i-use-bmm-with-github-copilot--cursor--other-ai-tools)
+  - [What IDEs/tools support BMM?](#what-idestools-support-bmm)
+  - [Can I customize agents?](#can-i-customize-agents)
+  - [What happens to my planning docs after implementation?](#what-happens-to-my-planning-docs-after-implementation)
+  - [Can I use BMM for non-software projects?](#can-i-use-bmm-for-non-software-projects)
+- [Advanced](#advanced)
+  - [What if my project grows from Level 1 to Level 3?](#what-if-my-project-grows-from-level-1-to-level-3)
+  - [Can I mix greenfield and brownfield approaches?](#can-i-mix-greenfield-and-brownfield-approaches)
+  - [How do I handle urgent hotfixes during a sprint?](#how-do-i-handle-urgent-hotfixes-during-a-sprint)
+  - [What if I disagree with the workflow's recommendations?](#what-if-i-disagree-with-the-workflows-recommendations)
+  - [Can multiple developers work on the same BMM project?](#can-multiple-developers-work-on-the-same-bmm-project)
+  - [What is party mode and when should I use it?](#what-is-party-mode-and-when-should-i-use-it)
+- [Getting Help](#getting-help)
+  - [Where do I get help if my question isn't answered here?](#where-do-i-get-help-if-my-question-isnt-answered-here)
+  - [How do I report a bug or request a feature?](#how-do-i-report-a-bug-or-request-a-feature)
 
 **Getting Help**
 
@@ -199,11 +223,11 @@ Yes! But the paradigm is fundamentally different from traditional agile teams.
 
 ### What is party mode and when should I use it?
 
-Party mode is a unique multi-agent collaboration feature where ALL your installed agents (19+ from BMM, CIS, BMB, custom modules) discuss your challenges together in real-time.
+Party mode is a unique multi-agent collaboration feature where ALL your installed modules agents discuss your challenges together in real-time or have some fun with any topic you have in mind.
 
 **How it works:**
 
-1. Run `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent)
+1. Run `/bmad:core:workflows:party-mode` (or `PM or fuzzy match on party-mode` from any agent)
 2. Introduce your topic
 3. BMad Master selects 2-3 most relevant agents per message
 4. Agents cross-talk, debate, and build on each other's ideas

docs/explanation/game-dev/agents.md

@@ -1,387 +0,0 @@
----
-title: "BMGD Agents Guide"
----
-
-Complete reference for BMGD's six specialized game development agents.
-
-## Agent Overview
-
-BMGD provides six agents, each with distinct expertise:
-
-| Agent | Name | Role | Phase Focus |
-|-------|------|------|-------------|
-| **Game Designer** | Samus Shepard | Lead Game Designer + Creative Vision Architect | Phases 1-2 |
-| **Game Architect** | Cloud Dragonborn | Principal Game Systems Architect + Technical Director | Phase 3 |
-| **Game Developer** | Link Freeman | Senior Game Developer + Technical Implementation Specialist | Phase 4 |
-| **Game Scrum Master** | Max | Game Development Scrum Master + Sprint Orchestrator | Phase 4 |
-| **Game QA** | GLaDOS | Game QA Architect + Test Automation Specialist | All Phases |
-| **Game Solo Dev** | Indie | Elite Indie Game Developer + Quick Flow Specialist | All Phases |
-
-## Game Designer (Samus Shepard)
-
-### Role
-
-Lead Game Designer + Creative Vision Architect
-
-### Identity
-
-Veteran designer with 15+ years crafting AAA and indie hits. Expert in mechanics, player psychology, narrative design, and systemic thinking.
-
-### Communication Style
-
-Talks like an excited streamer - enthusiastic, asks about player motivations, celebrates breakthroughs with "Let's GOOO!"
-
-### Core Principles
-
-- Design what players want to FEEL, not what they say they want
-- Prototype fast - one hour of playtesting beats ten hours of discussion
-- Every mechanic must serve the core fantasy
-
-### When to Use
-
-- Brainstorming game ideas
-- Creating Game Briefs
-- Designing GDDs
-- Developing narrative design
-
-### Available Commands
-
-| Command                | Description                      |
-| ---------------------- | -------------------------------- |
-| `workflow-status`      | Check project status             |
-| `brainstorm-game`      | Guided game ideation             |
-| `create-game-brief`    | Create Game Brief                |
-| `create-gdd`           | Create Game Design Document      |
-| `narrative`            | Create Narrative Design Document |
-| `quick-prototype`      | Rapid prototyping (IDE only)     |
-| `party-mode`           | Multi-agent collaboration        |
-| `advanced-elicitation` | Deep exploration (web only)      |
-
-## Game Architect (Cloud Dragonborn)
-
-### Role
-
-Principal Game Systems Architect + Technical Director
-
-### Identity
-
-Master architect with 20+ years shipping 30+ titles. Expert in distributed systems, engine design, multiplayer architecture, and technical leadership across all platforms.
-
-### Communication Style
-
-Speaks like a wise sage from an RPG - calm, measured, uses architectural metaphors about building foundations and load-bearing walls.
-
-### Core Principles
-
-- Architecture is about delaying decisions until you have enough data
-- Build for tomorrow without over-engineering today
-- Hours of planning save weeks of refactoring hell
-- Every system must handle the hot path at 60fps
-
-### When to Use
-
-- Planning technical architecture
-- Making engine/framework decisions
-- Designing game systems
-- Course correction during development
-
-### Available Commands
-
-| Command                | Description                           |
-| ---------------------- | ------------------------------------- |
-| `workflow-status`      | Check project status                  |
-| `create-architecture`  | Create Game Architecture              |
-| `correct-course`       | Course correction analysis (IDE only) |
-| `party-mode`           | Multi-agent collaboration             |
-| `advanced-elicitation` | Deep exploration (web only)           |
-
-## Game Developer (Link Freeman)
-
-### Role
-
-Senior Game Developer + Technical Implementation Specialist
-
-### Identity
-
-Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code.
-
-### Communication Style
-
-Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship.
-
-### Core Principles
-
-- 60fps is non-negotiable
-- Write code designers can iterate without fear
-- Ship early, ship often, iterate on player feedback
-- Red-green-refactor: tests first, implementation second
-
-### When to Use
-
-- Implementing stories
-- Code reviews
-- Performance optimization
-- Completing story work
-
-### Available Commands
-
-| Command                | Description                     |
-| ---------------------- | ------------------------------- |
-| `workflow-status`      | Check sprint progress           |
-| `dev-story`            | Implement story tasks           |
-| `code-review`          | Perform code review             |
-| `quick-dev`            | Flexible development (IDE only) |
-| `quick-prototype`      | Rapid prototyping (IDE only)    |
-| `party-mode`           | Multi-agent collaboration       |
-| `advanced-elicitation` | Deep exploration (web only)     |
-
-## Game Scrum Master (Max)
-
-### Role
-
-Game Development Scrum Master + Sprint Orchestrator
-
-### Identity
-
-Certified Scrum Master specializing in game dev workflows. Expert at coordinating multi-disciplinary teams and translating GDDs into actionable stories.
-
-### Communication Style
-
-Talks in game terminology - milestones are save points, handoffs are level transitions, blockers are boss fights.
-
-### Core Principles
-
-- Every sprint delivers playable increments
-- Clean separation between design and implementation
-- Keep the team moving through each phase
-- Stories are single source of truth for implementation
-
-### When to Use
-
-- Sprint planning and management
-- Creating epic tech specs
-- Writing story drafts
-- Assembling story context
-- Running retrospectives
-- Handling course corrections
-
-### Available Commands
-
-| Command                 | Description                                 |
-| ----------------------- | ------------------------------------------- |
-| `workflow-status`       | Check project status                        |
-| `sprint-planning`       | Generate/update sprint status               |
-| `sprint-status`         | View sprint progress, get next action       |
-| `create-story`          | Create story (marks ready-for-dev directly) |
-| `validate-create-story` | Validate story draft                        |
-| `epic-retrospective`    | Facilitate retrospective                    |
-| `correct-course`        | Navigate significant changes                |
-| `party-mode`            | Multi-agent collaboration                   |
-| `advanced-elicitation`  | Deep exploration (web only)                 |
-
-## Game QA (GLaDOS)
-
-### Role
-
-Game QA Architect + Test Automation Specialist
-
-### Identity
-
-Senior QA architect with 12+ years in game testing across Unity, Unreal, and Godot. Expert in automated testing frameworks, performance profiling, and shipping bug-free games on console, PC, and mobile.
-
-### Communication Style
-
-Speaks like a quality guardian - methodical, data-driven, but understands that "feel" matters in games. Uses metrics to back intuition. "Trust, but verify with tests."
-
-### Core Principles
-
-- Test what matters: gameplay feel, performance, progression
-- Automated tests catch regressions, humans catch fun problems
-- Every shipped bug is a process failure, not a people failure
-- Flaky tests are worse than no tests - they erode trust
-- Profile before optimize, test before ship
-
-### When to Use
-
-- Setting up test frameworks
-- Designing test strategies
-- Creating automated tests
-- Planning playtesting sessions
-- Performance testing
-- Reviewing test coverage
-
-### Available Commands
-
-| Command                | Description                                         |
-| ---------------------- | --------------------------------------------------- |
-| `workflow-status`      | Check project status                                |
-| `test-framework`       | Initialize game test framework (Unity/Unreal/Godot) |
-| `test-design`          | Create comprehensive game test scenarios            |
-| `automate`             | Generate automated game tests                       |
-| `playtest-plan`        | Create structured playtesting plan                  |
-| `performance-test`     | Design performance testing strategy                 |
-| `test-review`          | Review test quality and coverage                    |
-| `party-mode`           | Multi-agent collaboration                           |
-| `advanced-elicitation` | Deep exploration (web only)                         |
-
-### Knowledge Base
-
-GLaDOS has access to a comprehensive game testing knowledge base (`gametest/qa-index.csv`) including:
-
-**Engine-Specific Testing:**
-
-- Unity Test Framework (Edit Mode, Play Mode)
-- Unreal Automation and Gauntlet
-- Godot GUT (Godot Unit Test)
-
-**Game-Specific Testing:**
-
-- Playtesting fundamentals
-- Balance testing
-- Save system testing
-- Multiplayer/network testing
-- Input testing
-- Platform certification (TRC/XR)
-- Localization testing
-
-**General QA:**
-
-- QA automation strategies
-- Performance testing
-- Regression testing
-- Smoke testing
-- Test prioritization (P0-P3)
-
-## Game Solo Dev (Indie)
-
-### Role
-
-Elite Indie Game Developer + Quick Flow Specialist
-
-### Identity
-
-Battle-hardened solo game developer who ships complete games from concept to launch. Expert in Unity, Unreal, and Godot, having shipped titles across mobile, PC, and console. Lives and breathes the Quick Flow workflow - prototyping fast, iterating faster, and shipping before the hype dies.
-
-### Communication Style
-
-Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and player experience. Every response moves the game closer to ship. "Does it feel good? Ship it."
-
-### Core Principles
-
-- Prototype fast, fail fast, iterate faster
-- A playable build beats a perfect design doc
-- 60fps is non-negotiable - performance is a feature
-- The core loop must be fun before anything else matters
-- Ship early, playtest often
-
-### When to Use
-
-- Solo game development
-- Rapid prototyping
-- Quick iteration without full team workflow
-- Indie projects with tight timelines
-- When you want to handle everything yourself
-
-### Available Commands
-
-| Command            | Description                                            |
-| ------------------ | ------------------------------------------------------ |
-| `quick-prototype`  | Rapid prototype to test if a mechanic is fun           |
-| `quick-dev`        | Implement features end-to-end with game considerations |
-| `quick-spec`       | Create implementation-ready technical spec             |
-| `code-review`      | Review code quality                                    |
-| `test-framework`   | Set up automated testing                               |
-| `party-mode`       | Bring in specialists when needed                       |
-
-### Quick Flow vs Full BMGD
-
-Use **Game Solo Dev** when:
-
-- You're working alone or in a tiny team
-- Speed matters more than process
-- You want to skip the full planning phases
-- You're prototyping or doing game jams
-
-Use **Full BMGD workflow** when:
-
-- You have a larger team
-- The project needs formal documentation
-- You're working with stakeholders/publishers
-- Long-term maintainability is critical
-
-## Agent Selection Guide
-
-### By Phase
-
-| Phase                          | Primary Agent     | Secondary Agent   |
-| ------------------------------ | ----------------- | ----------------- |
-| 1: Preproduction               | Game Designer     | -                 |
-| 2: Design                      | Game Designer     | -                 |
-| 3: Technical                   | Game Architect    | Game QA           |
-| 4: Production (Planning)       | Game Scrum Master | Game Architect    |
-| 4: Production (Implementation) | Game Developer    | Game Scrum Master |
-| Testing (Any Phase)            | Game QA           | Game Developer    |
-
-### By Task
-
-| Task                             | Best Agent        |
-| -------------------------------- | ----------------- |
-| "I have a game idea"             | Game Designer     |
-| "Help me design my game"         | Game Designer     |
-| "How should I build this?"       | Game Architect    |
-| "What's the technical approach?" | Game Architect    |
-| "Plan our sprints"               | Game Scrum Master |
-| "Create implementation stories"  | Game Scrum Master |
-| "Build this feature"             | Game Developer    |
-| "Review this code"               | Game Developer    |
-| "Set up testing framework"       | Game QA           |
-| "Create test plan"               | Game QA           |
-| "Test performance"               | Game QA           |
-| "Plan a playtest"                | Game QA           |
-| "I'm working solo"               | Game Solo Dev     |
-| "Quick prototype this idea"      | Game Solo Dev     |
-| "Ship this feature fast"         | Game Solo Dev     |
-
-## Multi-Agent Collaboration
-
-### Party Mode
-
-All agents have access to `party-mode`, which brings multiple agents together for complex decisions. Use this when:
-
-- A decision spans multiple domains (design + technical)
-- You want diverse perspectives
-- You're stuck and need fresh ideas
-
-### Handoffs
-
-Agents naturally hand off to each other:
-
-```
-Game Designer → Game Architect → Game Scrum Master → Game Developer
-    ↓                ↓                  ↓                  ↓
-  GDD          Architecture      Sprint/Stories      Implementation
-                     ↓                                     ↓
-                 Game QA ←──────────────────────────── Game QA
-                     ↓                                     ↓
-              Test Strategy                         Automated Tests
-```
-
-Game QA integrates at multiple points:
-
-- After Architecture: Define test strategy
-- During Implementation: Create automated tests
-- Before Release: Performance and certification testing
-
-## Project Context
-
-All agents share the principle:
-
-> "Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`"
-
-The `project-context.md` file (if present) serves as the authoritative source for project decisions and constraints.
-
-## Next Steps
-
-- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD
-- **[Workflows Guide](/docs/reference/workflows/index.md)** - Detailed workflow reference
-- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Game type templates

docs/explanation/game-dev/bmgd-vs-bmm.md

@@ -1,125 +0,0 @@
----
-title: "BMGD vs BMM"
-description: Understanding the differences between BMGD and BMM
----
-
-BMGD (BMad Game Development) extends BMM (BMad Method) with game-specific capabilities. This page explains the key differences.
-
-## Quick Comparison
-
-| Aspect         | BMM                                   | BMGD                                                                     |
-| -------------- | ------------------------------------- | ------------------------------------------------------------------------ |
-| **Focus**      | General software                      | Game development                                                         |
-| **Agents**     | PM, Architect, Dev, SM, TEA, Solo Dev | Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev |
-| **Planning**   | PRD, Tech Spec                        | Game Brief, GDD                                                          |
-| **Types**      | N/A                                   | 24 game type templates                                                   |
-| **Narrative**  | N/A                                   | Full narrative workflow                                                  |
-| **Testing**    | Web-focused                           | Engine-specific (Unity, Unreal, Godot)                                   |
-| **Production** | BMM workflows                         | BMM workflows with game overrides                                        |
-
-## Agent Differences
-
-### BMM Agents
-- PM (Product Manager)
-- Architect
-- DEV (Developer)
-- SM (Scrum Master)
-- TEA (Test Architect)
-- Quick Flow Solo Dev
-
-### BMGD Agents
-- Game Designer
-- Game Developer
-- Game Architect
-- Game Scrum Master
-- Game QA
-- Game Solo Dev
-
-BMGD agents understand game-specific concepts like:
-- Game mechanics and balance
-- Player psychology
-- Engine-specific patterns
-- Playtesting and QA
-
-## Planning Documents
-
-### BMM Planning
-- **Product Brief** → **PRD** → **Architecture**
-- Focus: Software requirements, user stories, system design
-
-### BMGD Planning
-- **Game Brief** → **GDD** → **Architecture**
-- Focus: Game vision, mechanics, narrative, player experience
-
-The GDD (Game Design Document) includes:
-- Core gameplay loop
-- Mechanics and systems
-- Progression and balance
-- Art and audio direction
-- Genre-specific sections
-
-## Game Type Templates
-
-BMGD includes 24 game type templates that auto-configure GDD sections:
-
-- Action, Adventure, Puzzle
-- RPG, Strategy, Simulation
-- Sports, Racing, Fighting
-- Horror, Platformer, Shooter
-- And more...
-
-Each template provides:
-- Genre-specific GDD sections
-- Relevant mechanics patterns
-- Testing considerations
-- Common pitfalls to avoid
-
-## Narrative Support
-
-BMGD includes full narrative workflow for story-driven games:
-
-- **Narrative Design** workflow
-- Story structure templates
-- Character development
-- World-building guidelines
-- Dialogue systems
-
-BMM has no equivalent for narrative design.
-
-## Testing Differences
-
-### BMM Testing (TEA)
-- Web-focused (Playwright, Cypress)
-- API testing
-- E2E for web applications
-
-### BMGD Testing (Game QA)
-- Engine-specific frameworks (Unity, Unreal, Godot)
-- Gameplay testing
-- Performance profiling
-- Playtest planning
-- Balance validation
-
-## Production Workflow
-
-BMGD production workflows **inherit from BMM** and add game-specific:
-- Checklists
-- Templates
-- Quality gates
-- Engine-specific considerations
-
-This means you get all of BMM's implementation structure plus game-specific enhancements.
-
-## When to Use Each
-
-### Use BMM when:
-- Building web applications
-- Creating APIs and services
-- Developing mobile apps (non-game)
-- Any general software project
-
-### Use BMGD when:
-- Building video games
-- Creating interactive experiences
-- Game prototyping
-- Game jams

docs/explanation/game-dev/game-types.md

@@ -1,447 +0,0 @@
----
-title: "BMGD Game Types Guide"
----
-
-Reference for selecting and using BMGD's 24 supported game type templates.
-
-## Overview
-
-When creating a GDD, BMGD offers game type templates that provide genre-specific sections. This ensures your design document covers mechanics and systems relevant to your game's genre.
-
-## Supported Game Types
-
-### Action & Combat
-
-#### Action Platformer
-
-**Tags:** action, platformer, combat, movement
-
-Side-scrolling or 3D platforming with combat mechanics. Think Hollow Knight, Celeste with combat, or Mega Man.
-
-**GDD sections added:**
-
-- Movement systems (jumps, dashes, wall mechanics)
-- Combat mechanics (melee/ranged, combos)
-- Level design patterns
-- Boss design
-
-#### Shooter
-
-**Tags:** shooter, combat, aiming, fps, tps
-
-Projectile combat with aiming mechanics. Covers FPS, TPS, and arena shooters.
-
-**GDD sections added:**
-
-- Weapon systems
-- Aiming and accuracy
-- Enemy AI patterns
-- Level/arena design
-- Multiplayer considerations
-
-#### Fighting
-
-**Tags:** fighting, combat, competitive, combos, pvp
-
-1v1 combat with combos and frame data. Traditional fighters and platform fighters.
-
-**GDD sections added:**
-
-- Frame data systems
-- Combo mechanics
-- Character movesets
-- Competitive balance
-- Netcode requirements
-
-### Strategy & Tactics
-
-#### Strategy
-
-**Tags:** strategy, tactics, resources, planning
-
-Resource management with tactical decisions. RTS, 4X, and grand strategy.
-
-**GDD sections added:**
-
-- Resource systems
-- Unit/building design
-- AI opponent behavior
-- Map/scenario design
-- Victory conditions
-
-#### Turn-Based Tactics
-
-**Tags:** tactics, turn-based, grid, positioning
-
-Grid-based movement with turn order. XCOM-likes and tactical RPGs.
-
-**GDD sections added:**
-
-- Grid and movement systems
-- Turn order mechanics
-- Cover and positioning
-- Unit progression
-- Procedural mission generation
-
-#### Tower Defense
-
-**Tags:** tower-defense, waves, placement, strategy
-
-Wave-based defense with tower placement.
-
-**GDD sections added:**
-
-- Tower types and upgrades
-- Wave design and pacing
-- Economy systems
-- Map design patterns
-- Meta-progression
-
-### RPG & Progression
-
-#### RPG
-
-**Tags:** rpg, stats, inventory, quests, narrative
-
-Character progression with stats, inventory, and quests.
-
-**GDD sections added:**
-
-- Character stats and leveling
-- Inventory and equipment
-- Quest system design
-- Combat system (action/turn-based)
-- Skill trees and builds
-
-#### Roguelike
-
-**Tags:** roguelike, procedural, permadeath, runs
-
-Procedural generation with permadeath and run-based progression.
-
-**GDD sections added:**
-
-- Procedural generation rules
-- Permadeath and persistence
-- Run structure and pacing
-- Item/ability synergies
-- Meta-progression systems
-
-#### Metroidvania
-
-**Tags:** metroidvania, exploration, abilities, interconnected
-
-Interconnected world with ability gating.
-
-**GDD sections added:**
-
-- World map connectivity
-- Ability gating design
-- Backtracking flow
-- Secret and collectible placement
-- Power-up progression
-
-### Narrative & Story
-
-#### Adventure
-
-**Tags:** adventure, narrative, exploration, story
-
-Story-driven exploration and narrative. Point-and-click and narrative adventures.
-
-**GDD sections added:**
-
-- Puzzle design
-- Narrative delivery
-- Exploration mechanics
-- Dialogue systems
-- Story branching
-
-#### Visual Novel
-
-**Tags:** visual-novel, narrative, choices, story
-
-Narrative choices with branching story.
-
-**GDD sections added:**
-
-- Branching narrative structure
-- Choice and consequence
-- Character routes
-- UI/presentation
-- Save/load states
-
-#### Text-Based
-
-**Tags:** text, parser, interactive-fiction, mud
-
-Text input/output games. Parser games, choice-based IF, MUDs.
-
-**GDD sections added:**
-
-- Parser or choice systems
-- World model
-- Narrative structure
-- Text presentation
-- Save state management
-
-### Simulation & Management
-
-#### Simulation
-
-**Tags:** simulation, management, sandbox, systems
-
-Realistic systems with management and building. Includes tycoons and sim games.
-
-**GDD sections added:**
-
-- Core simulation loops
-- Economy modeling
-- AI agents/citizens
-- Building/construction
-- Failure states
-
-#### Sandbox
-
-**Tags:** sandbox, creative, building, freedom
-
-Creative freedom with building and minimal objectives.
-
-**GDD sections added:**
-
-- Creation tools
-- Physics/interaction systems
-- Persistence and saving
-- Sharing/community features
-- Optional objectives
-
-### Sports & Racing
-
-#### Racing
-
-**Tags:** racing, vehicles, tracks, speed
-
-Vehicle control with tracks and lap times.
-
-**GDD sections added:**
-
-- Vehicle physics model
-- Track design
-- AI opponents
-- Progression/career mode
-- Multiplayer racing
-
-#### Sports
-
-**Tags:** sports, teams, realistic, physics
-
-Team-based or individual sports simulation.
-
-**GDD sections added:**
-
-- Sport-specific rules
-- Player/team management
-- AI opponent behavior
-- Season/career modes
-- Multiplayer modes
-
-### Multiplayer
-
-#### MOBA
-
-**Tags:** moba, multiplayer, pvp, heroes, lanes
-
-Multiplayer team battles with hero selection.
-
-**GDD sections added:**
-
-- Hero/champion design
-- Lane and map design
-- Team composition
-- Matchmaking
-- Economy (gold/items)
-
-#### Party Game
-
-**Tags:** party, multiplayer, minigames, casual
-
-Local multiplayer with minigames.
-
-**GDD sections added:**
-
-- Minigame design patterns
-- Controller support
-- Round/game structure
-- Scoring systems
-- Player count flexibility
-
-### Horror & Survival
-
-#### Survival
-
-**Tags:** survival, crafting, resources, danger
-
-Resource gathering with crafting and persistent threats.
-
-**GDD sections added:**
-
-- Resource gathering
-- Crafting systems
-- Hunger/health/needs
-- Threat systems
-- Base building
-
-#### Horror
-
-**Tags:** horror, atmosphere, tension, fear
-
-Atmosphere and tension with limited resources.
-
-**GDD sections added:**
-
-- Fear mechanics
-- Resource scarcity
-- Sound design
-- Lighting and visibility
-- Enemy/threat design
-
-### Casual & Progression
-
-#### Puzzle
-
-**Tags:** puzzle, logic, cerebral
-
-Logic-based challenges and problem-solving.
-
-**GDD sections added:**
-
-- Puzzle mechanics
-- Difficulty progression
-- Hint systems
-- Level structure
-- Scoring/rating
-
-#### Idle/Incremental
-
-**Tags:** idle, incremental, automation, progression
-
-Passive progression with upgrades and automation.
-
-**GDD sections added:**
-
-- Core loop design
-- Prestige systems
-- Automation unlocks
-- Number scaling
-- Offline progress
-
-#### Card Game
-
-**Tags:** card, deck-building, strategy, turns
-
-Deck building with card mechanics.
-
-**GDD sections added:**
-
-- Card design framework
-- Deck building rules
-- Mana/resource systems
-- Rarity and collection
-- Competitive balance
-
-### Rhythm
-
-#### Rhythm
-
-**Tags:** rhythm, music, timing, beats
-
-Music synchronization with timing-based gameplay.
-
-**GDD sections added:**
-
-- Note/beat mapping
-- Scoring systems
-- Difficulty levels
-- Music licensing
-- Input methods
-
-## Hybrid Game Types
-
-Many games combine multiple genres. BMGD supports hybrid selection:
-
-### Examples
-
-**Action RPG** = Action Platformer + RPG
-
-- Movement and combat systems from Action Platformer
-- Progression and stats from RPG
-
-**Survival Horror** = Survival + Horror
-
-- Resource and crafting from Survival
-- Atmosphere and fear from Horror
-
-**Roguelike Deckbuilder** = Roguelike + Card Game
-
-- Run structure from Roguelike
-- Card mechanics from Card Game
-
-### How to Use Hybrids
-
-During GDD creation, select multiple game types when prompted:
-
-```
-Agent: What game type best describes your game?
-You: It's a roguelike with card game combat
-Agent: I'll include sections for both Roguelike and Card Game...
-```
-
-## Game Type Selection Tips
-
-### 1. Start with Core Fantasy
-
-What does the player primarily DO in your game?
-
-- Run and jump? → Platformer types
-- Build and manage? → Simulation types
-- Fight enemies? → Combat types
-- Make choices? → Narrative types
-
-### 2. Consider Your Loop
-
-What's the core gameplay loop?
-
-- Session-based runs? → Roguelike
-- Long-term progression? → RPG
-- Quick matches? → Multiplayer types
-- Creative expression? → Sandbox
-
-### 3. Don't Over-Combine
-
-2-3 game types maximum. More than that usually means your design isn't focused enough.
-
-### 4. Primary vs Secondary
-
-One type should be primary (most gameplay time). Others add flavor:
-
-- **Primary:** Platformer (core movement and exploration)
-- **Secondary:** Metroidvania (ability gating structure)
-
-## GDD Section Mapping
-
-When you select a game type, BMGD adds these GDD sections:
-
-| Game Type         | Key Sections Added                     |
-| ----------------- | -------------------------------------- |
-| Action Platformer | Movement, Combat, Level Design         |
-| RPG               | Stats, Inventory, Quests               |
-| Roguelike         | Procedural Gen, Runs, Meta-Progression |
-| Narrative         | Story Structure, Dialogue, Branching   |
-| Multiplayer       | Matchmaking, Netcode, Balance          |
-| Simulation        | Systems, Economy, AI                   |
-
-## Next Steps
-
-- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD
-- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - GDD workflow details
-- **[Glossary](/docs/reference/glossary/index.md)** - Game development terminology

docs/explanation/game-dev/index.md

@@ -1,70 +0,0 @@
----
-title: "BMGD - Game Development Module"
-description: AI-powered workflows for game design and development with BMGD
----
-
-Complete guides for the BMad Game Development Module (BMGD) — AI-powered workflows for game design and development that adapt to your project's needs.
-
-## Getting Started
-
-**New to BMGD?** Start here:
-
-- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started building your first game
-  - Installation and setup
-  - Understanding the game development phases
-  - Running your first workflows
-  - Agent-based development flow
-
-:::tip[Quick Path]
-Install BMGD module → Game Brief → GDD → Architecture → Build
-:::
-
-## Core Documentation
-
-- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Selecting and using game type templates (24 supported types)
-- **[BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md)** - Understanding the differences
-
-## Game Development Phases
-
-BMGD follows four phases aligned with game development:
-
-### Phase 1: Preproduction
-- **Brainstorm Game** - Ideation with game-specific techniques
-- **Game Brief** - Capture vision, market, and fundamentals
-
-### Phase 2: Design
-- **GDD (Game Design Document)** - Comprehensive game design
-- **Narrative Design** - Story, characters, world (for story-driven games)
-
-### Phase 3: Technical
-- **Game Architecture** - Engine, systems, patterns, structure
-
-### Phase 4: Production
-- **Sprint Planning** - Epic and story management
-- **Story Development** - Implementation workflow
-- **Code Review** - Quality assurance
-- **Testing** - Automated tests, playtesting, performance
-- **Retrospective** - Continuous improvement
-
-## Choose Your Path
-
-### I need to...
-
-**Start a new game project**
-→ Start with [Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)
-→ Run `brainstorm-game` for ideation
-→ Create a Game Brief with `create-brief`
-
-**Design my game**
-→ Create a GDD with `create-gdd`
-→ If story-heavy, add Narrative Design with `create-narrative`
-
-**Plan the technical architecture**
-→ Run `create-architecture` with the Game Architect
-
-**Build my game**
-→ Use Phase 4 production workflows
-→ Follow the sprint-based development cycle
-
-**Quickly test an idea**
-→ Use [Quick-Flow](/docs/how-to/workflows/bmgd-quick-flow.md) for rapid prototyping

docs/explanation/philosophy/facilitation-over-generation.md

@@ -1,106 +1,333 @@
 ---
 title: "Facilitation Over Generation"
-description: Understanding CIS's facilitation-first approach to creative work
+description: Understanding a facilitation-first approach to AI workflows and creative collaboration
 ---
 
+BMAD workflows take a fundamentally different approach from typical AI Prompts you will find. Instead of generating solutions directly, workflows act as facilitators who guide you through discovery processes, helping you arrive at insights and decisions yourself.
 
-The Creative Intelligence Suite (CIS) takes a fundamentally different approach from typical AI tools. Instead of generating solutions directly, CIS agents act as master facilitators who guide you to discover insights yourself.
+This has always been the magic of the BMad method - if you have used it you have felt it intuitively and noticed a difference - and it is through this document I want to really explain what this is. This is fundamental to understand if you are also interested in producing your own workflows or improving upon existing ones in any BMad related module.
 
 ## The Problem with Generation
 
-Traditional AI approaches to creative work:
+Traditional AI approaches to creative and knowledge work typically follow this pattern:
 
 :::note[Generation Example]
-**User:** "Give me marketing ideas"
+**User:** "I need a comprehensive UX design for my e-commerce app"
 
-**AI:** "Here are 10 marketing ideas..."
+**AI:** [Immediately generates] "Here's a complete UX specification with modern dark theme, card-based product grid, left navigation, and checkout flow..."
 :::
 
 This approach:
-- Produces generic, predictable outputs
-- Removes human ownership of ideas
-- Misses context and nuance
-- Limits creative exploration
+- Produces generic, predictable outputs that may not fit your actual needs
+- Removes your ownership and understanding of the solution
+- Misses critical context, constraints, and nuance
+- Limits creative exploration to the AI's training data patterns
+- Creates deliverables you can't explain or iterate on effectively
 
 ## The Facilitation Approach
 
-CIS agents use strategic questioning:
+Facilitative workflows use strategic questioning and guided discovery:
 
-:::note[Facilitation Example]
-**User:** "I need marketing ideas"
+:::note[Facilitation Example from UX Design Workflow]
+**User:** "I need a comprehensive UX design for my e-commerce app"
 
-**CIS:** "What makes your customers choose you over alternatives? What's the one thing they always mention?"
+**Workflow:** "Welcome! I'll act as your UX facilitator to help you discover the right approach. First, let me understand what documents you already have—do you have a product brief, PRD, or any research?"
 
-**User:** "They say our support is exceptional"
+**User:** "I have a product brief and some user research"
 
-**CIS:** "Interesting! How might you make that exceptional support visible before they become customers?"
+**Workflow:** "Great! Let me load those. [Loads documents] Now, what are the primary user goals for your e-commerce experience? What should users be able to accomplish?"
+
+**User:** "They need to browse products quickly and complete purchases without friction"
+
+**Workflow:** "Interesting! And what makes your e-commerce situation unique? What are the specific challenges or constraints you're working with?"
 :::
 
 This approach:
-- Draws out insights already within you
-- Maintains human ownership of ideas
-- Captures context and nuance
-- Enables deeper creative exploration
+- Draws out insights and expertise already within you
+- Maintains your ownership and understanding of decisions
+- Captures your specific context, constraints, and goals
+- Enables deeper exploration of your unique situation
+- Creates outputs you can confidently explain and iterate on
+
+## Real-World Examples from BMAD Workflows
+
+### Brainstorming Workflow (from core module)
+
+The brainstorming workflow demonstrates pure facilitation through its entire journey:
+
+**Session Setup:**
+```
+"Welcome! I'm excited to facilitate your brainstorming session. I'll guide you
+through proven creativity techniques to generate innovative ideas.
+
+**What are we brainstorming about?** (The central topic or challenge)
+**What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights)
+```
+
+**Technique Selection - Offering Options:**
+```
+"Ready to explore technique approaches?
+[1] User-Selected Techniques - Browse our complete technique library
+[2] AI-Recommended Techniques - Get customized suggestions based on your goals
+[3] Random Technique Selection - Discover unexpected creative methods
+[4] Progressive Technique Flow - Start broad, then systematically narrow focus
+
+Which approach appeals to you most?"
+```
+
+**Technique Execution - Interactive Coaching:**
+The workflow doesn't generate ideas—it coaches you through techniques with genuine back-and-forth dialogue:
+
+```
+"Let's start with: What if you could remove all practical constraints?
+
+I'm not just looking for a quick answer - I want to explore this together.
+What immediately comes to mind? Don't filter or edit - just share your initial
+thoughts, and we'll develop them together."
+
+[User responds]
+
+"That's interesting! Tell me more about [specific aspect you mentioned].
+What would that look like in practice? How does that connect to your core goal?"
+```
+
+**Key facilitation behaviors:**
+- Aims for 100+ ideas before suggesting organization
+- Asks "Continue exploring?" or "Move to next technique?"—user controls pace
+- Uses anti-bias protocols to force thinking in new directions every 10 ideas
+- Builds on user's ideas with genuine creative contributions
+- Keeps user in "generative exploration mode" as long as possible
+
+**Organization - Collaborative Synthesis:**
+```
+"Outstanding creative work! You've generated an incredible range of ideas.
+Now let's organize these creative gems and identify your most promising opportunities.
+
+I'm analyzing all your generated ideas to identify natural themes and patterns.
+**Emerging Themes I'm Identifying:**
+- Theme 1: [Name] - Ideas: [list] - Pattern: [connection]
+- Theme 2: [Name] - Ideas: [list] - Pattern: [connection]
+
+Which themes or specific ideas stand out to you as most valuable?"
+```
+
+Result: A comprehensive brainstorming session document with **your** ideas, organized by **your** priorities, with **your** action plans.
+
+### Create UX Design Workflow (from BMM method)
+
+The UX design workflow facilitates a 14-step journey from project understanding to complete UX specification—**never making design decisions for you**.
+
+**Step 1: Document Discovery (Collaborative Setup)**
+```
+"Welcome! I've set up your UX design workspace.
+
+**Documents Found:**
+- PRD: product-requirements.md
+- Product brief: brief.md
+
+**Files loaded:** [lists specific files]
+
+Do you have any other documents you'd like me to include, or shall we continue?"
+```
+
+**Step 2: Project Understanding (Discovery Questions)**
+```
+"Based on the project documentation, let me confirm what I'm understanding...
+
+**From the documents:** [summary of key insights]
+**Target Users:** [summary from documents]
+**Key Features/Goals:** [summary from documents]
+
+Does this match your understanding? Are there any corrections or additions?"
+```
+
+Then it dives deeper with targeted questions:
+```
+"Let me understand your users better to inform the UX design:
+
+**User Context Questions:**
+- What problem are users trying to solve?
+- What frustrates them with current solutions?
+- What would make them say 'this is exactly what I needed'?"
+```
+
+**Step 3: Core Experience Definition (Guiding Insights)**
+```
+"Now let's dig into the heart of the user experience.
+
+**Core Experience Questions:**
+- What's the ONE thing users will do most frequently?
+- What user action is absolutely critical to get right?
+- What should be completely effortless for users?
+- If we nail one interaction, everything else follows - what is it?
+
+Think about the core loop or primary action that defines your product's value."
+```
+
+**Step 4: Emotional Response (Feelings-Based Design)**
+```
+"Now let's think about how your product should make users feel.
+
+**Emotional Response Questions:**
+- What should users FEEL when using this product?
+- What emotion would make them tell a friend about this?
+- How should users feel after accomplishing their primary goal?
+
+Common emotional goals: Empowered and in control? Delighted and surprised?
+Efficient and productive? Creative and inspired?"
+```
+
+**Step 5: Pattern Inspiration (Learning from Examples)**
+```
+"Let's learn from products your users already love and use regularly.
+
+**Inspiration Questions:**
+- Name 2-3 apps your target users already love and USE frequently
+- For each one, what do they do well from a UX perspective?
+- What makes the experience compelling or delightful?
+
+For each inspiring app, let's analyze their UX success:
+- What core problem does it solve elegantly?
+- What makes the onboarding experience effective?
+- How do they handle navigation and information hierarchy?"
+```
+
+**Step 9: Design Directions (Interactive Visual Exploration)**
+The workflow generates 6-8 HTML mockup variations—but **you choose**:
+
+```
+"🎨 Design Direction Mockups Generated!
+
+I'm creating a comprehensive HTML showcase with 6-8 full-screen mockup variations.
+Each mockup represents a complete visual direction for your app's look and feel.
+
+**As you explore the design directions, look for:**
+✅ Which information hierarchy matches your priorities?
+✅ Which interaction style fits your core experience?
+✅ Which visual density feels right for your brand?
+
+**Which approach resonates most with you?**
+- Pick a favorite direction as-is
+- Combine elements from multiple directions
+- Request modifications to any direction
+
+Tell me: Which layout feels most intuitive? Which visual weight matches your brand?"
+```
+
+**Step 12: UX Patterns (Consistency Through Questions)**
+```
+"Let's establish consistency patterns for common situations.
+
+**Pattern Categories to Define:**
+- Button hierarchy and actions
+- Feedback patterns (success, error, warning, info)
+- Form patterns and validation
+- Navigation patterns
+
+Which categories are most critical for your product?
+
+**For [Critical Pattern Category]:**
+What should users see/do when they need to [pattern action]?
+
+**Considerations:**
+- Visual hierarchy (primary vs. secondary actions)
+- Feedback mechanisms
+- Error recovery
+- Accessibility requirements
+
+How should your product handle [pattern type] interactions?"
+```
+
+**The Result:** A complete, production-ready UX specification document that captures **your** decisions, **your** reasoning, and **your** vision—documented through guided discovery, not generation.
 
 ## Key Principles
 
 ### 1. Questions Over Answers
 
-CIS agents ask strategic questions rather than providing direct answers. This:
-- Activates your own creative thinking
-- Uncovers assumptions
-- Reveals blind spots
-- Builds on your domain knowledge
+Facilitative workflows ask strategic questions rather than providing direct answers. This:
+- Activates your own creative and analytical thinking
+- Uncovers assumptions you didn't know you had
+- Reveals blind spots in your understanding
+- Builds on your domain expertise and context
 
-### 2. Energy-Aware Sessions
+### 2. Multi-Turn Conversation
 
-CIS monitors engagement and adapts:
-- Adjusts pace when energy flags
-- Suggests breaks when needed
-- Changes techniques to maintain momentum
-- Recognizes productive vs. unproductive struggle
+Facilitation uses progressive discovery, not interrogation:
+- Ask 1-2 questions at a time, not laundry lists
+- Think about responses before asking follow-ups
+- Probe to understand deeper, not just collect facts
+- Use conversation to explore, not just extract
 
-### 3. Process Trust
+### 3. Intent-Based Guidance
 
-CIS uses proven methodologies:
-- Design Thinking's 5 phases
-- Structured brainstorming techniques
+Workflows specify goals and approaches, not exact scripts:
+- "Guide the user through discovering X" (intent)
+- NOT "Say exactly: 'What is X?'" (prescriptive)
+
+This allows the workflow to adapt naturally to your responses while maintaining structured progress.
+
+### 4. Process Trust
+
+Facilitative workflows use proven methodologies:
+- Design Thinking's phases (Empathize, Define, Ideate, Prototype, Test)
+- Structured brainstorming and creativity techniques
 - Root cause analysis frameworks
 - Innovation strategy patterns
 
-You're not just having a conversation—you're following time-tested creative processes.
+You're not just having a conversation—you're following time-tested processes adapted to your specific situation.
 
-### 4. Persona-Driven Engagement
+### 5. YOU Are the Expert
 
-Each CIS agent has a distinct personality:
-- **Carson** - Energetic, encouraging
-- **Maya** - Jazz-like, improvisational
-- **Dr. Quinn** - Analytical, methodical
-- **Victor** - Bold, strategic
-- **Sophia** - Narrative, imaginative
+Facilitative workflows operate on a core principle: **you are the expert on your situation**. The workflow brings:
+- Process expertise (how to think through problems)
+- Facilitation skills (how to guide exploration)
+- Technique knowledge (proven methods and frameworks)
 
-These personas create engaging experiences that maintain creative flow.
+You bring:
+- Domain knowledge (your specific field or industry)
+- Context understanding (your unique situation and constraints)
+- Decision authority (what will actually work for you)
 
 ## When Generation is Appropriate
 
-CIS does generate when appropriate:
-- Synthesizing session outputs
-- Documenting decisions
-- Creating structured artifacts
-- Providing technique examples
+Facilitative workflows DO generate when appropriate:
+- Synthesizing and structuring outputs after you've made decisions
+- Documenting your choices and rationale
+- Creating structured artifacts based on your input
+- Providing technique examples or option templates
+- Formatting and organizing your conclusions
 
-But the core creative work happens through facilitated discovery.
+But the **core creative and analytical work** happens through facilitated discovery, not generation.
+
+## The Distinction: Facilitator vs Generator
+
+| Facilitative Workflow                 | Generative AI                           |
+| ------------------------------------- | --------------------------------------- |
+| "What are your goals?"                | "Here's the solution"                   |
+| Asks 1-2 questions at a time          | Produces complete output immediately    |
+| Multiple turns, progressive discovery | Single turn, bulk generation            |
+| "Let me understand your context"      | "Here's a generic answer"               |
+| Offers options, you choose            | Makes decisions for you                 |
+| Documents YOUR reasoning              | No reasoning visible                    |
+| You can explain every decision        | You can't explain why choices were made |
+| Ownership and understanding           | Outputs feel alien                      |
 
 ## Benefits
 
 ### For Individuals
-- Deeper insights than pure generation
-- Ownership of creative outputs
-- Skill development in creative thinking
-- More memorable and actionable ideas
+- **Deeper insights** than pure generation—ideas connect to your actual knowledge
+- **Full ownership** of creative outputs and decisions
+- **Skill development** in structured thinking and problem-solving
+- **More memorable and actionable** results—you understand the "why"
 
 ### For Teams
-- Shared creative experience
-- Aligned understanding
-- Documented rationale
-- Stronger buy-in to outcomes
+- **Shared creative experience** building alignment and trust
+- **Aligned understanding** through documented exploration
+- **Documented rationale** for future reference and onboarding
+- **Stronger buy-in** to outcomes because everyone participated in discovery
+
+### For Implementation
+- **Outputs match reality** because they emerged from your actual constraints
+- **Easier iteration** because you understand the reasoning behind choices
+- **Confident implementation** because you can defend every decision
+- **Reduced rework** because facilitation catches issues early

docs/how-to/troubleshooting/bmgd-troubleshooting.md

@@ -215,6 +215,5 @@ When reporting issues, include:
 
 ## Next Steps
 
-- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started
 - **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference
 - **[Glossary](/docs/reference/glossary/index.md)** - Terminology

docs/tutorials/getting-started/quick-start-bmgd.md

@@ -1,260 +0,0 @@
----
-title: "Getting Started with BMad Game Development"
-description: Build games with BMad's Game Development Module
----
-
-
-Build games faster using AI-powered workflows with specialized game development agents that guide you through preproduction, design, architecture, and implementation.
-
-:::note[Module Extension]
-BMGD (BMad Game Development) is a module that extends BMad Method. You'll need BMad installed first—see the [BMad v6 tutorial](/docs/tutorials/getting-started/getting-started-bmadv6.md) if you haven't installed it yet.
-:::
-
-## What You'll Learn
-
-- Install and configure the BMGD module
-- Understand game development phases and specialized agents
-- Create a Game Brief and Game Design Document (GDD)
-- Progress from concept to working game code
-
-:::note[Prerequisites]
-- **BMad Method installed** — Follow the main installation guide first
-- **A game idea** — Even a rough concept is enough to start
-- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
-:::
-
-:::tip[Quick Path]
-**Install** → `npx bmad-method install` (select BMGD module)
-**Preproduction** → Game Designer creates Game Brief
-**Design** → Game Designer creates GDD (and Narrative if story-driven)
-**Technical** → Game Architect creates Architecture
-**Production** → Game SM manages sprints, Game Dev implements
-**Always use fresh chats** for each workflow to avoid context issues.
-:::
-
-## Understanding BMGD
-
-BMGD follows four game development phases with specialized agents for each:
-
-| Phase | Name          | What Happens                                                      |
-| ----- | ------------- | ----------------------------------------------------------------- |
-| 1     | Preproduction | Capture game vision, create Game Brief *(optional brainstorming)* |
-| 2     | Design        | Detail mechanics, systems, narrative in GDD                       |
-| 3     | Technical     | Plan engine, architecture, technical decisions                    |
-| 4     | Production    | Build game in sprints, story by story                             |
-
-![BMGD Workflow Overview](./images/workflow-overview.jpg)
-
-*Complete visual flowchart showing all phases, workflows, and agents for game development.*
-
-### Game Development Agents
-
-| Agent                 | When to Use                               |
-| --------------------- | ----------------------------------------- |
-| **Game Designer**     | Brainstorming, Game Brief, GDD, Narrative |
-| **Game Architect**    | Architecture, technical decisions         |
-| **Game Developer**    | Implementation, code reviews              |
-| **Game Scrum Master** | Sprint planning, story management         |
-| **Game QA**           | Test framework, test design, automation   |
-| **Game Solo Dev**     | Quick prototyping, indie development      |
-
-## Installation
-
-If you haven't installed BMad yet:
-
-```bash
-npx bmad-method install
-```
-
-Or add BMGD to an existing installation:
-
-```bash
-npx bmad-method install --add-module bmgd
-```
-
-Verify your installation:
-
-```
-your-project/
-├── _bmad/
-│   ├── bmgd/           # Game development module
-│   │   ├── agents/     # Game-specific agents
-│   │   ├── workflows/  # Game-specific workflows
-│   │   └── config.yaml # Module config
-│   ├── bmm/            # Core method module
-│   └── core/           # Core utilities
-├── _bmad-output/       # Generated artifacts (created later)
-└── .claude/            # IDE configuration (if using Claude Code)
-```
-
-## Step 1: Create Your Game Brief (Preproduction)
-
-Load the **Game Designer** agent in your IDE, wait for the menu, then start with your game concept.
-
-### Optional: Brainstorm First
-
-If you have a vague idea and want help developing it:
-
-```
-Run brainstorm-game
-```
-
-The agent guides you through game-specific ideation techniques to refine your concept.
-
-### Create the Game Brief
-
-```
-Run create-game-brief
-```
-
-The Game Designer walks you through:
-- **Game concept** — Core idea and unique selling points
-- **Design pillars** — The 3-5 principles that guide all decisions
-- **Target market** — Who plays this game?
-- **Fundamentals** — Platform, genre, scope, team size
-
-When complete, you'll have `game-brief.md` in your `_bmad-output/` folder.
-
-:::caution[Fresh Chats]
-Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
-:::
-
-## Step 2: Design Your Game
-
-With your Game Brief complete, detail your game's design.
-
-### Create the GDD
-
-**Start a fresh chat** with the **Game Designer** agent.
-
-```
-Run create-gdd
-```
-
-The agent guides you through mechanics, systems, and game-type-specific sections. BMGD offers 24 game type templates that provide genre-specific structure.
-
-When complete, you'll have `gdd.md` (or sharded into `gdd/` for large documents).
-
-:::note[Narrative Design (Optional)]
-For story-driven games, start a fresh chat and run `narrative` to create a Narrative Design Document covering story, characters, world, and dialogue.
-:::
-
-:::tip[Check Your Status]
-Unsure what's next? Load any agent and run `workflow-status`. It tells you the next recommended workflow.
-:::
-
-## Step 3: Plan Your Architecture
-
-**Start a fresh chat** with the **Game Architect** agent.
-
-```
-Run create-architecture
-```
-
-The architect guides you through:
-- **Engine selection** — Unity, Unreal, Godot, custom, etc.
-- **System design** — Core game systems and how they interact
-- **Technical patterns** — Architecture patterns suited to your game
-- **Structure** — Project organization and conventions
-
-When complete, you'll have `game-architecture.md`.
-
-## Step 4: Build Your Game
-
-Once planning is complete, move to production. **Each workflow should run in a fresh chat.**
-
-### Initialize Sprint Planning
-
-Load the **Game Scrum Master** agent and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories.
-
-### The Build Cycle
-
-For each story, repeat this cycle with fresh chats:
-
-| Step | Agent    | Workflow       | Purpose                            |
-| ---- | -------- | -------------- | ---------------------------------- |
-| 1    | Game SM  | `create-story` | Create story file from epic        |
-| 2    | Game Dev | `dev-story`    | Implement the story                |
-| 3    | Game QA  | `automate`     | Generate tests *(optional)*        |
-| 4    | Game Dev | `code-review`  | Quality validation *(recommended)* |
-
-After completing all stories in an epic, load the **Game SM** and run `retrospective`.
-
-### Quick Prototyping Alternative
-
-For rapid iteration or indie development, load the **Game Solo Dev** agent:
-- `quick-prototype` — Rapid prototyping
-- `quick-dev` — Flexible development without full sprint structure
-
-## What You've Accomplished
-
-You've learned the foundation of building games with BMad:
-
-- Installed the BMGD module
-- Created a Game Brief capturing your vision
-- Detailed your design in a GDD
-- Planned your technical architecture
-- Understood the build cycle for implementation
-
-Your project now has:
-
-```
-your-project/
-├── _bmad/                         # BMad configuration
-├── _bmad-output/
-│   ├── game-brief.md              # Your game vision
-│   ├── gdd.md                     # Game Design Document
-│   ├── narrative-design.md        # Story design (if applicable)
-│   ├── game-architecture.md       # Technical decisions
-│   ├── epics/                     # Epic and story files
-│   └── sprint-status.yaml         # Sprint tracking
-└── ...
-```
-
-## Quick Reference
-
-| Command                | Agent          | Purpose                       |
-| ---------------------- | -------------- | ----------------------------- |
-| `*brainstorm-game`     | Game Designer  | Guided game ideation          |
-| `*create-game-brief`   | Game Designer  | Create Game Brief             |
-| `*create-gdd`          | Game Designer  | Create Game Design Document   |
-| `*narrative`           | Game Designer  | Create Narrative Design       |
-| `*create-architecture` | Game Architect | Create game architecture      |
-| `*sprint-planning`     | Game SM        | Initialize sprint tracking    |
-| `*create-story`        | Game SM        | Create a story file           |
-| `*dev-story`           | Game Dev       | Implement a story             |
-| `*code-review`         | Game Dev       | Review implemented code       |
-| `*workflow-status`     | Any            | Check progress and next steps |
-
-## Common Questions
-
-**Do I need to create all documents?**
-At minimum, create a Game Brief and GDD. Architecture is highly recommended. Narrative Design is only needed for story-driven games.
-
-**Can I use the Game Solo Dev for everything?**
-Yes, for smaller projects or rapid prototyping. For larger games, the specialized agents provide more thorough guidance.
-
-**What game types are supported?**
-BMGD includes 24 game type templates (RPG, platformer, puzzle, strategy, etc.) that provide genre-specific GDD sections.
-
-**Can I change my design later?**
-Yes. Documents are living artifacts—return to update them as your vision evolves. The SM agent has `correct-course` for scope changes.
-
-## Getting Help
-
-- **During workflows** — Agents guide you with questions and explanations
-- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
-- **Documentation** — [BMGD Workflow Reference](/docs/reference/workflows/bmgd-workflows.md)
-- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)
-
-## Key Takeaways
-
-:::tip[Remember These]
-- **Always use fresh chats** — Load agents in new chats for each workflow
-- **Game Brief first** — It informs everything that follows
-- **Use game type templates** — 24 templates provide genre-specific GDD structure
-- **Documents evolve** — Return to update them as your vision grows
-- **Solo Dev for speed** — Use Game Solo Dev for rapid prototyping
-:::
-
-Ready to start? Load the **Game Designer** agent and run `create-game-brief` to capture your game vision.

src/core/tasks/sync-bug-tracking.xml

@@ -0,0 +1,123 @@
+<task id="{bmad_folder}/core/tasks/sync-bug-tracking.xml" name="Sync Bug Tracking">
+  <objective>Sync bugs.yaml and bugs.md when a story is marked done, updating related bugs to "fixed" and features to "implemented"</objective>
+
+  <description>
+    This task is invoked by workflows (story-done, code-review) after a story is marked done.
+    It searches bugs.yaml for bugs/features linked to the completed story and updates their status.
+    For multi-story features, it only marks "implemented" when ALL linked stories are done.
+  </description>
+
+  <inputs>
+    <input name="story_key" required="true">The story key (e.g., "3-7-checkout-from-club-detail-page")</input>
+    <input name="story_id" required="false">The story ID (e.g., "3.7") - used for related_story matching</input>
+    <input name="bugs_yaml" required="true">Path to bugs.yaml file</input>
+    <input name="bugs_md" required="true">Path to bugs.md file</input>
+    <input name="sprint_status" required="true">Path to sprint-status.yaml file</input>
+    <input name="date" required="true">Current date for timestamps</input>
+  </inputs>
+
+  <outputs>
+    <output name="bugs_updated">List of bug IDs marked as fixed</output>
+    <output name="features_updated">List of feature IDs marked as implemented</output>
+    <output name="features_pending">List of feature IDs with incomplete stories</output>
+  </outputs>
+
+  <flow>
+    <step n="1" goal="Load bugs.yaml and check for existence">
+      <action>Load {bugs_yaml} if it exists</action>
+      <check if="bugs.yaml does not exist">
+        <action>Set bugs_updated = [], features_updated = [], features_pending = []</action>
+        <action>Return early - no bug tracking to sync</action>
+      </check>
+    </step>
+
+    <step n="2" goal="Find matching bugs and features using multiple methods">
+      <action>Initialize: bugs_updated = [], features_updated = [], features_pending = []</action>
+
+      <action>Search for entries matching this story using ALL THREE methods:</action>
+      <action>1. Check sprint-status.yaml for comment "# Source: bugs.yaml/feature-XXX" or "# Source: bugs.yaml/bug-XXX" on the {story_key} line - this is the MOST RELIABLE method</action>
+      <action>2. Check related_story field in bugs.yaml matching {story_id} or {story_key}</action>
+      <action>3. Check sprint_stories arrays in feature_requests for entries containing {story_key}</action>
+
+      <critical>PRIORITY: Use sprint-status comment source if present - it's explicit and unambiguous</critical>
+    </step>
+
+    <step n="3" goal="Update matching bugs">
+      <check if="matching bugs found in bugs section">
+        <action>For each matching bug:</action>
+        <action>- Update status: "triaged" or "routed" or "in-progress" → "fixed"</action>
+        <action>- Set fixed_date: {date}</action>
+        <action>- Set assigned_to: "dev-agent" (if not already set)</action>
+        <action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
+        <action>- Add bug ID to bugs_updated list</action>
+      </check>
+    </step>
+
+    <step n="4" goal="Update matching features (with multi-story check)">
+      <check if="matching features found in feature_requests section">
+        <action>For each matching feature (via related_story OR sprint_stories):</action>
+
+        <critical>MULTI-STORY FEATURE CHECK: If feature has sprint_stories array with multiple entries:</critical>
+        <action>1. Extract all story keys from sprint_stories (format: "story-key: status")</action>
+        <action>2. Load sprint-status.yaml and check development_status for EACH story</action>
+        <action>3. Only proceed if ALL stories in sprint_stories have status "done" in sprint-status.yaml</action>
+        <action>4. If any story is NOT done, add feature to features_pending and log: "Feature {feature_id} has incomplete stories: {incomplete_list}"</action>
+
+        <check if="ALL sprint_stories are done (or feature has single story that matches)">
+          <action>- Update status: "backlog" or "triaged" or "routed" or "in-progress" → "implemented"</action>
+          <action>- Set implemented_date: {date}</action>
+          <action>- Update sprint_stories entries to reflect done status</action>
+          <action>- Append to notes: "Auto-closed via sync-bug-tracking. Story {story_key} marked done on {date}."</action>
+          <action>- Add feature ID to features_updated list</action>
+        </check>
+      </check>
+    </step>
+
+    <step n="5" goal="Save bugs.yaml updates">
+      <check if="bugs_updated is not empty OR features_updated is not empty">
+        <action>Save updated bugs.yaml, preserving all structure and comments</action>
+      </check>
+    </step>
+
+    <step n="6" goal="Update bugs.md to match">
+      <check if="bugs_updated is not empty OR features_updated is not empty">
+        <action>Load {bugs_md}</action>
+
+        <check if="bugs_updated is not empty">
+          <action>For each bug in bugs_updated:</action>
+          <action>- Find the bug entry in "# Tracked Bugs" section</action>
+          <action>- Move it to "# Fixed Bugs" section</action>
+          <action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] bug-XXX: Title [Fixed: {date}, Verified: pending]"</action>
+        </check>
+
+        <check if="features_updated is not empty">
+          <action>For each feature in features_updated:</action>
+          <action>- Find the feature entry in "# Tracked Feature Requests" section</action>
+          <action>- Move it to "# Implemented Features" section</action>
+          <action>- Add [IMPLEMENTED] tag prefix with date: "[IMPLEMENTED] feature-XXX: Title [Implemented: {date}, Verified: pending]"</action>
+        </check>
+
+        <action>Update statistics section if present</action>
+        <action>Save updated bugs.md</action>
+      </check>
+    </step>
+
+    <step n="7" goal="Return results">
+      <output>
+Bug/Feature Sync Results:
+{{#if bugs_updated}}
+- Bugs marked fixed: {{bugs_updated}}
+{{/if}}
+{{#if features_updated}}
+- Features marked implemented: {{features_updated}}
+{{/if}}
+{{#if features_pending}}
+- Features with incomplete stories (not yet implemented): {{features_pending}}
+{{/if}}
+{{#if no_matches}}
+- No related bugs/features found for story {story_key}
+{{/if}}
+      </output>
+    </step>
+  </flow>
+</task>

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/api-documenter.md

@@ -1,102 +0,0 @@
----
-name: bmm-api-documenter
-description: Documents APIs, interfaces, and integration points including REST endpoints, GraphQL schemas, message contracts, and service boundaries. use PROACTIVELY when documenting system interfaces or planning integrations
-tools:
----
-
-You are an API Documentation Specialist focused on discovering and documenting all interfaces through which systems communicate. Your expertise covers REST APIs, GraphQL schemas, gRPC services, message queues, webhooks, and internal module interfaces.
-
-## Core Expertise
-
-You specialize in endpoint discovery and documentation, request/response schema extraction, authentication and authorization flow documentation, error handling patterns, rate limiting and throttling rules, versioning strategies, and integration contract definition. You understand various API paradigms and documentation standards.
-
-## Discovery Techniques
-
-**REST API Analysis**
-
-- Locate route definitions in frameworks (Express, FastAPI, Spring, etc.)
-- Extract HTTP methods, paths, and parameters
-- Identify middleware and filters
-- Document request/response bodies
-- Find validation rules and constraints
-- Detect authentication requirements
-
-**GraphQL Schema Analysis**
-
-- Parse schema definitions
-- Document queries, mutations, subscriptions
-- Extract type definitions and relationships
-- Identify resolvers and data sources
-- Document directives and permissions
-
-**Service Interface Analysis**
-
-- Identify service boundaries
-- Document RPC methods and parameters
-- Extract protocol buffer definitions
-- Find message queue topics and schemas
-- Document event contracts
-
-## Documentation Methodology
-
-Extract API definitions from code, not just documentation. Compare documented behavior with actual implementation. Identify undocumented endpoints and features. Find deprecated endpoints still in use. Document side effects and business logic. Include performance characteristics and limitations.
-
-## Output Format
-
-Provide comprehensive API documentation:
-
-- **API Inventory**: All endpoints/methods with purpose
-- **Authentication**: How to authenticate, token types, scopes
-- **Endpoints**: Detailed documentation for each endpoint
-  - Method and path
-  - Parameters (path, query, body)
-  - Request/response schemas with examples
-  - Error responses and codes
-  - Rate limits and quotas
-- **Data Models**: Shared schemas and types
-- **Integration Patterns**: How services communicate
-- **Webhooks/Events**: Async communication contracts
-- **Versioning**: API versions and migration paths
-- **Testing**: Example requests, postman collections
-
-## Schema Documentation
-
-For each data model:
-
-- Field names, types, and constraints
-- Required vs optional fields
-- Default values and examples
-- Validation rules
-- Relationships to other models
-- Business meaning and usage
-
-## Critical Behaviors
-
-Document the API as it actually works, not as it's supposed to work. Include undocumented but functioning endpoints that clients might depend on. Note inconsistencies in error handling or response formats. Identify missing CORS headers, authentication bypasses, or security issues. Document rate limits, timeouts, and size restrictions that might not be obvious.
-
-For brownfield systems:
-
-- Legacy endpoints maintained for backward compatibility
-- Inconsistent patterns between old and new APIs
-- Undocumented internal APIs used by frontends
-- Hardcoded integrations with external services
-- APIs with multiple authentication methods
-- Versioning strategies (or lack thereof)
-- Shadow APIs created for specific clients
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE API DOCUMENTATION IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all API documentation you've discovered and analyzed in full detail. Do not just describe what you found - provide the complete, formatted API documentation ready for integration.
-
-Include in your final report:
-
-1. Complete API inventory with all endpoints/methods
-2. Full authentication and authorization documentation
-3. Detailed endpoint specifications with schemas
-4. Data models and type definitions
-5. Integration patterns and examples
-6. Any security concerns or inconsistencies found
-
-Remember: Your output will be used directly by the parent agent to populate documentation sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/codebase-analyzer.md

@@ -1,82 +0,0 @@
----
-name: bmm-codebase-analyzer
-description: Performs comprehensive codebase analysis to understand project structure, architecture patterns, and technology stack. use PROACTIVELY when documenting projects or analyzing brownfield codebases
-tools:
----
-
-You are a Codebase Analysis Specialist focused on understanding and documenting complex software projects. Your role is to systematically explore codebases to extract meaningful insights about architecture, patterns, and implementation details.
-
-## Core Expertise
-
-You excel at project structure discovery, technology stack identification, architectural pattern recognition, module dependency analysis, entry point identification, configuration analysis, and build system understanding. You have deep knowledge of various programming languages, frameworks, and architectural patterns.
-
-## Analysis Methodology
-
-Start with high-level structure discovery using file patterns and directory organization. Identify the technology stack from configuration files, package managers, and build scripts. Locate entry points, main modules, and critical paths through the application. Map module boundaries and their interactions. Document actual patterns used, not theoretical best practices. Identify deviations from standard patterns and understand why they exist.
-
-## Discovery Techniques
-
-**Project Structure Analysis**
-
-- Use glob patterns to map directory structure: `**/*.{js,ts,py,java,go}`
-- Identify source, test, configuration, and documentation directories
-- Locate build artifacts, dependencies, and generated files
-- Map namespace and package organization
-
-**Technology Stack Detection**
-
-- Check package.json, requirements.txt, go.mod, pom.xml, Gemfile, etc.
-- Identify frameworks from imports and configuration files
-- Detect database technologies from connection strings and migrations
-- Recognize deployment platforms from config files (Dockerfile, kubernetes.yaml)
-
-**Pattern Recognition**
-
-- Identify architectural patterns: MVC, microservices, event-driven, layered
-- Detect design patterns: factory, repository, observer, dependency injection
-- Find naming conventions and code organization standards
-- Recognize testing patterns and strategies
-
-## Output Format
-
-Provide structured analysis with:
-
-- **Project Overview**: Purpose, domain, primary technologies
-- **Directory Structure**: Annotated tree with purpose of each major directory
-- **Technology Stack**: Languages, frameworks, databases, tools with versions
-- **Architecture Patterns**: Identified patterns with examples and locations
-- **Key Components**: Entry points, core modules, critical services
-- **Dependencies**: External libraries, internal module relationships
-- **Configuration**: Environment setup, deployment configurations
-- **Build and Deploy**: Build process, test execution, deployment pipeline
-
-## Critical Behaviors
-
-Always verify findings with actual code examination, not assumptions. Document what IS, not what SHOULD BE according to best practices. Note inconsistencies and technical debt honestly. Identify workarounds and their reasons. Focus on information that helps other agents understand and modify the codebase. Provide specific file paths and examples for all findings.
-
-When analyzing brownfield projects, pay special attention to:
-
-- Legacy code patterns and their constraints
-- Technical debt accumulation points
-- Integration points with external systems
-- Areas of high complexity or coupling
-- Undocumented tribal knowledge encoded in the code
-- Workarounds and their business justifications
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE CODEBASE ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full codebase analysis you've performed in complete detail. Do not just describe what you analyzed - provide the complete, formatted analysis documentation ready for use.
-
-Include in your final report:
-
-1. Complete project structure with annotated directory tree
-2. Full technology stack identification with versions
-3. All identified architecture and design patterns with examples
-4. Key components and entry points with file paths
-5. Dependency analysis and module relationships
-6. Configuration and deployment details
-7. Technical debt and complexity areas identified
-
-Remember: Your output will be used directly by the parent agent to understand and document the codebase. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/data-analyst.md

@@ -1,101 +0,0 @@
----
-name: bmm-data-analyst
-description: Performs quantitative analysis, market sizing, and metrics calculations. use PROACTIVELY when calculating TAM/SAM/SOM, analyzing metrics, or performing statistical analysis
-tools:
----
-
-You are a Data Analysis Specialist focused on quantitative analysis and market metrics for product strategy. Your role is to provide rigorous, data-driven insights through statistical analysis and market sizing methodologies.
-
-## Core Expertise
-
-You excel at market sizing (TAM/SAM/SOM calculations), statistical analysis and modeling, growth projections and forecasting, unit economics analysis, cohort analysis, conversion funnel metrics, competitive benchmarking, and ROI/NPV calculations.
-
-## Market Sizing Methodology
-
-**TAM (Total Addressable Market)**:
-
-- Use multiple approaches to triangulate: top-down, bottom-up, and value theory
-- Clearly document all assumptions and data sources
-- Provide sensitivity analysis for key variables
-- Consider market evolution over 3-5 year horizon
-
-**SAM (Serviceable Addressable Market)**:
-
-- Apply realistic constraints: geographic, regulatory, technical
-- Consider go-to-market limitations and channel access
-- Account for customer segment accessibility
-
-**SOM (Serviceable Obtainable Market)**:
-
-- Base on realistic market share assumptions
-- Consider competitive dynamics and barriers to entry
-- Factor in execution capabilities and resources
-- Provide year-by-year capture projections
-
-## Analytical Techniques
-
-- **Growth Modeling**: S-curves, adoption rates, network effects
-- **Cohort Analysis**: LTV, CAC, retention, engagement metrics
-- **Funnel Analysis**: Conversion rates, drop-off points, optimization opportunities
-- **Sensitivity Analysis**: Impact of key variable changes
-- **Scenario Planning**: Best/expected/worst case projections
-- **Benchmarking**: Industry standards and competitor metrics
-
-## Data Sources and Validation
-
-Prioritize data quality and source credibility:
-
-- Government statistics and census data
-- Industry reports from reputable firms
-- Public company filings and investor presentations
-- Academic research and studies
-- Trade association data
-- Primary research where available
-
-Always triangulate findings using multiple sources and methodologies. Clearly indicate confidence levels and data limitations.
-
-## Output Standards
-
-Present quantitative findings with:
-
-- Clear methodology explanation
-- All assumptions explicitly stated
-- Sensitivity analysis for key variables
-- Visual representations (charts, graphs)
-- Executive summary with key numbers
-- Detailed calculations in appendix format
-
-## Financial Metrics
-
-Calculate and present key business metrics:
-
-- Customer Acquisition Cost (CAC)
-- Lifetime Value (LTV)
-- Payback period
-- Gross margins
-- Unit economics
-- Break-even analysis
-- Return on Investment (ROI)
-
-## Critical Behaviors
-
-Be transparent about data limitations and uncertainty. Use ranges rather than false precision. Challenge unrealistic growth assumptions. Consider market saturation and competition. Account for market dynamics and disruption potential. Validate findings against real-world benchmarks.
-
-When performing analysis, start with the big picture before drilling into details. Use multiple methodologies to validate findings. Be conservative in projections while identifying upside potential. Consider both quantitative metrics and qualitative factors. Always connect numbers back to strategic implications.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE DATA ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all calculations, metrics, and analysis in full detail. Do not just describe your methodology - provide the complete, formatted analysis with actual numbers and insights.
-
-Include in your final report:
-
-1. All market sizing calculations (TAM, SAM, SOM) with methodology
-2. Complete financial metrics and unit economics
-3. Statistical analysis results with confidence levels
-4. Charts/visualizations descriptions
-5. Sensitivity analysis and scenario planning
-6. Key insights and strategic implications
-
-Remember: Your output will be used directly by the parent agent for decision-making and documentation. Provide complete, ready-to-use analysis with actual numbers, not just methodological descriptions.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-analysis/pattern-detector.md

@@ -1,84 +0,0 @@
----
-name: bmm-pattern-detector
-description: Identifies architectural and design patterns, coding conventions, and implementation strategies used throughout the codebase. use PROACTIVELY when understanding existing code patterns before making modifications
-tools:
----
-
-You are a Pattern Detection Specialist who identifies and documents software patterns, conventions, and practices within codebases. Your expertise helps teams understand the established patterns before making changes, ensuring consistency and avoiding architectural drift.
-
-## Core Expertise
-
-You excel at recognizing architectural patterns (MVC, microservices, layered, hexagonal), design patterns (singleton, factory, observer, repository), coding conventions (naming, structure, formatting), testing patterns (unit, integration, mocking strategies), error handling approaches, logging strategies, and security implementations.
-
-## Pattern Recognition Methodology
-
-Analyze multiple examples to identify patterns rather than single instances. Look for repetition across similar components. Distinguish between intentional patterns and accidental similarities. Identify pattern variations and when they're used. Document anti-patterns and their impact. Recognize pattern evolution over time in the codebase.
-
-## Discovery Techniques
-
-**Architectural Patterns**
-
-- Examine directory structure for layer separation
-- Identify request flow through the application
-- Detect service boundaries and communication patterns
-- Recognize data flow patterns (event-driven, request-response)
-- Find state management approaches
-
-**Code Organization Patterns**
-
-- Naming conventions for files, classes, functions, variables
-- Module organization and grouping strategies
-- Import/dependency organization patterns
-- Comment and documentation standards
-- Code formatting and style consistency
-
-**Implementation Patterns**
-
-- Error handling strategies (try-catch, error boundaries, Result types)
-- Validation approaches (schema, manual, decorators)
-- Data transformation patterns
-- Caching strategies
-- Authentication and authorization patterns
-
-## Output Format
-
-Document discovered patterns with:
-
-- **Pattern Inventory**: List of all identified patterns with frequency
-- **Primary Patterns**: Most consistently used patterns with examples
-- **Pattern Variations**: Where and why patterns deviate
-- **Anti-patterns**: Problematic patterns found with impact assessment
-- **Conventions Guide**: Naming, structure, and style conventions
-- **Pattern Examples**: Code snippets showing each pattern in use
-- **Consistency Report**: Areas following vs violating patterns
-- **Recommendations**: Patterns to standardize or refactor
-
-## Critical Behaviors
-
-Don't impose external "best practices" - document what actually exists. Distinguish between evolving patterns (codebase moving toward something) and inconsistent patterns (random variations). Note when newer code uses different patterns than older code, indicating architectural evolution. Identify "bridge" code that adapts between different patterns.
-
-For brownfield analysis, pay attention to:
-
-- Legacy patterns that new code must interact with
-- Transitional patterns showing incomplete refactoring
-- Workaround patterns addressing framework limitations
-- Copy-paste patterns indicating missing abstractions
-- Defensive patterns protecting against system quirks
-- Performance optimization patterns that violate clean code principles
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE PATTERN ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all identified patterns and conventions in full detail. Do not just list pattern names - provide complete documentation with examples and locations.
-
-Include in your final report:
-
-1. All architectural patterns with code examples
-2. Design patterns identified with specific implementations
-3. Coding conventions and naming patterns
-4. Anti-patterns and technical debt patterns
-5. File locations and specific examples for each pattern
-6. Recommendations for consistency and improvement
-
-Remember: Your output will be used directly by the parent agent to understand the codebase structure and maintain consistency. Provide complete, ready-to-use documentation, not summaries.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/dependency-mapper.md

@@ -1,83 +0,0 @@
----
-name: bmm-dependency-mapper
-description: Maps and analyzes dependencies between modules, packages, and external libraries to understand system coupling and integration points. use PROACTIVELY when documenting architecture or planning refactoring
-tools:
----
-
-You are a Dependency Mapping Specialist focused on understanding how components interact within software systems. Your expertise lies in tracing dependencies, identifying coupling points, and revealing the true architecture through dependency analysis.
-
-## Core Expertise
-
-You specialize in module dependency graphing, package relationship analysis, external library assessment, circular dependency detection, coupling measurement, integration point identification, and version compatibility analysis. You understand various dependency management tools across different ecosystems.
-
-## Analysis Methodology
-
-Begin by identifying the dependency management system (npm, pip, maven, go modules, etc.). Extract declared dependencies from manifest files. Trace actual usage through import/require statements. Map internal module dependencies through code analysis. Identify runtime vs build-time dependencies. Detect hidden dependencies not declared in manifests. Analyze dependency depth and transitive dependencies.
-
-## Discovery Techniques
-
-**External Dependencies**
-
-- Parse package.json, requirements.txt, go.mod, pom.xml, build.gradle
-- Identify direct vs transitive dependencies
-- Check for version constraints and conflicts
-- Assess security vulnerabilities in dependencies
-- Evaluate license compatibility
-
-**Internal Dependencies**
-
-- Trace import/require statements across modules
-- Map service-to-service communications
-- Identify shared libraries and utilities
-- Detect database and API dependencies
-- Find configuration dependencies
-
-**Dependency Quality Metrics**
-
-- Measure coupling between modules (afferent/efferent coupling)
-- Identify highly coupled components
-- Detect circular dependencies
-- Assess stability of dependencies
-- Calculate dependency depth
-
-## Output Format
-
-Provide comprehensive dependency analysis:
-
-- **Dependency Overview**: Total count, depth, critical dependencies
-- **External Libraries**: List with versions, licenses, last update dates
-- **Internal Modules**: Dependency graph showing relationships
-- **Circular Dependencies**: Any cycles detected with involved components
-- **High-Risk Dependencies**: Outdated, vulnerable, or unmaintained packages
-- **Integration Points**: External services, APIs, databases
-- **Coupling Analysis**: Highly coupled areas needing attention
-- **Recommended Actions**: Updates needed, refactoring opportunities
-
-## Critical Behaviors
-
-Always differentiate between declared and actual dependencies. Some declared dependencies may be unused, while some used dependencies might be missing from declarations. Document implicit dependencies like environment variables, file system structures, or network services. Note version pinning strategies and their risks. Identify dependencies that block upgrades or migrations.
-
-For brownfield systems, focus on:
-
-- Legacy dependencies that can't be easily upgraded
-- Vendor-specific dependencies creating lock-in
-- Undocumented service dependencies
-- Hardcoded integration points
-- Dependencies on deprecated or end-of-life technologies
-- Shadow dependencies introduced through copy-paste or vendoring
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE DEPENDENCY ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full dependency mapping and analysis you've developed. Do not just describe what you found - provide the complete, formatted dependency documentation ready for integration.
-
-Include in your final report:
-
-1. Complete external dependency list with versions and risks
-2. Internal module dependency graph
-3. Circular dependencies and coupling analysis
-4. High-risk dependencies and security concerns
-5. Specific recommendations for refactoring or updates
-
-Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/epic-optimizer.md

@@ -1,81 +0,0 @@
----
-name: bmm-epic-optimizer
-description: Optimizes epic boundaries and scope definition for PRDs, ensuring logical sequencing and value delivery. Use PROACTIVELY when defining epic overviews and scopes in PRDs.
-tools:
----
-
-You are an Epic Structure Specialist focused on creating optimal epic boundaries for product development. Your role is to define epic scopes that deliver coherent value while maintaining clear boundaries between development phases.
-
-## Core Expertise
-
-You excel at epic boundary definition, value stream mapping, dependency identification between epics, capability grouping for coherent delivery, priority sequencing for MVP vs post-MVP, risk identification within epic scopes, and success criteria definition.
-
-## Epic Structuring Principles
-
-Each epic must deliver standalone value that users can experience. Group related capabilities that naturally belong together. Minimize dependencies between epics while acknowledging necessary ones. Balance epic size to be meaningful but manageable. Consider deployment and rollout implications. Think about how each epic enables future work.
-
-## Epic Boundary Rules
-
-Epic 1 MUST include foundational elements while delivering initial user value. Each epic should be independently deployable when possible. Cross-cutting concerns (security, monitoring) are embedded within feature epics. Infrastructure evolves alongside features rather than being isolated. MVP epics focus on critical path to value. Post-MVP epics enhance and expand core functionality.
-
-## Value Delivery Focus
-
-Every epic must answer: "What can users do when this is complete?" Define clear before/after states for the product. Identify the primary user journey enabled by each epic. Consider both direct value and enabling value for future work. Map epic boundaries to natural product milestones.
-
-## Sequencing Strategy
-
-Identify critical path items that unlock other epics. Front-load high-risk or high-uncertainty elements. Structure to enable parallel development where possible. Consider go-to-market requirements and timing. Plan for iterative learning and feedback cycles.
-
-## Output Format
-
-For each epic, provide:
-
-- Clear goal statement describing value delivered
-- High-level capabilities (not detailed stories)
-- Success criteria defining "done"
-- Priority designation (MVP/Post-MVP/Future)
-- Dependencies on other epics
-- Key considerations or risks
-
-## Epic Scope Definition
-
-Each epic scope should include:
-
-- Expansion of the goal with context
-- List of 3-7 high-level capabilities
-- Clear success criteria
-- Dependencies explicitly stated
-- Technical or UX considerations noted
-- No detailed story breakdown (comes later)
-
-## Quality Checks
-
-Verify each epic:
-
-- Delivers clear, measurable value
-- Has reasonable scope (not too large or small)
-- Can be understood by stakeholders
-- Aligns with product goals
-- Has clear completion criteria
-- Enables appropriate sequencing
-
-## Critical Behaviors
-
-Challenge epic boundaries that don't deliver coherent value. Ensure every epic can be deployed and validated. Consider user experience continuity across epics. Plan for incremental value delivery. Balance technical foundation with user features. Think about testing and rollback strategies for each epic.
-
-When optimizing epics, start with user journey analysis to find natural boundaries. Identify minimum viable increments for feedback. Plan validation points between epics. Consider market timing and competitive factors. Build quality and operational concerns into epic scopes from the start.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full, formatted epic structure and analysis that you've developed. Do not just describe what you did or would do - provide the actual epic definitions, scopes, and sequencing recommendations in full detail. The parent agent needs this complete content to integrate into the document being built.
-
-Include in your final report:
-
-1. The complete list of optimized epics with all details
-2. Epic sequencing recommendations
-3. Dependency analysis between epics
-4. Any critical insights or recommendations
-
-Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/requirements-analyst.md

@@ -1,61 +0,0 @@
----
-name: bmm-requirements-analyst
-description: Analyzes and refines product requirements, ensuring completeness, clarity, and testability. use PROACTIVELY when extracting requirements from user input or validating requirement quality
-tools:
----
-
-You are a Requirements Analysis Expert specializing in translating business needs into clear, actionable requirements. Your role is to ensure all requirements are specific, measurable, achievable, relevant, and time-bound.
-
-## Core Expertise
-
-You excel at requirement elicitation and extraction, functional and non-functional requirement classification, acceptance criteria development, requirement dependency mapping, gap analysis, ambiguity detection and resolution, and requirement prioritization using established frameworks.
-
-## Analysis Methodology
-
-Extract both explicit and implicit requirements from user input and documentation. Categorize requirements by type (functional, non-functional, constraints), identify missing or unclear requirements, map dependencies and relationships, ensure testability and measurability, and validate alignment with business goals.
-
-## Requirement Quality Standards
-
-Every requirement must be:
-
-- Specific and unambiguous with no room for interpretation
-- Measurable with clear success criteria
-- Achievable within technical and resource constraints
-- Relevant to user needs and business objectives
-- Traceable to specific user stories or business goals
-
-## Output Format
-
-Use consistent requirement ID formatting:
-
-- Functional Requirements: FR1, FR2, FR3...
-- Non-Functional Requirements: NFR1, NFR2, NFR3...
-- Include clear acceptance criteria for each requirement
-- Specify priority levels using MoSCoW (Must/Should/Could/Won't)
-- Document all assumptions and constraints
-- Highlight risks and dependencies with clear mitigation strategies
-
-## Critical Behaviors
-
-Ask clarifying questions for any ambiguous requirements. Challenge scope creep while ensuring completeness. Consider edge cases, error scenarios, and cross-functional impacts. Ensure all requirements support MVP goals and flag any technical feasibility concerns early.
-
-When analyzing requirements, start with user outcomes rather than solutions. Decompose complex requirements into simpler, manageable components. Actively identify missing non-functional requirements like performance, security, and scalability. Ensure consistency across all requirements and validate that each requirement adds measurable value to the product.
-
-## Required Output
-
-You MUST analyze the context and directive provided, then generate and return a comprehensive, visible list of requirements. The type of requirements will depend on what you're asked to analyze:
-
-- **Functional Requirements (FR)**: What the system must do
-- **Non-Functional Requirements (NFR)**: Quality attributes and constraints
-- **Technical Requirements (TR)**: Technical specifications and implementation needs
-- **Integration Requirements (IR)**: External system dependencies
-- **Other requirement types as directed**
-
-Format your output clearly with:
-
-1. The complete list of requirements using appropriate prefixes (FR1, NFR1, TR1, etc.)
-2. Grouped by logical categories with headers
-3. Priority levels (Must-have/Should-have/Could-have) where applicable
-4. Clear, specific, testable requirement descriptions
-
-Ensure the ENTIRE requirements list is visible in your response for user review and approval. Do not summarize or reference requirements without showing them.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/technical-decisions-curator.md

@@ -1,168 +0,0 @@
----
-name: bmm-technical-decisions-curator
-description: Curates and maintains technical decisions document throughout project lifecycle, capturing architecture choices and technology selections. use PROACTIVELY when technical decisions are made or discussed
-tools:
----
-
-# Technical Decisions Curator
-
-## Purpose
-
-Specialized sub-agent for maintaining and organizing the technical-decisions.md document throughout project lifecycle.
-
-## Capabilities
-
-### Primary Functions
-
-1. **Capture and Append**: Add new technical decisions with proper context
-2. **Organize and Categorize**: Structure decisions into logical sections
-3. **Deduplicate**: Identify and merge duplicate or conflicting entries
-4. **Validate**: Ensure decisions align and don't contradict
-5. **Prioritize**: Mark decisions as confirmed vs. preferences vs. constraints
-
-### Decision Categories
-
-- **Confirmed Decisions**: Explicitly agreed technical choices
-- **Preferences**: Non-binding preferences mentioned in discussions
-- **Constraints**: Hard requirements from infrastructure/compliance
-- **To Investigate**: Technical questions needing research
-- **Deprecated**: Decisions that were later changed
-
-## Trigger Conditions
-
-### Automatic Triggers
-
-- Any mention of technology, framework, or tool
-- Architecture pattern discussions
-- Performance or scaling requirements
-- Integration or API mentions
-- Deployment or infrastructure topics
-
-### Manual Triggers
-
-- User explicitly asks to record a decision
-- End of any planning session
-- Before transitioning between agents
-
-## Operation Format
-
-### When Capturing
-
-```markdown
-## [DATE] - [SESSION/AGENT]
-
-**Context**: [Where/how this came up]
-**Decision**: [What was decided/mentioned]
-**Type**: [Confirmed/Preference/Constraint/Investigation]
-**Rationale**: [Why, if provided]
-```
-
-### When Organizing
-
-1. Group related decisions together
-2. Elevate confirmed decisions to top
-3. Flag conflicts for resolution
-4. Summarize patterns (e.g., "Frontend: React ecosystem preferred")
-
-## Integration Points
-
-### Input Sources
-
-- PRD workflow discussions
-- Brief creation sessions
-- Architecture planning
-- Any user conversation mentioning tech
-
-### Output Consumers
-
-- Architecture document creation
-- Solution design documents
-- Technical story generation
-- Development environment setup
-
-## Usage Examples
-
-### Example 1: During PRD Discussion
-
-```
-User: "We'll need to integrate with Stripe for payments"
-Curator Action: Append to technical-decisions.md:
-- **Integration**: Stripe for payment processing (Confirmed - PRD discussion)
-```
-
-### Example 2: Casual Mention
-
-```
-User: "I've been thinking PostgreSQL would be better than MySQL here"
-Curator Action: Append to technical-decisions.md:
-- **Database**: PostgreSQL preferred over MySQL (Preference - user consideration)
-```
-
-### Example 3: Constraint Discovery
-
-```
-User: "We have to use our existing Kubernetes cluster"
-Curator Action: Append to technical-decisions.md:
-- **Infrastructure**: Must use existing Kubernetes cluster (Constraint - existing infrastructure)
-```
-
-## Quality Rules
-
-1. **Never Delete**: Only mark as deprecated, never remove
-2. **Always Date**: Every entry needs timestamp
-3. **Maintain Context**: Include where/why decision was made
-4. **Flag Conflicts**: Don't silently resolve contradictions
-5. **Stay Technical**: Don't capture business/product decisions
-
-## File Management
-
-### Initial Creation
-
-If technical-decisions.md doesn't exist:
-
-```markdown
-# Technical Decisions
-
-_This document captures all technical decisions, preferences, and constraints discovered during project planning._
-
----
-```
-
-### Maintenance Pattern
-
-- Append new decisions at the end during capture
-- Periodically reorganize into sections
-- Keep chronological record in addition to organized view
-- Archive old decisions when projects complete
-
-## Invocation
-
-The curator can be invoked:
-
-1. **Inline**: During any conversation when tech is mentioned
-2. **Batch**: At session end to review and capture
-3. **Review**: To organize and clean up existing file
-4. **Conflict Resolution**: When contradictions are found
-
-## Success Metrics
-
-- No technical decisions lost between sessions
-- Clear traceability of why each technology was chosen
-- Smooth handoff to architecture and solution design phases
-- Reduced repeated discussions about same technical choices
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE TECHNICAL DECISIONS DOCUMENT IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the complete technical-decisions.md content you've curated. Do not just describe what you captured - provide the actual, formatted technical decisions document ready for saving or integration.
-
-Include in your final report:
-
-1. All technical decisions with proper categorization
-2. Context and rationale for each decision
-3. Timestamps and sources
-4. Any conflicts or contradictions identified
-5. Recommendations for resolution if conflicts exist
-
-Remember: Your output will be used directly by the parent agent to save as technical-decisions.md or integrate into documentation. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/trend-spotter.md

@@ -1,115 +0,0 @@
----
-name: bmm-trend-spotter
-description: Identifies emerging trends, weak signals, and future opportunities. use PROACTIVELY when analyzing market trends, identifying disruptions, or forecasting future developments
-tools:
----
-
-You are a Trend Analysis and Foresight Specialist focused on identifying emerging patterns and future opportunities. Your role is to spot weak signals, analyze trend trajectories, and provide strategic insights about future market developments.
-
-## Core Expertise
-
-You specialize in weak signal detection, trend analysis and forecasting, disruption pattern recognition, technology adoption cycles, cultural shift identification, regulatory trend monitoring, investment pattern analysis, and cross-industry innovation tracking.
-
-## Trend Detection Framework
-
-**Weak Signals**: Early indicators of potential change
-
-- Startup activity and funding patterns
-- Patent filings and research papers
-- Regulatory discussions and proposals
-- Social media sentiment shifts
-- Early adopter behaviors
-- Academic research directions
-
-**Trend Validation**: Confirming pattern strength
-
-- Multiple independent data points
-- Geographic spread analysis
-- Adoption velocity measurement
-- Investment flow tracking
-- Media coverage evolution
-- Expert opinion convergence
-
-## Analysis Methodologies
-
-- **STEEP Analysis**: Social, Technological, Economic, Environmental, Political trends
-- **Cross-Impact Analysis**: How trends influence each other
-- **S-Curve Modeling**: Technology adoption and maturity phases
-- **Scenario Planning**: Multiple future possibilities
-- **Delphi Method**: Expert consensus on future developments
-- **Horizon Scanning**: Systematic exploration of future threats and opportunities
-
-## Trend Categories
-
-**Technology Trends**:
-
-- Emerging technologies and their applications
-- Technology convergence opportunities
-- Infrastructure shifts and enablers
-- Development tool evolution
-
-**Market Trends**:
-
-- Business model innovations
-- Customer behavior shifts
-- Distribution channel evolution
-- Pricing model changes
-
-**Social Trends**:
-
-- Generational differences
-- Work and lifestyle changes
-- Values and priority shifts
-- Communication pattern evolution
-
-**Regulatory Trends**:
-
-- Policy direction changes
-- Compliance requirement evolution
-- International regulatory harmonization
-- Industry-specific regulations
-
-## Output Format
-
-Present trend insights with:
-
-- Trend name and description
-- Current stage (emerging/growing/mainstream/declining)
-- Evidence and signals observed
-- Projected timeline and trajectory
-- Implications for the business/product
-- Recommended actions or responses
-- Confidence level and uncertainties
-
-## Strategic Implications
-
-Connect trends to actionable insights:
-
-- First-mover advantage opportunities
-- Risk mitigation strategies
-- Partnership and acquisition targets
-- Product roadmap implications
-- Market entry timing
-- Resource allocation priorities
-
-## Critical Behaviors
-
-Distinguish between fads and lasting trends. Look for convergence of multiple trends creating new opportunities. Consider second and third-order effects. Balance optimism with realistic assessment. Identify both opportunities and threats. Consider timing and readiness factors.
-
-When analyzing trends, cast a wide net initially then focus on relevant patterns. Look across industries for analogous developments. Consider contrarian viewpoints and potential trend reversals. Pay attention to generational differences in adoption. Connect trends to specific business implications and actions.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE TREND ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all identified trends, weak signals, and strategic insights in full detail. Do not just describe what you found - provide the complete, formatted trend analysis ready for integration.
-
-Include in your final report:
-
-1. All identified trends with supporting evidence
-2. Weak signals and emerging patterns
-3. Future opportunities and threats
-4. Strategic recommendations based on trends
-5. Timeline and urgency assessments
-
-Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/user-journey-mapper.md

@@ -1,123 +0,0 @@
----
-name: bmm-user-journey-mapper
-description: Maps comprehensive user journeys to identify touchpoints, friction areas, and epic boundaries. use PROACTIVELY when analyzing user flows, defining MVPs, or aligning development priorities with user value
-tools:
----
-
-# User Journey Mapper
-
-## Purpose
-
-Specialized sub-agent for creating comprehensive user journey maps that bridge requirements to epic planning.
-
-## Capabilities
-
-### Primary Functions
-
-1. **Journey Discovery**: Identify all user types and their paths
-2. **Touchpoint Mapping**: Map every interaction with the system
-3. **Value Stream Analysis**: Connect journeys to business value
-4. **Friction Detection**: Identify pain points and drop-off risks
-5. **Epic Alignment**: Map journeys to epic boundaries
-
-### Journey Types
-
-- **Primary Journeys**: Core value delivery paths
-- **Onboarding Journeys**: First-time user experience
-- **API/Developer Journeys**: Integration and development paths
-- **Admin Journeys**: System management workflows
-- **Recovery Journeys**: Error handling and support paths
-
-## Analysis Patterns
-
-### For UI Products
-
-```
-Discovery → Evaluation → Signup → Activation → Usage → Retention → Expansion
-```
-
-### For API Products
-
-```
-Documentation → Authentication → Testing → Integration → Production → Scaling
-```
-
-### For CLI Tools
-
-```
-Installation → Configuration → First Use → Automation → Advanced Features
-```
-
-## Journey Mapping Format
-
-### Standard Structure
-
-```markdown
-## Journey: [User Type] - [Goal]
-
-**Entry Point**: How they discover/access
-**Motivation**: Why they're here
-**Steps**:
-
-1. [Action] → [System Response] → [Outcome]
-2. [Action] → [System Response] → [Outcome]
-   **Success Metrics**: What indicates success
-   **Friction Points**: Where they might struggle
-   **Dependencies**: Required functionality (FR references)
-```
-
-## Epic Sequencing Insights
-
-### Analysis Outputs
-
-1. **Critical Path**: Minimum journey for value delivery
-2. **Epic Dependencies**: Which epics enable which journeys
-3. **Priority Matrix**: Journey importance vs complexity
-4. **Risk Areas**: High-friction or high-dropout points
-5. **Quick Wins**: Simple improvements with high impact
-
-## Integration with PRD
-
-### Inputs
-
-- Functional requirements
-- User personas from brief
-- Business goals
-
-### Outputs
-
-- Comprehensive journey maps
-- Epic sequencing recommendations
-- Priority insights for MVP definition
-- Risk areas requiring UX attention
-
-## Quality Checks
-
-1. **Coverage**: All user types have journeys
-2. **Completeness**: Journeys cover edge cases
-3. **Traceability**: Each step maps to requirements
-4. **Value Focus**: Clear value delivery points
-5. **Feasibility**: Technically implementable paths
-
-## Success Metrics
-
-- All critical user paths mapped
-- Clear epic boundaries derived from journeys
-- Friction points identified for UX focus
-- Development priorities aligned with user value
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE JOURNEY MAPS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all the user journey maps you've created in full detail. Do not just describe the journeys or summarize findings - provide the complete, formatted journey documentation that can be directly integrated into product documents.
-
-Include in your final report:
-
-1. All user journey maps with complete step-by-step flows
-2. Touchpoint analysis for each journey
-3. Friction points and opportunities identified
-4. Epic boundary recommendations based on journeys
-5. Priority insights for MVP and feature sequencing
-
-Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-planning/user-researcher.md

@@ -1,72 +0,0 @@
----
-name: bmm-user-researcher
-description: Conducts user research, develops personas, and analyzes user behavior patterns. use PROACTIVELY when creating user personas, analyzing user needs, or conducting user journey mapping
-tools:
----
-
-You are a User Research Specialist focused on understanding user needs, behaviors, and motivations to inform product decisions. Your role is to provide deep insights into target users through systematic research and analysis.
-
-## Core Expertise
-
-You specialize in user persona development, behavioral analysis, journey mapping, needs assessment, pain point identification, user interview synthesis, survey design and analysis, and ethnographic research methods.
-
-## Research Methodology
-
-Begin with exploratory research to understand the user landscape. Identify distinct user segments based on behaviors, needs, and goals rather than just demographics. Conduct competitive analysis to understand how users currently solve their problems. Map user journeys to identify friction points and opportunities. Synthesize findings into actionable insights that drive product decisions.
-
-## User Persona Development
-
-Create detailed, realistic personas that go beyond demographics:
-
-- Behavioral patterns and habits
-- Goals and motivations (what they're trying to achieve)
-- Pain points and frustrations with current solutions
-- Technology proficiency and preferences
-- Decision-making criteria
-- Daily workflows and contexts of use
-- Jobs-to-be-done framework application
-
-## Research Techniques
-
-- **Secondary Research**: Mining forums, reviews, social media for user sentiment
-- **Competitor Analysis**: Understanding how users interact with competing products
-- **Trend Analysis**: Identifying emerging user behaviors and expectations
-- **Psychographic Profiling**: Understanding values, attitudes, and lifestyles
-- **User Journey Mapping**: Documenting end-to-end user experiences
-- **Pain Point Analysis**: Identifying and prioritizing user frustrations
-
-## Output Standards
-
-Provide personas in a structured format with:
-
-- Persona name and representative quote
-- Background and context
-- Primary goals and motivations
-- Key frustrations and pain points
-- Current solutions and workarounds
-- Success criteria from their perspective
-- Preferred channels and touchpoints
-
-Include confidence levels for findings and clearly distinguish between validated insights and hypotheses. Provide specific recommendations for product features and positioning based on user insights.
-
-## Critical Behaviors
-
-Look beyond surface-level demographics to understand underlying motivations. Challenge assumptions about user needs with evidence. Consider edge cases and underserved segments. Identify unmet and unarticulated needs. Connect user insights directly to product opportunities. Always ground recommendations in user evidence.
-
-When conducting user research, start with broad exploration before narrowing focus. Use multiple data sources to triangulate findings. Pay attention to what users do, not just what they say. Consider the entire user ecosystem including influencers and decision-makers. Focus on outcomes users want to achieve rather than features they request.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE USER RESEARCH ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all user personas, research findings, and insights in full detail. Do not just describe what you analyzed - provide the complete, formatted user research documentation ready for integration.
-
-Include in your final report:
-
-1. All user personas with complete profiles
-2. User needs and pain points analysis
-3. Behavioral patterns and motivations
-4. Technology comfort levels and preferences
-5. Specific product recommendations based on research
-
-Remember: Your output will be used directly by the parent agent to populate document sections. Provide complete, ready-to-use content, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-research/market-researcher.md

@@ -1,51 +0,0 @@
----
-name: bmm-market-researcher
-description: Conducts comprehensive market research and competitive analysis for product requirements. use PROACTIVELY when gathering market insights, competitor analysis, or user research during PRD creation
-tools:
----
-
-You are a Market Research Specialist focused on providing actionable insights for product development. Your expertise includes competitive landscape analysis, market sizing, user persona development, feature comparison matrices, pricing strategy research, technology trend analysis, and industry best practices identification.
-
-## Research Approach
-
-Start with broad market context, then identify direct and indirect competitors. Analyze feature sets and differentiation opportunities, assess market gaps, and synthesize findings into actionable recommendations that drive product decisions.
-
-## Core Capabilities
-
-- Competitive landscape analysis with feature comparison matrices
-- Market sizing and opportunity assessment
-- User persona development and validation
-- Pricing strategy and business model research
-- Technology trend analysis and emerging disruptions
-- Industry best practices and regulatory considerations
-
-## Output Standards
-
-Structure your findings using tables and lists for easy comparison. Provide executive summaries for each research area with confidence levels for findings. Always cite sources when available and focus on insights that directly impact product decisions. Be objective about competitive strengths and weaknesses, and provide specific, actionable recommendations.
-
-## Research Priorities
-
-1. Current market leaders and their strategies
-2. Emerging competitors and potential disruptions
-3. Unaddressed user pain points and market gaps
-4. Technology enablers and constraints
-5. Regulatory and compliance considerations
-
-When conducting research, challenge assumptions with data, identify both risks and opportunities, and consider multiple market segments. Your goal is to provide the product team with clear, data-driven insights that inform strategic decisions.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE MARKET RESEARCH FINDINGS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include all research findings, competitive analysis, and market insights in full detail. Do not just describe what you researched - provide the complete, formatted research documentation ready for use.
-
-Include in your final report:
-
-1. Complete competitive landscape analysis with feature matrices
-2. Market sizing and opportunity assessment data
-3. User personas and segment analysis
-4. Pricing strategies and business model insights
-5. Technology trends and disruption analysis
-6. Specific, actionable recommendations
-
-Remember: Your output will be used directly by the parent agent for strategic product decisions. Provide complete, ready-to-use research findings, not summaries or references.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-research/tech-debt-auditor.md

@@ -1,106 +0,0 @@
----
-name: bmm-tech-debt-auditor
-description: Identifies and documents technical debt, code smells, and areas requiring refactoring with risk assessment and remediation strategies. use PROACTIVELY when documenting brownfield projects or planning refactoring
-tools:
----
-
-You are a Technical Debt Auditor specializing in identifying, categorizing, and prioritizing technical debt in software systems. Your role is to provide honest assessment of code quality issues, their business impact, and pragmatic remediation strategies.
-
-## Core Expertise
-
-You excel at identifying code smells, detecting architectural debt, assessing maintenance burden, calculating debt interest rates, prioritizing remediation efforts, estimating refactoring costs, and providing risk assessments. You understand that technical debt is often a conscious trade-off and focus on its business impact.
-
-## Debt Categories
-
-**Code-Level Debt**
-
-- Duplicated code and copy-paste programming
-- Long methods and large classes
-- Complex conditionals and deep nesting
-- Poor naming and lack of documentation
-- Missing or inadequate tests
-- Hardcoded values and magic numbers
-
-**Architectural Debt**
-
-- Violated architectural boundaries
-- Tightly coupled components
-- Missing abstractions
-- Inconsistent patterns
-- Outdated technology choices
-- Scaling bottlenecks
-
-**Infrastructure Debt**
-
-- Manual deployment processes
-- Missing monitoring and observability
-- Inadequate error handling and recovery
-- Security vulnerabilities
-- Performance issues
-- Resource leaks
-
-## Analysis Methodology
-
-Scan for common code smells using pattern matching. Measure code complexity metrics (cyclomatic complexity, coupling, cohesion). Identify areas with high change frequency (hot spots). Detect code that violates stated architectural principles. Find outdated dependencies and deprecated API usage. Assess test coverage and quality. Document workarounds and their reasons.
-
-## Risk Assessment Framework
-
-**Impact Analysis**
-
-- How many components are affected?
-- What is the blast radius of changes?
-- Which business features are at risk?
-- What is the performance impact?
-- How does it affect development velocity?
-
-**Debt Interest Calculation**
-
-- Extra time for new feature development
-- Increased bug rates in debt-heavy areas
-- Onboarding complexity for new developers
-- Operational costs from inefficiencies
-- Risk of system failures
-
-## Output Format
-
-Provide comprehensive debt assessment:
-
-- **Debt Summary**: Total items by severity, estimated remediation effort
-- **Critical Issues**: High-risk debt requiring immediate attention
-- **Debt Inventory**: Categorized list with locations and impact
-- **Hot Spots**: Files/modules with concentrated debt
-- **Risk Matrix**: Likelihood vs impact for each debt item
-- **Remediation Roadmap**: Prioritized plan with quick wins
-- **Cost-Benefit Analysis**: ROI for addressing specific debts
-- **Pragmatic Recommendations**: What to fix now vs accept vs plan
-
-## Critical Behaviors
-
-Be honest about debt while remaining constructive. Recognize that some debt is intentional and document the trade-offs. Focus on debt that actively harms the business or development velocity. Distinguish between "perfect code" and "good enough code". Provide pragmatic solutions that can be implemented incrementally.
-
-For brownfield systems, understand:
-
-- Historical context - why debt was incurred
-- Business constraints that prevent immediate fixes
-- Which debt is actually causing pain vs theoretical problems
-- Dependencies that make refactoring risky
-- The cost of living with debt vs fixing it
-- Strategic debt that enabled fast delivery
-- Debt that's isolated vs debt that's spreading
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE TECHNICAL DEBT AUDIT IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full technical debt assessment with all findings and recommendations. Do not just describe the types of debt - provide the complete, formatted audit ready for action.
-
-Include in your final report:
-
-1. Complete debt inventory with locations and severity
-2. Risk assessment matrix with impact analysis
-3. Hot spots and concentrated debt areas
-4. Prioritized remediation roadmap with effort estimates
-5. Cost-benefit analysis for debt reduction
-6. Specific, pragmatic recommendations for immediate action
-
-Remember: Your output will be used directly by the parent agent to plan refactoring and improvements. Provide complete, actionable audit findings, not theoretical discussions.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/document-reviewer.md

@@ -1,102 +0,0 @@
----
-name: bmm-document-reviewer
-description: Reviews and validates product documentation against quality standards and completeness criteria. use PROACTIVELY when finalizing PRDs, architecture docs, or other critical documents
-tools:
----
-
-You are a Documentation Quality Specialist focused on ensuring product documents meet professional standards. Your role is to provide comprehensive quality assessment and specific improvement recommendations for product documentation.
-
-## Core Expertise
-
-You specialize in document completeness validation, consistency and clarity checking, technical accuracy verification, cross-reference validation, gap identification and analysis, readability assessment, and compliance checking against organizational standards.
-
-## Review Methodology
-
-Begin with structure and organization review to ensure logical flow. Check content completeness against template requirements. Validate consistency in terminology, formatting, and style. Assess clarity and readability for the target audience. Verify technical accuracy and feasibility of all claims. Evaluate actionability of recommendations and next steps.
-
-## Quality Criteria
-
-**Completeness**: All required sections populated with appropriate detail. No placeholder text or TODO items remaining. All cross-references valid and accurate.
-
-**Clarity**: Unambiguous language throughout. Technical terms defined on first use. Complex concepts explained with examples where helpful.
-
-**Consistency**: Uniform terminology across the document. Consistent formatting and structure. Aligned tone and level of detail.
-
-**Accuracy**: Technically correct and feasible requirements. Realistic timelines and resource estimates. Valid assumptions and constraints.
-
-**Actionability**: Clear ownership and next steps. Specific success criteria defined. Measurable outcomes identified.
-
-**Traceability**: Requirements linked to business goals. Dependencies clearly mapped. Change history maintained.
-
-## Review Checklist
-
-**Document Structure**
-
-- Logical flow from problem to solution
-- Appropriate section hierarchy and organization
-- Consistent formatting and styling
-- Clear navigation and table of contents
-
-**Content Quality**
-
-- No ambiguous or vague statements
-- Specific and measurable requirements
-- Complete acceptance criteria
-- Defined success metrics and KPIs
-- Clear scope boundaries and exclusions
-
-**Technical Validation**
-
-- Feasible requirements given constraints
-- Realistic implementation timelines
-- Appropriate technology choices
-- Identified risks with mitigation strategies
-- Consideration of non-functional requirements
-
-## Issue Categorization
-
-**CRITICAL**: Blocks document approval or implementation. Missing essential sections, contradictory requirements, or infeasible technical approaches.
-
-**HIGH**: Significant gaps or errors requiring resolution. Ambiguous requirements, missing acceptance criteria, or unclear scope.
-
-**MEDIUM**: Quality improvements needed for clarity. Inconsistent terminology, formatting issues, or missing examples.
-
-**LOW**: Minor enhancements suggested. Typos, style improvements, or additional context that would be helpful.
-
-## Deliverables
-
-Provide an executive summary highlighting overall document readiness and key findings. Include a detailed issue list organized by severity with specific line numbers or section references. Offer concrete improvement recommendations for each issue identified. Calculate a completeness percentage score based on required elements. Provide a risk assessment summary for implementation based on document quality.
-
-## Review Focus Areas
-
-1. **Goal Alignment**: Verify all requirements support stated objectives
-2. **Requirement Quality**: Ensure testability and measurability
-3. **Epic/Story Flow**: Validate logical progression and dependencies
-4. **Technical Feasibility**: Assess implementation viability
-5. **Risk Identification**: Confirm all major risks are addressed
-6. **Success Criteria**: Verify measurable outcomes are defined
-7. **Stakeholder Coverage**: Ensure all perspectives are considered
-8. **Implementation Guidance**: Check for actionable next steps
-
-## Critical Behaviors
-
-Provide constructive feedback with specific examples and improvement suggestions. Prioritize issues by their impact on project success. Consider the document's audience and their needs. Validate against relevant templates and standards. Cross-reference related sections for consistency. Ensure the document enables successful implementation.
-
-When reviewing documents, start with high-level structure and flow before examining details. Validate that examples and scenarios are realistic and comprehensive. Check for missing elements that could impact implementation. Ensure the document provides clear, actionable outcomes for all stakeholders involved.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE DOCUMENT REVIEW IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full review findings with all issues and recommendations. Do not just describe what you reviewed - provide the complete, formatted review report ready for action.
-
-Include in your final report:
-
-1. Executive summary with document readiness assessment
-2. Complete issue list categorized by severity (CRITICAL/HIGH/MEDIUM/LOW)
-3. Specific line/section references for each issue
-4. Concrete improvement recommendations for each finding
-5. Completeness percentage score with justification
-6. Risk assessment and implementation concerns
-
-Remember: Your output will be used directly by the parent agent to improve the document. Provide complete, actionable review findings with specific fixes, not general observations.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/technical-evaluator.md

@@ -1,68 +0,0 @@
----
-name: bmm-technical-evaluator
-description: Evaluates technology choices, architectural patterns, and technical feasibility for product requirements. use PROACTIVELY when making technology stack decisions or assessing technical constraints
-tools:
----
-
-You are a Technical Evaluation Specialist focused on making informed technology decisions for product development. Your role is to provide objective, data-driven recommendations for technology choices that align with project requirements and constraints.
-
-## Core Expertise
-
-You specialize in technology stack evaluation and selection, architectural pattern assessment, performance and scalability analysis, security and compliance evaluation, integration complexity assessment, technical debt impact analysis, and comprehensive cost-benefit analysis for technology choices.
-
-## Evaluation Framework
-
-Assess project requirements and constraints thoroughly before researching technology options. Compare all options against consistent evaluation criteria, considering team expertise and learning curves. Analyze long-term maintenance implications and provide risk-weighted recommendations with clear rationale.
-
-## Evaluation Criteria
-
-Evaluate each technology option against:
-
-- Fit for purpose - does it solve the specific problem effectively
-- Maturity and stability of the technology
-- Community support, documentation quality, and ecosystem
-- Performance characteristics under expected load
-- Security features and compliance capabilities
-- Licensing terms and total cost of ownership
-- Integration capabilities with existing systems
-- Scalability potential for future growth
-- Developer experience and productivity impact
-
-## Deliverables
-
-Provide comprehensive technology comparison matrices showing pros and cons for each option. Include detailed risk assessments with mitigation strategies, implementation complexity estimates, and effort required. Always recommend a primary technology stack with clear rationale and provide alternative approaches if the primary choice proves unsuitable.
-
-## Technical Coverage Areas
-
-- Frontend frameworks and libraries (React, Vue, Angular, Svelte)
-- Backend languages and frameworks (Node.js, Python, Java, Go, Rust)
-- Database technologies including SQL and NoSQL options
-- Cloud platforms and managed services (AWS, GCP, Azure)
-- CI/CD pipelines and DevOps tooling
-- Monitoring, observability, and logging solutions
-- Security frameworks and authentication systems
-- API design patterns (REST, GraphQL, gRPC)
-- Architectural patterns (microservices, serverless, monolithic)
-
-## Critical Behaviors
-
-Avoid technology bias by evaluating all options objectively based on project needs. Consider both immediate requirements and long-term scalability. Account for team capabilities and willingness to adopt new technologies. Balance innovation with proven, stable solutions. Document all decision rationale thoroughly for future reference. Identify potential technical debt early and plan mitigation strategies.
-
-When evaluating technologies, start with problem requirements rather than preferred solutions. Consider the full lifecycle including development, testing, deployment, and maintenance. Evaluate ecosystem compatibility and operational requirements. Always plan for failure scenarios and potential migration paths if technologies need to be changed.
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE TECHNICAL EVALUATION IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full technology assessment with all comparisons and recommendations. Do not just describe the evaluation process - provide the complete, formatted evaluation ready for decision-making.
-
-Include in your final report:
-
-1. Complete technology comparison matrix with scores
-2. Detailed pros/cons analysis for each option
-3. Risk assessment with mitigation strategies
-4. Implementation complexity and effort estimates
-5. Primary recommendation with clear rationale
-6. Alternative approaches and fallback options
-
-Remember: Your output will be used directly by the parent agent to make technology decisions. Provide complete, actionable evaluations with specific recommendations, not general guidelines.

src/modules/bmm/sub-modules/claude-code/sub-agents/bmad-review/test-coverage-analyzer.md

@@ -1,108 +0,0 @@
----
-name: bmm-test-coverage-analyzer
-description: Analyzes test suites, coverage metrics, and testing strategies to identify gaps and document testing approaches. use PROACTIVELY when documenting test infrastructure or planning test improvements
-tools:
----
-
-You are a Test Coverage Analysis Specialist focused on understanding and documenting testing strategies, coverage gaps, and quality assurance approaches in software projects. Your role is to provide realistic assessment of test effectiveness and pragmatic improvement recommendations.
-
-## Core Expertise
-
-You excel at test suite analysis, coverage metric calculation, test quality assessment, testing strategy identification, test infrastructure documentation, CI/CD pipeline analysis, and test maintenance burden evaluation. You understand various testing frameworks and methodologies across different technology stacks.
-
-## Analysis Methodology
-
-Identify testing frameworks and tools in use. Locate test files and categorize by type (unit, integration, e2e). Analyze test-to-code ratios and distribution. Examine assertion patterns and test quality. Identify mocked vs real dependencies. Document test execution times and flakiness. Assess test maintenance burden.
-
-## Discovery Techniques
-
-**Test Infrastructure**
-
-- Testing frameworks (Jest, pytest, JUnit, Go test, etc.)
-- Test runners and configuration
-- Coverage tools and thresholds
-- CI/CD test execution
-- Test data management
-- Test environment setup
-
-**Coverage Analysis**
-
-- Line coverage percentages
-- Branch coverage analysis
-- Function/method coverage
-- Critical path coverage
-- Edge case coverage
-- Error handling coverage
-
-**Test Quality Metrics**
-
-- Test execution time
-- Flaky test identification
-- Test maintenance frequency
-- Mock vs integration balance
-- Assertion quality and specificity
-- Test naming and documentation
-
-## Test Categorization
-
-**By Test Type**
-
-- Unit tests: Isolated component testing
-- Integration tests: Component interaction testing
-- End-to-end tests: Full workflow testing
-- Contract tests: API contract validation
-- Performance tests: Load and stress testing
-- Security tests: Vulnerability scanning
-
-**By Quality Indicators**
-
-- Well-structured: Clear arrange-act-assert pattern
-- Flaky: Intermittent failures
-- Slow: Long execution times
-- Brittle: Break with minor changes
-- Obsolete: Testing removed features
-
-## Output Format
-
-Provide comprehensive testing assessment:
-
-- **Test Summary**: Total tests by type, coverage percentages
-- **Coverage Report**: Areas with good/poor coverage
-- **Critical Gaps**: Untested critical paths
-- **Test Quality**: Flaky, slow, or brittle tests
-- **Testing Strategy**: Patterns and approaches used
-- **Test Infrastructure**: Tools, frameworks, CI/CD integration
-- **Maintenance Burden**: Time spent maintaining tests
-- **Improvement Roadmap**: Prioritized testing improvements
-
-## Critical Behaviors
-
-Focus on meaningful coverage, not just percentages. High coverage doesn't mean good tests. Identify tests that provide false confidence (testing implementation, not behavior). Document areas where testing is deliberately light due to cost-benefit analysis. Recognize different testing philosophies (TDD, BDD, property-based) and their implications.
-
-For brownfield systems:
-
-- Legacy code without tests
-- Tests written after implementation
-- Test suites that haven't kept up with changes
-- Manual testing dependencies
-- Tests that mask rather than reveal problems
-- Missing regression tests for fixed bugs
-- Integration tests as substitutes for unit tests
-- Test data management challenges
-
-## CRITICAL: Final Report Instructions
-
-**YOU MUST RETURN YOUR COMPLETE TEST COVERAGE ANALYSIS IN YOUR FINAL MESSAGE.**
-
-Your final report MUST include the full testing assessment with coverage metrics and improvement recommendations. Do not just describe testing patterns - provide the complete, formatted analysis ready for action.
-
-Include in your final report:
-
-1. Complete test coverage metrics by type and module
-2. Critical gaps and untested paths with risk assessment
-3. Test quality issues (flaky, slow, brittle tests)
-4. Testing strategy evaluation and patterns used
-5. Prioritized improvement roadmap with effort estimates
-6. Specific recommendations for immediate action
-
-Remember: Your output will be used directly by the parent agent to improve test coverage and quality. Provide complete, actionable analysis with specific improvements, not general testing advice.

src/modules/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -214,11 +214,24 @@
       <output>ℹ️ Story status updated (no sprint tracking configured)</output>
     </check>
 
+    <!-- Sync bug tracking when story is marked done -->
+    <check if="{{new_status}} == 'done'">
+      <invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
+        <param name="story_key">{{story_key}}</param>
+        <param name="story_id">{{story_id}}</param>
+        <param name="bugs_yaml">{output_folder}/bugs.yaml</param>
+        <param name="bugs_md">{output_folder}/bugs.md</param>
+        <param name="sprint_status">{sprint_status}</param>
+        <param name="date">{date}</param>
+      </invoke-task>
+    </check>
+
     <output>**✅ Review Complete!**
 
       **Story Status:** {{new_status}}
       **Issues Fixed:** {{fixed_count}}
       **Action Items Created:** {{action_count}}
+      {{#if new_status == "done"}}**Bug/Feature Tracking:** Synced automatically{{/if}}
 
       {{#if new_status == "done"}}Code review complete!{{else}}Address the action items and continue development.{{/if}}
     </output>

src/modules/bmm/workflows/4-implementation/retrospective/instructions.md

@@ -1300,7 +1300,67 @@ Bob (Scrum Master): "See you all when prep work is done. Meeting adjourned!"
 
 </step>
 
-<step n="11" goal="Save Retrospective and Update Sprint Status">
+<step n="11" goal="Sync Epic-Linked Bugs/Features to Closed Status">
+<critical>Check bugs.yaml for bugs/features linked to this epic and close them</critical>
+
+<action>Load {bugs_yaml} if it exists</action>
+
+<check if="bugs.yaml exists">
+  <action>Search for entries with related_epic matching {{epic_number}}</action>
+
+  <action>For bugs section - find bugs with related_epic == {{epic_number}} AND status in ["fixed", "triaged", "routed"]:</action>
+  <check if="matching bugs found">
+    <action>For each matching bug:</action>
+    <action>- Move entry from "bugs" section to "closed_bugs" section</action>
+    <action>- Update status: → "closed"</action>
+    <action>- Set verified_by: "retrospective-workflow"</action>
+    <action>- Set verified_date: {date}</action>
+    <action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
+  </check>
+
+  <action>For feature_requests section - find features with related_epic == {{epic_number}} AND status in ["implemented", "backlog", "in-progress"]:</action>
+  <check if="matching features found">
+    <action>For each matching feature:</action>
+    <action>- Move entry from "feature_requests" section to "implemented_features" section</action>
+    <action>- Update status: → "complete"</action>
+    <action>- Set completed_by: "retrospective-workflow"</action>
+    <action>- Set completed_date: {date}</action>
+    <action>- Append to notes: "Auto-closed via epic retrospective. Epic {{epic_number}} completed on {date}."</action>
+  </check>
+
+  <action>Update statistics section with new counts</action>
+  <action>Save updated bugs.yaml</action>
+
+  <check if="bugs/features were moved">
+    <action>Also update bugs.md:</action>
+    <action>- Remove [IMPLEMENTED] tag from closed items</action>
+    <action>- Move bug entries to "# Fixed Bugs" section if not already there</action>
+    <action>- Move feature entries to "# Implemented Features" section if not already there</action>
+    <action>- Add [CLOSED] or [COMPLETE] tag to indicate final status</action>
+    <action>Save updated bugs.md</action>
+  </check>
+
+  <output>
+Bug/Feature Closure:
+{{#if bugs_closed}}
+- Bugs closed for Epic {{epic_number}}: {{bugs_closed_list}}
+{{/if}}
+{{#if features_completed}}
+- Features completed for Epic {{epic_number}}: {{features_completed_list}}
+{{/if}}
+{{#if no_matches}}
+- No outstanding bugs/features linked to Epic {{epic_number}}
+{{/if}}
+  </output>
+</check>
+
+<check if="bugs.yaml does not exist">
+  <action>Skip bug tracking sync - no bugs.yaml file present</action>
+</check>
+
+</step>
+
+<step n="12" goal="Save Retrospective and Update Sprint Status">
 
 <action>Ensure retrospectives folder exists: {retrospectives_folder}</action>
 <action>Create folder if it doesn't exist</action>
@@ -1356,7 +1416,7 @@ Retrospective document was saved successfully, but {sprint_status_file} may need
 
 </step>
 
-<step n="12" goal="Final Summary and Handoff">
+<step n="13" goal="Final Summary and Handoff">
 
 <output>
 **✅ Retrospective Complete, {user_name}!**

src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -54,5 +54,9 @@ sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
 story_directory: "{implementation_artifacts}"
 retrospectives_folder: "{implementation_artifacts}"
 
+# Bug tracking integration (optional)
+bugs_yaml: "{planning_artifacts}/bugs.yaml"
+bugs_md: "{planning_artifacts}/bugs.md"
+
 standalone: true
 web_bundle: false

src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -48,6 +48,26 @@
     <note>After discovery, these content variables are available: {epics_content} (all epics loaded - uses FULL_LOAD strategy)</note>
   </step>
 
+<step n="1.5" goal="Load bugs.yaml for bug/feature tracking (optional)">
+<action>Check if {bugs_yaml} exists in {planning_artifacts}</action>
+<check if="bugs_yaml exists">
+  <action>Read bugs.yaml using grep to find all bug-NNN and feature-NNN entries</action>
+  <action>For each bug/feature, extract:
+    - ID (e.g., bug-001, feature-003)
+    - Title
+    - Status (triaged, routed, in-progress, fixed/implemented, verified, closed)
+    - Recommended workflow (direct-fix, tech-spec, correct-course, backlog)
+    - Related stories (sprint_stories field for features)
+  </action>
+  <action>Build bug/feature inventory for inclusion in sprint status</action>
+  <action>Track feature-to-story mappings (feature-001 → stories 7-1, 7-2, etc.)</action>
+</check>
+<check if="bugs_yaml does not exist">
+  <output>Note: No bugs.yaml found - bug tracking not enabled for this project.</output>
+  <action>Continue without bug integration</action>
+</check>
+</step>
+
 <step n="2" goal="Build sprint status structure">
 <action>For each epic found, create entries in this order:</action>
 
@@ -65,6 +85,17 @@ development_status:
   epic-1-retrospective: optional
 ```
 
+<action>If bugs.yaml was loaded, add bug/feature sources header comment:</action>
+
+```yaml
+# STORY SOURCES:
+# ==============
+# - epics.md: Primary source ({story_count} stories)
+# - bugs.yaml: Feature-driven stories ({feature_story_count} stories from sprint_stories)
+#   - feature-001: 7-1, 7-2, 7-3 (from sprint_stories field)
+#   - feature-002: 3-7
+```
+
 </step>
 
 <step n="3" goal="Apply intelligent status detection">

src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -33,6 +33,10 @@ variables:
   epics_location: "{planning_artifacts}" # Directory containing epic*.md files
   epics_pattern: "epic*.md" # Pattern to find epic files
 
+  # Bug tracking integration (optional)
+  bugs_yaml: "{planning_artifacts}/bugs.yaml" # Structured bug/feature metadata
+  bugs_md: "{planning_artifacts}/bugs.md" # Human-readable bug tracking
+
   # Output configuration
   status_file: "{implementation_artifacts}/sprint-status.yaml"
 

src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -88,15 +88,31 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
 - IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
   </step>
 
+<step n="2.5" goal="Load bug/feature tracking status (optional)">
+  <action>Check if {bugs_yaml} exists</action>
+  <check if="bugs_yaml exists">
+    <action>Grep for bug-NNN and feature-NNN entries with status field</action>
+    <action>Count items by status: triaged, fixed/implemented (pending verify), verified, closed</action>
+    <action>Identify items needing action:
+      - Items with [IMPLEMENTED] tag → need verification
+      - Items with status "triaged" + workflow "direct-fix" → ready for implementation
+    </action>
+    <action>Store: bugs_pending_verify, bugs_triaged, features_pending_verify, features_triaged</action>
+  </check>
+</step>
+
 <step n="3" goal="Select next action recommendation">
   <action>Pick the next recommended workflow using priority:</action>
   <note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
-  1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
-  2. Else if any story status == review → recommend `code-review` for the first review story
-  3. Else if any story status == ready-for-dev → recommend `dev-story`
-  4. Else if any story status == backlog → recommend `create-story`
-  5. Else if any retrospective status == optional → recommend `retrospective`
-  6. Else → All implementation items done; suggest `workflow-status` to plan next phase
+  <note>Bug verification takes priority over new story work to close the feedback loop</note>
+  1. If any bug/feature has [IMPLEMENTED] tag (pending verify) → recommend `verify` for first pending item
+  2. If any story status == in-progress → recommend `dev-story` for the first in-progress story
+  3. Else if any story status == review → recommend `code-review` for the first review story
+  4. Else if any story status == ready-for-dev → recommend `dev-story`
+  5. Else if any bug status == triaged with workflow == direct-fix → recommend `implement` for first triaged bug
+  6. Else if any story status == backlog → recommend `create-story`
+  7. Else if any retrospective status == optional → recommend `retrospective`
+  8. Else → All implementation items done; suggest `workflow-status` to plan next phase
   <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
 </step>
 
@@ -112,6 +128,11 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
 
 **Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}}
 
+{{#if bugs_yaml_exists}}
+**Bugs:** triaged {{bugs_triaged}}, pending-verify {{bugs_pending_verify}}, closed {{bugs_closed}}
+**Features:** triaged {{features_triaged}}, pending-verify {{features_pending_verify}}, complete {{features_complete}}
+{{/if}}
+
 **Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
 
 {{#if risks}}

src/modules/bmm/workflows/4-implementation/sprint-status/workflow.yaml

@@ -21,6 +21,9 @@ instructions: "{installed_path}/instructions.md"
 variables:
   sprint_status_file: "{implementation_artifacts}/sprint-status.yaml"
   tracking_system: "file-system"
+  # Bug tracking integration (optional)
+  bugs_yaml: "{planning_artifacts}/bugs.yaml"
+  bugs_md: "{planning_artifacts}/bugs.md"
 
 # Smart input file references
 input_file_patterns:

src/modules/bmm/workflows/4-implementation/story-done/instructions.md

@@ -0,0 +1,124 @@
+# Story Approved Workflow Instructions (DEV Agent)
+
+<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This workflow is run by DEV agent AFTER user confirms a story is approved (Definition of Done is complete)</critical>
+<critical>Workflow: Update story file status to Done</critical>
+
+<step n="1" goal="Find reviewed story to mark done" tag="sprint-status">
+
+<check if="{story_path} is provided">
+  <action>Use {story_path} directly</action>
+  <action>Read COMPLETE story file and parse sections</action>
+  <action>Extract story_key from filename or story metadata</action>
+  <action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to mark as done"</action>
+</check>
+
+<check if="{story_path} is NOT provided">
+  <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+  <action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+  <action>Read ALL lines from beginning to end - do not skip any content</action>
+  <action>Parse the development_status section completely</action>
+
+<action>Find FIRST story (reading in order from top to bottom) where: - Key matches pattern: number-number-name (e.g., "1-2-user-auth") - NOT an epic key (epic-X) or retrospective (epic-X-retrospective) - Status value equals "review"
+</action>
+
+  <check if="no story with status 'review' found">
+    <output>No stories with status "review" found
+
+All stories are either still in development or already done.
+
+**Next Steps:**
+
+1. Run `dev-story` to implement stories
+2. Run `code-review` if stories need review first
+3. Check sprint-status.yaml for current story states
+   </output>
+   <action>HALT</action>
+   </check>
+
+<action>Use the first reviewed story found</action>
+<action>Find matching story file in {story_dir} using story_key pattern</action>
+<action>Read the COMPLETE story file</action>
+</check>
+
+<action>Extract story_id and story_title from the story file</action>
+
+<action>Find the "Status:" line (usually at the top)</action>
+<action>Update story file: Change Status to "done"</action>
+
+<action>Add completion notes to Dev Agent Record section:</action>
+<action>Find "## Dev Agent Record" section and add:
+
+```
+### Completion Notes
+**Completed:** {date}
+**Definition of Done:** All acceptance criteria met, code reviewed, tests passing
+```
+
+</action>
+
+<action>Save the story file</action>
+</step>
+
+<step n="2" goal="Update sprint status to done" tag="sprint-status">
+<action>Load the FULL file: {output_folder}/sprint-status.yaml</action>
+<action>Find development_status key matching {story_key}</action>
+<action>Verify current status is "review" (expected previous state)</action>
+<action>Update development_status[{story_key}] = "done"</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="story key not found in file">
+  <output>Story file updated, but could not update sprint-status: {story_key} not found
+
+Story is marked Done in file, but sprint-status.yaml may be out of sync.
+</output>
+</check>
+
+</step>
+
+<step n="3" goal="Sync related bugs/features in bug tracking">
+<critical>Invoke shared task to sync bugs.yaml and bugs.md for this completed story</critical>
+
+<invoke-task path="{project-root}/.bmad/core/tasks/sync-bug-tracking.xml">
+  <param name="story_key">{story_key}</param>
+  <param name="story_id">{story_id}</param>
+  <param name="bugs_yaml">{bugs_yaml}</param>
+  <param name="bugs_md">{bugs_md}</param>
+  <param name="sprint_status">{sprint_status}</param>
+  <param name="date">{date}</param>
+</invoke-task>
+
+</step>
+
+<step n="4" goal="Confirm completion to user">
+
+<output>**Story Approved and Marked Done, {user_name}!**
+
+Story file updated - Status: done
+Sprint status updated: review → done
+
+**Completed Story:**
+
+- **ID:** {story_id}
+- **Key:** {story_key}
+- **Title:** {story_title}
+- **Completed:** {date}
+
+**Next Steps:**
+
+1. Continue with next story in your backlog
+   - Run `create-story` for next backlog story
+   - Or run `dev-story` if ready stories exist
+2. Check epic completion status
+   - Run `retrospective` workflow to check if epic is complete
+   - Epic retrospective will verify all stories are done
+     </output>
+
+</step>
+
+</workflow>

src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml

@@ -0,0 +1,27 @@
+# Story Done Workflow (DEV Agent)
+name: story-done
+description: 'Marks a story as done (DoD complete), updates sprint-status → DONE, and syncs related bugs/features in bugs.yaml/bugs.md to [IMPLEMENTED] status.'
+author: 'BMad'
+
+# Critical variables from config
+config_source: '{project-root}/.bmad/bmm/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+sprint_status: '{output_folder}/sprint-status.yaml'
+
+# Workflow components
+installed_path: '{project-root}/.bmad/bmm/workflows/4-implementation/story-done'
+instructions: '{installed_path}/instructions.md'
+
+# Variables and inputs
+variables:
+  story_dir: '{config_source}:dev_ephemeral_location/stories' # Directory where stories are stored
+  bugs_yaml: '{output_folder}/bugs.yaml' # Bug/feature tracking structured data
+  bugs_md: '{output_folder}/bugs.md' # Bug/feature tracking human-readable log
+
+# Output configuration - no output file, just status updates
+default_output_file: ''
+
+standalone: true

src/modules/bmm/workflows/bug-tracking/reference-implementation.md

@@ -0,0 +1,542 @@
+# In-App Bug Reporting - Reference Implementation
+
+This document provides a reference implementation for adding **in-app bug reporting** to your project. The BMAD bug-tracking workflow works without this feature (using manual `bugs.md` input), but in-app reporting provides a better user experience.
+
+## Overview
+
+The in-app bug reporting feature allows users to submit bug reports directly from your application. Reports are stored in your database and then synced to `bugs.md` by the triage workflow.
+
+```
+User -> UI Modal -> API -> Database -> Triage Workflow -> bugs.md/bugs.yaml
+```
+
+## Components Required
+
+| Component | Purpose | Stack-Specific |
+|-----------|---------|----------------|
+| Database table | Store pending bug reports | Yes |
+| API: Create report | Accept user submissions | Yes |
+| API: Get pending | Fetch unsynced reports | Yes |
+| API: Mark synced | Update status after sync | Yes |
+| UI Modal | Bug report form | Yes |
+| Validation schemas | Input validation | Partially |
+
+## 1. Database Schema
+
+### Drizzle ORM (PostgreSQL)
+
+```typescript
+// src/lib/server/db/schema.ts
+
+import { pgTable, uuid, text, timestamp, index } from 'drizzle-orm/pg-core';
+
+export const bugReports = pgTable(
+  'bug_reports',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    organizationId: uuid('organization_id').notNull(), // For multi-tenant apps
+    reporterType: text('reporter_type').notNull(),     // 'staff' | 'member' | 'user'
+    reporterId: uuid('reporter_id').notNull(),
+    title: text('title').notNull(),
+    description: text('description').notNull(),
+    userAgent: text('user_agent'),
+    pageUrl: text('page_url'),
+    platform: text('platform'),                        // 'Windows', 'macOS', 'iOS', etc.
+    browser: text('browser'),                          // 'Chrome', 'Safari', 'Firefox'
+    screenshotUrl: text('screenshot_url'),             // Optional: cloud storage URL
+    status: text('status').notNull().default('new'),   // 'new' | 'synced' | 'dismissed'
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    syncedAt: timestamp('synced_at', { withTimezone: true })
+  },
+  (table) => [
+    index('bug_reports_organization_id_idx').on(table.organizationId),
+    index('bug_reports_status_idx').on(table.status),
+    index('bug_reports_created_at_idx').on(table.createdAt)
+  ]
+);
+
+export const BUG_REPORT_STATUS = {
+  NEW: 'new',
+  SYNCED: 'synced',
+  DISMISSED: 'dismissed'
+} as const;
+
+export const REPORTER_TYPE = {
+  STAFF: 'staff',
+  MEMBER: 'member',
+  USER: 'user'
+} as const;
+```
+
+### Prisma Schema
+
+```prisma
+model BugReport {
+  id              String    @id @default(uuid())
+  organizationId  String    @map("organization_id")
+  reporterType    String    @map("reporter_type")
+  reporterId      String    @map("reporter_id")
+  title           String
+  description     String
+  userAgent       String?   @map("user_agent")
+  pageUrl         String?   @map("page_url")
+  platform        String?
+  browser         String?
+  screenshotUrl   String?   @map("screenshot_url")
+  status          String    @default("new")
+  createdAt       DateTime  @default(now()) @map("created_at")
+  syncedAt        DateTime? @map("synced_at")
+
+  @@index([organizationId])
+  @@index([status])
+  @@index([createdAt])
+  @@map("bug_reports")
+}
+```
+
+## 2. Validation Schemas
+
+### Zod (TypeScript)
+
+```typescript
+// src/lib/schemas/bug-report.ts
+
+import { z } from 'zod';
+
+export const createBugReportSchema = z.object({
+  title: z
+    .string()
+    .trim()
+    .min(5, 'Title must be at least 5 characters')
+    .max(200, 'Title must be 200 characters or less'),
+  description: z
+    .string()
+    .trim()
+    .min(10, 'Description must be at least 10 characters')
+    .max(5000, 'Description must be 5000 characters or less'),
+  pageUrl: z.string().url().optional(),
+  userAgent: z.string().max(1000).optional(),
+  platform: z.string().max(50).optional(),
+  browser: z.string().max(50).optional()
+});
+
+export const markSyncedSchema = z.object({
+  ids: z.array(z.string().uuid()).min(1, 'At least one ID is required')
+});
+
+export const SCREENSHOT_CONFIG = {
+  maxSizeBytes: 5 * 1024 * 1024, // 5MB
+  maxSizeMB: 5,
+  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'] as const
+} as const;
+```
+
+## 3. API Endpoints
+
+### POST /api/bug-reports - Create Report
+
+```typescript
+// SvelteKit: src/routes/api/bug-reports/+server.ts
+
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { db } from '$lib/server/db';
+import { bugReports } from '$lib/server/db/schema';
+import { createBugReportSchema } from '$lib/schemas/bug-report';
+
+export const POST: RequestHandler = async ({ request, locals }) => {
+  // Determine reporter from auth context
+  if (!locals.user) {
+    return json({ error: { code: 'UNAUTHORIZED' } }, { status: 401 });
+  }
+
+  const body = await request.json();
+  const result = createBugReportSchema.safeParse(body);
+
+  if (!result.success) {
+    return json({
+      error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message }
+    }, { status: 400 });
+  }
+
+  const { title, description, pageUrl, userAgent, platform, browser } = result.data;
+
+  const [newReport] = await db
+    .insert(bugReports)
+    .values({
+      organizationId: locals.user.organizationId,
+      reporterType: 'staff',
+      reporterId: locals.user.id,
+      title,
+      description,
+      pageUrl,
+      userAgent,
+      platform,
+      browser
+    })
+    .returning();
+
+  return json({
+    data: {
+      bugReport: {
+        id: newReport.id,
+        title: newReport.title,
+        createdAt: newReport.createdAt.toISOString()
+      }
+    }
+  }, { status: 201 });
+};
+```
+
+### GET /api/bug-reports/pending - Fetch for Triage
+
+```typescript
+// SvelteKit: src/routes/api/bug-reports/pending/+server.ts
+
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { db } from '$lib/server/db';
+import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema';
+import { eq } from 'drizzle-orm';
+
+export const GET: RequestHandler = async () => {
+  const reports = await db
+    .select()
+    .from(bugReports)
+    .where(eq(bugReports.status, BUG_REPORT_STATUS.NEW))
+    .orderBy(bugReports.createdAt);
+
+  // Map to workflow-expected format
+  const formatted = reports.map((r) => ({
+    id: r.id,
+    title: r.title,
+    description: r.description,
+    reporterType: r.reporterType,
+    reporterName: 'Unknown', // Join with users table for real name
+    platform: r.platform,
+    browser: r.browser,
+    pageUrl: r.pageUrl,
+    screenshotUrl: r.screenshotUrl,
+    createdAt: r.createdAt.toISOString()
+  }));
+
+  return json({
+    data: {
+      reports: formatted,
+      count: formatted.length
+    }
+  });
+};
+```
+
+### POST /api/bug-reports/mark-synced - Update After Sync
+
+```typescript
+// SvelteKit: src/routes/api/bug-reports/mark-synced/+server.ts
+
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { db } from '$lib/server/db';
+import { bugReports, BUG_REPORT_STATUS } from '$lib/server/db/schema';
+import { inArray } from 'drizzle-orm';
+import { markSyncedSchema } from '$lib/schemas/bug-report';
+
+export const POST: RequestHandler = async ({ request }) => {
+  const body = await request.json();
+  const result = markSyncedSchema.safeParse(body);
+
+  if (!result.success) {
+    return json({
+      error: { code: 'VALIDATION_ERROR', message: result.error.issues[0]?.message }
+    }, { status: 400 });
+  }
+
+  const updated = await db
+    .update(bugReports)
+    .set({
+      status: BUG_REPORT_STATUS.SYNCED,
+      syncedAt: new Date()
+    })
+    .where(inArray(bugReports.id, result.data.ids))
+    .returning({ id: bugReports.id });
+
+  return json({
+    data: {
+      updatedCount: updated.length,
+      updatedIds: updated.map((r) => r.id)
+    }
+  });
+};
+```
+
+## 4. UI Component
+
+### Svelte 5 (with shadcn-svelte)
+
+```svelte
+<!-- src/lib/components/BugReportModal.svelte -->
+<script lang="ts">
+  import * as Dialog from '$lib/components/ui/dialog';
+  import { Button } from '$lib/components/ui/button';
+  import { Input } from '$lib/components/ui/input';
+  import { Textarea } from '$lib/components/ui/textarea';
+  import { toast } from 'svelte-sonner';
+  import { Bug } from 'lucide-svelte';
+  import { browser } from '$app/environment';
+
+  interface Props {
+    open: boolean;
+    onClose: () => void;
+  }
+
+  let { open = $bindable(), onClose }: Props = $props();
+
+  let title = $state('');
+  let description = $state('');
+  let loading = $state(false);
+
+  // Auto-detect environment
+  let platform = $derived(browser ? detectPlatform() : '');
+  let browserName = $derived(browser ? detectBrowser() : '');
+  let currentUrl = $derived(browser ? window.location.href : '');
+
+  function detectPlatform(): string {
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
+    if (ua.includes('android')) return 'Android';
+    if (ua.includes('mac')) return 'macOS';
+    if (ua.includes('win')) return 'Windows';
+    return 'Unknown';
+  }
+
+  function detectBrowser(): string {
+    const ua = navigator.userAgent;
+    if (ua.includes('Chrome') && !ua.includes('Edg')) return 'Chrome';
+    if (ua.includes('Safari') && !ua.includes('Chrome')) return 'Safari';
+    if (ua.includes('Firefox')) return 'Firefox';
+    if (ua.includes('Edg')) return 'Edge';
+    return 'Unknown';
+  }
+
+  async function handleSubmit() {
+    loading = true;
+    try {
+      const response = await fetch('/api/bug-reports', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          title,
+          description,
+          pageUrl: currentUrl,
+          userAgent: navigator.userAgent,
+          platform,
+          browser: browserName
+        })
+      });
+
+      if (!response.ok) {
+        const data = await response.json();
+        toast.error(data.error?.message || 'Failed to submit');
+        return;
+      }
+
+      toast.success('Bug report submitted');
+      onClose();
+    } finally {
+      loading = false;
+    }
+  }
+</script>
+
+<Dialog.Root bind:open onOpenChange={(o) => !o && onClose()}>
+  <Dialog.Content class="sm:max-w-[500px]">
+    <Dialog.Header>
+      <Dialog.Title class="flex items-center gap-2">
+        <Bug class="h-5 w-5" />
+        Report a Bug
+      </Dialog.Title>
+    </Dialog.Header>
+
+    <form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }} class="space-y-4">
+      <div>
+        <Input bind:value={title} placeholder="Brief summary" maxlength={200} />
+      </div>
+      <div>
+        <Textarea bind:value={description} placeholder="What happened?" rows={4} />
+      </div>
+      <div class="rounded-md bg-muted p-3 text-sm text-muted-foreground">
+        {platform} / {browserName}
+      </div>
+      <Dialog.Footer>
+        <Button variant="outline" onclick={onClose} disabled={loading}>Cancel</Button>
+        <Button type="submit" disabled={loading}>Submit</Button>
+      </Dialog.Footer>
+    </form>
+  </Dialog.Content>
+</Dialog.Root>
+```
+
+### React (with shadcn/ui)
+
+```tsx
+// src/components/BugReportModal.tsx
+
+import { useState } from 'react';
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import { Bug } from 'lucide-react';
+import { toast } from 'sonner';
+
+interface Props {
+  open: boolean;
+  onClose: () => void;
+}
+
+export function BugReportModal({ open, onClose }: Props) {
+  const [title, setTitle] = useState('');
+  const [description, setDescription] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const detectPlatform = () => {
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('iphone') || ua.includes('ipad')) return 'iOS';
+    if (ua.includes('android')) return 'Android';
+    if (ua.includes('mac')) return 'macOS';
+    if (ua.includes('win')) return 'Windows';
+    return 'Unknown';
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+
+    try {
+      const response = await fetch('/api/bug-reports', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          title,
+          description,
+          pageUrl: window.location.href,
+          userAgent: navigator.userAgent,
+          platform: detectPlatform()
+        })
+      });
+
+      if (!response.ok) throw new Error('Failed to submit');
+      toast.success('Bug report submitted');
+      onClose();
+    } catch {
+      toast.error('Failed to submit bug report');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={(o) => !o && onClose()}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Bug className="h-5 w-5" />
+            Report a Bug
+          </DialogTitle>
+        </DialogHeader>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <Input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Brief summary" />
+          <Textarea value={description} onChange={(e) => setDescription(e.target.value)} placeholder="What happened?" />
+          <DialogFooter>
+            <Button variant="outline" onClick={onClose} disabled={loading}>Cancel</Button>
+            <Button type="submit" disabled={loading}>Submit</Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## 5. Workflow Configuration
+
+Update your project's `.bmad/bmm/config.yaml` to set the `project_url`:
+
+```yaml
+# .bmad/bmm/config.yaml
+
+project_url: "http://localhost:5173"  # Dev
+# project_url: "https://your-app.com"  # Prod
+```
+
+The triage workflow will use this to call your API endpoints.
+
+## 6. API Response Format
+
+The workflow expects these response formats:
+
+### GET /api/bug-reports/pending
+
+```json
+{
+  "data": {
+    "reports": [
+      {
+        "id": "uuid",
+        "title": "Bug title",
+        "description": "Bug description",
+        "reporterType": "staff",
+        "reporterName": "John Doe",
+        "platform": "macOS",
+        "browser": "Chrome",
+        "pageUrl": "https://...",
+        "screenshotUrl": "https://...",
+        "createdAt": "2025-01-01T00:00:00Z"
+      }
+    ],
+    "count": 1
+  }
+}
+```
+
+### POST /api/bug-reports/mark-synced
+
+Request:
+```json
+{ "ids": ["uuid1", "uuid2"] }
+```
+
+Response:
+```json
+{
+  "data": {
+    "updatedCount": 2,
+    "updatedIds": ["uuid1", "uuid2"]
+  }
+}
+```
+
+## 7. Optional: Screenshot Storage
+
+For screenshot uploads, you'll need cloud storage (R2, S3, etc.):
+
+1. Create an upload endpoint: `POST /api/bug-reports/[id]/upload-screenshot`
+2. Upload to cloud storage
+3. Update `screenshotUrl` on the bug report record
+
+## 8. Security Considerations
+
+- **Authentication**: Create endpoint should require auth
+- **API Key**: Consider adding API key auth for pending/mark-synced endpoints in production
+- **Rate Limiting**: Add rate limits to prevent spam
+- **Input Sanitization**: Validate all user input (handled by Zod schemas)
+
+## Without In-App Reporting
+
+If you don't implement in-app reporting, the workflow still works:
+
+1. Users manually add bugs to `docs/bugs.md` under `# manual input`
+2. Run `/triage` to process them
+3. Workflow skips Step 0 (API sync) when no API is available
+
+The workflows are designed to be flexible and work with or without the in-app feature.

src/modules/bmm/workflows/bug-tracking/steps/step-01-init.md

@@ -0,0 +1,167 @@
+# Step 1: Bug Tracking Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete triage
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize bugs.yaml if needed
+- 📖 Track workflow state for potential continuation
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- bugs.yaml tracks all structured bug metadata
+- bugs.md is the user-facing input file
+- Don't assume knowledge from other steps
+
+## YOUR TASK:
+
+Initialize the Bug Tracking workflow by detecting existing state, discovering input files, and setting up for collaborative triage.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Session
+
+First, check workflow state:
+
+- Look for existing `{bugs_output}` (bugs.yaml)
+- If exists, grep for bugs with `status: triaged` (pending implementation)
+- Check `{bugs_input}` (bugs.md) for items in "# manual input" section
+
+### 2. Handle Continuation (If Pending Work Exists)
+
+If bugs.yaml exists with triaged bugs awaiting action:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with fresh initialization
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Pending Work)
+
+If no bugs.yaml exists OR no pending triaged bugs:
+
+#### A. Input File Discovery
+
+Discover and validate required files:
+
+**Required Files:**
+- `{bugs_input}` (bugs.md) - User-facing bug reports
+  - Must have "# manual input" section for new bugs
+  - May have "# Tracked Bugs" and "# Fixed Bugs" sections
+
+**Optional Context Files:**
+- `{sprint_status}` - Current sprint context (which stories are in progress)
+- `{epics_file}` - For mapping bugs to related stories/epics
+
+#### B. Initialize bugs.yaml (If Not Exists)
+
+If bugs.yaml doesn't exist, create it with header structure:
+
+```yaml
+# Bug Tracking Database
+# Generated by bug-tracking workflow
+# Last updated: {date}
+
+# Severity Definitions:
+# - critical: Prevents core functionality, crashes, data loss
+# - high: Blocks major features, significantly degrades UX
+# - medium: Affects subset of users, minor impact with workaround
+# - low: Cosmetic, edge case, or minor inconvenience
+
+# Complexity Definitions:
+# - trivial: One-line fix, obvious solution
+# - small: Single file/component, solution clear
+# - medium: Multiple files OR requires investigation
+# - complex: Architectural change, affects many areas
+
+# Workflow Routing Matrix:
+# - critical + any → correct-course
+# - high + trivial → direct-fix
+# - high + small → tech-spec
+# - high + medium/complex → correct-course
+# - medium + trivial → direct-fix
+# - medium + small → tech-spec
+# - medium + medium/complex → correct-course
+# - low + trivial → direct-fix
+# - low + small/medium/complex → backlog
+
+bugs: []
+features: []
+closed_bugs: []
+
+statistics:
+  total_active: 0
+  by_severity:
+    critical: 0
+    high: 0
+    medium: 0
+    low: 0
+  last_updated: {date}
+```
+
+#### C. Scan for New Bugs
+
+Read ONLY the "# manual input" section from bugs.md:
+- Grep for "# manual input" to find starting line
+- Grep for next section header to find ending line
+- Read just that range (do NOT read entire file)
+
+Count items found in manual input section.
+
+#### D. Complete Initialization and Report
+
+Report to user:
+
+"Welcome {user_name}! I've initialized the Bug Tracking workspace for {project_name}.
+
+**Files Status:**
+- bugs.md: {found/created} - {count} item(s) in manual input section
+- bugs.yaml: {found/created} - {active_count} active bugs tracked
+
+**Context Files:**
+- Sprint Status: {loaded/not found}
+- Epics: {loaded/not found}
+
+**Ready for Triage:**
+{count} new item(s) found in manual input section.
+
+[S] Sync bug reports from API first (if app integration configured)
+[C] Continue to parse and triage bugs
+[Q] Quit - no new bugs to triage"
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with bugs.yaml structure
+✅ Input files discovered and validated
+✅ Manual input section scanned for new items
+✅ User informed of status and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when pending work exists
+❌ Not creating bugs.yaml with proper header/definitions
+❌ Reading entire bugs.md instead of just manual input section
+❌ Not reporting status to user before proceeding
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding
+❌ **CRITICAL**: Proceeding with 'C' without fully reading the next step file
+
+## NEXT STEP:
+
+- If user selects [S], load `./step-02-sync.md` to sync from API
+- If user selects [C], load `./step-03-parse.md` to parse and identify new bugs
+- If user selects [Q], end workflow gracefully
+
+Remember: Do NOT proceed until user explicitly selects an option from the menu!

src/modules/bmm/workflows/bug-tracking/steps/step-01b-continue.md

@@ -0,0 +1,110 @@
+# Step 1b: Continue Existing Bug Tracking Session
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 🚪 This step handles CONTINUATION of existing work
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Summarize existing state before offering options
+- 💾 Preserve all existing bugs.yaml data
+- 📖 Help user understand where they left off
+- 🚫 FORBIDDEN to lose or overwrite existing triage work
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- bugs.yaml contains existing structured data
+- User may have triaged bugs awaiting implementation
+- Don't re-triage already processed bugs
+
+## YOUR TASK:
+
+Welcome user back and summarize the current state of bug tracking, offering relevant continuation options.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Load Current State
+
+Read bugs.yaml and extract:
+- Total active bugs count
+- Bugs by status (triaged, implemented, verified)
+- Bugs by severity breakdown
+- Bugs by recommended workflow
+
+### 2. Check for New Input
+
+Scan "# manual input" section of bugs.md:
+- Count items not yet in bugs.yaml
+- These are new bugs needing triage
+
+### 3. Present Continuation Summary
+
+Report to user:
+
+"Welcome back, {user_name}! Here's your Bug Tracking status for {project_name}.
+
+**Current State:**
+- Active Bugs: {total_active}
+  - Triaged (awaiting action): {triaged_count}
+  - Implemented (awaiting verification): {implemented_count}
+- By Severity: Critical: {critical} | High: {high} | Medium: {medium} | Low: {low}
+
+**Workflow Routing:**
+- Direct Fix: {direct_fix_count} bug(s)
+- Tech-Spec: {tech_spec_count} bug(s)
+- Correct-Course: {correct_course_count} bug(s)
+- Backlog: {backlog_count} bug(s)
+
+**New Items:**
+- {new_count} new item(s) found in manual input section
+
+**Options:**
+[T] Triage new bugs ({new_count} items)
+[I] Implement a bug - `/implement bug-NNN`
+[V] Verify implemented bugs - `/verify`
+[L] List bugs by status/severity
+[Q] Quit"
+
+### 4. Handle User Selection
+
+Based on user choice:
+
+- **[T] Triage**: Load `./step-03-parse.md` to process new bugs
+- **[I] Implement**: Guide user to run `/implement bug-NNN` skill
+- **[V] Verify**: Guide user to run `/verify` skill
+- **[L] List**: Show filtered bug list, then return to menu
+- **[Q] Quit**: End workflow gracefully
+
+## SUCCESS METRICS:
+
+✅ Existing state accurately summarized
+✅ New items detected and counted
+✅ User given clear options based on current state
+✅ Appropriate next step loaded based on selection
+
+## FAILURE MODES:
+
+❌ Losing track of existing triaged bugs
+❌ Re-triaging already processed bugs
+❌ Not detecting new items in manual input
+❌ Proceeding without user selection
+
+❌ **CRITICAL**: Reading only partial step file
+❌ **CRITICAL**: Proceeding without explicit user menu selection
+
+## NEXT STEP:
+
+Load appropriate step based on user selection:
+- [T] → `./step-03-parse.md`
+- [I], [V] → Guide to relevant skill, then return here
+- [L] → Display list, return to this menu
+- [Q] → End workflow
+
+Remember: Do NOT proceed until user explicitly selects an option!

src/modules/bmm/workflows/bug-tracking/steps/step-02-sync.md

@@ -0,0 +1,145 @@
+# Step 2: Sync Bug Reports from API
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 🌐 This step handles OPTIONAL API integration for in-app bug reporting
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Attempt API sync only if configured
+- 💾 Preserve existing manual input entries
+- 📖 Format synced reports as markdown entries
+- 🚫 FORBIDDEN to lose manually entered bugs
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- `project_url` may or may not be configured
+- API endpoints are optional - gracefully handle if unavailable
+- This step can be skipped if no API integration
+
+## YOUR TASK:
+
+Sync pending bug reports from the application's PostgreSQL database via API, formatting them as markdown entries in bugs.md.
+
+## SYNC SEQUENCE:
+
+### 1. Check API Configuration
+
+Verify `{project_url}` is configured:
+- If not configured or user skipped this step, proceed to step-03
+- If configured, attempt API connection
+
+### 2. Fetch Pending Reports
+
+**API Call:**
+```
+GET {project_url}/api/bug-reports/pending
+```
+
+**Expected Response:**
+```json
+{
+  "data": {
+    "reports": [...],
+    "count": number
+  }
+}
+```
+
+**Report Fields:**
+- `id` - Database ID
+- `title` - Bug title
+- `description` - Bug description
+- `reporterType` - Type of reporter (user, staff, admin)
+- `reporterName` - Name of reporter
+- `platform` - Platform (iOS, Android, web)
+- `browser` - Browser if web
+- `pageUrl` - URL where bug occurred
+- `screenshotUrl` - Optional screenshot
+- `createdAt` - Timestamp
+
+### 3. Handle No Reports
+
+If count == 0:
+
+"No new bug reports from the application API.
+
+[C] Continue to triage existing manual input
+[Q] Quit - nothing to process"
+
+### 4. Format Reports as Markdown
+
+For each report, create markdown entry:
+
+```markdown
+## Bug: {title}
+
+{description}
+
+Reported by: {reporterName} ({reporterType})
+Date: {createdAt formatted as YYYY-MM-DD}
+Platform: {platform} / {browser}
+Page: {pageUrl}
+{if screenshotUrl: Screenshot: {screenshotUrl}}
+```
+
+### 5. Insert into bugs.md
+
+- Read the "# manual input" section location from bugs.md
+- Insert new markdown entries after the "# manual input" header
+- Preserve any existing manual input entries
+- Write updated bugs.md
+
+### 6. Mark Reports as Synced
+
+**API Call:**
+```
+POST {project_url}/api/bug-reports/mark-synced
+Body: { "ids": [array of synced report IDs] }
+```
+
+This updates status to 'synced' so reports won't be fetched again.
+
+### 7. Report Sync Results
+
+"**Synced {count} bug report(s) from application:**
+
+{for each report:}
+- {title} (from {reporterName})
+{end for}
+
+These have been added to the manual input section of bugs.md.
+
+[C] Continue to parse and triage all bugs
+[Q] Quit"
+
+## SUCCESS METRICS:
+
+✅ API availability checked gracefully
+✅ Pending reports fetched and formatted
+✅ Existing manual entries preserved
+✅ Reports marked as synced in database
+✅ User informed of sync results
+
+## FAILURE MODES:
+
+❌ Crashing if API unavailable (should gracefully skip)
+❌ Overwriting existing manual input entries
+❌ Not marking reports as synced (causes duplicates)
+❌ Proceeding without user confirmation
+
+❌ **CRITICAL**: Reading only partial step file
+❌ **CRITICAL**: Proceeding without explicit user selection
+
+## NEXT STEP:
+
+After user selects [C], load `./step-03-parse.md` to parse and identify all bugs needing triage.
+
+Remember: Do NOT proceed until user explicitly selects [C] from the menu!

src/modules/bmm/workflows/bug-tracking/steps/step-03-parse.md

@@ -0,0 +1,164 @@
+# Step 3: Parse and Identify New Bugs
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 🔍 This step PARSES input only - triage happens in next step
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Parse manual input section thoroughly
+- 💾 Compare against existing bugs.yaml entries
+- 📖 Extract all available information from informal reports
+- 🚫 FORBIDDEN to start triage in this step - parsing only
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- bugs.yaml contains existing triaged bugs
+- Only parse "# manual input" section of bugs.md
+- Do NOT read entire bugs.md file
+
+## YOUR TASK:
+
+Parse the "# manual input" section of bugs.md, extract bug information, and identify which items need triage.
+
+## PARSE SEQUENCE:
+
+### 1. Read Manual Input Section
+
+Section-based reading of bugs.md:
+- Grep for "# manual input" to find starting line number
+- Grep for next section header ("# Tracked Bugs", "# Tracked Feature Requests", "# Fixed Bugs") to find ending line
+- Read just that range using offset/limit (do NOT read entire file)
+- If no closing section found within initial window, expand read range and retry
+
+### 2. Search Existing IDs in bugs.yaml
+
+Do NOT read entire bugs.yaml file:
+- Grep for `id: bug-[0-9]+` pattern to find all existing bug IDs
+- Grep for `id: feature-[0-9]+` pattern to find all existing feature IDs
+- This enables duplicate detection and next-ID generation
+
+### 3. Parse Bug Reports
+
+Expected formats in manual input (informal, user-written):
+
+**Format A: Markdown Headers**
+```markdown
+## Bug: Title Here
+
+Description text, possibly multi-paragraph.
+
+Reported by: Name
+Date: YYYY-MM-DD
+Related: Story 2.7
+Platform: iOS
+```
+
+**Format B: Bullet Lists**
+```markdown
+- **Title (Platform)**: Description text. CRITICAL if urgent.
+```
+
+**Format C: Numbered Lists**
+```markdown
+1. Title - Description text
+2. Another bug - More description
+```
+
+### 4. Extract Information
+
+For each bug report, extract:
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| Title | Yes | First line or header |
+| Description | Yes | May be multi-paragraph |
+| Reported by | No | Extract if mentioned |
+| Date | No | Extract if mentioned |
+| Related story | No | e.g., "2-7", "Story 2.7" |
+| Platform | No | iOS, Android, web, all |
+| Reproduction steps | No | If provided |
+| Severity hints | No | "CRITICAL", "urgent", etc. |
+
+### 5. Categorize Items
+
+Compare extracted bugs with existing bugs.yaml:
+
+- **New bugs**: Not in bugs.yaml yet (need full triage)
+- **Updated bugs**: In bugs.yaml but description changed (need re-triage)
+- **Feature requests**: Items that are enhancements, not bugs
+- **Unchanged**: Already triaged, skip
+
+### 6. Handle No New Bugs
+
+If NO new bugs found:
+
+"No new bugs found in the manual input section.
+
+All items have already been triaged and are tracked in bugs.yaml.
+
+**Options:**
+1. Add new bugs to docs/bugs.md (informal format)
+2. View bugs.yaml to see structured bug tracking
+3. Route existing triaged bugs to workflows
+
+[Q] Quit - nothing to triage"
+
+**HALT** - Do not proceed.
+
+### 7. Present Parsed Items
+
+"**Parsed {total_count} item(s) from manual input:**
+
+**New Bugs ({new_count}):**
+{for each new bug:}
+- {extracted_title}
+  - Description: {first 100 chars}...
+  - Platform: {platform or "not specified"}
+  - Related: {story or "not specified"}
+{end for}
+
+**Feature Requests ({feature_count}):**
+{for each feature:}
+- {title}
+{end for}
+
+**Already Triaged ({unchanged_count}):**
+{list titles of skipped items}
+
+Ready to triage {new_count} new bug(s) and {feature_count} feature request(s).
+
+[C] Continue to triage
+[E] Edit - re-parse with corrections
+[Q] Quit"
+
+## SUCCESS METRICS:
+
+✅ Manual input section read efficiently (not entire file)
+✅ All formats parsed correctly (headers, bullets, numbered)
+✅ Existing bugs detected to prevent duplicates
+✅ New vs updated vs unchanged correctly categorized
+✅ User shown summary and can proceed
+
+## FAILURE MODES:
+
+❌ Reading entire bugs.md instead of section
+❌ Missing bugs due to format not recognized
+❌ Not detecting duplicates against bugs.yaml
+❌ Starting triage in this step (should only parse)
+
+❌ **CRITICAL**: Reading only partial step file
+❌ **CRITICAL**: Proceeding without user selection
+
+## NEXT STEP:
+
+After user selects [C], load `./step-04-triage.md` to perform triage analysis on each new bug.
+
+Remember: Do NOT proceed until user explicitly selects [C] from the menu!

src/modules/bmm/workflows/bug-tracking/steps/step-04-triage.md

@@ -0,0 +1,212 @@
+# Step 4: Triage Each Bug
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR - ask clarifying questions when needed
+- 🎯 This step performs the CORE TRIAGE analysis
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed varies widely
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Triage ONE bug at a time with user confirmation
+- 💾 Track triage decisions for bugs.yaml update
+- 📖 Ask clarifying questions when severity/complexity unclear
+- 🚫 FORBIDDEN to auto-triage without user review
+
+## CONTEXT BOUNDARIES:
+
+- Parsed bugs from step-03 are in memory
+- Reference bugs.yaml header for severity/complexity definitions
+- Reference epics.md for story mapping
+- Each bug gets full triage analysis
+
+## YOUR TASK:
+
+Perform collaborative triage analysis on each parsed bug, assessing severity, complexity, effort, workflow routing, and documentation impact.
+
+## TRIAGE SEQUENCE (FOR EACH BUG):
+
+### 1. Generate Bug ID
+
+- Find highest existing bug-NNN from step-03 grep results
+- Assign next sequential ID (e.g., bug-006)
+- Format: `bug-` + zero-padded 3-digit number
+- For features: `feature-` + zero-padded 3-digit number
+
+### 2. Assess Severity
+
+**Severity Levels:**
+| Level | Criteria |
+|-------|----------|
+| critical | Prevents core functionality, crashes, data loss |
+| high | Blocks major features, significantly degrades UX but has workaround |
+| medium | Affects subset of users, minor impact |
+| low | Cosmetic, edge case, minor inconvenience |
+
+**Analysis Questions:**
+- Does it prevent core functionality? → critical
+- Does it cause crashes or data loss? → critical
+- Does it block major features? → high
+- Does it significantly degrade UX but have workaround? → high
+- Does it affect subset of users with minor impact? → medium
+- Is it cosmetic or edge case? → low
+
+**If Unclear - ASK:**
+"**Clarification needed for: {bug_title}**
+
+I need more information to assess severity:
+1. Does this bug prevent users from completing core flows?
+2. Does the bug cause crashes or data loss?
+3. How many users are affected? (all users, specific platform, edge case)
+4. Is there a workaround available?
+
+Please provide additional context."
+
+### 3. Assess Complexity
+
+**Complexity Levels:**
+| Level | Criteria |
+|-------|----------|
+| trivial | One-line fix, obvious solution |
+| small | Single file/component, solution clear |
+| medium | Multiple files OR requires investigation |
+| complex | Architectural change, affects many areas |
+
+**If Unclear - ASK:**
+"**Clarification needed for: {bug_title}**
+
+To estimate complexity, I need:
+1. Have you identified the root cause, or does it need investigation?
+2. Which file(s) or component(s) are affected?
+3. Is this isolated or does it affect multiple parts of the app?
+
+Please provide technical details if available."
+
+### 4. Determine Workflow Routing
+
+**Routing Matrix:**
+| Severity | Complexity | Workflow |
+|----------|------------|----------|
+| critical | any | correct-course |
+| high | trivial | direct-fix |
+| high | small | tech-spec |
+| high | medium/complex | correct-course |
+| medium | trivial | direct-fix |
+| medium | small | tech-spec |
+| medium | medium/complex | correct-course |
+| low | trivial | direct-fix |
+| low | small+ | backlog |
+
+### 5. Map to Related Story/Epic
+
+- If bug mentions story ID (e.g., "2-7"), use that
+- Otherwise, infer from description using epic keywords
+- Reference epics.md for story matching
+- Format: `{epic_number}-{story_number}` or null
+
+### 6. Determine Affected Platform
+
+Extract from description:
+- `all` - Default if not specified
+- `ios` - iOS only
+- `android` - Android only
+- `web` - Web only
+
+### 7. Assess Documentation Impact
+
+**PRD Impact** (`doc_impact.prd: true/false`)
+Set TRUE if issue:
+- Conflicts with stated product goals
+- Requires changing MVP scope
+- Adds/removes/modifies core functionality
+- Changes success metrics
+- Affects multiple epics
+
+**Architecture Impact** (`doc_impact.architecture: true/false`)
+Set TRUE if issue:
+- Requires new system components
+- Changes data model (new tables, schema)
+- Affects API contracts
+- Introduces new dependencies
+- Changes auth/security model
+
+**UX Impact** (`doc_impact.ux: true/false`)
+Set TRUE if issue:
+- Adds new screens or navigation
+- Changes existing user flows
+- Requires new UI components
+- Affects accessibility
+
+**If any doc_impact is TRUE AND workflow != correct-course:**
+- Override workflow to `correct-course`
+- Add note: "Workflow elevated due to documentation impact"
+
+### 8. Add Triage Notes
+
+Document reasoning:
+- Why this severity? (business impact, user impact)
+- Why this complexity? (investigation needed, files affected)
+- Why this workflow? (routing logic applied)
+- Suggested next steps or investigation areas
+
+### 9. Present Triage for Confirmation
+
+"**Triage: {bug_id} - {bug_title}**
+
+| Field | Value |
+|-------|-------|
+| Severity | {severity} |
+| Complexity | {complexity} |
+| Platform | {platform} |
+| Workflow | {recommended_workflow} |
+| Related | {related_story or 'None'} |
+
+**Documentation Impact:**
+- PRD: {yes/no}
+- Architecture: {yes/no}
+- UX: {yes/no}
+
+**Triage Notes:**
+{triage_notes}
+
+[A] Accept triage
+[M] Modify - adjust severity/complexity/workflow
+[S] Skip - don't triage this item now
+[N] Next bug (after accepting)"
+
+### 10. Handle Modifications
+
+If user selects [M]:
+- Ask which field to modify
+- Accept new value
+- Re-present triage for confirmation
+
+## SUCCESS METRICS:
+
+✅ Each bug triaged with user confirmation
+✅ Unclear items prompted for clarification
+✅ Routing matrix applied correctly
+✅ Documentation impact assessed
+✅ Triage notes document reasoning
+
+## FAILURE MODES:
+
+❌ Auto-triaging without user review
+❌ Not asking clarifying questions when needed
+❌ Incorrect routing matrix application
+❌ Missing documentation impact assessment
+❌ Not documenting triage reasoning
+
+❌ **CRITICAL**: Reading only partial step file
+❌ **CRITICAL**: Proceeding without user confirmation per bug
+
+## NEXT STEP:
+
+After ALL bugs triaged (user selected [A] or [N] for each), load `./step-05-update.md` to update bugs.yaml and bugs.md.
+
+Remember: Triage each bug individually with user confirmation!

src/modules/bmm/workflows/bug-tracking/steps/step-05-update.md

@@ -0,0 +1,200 @@
+# Step 5: Update Files with Triaged Metadata
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 💾 This step WRITES the triage results to files
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Update both bugs.yaml and bugs.md atomically
+- 💾 Preserve ALL existing data - append only
+- 📖 Move items from manual input to tracked sections
+- 🚫 FORBIDDEN to lose or corrupt existing data
+
+## CONTEXT BOUNDARIES:
+
+- Triage decisions from step-04 are in memory
+- bugs.yaml structure defined in step-01
+- bugs.md sections: manual input, Tracked Bugs, Tracked Feature Requests, Fixed Bugs
+- Preserve header comments and definitions
+
+## YOUR TASK:
+
+Write all triaged metadata to bugs.yaml and move triaged items from "# manual input" to appropriate tracked sections in bugs.md.
+
+## UPDATE SEQUENCE:
+
+### 1. Update bugs.yaml
+
+#### A. Load Existing Structure
+
+Read current bugs.yaml (if exists):
+- Preserve ALL header comments and definitions
+- Preserve existing `bugs:` array entries
+- Preserve existing `features:` array entries
+- Preserve existing `closed_bugs:` array
+
+#### B. Add New Bug Entries
+
+For each triaged bug, add to `bugs:` array:
+
+```yaml
+- id: bug-NNN
+  title: "Bug title"
+  description: |
+    Full description text
+    Can be multi-line
+  severity: critical|high|medium|low
+  complexity: trivial|small|medium|complex
+  affected_platform: all|ios|android|web
+  recommended_workflow: direct-fix|tech-spec|correct-course|backlog
+  related_story: "X-Y" or null
+  status: triaged
+  reported_by: "Name" or null
+  reported_date: "YYYY-MM-DD" or null
+  triaged_date: "{date}"
+  doc_impact:
+    prd: true|false
+    architecture: true|false
+    ux: true|false
+    notes: "Impact description" or null
+  triage_notes: |
+    Reasoning for severity, complexity, workflow decisions
+  implemented_by: null
+  implemented_date: null
+  verified_by: null
+  verified_date: null
+```
+
+#### C. Add Feature Request Entries
+
+For features, add to `features:` array with similar structure.
+
+#### D. Update Statistics
+
+Recalculate statistics section:
+
+```yaml
+statistics:
+  total_active: {count of non-closed bugs}
+  by_severity:
+    critical: {count}
+    high: {count}
+    medium: {count}
+    low: {count}
+  by_status:
+    triaged: {count}
+    implemented: {count}
+    verified: {count}
+  by_workflow:
+    direct-fix: {count}
+    tech-spec: {count}
+    correct-course: {count}
+    backlog: {count}
+  last_updated: "{date}"
+```
+
+#### E. Write bugs.yaml
+
+Write complete bugs.yaml file preserving all content.
+
+### 2. Update bugs.md
+
+#### A. Section-Based Reading
+
+Use grep to locate section line numbers:
+- "# manual input"
+- "# Tracked Bugs"
+- "# Tracked Feature Requests"
+- "# Fixed Bugs"
+
+Read only relevant sections with offset/limit.
+
+#### B. Remove from Manual Input
+
+For each triaged item:
+- Remove the original entry from "# manual input" section
+- Handle both header format and bullet format
+
+#### C. Add to Tracked Bugs
+
+For each triaged bug, add to "# Tracked Bugs" section:
+
+```markdown
+### {bug_id}: {title}
+
+{brief_description}
+
+- **Severity:** {severity}
+- **Complexity:** {complexity}
+- **Platform:** {platform}
+- **Workflow:** {workflow}
+- **Related:** {story or "None"}
+{if doc_impact flagged:}
+- **Doc Impact:** {PRD|Architecture|UX as applicable}
+{end if}
+
+**Notes:** {triage_notes_summary}
+
+---
+```
+
+Create "# Tracked Bugs" section if it doesn't exist.
+
+#### D. Add to Tracked Feature Requests
+
+For features, add to "# Tracked Feature Requests" section with similar format.
+
+#### E. Write bugs.md
+
+Write updated bugs.md preserving all sections.
+
+### 3. Confirm Updates
+
+"**Files Updated:**
+
+**bugs.yaml:**
+- Added {bug_count} new bug(s)
+- Added {feature_count} new feature request(s)
+- Total active bugs: {total_active}
+- Statistics recalculated
+
+**bugs.md:**
+- Removed {count} item(s) from manual input
+- Added {bug_count} bug(s) to Tracked Bugs section
+- Added {feature_count} feature(s) to Tracked Feature Requests section
+
+[C] Continue to summary
+[R] Review changes - show diff
+[U] Undo - restore previous state"
+
+## SUCCESS METRICS:
+
+✅ bugs.yaml updated with all triaged metadata
+✅ bugs.md items moved from manual input to tracked sections
+✅ Statistics accurately recalculated
+✅ All existing data preserved
+✅ User confirmed updates
+
+## FAILURE MODES:
+
+❌ Losing existing bugs.yaml entries
+❌ Corrupting bugs.md structure
+❌ Items remaining in manual input after triage
+❌ Statistics not matching actual data
+❌ Not preserving header comments/definitions
+
+❌ **CRITICAL**: Reading only partial step file
+❌ **CRITICAL**: Proceeding without user confirmation
+
+## NEXT STEP:
+
+After user selects [C], load `./step-06-complete.md` to present final triage summary.
+
+Remember: Do NOT proceed until user explicitly selects [C] from the menu!

src/modules/bmm/workflows/bug-tracking/steps/step-06-complete.md

@@ -0,0 +1,180 @@
+# Step 6: Triage Complete - Summary and Next Steps
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- ✅ ALWAYS treat this as collaborative triage between peers
+- 📋 YOU ARE A FACILITATOR, not an automatic processor
+- 🎉 This is the FINAL step - present comprehensive summary
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present comprehensive triage summary
+- 💾 All data already written in step-05
+- 📖 Guide user to next actions
+- 🚫 FORBIDDEN to modify files in this step
+
+## CONTEXT BOUNDARIES:
+
+- All triage decisions finalized in previous steps
+- bugs.yaml and bugs.md already updated
+- This step is READ-ONLY presentation
+- Focus on actionable next steps
+
+## YOUR TASK:
+
+Present a comprehensive summary of the triage session and guide the user to appropriate next actions based on workflow recommendations.
+
+## COMPLETION SEQUENCE:
+
+### 1. Present Triage Summary
+
+"**Bug Triage Complete, {user_name}!**
+
+---
+
+## Triaged Items
+
+{for each triaged bug:}
+
+### {bug_id}: {bug_title}
+
+| Field | Value |
+|-------|-------|
+| Severity | {severity} |
+| Complexity | {complexity} |
+| Platform | {platform} |
+| Workflow | {recommended_workflow} |
+| Related | {related_story or 'None'} |
+
+{if doc_impact flagged:}
+**Documentation Impact:**
+- PRD: {yes/no}
+- Architecture: {yes/no}
+- UX: {yes/no}
+- Notes: {doc_impact_notes}
+{end if}
+
+**Triage Reasoning:**
+{triage_notes}
+
+---
+
+{end for}
+
+## Updated Files
+
+- **bugs.yaml** - Structured metadata for all triaged items
+- **bugs.md** - Moved triaged items to Tracked sections
+
+---
+
+## Statistics Summary
+
+| Metric | Count |
+|--------|-------|
+| Total Active Bugs | {total_active} |
+| Critical | {critical_count} |
+| High | {high_count} |
+| Medium | {medium_count} |
+| Low | {low_count} |
+
+{if any doc_impact flagged:}
+
+## Documentation Updates Required
+
+Items with documentation impact have been routed to `correct-course` workflow:
+- PRD Impact: {prd_impact_count} item(s)
+- Architecture Impact: {arch_impact_count} item(s)
+- UX Impact: {ux_impact_count} item(s)
+{end if}
+
+---
+
+## Workflow Recommendations
+
+### Direct Fix ({direct_fix_count} items)
+Quick fixes with obvious solutions. No spec needed.
+
+**Command:** `/implement bug-NNN`
+
+{list bug IDs for direct-fix}
+
+### Tech-Spec ({tech_spec_count} items)
+Require technical specification before implementation.
+
+**Process:** Create tech-spec first, then `/implement`
+
+{list bug IDs for tech-spec}
+
+### Correct-Course ({correct_course_count} items)
+Need impact analysis before proceeding.
+
+**Process:** Run correct-course workflow for impact analysis
+
+{list bug IDs for correct-course}
+
+### Backlog ({backlog_count} items)
+Deferred - low priority items for future consideration.
+
+{list bug IDs for backlog}
+
+---
+
+## Next Steps
+
+**To implement a bug fix:**
+```
+/implement bug-NNN
+```
+
+**To verify after testing:**
+```
+/verify bug-NNN
+```
+
+**To verify all implemented bugs:**
+```
+/verify
+```
+
+**To list bugs by platform:**
+```
+/list-bugs android
+/list-bugs ios
+```
+
+---
+
+Thank you for completing the triage session!"
+
+### 2. End Workflow
+
+The workflow is complete. No further steps.
+
+## SUCCESS METRICS:
+
+✅ Comprehensive summary presented
+✅ All triaged items listed with metadata
+✅ Statistics accurately displayed
+✅ Workflow recommendations clear
+✅ Next step commands provided
+✅ User knows how to proceed
+
+## FAILURE MODES:
+
+❌ Incomplete summary missing items
+❌ Statistics not matching bugs.yaml
+❌ Unclear next step guidance
+❌ Modifying files in this step (should be read-only)
+
+## WORKFLOW COMPLETE
+
+This is the final step. The bug tracking triage workflow is complete.
+
+User can now:
+- Run `/implement bug-NNN` to fix bugs
+- Run `/verify` to verify implemented bugs
+- Add new bugs to bugs.md and run triage again

src/modules/bmm/workflows/bug-tracking/workflow.md

@@ -0,0 +1,58 @@
+---
+name: bug-tracking
+description: Triage user-reported bugs from bugs.md, generate structured metadata in bugs.yaml, and route to appropriate workflow
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+web_bundle: true
+---
+
+# Bug Tracking Workflow
+
+**Goal:** Transform informal bug reports into structured, actionable metadata with severity assessment, complexity estimation, and workflow routing recommendations.
+
+**Your Role:** You are a triage facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured analysis and triage methodology, while the user brings domain expertise and context about their product. Work together to efficiently categorize and route bugs for resolution.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- State tracked via bugs.yaml metadata
+- Append-only updates to bugs.md (move triaged items, never delete)
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `date` as system-generated current datetime
+- `dev_ephemeral_location` for sprint-status.yaml location
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/bug-tracking`
+- `bugs_input` = `{output_folder}/bugs.md` (user-facing bug reports)
+- `bugs_output` = `{output_folder}/bugs.yaml` (agent-facing structured metadata)
+- `sprint_status` = `{dev_ephemeral_location}/sprint-status.yaml`
+- `epics_file` = `{output_folder}/epics.md`
+
+### Optional API Integration
+
+- `project_url` = configurable base URL for in-app bug report sync (default: `http://localhost:5173`)
+- See `reference-implementation.md` for in-app bug reporting setup
+
+---
+
+## EXECUTION
+
+Load and execute `steps/step-01-init.md` to begin the workflow.
+
+**Note:** Input file discovery and initialization protocols are handled in step-01-init.md.

src/modules/bmm/workflows/implement/instructions.md

@@ -0,0 +1,523 @@
+# Implement Workflow (Bug Fix or Feature)
+
+```xml
+<critical>This workflow loads bug/feature context, implements the code, and updates tracking in both bugs.yaml and bugs.md</critical>
+<critical>Communicate in {communication_language} with {user_name}</critical>
+<critical>Auto-detects type from ID format: bug-NNN = bug fix, feature-NNN = feature implementation</critical>
+
+<workflow>
+
+  <step n="1" goal="Get item ID from user">
+    <check if="item_id not provided in user input">
+      <ask>Which bug or feature should I implement? (e.g., bug-026 or feature-021)</ask>
+    </check>
+    <action>Extract item ID from user input</action>
+    <action>Detect type from ID format:</action>
+    <action>- "bug-NNN" -> type = "bug", action_verb = "fix", past_verb = "Fixed"</action>
+    <action>- "feature-NNN" -> type = "feature", action_verb = "implement", past_verb = "Implemented"</action>
+    <check if="ID doesn't match either format">
+      <output>Invalid ID format. Use bug-NNN (e.g., bug-026) or feature-NNN (e.g., feature-021)</output>
+      <action>HALT</action>
+    </check>
+  </step>
+
+  <step n="2" goal="Load context from bugs.yaml">
+    <action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
+    <check if="type == bug">
+      <action>Entry will be in bugs section, grep will capture all fields</action>
+    </check>
+    <check if="type == feature">
+      <action>Entry will be in feature_requests section, grep will capture all fields</action>
+    </check>
+    <check if="item not found in bugs.yaml">
+      <output>{item_id} not found in bugs.yaml. Please verify the ID or run bug-tracking workflow first.</output>
+      <action>HALT</action>
+    </check>
+    <action>Extract and store metadata:</action>
+    <action>- title: Title/summary</action>
+    <action>- description: Full description</action>
+    <action>- severity/priority: Importance level</action>
+    <action>- complexity: trivial | small | medium | complex</action>
+    <action>- effort_estimate: Estimated hours</action>
+    <action>- affected_platform: all | ios | android (bugs only)</action>
+    <action>- related_story/related_epic: Related items if applicable</action>
+    <action>- doc_impact: Documentation impact flags (prd, architecture, ux) and notes</action>
+    <action>- notes: Triage notes including planned approach, files to check, implementation strategy</action>
+
+    <check if="recommended_workflow == 'backlog'">
+      <output>**BACKLOG ITEM - NOT READY FOR IMPLEMENTATION**
+
+**{item_id}: {title}**
+
+This item has `recommended_workflow: backlog` which means it's deferred and not scheduled for implementation.
+
+**To implement this item, first promote it to the sprint:**
+1. Run `*sprint-planning` and select this item for promotion
+2. Or manually update bugs.yaml: change `recommended_workflow` to `direct-fix`, `tech-spec`, or `correct-course`
+
+**Current Status:** {status}
+**Priority:** {priority}
+**Complexity:** {complexity}
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <check if="status == 'deferred'">
+      <output>**DEFERRED ITEM - NOT READY FOR IMPLEMENTATION**
+
+**{item_id}: {title}**
+
+This item is deferred (marked for future release, not current MVP).
+
+**To implement this item:**
+1. Update bugs.yaml: change `status` from `deferred` to `backlog`
+2. Run `*sprint-planning` to promote to current sprint
+
+**Notes:** {notes}
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <check if="status == 'blocked'">
+      <output>**BLOCKED ITEM - CANNOT IMPLEMENT**
+
+**{item_id}: {title}**
+
+This item is blocked and requires clarification before implementation.
+
+**Blocking reason:** {notes}
+
+**To unblock:**
+1. Resolve the blocking issue
+2. Update bugs.yaml: change `status` from `blocked` to `backlog`
+3. Run `/triage {item_id}` to re-evaluate
+      </output>
+      <action>HALT</action>
+    </check>
+  </step>
+
+  <step n="2.5" goal="Check for documentation impact and route to appropriate agents">
+    <action>Check doc_impact fields from bugs.yaml entry</action>
+    <check if="doc_impact.prd OR doc_impact.architecture OR doc_impact.ux is TRUE">
+      <output>**DOCUMENTATION IMPACT DETECTED**
+
+**{item_id}: {title}**
+
+This {type} requires documentation updates BEFORE implementation:
+
+{if doc_impact.prd:}
+- **PRD Impact:** Updates needed to product requirements
+  -> Route to PM Agent for PRD updates
+{end if}
+
+{if doc_impact.architecture:}
+- **Architecture Impact:** Updates needed to architecture docs
+  -> Route to Architect Agent for architecture updates
+{end if}
+
+{if doc_impact.ux:}
+- **UX Impact:** Updates needed to UX specifications
+  -> Route to UX Designer Agent for UX spec updates
+{end if}
+
+**Details:** {doc_impact.notes}
+
+**Options:**
+1. **update-docs-first** - Route to agents for documentation updates before implementation (recommended)
+2. **proceed-anyway** - Skip documentation updates and implement directly (not recommended)
+3. **cancel** - Return to review</output>
+      <ask>How should we proceed?</ask>
+
+      <check if="user chooses update-docs-first">
+        <output>Routing to documentation update workflow...
+
+**Documentation Update Sequence:**</output>
+
+        <check if="doc_impact.prd">
+          <output>1. **PRD Update** - Invoking PM Agent...</output>
+          <action>Prepare PRD update context:</action>
+          <action>- Source item: {item_id}</action>
+          <action>- Change description: {description}</action>
+          <action>- Specific PRD sections: {doc_impact.notes PRD sections}</action>
+          <invoke-agent agent="pm">
+            <task>Review and update PRD for {item_id}: {title}
+
+Change context: {description}
+
+Documentation notes: {doc_impact.notes}
+
+Please update the relevant PRD sections to reflect this change.
+
+After updates:
+1. Summarize what was changed
+2. Return to the implement workflow by running: /implement {item_id}
+
+IMPORTANT: You MUST return to /implement {item_id} after completing the PRD updates so the actual code implementation can proceed.</task>
+          </invoke-agent>
+        </check>
+
+        <check if="doc_impact.architecture">
+          <output>2. **Architecture Update** - Invoking Architect Agent...</output>
+          <action>Prepare architecture update context:</action>
+          <action>- Source item: {item_id}</action>
+          <action>- Change description: {description}</action>
+          <action>- Specific architecture sections: {doc_impact.notes architecture sections}</action>
+          <invoke-agent agent="architect">
+            <task>Review and update Architecture documentation for {item_id}: {title}
+
+Change context: {description}
+
+Documentation notes: {doc_impact.notes}
+
+Please update the relevant architecture sections (data model, APIs, security, etc.) to reflect this change.
+
+After updates:
+1. Summarize what was changed
+2. Return to the implement workflow by running: /implement {item_id}
+
+IMPORTANT: You MUST return to /implement {item_id} after completing the architecture updates so the actual code implementation can proceed.</task>
+          </invoke-agent>
+        </check>
+
+        <check if="doc_impact.ux">
+          <output>3. **UX Spec Update** - Invoking UX Designer Agent...</output>
+          <action>Prepare UX update context:</action>
+          <action>- Source item: {item_id}</action>
+          <action>- Change description: {description}</action>
+          <action>- Specific UX sections: {doc_impact.notes UX sections}</action>
+          <invoke-agent agent="ux-designer">
+            <task>Review and update UX specification for {item_id}: {title}
+
+Change context: {description}
+
+Documentation notes: {doc_impact.notes}
+
+Please update the relevant UX spec sections (screens, flows, components, etc.) to reflect this change.
+
+After updates:
+1. Summarize what was changed
+2. Return to the implement workflow by running: /implement {item_id}
+
+IMPORTANT: You MUST return to /implement {item_id} after completing the UX updates so the actual code implementation can proceed.</task>
+          </invoke-agent>
+        </check>
+
+        <output>**Documentation updates complete.**
+
+Proceeding with implementation...</output>
+        <action>Continue to step 3</action>
+      </check>
+
+      <check if="user chooses cancel">
+        <output>Cancelled. {item_id} remains in current state.</output>
+        <action>HALT</action>
+      </check>
+
+      <action if="user chooses proceed-anyway">
+        <output>Proceeding without documentation updates. Remember to update docs after implementation.</output>
+        <action>Continue to step 3</action>
+      </action>
+    </check>
+  </step>
+
+  <step n="3" goal="Evaluate routing and auto-route to correct-course if needed">
+    <action>Check recommended_workflow field from bugs.yaml</action>
+
+    <check if="recommended_workflow == 'correct-course'">
+      <output>**AUTO-ROUTING TO CORRECT-COURSE**
+
+**{item_id}: {title}**
+**Priority:** {severity_or_priority} | **Complexity:** {complexity}
+
+This {type} has `recommended_workflow: correct-course` which requires impact analysis and story creation before implementation.
+
+Invoking correct-course workflow via SM agent...</output>
+
+      <action>Invoke the correct-course workflow skill with item context</action>
+      <invoke-skill skill="bmad:bmm:workflows:correct-course">
+        <args>{item_id}: {title} - {description}
+
+Priority: {severity_or_priority}
+Complexity: {complexity}
+Doc Impact: {doc_impact summary}
+Notes: {notes}</args>
+      </invoke-skill>
+      <action>HALT - Correct Course workflow will handle story/epic creation</action>
+    </check>
+
+    <check if="recommended_workflow == 'tech-spec'">
+      <output>**AUTO-ROUTING TO TECH-SPEC**
+
+**{item_id}: {title}**
+
+This {type} has `recommended_workflow: tech-spec`. Invoking tech-spec workflow...</output>
+
+      <invoke-skill skill="bmad:bmm:workflows:tech-spec">
+        <args>{item_id}: {title} - {description}</args>
+      </invoke-skill>
+      <action>HALT - Tech-spec workflow will create implementation spec</action>
+    </check>
+
+    <check if="recommended_workflow == 'direct-fix'">
+      <output>**DIRECT IMPLEMENTATION**
+
+This {type} is routed for direct implementation. Proceeding...</output>
+      <action>Continue to step 4</action>
+    </check>
+
+    <check if="recommended_workflow is not set OR recommended_workflow is ambiguous">
+      <action>Evaluate the workflow routing matrix based on severity and complexity:</action>
+      <action>**Routing Matrix:**</action>
+      <action>- critical + any -> correct-course</action>
+      <action>- high/medium + medium/complex -> correct-course</action>
+      <action>- high + trivial -> direct-fix</action>
+      <action>- high/medium + small -> tech-spec</action>
+      <action>- medium + trivial -> direct-fix</action>
+      <action>- low + trivial -> direct-fix</action>
+      <action>- low + small+ -> backlog</action>
+
+      <action>Apply matrix to determine routing and continue accordingly</action>
+    </check>
+  </step>
+
+  <step n="4" goal="Present context and confirm approach">
+    <output>**{item_id}: {title}**
+
+**Type:** {type} | **Severity/Priority:** {severity_or_priority} | **Complexity:** {complexity} | **Effort:** ~{effort_estimate}h
+
+**Description:**
+{description}
+
+**Planned Approach (from triage notes):**
+{notes}
+
+**Related:** {related_story} / {related_epic}
+    </output>
+    <ask>Ready to {action_verb} this {type}? (yes/no/clarify)</ask>
+    <check if="user says clarify">
+      <ask>What additional context do you need?</ask>
+      <action>Gather clarification, update mental model</action>
+    </check>
+    <check if="user says no">
+      <output>Cancelled. {item_id} remains in current state.</output>
+      <action>HALT</action>
+    </check>
+  </step>
+
+  <step n="5" goal="Implement the fix/feature">
+    <action>Based on the notes/planned approach, identify files to modify or create</action>
+    <action>Read each affected file to understand current implementation</action>
+    <action>Implement following the planned approach:</action>
+    <action>- Make minimal, targeted changes</action>
+    <action>- Follow existing code patterns and style</action>
+    <action>- Add comments only where logic is non-obvious</action>
+    <action>- Do not over-engineer or add unrelated improvements</action>
+    <action>- Do not add extra features or "nice to haves"</action>
+
+    <action>For each file modified/created, track:</action>
+    <action>- File path</action>
+    <action>- What was changed/added</action>
+    <action>- How it addresses the bug/feature</action>
+
+    <check if="requires new files">
+      <action>Create new files following project conventions</action>
+      <action>Add appropriate imports/exports</action>
+    </check>
+
+    <check if="planned approach is unclear or insufficient">
+      <ask>The triage notes don't provide a clear approach.
+
+Based on my analysis, I suggest: {proposed_approach}
+
+Should I proceed with this approach?</ask>
+    </check>
+  </step>
+
+  <step n="6" goal="Verify implementation compiles">
+    <action>Run TypeScript compilation check: npm run check</action>
+    <check if="compilation errors in modified files">
+      <action>Fix compilation errors</action>
+      <action>Re-run compilation check</action>
+    </check>
+    <output>Compilation check passed.</output>
+  </step>
+
+  <step n="6.5" goal="Pre-update sync check">
+    <action>Search for {item_id} in both bugs.yaml and bugs.md using grep to check current status</action>
+    <check if="status differs between files OR item missing from one file">
+      <output>SYNC WARNING: {item_id} status mismatch detected
+- bugs.yaml: {yaml_status}
+- bugs.md: {md_status}
+Proceeding will update both files to "{new_status}".</output>
+    </check>
+  </step>
+
+  <step n="7" goal="Update bugs.yaml">
+    <action>Update entry in bugs.yaml:</action>
+    <check if="type == bug">
+      <action>- status: "fixed"</action>
+      <action>- fixed_date: {date} (YYYY-MM-DD format)</action>
+    </check>
+    <check if="type == feature">
+      <action>- status: "implemented"</action>
+      <action>- implemented_date: {date} (YYYY-MM-DD format)</action>
+    </check>
+    <action>- assigned_to: "dev-agent"</action>
+    <action>- files_modified: {list of files changed/created during implementation}</action>
+    <action>- Append to notes: "{past_verb} ({date}): {summary of changes made}"</action>
+    <action>Write updated bugs.yaml</action>
+  </step>
+
+  <step n="8" goal="Update bugs.md">
+    <action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
+
+    <action>**8a. Remove from tracked section (if present)**</action>
+    <check if="type == bug">
+      <action>Search for "{item_id}:" in "# Tracked Bugs" section</action>
+    </check>
+    <check if="type == feature">
+      <action>Search for "{item_id}:" in "# Tracked Feature Requests" section</action>
+    </check>
+    <action>If found, remove the entire entry (including any indented sub-items)</action>
+
+    <action>**8b. Add to completed section (INSERT AT TOP - newest first)**</action>
+    <check if="type == bug">
+      <action>Locate "# Fixed Bugs" section in bugs.md</action>
+      <action>If section not found, create it</action>
+      <action>INSERT AT TOP of section (immediately after "# Fixed Bugs" header):</action>
+      <action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Severity: {severity}, Platform: {platform}, Fixed: {date}, Verified: pending]</action>
+      <action>  - Fix: {description of what was fixed}</action>
+      <action>  - File(s): {list of modified files}</action>
+    </check>
+    <check if="type == feature">
+      <action>Locate "# Implemented Features" section in bugs.md</action>
+      <action>If section not found, create it before "# Fixed Bugs"</action>
+      <action>INSERT AT TOP of section (immediately after "# Implemented Features" header):</action>
+      <action>[IMPLEMENTED] {item_id}: {title} - {brief_description}. [Implemented: {date}, Platform: {platform}, Verified: pending]</action>
+      <action>  - Files: {list of modified/created files}</action>
+      <action>  - Features: {bullet list of what was implemented}</action>
+    </check>
+    <action>Write updated bugs.md</action>
+  </step>
+
+  <step n="9" goal="Post-update validation">
+    <action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
+    <action>Confirm {item_id} shows status "fixed"/"implemented" in bugs.yaml</action>
+    <action>Confirm {item_id} has [IMPLEMENTED] tag in bugs.md</action>
+    <check if="validation fails">
+      <output>SYNC ERROR: Files may be out of sync. Please verify manually:
+- bugs.yaml: Expected status "fixed"/"implemented"
+- bugs.md: Expected [IMPLEMENTED] tag in appropriate section</output>
+    </check>
+  </step>
+
+  <step n="10" goal="Present completion summary">
+    <output>**{item_id} {past_verb.upper()}**
+
+**Changes Made:**
+{for each modified file:}
+- {file_path}: {what was changed}
+{end for}
+
+**Updated Tracking:**
+- bugs.yaml: status -> "{status}", {date_field} -> {date}, files_modified updated
+- bugs.md: Moved to "{target_section}" with [IMPLEMENTED] tag
+
+**Verification Status:** pending
+
+**Next Steps:**
+1. Test manually
+2. Run `/verify {item_id}` after verification to close
+    </output>
+  </step>
+
+</workflow>
+```
+
+## Usage
+
+```
+/implement bug-026
+/implement feature-021
+```
+
+## Key Principles
+
+1. **Auto-detect Type** - ID format determines bug vs feature handling
+2. **Context First** - Always read and present details before implementing
+3. **Confirm Approach** - Validate planned approach with user before coding
+4. **Minimal Changes** - Only implement what's needed, no scope creep
+5. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
+6. **[IMPLEMENTED] Tag** - Indicates complete but awaiting verification
+
+---
+
+## Reference: Bug Tracking Definitions
+
+### Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **critical** | Blocks core functionality, prevents app use, or causes data loss (crashes, auth broken, data corruption) | Fix immediately, may require hotfix |
+| **high** | Major feature broken, significant UX degradation, workaround exists but painful (platform-specific failure, 5+ sec delays, accessibility blocker) | Fix in current/next sprint |
+| **medium** | Feature partially broken, UX degraded but usable (minor feature broken, unclear errors, 1-3 sec delays) | Fix when capacity allows |
+| **low** | Minor issue, cosmetic, edge case (typos, spacing, visual glitches) | Fix opportunistically or defer |
+
+### Complexity Levels
+
+| Level | Description | Effort |
+|-------|-------------|--------|
+| **trivial** | Obvious fix, single line change, no investigation needed (typo, missing semicolon, wrong color) | < 30 minutes |
+| **small** | Single file/component, clear root cause, solution known (missing validation, incorrect prop, logic error) | 30 min - 2 hours |
+| **medium** | Multiple files affected OR investigation required (spans 2-3 components, debugging needed, integration issue) | 2-8 hours |
+| **complex** | Architectural issue, affects multiple stories, requires design changes (race conditions, refactoring, profiling) | 8+ hours (1-2 days) |
+
+### Workflow Routing Matrix
+
+| Severity | Complexity | Workflow | Rationale |
+|----------|------------|----------|-----------|
+| critical | any | correct-course -> urgent | Need impact analysis even if small fix |
+| high | trivial | direct-fix (urgent) | Fast path for obvious important fix |
+| high | small | tech-spec (urgent) | Fast path with minimal overhead |
+| high | medium+ | correct-course -> story | Need proper analysis + testing |
+| medium | trivial | direct-fix | Too small for workflow overhead |
+| medium | small | tech-spec | Isolated fix needs spec |
+| medium | medium+ | correct-course -> story | Multi-file change needs story |
+| low | trivial | direct-fix (defer) | Fix opportunistically |
+| low | small+ | backlog (defer) | Document but don't schedule yet |
+
+### Status Flow
+
+```
+reported -> triaged -> routed -> in-progress -> fixed -> verified -> closed
+```
+
+| Status | Description |
+|--------|-------------|
+| **reported** | Bug logged in bugs.md, not yet analyzed |
+| **triaged** | PM analyzed, assigned severity/complexity/workflow |
+| **routed** | Workflow determined, story/tech-spec created |
+| **in-progress** | Developer actively working on fix |
+| **fixed** | Code changed, tests passing, ready for verification |
+| **verified** | Bug confirmed fixed by reporter or QA |
+| **closed** | Bug resolved and verified, no further action |
+
+### Metadata Fields
+
+| Field | Description |
+|-------|-------------|
+| id | Unique identifier (bug-NNN or feature-NNN) |
+| title | Short description (< 80 chars) |
+| description | Detailed explanation |
+| severity | critical \| high \| medium \| low |
+| complexity | trivial \| small \| medium \| complex |
+| status | Current workflow state |
+| recommended_workflow | direct-fix \| tech-spec \| correct-course \| backlog |
+| effort_estimate | Hours (based on complexity) |
+| reported_by / reported_date | Who found it and when |
+| triaged_by / triaged_date | Who triaged and when |
+| fixed_date / verified_date | Implementation and verification dates |
+| related_story / related_epic | Context links |
+| affected_platform | all \| ios \| android |
+| doc_impact | Documentation impact: prd, architecture, ux flags + notes |
+| notes | Investigation notes, decisions, implementation details |

src/modules/bmm/workflows/implement/workflow.yaml

@@ -0,0 +1,22 @@
+name: implement
+description: "Implement a bug fix or feature - loads context from bugs.yaml, implements the code, updates both bugs.yaml and bugs.md with [IMPLEMENTED] tag"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/implement"
+instructions: "{installed_path}/instructions.md"
+template: false
+
+# Input and output files
+variables:
+  bugs_md: "{output_folder}/bugs.md"
+  bugs_yaml: "{output_folder}/bugs.yaml"
+
+standalone: true

src/modules/bmm/workflows/verify/instructions.md

@@ -0,0 +1,219 @@
+# Verify Workflow (Close Implemented Bugs/Features)
+
+```xml
+<critical>This workflow verifies implemented items and closes them in both bugs.yaml and bugs.md</critical>
+<critical>Communicate in {communication_language} with {user_name}</critical>
+<critical>Removes [IMPLEMENTED] tag and updates status to CLOSED (bugs) or COMPLETE (features)</critical>
+
+<workflow>
+
+  <step n="1" goal="Get item ID or list pending items">
+    <check if="item_id provided in user input">
+      <action>Extract item ID from user input</action>
+      <action>Detect type from ID format:</action>
+      <action>- "bug-NNN" -> type = "bug", final_status = "CLOSED"</action>
+      <action>- "feature-NNN" -> type = "feature", final_status = "COMPLETE"</action>
+      <action>Proceed to Step 2</action>
+    </check>
+    <check if="no item_id provided OR user says 'list'">
+      <action>Search {bugs_yaml} for 'status: "fixed"' or 'status: "implemented"' using grep (do NOT read entire file)</action>
+      <action>Search {bugs_md} for '[IMPLEMENTED]' entries using grep</action>
+      <action>Find all items with:</action>
+      <action>- status == "fixed" or "implemented" in bugs.yaml</action>
+      <action>- [IMPLEMENTED] tag in bugs.md</action>
+      <output>**Pending Verification:**
+
+{for each pending item:}
+- **{item_id}**: {title} [{type}, {fixed_date or implemented_date}]
+{end for}
+
+**Total:** {count} item(s) awaiting verification
+
+To verify an item: `/verify bug-026`
+To verify all: Type "verify all"
+      </output>
+      <ask>Which item would you like to verify?</ask>
+    </check>
+    <check if="user says 'verify all' or 'all'">
+      <action>Set batch_mode = true</action>
+      <action>Collect all pending items</action>
+      <action>Proceed to Step 2 with batch processing</action>
+    </check>
+  </step>
+
+  <step n="2" goal="Load item context and check sync">
+    <action>Search for {item_id} in {bugs_yaml} using grep with 50+ lines of context after the match (do NOT read entire file - it exceeds token limits)</action>
+    <check if="type == bug">
+      <action>Entry will be in bugs section, verify status == "fixed"</action>
+    </check>
+    <check if="type == feature">
+      <action>Entry will be in feature_requests section, verify status == "implemented"</action>
+    </check>
+    <check if="item not found OR status not fixed/implemented">
+      <output>{item_id} is not in an implemented state. Current status: {status}
+
+Only items with status "fixed" (bugs) or "implemented" (features) can be verified.</output>
+      <action>HALT</action>
+    </check>
+    <action>Extract metadata: title, description, fixed_date/implemented_date, notes</action>
+
+    <action>**Sync Check:** Also read {bugs_md} to verify sync status</action>
+    <check if="bugs.yaml says fixed/implemented but bugs.md missing [IMPLEMENTED] tag">
+      <output>SYNC WARNING: {item_id} status mismatch detected
+- bugs.yaml: {yaml_status}
+- bugs.md: Missing [IMPLEMENTED] tag (may have been implemented outside workflow)
+
+Proceeding will update both files to CLOSED/COMPLETE.</output>
+      <ask>Continue with verification? (yes/no)</ask>
+      <check if="user says no">
+        <output>Cancelled. Please run /implement {item_id} first to sync files.</output>
+        <action>HALT</action>
+      </check>
+    </check>
+  </step>
+
+  <step n="3" goal="Confirm verification">
+    <output>**Verify {item_id}: {title}**
+
+**Type:** {type}
+**{past_verb}:** {fixed_date or implemented_date}
+
+**Implementation Notes:**
+{notes - show the FIXED/IMPLEMENTED section}
+
+**Files Changed:**
+{extract file list from notes}
+    </output>
+    <ask>Has this been tested and verified working? (yes/no/skip)</ask>
+    <check if="user says no">
+      <ask>What issue did you find? (I'll add it to the notes)</ask>
+      <action>Append verification failure note to bugs.yaml notes field</action>
+      <output>Noted. {item_id} remains in implemented state for rework.</output>
+      <action>HALT or continue to next item in batch</action>
+    </check>
+    <check if="user says skip">
+      <output>Skipped. {item_id} remains in implemented state.</output>
+      <action>Continue to next item in batch or HALT</action>
+    </check>
+  </step>
+
+  <step n="4" goal="Update bugs.yaml">
+    <action>Update entry in bugs.yaml:</action>
+    <action>- status: "closed"</action>
+    <action>- verified_by: {user_name}</action>
+    <action>- verified_date: {date} (YYYY-MM-DD format)</action>
+    <action>- Append to notes: "Verified ({date}) by {user_name}"</action>
+    <action>Write updated bugs.yaml</action>
+  </step>
+
+  <step n="5" goal="Update bugs.md">
+    <action>Search for {item_id} in {bugs_md} using grep with surrounding context to locate the entry</action>
+
+    <action>**5a. Find the entry**</action>
+    <check if="type == bug">
+      <action>Search for "[IMPLEMENTED] {item_id}:" in "# Fixed Bugs" section</action>
+      <check if="not found">
+        <action>Search for "{item_id}:" in "# Tracked Bugs" section (implemented outside workflow)</action>
+      </check>
+    </check>
+    <check if="type == feature">
+      <action>Search for "[IMPLEMENTED] {item_id}:" in "# Implemented Features" section</action>
+      <check if="not found">
+        <action>Search for "{item_id}:" in "# Tracked Feature Requests" section (implemented outside workflow)</action>
+      </check>
+    </check>
+
+    <action>**5b. Move entry if in wrong section**</action>
+    <check if="entry found in Tracked section (implemented outside workflow)">
+      <action>DELETE the entry from "# Tracked Bugs" or "# Tracked Feature Requests"</action>
+      <action>ADD entry to correct section:</action>
+      <check if="type == bug">
+        <action>Add to "# Fixed Bugs" section</action>
+      </check>
+      <check if="type == feature">
+        <action>Add to "# Implemented Features" section (at top, before other entries)</action>
+      </check>
+    </check>
+
+    <action>**5c. Update the entry format**</action>
+    <action>Remove "[IMPLEMENTED] " prefix if present</action>
+    <action>Update the status tag in brackets:</action>
+    <check if="type == bug">
+      <action>Change from "[Severity: X, Fixed: DATE, Verified: pending]" or "[Severity: X, Complexity: Y, Workflow: Z]"</action>
+      <action>To "[Severity: X, Platform: Y, Fixed: {date}, Verified: {date}, CLOSED]"</action>
+    </check>
+    <check if="type == feature">
+      <action>Change from "[Implemented: DATE, Verified: pending]" or "[Priority: X, Complexity: Y, Workflow: Z]"</action>
+      <action>To "[Implemented: {date}, Platform: Y, Verified: {date}, COMPLETE]"</action>
+    </check>
+    <action>Add implementation notes if available from bugs.yaml</action>
+
+    <action>Write updated bugs.md</action>
+  </step>
+
+  <step n="5.5" goal="Post-update validation">
+    <action>Search for {item_id} in both bugs.yaml and bugs.md using grep to validate updates</action>
+    <action>Confirm bugs.yaml: status="closed", verified_by set, verified_date set</action>
+    <action>Confirm bugs.md: No [IMPLEMENTED] tag, has CLOSED/COMPLETE in status tag</action>
+    <check if="validation fails">
+      <output>SYNC ERROR: Verification may be incomplete. Please check both files:
+- bugs.yaml: Expected status "closed", verified_by/verified_date set
+- bugs.md: Expected CLOSED/COMPLETE tag, no [IMPLEMENTED] prefix</output>
+    </check>
+  </step>
+
+  <step n="6" goal="Present completion summary">
+    <check if="batch_mode">
+      <output>**Verification Complete**
+
+**Verified {verified_count} item(s):**
+{for each verified item:}
+- {item_id}: {title} -> {final_status}
+{end for}
+
+**Skipped:** {skipped_count}
+**Failed verification:** {failed_count}
+
+**Updated Files:**
+- bugs.yaml: status -> "closed", verified_by/verified_date set
+- bugs.md: [IMPLEMENTED] tag removed, status -> {final_status}
+      </output>
+    </check>
+    <check if="not batch_mode">
+      <output>**{item_id} VERIFIED and {final_status}**
+
+**Updated:**
+- bugs.yaml: status -> "closed", verified_by -> {user_name}, verified_date -> {date}
+- bugs.md: Removed [IMPLEMENTED] tag, added "Verified: {date}, {final_status}"
+
+This item is now fully closed.
+      </output>
+    </check>
+  </step>
+
+</workflow>
+```
+
+## Usage
+
+```
+/verify                  # List all pending verification
+/verify bug-026          # Verify specific bug
+/verify feature-021      # Verify specific feature
+/verify all              # Verify all pending items
+```
+
+## Status Transitions
+
+| Type | Before | After |
+|------|--------|-------|
+| Bug | status: "fixed", [IMPLEMENTED] | status: "closed", CLOSED |
+| Feature | status: "implemented", [IMPLEMENTED] | status: "closed", COMPLETE |
+
+## Key Principles
+
+1. **Verification Gate** - User must confirm item was tested and works
+2. **Failure Handling** - If verification fails, add note and keep in implemented state
+3. **Batch Support** - Can verify multiple items at once
+4. **Dual Tracking** - ALWAYS update both bugs.yaml AND bugs.md
+5. **Proper Closure** - Removes [IMPLEMENTED] tag, adds final CLOSED/COMPLETE status

src/modules/bmm/workflows/verify/workflow.yaml

@@ -0,0 +1,22 @@
+name: verify
+description: "Verify and close implemented bugs/features - removes [IMPLEMENTED] tag, updates status to CLOSED/COMPLETE in both bugs.yaml and bugs.md"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/.bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/.bmad/bmm/workflows/verify"
+instructions: "{installed_path}/instructions.md"
+template: false
+
+# Input and output files
+variables:
+  bugs_md: "{output_folder}/bugs.md"
+  bugs_yaml: "{output_folder}/bugs.yaml"
+
+standalone: true

tools/cli/installers/lib/ide/antigravity.js

@@ -48,39 +48,39 @@ class AntigravitySetup extends BaseIdeSetup {
    * @returns {Object} Collected configuration
    */
   async collectConfiguration(options = {}) {
-    const config = {
-      subagentChoices: null,
-      installLocation: null,
-    };
+    // const config = {
+    //   subagentChoices: null,
+    //   installLocation: null,
+    // };
 
-    const sourceModulesPath = getSourcePath('modules');
-    const modules = options.selectedModules || [];
+    // const sourceModulesPath = getSourcePath('modules');
+    // const modules = options.selectedModules || [];
 
-    for (const moduleName of modules) {
-      // Check for Antigravity sub-module injection config in SOURCE directory
-      const injectionConfigPath = path.join(sourceModulesPath, moduleName, 'sub-modules', 'antigravity', 'injections.yaml');
+    // for (const moduleName of modules) {
+    // // Check for Antigravity sub-module injection config in SOURCE directory
+    // const injectionConfigPath = path.join(sourceModulesPath, moduleName, 'sub-modules', 'antigravity', 'injections.yaml');
 
-      if (await this.exists(injectionConfigPath)) {
-        const yaml = require('yaml');
+    // if (await this.exists(injectionConfigPath)) {
+    //   const yaml = require('yaml');
 
-        try {
-          // Load injection configuration
-          const configContent = await fs.readFile(injectionConfigPath, 'utf8');
-          const injectionConfig = yaml.parse(configContent);
+    //   try {
+    //     // Load injection configuration
+    //     const configContent = await fs.readFile(injectionConfigPath, 'utf8');
+    //     const injectionConfig = yaml.parse(configContent);
 
-          // Ask about subagents if they exist and we haven't asked yet
-          if (injectionConfig.subagents && !config.subagentChoices) {
-            config.subagentChoices = await this.promptSubagentInstallation(injectionConfig.subagents);
+    //     // Ask about subagents if they exist and we haven't asked yet
+    //     if (injectionConfig.subagents && !config.subagentChoices) {
+    //       config.subagentChoices = await this.promptSubagentInstallation(injectionConfig.subagents);
 
-            if (config.subagentChoices.install !== 'none') {
-              config.installLocation = await this._promptInstallLocation();
-            }
-          }
-        } catch (error) {
-          console.log(chalk.yellow(`  Warning: Failed to process ${moduleName} features: ${error.message}`));
-        }
-      }
-    }
+    //       if (config.subagentChoices.install !== 'none') {
+    //         config.installLocation = await this._promptInstallLocation();
+    //       }
+    //     }
+    //   } catch (error) {
+    //     console.log(chalk.yellow(`  Warning: Failed to process ${moduleName} features: ${error.message}`));
+    //   }
+    // }
+    // }
 
     return config;
   }
@@ -295,13 +295,13 @@ class AntigravitySetup extends BaseIdeSetup {
         console.log(chalk.cyan(`\nConfiguring ${moduleName} ${handler} features...`));
       }
 
-      if (interactive && config.subagents && !choices) {
-        choices = await this.promptSubagentInstallation(config.subagents);
+      // if (interactive && config.subagents && !choices) {
+      //   choices = await this.promptSubagentInstallation(config.subagents);
 
-        if (choices.install !== 'none') {
-          location = await this._promptInstallLocation();
-        }
-      }
+      //   if (choices.install !== 'none') {
+      //     location = await this._promptInstallLocation();
+      //   }
+      // }
 
       if (config.injections && choices && choices.install !== 'none') {
         for (const injection of config.injections) {

tools/cli/installers/lib/ide/claude-code.js

@@ -41,48 +41,48 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     });
   }
 
-  /**
-   * Collect configuration choices before installation
-   * @param {Object} options - Configuration options
-   * @returns {Object} Collected configuration
-   */
-  async collectConfiguration(options = {}) {
-    const config = {
-      subagentChoices: null,
-      installLocation: null,
-    };
+  // /**
+  //  * Collect configuration choices before installation
+  //  * @param {Object} options - Configuration options
+  //  * @returns {Object} Collected configuration
+  //  */
+  // async collectConfiguration(options = {}) {
+  //   const config = {
+  //     subagentChoices: null,
+  //     installLocation: null,
+  //   };
 
-    const sourceModulesPath = getSourcePath('modules');
-    const modules = options.selectedModules || [];
+  //   const sourceModulesPath = getSourcePath('modules');
+  //   const modules = options.selectedModules || [];
 
-    for (const moduleName of modules) {
-      // Check for Claude Code sub-module injection config in SOURCE directory
-      const injectionConfigPath = path.join(sourceModulesPath, moduleName, 'sub-modules', 'claude-code', 'injections.yaml');
+  //   for (const moduleName of modules) {
+  //     // Check for Claude Code sub-module injection config in SOURCE directory
+  //     const injectionConfigPath = path.join(sourceModulesPath, moduleName, 'sub-modules', 'claude-code', 'injections.yaml');
 
-      if (await this.exists(injectionConfigPath)) {
-        const yaml = require('yaml');
+  //     if (await this.exists(injectionConfigPath)) {
+  //       const yaml = require('yaml');
 
-        try {
-          // Load injection configuration
-          const configContent = await fs.readFile(injectionConfigPath, 'utf8');
-          const injectionConfig = yaml.parse(configContent);
+  //       try {
+  //         // Load injection configuration
+  //         const configContent = await fs.readFile(injectionConfigPath, 'utf8');
+  //         const injectionConfig = yaml.parse(configContent);
 
-          // Ask about subagents if they exist and we haven't asked yet
-          if (injectionConfig.subagents && !config.subagentChoices) {
-            config.subagentChoices = await this.promptSubagentInstallation(injectionConfig.subagents);
+  //         // Ask about subagents if they exist and we haven't asked yet
+  //         if (injectionConfig.subagents && !config.subagentChoices) {
+  //           config.subagentChoices = await this.promptSubagentInstallation(injectionConfig.subagents);
 
-            if (config.subagentChoices.install !== 'none') {
-              config.installLocation = await this.promptInstallLocation();
-            }
-          }
-        } catch (error) {
-          console.log(chalk.yellow(`  Warning: Failed to process ${moduleName} features: ${error.message}`));
-        }
-      }
-    }
+  //           if (config.subagentChoices.install !== 'none') {
+  //             config.installLocation = await this.promptInstallLocation();
+  //           }
+  //         }
+  //       } catch (error) {
+  //         console.log(chalk.yellow(`  Warning: Failed to process ${moduleName} features: ${error.message}`));
+  //       }
+  //     }
+  //   }
 
-    return config;
-  }
+  //   return config;
+  // }
 
   /**
    * Cleanup old BMAD installation before reinstalling
@@ -304,11 +304,10 @@ class ClaudeCodeSetup extends BaseIdeSetup {
       }
 
       if (interactive && config.subagents && !choices) {
-        choices = await this.promptSubagentInstallation(config.subagents);
-
-        if (choices.install !== 'none') {
-          location = await this.promptInstallLocation();
-        }
+        // choices = await this.promptSubagentInstallation(config.subagents);
+        // if (choices.install !== 'none') {
+        //   location = await this.promptInstallLocation();
+        // }
       }
 
       if (config.injections && choices && choices.install !== 'none') {