bmad-method 4.37.0-beta.6 → 4.39.0

package/bmad-core/tasks/apply-qa-fixes.md

@@ -0,0 +1,148 @@
+# apply-qa-fixes
+
+Implement fixes based on QA results (gate and assessments) for a specific story. This task is for the Dev agent to systematically consume QA outputs and apply code/test changes while only updating allowed sections in the story file.
+
+## Purpose
+
+- Read QA outputs for a story (gate YAML + assessment markdowns)
+- Create a prioritized, deterministic fix plan
+- Apply code and test changes to close gaps and address issues
+- Update only the allowed story sections for the Dev agent
+
+## Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "2.2"
+  - qa_root: from `bmad-core/core-config.yaml` key `qa.qaLocation` (e.g., `docs/project/qa`)
+  - story_root: from `bmad-core/core-config.yaml` key `devStoryLocation` (e.g., `docs/project/stories`)
+
+optional:
+  - story_title: '{title}' # derive from story H1 if missing
+  - story_slug: '{slug}' # derive from title (lowercase, hyphenated) if missing
+```
+
+## QA Sources to Read
+
+- Gate (YAML): `{qa_root}/gates/{epic}.{story}-*.yml`
+  - If multiple, use the most recent by modified time
+- Assessments (Markdown):
+  - Test Design: `{qa_root}/assessments/{epic}.{story}-test-design-*.md`
+  - Traceability: `{qa_root}/assessments/{epic}.{story}-trace-*.md`
+  - Risk Profile: `{qa_root}/assessments/{epic}.{story}-risk-*.md`
+  - NFR Assessment: `{qa_root}/assessments/{epic}.{story}-nfr-*.md`
+
+## Prerequisites
+
+- Repository builds and tests run locally (Deno 2)
+- Lint and test commands available:
+  - `deno lint`
+  - `deno test -A`
+
+## Process (Do not skip steps)
+
+### 0) Load Core Config & Locate Story
+
+- Read `bmad-core/core-config.yaml` and resolve `qa_root` and `story_root`
+- Locate story file in `{story_root}/{epic}.{story}.*.md`
+  - HALT if missing and ask for correct story id/path
+
+### 1) Collect QA Findings
+
+- Parse the latest gate YAML:
+  - `gate` (PASS|CONCERNS|FAIL|WAIVED)
+  - `top_issues[]` with `id`, `severity`, `finding`, `suggested_action`
+  - `nfr_validation.*.status` and notes
+  - `trace` coverage summary/gaps
+  - `test_design.coverage_gaps[]`
+  - `risk_summary.recommendations.must_fix[]` (if present)
+- Read any present assessment markdowns and extract explicit gaps/recommendations
+
+### 2) Build Deterministic Fix Plan (Priority Order)
+
+Apply in order, highest priority first:
+
+1. High severity items in `top_issues` (security/perf/reliability/maintainability)
+2. NFR statuses: all FAIL must be fixed → then CONCERNS
+3. Test Design `coverage_gaps` (prioritize P0 scenarios if specified)
+4. Trace uncovered requirements (AC-level)
+5. Risk `must_fix` recommendations
+6. Medium severity issues, then low
+
+Guidance:
+
+- Prefer tests closing coverage gaps before/with code changes
+- Keep changes minimal and targeted; follow project architecture and TS/Deno rules
+
+### 3) Apply Changes
+
+- Implement code fixes per plan
+- Add missing tests to close coverage gaps (unit first; integration where required by AC)
+- Keep imports centralized via `deps.ts` (see `docs/project/typescript-rules.md`)
+- Follow DI boundaries in `src/core/di.ts` and existing patterns
+
+### 4) Validate
+
+- Run `deno lint` and fix issues
+- Run `deno test -A` until all tests pass
+- Iterate until clean
+
+### 5) Update Story (Allowed Sections ONLY)
+
+CRITICAL: Dev agent is ONLY authorized to update these sections of the story file. Do not modify any other sections (e.g., QA Results, Story, Acceptance Criteria, Dev Notes, Testing):
+
+- Tasks / Subtasks Checkboxes (mark any fix subtask you added as done)
+- Dev Agent Record →
+  - Agent Model Used (if changed)
+  - Debug Log References (commands/results, e.g., lint/tests)
+  - Completion Notes List (what changed, why, how)
+  - File List (all added/modified/deleted files)
+- Change Log (new dated entry describing applied fixes)
+- Status (see Rule below)
+
+Status Rule:
+
+- If gate was PASS and all identified gaps are closed → set `Status: Ready for Done`
+- Otherwise → set `Status: Ready for Review` and notify QA to re-run the review
+
+### 6) Do NOT Edit Gate Files
+
+- Dev does not modify gate YAML. If fixes address issues, request QA to re-run `review-story` to update the gate
+
+## Blocking Conditions
+
+- Missing `bmad-core/core-config.yaml`
+- Story file not found for `story_id`
+- No QA artifacts found (neither gate nor assessments)
+  - HALT and request QA to generate at least a gate file (or proceed only with clear developer-provided fix list)
+
+## Completion Checklist
+
+- deno lint: 0 problems
+- deno test -A: all tests pass
+- All high severity `top_issues` addressed
+- NFR FAIL → resolved; CONCERNS minimized or documented
+- Coverage gaps closed or explicitly documented with rationale
+- Story updated (allowed sections only) including File List and Change Log
+- Status set according to Status Rule
+
+## Example: Story 2.2
+
+Given gate `docs/project/qa/gates/2.2-*.yml` shows
+
+- `coverage_gaps`: Back action behavior untested (AC2)
+- `coverage_gaps`: Centralized dependencies enforcement untested (AC4)
+
+Fix plan:
+
+- Add a test ensuring the Toolkit Menu "Back" action returns to Main Menu
+- Add a static test verifying imports for service/view go through `deps.ts`
+- Re-run lint/tests and update Dev Agent Record + File List accordingly
+
+## Key Principles
+
+- Deterministic, risk-first prioritization
+- Minimal, maintainable changes
+- Tests validate behavior and close gaps
+- Strict adherence to allowed story update areas
+- Gate ownership remains with QA; Dev signals readiness via Status

package/bmad-core/tasks/create-brownfield-story.md

@@ -128,7 +128,7 @@ Critical: For brownfield, ALWAYS include criteria about maintaining existing fun
 Standard structure:
 
 1. New functionality works as specified
-2. Existing {{affected feature}} continues to work unchanged  
+2. Existing {{affected feature}} continues to work unchanged
 3. Integration with {{existing system}} maintains current behavior
 4. No regression in {{related area}}
 5. Performance remains within acceptable bounds
@@ -139,16 +139,19 @@ Critical: This is where you'll need to be interactive with the user if informati
 
 Create Dev Technical Guidance section with available information:
 
-```markdown
+````markdown
 ## Dev Technical Guidance
 
 ### Existing System Context
