bmad-method 4.2.0 → 4.4.0

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

@@ -2,57 +2,50 @@
 
 ## 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.
+To generate a masterful, comprehensive, and optimized prompt that can be used with any AI-driven frontend development tool (e.g., Vercel v0, Lovable.ai, or similar) to scaffold or generate significant portions of a 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)
+- Completed UI/UX Specification (`front-end-spec`)
+- Completed Frontend Architecture Document (`front-end-architecture`) or a full stack combined architecture such as `architecture.md`
+- Main System Architecture Document (`architecture` - for API contracts and tech stack to give further context)
 
 ## 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>
+### 1. Core Prompting Principles
+
+Before generating the prompt, you must understand these core principles for interacting with a generative AI for code.
+
+- **Be Explicit and Detailed**: The AI cannot read your mind. Provide as much detail and context as possible. Vague requests lead to generic or incorrect outputs.
+- **Iterate, Don't Expect Perfection**: Generating an entire complex application in one go is rare. The most effective method is to prompt for one component or one section at a time, then build upon the results.
+- **Provide Context First**: Always start by providing the AI with the necessary context, such as the tech stack, existing code snippets, and overall project goals.
+- **Mobile-First Approach**: Frame all UI generation requests with a mobile-first design mindset. Describe the mobile layout first, then provide separate instructions for how it should adapt for tablet and desktop.
+
+### 2. The Structured Prompting Framework
+
+To ensure the highest quality output, you MUST structure every prompt using the following four-part framework.
+
+1. **High-Level Goal**: Start with a clear, concise summary of the overall objective. This orients the AI on the primary task.
+   - _Example: "Create a responsive user registration form with client-side validation and API integration."_
+2. **Detailed, Step-by-Step Instructions**: Provide a granular, numbered list of actions the AI should take. Break down complex tasks into smaller, sequential steps. This is the most critical part of the prompt.
+   - _Example: "1. Create a new file named `RegistrationForm.js`. 2. Use React hooks for state management. 3. Add styled input fields for 'Name', 'Email', and 'Password'. 4. For the email field, ensure it is a valid email format. 5. On submission, call the API endpoint defined below."_
+3. **Code Examples, Data Structures & Constraints**: Include any relevant snippets of existing code, data structures, or API contracts. This gives the AI concrete examples to work with. Crucially, you must also state what _not_ to do.
+   - _Example: "Use this API endpoint: `POST /api/register`. The expected JSON payload is `{ "name": "string", "email": "string", "password": "string" }`. Do NOT include a 'confirm password' field. Use Tailwind CSS for all styling."_
+4. **Define a Strict Scope**: Explicitly define the boundaries of the task. Tell the AI which files it can modify and, more importantly, which files to leave untouched to prevent unintended changes across the codebase.
+   - _Example: "You should only create the `RegistrationForm.js` component and add it to the `pages/register.js` file. Do NOT alter the `Navbar.js` component or any other existing page or component."_
+
+### 3. Assembling the Master Prompt
+
+You will now synthesize the inputs and the above principles into a final, comprehensive prompt.
+
+1. **Gather Foundational Context**:
+   - Start the prompt with a preamble describing the overall project purpose, the full tech stack (e.g., Next.js, TypeScript, Tailwind CSS), and the primary UI component library being used.
+2. **Describe the Visuals**:
+   - If the user has design files (Figma, etc.), instruct them to provide links or screenshots.
+   - If not, describe the visual style: color palette, typography, spacing, and overall aesthetic (e.g., "minimalist", "corporate", "playful").
+3. **Build the Prompt using the Structured Framework**:
+   - Follow the four-part framework from Section 2 to build out the core request, whether it's for a single component or a full page.
+4. **Present and Refine**:
+   - Output the complete, 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, referencing the principles above.
+   - <important_note>Conclude by reminding the user that all AI-generated code will require careful human review, testing, and refinement to be considered production-ready.</important_note>

package/.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
@@ -88,7 +88,8 @@ Documents within the `another-folder/` directory:
 ### [Nested Document](./another-folder/document.md)
 
 Description of nested document.
-```text
+
+````text
 
 ### Index Entry Format
 
@@ -98,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
 
@@ -176,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/templates/architecture-tmpl.md

@@ -136,7 +136,7 @@ Common patterns to consider:
 
 [[LLM: This is the DEFINITIVE technology selection section. Work with the user to make specific choices:
 
-1. Review PRD technical assumptions and any preferences from `data#technical-preferences`
+1. Review PRD technical assumptions and any preferences from `data#technical-preferences` or an attached `technical-preferences`
 2. For each category, present 2-3 viable options with pros/cons
 3. Make a clear recommendation based on project needs
 4. Get explicit user approval for each selection
