From 035a936f2e8ba6dba1add114f82dbb592ba412db Mon Sep 17 00:00:00 2001 From: Peet Stander <62140524+PMLS3@users.noreply.github.com> Date: Thu, 5 Jun 2025 13:48:38 +0200 Subject: [PATCH] feat: Enhance agent capabilities with new commands and update documentation for BMAD standards --- .augment-guidelines | 5 + .github/copilot-instructions.md | 5 + .gitignore | 3 + bmad-agent/commands.md | 253 +++++++++++++++++- bmad-agent/personas/dev.ide.md | 4 +- .../tasks/agent-knowledge-update-task.md | 11 +- bmad-agent/tasks/create-knowledge-files.js | 4 +- bmad-agent/tasks/create-next-story-task.md | 2 +- bmad-agent/templates/doc-sharding-tmpl.md | 6 +- .../templates/knowledge-version-tmpl.md | 10 +- bmad-agent/templates/story-tmpl.md | 4 +- 11 files changed, 289 insertions(+), 18 deletions(-) diff --git a/.augment-guidelines b/.augment-guidelines index 39de1d42..23d866e4 100644 --- a/.augment-guidelines +++ b/.augment-guidelines @@ -59,6 +59,11 @@ Immediate Action Commands: - `*exit`: Immediately abandon the current agent or party-mode and drop to base BMad Orchestrator - `*tasks`: List the tasks available to the current agent, along with a description. - `*party`: This enters group chat with all available agents. You will roleplay all agent personas as necessary +- `*mpcs`: List available Machine-Powered Capabilities for the current agent +- `*perplexity [query]`: Execute a web search using Perplexity (if available for current agent) +- `*github [query]`: Search code repositories on GitHub (if available for current agent) +- `*firecrawl [query]`: Perform advanced data analysis with Firecrawl (if available for current agent) +- `*dalle [prompt]`: Generate an image using DALL-E (if available for current agent) ## Global Output Requirements Apply to All Personas diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 39de1d42..23d866e4 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -59,6 +59,11 @@ Immediate Action Commands: - `*exit`: Immediately abandon the current agent or party-mode and drop to base BMad Orchestrator - `*tasks`: List the tasks available to the current agent, along with a description. - `*party`: This enters group chat with all available agents. You will roleplay all agent personas as necessary +- `*mpcs`: List available Machine-Powered Capabilities for the current agent +- `*perplexity [query]`: Execute a web search using Perplexity (if available for current agent) +- `*github [query]`: Search code repositories on GitHub (if available for current agent) +- `*firecrawl [query]`: Perform advanced data analysis with Firecrawl (if available for current agent) +- `*dalle [prompt]`: Generate an image using DALL-E (if available for current agent) ## Global Output Requirements Apply to All Personas diff --git a/.gitignore b/.gitignore index 324593f8..5014eb64 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,6 @@ build/ # VSCode settings .vscode/ + +.github/ +CLAUDE.md \ No newline at end of file diff --git a/bmad-agent/commands.md b/bmad-agent/commands.md index aa374436..ab51350f 100644 --- a/bmad-agent/commands.md +++ b/bmad-agent/commands.md @@ -84,11 +84,100 @@ 4. `*Dev` - Implement the module stories 5. `*QA create-test-plan` - Create test plan for the new module +## File Organization Guidelines + +### Directory Structure Overview + +The BMAD Method uses a **hybrid file organization system** that evolved from earlier versions: + +| Directory | Purpose | Contents | Auto-Generated | +|-----------|---------|----------|----------------| +| `docs/` | **Human Deliverables** | Project Briefs, PRDs, Architecture docs, Stories, API docs | ❌ Manual | +| `.ai/` | **Agent Knowledge & Logs** | Project context, tech stack, data models, agent logs | ✅ Auto-created | +| `bmad-agent/` | **BMAD System Files** | Personas, tasks, templates, configuration | ❌ Manual | + +### What Goes Where + +**`docs/` Directory - Project Documentation:** +- Project Briefs (from Analyst) +- Product Requirements Documents (from PM) +- Architecture Documents (from Architect) +- UX/UI Specifications (from Design Architect) +- User Stories (in `docs/stories/`) +- API Reference documentation +- Sharded documents (broken down from large docs) + +### Standard File Naming Convention + +**All BMAD Method core documents MUST use lowercase filenames with hyphens:** + +| Document Type | Standard Filename | Agent Responsible | +|---------------|-------------------|-------------------| +| Project Brief | `project-brief.md` | Analyst | +| Product Requirements | `prd.md` | PM | +| Architecture | `architecture.md` | Architect | +| Frontend Architecture | `frontend-architecture.md` | Design Architect | +| UX/UI Specification | `uxui-spec.md` | Design Architect | +| Technology Stack | `tech-stack.md` | Architect | +| Data Models | `data-models.md` | Architect/Data Scientist | +| API Reference | `api-reference.md` | Architect | +| Deployment Guide | `deployment-guide.md` | DevOps | +| Test Plan | `test-plan.md` | QA | +| User Stories | `{epic-num}.{story-num}.story.md` | SM | +| Epic Files | `epic-{id}.md` | SM (from sharding) | + +### Date Generation Standards + +**All agents MUST use actual current dates, not placeholders:** +- Use format: `YYYY-MM-DD` for dates (e.g., `2024-01-15`) +- Use format: `YYYY-MM-DD HH:MM` for timestamps (e.g., `2024-01-15 14:30`) +- **NEVER use placeholders** like `{DATE}`, `[DATE]`, or `TBD` +- **ALWAYS generate actual current date** when creating documents + +**`.ai/` Directory - Agent Intelligence:** +- `project-context.md` - Project goals, terminology, domain knowledge +- `tech-stack.md` - Technologies, frameworks, patterns in use +- `data-models.md` - Data structures and analytics approaches +- `deployment-info.md` - Infrastructure and deployment details +- `knowledge-versions.md` - Version history of knowledge updates +- Agent working files (test-issues.md, deployment-history.md, etc.) + +### System Evolution Note + +**If your project only has `docs/`:** You're likely using an older configuration or haven't run the knowledge update task yet. The current system automatically creates and manages the `.ai/` directory when you run `*BMAD Update Agent Knowledge`. + ### Updating Agent Knowledge +#### When to Run Knowledge Updates + +**Required Updates (Major Phases):** +- After Project Brief completion +- After PRD creation or major updates +- After Architecture design or significant changes +- After adding new modules or major features +- After tech stack changes + +**Frequency Guidelines:** +- **New Projects**: 3-4 times during initial setup +- **Active Development**: Every 2-4 weeks or when major changes occur +- **Mature Projects**: Monthly or when adding significant features + +**DON'T Update After:** +- Individual story completions +- Small bug fixes +- Routine development tasks +- Individual test runs + +#### Running the Update + 1. Complete a project phase (Brief, PRD, Architecture) 2. `*BMAD Update Agent Knowledge` - Extract and distribute knowledge -3. Verify knowledge files in `.ai/` directory +3. **Automatic Results:** + - Creates `.ai/` directory if it doesn't exist + - Generates knowledge files from your `docs/` content + - Updates agent customization strings + - Uses semantic versioning (Major.Minor.Patch) to track changes + - Agents automatically read from `.ai/` for project context ### Creating Custom Agents @@ -106,6 +195,168 @@ - [Task Name](task-file.md) ``` +## Common Scenarios + +### 1. Complete Project Initialization Flow +**Purpose:** Start a new project from scratch through to development + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Create Project Brief` | Brainstorm and research project concept | +| 2 | PM | `*PM Create PRD` | Create Product Requirements Document with epics and stories | +| 3 | Architect | `*Architect Create Architecture` | Design system architecture based on PRD | +| 4 | Design Architect | `*Design Architect Create Frontend Architecture` | Design UI/UX architecture (if applicable) | +| 5 | Design Architect | `*Design Architect Create UXUI Spec` | Create detailed UI/UX specifications | +| 6 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with project knowledge | +| 7 | PO | `*PO organize` | Organize and validate all documentation | +| 8 | SM | `*SM doc-shard` | Break down large documents into manageable pieces | +| 9 | SM | `*SM create` | Create first implementation story | +| 10 | Dev | `*Dev` | Implement the story | +| 11 | QA | `*QA create-test-plan` | Create test plan for the story | +| 12 | QA | `*QA run-tests` | Execute tests for the implementation | +| 13 | DevOps | `*DevOps deploy` | Deploy the implementation | + +**Special Considerations:** +- Run `*BMAD Update Agent Knowledge` after each major phase +- Consider using `*perplexity` during research phases +- For UI-heavy projects, add `*dalle` for mockup generation after step 5 + +### 2. Brownfield Project Takeover +**Purpose:** Integrate BMAD Method into an existing project + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Analyze Existing Project` | Document current state and challenges | +| 2 | PM | `*PM Reverse Engineer PRD` | Create PRD based on existing functionality | +| 3 | Architect | `*Architect Document Current Architecture` | Map out existing architecture | +| 4 | SM | `*SM doc-shard` | Break down documentation into manageable pieces | +| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with project knowledge | +| 6 | PO | `*PO audit` | Identify documentation gaps | +| 7 | SM | `*SM create` | Create first enhancement story | +| 8 | Dev | `*Dev` | Implement the enhancement | + +**Special Considerations:** +- Use `*github` to search for patterns in the existing codebase +- Consider `*SM pivot` if significant course correction is needed +- Create a project structure document if one doesn't exist + +### 3. Adding New Module to Existing Project +**Purpose:** Extend a project beyond original PRD scope + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Research Module Requirements` | Research requirements for new module | +| 2 | PM | `*PM update-prd {module-name}` | Update PRD with new module requirements | +| 3 | Architect | `*Architect module-design {module-name}` | Design new module architecture | +| 4 | Design Architect | `*Design Architect Update Frontend Architecture` | Update UI/UX for new module (if applicable) | +| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update all agents with new module knowledge | +| 6 | SM | `*SM doc-shard` | Break down module documentation | +| 7 | SM | `*SM create` | Create first module implementation story | +| 8 | Dev | `*Dev` | Implement the module story | +| 9 | QA | `*QA create-test-plan` | Create test plan for the module | +| 10 | DevOps | `*DevOps infra-plan` | Plan infrastructure changes for new module | + +**Special Considerations:** +- Ensure integration points with existing modules are clearly defined +- Consider impact on existing architecture and data models +- Update knowledge files to include new module terminology + +### 4. UI Redesign Workflow +**Purpose:** Implement frontend changes with minimal backend modifications + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Design Architect | `*Design Architect Analyze Current UI` | Document current UI state and issues | +| 2 | PM | `*PM Create UI PRD` | Create UI-focused requirements document | +| 3 | Design Architect | `*Design Architect Create UXUI Spec` | Create detailed UI/UX specifications | +| 4 | Design Architect | `*Design Architect Create Frontend Architecture` | Update frontend architecture | +| 5 | Design Architect | `*Design Architect Create AI Frontend Prompt` | Create prompt for AI UI generation | +| 6 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with UI knowledge | +| 7 | SM | `*SM create` | Create UI implementation story | +| 8 | Dev | `*Dev` | Implement UI changes | +| 9 | QA | `*QA create-test-plan` | Create UI-focused test plan | + +**Special Considerations:** +- Use `*dalle` for UI mockup generation +- Focus on component-based architecture for reusability +- Consider accessibility requirements in specifications + +### 5. API Integration Project +**Purpose:** Integrate external APIs into an existing project + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Research API` | Research API capabilities and limitations | +| 2 | PM | `*PM Create API Integration PRD` | Document API integration requirements | +| 3 | Architect | `*Architect Design API Integration` | Design integration architecture | +| 4 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with API knowledge | +| 5 | SM | `*SM create` | Create API integration story | +| 6 | Dev | `*Dev` | Implement API integration | +| 7 | QA | `*QA create-test-plan` | Create API testing plan | +| 8 | DevOps | `*DevOps update-env` | Update environment with API credentials | + +**Special Considerations:** +- Use `*perplexity` to research API best practices +- Create mock API responses for testing +- Document rate limits and fallback strategies + +### 6. Database Migration Project +**Purpose:** Migrate from one database technology to another + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Research Database Options` | Research database technologies | +| 2 | Architect | `*Architect Design Database Migration` | Design migration architecture | +| 3 | Data Scientist | `*Data Scientist analyze` | Analyze data patterns and migration challenges | +| 4 | PM | `*PM Create Migration PRD` | Document migration requirements and phases | +| 5 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with database knowledge | +| 6 | SM | `*SM create` | Create database migration story | +| 7 | Dev | `*Dev` | Implement migration code | +| 8 | QA | `*QA create-test-plan` | Create data validation test plan | +| 9 | DevOps | `*DevOps infra-plan` | Plan infrastructure changes for new database | + +**Special Considerations:** +- Create data validation strategies for before and after migration +- Plan for rollback scenarios +- Consider performance testing with representative data volumes + +### 7. Performance Optimization Project +**Purpose:** Improve performance of an existing application + +| Step | Agent | Command | Description | +|------|-------|---------|-------------| +| 1 | Analyst | `*Analyst Performance Analysis` | Identify performance bottlenecks | +| 2 | Architect | `*Architect Performance Optimization Plan` | Design optimization strategy | +| 3 | PM | `*PM Create Optimization PRD` | Document optimization requirements | +| 4 | BMAD | `*BMAD Update Agent Knowledge` | Update agents with performance knowledge | +| 5 | SM | `*SM create` | Create optimization story | +| 6 | Dev | `*Dev` | Implement optimizations | +| 7 | QA | `*QA create-performance-test-plan` | Create performance test plan | +| 8 | Data Scientist | `*Data Scientist analyze-metrics` | Analyze performance metrics | + +**Special Considerations:** +- Establish performance baselines before changes +- Use `*github` to research optimization patterns +- Consider both frontend and backend optimizations + +### Best Practices for Scenario Execution + +**Documentation First:** Complete documentation phases before implementation + +**Knowledge Updates:** Run `*BMAD Update Agent Knowledge` after each major phase + +**Incremental Implementation:** Create and implement stories one at a time + +**Regular Testing:** Integrate QA testing throughout the process + +**Feedback Loops:** Use `*SM pivot` if significant course correction is needed + +**MPC Integration:** Leverage appropriate MPCs for each scenario: +- Research: `*perplexity` +- Code patterns: `*github` +- Data analysis: `*firecrawl` +- UI visualization: `*dalle` + ## Documentation Management | Command | Description | diff --git a/bmad-agent/personas/dev.ide.md b/bmad-agent/personas/dev.ide.md index ece96a86..241c1120 100644 --- a/bmad-agent/personas/dev.ide.md +++ b/bmad-agent/personas/dev.ide.md @@ -17,7 +17,7 @@ MUST review and use: -- `Assigned Story File`: `docs/stories/{epicNumber}.{storyNumber}.story.md` +- `Assigned Story File`: `docs/stories/{epic-num}.{story-num}.story.md` (BMAD standard naming) - `Project Structure`: `docs/project-structure.md` - `Operational Guidelines`: `docs/operational-guidelines.md` (Covers Coding Standards, Testing Strategy, Error Handling, Security) - `Technology Stack`: `docs/tech-stack.md` @@ -47,7 +47,7 @@ MUST review and use: a. HALT feature implementation concerning the dependency. b. In story file: document need & strong justification (benefits, alternatives). c. Ask user for explicit approval for this dependency. - d. ONLY upon user's explicit approval (e.g., "User approved X on YYYY-MM-DD"), document it in the story file and proceed. + d. ONLY upon user's explicit approval (e.g., "User approved X on [current date in YYYY-MM-DD format]"), document it in the story file and proceed. - **Debugging Protocol:** - For temporary debug code (e.g., extensive logging): a. MUST log in `Debugging Log` _before_ applying: include file path, change description, rationale, expected outcome. Mark as 'Temp Debug for Story X.Y'. diff --git a/bmad-agent/tasks/agent-knowledge-update-task.md b/bmad-agent/tasks/agent-knowledge-update-task.md index a8b94e80..4b567449 100644 --- a/bmad-agent/tasks/agent-knowledge-update-task.md +++ b/bmad-agent/tasks/agent-knowledge-update-task.md @@ -4,11 +4,11 @@ Extract key project information from existing documentation and update agent knowledge files and customization strings to make all BMAD agents more effective with project-specific context. ## Input Required -- Project Brief (if available) -- PRD (if available) -- Architecture document (if available) -- Tech Stack document (if available) -- Other project artifacts +- Project Brief (`docs/project-brief.md` if available) +- PRD (`docs/prd.md` if available) +- Architecture document (`docs/architecture.md` if available) +- Tech Stack document (`docs/tech-stack.md` if available) +- Other project artifacts following BMAD naming standards ## Steps @@ -54,6 +54,7 @@ Extract key project information from existing documentation and update agent kno 5. **Update Knowledge Version History** - Create or update `.ai/knowledge-versions.md` using the template at `templates/knowledge-version-tmpl.md` + - **CRITICAL: Use actual current date in YYYY-MM-DD format, never leave date placeholders** - Increment version number appropriately based on change significance: - Major: Significant changes to project direction or core architecture - Minor: New features or components added to existing architecture diff --git a/bmad-agent/tasks/create-knowledge-files.js b/bmad-agent/tasks/create-knowledge-files.js index 67bb49e1..0baf7f30 100755 --- a/bmad-agent/tasks/create-knowledge-files.js +++ b/bmad-agent/tasks/create-knowledge-files.js @@ -306,7 +306,9 @@ function main() { ## Additional Resources - Project documentation is located in the \`docs/\` directory -- Architecture diagrams can be found in \`docs/architecture.md\` +- Architecture diagrams can be found in \`docs/architecture.md\` (BMAD standard naming) +- Project brief is in \`docs/project-brief.md\` +- PRD is in \`docs/prd.md\` `; updateKnowledgeFile(PROJECT_CONTEXT_PATH, projectContextContent); diff --git a/bmad-agent/tasks/create-next-story-task.md b/bmad-agent/tasks/create-next-story-task.md index 4cc60ad0..c2a32079 100644 --- a/bmad-agent/tasks/create-next-story-task.md +++ b/bmad-agent/tasks/create-next-story-task.md @@ -82,7 +82,7 @@ To identify the next logical story based on project progress and epic definition ### 5. Populate Story Template with Full Context -- Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`. +- Create a new story file: `docs/stories/{epic-num}.{story-num}.story.md` (using BMAD standard naming with hyphens). - Use the Story Template to structure the file. - Fill in: - Story `{EpicNum}.{StoryNum}: {Short Title Copied from Epic File}` diff --git a/bmad-agent/templates/doc-sharding-tmpl.md b/bmad-agent/templates/doc-sharding-tmpl.md index fae32ddf..93e24d12 100644 --- a/bmad-agent/templates/doc-sharding-tmpl.md +++ b/bmad-agent/templates/doc-sharding-tmpl.md @@ -6,7 +6,7 @@ This plan directs the agent on how to break down large source documents into sma ## 1. Source Document: PRD (Project Requirements Document) -- **Note to Agent:** Confirm the exact filename of the PRD with the user (e.g., `PRD.md`, `ProjectRequirements.md`, `prdx.y.z.md`). +- **Note to Agent:** The PRD should be named `prd.md` per BMAD naming standards. If using a different name, confirm with user and suggest renaming to standard format. ### 1.1. Epic Granulation @@ -19,7 +19,7 @@ This plan directs the agent on how to break down large source documents into sma ## 2. Source Document: Main Architecture Document -- **Note to Agent:** Confirm the exact filename with the user (e.g., `architecture.md`, `SystemArchitecture.md`). +- **Note to Agent:** The Architecture document should be named `architecture.md` per BMAD naming standards. If using a different name, confirm with user and suggest renaming to standard format. ### 2.1. Core Architecture Granules @@ -65,7 +65,7 @@ This plan directs the agent on how to break down large source documents into sma ## 3. Source Document(s): Front-End Specific Documentation -- **Note to Agent:** Confirm filenames with the user (e.g., `front-end-architecture.md`, `front-end-spec.md`, `ui-guidelines.md`). Multiple FE documents might exist. +- **Note to Agent:** Frontend documents should follow BMAD naming standards: `frontend-architecture.md`, `uxui-spec.md`. If using different names, confirm with user and suggest renaming to standard format. ### 3.1. Front-End Granules diff --git a/bmad-agent/templates/knowledge-version-tmpl.md b/bmad-agent/templates/knowledge-version-tmpl.md index 342fae79..f276272e 100644 --- a/bmad-agent/templates/knowledge-version-tmpl.md +++ b/bmad-agent/templates/knowledge-version-tmpl.md @@ -1,10 +1,12 @@ # Knowledge Version History ## Current Version: {VERSION_NUMBER} -**Last Updated:** {DATE} +**Last Updated:** [AGENT: Use current date in YYYY-MM-DD format] **Updated By:** {AGENT_NAME} **Change Type:** {MAJOR|MINOR|PATCH} +**IMPORTANT:** When using this template, replace {DATE} placeholders with actual current dates in YYYY-MM-DD format. Never leave date placeholders in final documents. + ## Change Summary {BRIEF_DESCRIPTION_OF_CHANGES} @@ -40,6 +42,6 @@ | Version | Date | Updated By | Change Type | Summary | |---------|------|------------|-------------|---------| -| {VERSION_NUMBER} | {DATE} | {AGENT_NAME} | {CHANGE_TYPE} | {BRIEF_SUMMARY} | -| {PREVIOUS_VERSION} | {DATE} | {AGENT_NAME} | {CHANGE_TYPE} | {BRIEF_SUMMARY} | -| {INITIAL_VERSION} | {DATE} | {AGENT_NAME} | Initial | Initial knowledge base creation | \ No newline at end of file +| {VERSION_NUMBER} | [AGENT: Current date YYYY-MM-DD] | {AGENT_NAME} | {CHANGE_TYPE} | {BRIEF_SUMMARY} | +| {PREVIOUS_VERSION} | [AGENT: Previous date YYYY-MM-DD] | {AGENT_NAME} | {CHANGE_TYPE} | {BRIEF_SUMMARY} | +| {INITIAL_VERSION} | [AGENT: Initial date YYYY-MM-DD] | {AGENT_NAME} | Initial | Initial knowledge base creation | \ No newline at end of file diff --git a/bmad-agent/templates/story-tmpl.md b/bmad-agent/templates/story-tmpl.md index 8cfe7c57..889787fb 100644 --- a/bmad-agent/templates/story-tmpl.md +++ b/bmad-agent/templates/story-tmpl.md @@ -1,4 +1,6 @@ -# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File} +# Story {epic-num}.{story-num}: {Short Title Copied from Epic File} + +**IMPORTANT:** Use BMAD standard naming: {epic-num}.{story-num} with hyphens, not {EpicNum}.{StoryNum} ## Status: { Draft | Approved | InProgress | Review | Done }