ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs: Comprehensive V4 documentation updates with Memory Bank, ADRs, and project scaffolding 

Enhanced BMAD Method documentation to reflect all V4 features and capabilities:

Documentation Updates:
- docs/versions.md: Added V4 feature list including Memory Bank, ADRs, dev journals, scaffolding preferences, enhanced agents, and session protocols
- docs/core-architecture.md: Added comprehensive sections for Memory Bank Architecture, ADR System, Development Journal System, and Project Scaffolding Standards
- README.md: Enhanced overview with new key innovations (Memory Bank Pattern, ADRs) and added navigation links to new guides
- docs/GUIDING-PRINCIPLES.md: Added new principle for Context Persistence and Knowledge Management
- docs/expansion-packs.md: Updated template guidance for YAML specification and enhanced AI Agent Ecosystems integration

New Comprehensive Guides:
- docs/memory-bank-guide.md: Complete guide to Memory Bank pattern with structure, usage, best practices, and integration points
- docs/adr-guide.md: Comprehensive ADR guide covering creation, maintenance, governance, and workflow integration
- docs/project-scaffolding-guide.md: Detailed guide to standardized project structures and organizational patterns

Framework Integration Updates:
- CLAUDE.md: Updated to reflect all V4 enhancements including new architecture components, enhanced agent capabilities, key data files, and practical guidance for V4 features

Key Features Documented:
- Memory Bank pattern for persistent AI context across sessions
- Architecture Decision Records (ADRs) for comprehensive decision tracking
- Development Journal system for session documentation and progress tracking
- Project scaffolding preferences for standardized directory structures
- Enhanced agent capabilities with session kickoff, comprehensive commit/PR workflows, and sprint reviews
- Context persistence systems that eliminate context loss between development sessions

This documentation update ensures complete coverage of the enhanced BMAD framework capabilities and provides practical guidance for implementing and using all V4 features.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Lucas C 2025-07-20 22:11:38 +02:00
parent 7cd0dd61a3
commit ddb3086e28
9 changed files with 1443 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
CLAUDE.md Normal file
View File

@ -0,0 +1,158 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Overview
BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is a natural language AI agent framework that orchestrates collaborative AI agents for software development and other domains. The entire framework is markdown-based with no code in the core framework.
## Key Architecture
### Multi-Agent System
- **Location**: `bmad-core/agents/` - Individual AI personas with specific roles
- **Agent Teams**: `bmad-core/agent-teams/` - Bundled collections of agents
- **Workflows**: `bmad-core/workflows/` - Prescribed sequences for different project types
- **Templates**: `bmad-core/templates/` - Reusable document templates (PRD, Architecture, etc.)
- **Tasks**: `bmad-core/tasks/` - Specific repeatable actions
- **Data**: `bmad-core/data/` - Knowledge base, technical preferences, coding standards, and scaffolding preferences
- **Checklists**: `bmad-core/checklists/` - Quality assurance and validation checklists for agents
### Two-Phase Development Approach
1. **Planning Phase** (Web UI): Creates PRDs and Architecture documents
2. **Development Phase** (IDE): Converts plans into hyper-detailed implementation stories
### V4 Enhanced Features
- **Memory Bank Pattern**: Persistent AI context management across development sessions (`docs/memory-bank/`)
- **Architecture Decision Records (ADRs)**: Comprehensive decision tracking system (`docs/adr/`)
- **Development Journals**: Session documentation and progress tracking (`docs/devJournal/`)
- **Project Scaffolding Standards**: Standardized directory structures and organizational patterns
- **Enhanced Agent Capabilities**: Session kickoff, comprehensive commit/PR workflows, sprint reviews
- **Context Persistence**: Eliminates context loss between development sessions
### Important Files
- `bmad-web-build.js` - Builds bundled text files for web UI consumption
- `bmad-installer.js` - Installs BMAD into other projects
- `bmad-version.js` - Version management utilities
- `settings.yaml` - Core framework configuration
## Essential Commands
### Development
```bash
# Install dependencies
npm install
# Build for web UI (creates bundled text files)
npm run build:web
# Build development version (for PR testing)
npm run build:dev
# Run installer locally
node ./tools/bmad-installer.js
# Format code
npm run format
# Check formatting
npm run format:check
# Run validation scripts
npm run validate
```
### Version Management
```bash
# Show current version
node ./tools/bmad-version.js
# Sync version across all files
node ./tools/bmad-version.js --sync
```
### Release Process
Releases are automated via semantic-release. Commits should follow conventional commit format:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation changes
- `chore:` for maintenance tasks
## Working with Agents and Workflows
### Adding/Modifying Agents
1. Agents are in `bmad-core/agents/[agent-name]/`
2. Each agent has `agent.yaml` (configuration) and `agent-system-prompt.md` (instructions)
3. Agents can reference templates, tasks, and tools
4. When modifying agents, ensure consistency with their role in workflows
### Working with Workflows
1. Workflows are in `bmad-core/workflows/[workflow-name].yaml`
2. They define sequences of agent interactions
3. Reference agents by their IDs from the agent definitions
4. Include handoff instructions between agents
### Templates and Tasks
- Templates (`bmad-core/templates/`) provide document structures using YAML format with embedded LLM instructions
- Tasks (`bmad-core/tasks/`) define specific repeatable actions including Memory Bank, ADR, and journal management
- Checklists (`bmad-core/checklists/`) provide quality assurance and validation workflows
- Data files (`bmad-core/data/`) include knowledge base, coding standards, technical preferences, and project scaffolding preferences
- All components are referenced by agents and can be customized per project
### Key Data Files
- `bmad-kb.md` - Core knowledge base with BMad concepts and workflows
- `technical-preferences.md` - User's preferred technologies and patterns
- `coding-standards.md` - Code quality standards and security principles
- `project-scaffolding-preference.md` - Standardized project structure guidelines
- `twelve-factor-principles.md` - Cloud-native application principles
- `microservice-patterns.md` - Microservice architecture patterns
## Testing and Validation
Since this is a natural language framework, there are no unit tests. Quality is ensured through:
1. Agent checklists and validation prompts
2. Workflow review cycles
3. Validation scripts that check YAML and markdown formatting
## Important Considerations
1. **Natural Language Focus**: All core framework components are markdown/YAML - no code
2. **Installer Pattern**: BMAD is designed to be installed into other projects, not run standalone
3. **Web UI Build**: The `build:web` command creates special bundled files for ChatGPT/Gemini consumption
4. **Expansion Packs**: The framework supports domain-specific extensions (game dev, DevOps, etc.)
5. **Document Sharding**: Large documents are automatically broken down into manageable pieces
6. **Memory Bank Integration**: Projects should initialize Memory Bank structure for context persistence
7. **ADR Documentation**: Important architectural decisions should be documented using ADR templates
8. **Project Scaffolding**: New projects should follow standardized directory structures from project-scaffolding-preference.md
9. **Agent Dependencies**: Agents now include enhanced capabilities for session management, context persistence, and quality workflows
## Working with V4 Features
### Memory Bank Usage
- Use `*initialize-memory-bank` task to set up persistent context structure
- Agents reference Memory Bank during session kickoff for full project context
- Update Memory Bank throughout development to maintain current state
### ADR Management
- Use `*create-adr` task for documenting architectural decisions
- ADRs are stored in `docs/adr/` and linked from Memory Bank system
- Reference ADRs in development stories and architecture documentation
### Development Journals
- Use `*create-dev-journal` task to document development sessions
- Journals capture progress, decisions, and insights for future reference
- Stored in `docs/devJournal/` organized by date/session
### Session Management
- Use `*session-kickoff` for proper session initialization with full context
- `*comprehensive-commit` and `*comprehensive-pr` for enhanced git workflows
- `*sprint-review` for comprehensive retrospectives and progress assessment
## GitHub Actions
The repository uses automated workflows for:
- CI/CD with semantic release
- Version syncing across documentation
- Changelog generation
- NPM publishing
When making changes, ensure they pass the format checks and validation scripts before committing.

