Improve developer experience with shared tooling, cleaner docs. (#170)

* docs: add headers and improve formatting for BMAD orchestrator agent documentation ## CHANGES - Add configuration header to cfg file - Improve numbered list formatting consistency - Add proper heading punctuation throughout - Enhance readability with cleaner structure - Standardize markdown formatting conventions * gitignore update * Plaform Engineer role for a robust infrastructure (#135) * Add Platform Engineer role to support a robust and validated infrastructure * Platform Engineer and Architect boundaries, confidence levels, domain expertise * remove duplicate task, leftover artifact * Consistency, workflow, feedback loops between architect and PE * PE customization generalized, updated Architect, consistency check * style: add VSCode integration and standardize document formatting CHANGES - Introduce VSCode recommended extensions and project-specific settings. - Update `.gitignore` to track the `.vscode` directory. - Apply consistent markdown formatting to all checklist documents. - Standardize spacing, list styles, and headers in personas. - Refine formatting and sectioning in task definition files. - Ensure newline termination for all modified text files. - Correct code block specifiers and minor textual content. * docs: remove exclamation from header * fix: spacing at end of line --------- Co-authored-by: Brian Madison <brianmadison@Brians-MacBook-Pro.local> Co-authored-by: Sebastian Ickler <icklers@users.noreply.github.com>
2025-06-05 05:42:07 -07:00
parent cffbb59941
commit fa470c92fd
22 changed files with 217 additions and 108 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,4 @@ build/
 # Environment variables
 .env

-# VSCode settings
-.vscode/
-CLAUDE.md
+CLAUDE.md
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+	"recommendations": [
+		"davidanson.vscode-markdownlint",
+		"streetsidesoftware.code-spell-checker"
+	]
+}
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -0,0 +1,40 @@
+{
+	"cSpell.words": [
+		"agentic",
+		"Axios",
+		"BMAD",
+		"Centricity",
+		"dataclass",
+		"docstrings",
+		"emergently",
+		"explorative",
+		"frontends",
+		"golint",
+		"Goroutines",
+		"HSTS",
+		"httpx",
+		"Immer",
+		"implementability",
+		"Inclusivity",
+		"Luxon",
+		"pasteable",
+		"Pino",
+		"Polyrepo",
+		"Pydantic",
+		"pyproject",
+		"rescope",
+		"roadmaps",
+		"roleplay",
+		"runbooks",
+		"Serilog",
+		"shadcn",
+		"structlog",
+		"Systemization",
+		"taskroot",
+		"Testcontainers",
+		"tmpl",
+		"VARCHAR",
+		"venv",
+		"WCAG"
+	]
+}
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # The BMAD-Method 3.1 (Breakthrough Method of Agile (ai-driven) Development)

-## Do This First, and all will make sense!
+## Do This First, and all will make sense

 There are lots of docs here, but I HIGHLY suggest you just try the Web Agent - it takes just a few minutes to set up in Gemini - and you can use the BMad Agent to explain how this method works, how to set up in the IDE, how to set up in the Web, what should be done in the web or ide (although you can choose your own path also!) - all just by talking to the bmad agent!

--- a/bmad-agent/checklists/architect-checklist.md
+++ b/bmad-agent/checklists/architect-checklist.md
@@ -256,4 +256,4 @@ This checklist serves as a comprehensive framework for the Architect to validate
 - [ ] Validation and error checking approaches are defined
 - [ ] Self-healing mechanisms are incorporated where possible
 - [ ] Testing patterns are clearly defined
- [ ] Debugging guidance is provided 
+- [ ] Debugging guidance is provided
--- a/bmad-agent/checklists/change-checklist.md
+++ b/bmad-agent/checklists/change-checklist.md
@@ -72,7 +72,7 @@

 ## 5. Sprint Change Proposal Components

-_(Ensure all agreed-upon points from previous sections are captured in the proposal)_
+(Ensure all agreed-upon points from previous sections are captured in the proposal)

 - [ ] **Identified Issue Summary:** Clear, concise problem statement.
 - [ ] **Epic Impact Summary:** How epics are affected.
--- a/bmad-agent/checklists/frontend-architecture-checklist.md
+++ b/bmad-agent/checklists/frontend-architecture-checklist.md
@@ -1,6 +1,7 @@
 # Frontend Architecture Document Review Checklist

 ## Purpose
+
 This checklist is for the Design Architect to use after completing the "Frontend Architecture Mode" and populating the `front-end-architecture-tmpl.txt` (or `.md`) document. It ensures all sections are comprehensively covered and meet quality standards before finalization.

 ---
@@ -34,10 +35,12 @@ This checklist is for the Design Architect to use after completing the "Frontend
 ## IV. Component Breakdown & Implementation Details

 ### Component Naming & Organization
+
 - [ ] Are conventions for naming components (e.g., PascalCase) described?
 - [ ] Is the organization of components on the filesystem clearly explained (reiterating from directory structure if needed)?

 ### Template for Component Specification
+
 - [ ] Is the "Template for Component Specification" itself complete and well-defined?
  - [ ] Does it include fields for: Purpose, Source File(s), Visual Reference?
  - [ ] Does it include a table structure for Props (Name, Type, Required, Default, Description)?
@@ -50,6 +53,7 @@ This checklist is for the Design Architect to use after completing the "Frontend
 - [ ] Is there a clear statement that this template should be used for most feature-specific components?

 ### Foundational/Shared Components (if any specified upfront)
+
 - [ ] If any foundational/shared UI components are specified, do they follow the "Template for Component Specification"?
 - [ ] Is the rationale for specifying these components upfront clear?

@@ -146,4 +150,4 @@ This checklist is for the Design Architect to use after completing the "Frontend
 - [ ] Have all placeholders (e.g., `{Project Name}`, `{e.g., ...}`) been filled in or removed where appropriate?
 - [ ] Has the document been reviewed for clarity, consistency, and completeness by the Design Architect?
 - [ ] Are all linked documents (Main Architecture, UI/UX Spec) finalized or stable enough for this document to rely on?
- [ ] Is the document ready to be shared with the development team? 
+- [ ] Is the document ready to be shared with the development team?
--- a/bmad-agent/checklists/pm-checklist.md
+++ b/bmad-agent/checklists/pm-checklist.md
@@ -5,6 +5,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 1. PROBLEM DEFINITION & CONTEXT

 ### 1.1 Problem Statement
+
 - [ ] Clear articulation of the problem being solved
 - [ ] Identification of who experiences the problem
 - [ ] Explanation of why solving this problem matters
@@ -12,6 +13,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Differentiation from existing solutions

 ### 1.2 Business Goals & Success Metrics
+
 - [ ] Specific, measurable business objectives defined
 - [ ] Clear success metrics and KPIs established
 - [ ] Metrics are tied to user and business value
@@ -19,6 +21,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Timeframe for achieving goals specified

 ### 1.3 User Research & Insights
+
 - [ ] Target user personas clearly defined
 - [ ] User needs and pain points documented
 - [ ] User research findings summarized (if available)
@@ -28,6 +31,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 2. MVP SCOPE DEFINITION

 ### 2.1 Core Functionality
+
 - [ ] Essential features clearly distinguished from nice-to-haves
 - [ ] Features directly address defined problem statement
 - [ ] Each Epic ties back to specific user needs
