bmad-method 4.6.3 → 4.8.0

package/bmad-core/data/bmad-kb.md

@@ -12,6 +12,60 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
 - **Reusable Resources**: Portable templates, tasks, and checklists
 - **Slash Command Integration**: Quick agent switching and control
 
+### When to Use BMAD
+
+- **New Projects (Greenfield)**: Complete end-to-end development
+- **Existing Projects (Brownfield)**: Feature additions and enhancements
+- **Team Collaboration**: Multiple roles working together
+- **Quality Assurance**: Structured testing and validation
+- **Documentation**: Professional PRDs, architecture docs, user stories
+
+## Getting Started
+
+### Quick Start Options
+
+#### Option 1: Web UI
+**Best for**: ChatGPT, Claude, Gemini users who want to start immediately
+
+1. Navigate to `dist/teams/`
+2. Copy `team-fullstack.txt` content
+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
+
+#### Option 2: IDE Integration
+**Best for**: Cursor, Claude Code, Windsurf, VS Code users
+
+```bash
+# Interactive installation (recommended)
+npx bmad-method install
+```
+
+**Installation Steps**:
+- Choose "Complete installation"
+- Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
+
+**Verify Installation**:
+- `.bmad-core/` folder created with all agents
+- IDE-specific integration files created
+- All agent commands/rules/modes available
+
+### Environment Selection Guide
+
+**Use Web UI for**:
+- Initial planning and documentation (PRD, architecture)
+- Cost-effective document creation (especially with Gemini)
+- Brainstorming and analysis phases
+- Multi-agent consultation and planning
+
+**Use IDE for**:
+- Active development and coding
+- File operations and project integration
+- Document sharding and story management
+- Implementation workflow (SM/Dev cycles)
+
+**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -33,15 +87,342 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 7. **START_SMALL_SCALE_FAST**: Test concepts, then expand.
 8. **EMBRACE_THE_CHAOS**: Adapt and overcome challenges.
 
