Enhance Documentation Structure and Navigation in MkDocs
- Updated mkdocs.yml to comment out logo and favicon paths, indicating they should be uncommented when assets are added. - Expanded navigation structure to include new sections for Setup & Configuration and Contributing, improving accessibility to essential documentation. - Revised README to link to the OpenMemory MCP Setup Guide, providing clearer instructions for enabling advanced memory features. - Updated instruction.md to clarify section titles for better user understanding. - Enhanced quick-reference.md by adding icons to memory-related commands, emphasizing their integration with OpenMemory MCP for improved user experience. - Improved overall organization and clarity of documentation to facilitate better user guidance and onboarding.
This commit is contained in:
Daniel Bentes
parent
168e350d7a
commit
49b3fc63c8
|
|
@ -0,0 +1,52 @@
|
|||
# 🎨 Visual Assets Needed
|
||||
|
||||
The BMad Method documentation requires the following visual assets to complete the professional branding:
|
||||
|
||||
## **Required Assets**
|
||||
|
||||
### 1. **BMad Method Logo** (`bmad-logo.png`)
|
||||
- **Purpose**: Main logo displayed in documentation header
|
||||
- **Dimensions**: 200x50px (recommended)
|
||||
- **Format**: PNG with transparent background
|
||||
- **Style Guidelines**:
|
||||
- Should represent the BMad Method brand
|
||||
- Clean, professional appearance
|
||||
- Works well on both light and dark backgrounds
|
||||
- Readable at small sizes
|
||||
|
||||
### 2. **Favicon** (`favicon.png`)
|
||||
- **Purpose**: Browser tab icon for documentation site
|
||||
- **Dimensions**: 32x32px (can also provide 16x16px)
|
||||
- **Format**: PNG or ICO
|
||||
- **Style Guidelines**:
|
||||
- Simple, recognizable icon derived from main logo
|
||||
- Clear at very small sizes
|
||||
- Represents BMad Method identity
|
||||
|
||||
## **Integration**
|
||||
|
||||
Once assets are created:
|
||||
|
||||
1. Place files in `docs/assets/images/` directory
|
||||
2. Uncomment lines in `mkdocs.yml`:
|
||||
```yaml
|
||||
logo: assets/images/bmad-logo.png
|
||||
favicon: assets/images/favicon.png
|
||||
```
|
||||
3. Test with `mkdocs serve` to verify proper display
|
||||
|
||||
## **Design Notes**
|
||||
|
||||
- **Brand Colors**: Consider using blues (#1976d2) to match current theme
|
||||
- **Typography**: Should complement Material Design theme
|
||||
- **Simplicity**: Keep designs clean and minimal for best documentation experience
|
||||
|
||||
## **Priority**
|
||||
|
||||
**High** - Visual branding significantly improves documentation professionalism and user experience.
|
||||
|
||||
---
|
||||
|
||||
**Status**: 🔴 **PENDING** - Assets not yet created
|
||||
**Owner**: Design team or contractor
|
||||
**Estimated Time**: 2-4 hours for both assets
|
||||
|
|
@ -150,12 +150,14 @@ bmad-agent/
|
|||
|
||||
## Memory System Integration
|
||||
|
||||
BMAD integrates with OpenMemory MCP for persistent intelligence:
|
||||
BMAD integrates with [OpenMemory MCP](https://mem0.ai/openmemory-mcp) for persistent intelligence:
|
||||
- **Automated Learning**: Captures decisions, patterns, and outcomes
|
||||
- **Search & Retrieval**: Finds relevant past experiences
|
||||
- **Pattern Recognition**: Identifies successful approaches
|
||||
- **Continuous Improvement**: Gets smarter with each use
|
||||
|
||||
**Setup**: Follow the [OpenMemory MCP Setup Guide](./docs/setup-configuration/openmemory-setup.md) to enable advanced memory features.
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
The framework tracks comprehensive quality metrics:
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
|
|||
|
||||
## Commit Message Convention
|
||||
|
||||
[Commit Convention](./docs/commit.md)
|
||||
[Commit Convention](commit.md)
|
||||
|
||||
## Code Style
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
# Assets Directory
|
||||
|
||||
This directory contains visual assets for the BMad Method documentation.
|
||||
|
||||
## Missing Assets (Need to be added):
|
||||
- bmad-logo.png: Main logo for the documentation site
|
||||
- favicon.png: Browser tab icon for the documentation site
|
||||
|
||||
## Recommended Sizes:
|
||||
- Logo: 200x50px (PNG with transparent background)
|
||||
- Favicon: 32x32px (PNG or ICO format)
|
||||
|
||||
## Usage:
|
||||
These assets are referenced in mkdocs.yml:
|
||||
- logo: assets/images/bmad-logo.png
|
||||
- favicon: assets/images/favicon.png
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
# 🎨 Visual Assets Needed
|
||||
|
||||
The BMad Method documentation requires the following visual assets to complete the professional branding:
|
||||
|
||||
## **Required Assets**
|
||||
|
||||
### 1. **BMad Method Logo** (`bmad-logo.png`)
|
||||
- **Purpose**: Main logo displayed in documentation header
|
||||
- **Dimensions**: 200x50px (recommended)
|
||||
- **Format**: PNG with transparent background
|
||||
- **Style Guidelines**:
|
||||
- Should represent the BMad Method brand
|
||||
- Clean, professional appearance
|
||||
- Works well on both light and dark backgrounds
|
||||
- Readable at small sizes
|
||||
|
||||
### 2. **Favicon** (`favicon.png`)
|
||||
- **Purpose**: Browser tab icon for documentation site
|
||||
- **Dimensions**: 32x32px (can also provide 16x16px)
|
||||
- **Format**: PNG or ICO
|
||||
- **Style Guidelines**:
|
||||
- Simple, recognizable icon derived from main logo
|
||||
- Clear at very small sizes
|
||||
- Represents BMad Method identity
|
||||
|
||||
## **Integration**
|
||||
|
||||
Once assets are created:
|
||||
|
||||
1. Place files in `docs/assets/images/` directory
|
||||
2. Uncomment lines in `mkdocs.yml`:
|
||||
```yaml
|
||||
logo: assets/images/bmad-logo.png
|
||||
favicon: assets/images/favicon.png
|
||||
```
|
||||
3. Test with `mkdocs serve` to verify proper display
|
||||
|
||||
## **Design Notes**
|
||||
|
||||
- **Brand Colors**: Consider using blues (#1976d2) to match current theme
|
||||
- **Typography**: Should complement Material Design theme
|
||||
- **Simplicity**: Keep designs clean and minimal for best documentation experience
|
||||
|
||||
## **Priority**
|
||||
|
||||
**High** - Visual branding significantly improves documentation professionalism and user experience.
|
||||
|
||||
---
|
||||
|
||||
**Status**: 🔴 **PENDING** - Assets not yet created
|
||||
**Owner**: Design team or contractor
|
||||
**Estimated Time**: 2-4 hours for both assets
|
||||
|
|
@ -13,7 +13,7 @@ Complete reference for all BMad Method commands with contextual usage guidance a
|
|||
|---------|-------------|-------------|---------|
|
||||
| `/help` | Show available commands and context-aware suggestions | When starting a session or unsure about next steps | `/help` |
|
||||
| `/agents` | List all available personas with descriptions | When choosing which persona to activate | `/agents` |
|
||||
| `/context` | Display current session context and memory insights | Before switching personas or when resuming work | `/context` |
|
||||
| `/context` 🧠 | Display current session context and memory insights | Before switching personas or when resuming work | `/context` |
|
||||
| `/yolo` | Toggle YOLO mode for comprehensive execution | When you want full automation vs step-by-step control | `/yolo` |
|
||||
| `/core-dump` | Execute enhanced core-dump with memory integration | When debugging issues or need complete system status | `/core-dump` |
|
||||
| `/exit` | Abandon current agent with memory preservation | When finished with current persona or switching contexts | `/exit` |
|
||||
|
|
@ -28,20 +28,23 @@ Complete reference for all BMad Method commands with contextual usage guidance a
|
|||
| `/po` | Switch to Product Owner (Sam) | Backlog management, user stories | Sprint planning, story refinement |
|
||||
| `/sm` | Switch to Scrum Master (Taylor) | Process improvement, team facilitation | Throughout project, retrospectives |
|
||||
| `/analyst` | Switch to Business Analyst (Jordan) | Research, analysis, requirements gathering | Project initiation, discovery phases |
|
||||
| `/design` | Switch to Design Architect (Casey) | UI/UX design, user experience | After requirements, parallel with architecture |
|
||||
| `/design-architect` | Switch to Design Architect (Casey) | UI/UX design, user experience | After requirements, parallel with architecture |
|
||||
| `/quality` | Switch to Quality Enforcer (Riley) | Quality assurance, standards enforcement | Throughout development, reviews |
|
||||
|
||||
### Memory-Enhanced Commands
|
||||
|
||||
!!! note "OpenMemory MCP Integration"
|
||||
Commands marked with 🧠 require [OpenMemory MCP](../setup-configuration/openmemory-setup.md) for full functionality. Without OpenMemory, these commands fall back to session-based memory.
|
||||
|
||||
| Command | Description | Usage Context | Impact |
|
||||
|---------|-------------|---------------|--------|
|
||||
| `/remember {content}` | Manually add important information to memory | After making key decisions or discoveries | Improves future recommendations |
|
||||
| `/recall {query}` | Search memories with natural language queries | When you need to remember past decisions or patterns | Provides historical context |
|
||||
| `/remember {content}` 🧠 | Manually add important information to memory | After making key decisions or discoveries | Improves future recommendations |
|
||||
| `/recall {query}` 🧠 | Search memories with natural language queries | When you need to remember past decisions or patterns | Provides historical context |
|
||||
| `/udtm` | Execute Ultra-Deep Thinking Mode | For major decisions requiring comprehensive analysis | Provides systematic analysis |
|
||||
| `/anti-pattern-check` | Scan for anti-patterns | During development and review phases | Identifies problematic code patterns |
|
||||
| `/suggest` | AI-powered next step recommendations | When stuck or want validation of next steps | Provides contextual guidance |
|
||||
| `/handoff {persona}` | Structured persona transition with memory briefing | When switching personas mid-task | Ensures continuity |
|
||||
| `/bootstrap-memory` | Initialize memory for brownfield projects | When starting work on existing projects | Builds historical context |
|
||||
| `/handoff {persona}` 🧠 | Structured persona transition with memory briefing | When switching personas mid-task | Ensures continuity |
|
||||
| `/bootstrap-memory` 🧠 | Initialize memory for brownfield projects | When starting work on existing projects | Builds historical context |
|
||||
| `/quality-gate {phase}` | Run quality gate validation | At key project milestones | Ensures quality standards |
|
||||
| `/brotherhood-review` | Initiate peer validation process | Before major decisions or deliverables | Enables collaborative validation |
|
||||
| `/checklist {name}` | Run validation checklist | To ensure completeness and quality | Systematic validation |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,83 @@
|
|||
# Commit Message Convention
|
||||
|
||||
We follow a structured commit message format to maintain clarity and consistency across the project.
|
||||
|
||||
## Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
## Type
|
||||
|
||||
Must be one of the following:
|
||||
|
||||
- **feat**: A new feature
|
||||
- **fix**: A bug fix
|
||||
- **docs**: Documentation only changes
|
||||
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
|
||||
- **refactor**: A code change that neither fixes a bug nor adds a feature
|
||||
- **perf**: A code change that improves performance
|
||||
- **test**: Adding missing tests or correcting existing tests
|
||||
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
|
||||
|
||||
## Scope
|
||||
|
||||
The scope could be anything specifying the place of the commit change. For example:
|
||||
|
||||
- **docs**: Documentation changes
|
||||
- **commands**: Command system changes
|
||||
- **personas**: Persona-related changes
|
||||
- **workflows**: Workflow documentation changes
|
||||
- **build**: Build system changes
|
||||
|
||||
## Subject
|
||||
|
||||
The subject contains a succinct description of the change:
|
||||
|
||||
- Use the imperative, present tense: "change" not "changed" nor "changes"
|
||||
- Don't capitalize the first letter
|
||||
- No dot (.) at the end
|
||||
|
||||
## Body
|
||||
|
||||
Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
|
||||
The body should include the motivation for the change and contrast this with previous behavior.
|
||||
|
||||
## Footer
|
||||
|
||||
The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
|
||||
|
||||
**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
|
||||
|
||||
## Examples
|
||||
|
||||
```
|
||||
feat(commands): add new memory bootstrap command
|
||||
|
||||
Add /bootstrap-memory command to initialize memory for brownfield projects.
|
||||
This enables better context understanding when starting work on existing codebases.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix(docs): correct command references in workflow documentation
|
||||
|
||||
- Replace /patterns with /anti-pattern-check
|
||||
- Replace /insights with /suggest
|
||||
- Add missing /udtm command documentation
|
||||
|
||||
BREAKING CHANGE: Several documented commands have been renamed or replaced.
|
||||
Users should update their workflows to use the new command names.
|
||||
```
|
||||
|
||||
```
|
||||
docs(workflows): update persona selection guide
|
||||
|
||||
Improve decision tree and add new scenario mappings for better persona selection guidance.
|
||||
```
|
||||
|
|
@ -10,14 +10,16 @@ Follow this path to go from installation to your first successful project:
|
|||
graph LR
|
||||
A[Install] --> B[Verify]
|
||||
B --> C[First Project]
|
||||
C --> D[Learn Commands]
|
||||
D --> E[Master Workflows]
|
||||
C --> D[Enhanced Memory]
|
||||
D --> E[Learn Commands]
|
||||
E --> F[Master Workflows]
|
||||
|
||||
style A fill:#e1f5fe
|
||||
style B fill:#f3e5f5
|
||||
style C fill:#e8f5e8
|
||||
style D fill:#fff3e0
|
||||
style E fill:#fce4ec
|
||||
style D fill:#e3f2fd
|
||||
style E fill:#fff3e0
|
||||
style F fill:#fce4ec
|
||||
```
|
||||
|
||||
## Step 1: Installation
|
||||
|
|
@ -66,6 +68,25 @@ Build a complete project using BMad Method to experience the full workflow.
|
|||
|
||||
---
|
||||
|
||||
## Step 4: Enhanced Memory (Optional)
|
||||
|
||||
Unlock advanced memory capabilities for persistent learning and context management.
|
||||
|
||||
**Time Required:** 10-15 minutes
|
||||
|
||||
[:octicons-arrow-right-24: **Setup OpenMemory MCP**](../setup-configuration/openmemory-setup.md){ .md-button }
|
||||
|
||||
**What you'll gain:**
|
||||
- Persistent memory across sessions and projects
|
||||
- Automatic pattern recognition and learning
|
||||
- Enhanced context awareness in multi-session workflows
|
||||
- Cross-project insight sharing
|
||||
|
||||
!!! tip "Recommended for Teams"
|
||||
OpenMemory MCP dramatically improves BMad Method effectiveness, especially for teams and long-running projects.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
Once you've completed the getting started journey, these references will be invaluable:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Instructions
|
||||
|
||||
- [Setting up Web Agent Orchestrator](#setting-up-web-agent-orchestrator)
|
||||
- [IDE Agent Setup and Usage](#ide-agent-setup-and-usage)
|
||||
- [Web Agent Setup](#setting-up-web-agent-orchestrator)
|
||||
- [IDE Agent Setup](#ide-agent-setup-and-usage)
|
||||
- [Tasks Setup and Usage](#tasks)
|
||||
|
||||
## Setting up Web Agent Orchestrator
|
||||
|
|
|
|||
223
docs/readme.md
223
docs/readme.md
|
|
@ -1,68 +1,219 @@
|
|||
# Expanded Documentation
|
||||
# BMad Method Documentation
|
||||
|
||||
If you got here and did not set up the web agent yet already - highlight suggest doing that and talking to the web agent, much easier than reading these yawn inducing docs.
|
||||
This directory contains the source files for the BMad Method Documentation website, built with MkDocs and the Material theme.
|
||||
|
||||
## IDE Project Quickstart
|
||||
## Quick Start
|
||||
|
||||
After you clone the project to your local machine, you can copy the `bmad-agent` folder to your project root. This will put the templates, checklists, and other assets the local agents will need to use the agents from your IDE instead of the Web Agent. Minimally to build your project you will want the sm.ide.md and dev.ide.md so you can draft and build your project incrementally.
|
||||
### Local Development
|
||||
|
||||
Here are the more [Setup and Usage Instructions](./instruction.md) for IDE, WEB and Task setup.
|
||||
1. **Install MkDocs and dependencies**:
|
||||
```bash
|
||||
pip install mkdocs-material mkdocs-minify-plugin PyYAML requests
|
||||
```
|
||||
|
||||
Starting with the latest version of the BMad Agents for the BMad Method is very easy - all you need to do is copy `bmad-agent` folder to your project. The dedicated dev and sm that existing in previous versions are still available and are in the `bmad-agent/personas` folder with the .ide.md extension. Copy and paste the contents into your specific IDE's method of configuring a custom agent mode. The dev and sm both are configured for architecture and prd artifacts to be in (project-root)/docs and stories will be generated and developed in/from your (project-root)/docs/stories.
|
||||
2. **Serve documentation locally**:
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
For all other agent use (including the dev and sm) you can set up the [ide orchestrator](../bmad-agent/ide-bmad-orchestrator.md) - you can ask the orchestrator bmad to become any agent you have [configured](../bmad-agent/ide-bmad-orchestrator.cfg.md).
|
||||
3. **View documentation**: Open [http://localhost:8000](http://localhost:8000)
|
||||
|
||||
[General IDE Custom Mode Setup](../docs/ide-setup.md).
|
||||
### Build Static Site
|
||||
|
||||
## Advancing AI-Driven Development
|
||||
```bash
|
||||
mkdocs build
|
||||
```
|
||||
|
||||
Welcome to the latest and most advanced yet easy to use version of the Web and IDE Agent Agile Workflow! This new version, called BMad Agent version V3, represents a significant evolution that builds upon previous versions.
|
||||
The built site will be in the `site/` directory.
|
||||
|
||||
## What's New?
|
||||
## Documentation Structure
|
||||
|
||||
All IDE Agents are now optimized to be under 6K characters, so they will work with windsurf's file limit restrictions.
|
||||
```
|
||||
docs/
|
||||
├── index.md # Homepage
|
||||
├── getting-started/ # New user onboarding
|
||||
│ ├── index.md # Getting started overview
|
||||
│ ├── installation.md # Installation guide
|
||||
│ ├── verification.md # Setup verification
|
||||
│ └── first-project.md # First project tutorial
|
||||
├── commands/ # Command reference
|
||||
│ ├── index.md # Commands overview
|
||||
│ ├── orchestrator.md # Core orchestrator commands
|
||||
│ ├── agents.md # Agent-specific commands
|
||||
│ └── quick-reference.md # Auto-generated command reference
|
||||
├── workflows/ # Workflows and best practices
|
||||
│ ├── index.md # Workflow overview
|
||||
│ ├── mvp-development.md # Complete MVP example
|
||||
│ ├── persona-switching.md # Using different personas
|
||||
│ └── best-practices.md # Quality and methodology
|
||||
├── examples/ # Real-world examples
|
||||
│ ├── index.md # Examples overview
|
||||
│ ├── web-app.md # Building a web application
|
||||
│ ├── api-service.md # Creating an API service
|
||||
│ └── troubleshooting.md # Common issues and solutions
|
||||
├── reference/ # Technical reference
|
||||
│ ├── index.md # Reference overview
|
||||
│ ├── personas.md # Auto-generated personas reference
|
||||
│ ├── tasks.md # Available tasks
|
||||
│ ├── quality-framework.md # Quality standards
|
||||
│ └── memory-system.md # Memory and learning features
|
||||
└── assets/ # Images, videos, and other assets
|
||||
├── images/
|
||||
└── videos/
|
||||
```
|
||||
|
||||
The method now has an uber Orchestrator called BMAD - this agent will take your web or ide usage to the next level - this agent can morph and become the specific agent you want to work with! This makes Web usage super easy to use and set up. And in the IDE - you do not have to set up so many different agents if you do not want to!
|
||||
## Automation Scripts
|
||||
|
||||
There have been drastic improvements to the generation of documents and artifacts and the agents are now programmed to really help you build the best possible plans. Advanced LLM prompting techniques have been incorporated and programmed to help you help the agents produce amazing accurate artifacts, unlike anything seen before. Additionally agents are now configurable in what they can and cannot do - so you can accept the defaults, or set which personas are able to do what tasks. If you think the PO should be the one generating PRDs and the Scrum Master should be your course corrector - its all possible now! **Define agile the BMad way - or your way!**
|
||||
### Command Synchronization
|
||||
|
||||
While this is very powerful - you can get started with the default recommended set up as is in this repo, and basically use the agents as they are envisioned and will be explained. Detailed configuration and usage is outlined in the [Instructions](./instruction.md)
|
||||
Automatically generates command reference documentation from the BMad system:
|
||||
|
||||
## What is the BMad Method?
|
||||
```bash
|
||||
python scripts/sync-commands.py
|
||||
```
|
||||
|
||||
The BMad Method is a revolutionary approach that elevates "vibe coding" to advanced project planning to ensure your developer agents can start and completed advanced projects with very explicit guidance. It provides a structured yet flexible framework to plan, execute, and manage software projects using a team of specialized AI agents.
|
||||
**Generated files:**
|
||||
- `docs/commands/quick-reference.md` - Complete command reference
|
||||
- `docs/reference/personas.md` - Available agents and their tasks
|
||||
|
||||
This method and tooling is so much more than just a task runner - this is a refined tool that will help you bring out your best ideas, define what you really are to build, and execute on it! From ideation, to PRD creation, to the technical decision making - this will help you do it all with the power of advanced LLM guidance.
|
||||
### Content Validation
|
||||
|
||||
The method is designed to be tool-agnostic in principle, with agent instructions and workflows adaptable to various AI platforms and IDEs.
|
||||
Validates documentation for common issues:
|
||||
|
||||
## Agile Agents
|
||||
```bash
|
||||
python scripts/validate-content.py
|
||||
```
|
||||
|
||||
Agents are programmed either directly self contained to drop right into an agent config in the ide - or they can be configured as programmable entities the orchestrating agent can become.
|
||||
**Checks performed:**
|
||||
- Markdown syntax validation
|
||||
- Internal link validation
|
||||
- External link validation (when not in CI)
|
||||
- Content standards compliance
|
||||
- MkDocs configuration validation
|
||||
|
||||
### Web Agents
|
||||
## Writing Guidelines
|
||||
|
||||
Gemini 2.5 or Open AI customGPTs are created by running the node build script to generate output to a build folder. This output is the full package to create the orchestrator web agent.
|
||||
### Content Standards
|
||||
|
||||
See the detailed [Web Orchestration Setup and Usage Instructions](./instruction.md#setting-up-web-agent-orchestrator)
|
||||
- **Scannable**: Use headings, bullets, and clear structure
|
||||
- **Action-oriented**: Start with what users can do
|
||||
- **Examples-first**: Show, then explain
|
||||
- **Progressive detail**: Essential info first, details via links
|
||||
- **Mobile-friendly**: Short paragraphs, clear formatting
|
||||
|
||||
### IDE Agents
|
||||
### Markdown Conventions
|
||||
|
||||
There are dedicated self contained agents that are stand alone, and also an IDE version of an orchestrator. For there standalone, there are:
|
||||
- **Headings**: Use proper hierarchy (H1 → H2 → H3)
|
||||
- **Code blocks**: Always specify language (```bash, ```python, etc.)
|
||||
- **Links**: Use descriptive text, validate all links
|
||||
- **Line length**: Keep lines under 120 characters for readability
|
||||
- **Images**: Include alt text, optimize for web
|
||||
|
||||
- [Dev IDE Agent](../bmad-agent/personas/dev.ide.md)
|
||||
- [Story Generating SM Agent](../bmad-agent/personas/sm.ide.md)
|
||||
### File Naming
|
||||
|
||||
If you want to use the other agents, you can use the other agents from that folder - but some will be larger than Windsurf allows - and there are many agents. So its recommended to either use 1 off tasks - OR even better - use the IDE Orchestrator Agent. See these [set up and Usage instructions for IDE Orchestrator](./instruction.md#ide-agent-setup-and-usage).
|
||||
- Use lowercase with hyphens: `getting-started.md`
|
||||
- Be descriptive: `mvp-development.md` not `example1.md`
|
||||
- Match URL structure: `workflows/best-practices.md` → `/workflows/best-practices/`
|
||||
|
||||
## Tasks
|
||||
## Contributing
|
||||
|
||||
Located in `bmad-agent/tasks/`, these self-contained instruction sets allow IDE agents or the orchestrators configured agents to perform specific jobs. These also can be used as one off commands with a vanilla agent in the ide by just referencing the task and asking the agent to perform it.
|
||||
### Adding New Content
|
||||
|
||||
**Purpose:**
|
||||
1. **Create the markdown file** in the appropriate directory
|
||||
2. **Add to navigation** in `mkdocs.yml`
|
||||
3. **Run validation** to check for issues:
|
||||
```bash
|
||||
python scripts/validate-content.py
|
||||
```
|
||||
4. **Test locally** with `mkdocs serve`
|
||||
5. **Submit pull request**
|
||||
|
||||
- **Reduce Agent Bloat:** Avoid adding rarely used instructions to primary agents.
|
||||
- **On-Demand Functionality:** Instruct any capable IDE agent to execute a task by providing the task file content.
|
||||
- **Versatility:** Handles specific functions like running checklists, creating stories, sharding documents, indexing libraries, etc.
|
||||
### Updating Command Reference
|
||||
|
||||
Think of tasks as specialized mini-agents callable by your main IDE agents.
|
||||
Command references are auto-generated from the BMad system. To update:
|
||||
|
||||
1. **Modify source files** in `bmad-agent/` directory
|
||||
2. **Run sync script**:
|
||||
```bash
|
||||
python scripts/sync-commands.py
|
||||
```
|
||||
3. **Review generated files** and commit changes
|
||||
|
||||
### Content Review Process
|
||||
|
||||
1. **Validation**: All content must pass validation checks
|
||||
2. **Testing**: Test all examples and installation steps
|
||||
3. **Review**: Peer review for accuracy and clarity
|
||||
4. **Deployment**: Automatic deployment via GitHub Actions
|
||||
|
||||
## Deployment
|
||||
|
||||
Documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch.
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
If needed, you can deploy manually:
|
||||
|
||||
```bash
|
||||
mkdocs gh-deploy
|
||||
```
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
The repository includes GitHub Actions workflows for:
|
||||
|
||||
- **docs-deploy.yml**: Automatic deployment to GitHub Pages
|
||||
- **docs-validate.yml**: Content validation on pull requests
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**MkDocs won't start**:
|
||||
```bash
|
||||
pip install --upgrade mkdocs-material
|
||||
```
|
||||
|
||||
**Validation errors**:
|
||||
- Check the specific error message
|
||||
- Run `python scripts/validate-content.py` for details
|
||||
- Fix issues and re-validate
|
||||
|
||||
**Missing dependencies**:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Build errors**:
|
||||
- Check `mkdocs.yml` syntax
|
||||
- Ensure all referenced files exist
|
||||
- Run `mkdocs build --strict` for detailed errors
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Check existing [GitHub Issues](https://github.com/danielbentes/DMAD-METHOD/issues)
|
||||
2. Review validation output for specific guidance
|
||||
3. Test with a fresh MkDocs installation
|
||||
4. Create a new issue with error details and system information
|
||||
|
||||
## Performance
|
||||
|
||||
The documentation is optimized for:
|
||||
|
||||
- **Load time**: <1 second for static content
|
||||
- **Search**: <100ms response time (client-side)
|
||||
- **Mobile**: Excellent performance on all devices
|
||||
- **SEO**: Static HTML with proper metadata
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Static site generator**: MkDocs with Material theme
|
||||
- **Hosting**: GitHub Pages with global CDN
|
||||
- **Search**: Client-side search with offline capability
|
||||
- **Analytics**: Privacy-focused analytics (when configured)
|
||||
- **Content**: Markdown files with front matter
|
||||
- **Automation**: Python scripts for validation and sync
|
||||
|
||||
---
|
||||
|
||||
For more information about BMad Method, visit the [main documentation](index.md) or the [GitHub repository](https://github.com/danielbentes/DMAD-METHOD).
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
# Setup & Configuration
|
||||
|
||||
This section provides comprehensive guides for setting up and configuring BMad Method with all its components and integrations.
|
||||
|
||||
## Setup Guides
|
||||
|
||||
### Core Setup
|
||||
- **[IDE Setup](../ide-setup.md)** - Configure your IDE for BMad Method
|
||||
- **[Instructions](../instruction.md)** - Detailed setup instructions for web and IDE agents
|
||||
- **[Recommended IDE Plugins](../recommended-ide-plugins.md)** - Essential plugins for optimal experience
|
||||
|
||||
### Advanced Integrations
|
||||
- **[OpenMemory MCP Setup](openmemory-setup.md)** - Enable persistent memory and context management
|
||||
|
||||
## Configuration Overview
|
||||
|
||||
BMad Method consists of several components that work together:
|
||||
|
||||
### 🤖 **Agent Components**
|
||||
- **IDE Agents**: Lightweight, specialized agents for specific roles
|
||||
- **IDE Orchestrator**: Multi-persona agent that can embody any specialist
|
||||
- **Web Orchestrator**: Browser-based agent with large context capabilities
|
||||
|
||||
### 🧠 **Memory System**
|
||||
- **OpenMemory MCP**: Persistent memory across sessions and tools
|
||||
- **Session State**: Context management within individual sessions
|
||||
- **Cross-Project Learning**: Share insights across multiple projects
|
||||
|
||||
### 📋 **Asset System**
|
||||
- **Personas**: Specialist AI personalities (Analyst, PM, Architect, etc.)
|
||||
- **Tasks**: Structured workflows for common activities
|
||||
- **Templates**: Standardized outputs and formats
|
||||
- **Checklists**: Quality assurance and validation lists
|
||||
|
||||
## Quick Start
|
||||
|
||||
If you're new to BMad Method:
|
||||
|
||||
1. **[Start with Installation](../getting-started/installation.md)** - Basic setup
|
||||
2. **[Verify Your Setup](../getting-started/verification.md)** - Ensure everything works
|
||||
3. **[Try Your First Project](../getting-started/first-project.md)** - Hands-on experience
|
||||
4. **[Set up OpenMemory](openmemory-setup.md)** - Enable advanced memory features
|
||||
|
||||
## Configuration Files
|
||||
|
||||
Key configuration files in BMad Method:
|
||||
|
||||
- **`bmad-agent/ide-bmad-orchestrator.cfg.md`** - IDE orchestrator configuration
|
||||
- **`bmad-agent/web-bmad-orchestrator.cfg.md`** - Web orchestrator configuration
|
||||
- **`build-web-agent.cfg.js`** - Web agent build configuration
|
||||
- **`mkdocs.yml`** - Documentation site configuration
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during setup:
|
||||
|
||||
1. Check the **[Troubleshooting sections](openmemory-setup.md#troubleshooting)** in specific guides
|
||||
2. Review **[Common Issues](../getting-started/verification.md)** in verification
|
||||
3. Join the **[Community Discussions](https://github.com/danielbentes/DMAD-METHOD/discussions)**
|
||||
4. Report **[Issues on GitHub](https://github.com/danielbentes/DMAD-METHOD/issues)**
|
||||
|
||||
---
|
||||
|
||||
**Ready to begin?** Start with **[IDE Setup](../ide-setup.md)** or jump to **[OpenMemory Setup](openmemory-setup.md)** for advanced features.
|
||||
|
|
@ -0,0 +1,303 @@
|
|||
# OpenMemory MCP Setup Guide
|
||||
|
||||
BMad Method integrates with [OpenMemory MCP](https://mem0.ai/openmemory-mcp) to provide persistent memory and context management across AI tools. This guide will help you set up OpenMemory MCP for enhanced BMad Method functionality.
|
||||
|
||||
!!! tip "Enhanced Memory Capabilities"
|
||||
OpenMemory MCP enables BMad Method to remember past decisions, patterns, and lessons learned across sessions, dramatically improving the quality of recommendations and workflow efficiency.
|
||||
|
||||
## What is OpenMemory MCP?
|
||||
|
||||
[OpenMemory MCP](https://mem0.ai/openmemory-mcp) is a local application that stores, organizes, and manages memories with topics, emotions, and timestamps. It enables sharing memories across AI tools like Claude, Cursor, and Windsurf while keeping your data private and secure.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **🔒 Privacy First**: All memories stored locally on your device
|
||||
- **🔄 Cross-Tool Integration**: Works with Claude, Cursor, Windsurf, and other MCP-compatible clients
|
||||
- **📊 Structured Memories**: Enriched with metadata like categories for easy searching
|
||||
- **🎯 Permission-Based Access**: You control what AI tools can access
|
||||
- **💾 Persistent Storage**: Memories survive across sessions and tool restarts
|
||||
|
||||
### BMad Method Integration Benefits
|
||||
|
||||
- **📚 Pattern Recognition**: Remember successful workflows and avoid past mistakes
|
||||
- **🧠 Context Continuity**: Maintain project context across persona switches
|
||||
- **🎯 Personalized Recommendations**: AI suggestions based on your past preferences
|
||||
- **📈 Continuous Learning**: System gets smarter with every interaction
|
||||
- **🤝 Team Memory**: Share insights and decisions across team members
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Node.js**: Version 16 or higher
|
||||
- **Compatible AI Client**: Claude Desktop, Cursor, or Windsurf
|
||||
- **BMad Method**: Already set up and configured
|
||||
|
||||
### Step 1: Install OpenMemory MCP
|
||||
|
||||
Follow the official installation instructions from the [OpenMemory GitHub repository](https://github.com/mem0ai/mem0/tree/main/openmemory):
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/mem0ai/mem0.git
|
||||
cd mem0/openmemory
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build the application
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Step 2: Configure MCP Client
|
||||
|
||||
Configure your AI client to use OpenMemory MCP. The exact steps vary by client:
|
||||
|
||||
#### For Claude Desktop
|
||||
|
||||
Add OpenMemory to your Claude Desktop configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"openmemory": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/mem0/openmemory/dist/index.js"],
|
||||
"env": {
|
||||
"OPENMEMORY_DATA_DIR": "/path/to/your/memory/data"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### For Cursor
|
||||
|
||||
Configure Cursor to use OpenMemory MCP by adding it to your MCP configuration file.
|
||||
|
||||
#### For Windsurf
|
||||
|
||||
Follow similar MCP configuration patterns for Windsurf integration.
|
||||
|
||||
### Step 3: Verify Installation
|
||||
|
||||
Test that OpenMemory MCP is working correctly:
|
||||
|
||||
1. **Start your AI client** (Claude Desktop, Cursor, etc.)
|
||||
2. **Test memory creation**:
|
||||
```
|
||||
/remember "This is a test memory for OpenMemory MCP setup"
|
||||
```
|
||||
3. **Test memory recall**:
|
||||
```
|
||||
/recall "test memory"
|
||||
```
|
||||
|
||||
If both commands work without errors, OpenMemory MCP is successfully configured.
|
||||
|
||||
## BMad Method Configuration
|
||||
|
||||
### Update BMad Configuration
|
||||
|
||||
The BMad Method automatically detects OpenMemory MCP availability. To ensure optimal integration:
|
||||
|
||||
1. **Verify memory provider setting** in `bmad-agent/ide-bmad-orchestrator.cfg.md`:
|
||||
```yaml
|
||||
memory-provider: "openmemory-mcp"
|
||||
```
|
||||
|
||||
2. **Check memory integration settings**:
|
||||
```yaml
|
||||
memory-persistence: "hybrid"
|
||||
context-scope: "cross-session"
|
||||
auto-memory-creation: true
|
||||
proactive-surfacing: true
|
||||
```
|
||||
|
||||
### Memory Categories
|
||||
|
||||
BMad Method uses specific memory categories for optimal organization:
|
||||
|
||||
- **`decisions`**: Important project and technical decisions
|
||||
- **`patterns`**: Successful workflows and anti-patterns
|
||||
- **`mistakes`**: Lessons learned from issues and failures
|
||||
- **`handoffs`**: Context shared between persona transitions
|
||||
- **`consultations`**: Multi-persona collaboration outcomes
|
||||
- **`user-preferences`**: Your preferred approaches and styles
|
||||
- **`quality-metrics`**: Quality assessment patterns and improvements
|
||||
- **`udtm-analyses`**: Ultra-Deep Thinking Mode analysis results
|
||||
- **`brotherhood-reviews`**: Peer review insights and feedback
|
||||
|
||||
## Usage with BMad Method
|
||||
|
||||
### Enhanced Commands
|
||||
|
||||
With OpenMemory MCP configured, BMad Method provides enhanced memory capabilities:
|
||||
|
||||
#### Core Memory Commands
|
||||
```bash
|
||||
/remember "key insight or decision" # Store important information
|
||||
/recall "search query" # Find relevant past memories
|
||||
/context # Get enhanced context with memory insights
|
||||
```
|
||||
|
||||
#### Memory-Enhanced Workflows
|
||||
```bash
|
||||
# Before starting work
|
||||
/context # Check current state + memory insights
|
||||
/recall "similar projects" # Learn from past experience
|
||||
|
||||
# During work
|
||||
/remember "Decision: chose React for team familiarity"
|
||||
/handoff architect # Structured transition with memory
|
||||
|
||||
# After completion
|
||||
/remember "Lesson learned: integration testing caught 3 major issues"
|
||||
```
|
||||
|
||||
### Automatic Memory Creation
|
||||
|
||||
BMad Method automatically creates memories for:
|
||||
|
||||
- **Major decisions** made during UDTM analysis
|
||||
- **Quality gate** outcomes and lessons learned
|
||||
- **Persona handoffs** with context and reasoning
|
||||
- **Brotherhood review** insights and feedback
|
||||
- **Anti-pattern detection** and resolution approaches
|
||||
- **Successful workflow patterns** and optimizations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### OpenMemory MCP Not Detected
|
||||
|
||||
**Symptoms**: BMad Method shows "Memory provider: file-based" instead of "openmemory-mcp"
|
||||
|
||||
**Solutions**:
|
||||
1. Verify OpenMemory MCP is running: Check your AI client's MCP server status
|
||||
2. Check configuration paths: Ensure paths in MCP configuration are correct
|
||||
3. Restart AI client: Sometimes a restart is needed to detect MCP servers
|
||||
4. Test MCP connection: Try basic `/remember` and `/recall` commands
|
||||
|
||||
#### Memory Commands Not Working
|
||||
|
||||
**Symptoms**: `/remember` and `/recall` commands return errors
|
||||
|
||||
**Solutions**:
|
||||
1. Verify MCP server status in your AI client
|
||||
2. Check OpenMemory MCP logs for errors
|
||||
3. Ensure proper permissions for data directory
|
||||
4. Test with simple memory operations first
|
||||
|
||||
#### Slow Memory Operations
|
||||
|
||||
**Symptoms**: Memory search and recall take too long
|
||||
|
||||
**Solutions**:
|
||||
1. Check memory database size and consider cleanup
|
||||
2. Ensure adequate system resources (RAM, storage)
|
||||
3. Update to latest OpenMemory MCP version
|
||||
4. Consider memory retention policies
|
||||
|
||||
### Getting Help
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. **Check BMad Method diagnostics**:
|
||||
```bash
|
||||
/diagnose
|
||||
```
|
||||
|
||||
2. **Verify OpenMemory status**:
|
||||
- Check MCP server logs in your AI client
|
||||
- Test basic memory operations
|
||||
- Verify data directory permissions
|
||||
|
||||
3. **Community Support**:
|
||||
- [OpenMemory GitHub Issues](https://github.com/mem0ai/mem0/issues)
|
||||
- [BMad Method GitHub Issues](https://github.com/danielbentes/DMAD-METHOD/issues)
|
||||
- [OpenMemory Documentation](https://mem0.ai/openmemory-mcp)
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Memory Retention Policies
|
||||
|
||||
Configure memory retention and cleanup policies:
|
||||
|
||||
```yaml
|
||||
# In BMad configuration
|
||||
memory-retention:
|
||||
default-ttl: 90d # Default memory lifetime
|
||||
auto-cleanup: true # Automatic cleanup of old memories
|
||||
categories:
|
||||
decisions: 365d # Keep decisions for 1 year
|
||||
patterns: permanent # Keep successful patterns permanently
|
||||
mistakes: 180d # Keep lessons learned for 6 months
|
||||
```
|
||||
|
||||
### Cross-Project Memory Sharing
|
||||
|
||||
Enable memory sharing across multiple projects:
|
||||
|
||||
```yaml
|
||||
cross-project-learning: true
|
||||
memory-scope: "global" # Share insights across all projects
|
||||
project-isolation: false # Allow cross-project pattern recognition
|
||||
```
|
||||
|
||||
### Team Memory Synchronization
|
||||
|
||||
For team environments, consider setting up shared memory spaces:
|
||||
|
||||
```yaml
|
||||
team-memory:
|
||||
enabled: true
|
||||
shared-categories: ["patterns", "quality-metrics", "anti-patterns"]
|
||||
sync-frequency: "daily"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Memory Organization
|
||||
|
||||
1. **Use descriptive memories**: Include context and reasoning
|
||||
```bash
|
||||
/remember "Architecture decision: Chose microservices over monolith due to team size (8 developers) and need for independent deployment cycles"
|
||||
```
|
||||
|
||||
2. **Tag important patterns**:
|
||||
```bash
|
||||
/remember "Successful pattern: Starting with /analyst before /pm improved requirements quality by 40%"
|
||||
```
|
||||
|
||||
3. **Document mistakes with solutions**:
|
||||
```bash
|
||||
/remember "Mistake: Skipped integration testing, caused 3-day deployment delay. Solution: Always run integration tests before merge"
|
||||
```
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
1. **Start sessions with memory review**:
|
||||
```bash
|
||||
/context # Get current state + memory insights
|
||||
/recall "project challenges" # Learn from past issues
|
||||
```
|
||||
|
||||
2. **Regular memory maintenance**:
|
||||
```bash
|
||||
/recall "outdated patterns" # Review and update old patterns
|
||||
/remember "Pattern update: New linting rules improved code quality"
|
||||
```
|
||||
|
||||
3. **Share insights with team**:
|
||||
```bash
|
||||
/remember "Team insight: Daily standups more effective with specific blockers discussion"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Next Steps:**
|
||||
- [Return to Setup & Configuration](index.md)
|
||||
- [Explore Memory-Enhanced Workflows](../workflows/index.md)
|
||||
- [Learn about Enhanced Commands](../commands/quick-reference.md)
|
||||
15
mkdocs.yml
15
mkdocs.yml
|
|
@ -34,8 +34,9 @@ theme:
|
|||
- header.autohide
|
||||
- content.action.edit
|
||||
- content.code.copy
|
||||
logo: assets/images/bmad-logo.png
|
||||
favicon: assets/images/favicon.png
|
||||
# logo: assets/images/bmad-logo.png
|
||||
# favicon: assets/images/favicon.png
|
||||
# Note: Uncomment above when assets are added
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
|
|
@ -51,8 +52,18 @@ nav:
|
|||
- workflows/index.md
|
||||
- Persona Selection: workflows/persona-selection.md
|
||||
- Quality Framework: workflows/quality-framework.md
|
||||
- Workflow Diagram: workflow-diagram.md
|
||||
- Reference:
|
||||
- Personas: reference/personas.md
|
||||
- Setup & Configuration:
|
||||
- setup-configuration/index.md
|
||||
- IDE Setup: ide-setup.md
|
||||
- Instructions: instruction.md
|
||||
- Recommended IDE Plugins: recommended-ide-plugins.md
|
||||
- OpenMemory MCP Setup: setup-configuration/openmemory-setup.md
|
||||
- Contributing:
|
||||
- CONTRIBUTING.md
|
||||
- Commit Convention: commit.md
|
||||
|
||||
plugins:
|
||||
- search:
|
||||
|
|
|
|||
Loading…
Reference in New Issue