bmad-method 4.27.6 → 5.0.0

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

@@ -0,0 +1,206 @@
+# Create Next Story Task
+
+## Purpose
+
+To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research.
+
+## Inputs for this Task
+
+- Access to the project's documentation repository, specifically:
+  - `docs/index.md` (hereafter "Index Doc")
+  - All Epic files - located in one of these locations:
+    - Primary: `docs/prd/epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
+    - Secondary: `docs/epics/epic-{n}-{description}.md`
+    - User-specified location if not found in above paths
+  - Existing story files in `docs/stories/`
+  - Main PRD (hereafter "PRD Doc")
+  - Main Architecture Document (hereafter "Main Arch Doc")
+  - Frontend Architecture Document (hereafter "Frontend Arch Doc," if relevant)
+  - Project Structure Guide (`docs/project-structure.md`)
+  - Operational Guidelines Document (`docs/operational-guidelines.md`)
+  - Technology Stack Document (`docs/tech-stack.md`)
+  - Data Models Document (as referenced in Index Doc)
+  - API Reference Document (as referenced in Index Doc)
+  - UI/UX Specifications, Style Guides, Component Guides (if relevant, as referenced in Index Doc)
+- The `bmad-core/templates/story-tmpl.md` (hereafter "Story Template")
+- The `bmad-core/checklists/story-draft-checklist.md` (hereafter "Story Draft Checklist")
+- User confirmation to proceed with story identification and, if needed, to override warnings about incomplete prerequisite stories.
+
+## Task Execution Instructions
+
+### 1. Identify Next Story for Preparation
+
+#### 1.1 Locate Epic Files
+
+- First, determine where epic files are located:
+  - Check `docs/prd/` for files matching pattern `epic-{n}-*.md`
+  - If not found, check `docs/epics/` for files matching pattern `epic-{n}-*.md`
+  - If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored."
+- Note: Epic files follow naming convention `epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
+
+#### 1.2 Review Existing Stories
+
+- Review `docs/stories/` to find the highest-numbered story file.
+- **If a highest story file exists (`{lastEpicNum}.{lastStoryNum}.story.md`):**
+
+  - Verify its `Status` is 'Done' (or equivalent).
+  - If not 'Done', present an alert to the user:
+
+    ```plaintext
+    ALERT: Found incomplete story:
+    File: {lastEpicNum}.{lastStoryNum}.story.md
+    Status: [current status]
+
+    Would you like to:
+    1. View the incomplete story details (instructs user to do so, agent does not display)
+    2. Cancel new story creation at this time
+    3. Accept risk & Override to create the next story in draft
+
+    Please choose an option (1/2/3):
+    ```
+
+  - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}-*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
+  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}-*.md`, then `epic-{lastEpicNum + 2}-*.md`, etc.) whose prerequisites are met.
+
+- **If no story files exist in `docs/stories/`:**
+  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
+- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+- Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
+
+### 2. Gather Core Story Requirements (from Epic File)
+
+- For the identified story, open its parent Epic File (e.g., `epic-{epicNum}-*.md` from the location identified in step 1.1).
+- Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks.
+- Keep a record of this original epic-defined scope for later deviation analysis.
+
+### 3. Review Previous Story and Extract Dev Notes
+
+[[LLM: This step is CRITICAL for continuity and learning from implementation experience]]
+
+- If this is not the first story (i.e., previous story exists):
+  - Read the previous story file: `docs/stories/{prevEpicNum}.{prevStoryNum}.story.md`
+  - Pay special attention to:
+    - Dev Agent Record sections (especially Completion Notes and Debug Log References)
+    - Any deviations from planned implementation
+    - Technical decisions made during implementation
+    - Challenges encountered and solutions applied
+    - Any "lessons learned" or notes for future stories
+  - Extract relevant insights that might inform the current story's preparation
+
+### 4. Gather & Synthesize Architecture Context from Sharded Docs
+
+[[LLM: CRITICAL - You MUST gather technical details from the sharded architecture documents. NEVER make up technical details not found in these documents.]]
+
+#### 4.1 Start with Architecture Index
+
+- Read `docs/architecture/index.md` to understand the full scope of available documentation
+- Identify which sharded documents are most relevant to the current story
+
+#### 4.2 Recommended Reading Order Based on Story Type
+
+[[LLM: Read documents in this order, but ALWAYS verify relevance to the specific story. Skip irrelevant sections but NEVER skip documents that contain information needed for the story.]]
+
+**For ALL Stories:**
+
+1. `docs/architecture/tech-stack.md` - Understand technology constraints and versions
+2. `docs/architecture/unified-project-structure.md` - Know where code should be placed
+3. `docs/architecture/coding-standards.md` - Ensure dev follows project conventions
+4. `docs/architecture/testing-strategy.md` - Include testing requirements in tasks
+
+**For Backend/API Stories, additionally read:** 5. `docs/architecture/data-models.md` - Data structures and validation rules 6. `docs/architecture/database-schema.md` - Database design and relationships 7. `docs/architecture/backend-architecture.md` - Service patterns and structure 8. `docs/architecture/rest-api-spec.md` - API endpoint specifications 9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)
+
+**For Frontend/UI Stories, additionally read:** 5. `docs/architecture/frontend-architecture.md` - Component structure and patterns 6. `docs/architecture/components.md` - Specific component designs 7. `docs/architecture/core-workflows.md` - User interaction flows 8. `docs/architecture/data-models.md` - Frontend data handling
+
+**For Full-Stack Stories:**
+
+- Read both Backend and Frontend sections above
+
+#### 4.3 Extract Story-Specific Technical Details
+
+[[LLM: As you read each document, extract ONLY the information directly relevant to implementing the current story. Do NOT include general information unless it directly impacts the story implementation.]]
+
+For each relevant document, extract:
+
+- Specific data models, schemas, or structures the story will use
+- API endpoints the story must implement or consume
+- Component specifications for UI elements in the story
+- File paths and naming conventions for new code
+- Testing requirements specific to the story's features
+- Security or performance considerations affecting the story
+
+#### 4.4 Document Source References
+
+[[LLM: ALWAYS cite the source document and section for each technical detail you include. This helps the dev agent verify information if needed.]]
+
+Format references as: `[Source: architecture/{filename}.md#{section}]`
+
+### 5. Verify Project Structure Alignment
+
+- Cross-reference the story's requirements and anticipated file manipulations with the Project Structure Guide from `docs/architecture/unified-project-structure.md`.
+- Ensure any file paths, component locations, or module names implied by the story align with defined structures.
+- Document any structural conflicts, necessary clarifications, or undefined components/paths in a "Project Structure Notes" section within the story draft.
+
+### 6. Populate Story Template with Full Context
+
+- Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`.
+- Use the Story Template to structure the file.
+- Fill in:
+  - Story `{EpicNum}.{StoryNum}: {Short Title Copied from Epic File}`
+  - `Status: Draft`
+  - `Story` (User Story statement from Epic)
+  - `Acceptance Criteria (ACs)` (from Epic, to be refined if needed based on context)
+- **`Dev Technical Guidance` section (CRITICAL):**
+
+  [[LLM: This section MUST contain ONLY information extracted from the architecture shards. NEVER invent or assume technical details.]]
+
+  - Include ALL relevant technical details gathered from Steps 3 and 4, organized by category:
+    - **Previous Story Insights**: Key learnings or considerations from the previous story
+    - **Data Models**: Specific schemas, validation rules, relationships [with source references]
+    - **API Specifications**: Endpoint details, request/response formats, auth requirements [with source references]
+    - **Component Specifications**: UI component details, props, state management [with source references]
+    - **File Locations**: Exact paths where new code should be created based on project structure
+    - **Testing Requirements**: Specific test cases or strategies from testing-strategy.md
+    - **Technical Constraints**: Version requirements, performance considerations, security rules
+  - Every technical detail MUST include its source reference: `[Source: architecture/{filename}.md#{section}]`
+  - If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs"
+
+- **`Tasks / Subtasks` section:**
+  - Generate a detailed, sequential list of technical tasks based ONLY on:
+    - Requirements from the Epic
+    - Technical constraints from architecture shards
+    - Project structure from unified-project-structure.md
+    - Testing requirements from testing-strategy.md
+  - Each task must reference relevant architecture documentation
+  - Include unit testing as explicit subtasks based on testing-strategy.md
+  - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`)
+- Add notes on project structure alignment or discrepancies found in Step 5.
+- Prepare content for the "Deviation Analysis" based on any conflicts between epic requirements and architecture constraints.
+
+### 7. Run Story Draft Checklist
+
+- Execute the Story Draft Checklist against the prepared story
+- Document any issues or gaps identified
+- Make necessary adjustments to meet quality standards
+- Ensure all technical guidance is properly sourced from architecture docs
+
+### 8. Finalize Story File
+
+- Review all sections for completeness and accuracy
+- Verify all source references are included for technical details
+- Ensure tasks align with both epic requirements and architecture constraints
+- Update status to "Draft"
+- Save the story file to `docs/stories/{epicNum}.{storyNum}.story.md`
+
+### 9. Report Completion
+
+Provide a summary to the user including:
+
+- Story created: `{epicNum}.{storyNum} - {Story Title}`
+- Status: Draft
+- Key technical components included from architecture docs
+- Any deviations or conflicts noted between epic and architecture
+- Recommendations for story review before approval
+- Next steps: Story should be reviewed by PO for approval before dev work begins
+
+[[LLM: Remember - The success of this task depends on extracting real, specific technical details from the architecture shards. The dev agent should have everything they need in the story file without having to search through multiple documents.]]

package/.bmad-core/tasks/create-team.md

@@ -0,0 +1,229 @@
+# Create Team Task
+
+This task guides you through creating a new BMAD agent team that conforms to the agent-team schema and effectively combines agents for specific project types.
+
+**Note for User-Created Teams**: If creating a custom team for your own use (not part of the core BMAD system), prefix the team name with a period (e.g., `.team-frontend`) to ensure it's gitignored and won't conflict with repository updates.
+
+## Prerequisites
+
+1. Load and understand the team schema: `/bmad-core/schemas/agent-team-schema.yml`
+2. Review existing teams in `/bmad-core/agent-teams/` for patterns and naming conventions
+3. List available agents from `/agents/` to understand team composition options
+4. Review workflows in `/bmad-core/workflows/` to align team capabilities
+
+## Process
+
+### 1. Define Team Purpose and Scope
+
+Before selecting agents, clarify the team's mission:
+
+- **Team Purpose**: What specific problems will this team solve?
+- **Project Types**: Greenfield, brownfield, or both?
+- **Technical Scope**: UI-focused, backend-only, or full-stack?
+- **Team Size Consideration**: Smaller teams (3-5 agents) for focused work, larger teams (6-8) for comprehensive coverage
+
+### 2. Create Team Metadata
+
+Based on the schema requirements:
+
+- **Team Name**: Must follow pattern `^Team .+$` (e.g., "Team Frontend", "Team Analytics")
+  - For user teams: prefix with period (e.g., "Team .MyCustom")
+- **Description**: 20-500 characters explaining team's purpose, capabilities, and use cases
+- **File Name**: `/bmad-core/agent-teams/team-{identifier}.yml`
+  - For user teams: `/bmad-core/agent-teams/.team-{identifier}.yml`
+
+### 3. Select Agents Based on Purpose
+
+#### Discover Available Agents
+
+1. List all agents from `/agents/` directory
+2. Review each agent's role and capabilities
+3. Consider agent synergies and coverage
+
+#### Agent Selection Guidelines
+
+Based on team purpose, recommend agents:
+
+**For Planning & Strategy Teams:**
+
+- `bmad` (required orchestrator)
+- `analyst` - Requirements gathering and research
+- `pm` - Product strategy and documentation
+- `po` - Validation and approval
+- `architect` - Technical planning (if technical planning needed)
+
+**For Design & UX Teams:**
+
+- `bmad` (required orchestrator)
+- `ux-expert` - User experience design
+- `architect` - Frontend architecture
+- `pm` - Product requirements alignment
+- `po` - Design validation
+
+**For Development Teams:**
+
+- `bmad-orchestrator` (required)
+- `sm` - Sprint coordination
+- `dev` - Implementation
+- `qa` - Quality assurance
+- `architect` - Technical guidance
+
+**For Full-Stack Teams:**
+
+- `bmad-orchestrator` (required)
+- `analyst` - Initial planning
+- `pm` - Product management
+- `ux-expert` - UI/UX design (if UI work included)
+- `architect` - System architecture
+- `po` - Validation
+- Additional agents as needed
+
+#### Special Cases
+
+- **Using Wildcard**: If team needs all agents, use `["bmad", "*"]`
+- **Validation**: Schema requires `bmad` in all teams
+
+### 4. Select Workflows
+
+Based on the schema's workflow enum values and team composition:
+
+1. **Analyze team capabilities** against available workflows:
+
+   - `brownfield-fullstack` - Requires full team with UX
+   - `brownfield-service` - Backend-focused team
+   - `brownfield-ui` - UI/UX-focused team
+   - `greenfield-fullstack` - Full team for new projects
+   - `greenfield-service` - Backend team for new services
+   - `greenfield-ui` - Frontend team for new UIs
+
+2. **Match workflows to agents**:
+
+   - UI workflows require `ux-expert`
+   - Service workflows benefit from `architect` and `dev`
+   - All workflows benefit from planning agents (`analyst`, `pm`)
+
+3. **Apply schema validation rules**:
+   - Teams without `ux-expert` shouldn't have UI workflows
+   - Teams named "Team No UI" can't have UI workflows
+
+### 5. Create Team Configuration
+
+Generate the configuration following the schema:
+
+```yaml
+bundle:
+  name: "{Team Name}" # Must match pattern "^Team .+$"
+  description: >-
+    {20-500 character description explaining purpose,
+    capabilities, and ideal use cases}
+
+agents:
+  - bmad # Required orchestrator
+  - { agent-id-1 }
+  - { agent-id-2 }
+  # ... additional agents
+
+workflows:
+  - { workflow-1 } # From enum list
+  - { workflow-2 }
+  # ... additional workflows
+```
+
+### 6. Validate Team Composition
+
+Before finalizing, verify:
+
+1. **Role Coverage**: Does the team have all necessary skills for its workflows?
+2. **Size Optimization**:
+   - Minimum: 2 agents (bmad + 1)
+   - Recommended: 3-7 agents
+   - Maximum with wildcard: bmad + "\*"
+3. **Workflow Alignment**: Can the selected agents execute all workflows?
+4. **Schema Compliance**: Configuration matches all schema requirements
+
+### 7. Integration Recommendations
+
+Document how this team integrates with existing system:
+
+1. **Complementary Teams**: Which existing teams complement this one?
+2. **Handoff Points**: Where does this team hand off to others?
+3. **Use Case Scenarios**: Specific project types ideal for this team
+
+### 8. Validation and Testing
+
+1. **Schema Validation**: Ensure configuration matches agent-team-schema.yml
+2. **Build Validation**: Run `npm run validate`
+3. **Build Team**: Run `npm run build:team -t {team-name}`
+4. **Size Check**: Verify output is appropriate for target platform
+5. **Test Scenarios**: Run sample workflows with the team
+
+## Example Team Creation
+
+### Example 1: API Development Team
+
+```yaml
+bundle:
+  name: "Team API"
+  description: >-
+    Specialized team for API and backend service development. Focuses on
+    robust service architecture, implementation, and testing without UI
+    components. Ideal for microservices, REST APIs, and backend systems.
+
+agents:
+  - bmad
+  - analyst
+  - architect
+  - dev
+  - qa
+  - po
+
+workflows:
+  - greenfield-service
+  - brownfield-service
+```
+
+### Example 2: Rapid Prototyping Team
+
+```yaml
+bundle:
+  name: "Team Prototype"
+  description: >-
+    Agile team for rapid prototyping and proof of concept development.
+    Combines planning, design, and implementation for quick iterations
+    on new ideas and experimental features.
+
+agents:
+  - bmad
+  - pm
+  - ux-expert
+  - architect
+  - dev
+
+workflows:
+  - greenfield-ui
+  - greenfield-fullstack
+```
+
+## Team Creation Checklist
+
+- [ ] Team purpose clearly defined
+- [ ] Name follows schema pattern "Team {Name}"
+- [ ] Description is 20-500 characters
+- [ ] Includes bmad orchestrator
+- [ ] Agents align with team purpose
+- [ ] Workflows match team capabilities
+- [ ] No conflicting validations (e.g., no-UI team with UI workflows)
+- [ ] Configuration validates against schema
+- [ ] Build completes successfully
+- [ ] Output size appropriate for platform
+
+## Best Practices
+
+1. **Start Focused**: Create teams with specific purposes rather than general-purpose teams
+2. **Consider Workflow**: Order agents by typical workflow sequence
+3. **Avoid Redundancy**: Don't duplicate roles unless needed
+4. **Document Rationale**: Explain why each agent is included
+5. **Test Integration**: Verify team works well with selected workflows
+6. **Iterate**: Refine team composition based on usage
+
+This schema-driven approach ensures teams are well-structured, purposeful, and integrate seamlessly with the BMAD ecosystem.

package/{bmad-core → .bmad-core}/tasks/doc-migration-task.md

@@ -68,7 +68,7 @@ The epic numbering starts at 1 and increments for each epic found.
 
 ### Before (PRD):
 
-```markdown
+`````markdown
 # Product Requirements Document
 
 ## 1. Executive Summary
@@ -91,10 +91,9 @@ Epic content...
 
 Content here...
 
-```
+````text
 
 ### After (PRD):
-
 ```markdown
 # Product Requirements Document
 
@@ -114,11 +113,9 @@ Epic content...
 
 ## Success Metrics
 Content here...
-
-```
+```text
 
 ### Before (Non-PRD):
-
 ```markdown
 # Architecture Document
 
@@ -127,10 +124,9 @@ Content...
 
 ## 2.1 Technical Stack & Tools
 Content...
-```
+```text
 
 ### After (Non-PRD):
-
 ```markdown
 # Architecture Document
 
@@ -139,5 +135,9 @@ Content...
 
 ## Technical Stack Tools
 Content...
+````
+`````
 
-```
+```text
+
+```

package/{common → .bmad-core}/tasks/execute-checklist.md

@@ -2,9 +2,13 @@
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
+## Context
+
+The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
+
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -13,7 +17,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from {root}/checklists/
+     - Load the appropriate checklist from bmad-core/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

package/.bmad-core/tasks/generate-ai-frontend-prompt.md

@@ -0,0 +1,58 @@
+# Create AI Frontend Prompt Task
+
+## Purpose
+
+To generate a masterful, comprehensive, and optimized prompt that can be used with AI-driven frontend development tools (e.g., Lovable, Vercel v0, or similar) to scaffold or generate significant portions of the frontend application.
+
+## Inputs
+
+- Completed UI/UX Specification (`front-end-spec-tmpl`)
+- Completed Frontend Architecture Document (`front-end-architecture`)
+- Main System Architecture Document (`architecture` - for API contracts and tech stack)
+- Primary Design Files (Figma, Sketch, etc. - for visual context if the tool can accept it or if descriptions are needed)
+
+## Key Activities & Instructions
+
+1. **Confirm Target AI Generation Platform:**
+
+   - Ask the user to specify which AI frontend generation tool/platform they intend to use (e.g., "Lovable.ai", "Vercel v0", "GPT-4 with direct code generation instructions", etc.).
+   - Explain that prompt optimization might differ slightly based on the platform's capabilities and preferred input format.
+
+2. **Synthesize Inputs into a Structured Prompt:**
+
+   - **Overall Project Context:**
+     - Briefly state the project's purpose (from brief/PRD).
+     - Specify the chosen frontend framework, core libraries, and UI component library (from `front-end-architecture` and main `architecture`).
+     - Mention the styling approach (e.g., Tailwind CSS, CSS Modules).
+   - **Design System & Visuals:**
+     - Reference the primary design files (e.g., Figma link).
+     - If the tool doesn't directly ingest design files, describe the overall visual style, color palette, typography, and key branding elements (from `front-end-spec-tmpl`).
+     - List any global UI components or design tokens that should be defined or adhered to.
+   - **Application Structure & Routing:**
+     - Describe the main pages/views and their routes (from `front-end-architecture` - Routing Strategy).
+     - Outline the navigation structure (from `front-end-spec-tmpl`).
+   - **Key User Flows & Page-Level Interactions:**
+     - For a few critical user flows (from `front-end-spec-tmpl`):
+       - Describe the sequence of user actions and expected UI changes on each relevant page.
+       - Specify API calls to be made (referencing API endpoints from the main `architecture`) and how data should be displayed or used.
+   - **Component Generation Instructions (Iterative or Key Components):**
+     - Based on the chosen AI tool's capabilities, decide on a strategy:
+       - **Option 1 (Scaffolding):** Prompt for the generation of main page structures, layouts, and placeholders for components.
+       - **Option 2 (Key Component Generation):** Select a few critical or complex components from the `front-end-architecture` (Component Breakdown) and provide detailed specifications for them (props, state, basic behavior, key UI elements).
+       - **Option 3 (Holistic, if tool supports):** Attempt to describe the entire application structure and key components more broadly.
+     - <important_note>Advise the user that generating an entire complex application perfectly in one go is rare. Iterative prompting or focusing on sections/key components is often more effective.</important_note>
+   - **State Management (High-Level Pointers):**
+     - Mention the chosen state management solution (e.g., "Use Redux Toolkit").
+     - For key pieces of data, indicate if they should be managed in global state.
+   - **API Integration Points:**
+     - For pages/components that fetch or submit data, clearly state the relevant API endpoints (from `architecture`) and the expected data shapes (can reference schemas in `data-models` or `api-reference` sections of the architecture doc).
+   - **Critical "Don'ts" or Constraints:**
+     - e.g., "Do not use deprecated libraries." "Ensure all forms have basic client-side validation."
+   - **Platform-Specific Optimizations:**
+     - If the chosen AI tool has known best practices for prompting (e.g., specific keywords, structure, level of detail), incorporate them. (This might require the agent to have some general knowledge or to ask the user if they know any such specific prompt modifiers for their chosen tool).
+
+3. **Present and Refine the Master Prompt:**
+   - Output the generated prompt in a clear, copy-pasteable format (e.g., a large code block).
+   - Explain the structure of the prompt and why certain information was included.
+   - Work with the user to refine the prompt based on their knowledge of the target AI tool and any specific nuances they want to emphasize.
+   - <important_note>Remind the user that the generated code from the AI tool will likely require review, testing, and further refinement by developers.</important_note>

package/{bmad-core → .bmad-core}/tasks/index-docs.md

@@ -56,7 +56,7 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
 
 The index should be organized as follows:
 
-```markdown
+`````markdown
 # Documentation Index
 
 ## Root Documents
@@ -89,7 +89,7 @@ Documents within the `another-folder/` directory:
 
 Description of nested document.
 
-```
+````text
 
 ### Index Entry Format
 
@@ -99,7 +99,10 @@ Each entry should follow this format:
 ### [Document Title](relative/path/to/file.md)
 
 Brief description of the document's purpose and contents.
-```
+````
+`````
+
+````
 
 ### Rules of Operation
 
@@ -177,3 +180,4 @@ Please provide:
 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 → .bmad-core}/tasks/shard-doc.md

@@ -6,27 +6,9 @@
 - 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
+## Recommended Method: @kayvan/markdown-tree-parser
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/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 bmad-core/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 bmad-core/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.]]
+[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
 
 ### Installation and Usage
 
@@ -59,19 +41,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 ---
 
-## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
+## Manual Method (if @kayvan/markdown-tree-parser is not available)
 
 [[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
 
 ### Task Instructions
 
-1. Identify Document and Target Location
+### 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
+### 2. Parse and Extract Sections
 
 [[LLM: When sharding the document:
 
@@ -81,7 +63,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
    - 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
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks
      - Mermaid diagrams - preserve the complete diagram syntax
      - Nested markdown elements
      - Multi-line content that might contain ## inside code blocks
@@ -100,7 +82,7 @@ For each extracted section:
 
 2. **Adjust heading levels**:
 
-   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
+   - The level 2 heading becomes level 1 (# instead of ##)
    - All subsection levels decrease by 1:
 
    ```txt