-## IDE Development Workflow
+### Key Workflow Principles
+
+1. **Agent Specialization**: Each agent has specific expertise and responsibilities
+2. **Clean Handoffs**: Always start fresh when switching between agents
+3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
+4. **Iterative Development**: Complete one story before starting the next
+5. **Documentation First**: Always start with solid PRD and architecture
+
+## Agent System
+
+### Core Development Team
+
+| Agent       | Role               | Primary Functions                       | When to Use                            |
+| ----------- | ------------------ | --------------------------------------- | -------------------------------------- |
+| `analyst`   | Business Analyst   | Market research, requirements gathering | Project planning, competitive analysis |
+| `pm`        | Product Manager    | PRD creation, feature prioritization    | Strategic planning, roadmaps           |
+| `architect` | Solution Architect | System design, technical architecture   | Complex systems, scalability planning  |
+| `dev`       | Developer          | Code implementation, debugging          | All development tasks                  |
+| `qa`        | QA Specialist      | Test planning, quality assurance        | Testing strategies, bug validation     |
+| `ux-expert` | UX Designer        | UI/UX design, prototypes                | User experience, interface design      |
+| `po`        | Product Owner      | Backlog management, story validation    | Story refinement, acceptance criteria  |
+| `sm`        | Scrum Master       | Sprint planning, story creation         | Project management, workflow           |
+
+### Meta Agents
+
+| Agent               | Role             | Primary Functions                     | When to Use                       |
+| ------------------- | ---------------- | ------------------------------------- | --------------------------------- |
+| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching | Complex multi-role tasks          |
+| `bmad-master`       | Universal Expert | All capabilities without switching    | Single-session comprehensive work |
+
+### Agent Interaction Commands
+
+#### IDE-Specific Syntax
+
+**Agent Loading by IDE**:
+- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
+- **Cursor**: `@agent-name` (e.g., `@bmad-master`)
+- **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
+- **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)
+
+**Chat Management Guidelines**:
+- **Claude Code, Cursor, Windsurf**: Start new chats when switching agents
+- **Roo Code**: Switch modes within the same conversation
+
+**Common Task Commands**:
+- `*help` - Show available commands
+- `*status` - Show current context/progress
+- `*exit` - Exit the agent mode
+- `*shard-doc docs/prd.md prd` - Shard PRD into manageable pieces
+- `*shard-doc docs/architecture.md architecture` - Shard architecture document
+- `*create` - Run create-next-story task (SM agent)
+
+**In Web UI**:
+```text
+/pm create-doc prd
+/architect review system design
+/dev implement story 1.2
+/help - Show available commands
+/switch agent-name - Change active agent (if orchestrator available)
+```
+
+## Team Configurations
+
+### Pre-Built Teams
+
+#### Team All
+- **Includes**: All 10 agents + orchestrator
+- **Use Case**: Complete projects requiring all roles
+- **Bundle**: `team-all.txt`
+
+#### Team Fullstack
+- **Includes**: PM, Architect, Developer, QA, UX Expert
+- **Use Case**: End-to-end web/mobile development
+- **Bundle**: `team-fullstack.txt`
+
+#### Team No-UI
+- **Includes**: PM, Architect, Developer, QA (no UX Expert)
+- **Use Case**: Backend services, APIs, system development
+- **Bundle**: `team-no-ui.txt`
+
+## Core Architecture
+
+### System Overview
+
+The BMAD-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
+
+### Key Architectural Components
+
+#### 1. Agents (`bmad-core/agents/`)
+- **Purpose**: Each markdown file defines a specialized AI agent for a specific Agile role (PM, Dev, Architect, etc.)
+- **Structure**: Contains YAML headers specifying the agent's persona, capabilities, and dependencies
+- **Dependencies**: Lists of tasks, templates, checklists, and data files the agent can use
+- **Startup Instructions**: Can load project-specific documentation for immediate context
+
+#### 2. Agent Teams (`bmad-core/agent-teams/`)
+- **Purpose**: Define collections of agents bundled together for specific purposes
+- **Examples**: `team-all.yml` (comprehensive bundle), `team-fullstack.yml` (full-stack development)
+- **Usage**: Creates pre-packaged contexts for web UI environments
+
+#### 3. Workflows (`bmad-core/workflows/`)
+- **Purpose**: YAML files defining prescribed sequences of steps for specific project types
+- **Types**: Greenfield (new projects) and Brownfield (existing projects) for UI, service, and fullstack development
+- **Structure**: Defines agent interactions, artifacts created, and transition conditions
+
+#### 4. Reusable Resources
+- **Templates** (`bmad-core/templates/`): Markdown templates for PRDs, architecture specs, user stories
+- **Tasks** (`bmad-core/tasks/`): Instructions for specific repeatable actions like "shard-doc" or "create-next-story"
+- **Checklists** (`bmad-core/checklists/`): Quality assurance checklists for validation and review
+- **Data** (`bmad-core/data/`): Core knowledge base and technical preferences
+
+### Dual Environment Architecture
+
+#### IDE Environment
+
+- Users interact directly with agent markdown files
+- Agents can access all dependencies dynamically
+- Supports real-time file operations and project integration
+- Optimized for development workflow execution
+
+#### Web UI Environment
+
+- Uses pre-built bundles from `dist/teams` for stand alone 1 upload files for all agents and their assest with an orchestrating agent
+- Single text files containing all agent dependencies are in `dist/agents/` - these are unnecessary unless you want to create a web agent that is only a single agent and not a team
+- Created by the web-builder tool for upload to web interfaces
+- Provides complete context in one package
+
+### Template Processing System
+
+BMAD employs a sophisticated template system with three key components:
+
+1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
+
+**Template Features**:
+
+- **Self-contained**: Templates embed both output structure and processing instructions
+- **Variable Substitution**: `{{placeholders}}` for dynamic content
+- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
+- **Interactive Refinement**: Built-in elicitation processes for quality improvement
+
+### Technical Preferences Integration
+
+The `technical-preferences.md` file serves as a persistent technical profile that:
+- Ensures consistency across all agents and projects
+- Eliminates repetitive technology specification
+- Provides personalized recommendations aligned with user preferences
+- Evolves over time with lessons learned
+
+### Build and Delivery Process
+
+The `web-builder.js` tool creates web-ready bundles by:
+1. Reading agent or team definition files
+2. Recursively resolving all dependencies
+3. Concatenating content into single text files with clear separators
+4. Outputting ready-to-upload bundles for web AI interfaces
+
+This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMAD powerful.
+
+## Complete Development Workflow
+
+### Planning Phase (Web UI Recommended)
+
+**Ideal for cost efficiency, especially with Gemini:**
+
+1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
+2. **Project Brief**: Create foundation document (Analyst or user)
+3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
+4. **Architecture Design**: `/architect create-doc architecture` - Technical foundation
+5. **Validation & Alignment**: `/po` run master checklist to ensure document consistency
+6. **Document Preparation**: Copy final documents to project as `docs/prd.md` and `docs/architecture.md`
+
+#### Example Planning Prompts
+
+**For PRD Creation**:
+```text
+"I want to build a [type] application that [core purpose].
+Help me brainstorm features and create a comprehensive PRD."
+```
+
+**For Architecture Design**:
+```text
+"Based on this PRD, design a scalable technical architecture
+that can handle [specific requirements]."
+```
+
+### Critical Transition: Web UI to IDE
+
+**Once planning is complete, you MUST switch to IDE for development:**
+
+- **Why**: Development workflow requires file operations, real-time project integration, and document sharding
+- **Cost Benefit**: Web UI is more cost-effective for large document creation; IDE is optimized for development tasks
+- **Required Files**: Ensure `docs/prd.md` and `docs/architecture.md` exist in your project
+
+### IDE Development Workflow
+
+**Prerequisites**: Planning documents must exist in `docs/` folder
+
+1. **Document Sharding**: 
+   - `@bmad-master` or `@po` shard `docs/prd.md` to `docs/prd/` folder
+   - If architecture exists, shard to `docs/architecture/` folder
+   - Results in multiple manageable documents and epic files
+
+2. **Verify Sharded Content**:
+   - At least one `epic-n.md` file in `docs/prd/` with stories in development order
+   - Source tree document and coding standards for dev agent reference
+   - Sharded docs for SM agent story creation
+
+**Resulting Folder Structure**:
+- `docs/prd/` - Broken down PRD sections
+- `docs/architecture/` - Broken down architecture sections
+- `docs/stories/` - Generated user stories
+
+3. **Development Cycle** (Sequential, one story at a time):
+
+   **Step 1 - Story Creation**: New chat window → `@sm` → `*create`
+   - SM executes create-next-story task
+   - Review generated story in `docs/stories/`
+   - Update status from "Draft" to "Approved"
+   
+   **Step 2 - Story Implementation**: New chat window → `@dev`
+   - Agent asks which story to implement
+   - Include story file content to save dev agent lookup time
+   - Dev follows tasks/subtasks, marking completion
+   - Dev leaves notes for SM about any deviations
+   - Update status to "Done"
+   
+   **Step 3 - Repeat**: Continue SM → Dev cycle until all epic stories complete
+
+**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
+
+### Status Tracking Workflow
+
+Stories progress through defined statuses:
+- **Draft** → **Approved** → **InProgress** → **Done**
+
+Each status change requires user verification and approval before proceeding.
+
+### Workflow Types
+
+#### Greenfield Development
+- Business analysis and market research
+- Product requirements and feature definition  
+- System architecture and design
+- Development execution
+- Testing and deployment
+
+#### Brownfield Enhancement
+- Current system analysis
+- Enhancement planning
+- Impact assessment
+- Incremental development
+- Integration testing
+
+## Document Creation Best Practices
+
+### Required File Naming for Framework Integration
+
+- `docs/prd.md` - Product Requirements Document
+- `docs/architecture.md` - System Architecture Document
+
+**Why These Names Matter**:
+- Agents automatically reference these files during development
+- Sharding tasks expect these specific filenames
+- Workflow automation depends on standard naming
+
+### Cost-Effective Document Creation Workflow
+
+**Recommended for Large Documents (PRD, Architecture):**
+
+1. **Use Web UI**: Create documents in web interface for cost efficiency
+2. **Copy Final Output**: Save complete markdown to your project
+3. **Standard Names**: Save as `docs/prd.md` and `docs/architecture.md`
+4. **Switch to IDE**: Use IDE agents for development and smaller documents
+
+### Document Sharding
+
+Templates with Level 2 headings (`##`) can be automatically sharded:
+
+**Original PRD**:
+```markdown
+## Goals and Background Context
+## Requirements  
+## User Interface Design Goals
+## Success Metrics
+```
+
+**After Sharding**:
+- `docs/prd/goals-and-background-context.md`
+- `docs/prd/requirements.md`
+- `docs/prd/user-interface-design-goals.md`
+- `docs/prd/success-metrics.md`
+
+Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sharding.
+
+## Usage Patterns and Best Practices
+
+### Environment-Specific Usage
+
+**Web UI Best For**:
+- Initial planning and documentation phases
+- Cost-effective large document creation
+- Agent consultation and brainstorming
+- Multi-agent workflows with orchestrator
+
+**IDE Best For**:
+- Active development and implementation
+- File operations and project integration
+- Story management and development cycles
+- Code review and debugging
+
+### Quality Assurance
+
+- Use appropriate agents for specialized tasks
+- Follow Agile ceremonies and review processes
+- Maintain document consistency with PO agent
+- Regular validation with checklists and templates
+
+### Performance Optimization
+
+- Use specific agents vs. `bmad-master` for focused tasks
+- Choose appropriate team size for project needs
+- Leverage technical preferences for consistency
+- Regular context management and cache clearing
+
+## Success Tips
+
+- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
+- **Use bmad-master for document organization** - Sharding creates manageable chunks
+- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
+- **Keep conversations focused** - One agent, one task per conversation
+- **Review everything** - Always review and approve before marking complete
 