@@ -35,6 +39,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Minimum requirements for success defined

 ### 2.2 Scope Boundaries
+
 - [ ] Clear articulation of what is OUT of scope
 - [ ] Future enhancements section included
 - [ ] Rationale for scope decisions documented
@@ -42,6 +47,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Scope has been reviewed and refined multiple times

 ### 2.3 MVP Validation Approach
+
 - [ ] Method for testing MVP success defined
 - [ ] Initial user feedback mechanisms planned
 - [ ] Criteria for moving beyond MVP specified
@@ -51,6 +57,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 3. USER EXPERIENCE REQUIREMENTS

 ### 3.1 User Journeys & Flows
+
 - [ ] Primary user flows documented
 - [ ] Entry and exit points for each flow identified
 - [ ] Decision points and branches mapped
@@ -58,6 +65,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Edge cases considered

 ### 3.2 Usability Requirements
+
 - [ ] Accessibility considerations documented
 - [ ] Platform/device compatibility specified
 - [ ] Performance expectations from user perspective defined
@@ -65,6 +73,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] User feedback mechanisms identified

 ### 3.3 UI Requirements
+
 - [ ] Information architecture outlined
 - [ ] Critical UI components identified
 - [ ] Visual design guidelines referenced (if applicable)
@@ -74,6 +83,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 4. FUNCTIONAL REQUIREMENTS

 ### 4.1 Feature Completeness
+
 - [ ] All required features for MVP documented
 - [ ] Features have clear, user-focused descriptions
 - [ ] Feature priority/criticality indicated
@@ -81,6 +91,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Dependencies between features identified

 ### 4.2 Requirements Quality
+
 - [ ] Requirements are specific and unambiguous
 - [ ] Requirements focus on WHAT not HOW
 - [ ] Requirements use consistent terminology
@@ -88,6 +99,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Technical jargon minimized or explained

 ### 4.3 User Stories & Acceptance Criteria
+
 - [ ] Stories follow consistent format
 - [ ] Acceptance criteria are testable
 - [ ] Stories are sized appropriately (not too large)
@@ -98,6 +110,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 5. NON-FUNCTIONAL REQUIREMENTS

 ### 5.1 Performance Requirements
+
 - [ ] Response time expectations defined
 - [ ] Throughput/capacity requirements specified
 - [ ] Scalability needs documented
@@ -105,6 +118,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Load handling expectations set

 ### 5.2 Security & Compliance
+
 - [ ] Data protection requirements specified
 - [ ] Authentication/authorization needs defined
 - [ ] Compliance requirements documented
@@ -112,6 +126,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Privacy considerations addressed

 ### 5.3 Reliability & Resilience
+
 - [ ] Availability requirements defined
 - [ ] Backup and recovery needs documented
 - [ ] Fault tolerance expectations set
@@ -119,6 +134,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Maintenance and support considerations included

 ### 5.4 Technical Constraints
+
 - [ ] Platform/technology constraints documented
 - [ ] Integration requirements outlined
 - [ ] Third-party service dependencies identified
@@ -128,6 +144,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 6. EPIC & STORY STRUCTURE

 ### 6.1 Epic Definition
+
 - [ ] Epics represent cohesive units of functionality
 - [ ] Epics focus on user/business value delivery
 - [ ] Epic goals clearly articulated
@@ -135,6 +152,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Epic sequence and dependencies identified

 ### 6.2 Story Breakdown
+
 - [ ] Stories are broken down to appropriate size
 - [ ] Stories have clear, independent value
 - [ ] Stories include appropriate acceptance criteria
@@ -142,6 +160,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Stories aligned with epic goals

 ### 6.3 First Epic Completeness
+
 - [ ] First epic includes all necessary setup steps
 - [ ] Project scaffolding and initialization addressed
 - [ ] Core infrastructure setup included
@@ -151,6 +170,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 7. TECHNICAL GUIDANCE

 ### 7.1 Architecture Guidance
+
 - [ ] Initial architecture direction provided
 - [ ] Technical constraints clearly communicated
 - [ ] Integration points identified
@@ -159,6 +179,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Known areas of high complexity or technical risk flagged for architectural deep-dive

 ### 7.2 Technical Decision Framework
+
 - [ ] Decision criteria for technical choices provided
 - [ ] Trade-offs articulated for key decisions
 - [ ] Rationale for selecting primary approach over considered alternatives documented (for key design/feature choices)
@@ -167,6 +188,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Guidance on technical debt approach provided

 ### 7.3 Implementation Considerations
+
 - [ ] Development approach guidance provided
 - [ ] Testing requirements articulated
 - [ ] Deployment expectations set
@@ -176,6 +198,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 8. CROSS-FUNCTIONAL REQUIREMENTS

 ### 8.1 Data Requirements
+
 - [ ] Data entities and relationships identified
 - [ ] Data storage requirements specified
 - [ ] Data quality requirements defined
@@ -184,6 +207,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Schema changes planned iteratively, tied to stories requiring them

 ### 8.2 Integration Requirements
+
 - [ ] External system integrations identified
 - [ ] API requirements documented
 - [ ] Authentication for integrations specified
@@ -191,6 +215,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Integration testing requirements outlined

 ### 8.3 Operational Requirements
+
 - [ ] Deployment frequency expectations set
 - [ ] Environment requirements defined
 - [ ] Monitoring and alerting needs identified
@@ -200,6 +225,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## 9. CLARITY & COMMUNICATION

 ### 9.1 Documentation Quality
+
 - [ ] Documents use clear, consistent language
 - [ ] Documents are well-structured and organized
 - [ ] Technical terms are defined where necessary
@@ -207,6 +233,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 - [ ] Documentation is versioned appropriately

 ### 9.2 Stakeholder Alignment
+
 - [ ] Key stakeholders identified
 - [ ] Stakeholder input incorporated
 - [ ] Potential areas of disagreement addressed
@@ -216,6 +243,7 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 ## PRD & EPIC VALIDATION SUMMARY

 ### Category Statuses
+
 | Category | Status | Critical Issues |
 |----------|--------|----------------|
 | 1. Problem Definition & Context | PASS/FAIL/PARTIAL | |
@@ -229,11 +257,14 @@ This checklist serves as a comprehensive framework to ensure the Product Require
 | 9. Clarity & Communication | PASS/FAIL/PARTIAL | |

 ### Critical Deficiencies
+
 - List all critical issues that must be addressed before handoff to Architect

 ### Recommendations
+
 - Provide specific recommendations for addressing each deficiency

 ### Final Decision
+
 - **READY FOR ARCHITECT**: The PRD and epics are comprehensive, properly structured, and ready for architectural design.
- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies. 
+- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies.
--- a/bmad-agent/checklists/po-master-checklist.md
+++ b/bmad-agent/checklists/po-master-checklist.md
@@ -5,6 +5,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 1. PROJECT SETUP & INITIALIZATION

 ### 1.1 Project Scaffolding
+
 - [ ] Epic 1 includes explicit steps for project creation/initialization
 - [ ] If using a starter template, steps for cloning/setup are included
 - [ ] If building from scratch, all necessary scaffolding steps are defined
@@ -12,6 +13,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 - [ ] Repository setup and initial commit processes are defined (if applicable)

 ### 1.2 Development Environment
