BMAD Method Guide for Windsurf

This guide walks you through the complete BMAD workflow using Windsurf as your AI-powered IDE.

Step 1: Install BMAD in Your Project

• Navigate to your project directory

• Run the BMAD installer:

• When prompted:

• Installation Type: Choose “Complete installation (recommended)”

• IDE: Select “Windsurf”

This creates a .bmad-core folder with all agents and a .windsurf/rules folder with agent rules.

Step 2: Set Up Team Fullstack in Gemini

For ideation and planning, use Google’s Gemini Custom Gem with the team-fullstack configuration:

• Open Google gems
• Create a new Gem - give it a title and description
• Copy the contents of .<install location>/<web-bundles>/teams/team-fullstack.txt (location can vary if you chose a non default installation location for the bundles) - or just use the bundle premade from the repo dist folder.
• 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 Windsurf - Document Sharding

Once you have your PRD and architecture documents in the docs/ folder:

• Start a new chat in Windsurf
• Load the bmad-master agent: Type @bmad-master
• Shard the PRD: Type *shard-doc docs/prd.md prd
• 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)

• Start a new chat
• Load SM agent: Type @sm
• Create story: Type *create (this runs the create-next-story task)
• Review the generated story
• If approved: Set story status to “Approved” in the story file

Implement Stories (Developer)

• Start a new chat
• Load Dev agent: Type @dev
• The agent will ask which story to implement
• Follow the development tasks the agent provides
• When story is complete: Mark status as “Done”

Repeat the Cycle

• Start a new chat with SM agent (@sm)
• Create next story: Type *create
• Review and approve
• Start new chat with Dev agent (@dev)
• Implement the story
• Repeat until project complete

Available Agent Rules in Windsurf

All BMAD agents are available as Windsurf 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

Windsurf-Specific Features

• Agent rules are stored in: .windsurf/rules/ as .md files + Rule activation: Rules activate when you mention @agent-name in chat + Collaborative workflow: Windsurf’s collaborative features work well with BMAD’s agent-switching pattern + Context awareness: Agents have access to your project context

Key Workflow Principles

• Always start new chats when switching agents to avoid context confusion
• Use Gemini for initial planning and ideation with the team-fullstack bundle
• Use bmad-master for document management (sharding, templates, etc.)
• Follow the SM → Dev cycle for consistent story development
• 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 Windsurf’s collaboration: Use the collaborative features for team reviews

This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

npx bmad-method install