11
README.md
View File

@ -15,13 +15,17 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
## Overview
**BMad Method's Two Key Innovations:**
**BMad Method's Key Innovations:**
**1. Agentic Planning:** Dedicated agents (Analyst, PM, Architect) collaborate with you to create detailed, consistent PRDs and Architecture documents. Through advanced prompt engineering and human-in-the-loop refinement, these planning agents produce comprehensive specifications that go far beyond generic AI task generation.
**2. Context-Engineered Development:** The Scrum Master agent then transforms these detailed plans into hyper-detailed development stories that contain everything the Dev agent needs - full context, implementation details, and architectural guidance embedded directly in story files.
This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why.
**3. Memory Bank Pattern:** Persistent AI context management across development sessions maintains project understanding, architectural decisions, and development progress, eliminating context loss between sessions.
**4. Architecture Decision Records (ADRs):** Comprehensive tracking and documentation of technical decisions throughout the project lifecycle, preserving institutional knowledge and decision rationale.
This multi-faceted approach eliminates **planning inconsistency**, **context loss**, and **decision drift** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why, while the Memory Bank ensures continuity across all development sessions.
**📖 [See the complete workflow in the User Guide](bmad-core/user-guide.md)** - Planning phase, development cycle, and all agent roles
@ -41,6 +45,9 @@ This two-phase approach eliminates both **planning inconsistency** and **context
- **[Install and Build software with Full Stack Agile AI Team](#quick-start)** → Quick Start Instruction
- **[Learn how to use BMad](bmad-core/user-guide.md)** → Complete user guide and walkthrough
- **[See available AI agents](#available-agents)** → Specialized roles for your team
- **[Memory Bank Guide](docs/memory-bank-guide.md)** → Persistent context management
- **[ADR Guide](docs/adr-guide.md)** → Architecture decision documentation
- **[Project Scaffolding Guide](docs/project-scaffolding-guide.md)** → Standardized project structures
- **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education
- **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain
- **[Browse ready-made expansion packs](expansion-packs/)** → Game dev, DevOps, infrastructure and get inspired with ideas and examples

7
docs/GUIDING-PRINCIPLES.md
View File

@ -24,6 +24,13 @@ The BMad Method is a natural language framework for AI-assisted software develop
- **Templates are outputs**: Structured documents with embedded instructions for generation
- **Dependencies matter**: Explicitly declare only what's needed
### 4. Context Persistence and Knowledge Management
- **Memory Bank Pattern**: Maintain persistent AI context across development sessions to eliminate context loss
- **Decision Documentation**: Use Architecture Decision Records (ADRs) to preserve institutional knowledge and decision rationale
- **Session Documentation**: Capture development progress and insights through development journals
- **Standardized Organization**: Follow consistent project scaffolding to support knowledge systems and agent workflows
## Practical Guidelines
### When to Add to Core

371
docs/adr-guide.md Normal file
View File

@ -0,0 +1,371 @@
# Architecture Decision Records (ADR) Guide
## Overview
Architecture Decision Records (ADRs) are a critical component of the BMad Method for documenting and tracking technical decisions throughout the project lifecycle. ADRs provide a structured approach to capturing the context, reasoning, and consequences of architectural choices, ensuring that institutional knowledge is preserved and decision-making processes remain transparent.
## What are ADRs?
An Architecture Decision Record is a document that captures a single architectural decision and its context. Each ADR describes:
- **The decision context** - What situation prompted this decision?
- **The decision itself** - What was decided?
- **The rationale** - Why was this decision made?
- **The consequences** - What are the implications of this decision?
ADRs are immutable once written - if a decision changes, a new ADR is created that supersedes the old one, maintaining a complete historical record of decision evolution.
## Why Use ADRs?
### Decision Transparency
- Clear documentation of why technical choices were made
- Visible reasoning process for future reference
- Shared understanding across team members
- Accountability for technical decisions
### Historical Context
- Understanding the environment and constraints when decisions were made
- Preventing re-litigation of previously resolved issues
- Learning from past decisions and their outcomes
- Maintaining continuity across team changes
### Change Management
- Structured approach to evolving architectural decisions
- Clear process for superseding previous decisions
- Impact assessment for proposed changes
- Migration planning and execution guidance
### Knowledge Transfer
- Preserving institutional knowledge beyond individual team members
- Onboarding new team members with complete context
- Understanding legacy decisions and their constraints
- Building organizational learning capabilities
## ADR Structure
BMad ADRs follow a standardized format that ensures consistency and completeness:
### Header Information
- **ADR Number**: Sequential identifier (ADR-001, ADR-002, etc.)
- **Title**: Descriptive title summarizing the decision
- **Date**: When the decision was made
- **Status**: Current status (Proposed, Accepted, Superseded, Deprecated)
- **Participants**: Who was involved in making the decision
### Core Content Sections
#### 1. Context and Problem Statement
- **Situation**: What circumstances led to this decision point?
- **Problem**: What specific problem needs to be solved?
- **Constraints**: What limitations or requirements must be considered?
- **Success Criteria**: How will we know if this decision was successful?
#### 2. Decision Drivers
- **Functional Requirements**: What capabilities must be delivered?
- **Quality Attributes**: Performance, security, maintainability, etc.
- **Technical Constraints**: Platform limitations, existing systems, etc.
- **Business Constraints**: Budget, timeline, skills, compliance, etc.
#### 3. Considered Options
For each option considered:
- **Description**: What would this approach involve?
- **Pros**: What are the advantages of this approach?
- **Cons**: What are the disadvantages or risks?
- **Trade-offs**: What would we gain/lose with this choice?
#### 4. Decision Outcome
- **Chosen Option**: Which approach was selected?
- **Justification**: Why was this option chosen over the alternatives?
- **Decision Makers**: Who made the final decision?
- **Decision Date**: When was the decision finalized?
#### 5. Consequences and Implications
- **Positive Consequences**: Expected benefits and improvements
- **Negative Consequences**: Accepted trade-offs and limitations
- **Neutral Consequences**: Other implications that are neither positive nor negative
- **Risks**: Potential issues that may arise from this decision
#### 6. Implementation Notes
- **Implementation Plan**: High-level approach to implementing the decision
- **Timeline**: Key milestones and deadlines
- **Dependencies**: What other work must be completed first?
- **Success Metrics**: How will implementation success be measured?
#### 7. Follow-up Actions
- **Next Steps**: Immediate actions required to implement the decision
- **Review Points**: When should this decision be re-evaluated?
- **Monitoring**: What should be watched to ensure the decision remains valid?
- **Migration**: If applicable, how to transition from previous approaches?
## Getting Started with ADRs
### Setting Up ADR Process
1. **Initialize ADR Structure**
```
Use the `*create-adr` command with any BMad agent
This creates the /docs/adr directory and first ADR template
```
2. **Establish ADR Governance**
```
Define who can create ADRs (typically Architect, senior developers)
Establish review and approval processes
Set guidelines for when ADRs are required
Create templates for common decision types
```
3. **Integrate with Workflows**
```
Include ADR creation in architecture tasks
Reference ADRs in development stories
Link ADRs to Memory Bank for context
Review ADRs during sprint retrospectives
```
### When to Create an ADR
**Always create an ADR for:**
- Technology stack decisions (frameworks, databases, services)
- Architecture pattern choices (microservices vs monolith, event-driven vs request-response)
- Infrastructure decisions (cloud providers, deployment strategies)
- Security architecture choices (authentication methods, data protection)
- Integration patterns and protocols
- Data architecture and storage strategies
**Consider creating an ADR for:**
- Significant library or tool selections
- Coding standards and conventions
- Testing strategies and approaches
- Deployment and release processes
- Monitoring and observability approaches
- Performance optimization strategies
**Don't create ADRs for:**
- Implementation details that don't affect architecture
- Temporary or experimental decisions
- Decisions that can be easily reversed
- Personal preferences without architectural impact
## Daily Usage Patterns
### Creating ADRs
1. **Identify Decision Point**
- Recognize when an architectural decision needs to be made
- Gather stakeholders and relevant information
- Define the scope and impact of the decision
2. **Research and Analysis**
- Investigate available options and approaches
- Analyze trade-offs and implications
- Consult with team members and experts
- Consider long-term consequences
3. **Draft ADR**
- Use `*create-adr` command to create new ADR
- Fill in all required sections thoroughly
- Include specific examples and evidence
- Reference related ADRs and documentation
4. **Review and Approval**
- Share with relevant stakeholders
- Incorporate feedback and revisions
- Obtain necessary approvals
- Finalize and mark as Accepted
### Referencing ADRs
- **In Code**: Include ADR references in significant architectural components
- **In Documentation**: Link to relevant ADRs from architecture documentation
- **In Stories**: Reference applicable ADRs in development stories
- **In Reviews**: Use ADRs to guide code and architecture reviews
### Maintaining ADRs
- **Regular Reviews**: Periodically review ADRs for continued relevance
- **Status Updates**: Update status when decisions are superseded or deprecated
- **Outcome Tracking**: Document actual consequences versus predicted outcomes
- **Lesson Capture**: Record lessons learned from ADR outcomes
## Best Practices
### Writing Quality ADRs
**Be Specific and Concrete**
- Use specific examples rather than abstract concepts
- Include quantitative criteria where possible
- Reference specific technologies, patterns, and approaches
- Provide concrete success and failure criteria
**Include Sufficient Context**
- Explain the business and technical environment
- Document constraints and assumptions
- Reference related decisions and dependencies
- Include timeline and urgency factors
**Consider Multiple Perspectives**
- Include different stakeholder viewpoints
- Consider short-term and long-term implications
- Address both technical and business concerns
- Acknowledge uncertainty and risks
**Maintain Objectivity**
- Present options fairly without bias
- Acknowledge weaknesses in chosen approaches
- Document dissenting opinions when relevant
- Separate facts from opinions clearly
### ADR Governance
**Establish Clear Ownership**
- Define who can create and approve ADRs
- Assign responsibility for ADR maintenance
- Create escalation paths for disputed decisions
- Establish review cycles and update processes
**Ensure Visibility**
- Make ADRs easily discoverable and accessible
- Include ADRs in onboarding processes
- Reference ADRs in relevant documentation
- Communicate significant ADRs to stakeholders
**Maintain Quality Standards**
- Establish templates and writing guidelines
- Require peer review before acceptance
- Validate that ADRs include all required sections
- Ensure decisions are actually implemented
## Advanced Usage
### ADR Relationships
**Superseding ADRs**
- Create new ADR that replaces previous decision
- Update old ADR status to "Superseded by ADR-XXX"
- Explain why previous decision no longer applies
- Document migration plan if applicable
**Related ADRs**
- Reference related decisions in each ADR
- Create ADR chains for evolutionary decisions
- Cross-reference ADRs that affect each other
- Maintain decision dependency maps
**ADR Collections**
- Group related ADRs by system or domain
- Create index ADRs for complex decision areas
- Organize ADRs by architectural layers or concerns
- Maintain chronological and topical views
### Integration with Tools
**Version Control**
- Store ADRs in same repository as code
- Use pull requests for ADR review processes
- Tag ADRs with relevant releases
- Track ADR changes over time
**Documentation Systems**
- Link ADRs from architecture documentation
- Include ADRs in generated documentation
- Create ADR dashboards and summaries
- Integrate with project wikis and portals
**Development Tools**
- Reference ADRs in code comments
- Include ADR numbers in commit messages
- Link ADRs from issue tracking systems
- Integrate with code review tools
## Troubleshooting Common Issues
### ADRs Not Being Created
**Symptoms**: Important decisions made without ADRs
**Solutions**:
- Include ADR creation in definition of done
- Add ADR checkpoints to review processes
- Provide ADR training and templates
- Recognize and reward good ADR practices
### ADRs Becoming Outdated
**Symptoms**: ADRs no longer reflect current reality
**Solutions**:
- Establish regular ADR review cycles
- Include ADR validation in retrospectives
- Assign ADR maintenance responsibilities
- Create processes for updating or superseding ADRs
### Low ADR Quality
**Symptoms**: ADRs lack detail or miss key information
**Solutions**:
- Provide ADR writing training and examples
- Establish peer review requirements
- Create quality checklists and templates
- Give feedback on ADR content and structure
### ADRs Not Being Used
**Symptoms**: Team doesn't reference or follow ADRs
**Solutions**:
- Make ADRs easily discoverable and accessible
- Reference ADRs in relevant processes and documentation
- Include ADR awareness in onboarding
- Demonstrate value through successful outcomes
## ADR Templates
The BMad framework includes templates for different types of ADRs:
- `adr-tmpl.yaml` - General ADR template for any architectural decision
- Specialized templates for common decision types (technology selection, pattern adoption, etc.)
These templates ensure consistency and completeness while providing guidance for documenting different types of architectural decisions.
## Related Documentation
- [Memory Bank Guide](memory-bank-guide.md) - Persistent context management
- [Project Scaffolding Guide](project-scaffolding-guide.md) - Standard project structures
- [Core Architecture](core-architecture.md) - Technical framework details
- [User Guide](../bmad-core/user-guide.md) - Complete BMad workflow documentation

110
docs/core-architecture.md
View File

@ -127,6 +127,116 @@ The file typically includes preferred technology stacks, design patterns, extern
**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.
#### 3.4.3. Memory Bank Architecture
BMad introduces a sophisticated Memory Bank pattern for persistent AI context management across development sessions. This addresses one of the most significant challenges in AI-assisted development: maintaining continuity and context between sessions.
**Purpose and Benefits:**
- **Context Persistence**: Maintains project understanding across multiple development sessions
- **Knowledge Continuity**: Preserves architectural decisions, patterns, and project-specific knowledge
- **Efficient Onboarding**: New team members or agents can quickly understand project state
- **Decision Tracking**: Links to ADR system for comprehensive decision documentation
**Memory Bank Structure:**
The Memory Bank creates a standardized directory structure in `docs/memory-bank/` containing:
- `projectContext.md`: Core project understanding and business context
- `techContext.md`: Technical architecture and implementation details
- `systemPatterns.md`: Established patterns and conventions
- `activeContext.md`: Current development state and priorities
- `progress.md`: Development milestones and completed work
**Integration Points:**
- Agents reference Memory Bank during session initialization
- Development workflows update Memory Bank as work progresses
- QA reviews validate Memory Bank accuracy during story reviews
- Sprint reviews use Memory Bank for comprehensive project assessment
#### 3.4.4. Architecture Decision Records (ADR) System
BMad incorporates a comprehensive ADR system for tracking and documenting technical decisions throughout the project lifecycle.
**Purpose and Benefits:**
- **Decision Transparency**: Clear documentation of why technical choices were made
- **Historical Context**: Understanding the reasoning behind past decisions
- **Change Management**: Structured approach to evolving architectural decisions
- **Knowledge Transfer**: Preserving institutional knowledge for team transitions
**ADR Structure:**
ADRs follow a standardized format covering:
- Decision context and problem statement
- Considered options and trade-offs
- Final decision and rationale
- Consequences and implications
- Implementation notes and timeline
**Integration Points:**
- Architect agent creates ADRs for significant technical decisions
- Development workflows reference relevant ADRs during implementation
- Memory Bank system links to ADRs for comprehensive context
- Sprint reviews evaluate ADR outcomes and lessons learned
#### 3.4.5. Development Journal System
The Development Journal system provides structured documentation for individual development sessions and overall project progress.
**Purpose and Benefits:**
- **Session Documentation**: Capturing work completed, decisions made, and issues encountered
- **Progress Tracking**: Understanding velocity and identifying bottlenecks
- **Knowledge Preservation**: Preventing loss of important insights and lessons learned
- **Retrospective Support**: Providing detailed data for sprint reviews and process improvement
**Journal Structure:**
Development journals include:
- Session objectives and planned work
- Technical work completed with context
- Decisions made and rationale
- Challenges encountered and solutions
- Next session priorities and blockers
**Integration Points:**
- Dev agent updates journals throughout development sessions
- SM agent references journals when planning subsequent stories
- Memory Bank incorporates journal insights into project context
- Sprint reviews aggregate journal data for comprehensive assessment
#### 3.4.6. Project Scaffolding Standards
BMad now includes standardized project scaffolding preferences that establish consistent directory structures and organizational patterns across all projects.
**Purpose and Benefits:**
- **Standardization**: Consistent project organization across all BMad projects
- **Efficiency**: Reduced setup time with established conventions
- **Integration**: Seamless integration with Memory Bank, ADR, and journal systems
- **Scalability**: Patterns that work for projects of varying complexity
**Standard Directory Structure:**
```
/docs
/adr # Architecture Decision Records
/devJournal # Development journals
/memory-bank # Persistent AI context
/prd # Sharded Product Requirements Documents
/architecture # Sharded Architecture Documents
```
**Integration Points:**
- All agents reference scaffolding preferences during project initialization
- Templates automatically create required directory structures
- Memory Bank and ADR systems rely on standardized locations
- Installation scripts ensure proper project structure setup
## 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.

20
docs/expansion-packs.md
View File

@ -217,10 +217,12 @@ Tasks should be:
Templates need:
- Structured output format
- Embedded LLM instructions
- Placeholders for customization
- Professional formatting
- Structured output format using YAML specification
- Embedded LLM instructions in `instruction` fields
- Placeholders for customization using `{{variable}}` syntax
- Professional formatting with clear section hierarchy
- Integration with Memory Bank and ADR systems when applicable
- Support for variable substitution and conditional sections
### Step 5: Test & Iterate
@ -251,10 +253,12 @@ Imagine a future where:
Expansion packs could enable:
- Cross-pack agent collaboration
- Industry-standard agent protocols
- Interoperable AI workflows
- Universal agent languages
- Cross-pack agent collaboration with shared Memory Bank patterns
- Industry-standard agent protocols with common ADR structures
- Interoperable AI workflows using standardized project scaffolding
- Universal agent languages with consistent template specifications
- Context persistence across different domain expertise areas
- Seamless knowledge transfer between specialized agent teams
### Democratizing Expertise

292
docs/memory-bank-guide.md Normal file
View File

@ -0,0 +1,292 @@
# Memory Bank Guide
## Overview
The Memory Bank pattern is BMad's solution to one of the most significant challenges in AI-assisted development: maintaining context and continuity across multiple development sessions. By creating a persistent, structured knowledge repository, the Memory Bank ensures that AI agents can quickly understand project state, architectural decisions, and development progress regardless of when they join the project or how much time has passed since the last session.
## What is the Memory Bank?
The Memory Bank is a standardized directory structure (`docs/memory-bank/`) containing five core documents that capture different aspects of project knowledge:
1. **projectContext.md** - Business context and project understanding
2. **techContext.md** - Technical architecture and implementation details
3. **systemPatterns.md** - Established patterns and conventions
4. **activeContext.md** - Current development state and priorities
5. **progress.md** - Development milestones and completed work
## Why Use the Memory Bank?
### Context Persistence
- Eliminates the need to re-explain project background in every session
- Maintains understanding of business requirements and constraints
- Preserves technical decisions and their rationale
### Knowledge Continuity
- Captures architectural patterns and conventions as they evolve
- Documents lessons learned and best practices discovered
- Maintains awareness of project-specific constraints and requirements
### Efficient Onboarding
- New team members can quickly understand project state
- AI agents can immediately access full project context
- Reduces ramp-up time for both humans and AI assistants
### Decision Tracking
- Links to Architecture Decision Records (ADRs) for comprehensive context
- Maintains awareness of why certain approaches were chosen
- Prevents re-litigating previously resolved decisions
## Memory Bank Structure
### projectContext.md
**Purpose**: Core business understanding and project fundamentals
**Content includes:**
- Project vision and objectives
- Target audience and user personas
- Business constraints and requirements
- Key stakeholders and decision makers
- Success metrics and KPIs
- Competitive landscape awareness
**When to update:**
- Project requirements change
- New stakeholders are identified
- Business priorities shift
- User feedback changes understanding
### techContext.md
**Purpose**: Technical architecture and implementation details
**Content includes:**
- System architecture overview
- Technology stack and frameworks
- Key design patterns and approaches
- Infrastructure and deployment details
- Integration points and external dependencies
- Performance requirements and constraints
**When to update:**
- Architectural decisions are made
- New technologies are adopted
- Infrastructure changes occur
- Performance requirements evolve
### systemPatterns.md
**Purpose**: Established patterns and conventions
**Content includes:**
- Coding standards and style guides
- Naming conventions and file organization
- Error handling patterns
- Testing approaches and strategies
- Security patterns and practices
- Code review guidelines
**When to update:**
- New patterns are established
- Conventions are refined or changed
- Best practices are discovered
- Team standards evolve
### activeContext.md
**Purpose**: Current development state and immediate priorities
**Content includes:**
- Current sprint objectives
- Active development streams
- Immediate priorities and blockers
- Recent decisions and their context
- Open questions and areas of investigation
- Next planned features or improvements
**When to update:**
- Sprint planning occurs
- Priorities change
- Blockers are encountered or resolved
- New questions or investigations arise
### progress.md
**Purpose**: Development milestones and historical progress
**Content includes:**
- Completed features and milestones
- Key achievements and breakthroughs
- Lessons learned from completed work
- Metrics and performance data
- Release history and versioning
- Retrospective insights
**When to update:**
- Features are completed
- Milestones are reached
- Sprint retrospectives occur
- Significant lessons are learned
## Getting Started with Memory Bank
### Initial Setup
1. **Initialize the Memory Bank**
```
Use the `*initialize-memory-bank` command with any BMad agent
This creates the basic directory structure and template files
```
2. **Populate Initial Context**
```
Fill in projectContext.md with business understanding
Document techContext.md with current architecture
Establish systemPatterns.md with existing conventions
Set activeContext.md with current priorities
Initialize progress.md with any completed work
```
3. **Integrate with Workflows**
```
Reference Memory Bank during session kickoffs
Update during development sessions
Review during QA processes
Validate during sprint reviews
```
### Daily Usage Patterns
#### Session Start
- Use `*session-kickoff` to load Memory Bank context
- Review activeContext.md for current priorities
- Check for any updates since last session
- Update activeContext.md with session objectives
#### During Development
- Reference techContext.md for architectural guidance
- Follow patterns established in systemPatterns.md
- Update progress.md as work is completed
- Document new patterns or decisions as they emerge
#### Session End
- Update activeContext.md with current state
- Document progress in progress.md
- Note any new patterns in systemPatterns.md
- Update technical context if architecture evolved
#### Sprint Boundaries
- Comprehensive review of all Memory Bank documents
- Update progress.md with sprint achievements
- Refresh activeContext.md with new priorities
- Validate technical context accuracy
## Best Practices
### Content Quality
- **Be Specific**: Avoid vague statements; include concrete details
- **Stay Current**: Regular updates prevent information decay
- **Include Context**: Explain not just what, but why decisions were made
- **Link References**: Connect to ADRs, documentation, and external resources
### Maintenance Patterns
- **Little and Often**: Small, frequent updates are better than large, infrequent ones
- **Team Responsibility**: All team members should contribute to Memory Bank maintenance
- **Review Cycles**: Regular reviews ensure accuracy and completeness
- **Pruning**: Remove outdated information to prevent confusion
### Integration with Other Systems
- **ADR Integration**: Link to relevant Architecture Decision Records
- **Story References**: Connect to development stories and epics
- **Documentation Links**: Reference external documentation and resources
- **Version Control**: Treat Memory Bank as code - version control all changes
## Advanced Usage
### Multi-Project Memory Banks
For teams working on multiple projects:
- Maintain separate Memory Banks per project
- Create shared patterns document for common approaches
- Cross-reference related projects and shared components
### Team Collaboration
- Establish ownership patterns for different Memory Bank sections
- Use pull request reviews for significant Memory Bank changes
- Include Memory Bank updates in definition of done
- Regular team reviews of Memory Bank accuracy
### Automation Opportunities
- Automatic updates from development tools and CI/CD systems
- Integration with project management tools for progress tracking
- Automated validation of Memory Bank content accuracy
- Notifications when Memory Bank content becomes stale
## Troubleshooting
### Common Issues
**Memory Bank becomes outdated:**
- Solution: Establish regular review cycles and update responsibilities
- Prevention: Include Memory Bank updates in sprint planning and retrospectives
**Information overload:**
- Solution: Focus on essential context; avoid unnecessary detail
- Prevention: Regular pruning of outdated or irrelevant information
**Inconsistent updates:**
- Solution: Establish clear ownership and update responsibilities
- Prevention: Include Memory Bank maintenance in team processes
**Conflicting information:**
- Solution: Regular validation against actual project state
- Prevention: Single source of truth principles and conflict resolution processes
## Memory Bank Templates
The BMad framework includes templates for each Memory Bank component:
- `projectContext-tmpl.yaml` - Business context template
- `techContext-tmpl.yaml` - Technical context template
- `systemPatterns-tmpl.yaml` - Patterns documentation template
- `activeContext-tmpl.yaml` - Current state template
- `progress-tmpl.yaml` - Progress tracking template
These templates provide structure and guidance for creating comprehensive Memory Bank documentation that integrates seamlessly with BMad workflows and agent capabilities.
## Related Documentation
- [ADR Guide](adr-guide.md) - Architecture Decision Records
- [Project Scaffolding Guide](project-scaffolding-guide.md) - Standard project structures
- [Core Architecture](core-architecture.md) - Technical framework details
- [User Guide](../bmad-core/user-guide.md) - Complete BMad workflow documentation

477
docs/project-scaffolding-guide.md Normal file
View File

@ -0,0 +1,477 @@
# Project Scaffolding Guide
## Overview
Project scaffolding in the BMad Method refers to the standardized directory structures, organizational patterns, and foundational practices that ensure consistency, efficiency, and seamless integration across all BMad-powered projects. This guide provides comprehensive guidance on establishing and maintaining project structures that support effective AI-assisted development.
## What is Project Scaffolding?
Project scaffolding encompasses the foundational organizational elements that structure a project for success:
- **Directory Structure**: Standardized folder organization and naming conventions
- **Documentation Patterns**: Consistent approaches to project documentation
- **Integration Points**: Seamless connection with BMad systems (Memory Bank, ADRs, etc.)
- **Workflow Support**: Structures that facilitate BMad agent operations
- **Scalability Patterns**: Organizations that work from small projects to enterprise systems
## Why Standardized Scaffolding Matters
### Consistency Across Projects
- Predictable project organization reduces cognitive load
- Team members can quickly navigate any BMad project
- Tools and scripts work reliably across different projects
- Knowledge transfer between projects becomes seamless
### Efficiency and Speed
- Reduced setup time with established conventions
- Faster onboarding for new team members
- Automated tooling works reliably with standard structures
- Templates and generators can make assumptions about organization
### Integration with BMad Systems
- Memory Bank pattern requires specific directory locations
- ADR system depends on standardized documentation structure
- Agent workflows expect predictable file and folder patterns
- Build and deployment scripts work with consistent organization
### Scalability and Evolution
- Patterns that work for small projects scale to enterprise systems
- Organizational principles support growth and complexity
- Consistent structures facilitate refactoring and reorganization
- Standards evolve based on real-world usage and feedback
## Standard Directory Structure
### Core Documentation Structure
```
/docs
/adr # Architecture Decision Records
/001-example.md # Individual ADR files
/002-another.md
/devJournal # Development session documentation
/2024-01/ # Organized by month
/2024-02/
/memory-bank # Persistent AI context
projectContext.md
techContext.md
systemPatterns.md
activeContext.md
progress.md
/prd # Sharded Product Requirements Documents
/section1/
/section2/
/architecture # Sharded Architecture Documents
/overview/
/detailed-design/
/patterns/
/api # API documentation and specifications
/runbooks # Operational procedures and guides
/design # UI/UX designs and specifications
```
### Source Code Organization
```
/src # Primary source code
/components/ # Reusable components
/services/ # Business logic and services
/utils/ # Utility functions and helpers
/types/ # Type definitions (TypeScript)
/constants/ # Application constants
/config/ # Configuration files
/tests # Test files (mirrors src structure)
/components/
/services/
/utils/
/integration/
/e2e/
/scripts # Build, deployment, and utility scripts
/tools # Development tools and helpers
```
### Configuration and Infrastructure
```
/config # Environment and deployment configurations
/environments/ # Environment-specific settings
/deployment/ # Deployment configurations
/infra # Infrastructure as Code
/terraform/ # Terraform configurations
/ansible/ # Ansible playbooks
/docker/ # Docker configurations
/.github # GitHub workflows and templates
/workflows/ # CI/CD workflows
/templates/ # Issue and PR templates
```
## Scaffolding Principles
### 1. Clarity and Discoverability
- **Descriptive Names**: Folder and file names clearly indicate their purpose
- **Logical Grouping**: Related items are organized together
- **Hierarchical Structure**: Information is organized from general to specific
- **Consistent Patterns**: Similar items follow similar organizational patterns
### 2. Separation of Concerns
- **Documentation vs Code**: Clear separation between documentation and implementation
- **Configuration vs Logic**: Environment and deployment configs separated from business logic
- **Tests vs Implementation**: Test code organized separately but mirroring source structure
- **Tools vs Application**: Development tools separated from application code
### 3. Scalability and Flexibility
- **Modular Organization**: Structure supports adding new modules and components
- **Depth Balance**: Not too shallow (everything in root) or too deep (excessive nesting)
- **Growth Accommodation**: Structure adapts as projects grow in size and complexity
- **Refactoring Support**: Organization facilitates moving and reorganizing code
### 4. Integration Support
- **BMad Compatibility**: Structure supports all BMad agents and workflows
- **Tool Integration**: Organization works well with development tools and IDEs
- **CI/CD Support**: Structure facilitates automated build and deployment processes
- **Documentation Generation**: Organization supports automated documentation tools
## Implementation Guide
### Starting a New Project
1. **Initialize Basic Structure**
```bash
# Create core directories
mkdir -p docs/{adr,devJournal,memory-bank,prd,architecture,api,runbooks,design}
mkdir -p src/{components,services,utils,types,constants,config}
mkdir -p tests/{components,services,utils,integration,e2e}
mkdir -p {scripts,tools,config,infra}
```
2. **Initialize BMad Systems**
```
Use `*initialize-memory-bank` to create Memory Bank structure
Create first ADR documenting project scaffolding decisions
Set up development journal structure
```
3. **Create Foundation Files**
```
README.md - Project overview and getting started guide
CONTRIBUTING.md - Contribution guidelines and processes
.gitignore - Appropriate ignore patterns for technology stack
package.json / requirements.txt / etc. - Dependency management
```
### Adapting Existing Projects
1. **Assess Current Structure**
- Document existing organization patterns
- Identify alignment gaps with BMad standards
- Plan migration strategy for minimal disruption
- Consider backward compatibility requirements
2. **Gradual Migration**
- Start with documentation structure (docs/ folder)
- Initialize Memory Bank and ADR systems
- Gradually reorganize source code following patterns
- Update build and deployment scripts as needed
3. **Team Communication**
- Communicate changes and rationale to team
- Provide migration guidance and support
- Update development workflows and processes
- Document new organizational patterns
## Technology-Specific Adaptations
### Frontend Applications (React, Vue, Angular)
```
/src
/components/
/ui/ # Pure UI components
/business/ # Business logic components
/layout/ # Layout and navigation components
/hooks/ # Custom hooks (React)
/composables/ # Composables (Vue)
/services/ # Angular services
/stores/ # State management
/assets/ # Static assets
/styles/ # Stylesheets and themes
```
### Backend Applications (Node.js, Python, Java)
```
/src
/controllers/ # Request handlers and routing
/services/ # Business logic and domain services
/models/ # Data models and entities
/repositories/ # Data access layer
/middleware/ # Request/response middleware
/validators/ # Input validation
/serializers/ # Data serialization/deserialization
```
### Full-Stack Applications
```
/client # Frontend application
/src/
/public/
/tests/
/server # Backend application
/src/
/tests/
/shared # Shared code between client and server
/types/
/constants/
/utils/
/docs # Shared documentation
```
### Microservices Architecture
```
/services
/user-service/
/src/
/tests/
/docs/
/order-service/
/src/
/tests/
/docs/
/shared
/libraries/
/types/
/tools/
/infra
/kubernetes/
/terraform/
/monitoring/
```
## Best Practices
### Naming Conventions
**Directories**
- Use lowercase with hyphens for multi-word names
- Be descriptive but concise
- Use plural forms for collections (components, services, utils)
- Avoid abbreviations unless universally understood
**Files**
- Use consistent naming patterns within each directory
- Include file type/purpose in name when helpful
- Use extensions that clearly indicate file type and purpose
- Follow language-specific conventions
### Documentation Organization
**Structure Documentation Hierarchically**
- Overview documents at top level
- Detailed documentation in subdirectories
- Cross-reference related documents
- Maintain consistent formatting and style
**Keep Documentation Close to Code**
- Component documentation near component code
- API documentation with API implementations
- Technical decisions documented in ADRs
- Implementation notes in development journals
### Configuration Management
**Environment-Specific Configuration**
- Separate configuration from code
- Use environment variables for deployment-specific values
- Organize configuration by environment and service
- Document configuration options and their purposes
**Secrets Management**
- Never commit secrets to version control
- Use secure secret management systems
- Document secret requirements and setup
- Provide examples with placeholder values
## Integration with BMad Systems
### Memory Bank Integration
- projectContext.md references project structure decisions
- techContext.md documents technology and architectural choices
- systemPatterns.md captures organizational conventions
- All agents reference scaffolding preferences during initialization
### ADR Integration
- Create ADRs for significant scaffolding decisions
- Document rationale for organizational choices
- Reference scaffolding ADRs from project structure documentation
- Update ADRs when scaffolding patterns evolve
### Agent Workflow Integration
- All BMad agents understand standard directory structures
- Templates automatically create appropriate directory structures
- Workflows assume consistent organizational patterns
- Build systems work reliably with standard structures
### Development Process Integration
- Code reviews validate adherence to scaffolding standards
- Build processes work consistently across projects
- Deployment scripts make standard organizational assumptions
- Monitoring and observability integrate with standard patterns
## Advanced Patterns
### Monorepo Organization
```
/packages
/shared-ui/
/shared-utils/
/app-frontend/
/app-backend/
/mobile-app/
/tools
/build-tools/
/dev-tools/
/scripts/
/docs
/architecture/
/packages/
/deployment/
```
### Domain-Driven Design Integration
```
/src
/domains
/user/
/entities/
/services/
/repositories/
/controllers/
/order/
/entities/
/services/
/repositories/
/controllers/
/shared
/infrastructure/
/utilities/
```
### Plugin/Extension Architecture
```
/core
/src/
/tests/
/plugins
/auth-plugin/
/payment-plugin/
/analytics-plugin/
/extension-api
/interfaces/
/base-classes/
/utilities/
```
## Troubleshooting Common Issues
### Inconsistent Organization
**Symptoms**: Different parts of project follow different patterns
**Solutions**:
- Document and communicate organizational standards
- Perform regular organizational reviews
- Use linting tools to enforce patterns
- Include organization in code review criteria
### Deep Nesting
**Symptoms**: Excessive directory depth makes navigation difficult
**Solutions**:
- Flatten overly deep hierarchies
- Group related items at same level
- Use logical grouping rather than deep nesting
- Consider domain-based organization
### Unclear Purpose
**Symptoms**: Developers can't find files or understand organization
**Solutions**:
- Use more descriptive directory and file names
- Add README files explaining organization
- Create directory index files
- Provide organizational documentation
### Scaffolding Debt
**Symptoms**: Project structure becomes outdated or inconsistent over time
**Solutions**:
- Regular organizational reviews and updates
- Include scaffolding in technical debt assessments
- Planned refactoring of organizational patterns
- Update documentation and tooling as patterns evolve
## Scaffolding Templates
The BMad framework includes scaffolding templates and utilities:
- Standard directory structure generators
- Project initialization scripts
- Organizational linting rules
- Documentation templates for common structures
These tools ensure that new projects start with appropriate scaffolding and existing projects can migrate to standard patterns efficiently.
## Related Documentation
- [Memory Bank Guide](memory-bank-guide.md) - Persistent context management
- [ADR Guide](adr-guide.md) - Architecture decision documentation
- [Core Architecture](core-architecture.md) - Technical framework details
- [User Guide](../bmad-core/user-guide.md) - Complete BMad workflow documentation

7
docs/versions.md
View File

@ -16,6 +16,13 @@ Guiding Principles of V4:
- Helpers for installers and web builders that will work with any OS and IDE easily
- Align all agents to be the same for IDE and Web, without losing the power of the web versions, or the leanness of the files in the IDE to reduce context
- Further improvements to the two most important agents - the SM and DEV
- Memory Bank pattern for persistent AI context across sessions
- Architecture Decision Records (ADRs) for tracking technical decisions
- Development Journal system for session documentation
- Project scaffolding preferences for standardized directory structures
- Enhanced agent capabilities with comprehensive commit and PR workflows
- Sprint review and retrospective tasks
- Session kickoff protocol for proper initialization
## V3