+
 [Extract from available documentation]
 
 ### Integration Approach
+
 [Based on patterns found or ask user]
 
 ### Technical Constraints
+
 [From documentation or user input]
 
 ### Missing Information
@@ -191,6 +194,7 @@ Example task structure for brownfield:
   - [ ] Integration test for {{integration point}}
   - [ ] Update existing tests if needed
 ```
+````
 
 ### 5. Risk Assessment and Mitigation
 
@@ -202,14 +206,17 @@ Add section for brownfield-specific risks:
 ## Risk Assessment
 
 ### Implementation Risks
+
 - **Primary Risk**: {{main risk to existing system}}
 - **Mitigation**: {{how to address}}
 - **Verification**: {{how to confirm safety}}
 
 ### Rollback Plan
+
 - {{Simple steps to undo changes if needed}}
 
 ### Safety Checks
+
 - [ ] Existing {{feature}} tested before changes
 - [ ] Changes can be feature-flagged or isolated
 - [ ] Rollback procedure documented
@@ -252,6 +259,7 @@ Include header noting documentation context:
 <!-- Context: Brownfield enhancement to {{existing system}} -->
 
 ## Status: Draft
+
 [Rest of story content...]
 ```
 
@@ -272,7 +280,7 @@ Key Integration Points Identified:
 Risks Noted:
 - {{primary risk}}
 
