bmad-method 4.2.0 → 4.4.0

package/docs/bmad-workflow-guide.md

@@ -0,0 +1,161 @@
+# BMAD Method Universal Workflow Guide
+
+This guide outlines the core BMAD workflow that applies regardless of which AI-powered IDE you're using.
+
+## Overview
+
+The BMAD Method follows a structured approach to AI-assisted software development:
+
+1. **Install BMAD** in your project
+2. **Plan with Gemini** using team-fullstack
+3. **Organize with bmad-master** (document sharding)
+4. **Develop iteratively** with SM → Dev cycles
+
+## The Complete Workflow
+
+### Phase 1: Project Setup
+
+1. **Install BMAD in your project**:
+
+   ```bash
+   npx bmad-method install
+   ```
+
+   - Choose "Complete installation"
+   - Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
+
+2. **Verify installation**:
+   - `.bmad-core/` folder created with all agents
+   - IDE-specific integration files created
+   - All agent commands/rules/modes available
+
+### Phase 2: Ideation & Planning (Gemini)
+
+Use Google's Gemini for collaborative planning with the full team:
+
+1. **Open [Google AI Studio](https://aistudio.google.com/)**
+2. **Load team-fullstack**:
+   - Copy contents of: `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
+   - Paste into new Gemini chat
+3. **Collaborate with the team**:
+   - Business Analyst: Requirements gathering
+   - Product Manager: Feature prioritization
+   - Solution Architect: Technical design
+   - UX Expert: User experience design
+
+### Example Gemini Sessions:
+
+```text
+"I want to build a [type] application that [core purpose].
+Help me brainstorm features and create a comprehensive PRD."
+
+"Based on this PRD, design a scalable technical architecture
+that can handle [specific requirements]."
+```
+
+4. **Export planning documents**:
+   - Save PRD as `docs/prd.md`
+   - Save architecture as `docs/architecture.md`
+
+### Phase 3: Document Organization (IDE)
+
+Switch back to your IDE for document management:
+
+1. **Load bmad-master agent** (syntax varies by IDE)
+2. **Shard the PRD**:
+   ```
+   *shard-doc docs/prd.md prd
+   ```
+3. **Shard the architecture**:
+   ```
+   *shard-doc docs/architecture.md architecture
+   ```
+
+**Result**: Organized folder structure:
+
+- `docs/prd/` - Broken down PRD sections
+- `docs/architecture/` - Broken down architecture sections
+
+### Phase 4: Iterative Development
+
+Follow the SM → Dev cycle for systematic story development:
+
+#### 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. **Agent asks**: Which story to implement
+4. **Follow development tasks**
+5. **Complete implementation**
+6. **Update status**: Change to "Done"
+
+#### Repeat Until Complete
+
+- **SM**: Create next story → Review → Approve
+- **Dev**: Implement story → Complete → Mark done
+- **Continue**: Until all features implemented
+
+## IDE-Specific Syntax
+
+### Agent Loading Syntax 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:
+
+- **Claude Code, Cursor, Windsurf**: Start new chats when switching agents
+- **Roo Code**: Switch modes within the same conversation
+
+## Available Agents
+
+### Core Development Agents:
+
+- **bmad-master**: Universal task executor, document management
+- **sm**: Scrum Master for story creation and agile process
+- **dev**: Full-stack developer for implementation
+- **architect**: Solution architect for technical design
+
+### Specialized Agents:
+
+- **pm**: Product manager for planning and prioritization
+- **analyst**: Business analyst for requirements
+- **qa**: QA specialist for testing strategies
+- **po**: Product owner for backlog management
+- **ux-expert**: UX specialist for design
+
+## Key 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
+
+## Common Commands
+
+Every agent supports these core commands:
+
+- `*help` - Show available commands
+- `*status` - Show current context/progress
+- `*exit` - Exit the agent mode
+
+## 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
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear separation of concerns and consistent progress tracking.

package/docs/claude-code-guide.md

@@ -0,0 +1,119 @@
+# BMAD Method Guide for Claude Code
+
+This guide walks you through the complete BMAD workflow using Claude Code as your AI-powered IDE.
+
+## Step 1: Install BMAD in Your Project
+
+1. Navigate to your project directory
+2. Run the BMAD installer:
+   ```bash
+   npx bmad-method install
+   ```
+3. When prompted:
+   - **Installation Type**: Choose "Complete installation (recommended)"
+   - **IDE**: Select "Claude Code"
+
+This creates a `.bmad-core` folder with all agents and a `.claude/commands` folder with agent commands.
+
+## Step 2: Set Up Team Fullstack in Gemini
+
+For ideation and planning, use Google's Gemini with the team-fullstack configuration:
+
+1. Open [Google AI Studio (Gemini)](https://aistudio.google.com/)
+2. Create a new chat
+3. Copy the contents of `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
+4. Paste this content into Gemini to set up the team
+
+### Gemini Planning Phase
+
+In Gemini, ask the BMAD team to help you:
+
+- **Ideate** your project concept
+- **Brainstorm** features and requirements
+- **Create a PRD** (Product Requirements Document)
+- **Design the architecture**
+
+Ask questions like:
+
+- "Help me brainstorm a [type of application] that does [core functionality]"
+- "Create a comprehensive PRD for this concept"
+- "Design the technical architecture for this system"
+
+Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
+
+- `docs/prd.md`
+- `docs/architecture.md`
+
+## Step 3: Back to Claude Code - Document Sharding
+
+Once you have your PRD and architecture documents in the `docs/` folder:
+
+1. **Start a new chat in Claude Code**
+2. **Load the bmad-master agent**: Type `/bmad-master`
+3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
+4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
+
+This creates organized folders:
+
+- `docs/prd/` - Contains broken down PRD sections
+- `docs/architecture/` - Contains broken down architecture sections
+
+## Step 4: Story Development Cycle
+
+Now begin the iterative development cycle:
+
+### Create Stories (Scrum Master)
+
+1. **Start a new chat**
+2. **Load SM agent**: Type `/sm`
+3. **Create story**: Type `*create` (this runs the create-next-story task)
+4. **Review the generated story**
+5. **If approved**: Set story status to "Approved" in the story file
+
+### Implement Stories (Developer)
+
+1. **Start a new chat**
+2. **Load Dev agent**: Type `/dev`
+3. **The agent will ask which story to implement**
+4. **Follow the development tasks** the agent provides
+5. **When story is complete**: Mark status as "Done"
+
+### Repeat the Cycle
+
+1. **Start a new chat with SM agent** (`/sm`)
+2. **Create next story**: Type `*create`
+3. **Review and approve**
+4. **Start new chat with Dev agent** (`/dev`)
+5. **Implement the story**
+6. **Repeat until project complete**
+
+## Available Commands in Claude Code
+
+All BMAD agents are available as Claude Code commands:
+
+- `/bmad-master` - Universal task executor
+- `/sm` - Scrum Master for story creation
+- `/dev` - Full-stack developer for implementation
+- `/architect` - Solution architect for design
+- `/pm` - Product manager for planning
+- `/analyst` - Business analyst for requirements
+- `/qa` - QA specialist for testing
+- `/po` - Product owner for prioritization
+- `/ux-expert` - UX specialist for design
+
+## Key Workflow Principles
+
+1. **Always start new chats** when switching agents to avoid context confusion
+2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
+3. **Use bmad-master for document management** (sharding, templates, etc.)
+4. **Follow the SM → Dev cycle** for consistent story development
+5. **Review and approve stories** before implementation begins
+
+## Tips for Success
+
+- **Keep chats focused**: Each chat should have one agent and one primary task
+- **Use \*help command**: Every agent supports `*help` to see available commands
+- **Review generated content**: Always review and approve stories before marking them ready
+- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

package/docs/core-architecture.md

@@ -0,0 +1,213 @@
+# BMAD Method: Core Architecture
+
+This document serves as the definitive source of truth for the BMAD-Method's architecture. It is designed to be understood by both human developers and the AI agents that operate within the framework.
+
+## 1. Overview
+
+The BMAD-Method is an AI-Powered Agile Development Framework designed to transform software development by providing specialized AI agents for every role in a complete Agile team. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex software development tasks in a predictable, high-quality manner.
+
+The system facilitates a full development lifecycle:
+
+1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
+2. **Architecture & Design**: Defining system architecture and UI/UX specifications.
+3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
+
+## 2. System Architecture Diagram
+
+The entire BMAD-Method ecosystem is designed around the `.bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
+
+````mermaid
+graph TD
+    subgraph BMAD Method Project
+        subgraph Core Framework
+            A["bmad-core"]
+            A --> B["agents"]
+            A --> C["agent-teams"]
+            A --> D["workflows"]
+            A --> E["templates"]
+            A --> F["tasks"]
+            A --> G["checklists"]
+            A --> H["data (KB)"]
+        end
+
+        subgraph Tooling
+            I["tools/builders/web-builder.js"]
+        end
+
+        subgraph Outputs
+            J[".bmad-core/web-bundles"]
+        end
+
+        B -- defines dependencies for --> E
+        B -- defines dependencies for --> F
+        B -- defines dependencies for --> G
+        B -- defines dependencies for --> H
+
+        C -- bundles --> B
+        I -- reads from --> A
+        I -- creates --> J
+    end
+
+    subgraph Target Environments
+        K["IDE (Cursor, VS Code, etc.)"]
+        L["Web UI (Gemini, ChatGPT)"]
+    end
+
+    B --> K
+    J --> L
+
+    style A fill:#1a73e8,color:#fff
+    style I fill:#f9ab00,color:#fff
+    style J fill:#34a853,color:#fff
+```text
+
+## 3. Core Components
+
+The `.bmad-core` directory contains all the definitions and resources that give the agents their capabilities.
+
+### 3.1. Agents (`.bmad-core/agents/`)
+
+- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
+- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
+- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation.
+- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
+- **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
+
+### 3.2. Agent Teams (`.bmad-core/agent-teams/`)
+
+- **Purpose**: Team files (e.g., `team-all.yml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
+- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
+
+### 3.3. Workflows (`.bmad-core/workflows/`)
+
+- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
+- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
+
+### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
+
+- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies.
+  - **`templates/`**: Contains markdown templates for common documents like PRDs, architecture specifications, and user stories.
+  - **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story".
+  - **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or Architect.
+  - **`data/`**: Contains the core knowledge base (`bmad-kb.md`), technical preferences (`technical-preferences.md`), and other key data files.
+
+#### 3.4.1. Template Processing System
+
+A key architectural principle of BMAD is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
+
+The BMAD framework employs a sophisticated template processing system orchestrated by three key components:
+
+- **`template-format.md`** (`.bmad-core/utils/`): Defines the foundational markup language used throughout all BMAD templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
+
+- **`create-doc.md`** (`.bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
+
+- **`advanced-elicitation.md`** (`.bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
+
+The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
+
+#### 3.4.2. Technical Preferences System
+
+BMAD includes a personalization layer through the `technical-preferences.md` file in `.bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
+
+**Purpose and Benefits:**
+- **Consistency**: Ensures all agents reference the same technical preferences
+- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
+- **Personalization**: Agents provide recommendations aligned with user preferences
+- **Learning**: Captures lessons learned and preferences that evolve over time
+
+**Content Structure:**
+The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
+
+**Integration Points:**
+- Templates can reference technical preferences during document generation
+- Agents suggest preferred technologies when appropriate for project requirements
+- When preferences don't fit project needs, agents explain alternatives
+- Web bundles can include preferences content for consistent behavior across platforms
+
+**Evolution Over Time:**
+Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time.
+
+## 4. The Build & Delivery Process
+
+The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter.
+
+### 4.1. Web Builder (`tools/builders/web-builder.js`)
+
+- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `.bmad-core/web-bundles/`.
+- **Process**:
+  1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
+  2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
+  3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
+  4. **Outputs Bundle**: The final `.txt` file is saved in the `web-bundles` directory, ready to be uploaded to a web UI.
+
+### 4.2. Environment-Specific Usage
+
+- **For IDEs**: Users interact with the agents directly via their markdown files in `.bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
+- **For Web UIs**: Users upload a pre-built bundle from `.bmad-core/web-bundles/`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
+
+## 5. BMAD Workflows
+
+### 5.1. The Planning Workflow
+
+Before development begins, BMAD follows a structured planning workflow that establishes the foundation for successful project execution:
+
+```mermaid
+graph TD
+    A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"}
+    B -->|Yes| C["Analyst: Market Research & Analysis"]
+    B -->|No| D["Create Project Brief"]
+    C --> D["Analyst: Create Project Brief"]
+    D --> E["PM: Create PRD from Brief"]
+    E --> F["Architect: Create Architecture from PRD"]
+    F --> G["PO: Run Master Checklist"]
+    G --> H{"Documents Aligned?"}
+    H -->|Yes| I["Planning Complete"]
+    H -->|No| J["PO: Update Epics & Stories"]
+    J --> K["Update PRD/Architecture as needed"]
+    K --> G
+    I --> L["📁 Switch to IDE"]
+    L --> M["PO: Shard Documents"]
+    M --> N["Ready for SM/Dev Cycle"]
+
+    style I fill:#34a853,color:#fff
+    style G fill:#f9ab00,color:#fff
+    style L fill:#1a73e8,color:#fff
+    style N fill:#34a853,color:#fff
+````
+
+**Key Planning Phases:**
+
+1. **Optional Analysis**: Analyst conducts market research and competitive analysis
+2. **Project Brief**: Foundation document created by Analyst or user
+3. **PRD Creation**: PM transforms brief into comprehensive product requirements
+4. **Architecture Design**: Architect creates technical foundation based on PRD
+5. **Validation & Alignment**: PO ensures all documents are consistent and complete
+6. **Refinement**: Updates to epics, stories, and documents as needed
+7. **Environment Transition**: Critical switch from web UI to IDE for development workflow
+8. **Document Preparation**: PO shards large documents for development consumption
+
+**Workflow Orchestration**: The `bmad-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases.
+
+### 5.2. The Core Development Cycle
+
+Once the initial planning and architecture phases are complete, the project moves into a cyclical development workflow, as detailed in the `bmad-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process.
+
+```mermaid
+graph TD
+    A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
+    B --> C["PO: Shard Arch"]
+    C --> D["Development Phase"]
+    D --> E["Scrum Master: Drafts next story from sharded epic"]
+    E --> F{"User Approval"}
+    F -->|Approved| G["Dev: Implement Story"]
+    F -->|Needs Changes| E
+    G --> H["Dev: Complete story Tasks"]
+    H --> I{"User Verification"}
+    I -->|Verified Complete| J["Mark Story as Done"]
+    I -->|Needs Fixes| G
+    J --> E
+
+    style J fill:#34a853,color:#fff
+```
+
+This cycle continues, with the Scrum Master and Developer agents working in tandem, until all stories in the epic are completed.

package/docs/cursor-guide.md

@@ -0,0 +1,127 @@
+# BMAD Method Guide for Cursor
+
+This guide walks you through the complete BMAD workflow using Cursor as your AI-powered IDE.
+
+## Step 1: Install BMAD in Your Project
+
+1. Navigate to your project directory
+2. Run the BMAD installer:
+   ```bash
+   npx bmad-method install
+   ```
+3. When prompted:
+   - **Installation Type**: Choose "Complete installation (recommended)"
+   - **IDE**: Select "Cursor"
+
+This creates a `.bmad-core` folder with all agents and a `.cursor/rules` folder with agent rules.
+
+## Step 2: Set Up Team Fullstack in Gemini
+
+For ideation and planning, use Google's Gemini with the team-fullstack configuration:
+
+1. Open [Google AI Studio (Gemini)](https://aistudio.google.com/)
+2. Create a new chat
+3. Copy the contents of `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
+4. Paste this content into Gemini to set up the team
+
+### Gemini Planning Phase
+
+In Gemini, ask the BMAD team to help you:
+
+- **Ideate** your project concept
+- **Brainstorm** features and requirements
+- **Create a PRD** (Product Requirements Document)
+- **Design the architecture**
+
+Ask questions like:
+
+- "Help me brainstorm a [type of application] that does [core functionality]"
+- "Create a comprehensive PRD for this concept"
+- "Design the technical architecture for this system"
+
+Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
+
+- `docs/prd.md`
+- `docs/architecture.md`
+
+## Step 3: Back to Cursor - Document Sharding
+
+Once you have your PRD and architecture documents in the `docs/` folder:
+
+1. **Start a new chat in Cursor**
+2. **Load the bmad-master agent**: Type `@bmad-master`
+3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
+4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
+
+This creates organized folders:
+
+- `docs/prd/` - Contains broken down PRD sections
+- `docs/architecture/` - Contains broken down architecture sections
+
+## Step 4: Story Development Cycle
+
+Now begin the iterative development cycle:
+
+### Create Stories (Scrum Master)
+
+1. **Start a new chat**
+2. **Load SM agent**: Type `@sm`
+3. **Create story**: Type `*create` (this runs the create-next-story task)
+4. **Review the generated story**
+5. **If approved**: Set story status to "Approved" in the story file
+
+### Implement Stories (Developer)
+
+1. **Start a new chat**
+2. **Load Dev agent**: Type `@dev`
+3. **The agent will ask which story to implement**
+4. **Follow the development tasks** the agent provides
+5. **When story is complete**: Mark status as "Done"
+
+### Repeat the Cycle
+
+1. **Start a new chat with SM agent** (`@sm`)
+2. **Create next story**: Type `*create`
+3. **Review and approve**
+4. **Start new chat with Dev agent** (`@dev`)
+5. **Implement the story**
+6. **Repeat until project complete**
+
+## Available Agent Rules in Cursor
+
+All BMAD agents are available as Cursor rules (use `@` prefix):
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master for story creation
+- `@dev` - Full-stack developer for implementation
+- `@architect` - Solution architect for design
+- `@pm` - Product manager for planning
+- `@analyst` - Business analyst for requirements
+- `@qa` - QA specialist for testing
+- `@po` - Product owner for prioritization
+- `@ux-expert` - UX specialist for design
+
+## Cursor-Specific Features
+
+- **Agent rules are stored in**: `.cursor/rules/` as `.mdc` files
+- **Auto-completion**: Cursor will suggest `@agent-name` as you type
+- **Rule activation**: Rules activate automatically when you mention `@agent-name`
+- **Context awareness**: Agents have access to your current file context
+
+## Key Workflow Principles
+
+1. **Always start new chats** when switching agents to avoid context confusion
+2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
+3. **Use bmad-master for document management** (sharding, templates, etc.)
+4. **Follow the SM → Dev cycle** for consistent story development
+5. **Review and approve stories** before implementation begins
+
+## Tips for Success
+
+- **Keep chats focused**: Each chat should have one agent and one primary task
+- **Use \*help command**: Every agent supports `*help` to see available commands
+- **Review generated content**: Always review and approve stories before marking them ready
+- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
+- **Leverage Cursor's context**: Agents can see your current file selection for better assistance
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.