+
 - [ ] Local development environment setup is clearly defined
 - [ ] Required tools and versions are specified (Node.js, Python, etc.)
 - [ ] Steps for installing dependencies are included
@@ -19,6 +21,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 - [ ] Development server setup is included

 ### 1.3 Core Dependencies
+
 - [ ] All critical packages/libraries are installed early in the process
 - [ ] Package management (npm, pip, etc.) is properly addressed
 - [ ] Version specifications are appropriately defined
@@ -27,6 +30,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 2. INFRASTRUCTURE & DEPLOYMENT SEQUENCING

 ### 2.1 Database & Data Store Setup
+
 - [ ] Database selection/setup occurs before any database operations
 - [ ] Schema definitions are created before data operations
 - [ ] Migration strategies are defined if applicable
@@ -34,12 +38,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 - [ ] Database access patterns and security are established early

 ### 2.2 API & Service Configuration
+
 - [ ] API frameworks are set up before implementing endpoints
 - [ ] Service architecture is established before implementing services
 - [ ] Authentication framework is set up before protected routes
 - [ ] Middleware and common utilities are created before use

 ### 2.3 Deployment Pipeline
+
 - [ ] CI/CD pipeline is established before any deployment actions
 - [ ] Infrastructure as Code (IaC) is set up before use
 - [ ] Environment configurations (dev, staging, prod) are defined early
@@ -47,6 +53,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 - [ ] Rollback procedures or considerations are addressed

 ### 2.4 Testing Infrastructure
+
 - [ ] Testing frameworks are installed before writing tests
 - [ ] Test environment setup precedes test implementation
 - [ ] Mock services or data are defined before testing
@@ -55,18 +62,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 3. EXTERNAL DEPENDENCIES & INTEGRATIONS

 ### 3.1 Third-Party Services
+
 - [ ] Account creation steps are identified for required services
 - [ ] API key acquisition processes are defined
 - [ ] Steps for securely storing credentials are included
 - [ ] Fallback or offline development options are considered

 ### 3.2 External APIs
+
 - [ ] Integration points with external APIs are clearly identified
 - [ ] Authentication with external services is properly sequenced
 - [ ] API limits or constraints are acknowledged
 - [ ] Backup strategies for API failures are considered

 ### 3.3 Infrastructure Services
+
 - [ ] Cloud resource provisioning is properly sequenced
 - [ ] DNS or domain registration needs are identified
 - [ ] Email or messaging service setup is included if needed
@@ -75,12 +85,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 4. USER/AGENT RESPONSIBILITY DELINEATION

 ### 4.1 User Actions
+
 - [ ] User responsibilities are limited to only what requires human intervention
 - [ ] Account creation on external services is properly assigned to users
 - [ ] Purchasing or payment actions are correctly assigned to users
 - [ ] Credential provision is appropriately assigned to users

 ### 4.2 Developer Agent Actions
+
 - [ ] All code-related tasks are assigned to developer agents
 - [ ] Automated processes are correctly identified as agent responsibilities
 - [ ] Configuration management is properly assigned
@@ -89,18 +101,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 5. FEATURE SEQUENCING & DEPENDENCIES

 ### 5.1 Functional Dependencies
+
 - [ ] Features that depend on other features are sequenced correctly
 - [ ] Shared components are built before their use
 - [ ] User flows follow a logical progression
 - [ ] Authentication features precede protected routes/features

 ### 5.2 Technical Dependencies
+
 - [ ] Lower-level services are built before higher-level ones
 - [ ] Libraries and utilities are created before their use
 - [ ] Data models are defined before operations on them
 - [ ] API endpoints are defined before client consumption

 ### 5.3 Cross-Epic Dependencies
+
 - [ ] Later epics build upon functionality from earlier epics
 - [ ] No epic requires functionality from later epics
 - [ ] Infrastructure established in early epics is utilized consistently
@@ -109,18 +124,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 6. MVP SCOPE ALIGNMENT

 ### 6.1 PRD Goals Alignment
+
 - [ ] All core goals defined in the PRD are addressed in epics/stories
 - [ ] Features directly support the defined MVP goals
 - [ ] No extraneous features beyond MVP scope are included
 - [ ] Critical features are prioritized appropriately

 ### 6.2 User Journey Completeness
+
 - [ ] All critical user journeys are fully implemented
 - [ ] Edge cases and error scenarios are addressed
 - [ ] User experience considerations are included
 - [ ] Accessibility requirements are incorporated if specified

 ### 6.3 Technical Requirements Satisfaction
+
 - [ ] All technical constraints from the PRD are addressed
 - [ ] Non-functional requirements are incorporated
 - [ ] Architecture decisions align with specified constraints
@@ -129,18 +147,21 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 7. RISK MANAGEMENT & PRACTICALITY

 ### 7.1 Technical Risk Mitigation
+
 - [ ] Complex or unfamiliar technologies have appropriate learning/prototyping stories
 - [ ] High-risk components have explicit validation steps
 - [ ] Fallback strategies exist for risky integrations
 - [ ] Performance concerns have explicit testing/validation

 ### 7.2 External Dependency Risks
+
 - [ ] Risks with third-party services are acknowledged and mitigated
 - [ ] API limits or constraints are addressed
 - [ ] Backup strategies exist for critical external services
 - [ ] Cost implications of external services are considered

 ### 7.3 Timeline Practicality
+
 - [ ] Story complexity and sequencing suggest a realistic timeline
 - [ ] Dependencies on external factors are minimized or managed
 - [ ] Parallel work is enabled where possible
@@ -149,12 +170,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 8. DOCUMENTATION & HANDOFF

 ### 8.1 Developer Documentation
+
 - [ ] API documentation is created alongside implementation
 - [ ] Setup instructions are comprehensive
 - [ ] Architecture decisions are documented
 - [ ] Patterns and conventions are documented

 ### 8.2 User Documentation
+
 - [ ] User guides or help documentation is included if required
 - [ ] Error messages and user feedback are considered
 - [ ] Onboarding flows are fully specified
@@ -163,12 +186,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## 9. POST-MVP CONSIDERATIONS

 ### 9.1 Future Enhancements
+
 - [ ] Clear separation between MVP and future features
 - [ ] Architecture supports planned future enhancements
 - [ ] Technical debt considerations are documented
 - [ ] Extensibility points are identified

 ### 9.2 Feedback Mechanisms
+
 - [ ] Analytics or usage tracking is included if required
 - [ ] User feedback collection is considered
 - [ ] Monitoring and alerting are addressed
@@ -177,6 +202,7 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 ## VALIDATION SUMMARY

 ### Category Statuses
+
 | Category | Status | Critical Issues |
 |----------|--------|----------------|
 | 1. Project Setup & Initialization | PASS/FAIL/PARTIAL | |
@@ -190,11 +216,14 @@ This checklist serves as a comprehensive framework for the Product Owner to vali
 | 9. Post-MVP Considerations | PASS/FAIL/PARTIAL | |

 ### Critical Deficiencies
+
 - List all critical issues that must be addressed before approval

 ### Recommendations
+
 - Provide specific recommendations for addressing each deficiency

 ### Final Decision
+
 - **APPROVED**: The plan is comprehensive, properly sequenced, and ready for implementation.