-1. Shard the PRD (And Architecture documents if they exist also based on workflow type) using the Doc Shard task. The BMad-Master agent can help you do this. You will select the task, provide the doc to shard and the output folder. for example: `BMad Master, please Shard the docs/prd.md to the doc/prd/ folder` - this should ask you to use the md-tree-parser which is recommended, but either way shoudl result in multiple documents being created in the folder docs/prd.
-2. If you have fullstack, front end and or back end architecture documents you will want to follow the same thing, but shard all of these to an architecture folder instead of a prd folder.
-3. Ensure that you have at least one epic-n.md file in your prd folder, with the stories in order to develop.
-4. The docs or architecture folder or prd folder should have a source tree document and coding standards at a minimum. These are used by the dev agent, and the many other sharded docs are used by the SM agent.
-5. Use a new chat window to allow the SM agent to `draft the next story`.
-6. If you agree the story is correct, mark it as approved in the status field, and then start a new chat window with the dev agent.
-7. Ask the dev agent to implement the next story. If you draft the story file into the chat it will save time for the dev to have to find what the next one is. The dev should follow the tasks and subtasks marking them off as they are completed. The dev agent will also leave notes potentially for the SM to know about any deviations that might have occured to help draft the next story.
-8. Once complete and you have verified, mark it done, and start a new chat. Ask the SM to draft the next story - repeating the cycle.
+## Getting Help
 
