bmad-method 4.37.0-beta.5 → 4.37.0

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

@@ -0,0 +1,173 @@
+# Index Documentation Task
+
+## Purpose
+
+This task maintains the integrity and completeness of the `docs/index.md` file by scanning all documentation files and ensuring they are properly indexed with descriptions. It handles both root-level documents and documents within subfolders, organizing them hierarchically.
+
+## Task Instructions
+
+You are now operating as a Documentation Indexer. Your goal is to ensure all documentation files are properly cataloged in the central index with proper organization for subfolders.
+
+### 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
+   - Keep track of already-indexed content
+   - 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
+   - Check if it's already in the index
+   - Note which folder it belongs to (if in a subfolder)
+   - 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)
+     - Ask for explicit confirmation before removal
+     - Provide option to update the path if file was moved
+     - Log the decision (remove/update/keep) for final report
+
+5. Update `docs/index.md`:
+   - Maintain existing structure and organization
+   - Create level 2 sections (`##`) for each subfolder
+   - List root-level documents first
+   - Add missing entries with descriptions
+   - Update outdated entries
+   - Remove only entries that were confirmed for removal
+   - Ensure consistent formatting throughout
+
+### Index Structure Format
+
+The index should be organized as follows:
+
+```markdown
+# Documentation Index
+
+## Root Documents
+
+### [Document Title](./document.md)
+
+Brief description of the document's purpose and contents.
+
+### [Another Document](./another.md)
+
+Description here.
+
+## Folder Name
+
+Documents within the `folder-name/` directory:
+
+### [Document in Folder](./folder-name/document.md)
+
+Description of this document.
+
+### [Another in Folder](./folder-name/another.md)
+
+Description here.
+
+## Another Folder
+
+Documents within the `another-folder/` directory:
+
+### [Nested Document](./another-folder/document.md)
+
+Description of nested document.
+```
+
+### Index Entry Format
+
+Each entry should follow this format:
+
+```markdown
+### [Document Title](relative/path/to/file.md)
+
+Brief description of the document's purpose and contents.
+```
+
+### Rules of Operation
+
+1. NEVER modify the content of indexed files
+2. Preserve existing descriptions in index.md when they are adequate
+3. Maintain any existing categorization or grouping in the index
+4. Use relative paths for all links (starting with `./`)
+5. Ensure descriptions are concise but informative
+6. NEVER remove entries without explicit confirmation
+7. Report any broken links or inconsistencies found
+8. Allow path updates for moved files before considering removal
+9. Create folder sections using level 2 headings (`##`)
+10. Sort folders alphabetically, with root documents listed first
+11. Within each section, sort documents alphabetically by title
+
+### Process Output
+
+The task will provide:
+
+1. A summary of changes made to index.md
+2. List of newly indexed files (organized by folder)
+3. List of updated entries
+4. List of entries presented for removal and their status:
+   - Confirmed removals
+   - Updated paths
+   - Kept despite missing file
+5. Any new folders discovered
+6. Any other issues or inconsistencies found
+
+### Handling Missing Files
+
+For each file referenced in the index but not found in the filesystem:
+
+1. Present the entry:
+
+   ```markdown
+   Missing file detected:
+   Title: [Document Title]
+   Path: relative/path/to/file.md
+   Description: Existing description
+   Section: [Root Documents | Folder Name]
+
+   Options:
+
+   1. Remove this entry
+   2. Update the file path
+   3. Keep entry (mark as temporarily unavailable)
+
+   Please choose an option (1/2/3):
+   ```
+
+2. Wait for user confirmation before taking any action
+3. Log the decision for the final report
+
+### 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
+
+2. **README files**: Convert `README.md` to more descriptive titles based on content
+
+3. **Nested Subfolders**: For deeply nested folders, maintain the hierarchy but limit to 2 levels in the main index. Deeper structures should have their own index files.
+
+## Required Input
+
+Please provide:
+
+1. Location of the `docs/` directory (default: `./docs`)
+2. Confirmation of write access to `docs/index.md`
+3. Any specific categorization preferences
+4. Any files or directories to exclude from indexing (e.g., `.git`, `node_modules`)
+5. Whether to include hidden files/folders (starting with `.`)
+
+Would you like to proceed with documentation indexing? Please provide the required input above.

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

@@ -0,0 +1,75 @@
+# KB Mode Interaction Task
+
+## Purpose
+
+Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (\*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+
+Announce entering KB mode with a brief, friendly introduction.
+
+### 2. Present Topic Areas
+
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMad
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMad implements Agile methodologies
+7. **Configuration** - Customizing BMad for your needs
+8. **Best Practices** - Tips for effective BMad usage
+
+Or ask me about anything else related to BMad-Method!
+
+### 3. Respond Contextually
+
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+
+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
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**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.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMad
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMad implements Agile methodologies
+7. **Configuration** - Customizing BMad for your needs
+8. **Best Practices** - Tips for effective BMad usage
+
+Or ask me about anything else related to BMad-Method!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]