@@ -341,18 +341,21 @@ Use YAML format for better readability. If no REST API, skip this section.]]
 
 ^^CONDITION: has_rest_api^^
 
-```yaml
+````yaml
 openapi: 3.0.0
 info:
-  title: { { api_title } }
-  version: { { api_version } }
-  description: { { api_description } }
-
+  title:
+    '[object Object]': null
+  version:
+    '[object Object]': null
+  description:
+    '[object Object]': null
 servers:
-  - url: { { api_base_url } }
-    description: { { environment } }
-# ... OpenAPI specification continues
-```
+  - url:
+      '[object Object]': null
+    description:
+      '[object Object]': null
+```text
 
 ^^/CONDITION: has_rest_api^^
 
@@ -415,7 +418,7 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```
+````
 
 @{example: monorepo-structure}
 project-root/
@@ -463,7 +466,7 @@ Get user input on deployment preferences and CI/CD tool choices.]]
 
 ### Environment Promotion Flow
 
-```
+```text
 {{promotion_flow_diagram}}
 ```
 

package/.bmad-core/templates/fullstack-architecture-tmpl.md

@@ -109,9 +109,9 @@ Document the choice and key services that will be used.]]
 
 Use appropriate diagram type for clarity.]]
 
-```mermaid
+````mermaid
 {{architecture_diagram}}
-```
+```text
 
 ### Architectural Patterns
 
@@ -222,7 +222,7 @@ After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
     model_interface;
   }
 }
-```
+````
 
 **Relationships:**
 
@@ -246,7 +246,7 @@ After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
 
 **TypeScript Interface:**
 
-```typescript
+````typescript
 interface User {
   id: string;
   email: string;
@@ -262,7 +262,7 @@ interface UserProfile {
   bio?: string;
   preferences: Record<string, any>;
 }
-```
+```text
 
 **Relationships:**
 
@@ -286,27 +286,30 @@ Use appropriate format for the chosen API style. If no API (e.g., static site),
 
 ^^CONDITION: has_rest_api^^
 
-```yaml
+```yml
 openapi: 3.0.0
 info:
-  title: { { api_title } }
-  version: { { api_version } }
-  description: { { api_description } }
-
+  title:
+    '[object Object]': null
+  version:
+    '[object Object]': null
+  description:
+    '[object Object]': null
 servers:
-  - url: { { api_base_url } }
-    description: { { environment } }
-# ... OpenAPI specification continues
-```
+  - url:
+      '[object Object]': null
+    description:
+      '[object Object]': null
+````
 
 ^^/CONDITION: has_rest_api^^
 
 ^^CONDITION: has_graphql_api^^
 
-```graphql
+````graphql
 # GraphQL Schema
 {{graphql_schema}}
-```
+```text
 
 ^^/CONDITION: has_graphql_api^^
 
@@ -319,7 +322,7 @@ servers:
     trpc_routers;
   }
 }
-```
+````
 
 ^^/CONDITION: has_trpc_api^^
 
@@ -464,19 +467,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 **Component Organization:**
 
-```
+`````text
 {{component_structure}}
-```
+```text
 
 **Component Template:**
 
-```typescript
+````typescript
 {
   {
     component_template;
   }
 }
-```
+```text
 
 ### State Management Architecture
 
@@ -490,7 +493,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
     state_structure;
   }
 }
-```
+`````
 
 **State Management Patterns:**
 
@@ -503,19 +506,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 **Route Organization:**
 
-```
+`````text
 {{route_structure}}
-```
+```text
 
 **Protected Route Pattern:**
 
-```typescript
+````typescript
 {
   {
     protected_route_example;
   }
 }
-```
+```text
 
 ### Frontend Services Layer
 
@@ -529,17 +532,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
     api_client_setup;
   }
 }
-```
+`````
 
 **Service Example:**
 
-```typescript
+````typescript
 {
   {
     service_example;
   }
 }
-```
+```text
 
 ## Backend Architecture
 
@@ -554,9 +557,11 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 ^^CONDITION: serverless^^
 **Function Organization:**
 
-```
+````
+
 {{function_structure}}
-```
+
+````text
 
 **Function Template:**
 
@@ -566,26 +571,26 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
     function_template;
   }
 }
-```
+````
 
 ^^/CONDITION: serverless^^
 
 ^^CONDITION: traditional_server^^
 **Controller/Route Organization:**
 
-```
+`````text
 {{controller_structure}}
-```
+```text
 
 **Controller Template:**
 
-```typescript
+````typescript
 {
   {
     controller_template;
   }
 }
-```
+```text
 
 ^^/CONDITION: traditional_server^^
 
@@ -597,17 +602,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```sql
 {{database_schema}}
-```
+`````
 
 **Data Access Layer:**
 
-```typescript
+````typescript
 {
   {
     repository_pattern;
   }
 }
