docs(bmad-core): update documentation for enhanced workflow and user guide

- Fix typos and improve clarity in user guide
- Add new enhanced development workflow documentation
- Update brownfield workflow with flattened codebase instructions
- Improve consistency in documentation formatting

bmad-core/enhanced-ide-development-workflow.md

@@ -0,0 +1,43 @@
+# Enhanced Development Workflow
+
+This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
+
+## Create new Branch
+
+1. **Start new branch**
+
+## Story Creation (Scrum Master)
+
+1. **Start new chat/conversation**
+2. **Load SM agent**
+3. **Execute**: `*create` (runs create-next-story task)
+4. **Review generated story** in `docs/stories/`
+5. **Update status**: Change from "Draft" to "Approved"
+
+## Story Implementation (Developer)
+
+1. **Start new chat/conversation**
+2. **Load Dev agent**
+3. **Execute**: `*develop-story {selected-story}` (runs execute-checklist task)
+4. **Review generated report** in `{selected-story}`
+
+## Story Review (Quality Assurance)
+
+1. **Start new chat/conversation**
+2. **Load QA agent**
+3. **Execute**: `*review {selected-story}` (runs review-story task)
+4. **Review generated report** in `{selected-story}`
+
+## Commit Changes and Push
+
+1. **Commit changes**
+2. **Push to remote**
+
+## Repeat Until Complete
+
+- **SM**: Create next story → Review → Approve
+- **Dev**: Implement story → Complete → Mark Ready for Review
+- **QA**: Review story → Mark done
+- **Commit**: All changes
+- **Push**: To remote
+- **Continue**: Until all features implemented

bmad-core/user-guide.md

@@ -1,12 +1,12 @@
 # BMad-Method BMAd Code User Guide
 
-This guide will help you understand and effectively use the BMad Method for agile ai driven planning and development.
+This guide will help you understand and effectively use the BMad Method for agile AI driven planning and development.
 
 ## The BMad Plan and Execute Workflow
 
-First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but its suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
+First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but it's suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
 
-If you are going to use the BMad Method with a Brownfield project (an existing project), review [Working in the Brownfield](./working-in-the-brownfield.md)
+If you are going to use the BMad Method with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
 
 If you do not see the diagrams that following rendering, you can install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugin's, if you right click on the tab when open, there should be a Open Preview option, or check the IDE documentation.
 
@@ -132,7 +132,7 @@ graph TD
 If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
 
 1. Navigate to `dist/teams/`
-2. Copy `team-fullstack.txt` content
+2. Copy `team-fullstack.txt`
 3. Create new Gemini Gem or CustomGPT
 4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
 5. Type `/help` to see available commands
@@ -152,7 +152,7 @@ There are two bmad agents - in the future they will be consolidated into the sin
 
 This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when in the web by accessing the knowledge base and explaining anything to you about the process.
 
-If you dont want to bother switching between different agents aside from the dev, this is the agent for you.
+If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
 
 ### BMad-Orchestrator
 
@@ -210,6 +210,7 @@ dependencies:
 - **Agent Selection**: Use appropriate agent for task
 - **Iterative Development**: Work in small, focused tasks
 - **File Organization**: Maintain clean project structure
+- **Commit Regularly**: Save your work frequently
 
 ## Technical Preferences System
 
@@ -236,7 +237,7 @@ devLoadAlwaysFiles:
 
 You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into it's context. These are the rules the agent will follow.
 
-As your project grows and the code starts to build consistent patterns, coding standards should be reduced to just the items that the agent makes mistakes at still - must with the better models, they will look at surrounding code in files and not need a rule from that file to guide them.
+As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards that the agent still makes with. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
 
 ## Getting Help
 

bmad-core/working-in-the-brownfield.md

@@ -2,10 +2,10 @@
 
 > **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
 >
-> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase or critical sections of it all at once (obviously within reason):
+> Gemini Web's 1M+ token context window or Gemini CLI (when it's working) can analyze your ENTIRE codebase, or critical sections of it, all at once (obviously within reason):
 >
 > - Upload via GitHub URL or use gemini cli in the project folder
-> - If in the web: Upload up to 1000 files or the zipped project or just give it the github url
+> - If working in the web: use the flattener-tool to flatten your project into a single file, then upload that file to your web agent.
 
 ## What is Brownfield Development?
 
@@ -22,10 +22,13 @@ Brownfield development refers to adding features, fixing bugs, or modernizing ex
 
 ## When NOT to use a Brownfield Flow
 
-If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask him to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
+If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask it to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
 
 ## The Complete Brownfield Workflow
 
+1. **Follow the [<ins>User Guide - Installation</ins>](user-guide.md#installation) steps to setup your agent in the web.**
+2. **Generate a 'flattened' single file of your entire codebase** run: ```npm run flatten```
+
 ### Choose Your Approach
 
 #### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
@@ -48,7 +51,7 @@ If you have just completed an MVP with BMad, and you want to continue with post-
 
 #### Phase 1: Define Requirements First
 
-**In Gemini Web (with your codebase uploaded):**
+**In Gemini Web (with your flattened-codebase.xml uploaded):**
 
 ```bash
 @pm
@@ -104,8 +107,7 @@ For example, if you say "Add payment processing to user service":
 1. **Go to Gemini Web** (gemini.google.com)
 2. **Upload your project**:
    - **Option A**: Paste your GitHub repository URL directly
-   - **Option B**: Upload up to 1000 files from your src/project folder
-   - **Option C**: Zip your project and upload the archive
+   - **Option B**: Upload your flattened-codebase.xml file
 3. **Load the analyst agent**: Upload `dist/agents/analyst.txt`
 4. **Run documentation**: Type `*document-project`
 
@@ -113,7 +115,7 @@ The analyst will generate comprehensive documentation of everything.
 
 #### Phase 2: Plan Your Enhancement
 
-#### Option A: Full Brownfield Workflow (Recommended for Major Changes)
+##### Option A: Full Brownfield Workflow (Recommended for Major Changes)
 
 **1. Create Brownfield PRD**:
 
@@ -157,7 +159,7 @@ The architect will:
 - **Identify technical risks**
 - **Define compatibility requirements**
 
-#### Option B: Quick Enhancement (For Focused Changes)
+##### Option B: Quick Enhancement (For Focused Changes)
 
 **For Single Epic Without Full PRD**:
 
@@ -203,24 +205,7 @@ The PO ensures:
 
 ### Phase 4: Transition to Development
 
-Follow the enhanced IDE Development Workflow:
-
-1. **Ensure documents are in project**:
-
-   - Copy `docs/prd.md` (or brownfield-prd.md)
-   - Copy `docs/architecture.md` (or brownfield-architecture.md)
-
-2. **Shard documents**:
-
-   ```bash
-   @po
-   # Ask to shard docs/prd.md
-   ```
-
-3. **Development cycle**:
-   - **SM** creates stories with integration awareness
-   - **Dev** implements with existing code respect
-   - **QA** reviews for compatibility and improvements
+**Follow the [<ins>Enhanced IDE Development Workflow</ins>](enhanced-ide-development-workflow.md)**
 
 ## Brownfield Best Practices