bmad-method 4.15.0 → 4.16.0

package/.bmad-core/templates/story-tmpl.md

@@ -0,0 +1,69 @@
+# Story {{EpicNum}}.{{StoryNum}}: {{Short Title Copied from Epic File specific story}}
+
+## Status: {{ Draft | Approved | InProgress | Review | Done }}
+
+## Story
+
+- As a {{role}}
+- I want {{action}}
+- so that {{benefit}}
+
+## Acceptance Criteria (ACs)
+
+{{ Copy of Acceptance Criteria numbered list }}
+
+## Tasks / Subtasks
+
+- [ ] Task 1 (AC: # if applicable)
+  - [ ] Subtask1.1...
+- [ ] Task 2 (AC: # if applicable)
+  - [ ] Subtask 2.1...
+- [ ] Task 3 (AC: # if applicable)
+  - [ ] Subtask 3.1...
+
+## Dev Notes
+
+[[LLM: populates relevant information, only what was pulled from actual artifacts from docs folder, relevant to this story. Do not invent information. Critical: If known add Relevant Source Tree info that relates to this story. If there were important notes from previous story that are relevant to this one, also include them here if it will help the dev agent. You do NOT need to repeat anything from coding standards or test standards as the dev agent is already aware of those. The dev agent should NEVER need to read the PRD or architecture documents or child documents though to complete this self contained story, because your critical mission is to share the specific items needed here extremely concisely for the Dev Agent LLM to comprehend with the least about of context overhead token usage needed.]]
+
+### Testing
+
+[[LLM: Scrum Master use `test-strategy-and-standards.md` to leave instruction for developer agent in the following concise format, leave unchecked if no specific test requirement of that type]]
+Dev Note: Story Requires the following tests:
+
+- [ ] {{type f.e. Jest}} Unit Tests: (nextToFile: {{true|false}}), coverage requirement: {{from strategy or default 80%}}
+- [ ] {{type f.e. Jest with in memory db}} Integration Test (Test Location): location: {{Integration test location f.e. `/tests/story-name/foo.spec.cs` or `next to handler`}}
+- [ ] {{type f.e. Cypress}} E2E: location: {{f.e. `/e2e/{epic-name/bar.test.ts`}}
+
+Manual Test Steps: [[LLM: Include how if possible the user can manually test the functionality when story is Ready for Review, if any]]
+
+{{ f.e. `- dev will create a script with task 3 above that you can run with "npm run test-initiate-launch-sequence" and validate Armageddon is initiated`}}
+
+## Dev Agent Record
+
+### Agent Model Used: {{Agent Model Name/Version}}
+
+### Debug Log References
+
+[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update]]
+[[LLM: (Dev Agent) If the debug is logged to during the current story progress, create a table with the debug log and the specific task section in the debug log - do not repeat all the details in the story]]
+
+### Completion Notes List
+
+[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
+[[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]
+
+### File List
+
+[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
+
+### Change Log
+
+[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
+[[LLM: (Dev Agent) Track document versions and changes during development that deviate from story dev start]]
+
+| Date | Version | Description | Author |
+| :--- | :------ | :---------- | :----- |
+
+## QA Results
+
+[[LLM: QA Agent Results]]

package/.bmad-core/utils/file-resolution-context.md

@@ -0,0 +1,10 @@
+# File Resolution Context
+
+Update the installer/upgrader so that when agents are added to a project (under Add these two lines to any agent's `activation-instructions` for ide installation:
+
+```yaml
+- IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
+- REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+```
+
+and add `root: .bmad-core` as the first root yml property.

package/.bmad-core/utils/template-format.md

@@ -0,0 +1,26 @@
+# Template Format Conventions
+
+Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+
+## Template Markup Elements
+
+- **{{placeholders}}**: Variables to be replaced with actual content
+- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
+- **REPEAT** sections: Content blocks that may be repeated as needed
+- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
+- **@{examples}**: Example content for guidance (never output to users)
+
+## Processing Rules
+
+- Replace all {{placeholders}} with project-specific content
+- Execute all [[LLM: instructions]] internally without showing users
+- Process conditional and repeat blocks as specified
+- Use examples for guidance but never include them in final output
+- Present only clean, formatted content to users
+
+## Critical Guidelines
+
+- **NEVER display template markup, LLM instructions, or examples to users**
+- Template elements are for AI processing only
+- Focus on faithful template execution and clean output
+- All template-specific instructions are embedded within templates

package/.bmad-core/utils/web-agent-startup-instructions.md

@@ -0,0 +1,39 @@
+# Web Agent Bundle Instructions
+
+You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+
+## Important Instructions
+
+1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
+
+2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
+
+- `==================== START: folder#filename ====================`
+- `==================== END: folder#filename ====================`
+
+When you need to reference a resource mentioned in your instructions:
+
+- Look for the corresponding START/END tags
+- The format is always `folder#filename` (e.g., `personas#analyst`, `tasks#create-story`)
+- If a section is specified (e.g., `tasks#create-story#section-name`), navigate to that section within the file
+
+**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
+
+```yaml
+dependencies:
+  utils:
+    - template-format
+  tasks:
+    - create-story
+```
+
+These references map directly to bundle sections:
+
+- `utils: template-format` → Look for `==================== START: utils#template-format ====================`
+- `tasks: create-story` → Look for `==================== START: tasks#create-story ====================`
+
+3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
+
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+
+---

package/.bmad-core/utils/workflow-management.md

@@ -0,0 +1,223 @@
+# Workflow Management
+
+This utility enables the BMAD orchestrator to manage and execute team workflows.
+
+## Important: Dynamic Workflow Loading
+
+The BMAD orchestrator MUST read the available workflows from the current team configuration's `workflows` field. Do not use hardcoded workflow lists. Each team bundle defines its own set of supported workflows based on the agents it includes.
+
+**Critical Distinction**:
+
+- When asked "what workflows are available?", show ONLY the workflows defined in the current team bundle's configuration
+- Use `/agent-list` to show agents in the current bundle
+- Use `/workflows` to show workflows in the current bundle, NOT any creation tasks
+
+### Workflow Descriptions
+
+When displaying workflows, use these descriptions based on the workflow ID:
+
+- **greenfield-fullstack**: Build a new full-stack application from concept to development
+- **brownfield-fullstack**: Enhance an existing full-stack application with new features
+- **greenfield-service**: Build a new backend service or API from concept to development
+- **brownfield-service**: Enhance an existing backend service or API
+- **greenfield-ui**: Build a new frontend/UI application from concept to development
+- **brownfield-ui**: Enhance an existing frontend/UI application
+
+## Workflow Commands
+
+### /workflows
+
+Lists all available workflows for the current team. The available workflows are determined by the team configuration and may include workflows such as:
+
+- greenfield-fullstack
+- brownfield-fullstack
+- greenfield-service
+- brownfield-service
+- greenfield-ui
+- brownfield-ui
+
+The actual list depends on which team bundle is loaded. When responding to this command, display the workflows that are configured in the current team's `workflows` field.
+
+Example response format:
+
+```text
+Available workflows for [Team Name]:
+1. [workflow-id] - [Brief description based on workflow type]
+2. [workflow-id] - [Brief description based on workflow type]
+[... etc. ...]
+
+Use /workflow-start {number or id} to begin a workflow.
+```
+
+### /workflow-start {workflow-id}
+
+Starts a specific workflow and transitions to the first agent.
+
+Example: `/workflow-start greenfield-fullstack`
+
+### /workflow-status
+
+Shows current workflow progress, completed artifacts, and next steps.
+
+Example response:
+
+```text
+Current Workflow: Greenfield Full-Stack Development
+Stage: Product Planning (2 of 6)
+Completed:
+  ✓ Discovery & Requirements
+    - project-brief (completed by Mary)
+
+In Progress:
+  ⚡ Product Planning
+    - Create PRD (John) - awaiting input
+
+Next: Technical Architecture
+```
+
+### /workflow-resume
+
+Resumes a workflow from where it left off, useful when starting a new chat.
+
+User can provide completed artifacts:
+
+```text
+User: /workflow-resume greenfield-fullstack
+      I have completed: project-brief, PRD
+BMad: I see you've completed Discovery and part of Product Planning.
+      Based on the greenfield-fullstack workflow, the next step is:
+      - UX Strategy with Sally (ux-expert)
+
+      Would you like me to load Sally to continue?
+```
+
+### /workflow-next
+
+Shows the next recommended agent and action in the current workflow.
+
+## Workflow Execution Flow
+
+### 1. Starting a Workflow
+
+When a workflow is started:
+
+1. Load the workflow definition
+2. Identify the first stage and step
+3. Transition to the required agent
+4. Provide context about expected inputs/outputs
+5. Guide artifact creation
+
+### 2. Stage Transitions
+
+After each artifact is completed:
+
+1. Mark the step as complete
+2. Check transition conditions
+3. If stage is complete, move to next stage
+4. Load the appropriate agent
+5. Pass relevant artifacts as context
+
+### 3. Artifact Tracking
+
+Track all created artifacts:
+
+```yaml
+workflow_state:
+  current_workflow: greenfield-fullstack
+  current_stage: planning
+  current_step: 2
+  artifacts:
+    project-brief:
+      status: completed
+      created_by: analyst
+      timestamp: 2024-01-15T10:30:00.000Z
+    prd:
+      status: in-progress
+      created_by: pm
+      started: 2024-01-15T11:00:00.000Z
+```
+
+### 4. Workflow Interruption Handling
+
+When user returns after interruption:
+
+1. Ask if continuing previous workflow
+2. Request any completed artifacts
+3. Analyze provided artifacts
+4. Determine workflow position
+5. Suggest next appropriate step
+
+Example:
+
+```text
+User: I'm working on a new app. Here's my PRD and architecture doc.
+BMad: I see you have a PRD and architecture document. Based on these artifacts,
+      it looks like you're following the greenfield-fullstack workflow and have completed
+      stages 1-3. The next recommended step would be:
+
+      Stage 4: Validation & Refinement
+      - Load Sarah (Product Owner) to validate all artifacts
+
+      Would you like to continue with this workflow?
+```
+
+## Workflow Context Passing
+
+When transitioning between agents, pass:
+
+1. Previous artifacts created
+2. Current workflow stage
+3. Expected outputs
+4. Any decisions or constraints identified
+
+Example transition:
+
+```text
+BMad: Great! John has completed the PRD. According to the greenfield-fullstack workflow,
+      the next step is UX Strategy with Sally.
+
+      /ux-expert
+
+Sally: I see we're in the Product Planning stage of the greenfield-fullstack workflow.
+       I have access to:
+       - Project Brief from Mary
+       - PRD from John
+
+       Let's create the UX strategy and UI specifications. First, let me review
+       the PRD to understand the features we're designing for...
+```
+
+## Multi-Path Workflows
+
+Some workflows may have multiple paths:
+
+```yaml
+conditional_paths:
+  - condition: project_type == 'mobile'
+    next_stage: mobile-specific-design
+  - condition: project_type == 'web'
+    next_stage: web-architecture
+  - default: fullstack-architecture
+```
+
+Handle these by asking clarifying questions when needed.
+
+## Workflow Best Practices
+
+1. **Always show progress** - Users should know where they are
+2. **Explain transitions** - Why moving to next agent
+3. **Preserve context** - Pass relevant information forward
+4. **Allow flexibility** - Users can skip or modify steps
+5. **Track everything** - Maintain complete workflow state
+
+## Integration with Agents
+
+Each agent should be workflow-aware:
+
+- Know which workflow is active
+- Understand their role in the workflow
+- Access previous artifacts
+- Know expected outputs
+- Guide toward workflow goals
+
+This creates a seamless experience where the entire team works together toward the workflow's objectives.

package/.bmad-core/workflows/brownfield-fullstack.yml

@@ -0,0 +1,112 @@
+workflow:
+  id: brownfield-fullstack
+  name: Brownfield Full-Stack Enhancement
+  description: >-
+    Agent workflow for enhancing existing full-stack applications with new features,
+    modernization, or significant changes. Handles existing system analysis and safe integration.
+  type: brownfield
+  project_types:
+    - feature-addition
+    - refactoring
+    - modernization
+    - integration-enhancement
+
+  sequence:
+    - step: project_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: multiple documents per the document-project template
+      notes: "Review existing documentation, codebase structure, and identify integration points. Document current system understanding before proceeding."
+
+    - agent: pm
+      creates: brownfield-prd.md
+      uses: brownfield-prd-tmpl
+      requires: existing_project_analysis
+      notes: "Creates comprehensive brownfield PRD with existing system analysis and enhancement planning. SAVE OUTPUT: Copy final brownfield-prd.md to your project's docs/ folder."
+
+    - agent: architect
+      creates: brownfield-architecture.md
+      uses: brownfield-architecture-tmpl
+      requires: brownfield-prd.md
+      notes: "Creates brownfield architecture with integration strategy and existing system constraints. SAVE OUTPUT: Copy final brownfield-architecture.md to your project's docs/ folder."
+
+    - agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      notes: "Validates all brownfield documents for integration safety and completeness. May require updates to any document."
+
+    - agent: various
+      updates: any_flagged_documents
+      condition: po_checklist_issues
+      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
+
+    - workflow_end:
+      action: move_to_ide
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
+        
+        1. ENSURE DOCUMENTS ARE IN PROJECT:
+           - Copy final prd.md to project's docs/prd.md
+           - Copy final architecture.md to project's docs/architecture.md
+           - All documents must be in the project before proceeding
+        
+        2. SHARD DOCUMENTS (in IDE):
+           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+           - This creates docs/prd/ and docs/architecture/ folders with sharded content
+        
+        3. START DEVELOPMENT CYCLE:
+           a. SM Agent (New Chat): @sm → *create
+              - Creates next story from sharded docs
+              - Review and approve story (Draft → Approved)
+           
+           b. Dev Agent (New Chat): @dev
+              - Implements approved story
+              - Updates File List with all changes
+              - Marks story as "Review" when complete
+           
+           c. QA Agent (New Chat): @qa → review-story
+              - Senior dev review with refactoring ability
+              - Fixes small issues directly
+              - Leaves checklist for remaining items
+              - Updates story status (Review → Done or stays Review)
+           
+           d. If QA left unchecked items:
+              - Dev Agent (New Chat): Address remaining items
+              - Return to QA for final approval
+        
+        4. REPEAT: Continue cycle for all epic stories
+        
+        Reference: data#bmad-kb:IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Brownfield Enhancement] --> B[analyst: analyze existing project]
+        B --> C[pm: brownfield-prd.md]
+        C --> D[architect: brownfield-architecture.md]
+        D --> E[po: validate with po-master-checklist]
+        E --> F{PO finds issues?}
+        F -->|Yes| G[Return to relevant agent for fixes]
+        F -->|No| H[Move to IDE Environment]
+        G --> E
+
+        style H fill:#90EE90
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Enhancement requires coordinated stories
+      - Architectural changes are needed
+      - Significant integration work required
+      - Risk assessment and mitigation planning necessary
+      - Multiple team members will work on related changes
+
+  handoff_prompts:
+    analyst_to_pm: "Existing project analysis complete. Create comprehensive brownfield PRD with integration strategy."
+    pm_to_architect: "Brownfield PRD ready. Save it as docs/brownfield-prd.md, then create the integration architecture."
+    architect_to_po: "Architecture complete. Save it as docs/brownfield-architecture.md. Please validate all artifacts for integration safety."
+    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
+    complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

package/.bmad-core/workflows/brownfield-service.yml

@@ -0,0 +1,113 @@
+workflow:
+  id: brownfield-service
+  name: Brownfield Service/API Enhancement
+  description: >-
+    Agent workflow for enhancing existing backend services and APIs with new features,
+    modernization, or performance improvements. Handles existing system analysis and safe integration.
+  type: brownfield
+  project_types:
+    - service-modernization
+    - api-enhancement
+    - microservice-extraction
+    - performance-optimization
+    - integration-enhancement
+
+  sequence:
+    - step: service_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: multiple documents per the document-project template
+      notes: "Review existing service documentation, codebase, performance metrics, and identify integration dependencies."
+
+    - agent: pm
+      creates: brownfield-prd.md
+      uses: brownfield-prd-tmpl
+      requires: existing_service_analysis
+      notes: "Creates comprehensive brownfield PRD focused on service enhancement with existing system analysis. SAVE OUTPUT: Copy final brownfield-prd.md to your project's docs/ folder."
+
+    - agent: architect
+      creates: brownfield-architecture.md
+      uses: brownfield-architecture-tmpl
+      requires: brownfield-prd.md
+      notes: "Creates brownfield architecture with service integration strategy and API evolution planning. SAVE OUTPUT: Copy final brownfield-architecture.md to your project's docs/ folder."
+
+    - agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      notes: "Validates all brownfield documents for service integration safety and API compatibility. May require updates to any document."
+
+    - agent: various
+      updates: any_flagged_documents
+      condition: po_checklist_issues
+      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
+
+    - workflow_end:
+      action: move_to_ide
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
+        
+        1. ENSURE DOCUMENTS ARE IN PROJECT:
+           - Copy final prd.md to project's docs/prd.md
+           - Copy final architecture.md to project's docs/architecture.md
+           - All documents must be in the project before proceeding
+        
+        2. SHARD DOCUMENTS (in IDE):
+           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+           - This creates docs/prd/ and docs/architecture/ folders with sharded content
+        
+        3. START DEVELOPMENT CYCLE:
+           a. SM Agent (New Chat): @sm → *create
+              - Creates next story from sharded docs
+              - Review and approve story (Draft → Approved)
+           
+           b. Dev Agent (New Chat): @dev
+              - Implements approved story
+              - Updates File List with all changes
+              - Marks story as "Review" when complete
+           
+           c. QA Agent (New Chat): @qa → review-story
+              - Senior dev review with refactoring ability
+              - Fixes small issues directly
+              - Leaves checklist for remaining items
+              - Updates story status (Review → Done or stays Review)
+           
+           d. If QA left unchecked items:
+              - Dev Agent (New Chat): Address remaining items
+              - Return to QA for final approval
+        
+        4. REPEAT: Continue cycle for all epic stories
+        
+        Reference: data#bmad-kb:IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Service Enhancement] --> B[analyst: analyze existing service]
+        B --> C[pm: brownfield-prd.md]
+        C --> D[architect: brownfield-architecture.md]
+        D --> E[po: validate with po-master-checklist]
+        E --> F{PO finds issues?}
+        F -->|Yes| G[Return to relevant agent for fixes]
+        F -->|No| H[Move to IDE Environment]
+        G --> E
+
+        style H fill:#90EE90
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Service enhancement requires coordinated stories
+      - API versioning or breaking changes needed
+      - Database schema changes required
+      - Performance or scalability improvements needed
+      - Multiple integration points affected
+
+  handoff_prompts:
+    analyst_to_pm: "Service analysis complete. Create comprehensive brownfield PRD with service integration strategy."
+    pm_to_architect: "Brownfield PRD ready. Save it as docs/brownfield-prd.md, then create the service architecture."
+    architect_to_po: "Architecture complete. Save it as docs/brownfield-architecture.md. Please validate all artifacts for service integration safety."
+    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
+    complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."