-With this work flow, there is only 1 story in progress at a time, worked sequentially.
+- **Commands**: Use `/help` in any environment to see available commands
+- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Documentation**: Check `docs/` folder for project-specific context
+- **Community**: Discord and GitHub resources available for support

package/bmad-core/tasks/create-next-story.md

@@ -4,45 +4,42 @@
 
 To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research.
 
-## Inputs for this Task
-
-- Access to the project's documentation repository, specifically:
-  - `docs/index.md` (hereafter "Index Doc")
-  - All Epic files - located in one of these locations:
-    - Primary: `docs/prd/epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
-    - Secondary: `docs/epics/epic-{n}-{description}.md`
-    - User-specified location if not found in above paths
-  - Existing story files in `docs/stories/`
-  - Main PRD (hereafter "PRD Doc")
-  - Main Architecture Document (hereafter "Main Arch Doc")
-  - Frontend Architecture Document (hereafter "Frontend Arch Doc," if relevant)
-  - Project Structure Guide (`docs/project-structure.md`)
-  - Operational Guidelines Document (`docs/operational-guidelines.md`)
-  - Technology Stack Document (`docs/tech-stack.md`)
-  - Data Models Document (as referenced in Index Doc)
-  - API Reference Document (as referenced in Index Doc)
-  - UI/UX Specifications, Style Guides, Component Guides (if relevant, as referenced in Index Doc)
-- The `bmad-core/templates/story-tmpl.md` (hereafter "Story Template")
-- The `bmad-core/checklists/story-draft-checklist.md` (hereafter "Story Draft Checklist")
-- User confirmation to proceed with story identification and, if needed, to override warnings about incomplete prerequisite stories.
-
 ## Task Execution Instructions
 
+### 0. Load Core Configuration
+
+[[LLM: CRITICAL - This MUST be your first step]]
+
+- Load `.bmad-core/core-config.yml` from the project root
+- If the file does not exist:
+  - HALT and inform the user: "core-config.yml not found. This file is required for story creation. You can:
+    1. Copy it from GITHUB BMAD-METHOD/bmad-core/core-config.yml and configure it for your project
+    2. Run the BMAD installer against your project to upgrade and add the file automatically
+    Please add and configure core-config.yml before proceeding."
+- Extract the following key configurations:
+  - `dev-story-location`: Where to save story files
+  - `prd.prdSharded`: Whether PRD is sharded or monolithic
+  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `prd.prdShardedLocation`: Location of sharded epic files
+  - `prd.epicFilePattern`: Pattern for epic files (e.g., `epic-{n}*.md`)
+  - `architecture.architectureVersion`: Architecture document version
+  - `architecture.architectureSharded`: Whether architecture is sharded
+  - `architecture.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureShardedLocation`: Location of sharded architecture files
+
 ### 1. Identify Next Story for Preparation
 
 #### 1.1 Locate Epic Files
 
-- First, determine where epic files are located:
-  - Check `docs/prd/` for files matching pattern `epic-{n}-*.md`
-  - If not found, check `docs/epics/` for files matching pattern `epic-{n}-*.md`
-  - If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored."
-- Note: Epic files follow naming convention `epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
+- Based on `prdSharded` from config:
+  - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
+  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
 
 #### 1.2 Review Existing Stories
 