package/bmad-core/tasks/review-story.md

@@ -0,0 +1,154 @@
+# review-story
+
+When a developer agent marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
+
+## Prerequisites
+
+- Story status must be "Review"
+- Developer has completed all tasks and updated the File List
+- All automated tests are passing
+
+## Review Process
+
+1. **Read the Complete Story**
+   - Review all acceptance criteria
+   - Understand the dev notes and requirements
+   - Note any completion notes from the developer
+
+2. **Verify Implementation Against Dev Notes Guidance**
+   - Review the "Dev Notes" section for specific technical guidance provided to the developer
+   - Verify the developer's implementation follows the architectural patterns specified in Dev Notes
+   - Check that file locations match the project structure guidance in Dev Notes
+   - Confirm any specified libraries, frameworks, or technical approaches were used correctly
+   - Validate that security considerations mentioned in Dev Notes were implemented
+
+3. **Focus on the File List**
+   - Verify all files listed were actually created/modified
+   - Check for any missing files that should have been updated
+   - Ensure file locations align with the project structure guidance from Dev Notes
+
+4. **Senior Developer Code Review**
+   - Review code with the eye of a senior developer
+   - If changes form a cohesive whole, review them together
+   - If changes are independent, review incrementally file by file
+   - Focus on:
+     - Code architecture and design patterns
+     - Refactoring opportunities
+     - Code duplication or inefficiencies
+     - Performance optimizations
+     - Security concerns
+     - Best practices and patterns
+
+5. **Active Refactoring**
+   - As a senior developer, you CAN and SHOULD refactor code where improvements are needed
+   - When refactoring:
+     - Make the changes directly in the files
+     - Explain WHY you're making the change
+     - Describe HOW the change improves the code
+     - Ensure all tests still pass after refactoring
+     - Update the File List if you modify additional files
+
+6. **Standards Compliance Check**
+   - Verify adherence to `docs/coding-standards.md`
+   - Check compliance with `docs/unified-project-structure.md`
+   - Validate testing approach against `docs/testing-strategy.md`
+   - Ensure all guidelines mentioned in the story are followed
+
+7. **Acceptance Criteria Validation**
+   - Verify each AC is fully implemented
+   - Check for any missing functionality
+   - Validate edge cases are handled
+
+8. **Test Coverage Review**
+   - Ensure unit tests cover edge cases
+   - Add missing tests if critical coverage is lacking
+   - Verify integration tests (if required) are comprehensive
+   - Check that test assertions are meaningful
+   - Look for missing test scenarios
+
+9. **Documentation and Comments**
+   - Verify code is self-documenting where possible
+   - Add comments for complex logic if missing
+   - Ensure any API changes are documented
+
+## Update Story File - QA Results Section ONLY
+
+**CRITICAL**: You are ONLY authorized to update the "QA Results" section of the story file. DO NOT modify any other sections.
+
+After review and any refactoring, append your results to the story file in the QA Results section:
+
+```markdown
+## QA Results
+
+### Review Date: [Date]
+
+### Reviewed By: Quinn (Senior Developer QA)
+
+### Code Quality Assessment
+
+[Overall assessment of implementation quality]
+
+### Refactoring Performed
+
+[List any refactoring you performed with explanations]
+
+- **File**: [filename]
+  - **Change**: [what was changed]
+  - **Why**: [reason for change]
+  - **How**: [how it improves the code]
+
+### Compliance Check
+
+- Coding Standards: [✓/✗] [notes if any]
+- Project Structure: [✓/✗] [notes if any]
+- Testing Strategy: [✓/✗] [notes if any]
+- All ACs Met: [✓/✗] [notes if any]
+
+### Improvements Checklist
+
+[Check off items you handled yourself, leave unchecked for dev to address]
+
+- [x] Refactored user service for better error handling (services/user.service.ts)
+- [x] Added missing edge case tests (services/user.service.test.ts)
+- [ ] Consider extracting validation logic to separate validator class
+- [ ] Add integration test for error scenarios
+- [ ] Update API documentation for new error codes
+
+### Security Review
+
+[Any security concerns found and whether addressed]
+
+### Performance Considerations
+
+[Any performance issues found and whether addressed]
+
+### Final Status
+
+[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
+```
+
+## Key Principles
+
+- You are a SENIOR developer reviewing junior/mid-level work
+- You have the authority and responsibility to improve code directly
+- Always explain your changes for learning purposes
+- Balance between perfection and pragmatism
+- Focus on significant improvements, not nitpicks
+
+## Blocking Conditions
+
+Stop the review and request clarification if:
+
+- Story file is incomplete or missing critical sections
+- File List is empty or clearly incomplete
+- No tests exist when they were required
+- Code changes don't align with story requirements
+- Critical architectural issues that require discussion
+
+## Completion
+
+After review:
+
+1. If all items are checked and approved: Update story status to "Done"
+2. If unchecked items remain: Keep status as "Review" for dev to address
+3. Always provide constructive feedback and explanations for learning