-{{If missing info}}: 
+{{If missing info}}:
 Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.
 
 Next Steps:

package/bmad-core/tasks/create-deep-research-prompt.md

@@ -21,63 +21,54 @@ CRITICAL: First, help the user select the most appropriate research focus based
 Present these numbered options to the user:
 
 1. **Product Validation Research**
-
    - Validate product hypotheses and market fit
    - Test assumptions about user needs and solutions
    - Assess technical and business feasibility
    - Identify risks and mitigation strategies
 
 2. **Market Opportunity Research**
-
    - Analyze market size and growth potential
    - Identify market segments and dynamics
    - Assess market entry strategies
    - Evaluate timing and market readiness
 
 3. **User & Customer Research**
-
    - Deep dive into user personas and behaviors
    - Understand jobs-to-be-done and pain points
    - Map customer journeys and touchpoints
    - Analyze willingness to pay and value perception
 
 4. **Competitive Intelligence Research**
-
    - Detailed competitor analysis and positioning
    - Feature and capability comparisons
    - Business model and strategy analysis
    - Identify competitive advantages and gaps
 
 5. **Technology & Innovation Research**
-
    - Assess technology trends and possibilities
    - Evaluate technical approaches and architectures
    - Identify emerging technologies and disruptions
    - Analyze build vs. buy vs. partner options
 
 6. **Industry & Ecosystem Research**
-
    - Map industry value chains and dynamics
    - Identify key players and relationships
    - Analyze regulatory and compliance factors
    - Understand partnership opportunities
 
 7. **Strategic Options Research**
-
    - Evaluate different strategic directions
    - Assess business model alternatives
    - Analyze go-to-market strategies
    - Consider expansion and scaling paths
 
 8. **Risk & Feasibility Research**
-
    - Identify and assess various risk factors
    - Evaluate implementation challenges
    - Analyze resource requirements
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
@@ -246,13 +237,11 @@ CRITICAL: collaborate with the user to develop specific, actionable research que
 ### 5. Review and Refinement
 
 1. **Present Complete Prompt**
-
    - Show the full research prompt
    - Explain key elements and rationale
    - Highlight any assumptions made
 
 2. **Gather Feedback**
-
    - Are the objectives clear and correct?
    - Do the questions address all concerns?
    - Is the scope appropriate?

package/bmad-core/tasks/document-project.md

@@ -111,9 +111,9 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 
 ### Change Log
 
-| Date | Version | Description | Author |
-|------|---------|-------------|--------|
-| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
+| Date   | Version | Description                 | Author    |
+| ------ | ------- | --------------------------- | --------- |
+| [Date] | 1.0     | Initial brownfield analysis | [Analyst] |
 
 ## Quick Reference - Key Files and Entry Points
 
@@ -136,11 +136,11 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 
 ### Actual Tech Stack (from package.json/requirements.txt)
 
-| Category | Technology | Version | Notes |
-|----------|------------|---------|--------|
-| Runtime | Node.js | 16.x | [Any constraints] |
-| Framework | Express | 4.18.2 | [Custom middleware?] |
-| Database | PostgreSQL | 13 | [Connection pooling setup] |
+| Category  | Technology | Version | Notes                      |
+| --------- | ---------- | ------- | -------------------------- |
+| Runtime   | Node.js    | 16.x    | [Any constraints]          |
+| Framework | Express    | 4.18.2  | [Custom middleware?]       |
+| Database  | PostgreSQL | 13      | [Connection pooling setup] |
 
 etc...
 
@@ -179,6 +179,7 @@ project-root/
 ### Data Models
 
 Instead of duplicating, reference actual model files:
+
 - **User Model**: See `src/models/User.js`
 - **Order Model**: See `src/models/Order.js`
 - **Related Types**: TypeScript definitions in `src/types/`
@@ -208,10 +209,10 @@ Instead of duplicating, reference actual model files:
 
 ### External Services
 
-| Service | Purpose | Integration Type | Key Files |
-|---------|---------|------------------|-----------|
-| Stripe | Payments | REST API | `src/integrations/stripe/` |
-| SendGrid | Emails | SDK | `src/services/emailService.js` |
+| Service  | Purpose  | Integration Type | Key Files                      |
+| -------- | -------- | ---------------- | ------------------------------ |
+| Stripe   | Payments | REST API         | `src/integrations/stripe/`     |
+| SendGrid | Emails   | SDK              | `src/services/emailService.js` |
 
 etc...
 