-- Review `docs/stories/` to find the highest-numbered story file.
+- Check `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- If the directory exists and has at least 1 file, find the highest-numbered story file.
 - **If a highest story file exists (`{lastEpicNum}.{lastStoryNum}.story.md`):**
-
   - Verify its `Status` is 'Done' (or equivalent).
   - If not 'Done', present an alert to the user:
 
@@ -60,17 +57,17 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}-*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}-*.md`, then `epic-{lastEpicNum + 2}-*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
+  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
 
 - **If no story files exist in `docs/stories/`:**
   - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
 - If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
-### 2. Gather Core Story Requirements (from Epic File)
+### 2. Gather Core Story Requirements (from Epic)
 
-- For the identified story, open its parent Epic File (e.g., `epic-{epicNum}-*.md` from the location identified in step 1.1).
+- For the identified story, review its parent Epic (e.g., `epic-{epicNum}*.md` from the location identified in step 1.1).
 - Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks.
 - Keep a record of this original epic-defined scope for later deviation analysis.
 
@@ -79,7 +76,7 @@ To identify the next logical story based on project progress and epic definition
 [[LLM: This step is CRITICAL for continuity and learning from implementation experience]]
 
 - If this is not the first story (i.e., previous story exists):
-  - Read the previous story file: `docs/stories/{prevEpicNum}.{prevStoryNum}.story.md`
+  - Read the previous sequential story from `docs/stories`
   - Pay special attention to:
     - Dev Agent Record sections (especially Completion Notes and Debug Log References)
     - Any deviations from planned implementation
@@ -88,18 +85,30 @@ To identify the next logical story based on project progress and epic definition
     - Any "lessons learned" or notes for future stories
   - Extract relevant insights that might inform the current story's preparation
 
-### 4. Gather & Synthesize Architecture Context from Sharded Docs
+### 4. Gather & Synthesize Architecture Context
+
+[[LLM: CRITICAL - You MUST gather technical details from the architecture documents. NEVER make up technical details not found in these documents.]]
 
-[[LLM: CRITICAL - You MUST gather technical details from the sharded architecture documents. NEVER make up technical details not found in these documents.]]
+#### 4.1 Determine Architecture Document Strategy
 
-#### 4.1 Start with Architecture Index
+Based on configuration loaded in Step 0:
 
-- Read `docs/architecture/index.md` to understand the full scope of available documentation
-- Identify which sharded documents are most relevant to the current story
+- **If `architectureVersion: v4` and `architectureSharded: true`**:
+  - Read `{architectureShardedLocation}/index.md` to understand available documentation
+  - Follow the structured reading order in section 4.2 below
+  
+- **If `architectureVersion: v4` and `architectureSharded: false`**:
+  - Load the monolithic architecture from `architecture-file`
+  - Extract relevant sections based on v4 structure (tech stack, project structure, etc.)
+  
+- **If `architectureVersion` is NOT v4**:
+  - Inform user: "Architecture document is not v4 format. Will use best judgment to find relevant information."
+  - If `architectureSharded: true`: Search sharded files by filename relevance
+  - If `architectureSharded: false`: Search within monolithic `architecture-file` for relevant sections
 
-#### 4.2 Recommended Reading Order Based on Story Type
+#### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
-[[LLM: Read documents in this order, but ALWAYS verify relevance to the specific story. Skip irrelevant sections but NEVER skip documents that contain information needed for the story.]]
+[[LLM: Use this structured approach ONLY for v4 sharded architecture. For other versions, use best judgment based on file names and content.]]
 
 **For ALL Stories:**
 
@@ -108,9 +117,18 @@ To identify the next logical story based on project progress and epic definition
 3. `docs/architecture/coding-standards.md` - Ensure dev follows project conventions
 4. `docs/architecture/testing-strategy.md` - Include testing requirements in tasks
 
-**For Backend/API Stories, additionally read:** 5. `docs/architecture/data-models.md` - Data structures and validation rules 6. `docs/architecture/database-schema.md` - Database design and relationships 7. `docs/architecture/backend-architecture.md` - Service patterns and structure 8. `docs/architecture/rest-api-spec.md` - API endpoint specifications 9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)
+**For Backend/API Stories, additionally read:**
+5. `docs/architecture/data-models.md` - Data structures and validation rules
+6. `docs/architecture/database-schema.md` - Database design and relationships
+7. `docs/architecture/backend-architecture.md` - Service patterns and structure
+8. `docs/architecture/rest-api-spec.md` - API endpoint specifications
+9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)
 
-**For Frontend/UI Stories, additionally read:** 5. `docs/architecture/frontend-architecture.md` - Component structure and patterns 6. `docs/architecture/components.md` - Specific component designs 7. `docs/architecture/core-workflows.md` - User interaction flows 8. `docs/architecture/data-models.md` - Frontend data handling
+**For Frontend/UI Stories, additionally read:**
+5. `docs/architecture/frontend-architecture.md` - Component structure and patterns
+6. `docs/architecture/components.md` - Specific component designs
+7. `docs/architecture/core-workflows.md` - User interaction flows
+8. `docs/architecture/data-models.md` - Frontend data handling
 
 **For Full-Stack Stories:**
 
@@ -143,7 +161,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`.
+- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
 - Use the Story Template to structure the file.
 - Fill in:
   - Story `{EpicNum}.{StoryNum}: {Short Title Copied from Epic File}`
@@ -190,7 +208,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `docs/stories/{epicNum}.{storyNum}.story.md`
+- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 

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

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