package/bmad-core/tasks/shard-doc.md

@@ -0,0 +1,185 @@
+# Document Sharding Task
+
+## Purpose
+
+- Split a large document into multiple smaller documents based on level 2 sections
+- Create a folder structure to organize the sharded documents
+- Maintain all content integrity including code blocks, diagrams, and markdown formatting
+
+## Primary Method: Automatic with markdown-tree
+
+[[LLM: First, check if markdownExploder is set to true in {root}/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+
+If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
+
+If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
+
+1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+2. Or set markdownExploder to false in {root}/core-config.yaml
+
+**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
+
+If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
+
+1. Set markdownExploder to true in {root}/core-config.yaml
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]
+
+### Installation and Usage
+
+1. **Install globally**:
+
+   ```bash
+   npm install -g @kayvan/markdown-tree-parser
+   ```
+
+2. **Use the explode command**:
+
+   ```bash
+   # For PRD
+   md-tree explode docs/prd.md docs/prd
+
+   # For Architecture
+   md-tree explode docs/architecture.md docs/architecture
+
+   # For any document
+   md-tree explode [source-document] [destination-folder]
+   ```
+
+3. **What it does**:
+   - Automatically splits the document by level 2 sections
+   - Creates properly named files
+   - Adjusts heading levels appropriately
+   - Handles all edge cases with code blocks and special markdown
+
+If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
+
+---
+
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
+
+### Task Instructions
+
+1. Identify Document and Target Location
+
+- Determine which document to shard (user-provided path)
+- Create a new folder under `docs/` with the same name as the document (without extension)
+- Example: `docs/prd.md` → create folder `docs/prd/`
+
+2. Parse and Extract Sections
+
+CRITICAL AEGNT SHARDING RULES:
+
+1. Read the entire document content
+2. Identify all level 2 sections (## headings)
+3. For each level 2 section:
+   - Extract the section heading and ALL content until the next level 2 section
+   - Include all subsections, code blocks, diagrams, lists, tables, etc.
+   - Be extremely careful with:
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
+     - Mermaid diagrams - preserve the complete diagram syntax
+     - Nested markdown elements
+     - Multi-line content that might contain ## inside code blocks
+
+CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
+
+### 3. Create Individual Files
+
+For each extracted section:
+
+1. **Generate filename**: Convert the section heading to lowercase-dash-case
+   - Remove special characters
+   - Replace spaces with dashes
+   - Example: "## Tech Stack" → `tech-stack.md`
+
+2. **Adjust heading levels**:
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
+   - All subsection levels decrease by 1:
+
+   ```txt
+     - ### → ##
+     - #### → ###
+     - ##### → ####
+     - etc.
+   ```
+
+3. **Write content**: Save the adjusted content to the new file
+
+### 4. Create Index File
+
+Create an `index.md` file in the sharded folder that:
+
+1. Contains the original level 1 heading and any content before the first level 2 section
+2. Lists all the sharded files with links:
+
+```markdown
+# Original Document Title
+
+[Original introduction content if any]
+
+## Sections
+
+- [Section Name 1](./section-name-1.md)
+- [Section Name 2](./section-name-2.md)
+- [Section Name 3](./section-name-3.md)
+  ...
+```
+
+### 5. Preserve Special Content
+
+1. **Code blocks**: Must capture complete blocks including:
+
+   ```language
+   content
+   ```
+
+2. **Mermaid diagrams**: Preserve complete syntax:
+
+   ```mermaid
+   graph TD
+   ...
+   ```
+
+3. **Tables**: Maintain proper markdown table formatting
+
+4. **Lists**: Preserve indentation and nesting
+
+5. **Inline code**: Preserve backticks
+
+6. **Links and references**: Keep all markdown links intact
+
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
+
+### 6. Validation
+
+After sharding:
+
+1. Verify all sections were extracted
+2. Check that no content was lost
+3. Ensure heading levels were properly adjusted
+4. Confirm all files were created successfully
+
+### 7. Report Results
+
+Provide a summary:
+
+```text
+Document sharded successfully:
+- Source: [original document path]
+- Destination: docs/[folder-name]/
+- Files created: [count]
+- Sections:
+  - section-name-1.md: "Section Title 1"
+  - section-name-2.md: "Section Title 2"
+  ...
+```
+
+## Important Notes
+
+- Never modify the actual content, only adjust heading levels
+- Preserve ALL formatting, including whitespace where significant
+- Handle edge cases like sections with code blocks containing ## symbols
+- Ensure the sharding is reversible (could reconstruct the original from shards)