-```
+```text
 
 ### Authentication and Authorization
 
@@ -617,17 +622,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{auth_flow_diagram}}
-```
+````
 
 **Middleware/Guards:**
 
-```typescript
+````typescript
 {
   {
     auth_middleware;
   }
 }
-```
+```text
 
 ## Unified Project Structure
 
@@ -687,7 +692,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 ├── package.json                # Root package.json
 ├── {{monorepo_config}}         # Monorepo configuration
 └── README.md
-```
+````
 
 @{example: vercel_structure}
 apps/
@@ -709,19 +714,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 **Prerequisites:**
 
-```bash
+````bash
 {{prerequisites_commands}}
-```
+```text
 
 **Initial Setup:**
 
 ```bash
 {{setup_commands}}
-```
+````
 
 **Development Commands:**
 
-```bash
+````bash
 # Start all services
 {{start_all_command}}
 
@@ -733,7 +738,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 # Run tests
 {{test_commands}}
-```
+```text
 
 ### Environment Configuration
 
@@ -748,7 +753,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 # Shared
 {{shared_env_vars}}
-```
+````
 
 ## Deployment Architecture
 
@@ -771,9 +776,9 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ### CI/CD Pipeline
 
-```yaml
-{ { cicd_pipeline_config } }
-```
+````yaml
+'[object Object]': null
+```text
 
 ### Environments
 
@@ -831,33 +836,42 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ### Testing Pyramid
 
-```
+````
+
         E2E Tests
        /          \
     Integration Tests
-   /                  \
- Frontend Unit    Backend Unit
-```
+
+/ \
+ Frontend Unit Backend Unit
+
+```text
 
 ### Test Organization
 
 **Frontend Tests:**
 
 ```
+
 {{frontend_test_structure}}
-```
+
+````text
 
 **Backend Tests:**
 
-```
+```text
+
 {{backend_test_structure}}
-```
+
+```text
 
 **E2E Tests:**
 
-```
+````
+
 {{e2e_test_structure}}
-```
+
+````text
 
 ### Test Examples
 
@@ -869,17 +883,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
     frontend_test_example;
   }
 }
-```
+````
 
 **Backend API Test:**
 
-```typescript
+````typescript
 {
   {
     backend_test_example;
   }
 }
-```
+```text
 
 **E2E Test:**
 
@@ -889,7 +903,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
     e2e_test_example;
   }
 }
-```
+````
 
 ## Coding Standards
 
@@ -930,9 +944,9 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ### Error Flow
 
-```mermaid
+````mermaid
 {{error_flow_diagram}}
-```
+```text
 
 ### Error Response Format
 
@@ -946,17 +960,17 @@ interface ApiError {
     requestId: string;
   };
 }
-```
+````
 
 ### Frontend Error Handling
 
-```typescript
+````typescript
 {
   {
     frontend_error_handler;
   }
 }
-```
+```text
 
 ### Backend Error Handling
 
@@ -966,7 +980,7 @@ interface ApiError {
     backend_error_handler;
   }
 }
-```
+````
 
 ## Monitoring and Observability
 
@@ -1000,35 +1014,3 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 ## Checklist Results Report
 
 [[LLM: Before running the checklist, offer to output the full architecture document. Once user confirms, execute the `architect-checklist` and populate results here.]]
-
-## Next Steps
-
-[[LLM: Provide specific next steps for implementation.]]
-
-### Implementation Order
-
-1. **Environment Setup**
-
-   - Initialize monorepo structure
-   - Configure development environment
-   - Set up version control
-
-2. **Foundation (Epic 1)**
-
-   - Implement authentication flow
-   - Set up database schema
-   - Create basic API structure
-   - Implement core UI components
-
-3. **Feature Development**
-   - Follow story sequence from PRD
-   - Maintain type safety across stack
-   - Write tests as you go
-
-### Developer Handoff Prompts
-
-**For Scrum Master:**
-"Create stories for {{Project Name}} using the PRD at docs/prd.md and this fullstack architecture at docs/fullstack-architecture.md. Focus on Epic 1 implementation."
-
-**For Developer:**
-"Implement Story 1.1 from docs/stories/epic1/story-1.1.md using the fullstack architecture at docs/fullstack-architecture.md. Follow the coding standards and use the defined tech stack."

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

@@ -88,7 +88,7 @@
 
 [[LLM: Gather technical decisions that will guide the Architect. Steps:
 
-1. Check if `data#technical-preferences` file exists - use it to pre-populate choices
+1. Check if `data#technical-preferences` or an attached `technical-preferences` file exists - use it to pre-populate choices
 2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets
 3. For unknowns, offer guidance based on project goals and MVP scope
 4. Document ALL technical choices with rationale (why this choice fits the project)