refactor: standardize formatting and improve readability across core documents (#211)

### CHANGES - Add newlines and spacing for improved readability - Standardize instructional text for consistency - Renumber lists within tasks for better clarity - Add language identifiers to various code blocks - Update placeholder text for improved consistency - Adjust descriptions and wording in multiple files - Update VS Code settings and dictionary words
2025-06-14 06:33:59 -07:00
parent 726c3d35b6
commit 009c77f0f5
35 changed files with 515 additions and 349 deletions
--- a/.bmad-core/tasks/brainstorming-techniques.md
+++ b/.bmad-core/tasks/brainstorming-techniques.md
@@ -53,17 +53,17 @@ This task provides a comprehensive toolkit of creative brainstorming techniques

 #### Structured Ideation Frameworks

-5. **SCAMPER Method**
+1. **SCAMPER Method**
   [[LLM: Guide through each SCAMPER prompt systematically.]]
-   - **S**ubstitute: What can be substituted?
-   - **C**ombine: What can be combined or integrated?
-   - **A**dapt: What can be adapted from elsewhere?
-   - **M**odify/Magnify: What can be emphasized or reduced?
-   - **P**ut to other uses: What else could this be used for?
-   - **E**liminate: What can be removed or simplified?
-   - **R**everse/Rearrange: What can be reversed or reordered?
+   - **S** = Substitute: What can be substituted?
+   - **C** = Combine: What can be combined or integrated?
+   - **A** = Adapt: What can be adapted from elsewhere?
+   - **M** = Modify/Magnify: What can be emphasized or reduced?
+   - **P** = Put to other uses: What else could this be used for?
+   - **E** = Eliminate: What can be removed or simplified?
+   - **R**= Reverse/Rearrange: What can be reversed or reordered?

-6. **Six Thinking Hats**
+2. **Six Thinking Hats**
   [[LLM: Cycle through different thinking modes, spending focused time in each.]]
   - White Hat: Facts and information
   - Red Hat: Emotions and intuition
@@ -72,9 +72,10 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
   - Green Hat: Creativity and alternatives
   - Blue Hat: Process and control

-7. **Mind Mapping**
+3. **Mind Mapping**
   [[LLM: Create text-based mind maps with clear hierarchical structure.]]
-   ```
+
+   ```plaintext
   Central Concept
   ├── Branch 1
   │   ├── Sub-idea 1.1
@@ -88,21 +89,21 @@ This task provides a comprehensive toolkit of creative brainstorming techniques

 #### Collaborative Techniques

-8. **"Yes, And..." Building**
+1. **"Yes, And..." Building**
   [[LLM: Accept every idea and build upon it without judgment. Encourage wild ideas and defer criticism.]]
   - Accept the premise of each idea
   - Add to it with "Yes, and..."
   - Build chains of connected ideas
   - Explore tangents freely

-9. **Brainwriting/Round Robin**
+2. **Brainwriting/Round Robin**
   [[LLM: Simulate multiple perspectives by generating ideas from different viewpoints.]]
   - Generate ideas from stakeholder perspectives
   - Build on previous ideas in rounds
   - Combine unrelated ideas
   - Cross-pollinate concepts

-10. **Random Stimulation**
+3. **Random Stimulation**
    [[LLM: Use random words, images, or concepts as creative triggers.]]
    - Random word association
    - Picture/metaphor inspiration
@@ -111,21 +112,21 @@ This task provides a comprehensive toolkit of creative brainstorming techniques

 #### Deep Exploration Techniques

-11. **Five Whys**
+1. **Five Whys**
    [[LLM: Dig deeper into root causes and underlying motivations.]]
    - Why does this problem exist? → Answer → Why? (repeat 5 times)
    - Uncover hidden assumptions
    - Find root causes, not symptoms
    - Identify intervention points

-12. **Morphological Analysis**
+2. **Morphological Analysis**
    [[LLM: Break down into parameters and systematically explore combinations.]]
    - List key parameters/dimensions
    - Identify possible values for each
    - Create combination matrix
    - Explore unusual combinations

-13. **Provocation Technique (PO)**
+3. **Provocation Technique (PO)**
    [[LLM: Make deliberately provocative statements to jar thinking.]]
    - PO: Cars have square wheels
    - PO: Customers pay us to take products
@@ -137,26 +138,31 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Help user select appropriate techniques based on their needs.]]

 **For Initial Exploration:**
+
 - What If Scenarios
 - First Principles
 - Mind Mapping

 **For Stuck/Blocked Thinking:**
+
 - Random Stimulation
 - Reversal/Inversion
 - Provocation Technique

 **For Systematic Coverage:**
+
 - SCAMPER
 - Morphological Analysis
 - Six Thinking Hats

 **For Deep Understanding:**
+
 - Five Whys
 - Analogical Thinking
 - First Principles

 **For Team/Collaborative Settings:**
+
 - Brainwriting
 - "Yes, And..."
 - Six Thinking Hats
@@ -190,17 +196,20 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Present brainstorming results in an organized, actionable format.]]

 **Session Summary:**