- **REJECTED**: The plan requires revision to address the identified deficiencies. 
+- **REJECTED**: The plan requires revision to address the identified deficiencies.
--- a/bmad-agent/checklists/story-dod-checklist.md
+++ b/bmad-agent/checklists/story-dod-checklist.md
@@ -1,17 +1,17 @@
 # Story Definition of Done (DoD) Checklist

-## Instructions for Developer Agent:
+## Instructions for Developer Agent

 Before marking a story as 'Review', please go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary.

-## Checklist Items:
+## Checklist Items

-1.  **Requirements Met:**
+1. **Requirements Met:**

    - [ ] All functional requirements specified in the story are implemented.
    - [ ] All acceptance criteria defined in the story are met.

-2.  **Coding Standards & Project Structure:**
+2. **Coding Standards & Project Structure:**

    - [ ] All new/modified code strictly adheres to `Operational Guidelines`.
    - [ ] All new/modified code aligns with `Project Structure` (file locations, naming, etc.).
@@ -21,23 +21,23 @@ Before marking a story as 'Review', please go through each item in this checklis
    - [ ] No new linter errors or warnings introduced.
    - [ ] Code is well-commented where necessary (clarifying complex logic, not obvious statements).

-3.  **Testing:**
+3. **Testing:**

    - [ ] All required unit tests as per the story and `Operational Guidelines` Testing Strategy are implemented.
    - [ ] All required integration tests (if applicable) as per the story and `Operational Guidelines` Testing Strategy are implemented.
    - [ ] All tests (unit, integration, E2E if applicable) pass successfully.
    - [ ] Test coverage meets project standards (if defined).

-4.  **Functionality & Verification:**
+4. **Functionality & Verification:**

    - [ ] Functionality has been manually verified by the developer (e.g., running the app locally, checking UI, testing API endpoints).
    - [ ] Edge cases and potential error conditions considered and handled gracefully.

-5.  **Story Administration:**
+5. **Story Administration:**
    - [ ] All tasks within the story file are marked as complete.
    - [ ] Any clarifications or decisions made during development are documented in the story file or linked appropriately.
    - [ ] The story wrap up section has been completed with notes of changes or information relevant to the next story or overall project, the agent model that was primarily used during development, and the changelog of any changes is properly updated.
-6.  **Dependencies, Build & Configuration:**
+6. **Dependencies, Build & Configuration:**

    - [ ] Project builds successfully without errors.
    - [ ] Project linting passes
@@ -46,11 +46,11 @@ Before marking a story as 'Review', please go through each item in this checklis
    - [ ] No known security vulnerabilities introduced by newly added and approved dependencies.
    - [ ] If new environment variables or configurations were introduced by the story, they are documented and handled securely.

-7.  **Documentation (If Applicable):**
+7. **Documentation (If Applicable):**
    - [ ] Relevant inline code documentation (e.g., JSDoc, TSDoc, Python docstrings) for new public APIs or complex logic is complete.
    - [ ] User-facing documentation updated, if changes impact users.
    - [ ] Technical documentation (e.g., READMEs, system diagrams) updated if significant architectural changes were made.

-## Final Confirmation:
+## Final Confirmation

 - [ ] I, the Developer Agent, confirm that all applicable items above have been addressed.
--- a/bmad-agent/personas/analyst.md
+++ b/bmad-agent/personas/analyst.md
@@ -67,19 +67,19 @@ This phase focuses on collaboratively crafting a comprehensive and effective pro

 Choose this phase with the Analyst when you need to prepare for in-depth research by meticulously defining the research questions, scope, objectives, and desired output format for a dedicated research agent or for your own research activities.

-### Instructions
+### Deep Research Instructions

 <critical*rule>Note on Subsequent Deep Research Execution:</critical_rule>
 The output of this phase is a research prompt. The actual execution of the deep research based on this prompt may require a dedicated deep research model/function or a different agent/tool. This agent helps you prepare the \_best possible prompt* for that execution.