@@ -256,6 +257,7 @@ npm run test:integration  # Runs integration tests (requires local DB)
 ### Files That Will Need Modification
 
 Based on the enhancement requirements, these files will be affected:
+
 - `src/services/userService.js` - Add new user fields
 - `src/models/User.js` - Update schema
 - `src/routes/userRoutes.js` - New endpoints
@@ -338,4 +340,4 @@ Apply the advanced elicitation task after major sections to refine based on user
 - References actual files rather than duplicating content when possible
 - Documents technical debt, workarounds, and constraints honestly
 - For brownfield projects with PRD: Provides clear enhancement impact analysis
-- The goal is PRACTICAL documentation for AI agents doing real work
+- The goal is PRACTICAL documentation for AI agents doing real work

package/bmad-core/tasks/facilitate-brainstorming-session.md

@@ -1,6 +1,6 @@
 ---
 docOutputLocation: docs/brainstorming-session-results.md
-template: "{root}/templates/brainstorming-output-tmpl.yaml"
+template: '{root}/templates/brainstorming-output-tmpl.yaml'
 ---
 
 # Facilitate Brainstorming Session Task
@@ -43,7 +43,7 @@ If user selects Option 1, present numbered list of techniques from the brainstor
 1. Apply selected technique according to data file description
 2. Keep engaging with technique until user indicates they want to:
    - Choose a different technique
-   - Apply current ideas to a new technique  
+   - Apply current ideas to a new technique
    - Move to convergent phase
    - End session
 

package/bmad-core/tasks/index-docs.md

@@ -11,14 +11,12 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
 ### Required Steps
 
 1. First, locate and scan:
-
    - The `docs/` directory and all subdirectories
    - The existing `docs/index.md` file (create if absent)
    - All markdown (`.md`) and text (`.txt`) files in the documentation structure
    - Note the folder structure for hierarchical organization
 
 2. For the existing `docs/index.md`:
-
    - Parse current entries
    - Note existing file references and descriptions
    - Identify any broken links or missing files
@@ -26,7 +24,6 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
    - Preserve existing folder sections
 
 3. For each documentation file found:
-
    - Extract the title (from first heading or filename)
    - Generate a brief description by analyzing the content
    - Create a relative markdown link to the file
@@ -35,7 +32,6 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
    - If missing or outdated, prepare an update
 
 4. For any missing or non-existent files found in index:
-
    - Present a list of all entries that reference non-existent files
    - For each entry:
      - Show the full entry details (title, path, description)
@@ -88,7 +84,6 @@ Documents within the `another-folder/` directory:
 ### [Nested Document](./another-folder/document.md)
 
 Description of nested document.
-
 ```
 
 ### Index Entry Format
@@ -157,7 +152,6 @@ For each file referenced in the index but not found in the filesystem:
 ### Special Cases
 
 1. **Sharded Documents**: If a folder contains an `index.md` file, treat it as a sharded document:
-
    - Use the folder's `index.md` title as the section title
    - List the folder's documents as subsections
    - Note in the description that this is a multi-part document

package/bmad-core/tasks/kb-mode-interaction.md

@@ -6,7 +6,7 @@ Provide a user-friendly interface to the BMad knowledge base without overwhelmin
 
 ## Instructions
 
-When entering KB mode (*kb-mode), follow these steps:
+When entering KB mode (\*kb-mode), follow these steps:
 
 ### 1. Welcome and Guide
 
@@ -48,12 +48,12 @@ Or ask me about anything else related to BMad-Method!
 When user is done or wants to exit KB mode:
 
 - Summarize key points discussed if helpful
-- Remind them they can return to KB mode anytime with *kb-mode
+- Remind them they can return to KB mode anytime with \*kb-mode
 - Suggest next steps based on what was discussed
 
 ## Example Interaction
 
-**User**: *kb-mode
+**User**: \*kb-mode
 
 **Assistant**: I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method.