+
 - Techniques used
 - Number of ideas generated
 - Key themes identified

 **Idea Categories:**
+
 1. **Immediate Opportunities** - Ideas that could be implemented now
 2. **Future Innovations** - Ideas requiring more development
 3. **Moonshots** - Ambitious, transformative ideas
 4. **Insights & Learnings** - Key realizations from the session

 **Next Steps:**
+
 - Which ideas to explore further
 - Recommended follow-up techniques
 - Suggested research areas
@@ -213,4 +222,4 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 - Build on ideas collaboratively
 - Document everything - even "silly" ideas can spark breakthroughs
 - Take breaks if energy flags
- End with clear next actions
+- End with clear next actions
--- a/.bmad-core/tasks/brownfield-create-story.md
+++ b/.bmad-core/tasks/brownfield-create-story.md
@@ -55,8 +55,8 @@ Create a single focused story following this structure:

 #### User Story

-As a {{user type}},  
-I want {{specific action/capability}},  
+As a {{user type}},
+I want {{specific action/capability}},
 So that {{clear benefit/value}}.

 #### Story Context
--- a/.bmad-core/tasks/create-deep-research-prompt.md
+++ b/.bmad-core/tasks/create-deep-research-prompt.md
@@ -187,7 +187,7 @@ Present these numbered options to the user:

 **Research Prompt Template:**

-```
+```markdown
 ## Research Objective
 [Clear statement of what this research aims to achieve]

--- a/.bmad-core/tasks/create-expansion-pack.md
+++ b/.bmad-core/tasks/create-expansion-pack.md
@@ -39,7 +39,7 @@ Request from the user:

 #### 1.3 Create Planning Document

-**STOP HERE AND CREATE PLAN FIRST**
+IMPORTANT: STOP HERE AND CREATE PLAN FIRST

 Create `expansion-packs/{pack-name}/plan.md` with:

@@ -85,7 +85,7 @@ Create `expansion-packs/{pack-name}/plan.md` with:
 User approval received: [ ] Yes
 ```

-**Wait for user approval before proceeding to Phase 2**
+Important: Wait for user approval before proceeding to Phase 2

 ### Phase 2: Component Design

@@ -142,7 +142,7 @@ For each checklist:

 ### Phase 3: Implementation

-**Only proceed after plan.md is approved**
+IMPORTANT: Only proceed after plan.md is approved

 #### 3.1 Create Directory Structure

@@ -227,7 +227,7 @@ post_install_message: |

 ### Phase 4: Content Creation

-**Work through plan.md checklist systematically**
+IMPORTANT: Work through plan.md checklist systematically!

 #### 4.1 Create Orchestrator First

@@ -308,12 +308,6 @@ For each required data file:
 - **Example**:
 ```

-{sample content}
-
-```
-
-```
-
 ## Example: Healthcare Expansion Pack

 ```text
@@ -362,38 +356,38 @@ Required user data files:

 ### Planning Phase

-6. "Here's the proposed plan. Please review and approve before we continue."
+1. "Here's the proposed plan. Please review and approve before we continue."

 ### Orchestrator Design

-7. "What key commands should the {pack-name} orchestrator support?"
-8. "What's the typical workflow from start to finish?"
-9. "How should it integrate with core BMAD agents?"
+1. "What key commands should the {pack-name} orchestrator support?"
+2. "What's the typical workflow from start to finish?"
+3. "How should it integrate with core BMAD agents?"

 ### Agent Planning

-10. "For agent '{name}', what is their specific expertise?"
-11. "What tasks will this agent reference? (I'll create them)"
-12. "What templates will this agent use? (I'll create them)"
-13. "What data files will this agent need? (You'll provide these)"
+1. "For agent '{name}', what is their specific expertise?"
+2. "What tasks will this agent reference? (I'll create them)"
+3. "What templates will this agent use? (I'll create them)"
+4. "What data files will this agent need? (You'll provide these)"

 ### Task Design

-14. "Describe the '{task}' process step-by-step"
-15. "What information is needed to complete this task?"
-16. "What should the output look like?"
+1. "Describe the '{task}' process step-by-step"
+2. "What information is needed to complete this task?"
+3. "What should the output look like?"

 ### Template Creation

-17. "What sections should the '{template}' document have?"
-18. "Are there any required formats or standards?"
-19. "Can you provide an example of a completed document?"
+1. "What sections should the '{template}' document have?"
+2. "Are there any required formats or standards?"
+3. "Can you provide an example of a completed document?"

 ### Data Requirements

-20. "For {data-file}, what information should it contain?"
-21. "What format should this data be in?"
-22. "Can you provide a sample?"
+1. "For {data-file}, what information should it contain?"
+2. "What format should this data be in?"
+3. "Can you provide a sample?"

 ## Important Considerations

--- a/.bmad-core/tasks/create-ide-agent.md
+++ b/.bmad-core/tasks/create-ide-agent.md
@@ -77,6 +77,7 @@ Required commands per schema:
 ```

 Add role-specific commands:
+
 - Use pattern: `^\\*[a-z][a-z0-9-]*( \\{[^}]+\\})?$`
 - Include clear descriptions (10+ chars)
 - Reference tasks when appropriate
@@ -98,9 +99,10 @@ Analyze where this IDE agent fits in workflows:
   - For specialized agents → specific workflow steps

 4. **Document recommendations**:
+
   ```markdown
   ## Workflow Integration
-   
+
   This agent enhances the following workflows:
   - `greenfield-service`: API design phase (between architecture and implementation)
   - `brownfield-service`: API refactoring and modernization
@@ -118,9 +120,10 @@ Consider which teams benefit from this IDE agent:
   - Domain experts → relevant specialized teams

 3. **Document integration**:
+
   ```markdown
   ## Team Integration
-   
+
   Recommended teams for this agent:
   - `team-fullstack`: Provides specialized {domain} expertise
   - `team-no-ui`: Enhances backend {capability}
@@ -243,7 +246,7 @@ Recommended teams for this agent:
 - [ ] Persona has all 5 required fields
 - [ ] Minimum 3 Core Principles including Numbered Options Protocol
 - [ ] First startup instruction announces name/role with *help
- [ ] Includes *help and *chat-mode commands
+- [ ] Includes *help and*chat-mode commands
 - [ ] Commands follow pattern requirements
 - [ ] Workflow integration documented
 - [ ] Team integration suggestions provided
@@ -259,4 +262,4 @@ Recommended teams for this agent:
 5. **Integration First**: Consider how agent enhances existing workflows
 6. **Schema Compliance**: Always validate against the schema

-This schema-driven approach ensures IDE agents are consistent, integrated, and valuable additions to the BMAD ecosystem.
+This schema-driven approach ensures IDE agents are consistent, integrated, and valuable additions to the BMAD ecosystem.
--- a/.bmad-core/tasks/create-team.md
+++ b/.bmad-core/tasks/create-team.md
@@ -45,6 +45,7 @@ Based on the schema requirements:
 Based on team purpose, recommend agents:

 **For Planning & Strategy Teams:**
+
 - `bmad` (required orchestrator)
 - `analyst` - Requirements gathering and research
 - `pm` - Product strategy and documentation
@@ -52,6 +53,7 @@ Based on team purpose, recommend agents:
 - `architect` - Technical planning (if technical planning needed)

 **For Design & UX Teams:**
+
 - `bmad` (required orchestrator)
 - `ux-expert` - User experience design
 - `architect` - Frontend architecture
@@ -59,6 +61,7 @@ Based on team purpose, recommend agents:
 - `po` - Design validation

 **For Development Teams:**
+
 - `bmad` (required orchestrator)
 - `sm` - Sprint coordination
 - `dev` - Implementation
@@ -66,6 +69,7 @@ Based on team purpose, recommend agents:
 - `architect` - Technical guidance

 **For Full-Stack Teams:**
+
 - `bmad` (required orchestrator)
 - `analyst` - Initial planning
 - `pm` - Product management
@@ -128,7 +132,7 @@ workflows:
 Before finalizing, verify:

 1. **Role Coverage**: Does the team have all necessary skills for its workflows?
-2. **Size Optimization**: 
+2. **Size Optimization**:
   - Minimum: 2 agents (bmad + 1)
   - Recommended: 3-7 agents
   - Maximum with wildcard: bmad + "*"
@@ -159,8 +163,8 @@ Document how this team integrates with existing system:
 bundle:
  name: "Team API"
  description: >-
-    Specialized team for API and backend service development. Focuses on 
-    robust service architecture, implementation, and testing without UI 
+    Specialized team for API and backend service development. Focuses on
+    robust service architecture, implementation, and testing without UI
    components. Ideal for microservices, REST APIs, and backend systems.

 agents:
@@ -182,8 +186,8 @@ workflows:
 bundle:
  name: "Team Prototype"
  description: >-
-    Agile team for rapid prototyping and proof of concept development. 
-    Combines planning, design, and implementation for quick iterations 
+    Agile team for rapid prototyping and proof of concept development.
+    Combines planning, design, and implementation for quick iterations
    on new ideas and experimental features.

 agents:
@@ -220,4 +224,4 @@ workflows:
 5. **Test Integration**: Verify team works well with selected workflows
 6. **Iterate**: Refine team composition based on usage

-This schema-driven approach ensures teams are well-structured, purposeful, and integrate seamlessly with the BMAD ecosystem.
+This schema-driven approach ensures teams are well-structured, purposeful, and integrate seamlessly with the BMAD ecosystem.
--- a/.bmad-core/tasks/index-docs.md
+++ b/.bmad-core/tasks/index-docs.md
@@ -174,4 +174,4 @@ Please provide:
 4. Any files or directories to exclude from indexing (e.g., `.git`, `node_modules`)
 5. Whether to include hidden files/folders (starting with `.`)

-Would you like to proceed with documentation indexing? Please provide the required input above.
+Would you like to proceed with documentation indexing? Please provide the required input above.