-1.  **Understand Research Context & Objectives:**
+1. **Understand Research Context & Objectives:**
    - Review any available context from previous phases (e.g., Brainstorming outputs, user's initial problem statement).
    - Ask clarifying questions to deeply understand:
      - The primary goals for conducting the deep research.
      - The specific decisions the research findings will inform.
      - Any existing knowledge, assumptions, or hypotheses to be tested or explored.
      - The desired depth and breadth of the research.
-2.  **Collaboratively Develop the Research Prompt Structure:**
+2. **Collaboratively Develop the Research Prompt Structure:**
    - **Define Overall Research Objective(s):** Work with the user to draft a clear, concise statement of what the deep research aims to achieve.
    - **Identify Key Research Areas/Themes:** Break down the overall objective into logical sub-topics or themes for investigation (e.g., market sizing, competitor capabilities, technology viability, user segment analysis).
    - **Formulate Specific Research Questions:** For each key area/theme, collaboratively generate a list of specific, actionable questions the research should answer. Ensure questions cover:
@@ -87,23 +87,23 @@ The output of this phase is a research prompt. The actual execution of the deep
      - Analytical insights required (e.g., SWOT analysis, trend implications, feasibility assessments).
      - Validation of specific hypotheses.
    - **Define Target Information Sources (if known/preferred):** Discuss if there are preferred types of sources (e.g., industry reports, academic papers, patent databases, user forums, specific company websites).
-    - **Specify Desired Output Format for Research Findings:** Determine how the findings from the _executed research_ (by the other agent/tool) should ideally be structured for maximum usability (e.g., comparative tables, detailed summaries per question, pros/cons lists, SWOT analysis format). This will inform the prompt.
+    - **Specify Desired Output Format for Research Findings:** Determine how the findings from the *executed research* (by the other agent/tool) should ideally be structured for maximum usability (e.g., comparative tables, detailed summaries per question, pros/cons lists, SWOT analysis format). This will inform the prompt.
    - **Identify Evaluation Criteria (if applicable):** If the research involves comparing options (e.g., technologies, solutions), define the criteria for evaluation (e.g., cost, performance, scalability, ease of integration).
-3.  **Draft the Comprehensive Research Prompt:**
+3. **Draft the Comprehensive Research Prompt:**
    - Synthesize all the defined elements (objectives, key areas, specific questions, source preferences, output format preferences, evaluation criteria) into a single, well-structured research prompt.
    - The prompt should be detailed enough to guide a separate research agent effectively.
    - Include any necessary context from previous discussions (e.g., key insights from brainstorming, the user's initial brief) within the prompt to ensure the research agent has all relevant background.
-4.  **Review and Refine the Research Prompt:**
+4. **Review and Refine the Research Prompt:**
    - Present the complete draft research prompt to the user for review and approval.
    - Explain the structure and rationale behind different parts of the prompt.
    - Incorporate user feedback to refine the prompt, ensuring it is clear, comprehensive, and accurately reflects the research needs.
-5.  **Finalize and Deliver the Research Prompt:**
+5. **Finalize and Deliver the Research Prompt:**
    - Provide the finalized, ready-to-use research prompt to the user.
    - <important_note>Advise the user that this prompt is now ready to be provided to a dedicated deep research agent or tool for execution. Discuss next steps, such as proceeding to the Project Briefing Phase (potentially after research findings are available) or returning to Brainstorming if the prompt generation revealed new areas for ideation.</important_note>

 ## Project Briefing Phase

-### Instructions
+### Project Briefing Instructions

 - State that you will use the attached `project-brief-tmpl` as the structure
 - Guide through defining each section of the template:
--- a/bmad-agent/personas/bmad.md
+++ b/bmad-agent/personas/bmad.md
@@ -8,25 +8,25 @@

 ## Core BMAD Orchestrator Principles (Always Active)

-1.  **Config-Driven Authority:** All knowledge of available personas, tasks, and resource paths originates from its loaded Configuration. (Reflects Core Orchestrator Principle #1)
-2.  **BMAD Method Adherence:** Uphold and guide users strictly according to the principles, workflows, and best practices of the BMAD Method as defined in the `bmad-kb.md`.
-3.  **Accurate Persona Embodiment:** Faithfully and accurately activate and embody specialized agent personas as requested by the user and defined in the Configuration. When embodied, the specialized persona's principles take precedence.
-4.  **Knowledge Conduit:** Serve as the primary access point to the `bmad-kb.md`, answering general queries about the method, agent roles, processes, and tool locations.
-5.  **Workflow Facilitation:** Guide users through the suggested order of agent engagement and assist in navigating different phases of the BMAD workflow, helping to select the correct specialist agent for a given objective.
-6.  **Neutral Orchestration:** When not embodying a specific persona, maintain a neutral, facilitative stance, focusing on enabling the user's effective interaction with the broader BMAD ecosystem.
-7.  **Clarity in Operation:** Always be explicit about which persona (if any) is currently active and what task is being performed, or if operating as the base Orchestrator. (Reflects Core Orchestrator Principle #5)
-8.  **Guidance on Agent Selection:** Proactively help users choose the most appropriate specialist agent if they are unsure or if their request implies a specific agent's capabilities.
-9.  **Resource Awareness:** Maintain and utilize knowledge of the location and purpose of all key BMAD resources, including personas, tasks, templates, and the knowledge base, resolving paths as per configuration.
+1. **Config-Driven Authority:** All knowledge of available personas, tasks, and resource paths originates from its loaded Configuration. (Reflects Core Orchestrator Principle #1)
+2. **BMAD Method Adherence:** Uphold and guide users strictly according to the principles, workflows, and best practices of the BMAD Method as defined in the `bmad-kb.md`.
+3. **Accurate Persona Embodiment:** Faithfully and accurately activate and embody specialized agent personas as requested by the user and defined in the Configuration. When embodied, the specialized persona's principles take precedence.
+4. **Knowledge Conduit:** Serve as the primary access point to the `bmad-kb.md`, answering general queries about the method, agent roles, processes, and tool locations.
+5. **Workflow Facilitation:** Guide users through the suggested order of agent engagement and assist in navigating different phases of the BMAD workflow, helping to select the correct specialist agent for a given objective.
+6. **Neutral Orchestration:** When not embodying a specific persona, maintain a neutral, facilitative stance, focusing on enabling the user's effective interaction with the broader BMAD ecosystem.
+7. **Clarity in Operation:** Always be explicit about which persona (if any) is currently active and what task is being performed, or if operating as the base Orchestrator. (Reflects Core Orchestrator Principle #5)
+8. **Guidance on Agent Selection:** Proactively help users choose the most appropriate specialist agent if they are unsure or if their request implies a specific agent's capabilities.
+9. **Resource Awareness:** Maintain and utilize knowledge of the location and purpose of all key BMAD resources, including personas, tasks, templates, and the knowledge base, resolving paths as per configuration.
 10. **Adaptive Support & Safety:** Provide support based on the BMAD knowledge. Adhere to safety protocols regarding persona switching, defaulting to new chat recommendations unless explicitly overridden. (Reflects Core Orchestrator Principle #3 & #4)

 ## Critical Start-Up & Operational Workflow (High-Level Persona Awareness)

 _This persona is the embodiment of the orchestrator logic described in the main `ide-bmad-orchestrator-cfg.md` or equivalent web configuration._

-1.  **Initialization:** Operates based on a loaded and parsed configuration file that defines available personas, tasks, and resource paths. If this configuration is missing or unparsable, it cannot function effectively and would guide the user to address this.
-2.  **User Interaction Prompt:**
+1. **Initialization:** Operates based on a loaded and parsed configuration file that defines available personas, tasks, and resource paths. If this configuration is missing or unparsable, it cannot function effectively and would guide the user to address this.
+2. **User Interaction Prompt:**
    - Greets the user and confirms operational readiness (e.g., "BMAD IDE Orchestrator ready. Config loaded.").
    - If the user's initial prompt is unclear or requests options: Lists available specialist personas (Title, Name, Description) and their configured Tasks, prompting: "Which persona shall I become, and what task should it perform?"
-3.  **Persona Activation:** Upon user selection, activates the chosen persona by loading its definition and applying any specified customizations. It then fully embodies the loaded persona, and its own Orchestrator persona becomes dormant until the specialized persona's task is complete or a persona switch is initiated.
-4.  **Task Execution (as Orchestrator):** Can execute general tasks not specific to a specialist persona, such as providing information about the BMAD method itself or listing available personas/tasks.
-5.  **Handling Persona Change Requests:** If a user requests a different persona while one is active, it follows the defined protocol (recommend new chat or require explicit override).
+3. **Persona Activation:** Upon user selection, activates the chosen persona by loading its definition and applying any specified customizations. It then fully embodies the loaded persona, and its own Orchestrator persona becomes dormant until the specialized persona's task is complete or a persona switch is initiated.
+4. **Task Execution (as Orchestrator):** Can execute general tasks not specific to a specialist persona, such as providing information about the BMAD method itself or listing available personas/tasks.
+5. **Handling Persona Change Requests:** If a user requests a different persona while one is active, it follows the defined protocol (recommend new chat or require explicit override).
--- a/bmad-agent/personas/dev.ide.md
+++ b/bmad-agent/personas/dev.ide.md
@@ -26,20 +26,20 @@ MUST review and use:

 ## Core Operational Mandates

-1.  **Story File is Primary Record:** The assigned story file is your sole source of truth, operational log, and memory for this task. All significant actions, statuses, notes, questions, decisions, approvals, and outputs (like DoD reports) MUST be clearly and immediately retained in this file for seamless continuation by any agent instance.
-2.  **Strict Standards Adherence:** All code, tests, and configurations MUST strictly follow `Operational Guidelines` and align with `Project Structure`. Non-negotiable.
-3.  **Dependency Protocol Adherence:** New external dependencies are forbidden unless explicitly user-approved.
+1. **Story File is Primary Record:** The assigned story file is your sole source of truth, operational log, and memory for this task. All significant actions, statuses, notes, questions, decisions, approvals, and outputs (like DoD reports) MUST be clearly and immediately retained in this file for seamless continuation by any agent instance.
+2. **Strict Standards Adherence:** All code, tests, and configurations MUST strictly follow `Operational Guidelines` and align with `Project Structure`. Non-negotiable.
+3. **Dependency Protocol Adherence:** New external dependencies are forbidden unless explicitly user-approved.

 ## Standard Operating Workflow

-1.  **Initialization & Preparation:**
+1. **Initialization & Preparation:**

    - Verify assigned story `Status: Approved` (or similar ready state). If not, HALT; inform user.
    - On confirmation, update story status to `Status: InProgress` in the story file.
    - <critical_rule>Thoroughly review all "Essential Context & Reference Documents". Focus intensely on the assigned story's requirements, ACs, approved dependencies, and tasks detailed within it.</critical_rule>
    - Review `Debug Log` for relevant pending reversions.

-2.  **Implementation & Development:**
+2. **Implementation & Development:**

    - Execute story tasks/subtasks sequentially.
    - **External Dependency Protocol:**
@@ -55,12 +55,12 @@ MUST review and use:
      - If an issue persists after 3-4 debug cycles for the same sub-problem: pause, document issue/steps (ref. Debugging Log)/status in story file, then ask user for guidance.
    - Update task/subtask status in story file as you progress.

-3.  **Testing & Quality Assurance:**
+3. **Testing & Quality Assurance:**

    - Rigorously implement tests (unit, integration, etc.) for new/modified code per story ACs or `Operational Guidelines` (Testing Strategy).
    - Run relevant tests frequently. All required tests MUST pass before DoD checks.

-4.  **Handling Blockers & Clarifications (Non-Dependency):**
+4. **Handling Blockers & Clarifications (Non-Dependency):**

    - If ambiguities or documentation conflicts arise:
      a. First, attempt to resolve by diligently re-referencing all loaded documentation.
@@ -68,7 +68,7 @@ MUST review and use:
      c. Concisely present issue & questions to user for clarification/decision.
      d. Await user clarification/approval. Document resolution in story file before proceeding.

-5.  **Pre-Completion DoD Review & Cleanup:**
+5. **Pre-Completion DoD Review & Cleanup:**

    - Ensure all story tasks & subtasks are marked complete. Verify all tests pass.
    - <critical_rule>Review `Debug Log`. Meticulously revert all temporary changes for this story. Any change proposed as permanent requires user approval & full standards adherence. `Debug Log` must be clean of unaddressed temporary changes for this story.</critical_rule>
@@ -76,13 +76,13 @@ MUST review and use:
    - Address any unmet checklist items.
    - Prepare itemized "Story DoD Checklist Report" in story file. Justify `[N/A]` items. Note DoD check clarifications/interpretations.

-6.  **Final Handoff for User Approval:**
+6. **Final Handoff for User Approval:**
    - <important_note>Final confirmation: Code/tests meet `Operational Guidelines` & all DoD items are verifiably met (incl. approvals for new dependencies and debug code).</important_note>
    - Present "Story DoD Checklist Report" summary to user.
    - <critical_rule>Update story `Status: Review` in story file if DoD, Tasks and Subtasks are complete.</critical_rule>
    - State story is complete & HALT!

-## Commands:
+## Commands

 - `*help` - list these commands
 - `*core-dump` - ensure story tasks and notes are recorded as of now, and then run bmad-agent/tasks/core-dump.md
--- a/bmad-agent/personas/devops-pe.ide.md
+++ b/bmad-agent/personas/devops-pe.ide.md
@@ -64,13 +64,13 @@ MUST review and use:

 When responding to requests, gather essential context first:

-**Environment**: Platform, regions, infrastructure state (greenfield/brownfield), scale requirements  
-**Project**: Team composition, timeline, business drivers, compliance needs  
+**Environment**: Platform, regions, infrastructure state (greenfield/brownfield), scale requirements
+**Project**: Team composition, timeline, business drivers, compliance needs
 **Technical**: Current pain points, integration needs, performance requirements

 For implementation scenarios, summarize key context:

-```
+```plaintext
 [Environment] Multi-cloud, multi-region, brownfield
 [Stack] Microservices, event-driven, containerized
 [Constraints] SOC2 compliance, 3-month timeline
@@ -191,6 +191,7 @@ For complex technical problems, use a structured meta-reasoning approach:
 ## Domain Boundaries with Architecture

 ### Collaboration Protocols
+
 - **Design Review Gates:** Architecture produces technical specifications, DevOps/Platform reviews for implementability
 - **Feasibility Feedback:** DevOps/Platform provides operational constraints during architecture design phase
 - **Implementation Planning:** Joint sessions to translate architectural decisions into operational tasks
--- a/bmad-agent/personas/sm.ide.md
+++ b/bmad-agent/personas/sm.ide.md
@@ -1,6 +1,6 @@
 # Role: Technical Scrum Master (IDE - Story Creator & Validator)

-## File References:
+## File References

 `Create Next Story Task`: `bmad-agent/tasks/create-next-story-task.md`

--- a/bmad-agent/tasks/create-ai-frontend-prompt.md
+++ b/bmad-agent/tasks/create-ai-frontend-prompt.md
@@ -13,12 +13,12 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi

 ## Key Activities & Instructions

-1.  **Confirm Target AI Generation Platform:**
+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:**
+2. **Synthesize Inputs into a Structured Prompt:**

    - **Overall Project Context:**
      - Briefly state the project's purpose (from brief/PRD).
@@ -51,7 +51,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi
    - **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:**
+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.
--- a/bmad-agent/tasks/create-architecture.md
+++ b/bmad-agent/tasks/create-architecture.md
@@ -8,7 +8,7 @@

 ## Instructions

-1.  **Input Analysis & Dialogue Establishment:**
+1. **Input Analysis & Dialogue Establishment:**

    - Ensure you have all necessary inputs: PRD document (specifically checking for the 'Technical Assumptions' and 'Initial Architect Prompt' sections for the decided repository and service architecture), project brief, any deep research reports, and optionally a `technical-preferences.md`. Request any missing critical documents.
    - Thoroughly review all inputs.
@@ -21,7 +21,7 @@
      - Request the user to select their preferred mode (e.g., "Please let me know if you'd prefer A or B.").
      - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.

-2.  **Resolve Ambiguities & Gather Missing Information:**
+2. **Resolve Ambiguities & Gather Missing Information:**

    - If key information is missing or requirements are unclear after initial review, formulate specific, targeted questions.
    - **External API Details:** If the project involves integration with external APIs, especially those that are less common or where you lack high confidence in your training data regarding their specific request/response schemas, and if a "Deep Research" phase was not conducted for these APIs:
@@ -33,7 +33,7 @@
    - Present questions to the user (batched logically if multiple) and await their input.
    - Document all decisions and clarifications received before proceeding.

-3.  **Iterative Technology Selection & Design (Interactive, if not YOLO mode):**
+3. **Iterative Technology Selection & Design (Interactive, if not YOLO mode):**

    - For each major architectural component or decision point (e.g., frontend framework, backend language/framework, database system, cloud provider, key services, communication patterns):
      - If multiple viable options exist based on requirements or research, present 2-3 choices, briefly outlining their pros, cons, and relevance to the project. Consider any preferences stated in `technical-preferences.md` when formulating these options and your recommendation.
@@ -42,7 +42,7 @@
      - Document the confirmed choice and its rationale within the architecture document.
    - **Starter Templates:** If applicable and requested, research and recommend suitable starter templates or assess existing codebases. Explain alignment with project goals and seek user confirmation.

-4.  **Create Technical Artifacts (Incrementally, unless YOLO mode, guided by `architecture-tmpl`):**
+4. **Create Technical Artifacts (Incrementally, unless YOLO mode, guided by `architecture-tmpl`):**

    - For each artifact or section of the main Architecture Document:

@@ -57,7 +57,7 @@
        - [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options)
        - **Seek Approval:** Obtain explicit user approval for the section before moving to the next, or for the entire artifact if drafted holistically (in YOLO mode).

-5.  **Identify Missing Technical Stories / Refine Epics (Interactive):**
+5. **Identify Missing Technical Stories / Refine Epics (Interactive):**

    - Based on the designed architecture, identify any necessary technical stories/tasks that are not yet captured in the PRD or epics (e.g., "Set up CI/CD pipeline for frontend deployment," "Implement authentication module using JWT," "Create base Docker images for backend services," "Configure initial database schema based on data models").
    - Explain the importance of these technical stories for enabling the functional requirements and successful project execution.
@@ -65,7 +65,7 @@
    - Review existing epics/stories from the PRD and suggest technical considerations or acceptance criteria refinements to ensure they are implementable based on the chosen architecture. For example, specifying API endpoints to be called, data formats, or critical library versions.
    - After collaboration, prepare a concise summary detailing all proposed additions, updates, or modifications to epics and user stories. If no changes are identified, explicitly state this.

-6.  **Validate Architecture Against Checklist & Finalize Output:**
+6. **Validate Architecture Against Checklist & Finalize Output:**
    - Once the main architecture document components have been drafted and reviewed with the user, perform a comprehensive review using the `architect-checklist`.
    - Go through each item in the checklist to ensure the architecture document is comprehensive, addresses all key architectural concerns (e.g., security, scalability, maintainability, testability (including confirmation that coding standards and the testing strategy clearly define unit test location and naming conventions), developer experience), and that proposed solutions are robust.
    - For each checklist item, confirm its status (e.g., \[x] Completed, \[ ] N/A, \[!] Needs Attention).
@@ -110,14 +110,14 @@ Present the user with the following list of 'Advanced Reflective, Elicitation &

 {Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.}

-1.  **Critical Self-Review & User Goal Alignment**
-2.  **Generate & Evaluate Alternative Design Solutions**
-3.  **User Journey & Interaction Stress Test (Conceptual)**
-4.  **Deep Dive into Design Assumptions & Constraints**
-5.  **Usability & Accessibility Audit Review & Probing Questions**
-6.  **Collaborative Ideation & UI Feature Brainstorming**
-7.  **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
-8.  **Finalize this Section and Proceed.**
+1. **Critical Self-Review & User Goal Alignment**
+2. **Generate & Evaluate Alternative Design Solutions**
+3. **User Journey & Interaction Stress Test (Conceptual)**
+4. **Deep Dive into Design Assumptions & Constraints**
+5. **Usability & Accessibility Audit Review & Probing Questions**
+6. **Collaborative Ideation & UI Feature Brainstorming**
+7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
+8. **Finalize this Section and Proceed.**

 After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section."

--- a/bmad-agent/tasks/create-deep-research-prompt.md
+++ b/bmad-agent/tasks/create-deep-research-prompt.md
@@ -1,4 +1,4 @@
-## Deep Research Phase
+# Deep Research Phase

 Leveraging advanced analytical capabilities, the Deep Research Phase with the PM is designed to provide targeted, strategic insights crucial for product definition. Unlike the broader exploratory research an Analyst might undertake, the PM utilizes deep research to:

@@ -9,13 +9,13 @@ Leveraging advanced analytical capabilities, the Deep Research Phase with the PM

 Choose this phase with the PM when you need to strategically validate a product direction, fill specific knowledge gaps critical for defining _what_ to build, or ensure a strong, evidence-backed foundation for your PRD, especially if initial Analyst research was not performed or requires deeper, product-focused investigation.

-### Purpose
+## Purpose

 - To gather foundational information, validate concepts, understand market needs, or analyze competitors when a comprehensive Project Brief from an Analyst is unavailable or insufficient.
 - To ensure the PM has a solid, data-informed basis for defining a valuable and viable product before committing to PRD specifics.
 - To de-risk product decisions by grounding them in targeted research, especially if the user is engaging the PM directly without prior Analyst work or if the initial brief lacks necessary depth.

-### Instructions
+## Instructions

 <critical_rule>Note on Deep Research Execution:</critical_rule>
 To perform deep research effectively, please be aware:
@@ -24,7 +24,7 @@ To perform deep research effectively, please be aware:
 - Alternatively, ensure you have activated or switched to a model/environment that has integrated deep research capabilities.
  This agent can guide you in preparing for deep research, but the execution may require one of these steps.

-1.  **Assess Inputs & Identify Gaps:**
+1. **Assess Inputs & Identify Gaps:**
    - Review any existing inputs (user's initial idea, high-level requirements, partial brief from Analyst, etc.).
    - Clearly identify critical knowledge gaps concerning:
      - Target audience (needs, pain points, behaviors, key segments).
@@ -32,24 +32,24 @@ To perform deep research effectively, please be aware:
      - Competitive analysis (key direct/indirect competitors, their offerings, strengths, weaknesses, market positioning, potential differentiators for this product).
      - Problem/Solution validation (evidence supporting the proposed solution's value and fit for the identified problem).
      - High-level technical or resource considerations (potential major roadblocks or dependencies).
-2.  **Formulate Research Plan:**
+2. **Formulate Research Plan:**
    - Define specific, actionable research questions to address the identified gaps.
    - Propose targeted research activities (e.g., focused web searches for market reports, competitor websites, industry analyses, user reviews of similar products, technology trends).
    - <important_note>Confirm this research plan, scope, and key questions with the user before proceeding with research execution.</important_note>
-3.  **Execute Research:**
+3. **Execute Research:**
    - Conduct the planned research activities systematically.
    - Prioritize gathering credible, relevant, and actionable insights that directly inform product definition and strategy.
-4.  **Synthesize & Present Findings:**
+4. **Synthesize & Present Findings:**
    - Organize and summarize key research findings in a clear, concise, and easily digestible manner (e.g., bullet points, brief summaries per research question).
    - Highlight the most critical implications for the product's vision, strategy, target audience, core features, and potential risks.
    - Present these synthesized findings and their implications to the user.
-5.  **Discussing and Utilizing Research Output:**
+5. **Discussing and Utilizing Research Output:**
    - The comprehensive findings/report from this Deep Research phase can be substantial. I am available to discuss these with you, explain any part in detail, and help you understand their implications.
    - **Options for Utilizing These Findings for PRD Generation:**
-      1.  **Full Handoff to New PM Session:** The complete research output can serve as a foundational document if you initiate a _new_ session with a Product Manager (PM) agent who will then execute the 'PRD Generate Task'.
-      2.  **Key Insights Summary for This Session:** I can prepare a concise summary of the most critical findings, tailored to be directly actionable as we (in this current session) transition to potentially invoking the 'PRD Generate Task'.
+      1. **Full Handoff to New PM Session:** The complete research output can serve as a foundational document if you initiate a _new_ session with a Product Manager (PM) agent who will then execute the 'PRD Generate Task'.
+      2. **Key Insights Summary for This Session:** I can prepare a concise summary of the most critical findings, tailored to be directly actionable as we (in this current session) transition to potentially invoking the 'PRD Generate Task'.
    - <critical_rule>Regardless of how you proceed, it is highly recommended that these research findings (either the full output or the key insights summary) are provided as direct input when invoking the 'PRD Generate Task'. This ensures the PRD is built upon a solid, evidence-based foundation.</critical_rule>
-6.  **Confirm Readiness for PRD Generation:**
+6. **Confirm Readiness for PRD Generation:**
    - Discuss with the user whether the gathered information provides a sufficient and confident foundation to proceed to the 'PRD Generate Task'.
    - If significant gaps or uncertainties remain, discuss and decide with the user on further targeted research or if assumptions need to be documented and carried forward.
    - Once confirmed, clearly state that the next step could be to invoke the 'PRD Generate Task' or, if applicable, revisit other phase options.
--- a/bmad-agent/tasks/create-frontend-architecture.md
+++ b/bmad-agent/tasks/create-frontend-architecture.md
@@ -132,14 +132,14 @@ Present the user with the following list of 'Advanced Reflective, Elicitation &

 {Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.}

-1.  **Critical Self-Review & User Goal Alignment**
-2.  **Generate & Evaluate Alternative Design Solutions**
-3.  **User Journey & Interaction Stress Test (Conceptual)**
-4.  **Deep Dive into Design Assumptions & Constraints**
-5.  **Usability & Accessibility Audit Review & Probing Questions**
-6.  **Collaborative Ideation & UI Feature Brainstorming**
-7.  **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
-8.  **Finalize this Section and Proceed.**
+1. **Critical Self-Review & User Goal Alignment**
+2. **Generate & Evaluate Alternative Design Solutions**
+3. **User Journey & Interaction Stress Test (Conceptual)**
+4. **Deep Dive into Design Assumptions & Constraints**
+5. **Usability & Accessibility Audit Review & Probing Questions**
+6. **Collaborative Ideation & UI Feature Brainstorming**
+7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
+8. **Finalize this Section and Proceed.**

 After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section."

--- a/bmad-agent/tasks/create-next-story-task.md
+++ b/bmad-agent/tasks/create-next-story-task.md
@@ -33,7 +33,7 @@ To identify the next logical story based on project progress and epic definition
  - 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]
--- a/bmad-agent/tasks/create-platform-infrastructure.md
+++ b/bmad-agent/tasks/create-platform-infrastructure.md
@@ -2,7 +2,7 @@

 ## Purpose

-To implement a comprehensive platform infrastructure stack based on the Infrastructure Architecture Document, including foundation infrastructure, container orchestration, GitOps workflows, service mesh, and developer experience platforms. This integrated approach ensures all platform components work synergetically to provide a complete, secure, and operationally excellent platform foundation.
+To implement a comprehensive platform infrastructure stack based on the Infrastructure Architecture Document, including foundation infrastructure, container orchestration, GitOps workflows, service mesh, and developer experience platforms. This integrated approach ensures all platform components work synergistically to provide a complete, secure, and operationally excellent platform foundation.

 ## Inputs

--- a/bmad-agent/tasks/create-prd.md
+++ b/bmad-agent/tasks/create-prd.md
@@ -46,11 +46,11 @@ After discussing initial PRD sections (like Problem, Goals, User Personas) and b

    When doing so, first check if a `docs/technical-preferences.md` file exists or has been provided. If it does, inform the user you will consult it to help guide these technical decisions, while still confirming all choices with them. Ask targeted questions such as:

-1.  "What are your preliminary thoughts on the primary programming languages and frameworks for the backend and frontend (if applicable)? (I will cross-reference any preferences you've noted in `technical-preferences`.)"
-2.  "Which database system are you considering? (Checking preferences...)"
-3.  "Are there any specific cloud services, key libraries, or deployment platforms we should plan for at this stage? (Checking preferences...)"
-4.  "How do you envision the high-level folder structure or main modules of the application? Could you describe the key components and their responsibilities? (I'll consider any structural preferences noted.)"
-5.  "Will this be a monorepo or are you thinking of separate repositories for different parts of the application?"
+1. "What are your preliminary thoughts on the primary programming languages and frameworks for the backend and frontend (if applicable)? (I will cross-reference any preferences you've noted in `technical-preferences`.)"
+2. "Which database system are you considering? (Checking preferences...)"
+3. "Are there any specific cloud services, key libraries, or deployment platforms we should plan for at this stage? (Checking preferences...)"
+4. "How do you envision the high-level folder structure or main modules of the application? Could you describe the key components and their responsibilities? (I'll consider any structural preferences noted.)"
+5. "Will this be a monorepo or are you thinking of separate repositories for different parts of the application?"
    This section should be collaboratively filled and updated as needed if subsequent epic/story discussions reveal new requirements or constraints.

 </important_note\>
@@ -113,7 +113,7 @@ Produce the PRD with PM Prompt per the `prd-tmpl` utilizing the following guidan

 - If the product described in this PRD includes a user interface:

-  1.  **Include Design Architect Prompt in PRD:** You will add a dedicated section in the PRD document you are producing, specifically at the location marked `(END Checklist START Design Architect UI/UX Specification Mode Prompt)` (as per the `prd-tmpl` structure). This section will contain a prompt for the **Design Architect** agent.
+  1. **Include Design Architect Prompt in PRD:** You will add a dedicated section in the PRD document you are producing, specifically at the location marked `(END Checklist START Design Architect UI/UX Specification Mode Prompt)` (as per the `prd-tmpl` structure). This section will contain a prompt for the **Design Architect** agent.

      - The prompt should clearly state that the Design Architect is to operate in its **'UI/UX Specification Mode'**.

@@ -138,7 +138,7 @@ Produce the PRD with PM Prompt per the `prd-tmpl` utilizing the following guidan
        Please guide the user through this process to enrich the PRD with detailed UI/UX specifications.
        ```

-  2.  **Recommend User Workflow:** After finalizing this PRD (with the included prompt for the Design Architect), strongly recommend to the user the following sequence:
+  2. **Recommend User Workflow:** After finalizing this PRD (with the included prompt for the Design Architect), strongly recommend to the user the following sequence:
      a. First, engage the **Design Architect** agent (using the prompt you've embedded in the PRD) to operate in **'UI/UX Specification Mode'**. Explain that this step is crucial for detailing the user interface and experience, and the output (e.g., a populated `front-end-spec-tmpl` and potentially updated PRD sections) will be vital.
      b. Second, _after_ the Design Architect has completed its UI/UX specification work, the user should then proceed to engage the **Architect** agent (using the 'Initial Architect Prompt' also contained in this PRD). The PRD, now enriched with UI/UX details, will provide a more complete basis for technical architecture design.

@@ -215,14 +215,14 @@ Present the user with the following list of 'Advanced Reflective, Elicitation &

 {Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.}

-1.  **Critical Self-Review & User Goal Alignment**
-2.  **Generate & Evaluate Alternative Design Solutions**
-3.  **User Journey & Interaction Stress Test (Conceptual)**
-4.  **Deep Dive into Design Assumptions & Constraints**
-5.  **Usability & Accessibility Audit Review & Probing Questions**
-6.  **Collaborative Ideation & UI Feature Brainstorming**
-7.  **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
-8.  **Finalize this Section and Proceed.**
+1. **Critical Self-Review & User Goal Alignment**
+2. **Generate & Evaluate Alternative Design Solutions**
+3. **User Journey & Interaction Stress Test (Conceptual)**
+4. **Deep Dive into Design Assumptions & Constraints**
+5. **Usability & Accessibility Audit Review & Probing Questions**
+6. **Collaborative Ideation & UI Feature Brainstorming**
+7. **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
+8. **Finalize this Section and Proceed.**

 After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section."