diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 00000000..b7dd030d --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,36 @@ +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json + +language: "en-US" +early_access: true +reviews: + profile: chill + high_level_summary: true + request_changes_workflow: false + review_status: true + collapse_walkthrough: false + poem: false + auto_review: + enabled: false # must be manually triggered with @coderabbit review + drafts: true # Can review drafts. Since it's manually triggered, it's fine. + auto_incremental_review: false # always review the whole PR, not just new commits + base_branches: + - main + path_filters: + - "!**/node_modules/**" + path_instructions: + - path: "**/*" + instructions: | + Focus on inconsistencies, contradictions, edge cases and serious issues. + Avoid commenting on minor issues such as linting, formatting and style issues. + When providing code suggestions, use GitHub's suggestion format: + ```suggestion + + ``` + - path: "**/*.js" + instructions: | + CLI tooling code. Check for: missing error handling on fs operations, + path.join vs string concatenation, proper cleanup in error paths. + Flag any process.exit() without error message. +chat: + auto_reply: true # Response to mentions in comments, a la @coderabbit review + diff --git a/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md similarity index 94% rename from CODE_OF_CONDUCT.md rename to .github/CODE_OF_CONDUCT.md index 27b04993..843ec9ee 100644 --- a/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -60,7 +60,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -the official BMAD Discord server (https://discord.com/invite/gk8jAdXWmj) - DM a moderator or flag a post. +the official BMAD Discord server () - DM a moderator or flag a post. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the @@ -116,7 +116,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +. Translations are available at +. diff --git a/.github/ISSUE_TEMPLATE/idea_submission.md b/.github/ISSUE_TEMPLATE/idea_submission.md index aec346ae..6ab26d5b 100644 --- a/.github/ISSUE_TEMPLATE/idea_submission.md +++ b/.github/ISSUE_TEMPLATE/idea_submission.md @@ -8,7 +8,7 @@ assignees: '' # Idea: [Replace with a clear, actionable title] -### PASS Framework +## PASS Framework **P**roblem: diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml index fc750b62..8111ca44 100644 --- a/.github/workflows/quality.yaml +++ b/.github/workflows/quality.yaml @@ -3,6 +3,7 @@ name: Quality & Validation # Runs comprehensive quality checks on all PRs: # - Prettier (formatting) # - ESLint (linting) +# - markdownlint (markdown quality) # - Schema validation (YAML structure) # - Agent schema tests (fixture-based validation) # - Installation component tests (compilation) @@ -50,6 +51,24 @@ jobs: - name: ESLint run: npm run lint + markdownlint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version-file: ".nvmrc" + cache: "npm" + + - name: Install dependencies + run: npm ci + + - name: markdownlint + run: npm run lint:md + validate: runs-on: ubuntu-latest steps: diff --git a/.gitignore b/.gitignore index 47a82e6e..8a9137a1 100644 --- a/.gitignore +++ b/.gitignore @@ -62,7 +62,7 @@ src/modules/bmm/sub-modules/ src/modules/bmb/sub-modules/ src/modules/cis/sub-modules/ src/modules/bmgd/sub-modules/ - +shared-modules z*/ .bmad @@ -73,3 +73,5 @@ z*/ .agentvibes/ .kiro/ .roo + +bmad-custom-src/ \ No newline at end of file diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 00000000..84d44c7d --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,42 @@ +# markdownlint-cli2 configuration +# https://github.com/DavidAnson/markdownlint-cli2 + +ignores: + - node_modules/** + - test/fixtures/** + - CODE_OF_CONDUCT.md + - .bmad/** + - .bmad*/** + - .agent/** + - .claude/** + - .roo/** + - .codex/** + - .agentvibes/** + - .kiro/** + - sample-project/** + - test-project-install/** + - z*/** + +# Rule configuration +config: + # Disable all rules by default + default: false + + # Heading levels should increment by one (h1 -> h2 -> h3, not h1 -> h3) + MD001: true + + # Duplicate sibling headings (same heading text at same level under same parent) + MD024: + siblings_only: true + + # Trailing commas in headings (likely typos) + MD026: + punctuation: "," + + # Bare URLs - may not render as links in all parsers + # Should use or [text](url) format + MD034: true + + # Spaces inside emphasis markers - breaks rendering + # e.g., "* text *" won't render as emphasis + MD037: true diff --git a/CHANGELOG.md b/CHANGELOG.md index f39d928c..5bb4bd3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,164 +1,199 @@ # Changelog +## [6.0.0-alpha.15] + +**Release: December 7, 2025** + +### ๐Ÿ”ง Module Installation Standardization + +**Unified Module Configuration:** + +- **module.yaml Standard**: All modules now use `module.yaml` instead of `_module-installer/install-config.yaml` for consistent configuration (BREAKING CHANGE) +- **Universal Installer**: Both core and custom modules now use the same installer with consistent behavior +- **Streamlined Module Creation**: Module builder templates updated to use new module.yaml standard +- **Enhanced Module Discovery**: Improved module caching and discovery mechanisms + +**Custom Content Installation Revolution:** + +- **Interactive Custom Content Search**: Installer now proactively asks if you have custom content to install +- **Flexible Location Specification**: Users can indicate custom content location during installation +- **Improved Custom Module Handler**: Enhanced error handling and debug output for custom installations +- **Comprehensive Documentation**: New custom-content-installation.md guide (245 lines) replacing custom-agent-installation.md + +### ๐Ÿค– Code Review Integration Expansion + +**AI Review Tools:** + +- **CodeRabbit AI Integration**: Added .coderabbit.yaml configuration for automated code review +- **Raven's Verdict PR Review Tool**: New PR review automation tool (297 lines of documentation) +- **Review Path Configuration**: Proper exclusion patterns for node_modules and generated files +- **Review Documentation**: Comprehensive usage guidance and skip conditions for PRs + +### ๐Ÿ“š Documentation Improvements + +**Documentation Restructuring:** + +- **Code of Conduct**: Moved to .github/ folder following GitHub standards +- **Gem Creation Link**: Updated to point to Gemini Gem manager instead of deprecated interface +- **Example Custom Content**: Improved README files and disabled example modules to prevent accidental installation +- **Custom Module Documentation**: Enhanced module installation guides with new YAML structure + +### ๐Ÿงน Cleanup & Optimization + +**Memory Management:** + +- **Removed Hardcoded .bmad Folders**: Cleaned up demo content to use configurable paths +- **Sidecar File Cleanup**: Removed old .bmad-user-memory folders from wellness modules +- **Example Content Organization**: Better organization of example-custom-content directory + +**Installer Improvements:** + +- **Debug Output Enhancement**: Added informative debug output when installer encounters errors +- **Custom Module Caching**: Improved caching mechanism for custom module installations +- **Consistent Behavior**: All modules now behave consistently regardless of custom or core status + +### ๐Ÿ“Š Statistics + +- **77 files changed** with 2,852 additions and 607 deletions +- **15 commits** since alpha.14 + +### โš ๏ธ Breaking Changes + +1. **module.yaml Configuration**: All modules must now use `module.yaml` instead of `_module-installer/install-config.yaml` + - Core modules updated automatically + - Custom modules will need to rename their configuration file + - Module builder templates generate new format + +### ๐Ÿ“ฆ New Dependencies + +- No new dependencies added in this release + +--- + +## [6.0.0-alpha.14] + +**Release: December 7, 2025** + +### ๐Ÿ”ง Installation & Configuration Revolution + +**Custom Module Installation Overhaul:** + +- **Simple custom.yaml Installation**: Custom agents and workflows can now be installed with a single YAML file +- **IDE Configuration Preservation**: Upgrades will no longer delete custom modules, agents, and workflows from IDE configuration +- **Removed Legacy agent-install Command**: Streamlined installation process (BREAKING CHANGE) +- **Sidecar File Retention**: Custom sidecar files are preserved during updates +- **Flexible Agent Sidecar Locations**: Fully configurable via config options instead of hardcoded paths + +**Module Discovery System Transformation:** + +- **Recursive Agent Discovery**: Deep scanning for agents across entire project structure +- **Enhanced Manifest Generation**: Comprehensive scanning of all installed modules +- **Nested Agent Support**: Fixed nested agents appearing in CLI commands +- **Module Reinstall Fix**: Prevented modules from showing as obsolete during reinstall + +### ๐Ÿ—๏ธ Advanced Builder Features + +**Workflow Builder Evolution:** + +- **Continuable Workflows**: Create workflows with sophisticated branching and continuation logic +- **Template LOD Options**: Level of Detail output options for flexible workflow generation +- **Step-Based Architecture**: Complete conversion to granular step-file system +- **Enhanced Creation Process**: Improved workflow creation with better template handling + +**Module Builder Revolution:** + +- **11-Step Module Creation**: Comprehensive step-by-step module generation process +- **Production-Ready Templates**: Complete templates for agents, installers, and workflow plans +- **Built-in Validation System**: Ensures module quality and BMad Core compliance +- **Professional Documentation**: Auto-generated module documentation and structure + +### ๐Ÿš€ BMad Method (BMM) Enhancements + +**Workflow Improvements:** + +- **Brownfield PRD Support**: Enhanced PRD workflow for existing project integration +- **Sprint Status Command**: New workflow for tracking development progress +- **Step-Based Format**: Improved continue functionality across all workflows +- **Quick-Spec-Flow Documentation**: Rapid development specification flows + +**Documentation Revolution:** + +- **Comprehensive Troubleshooting Guide**: 680-line detailed troubleshooting documentation +- **Quality Check Integration**: Added markdownlint-cli2 for markdown quality assurance +- **Enhanced Test Architecture**: Improved CI/CD templates and testing workflows + +### ๐ŸŒŸ New Features & Integrations + +**Kiro-Cli Installer:** + +- **Intelligent Routing**: Smart routing to quick-dev workflow +- **BMad Core Compliance**: Full compliance with BMad standards + +**Discord Notifications:** + +- **Compact Format**: Streamlined plain-text notifications +- **Bug Fixes**: Resolved notification delivery issues + +**Example Mental Wellness Module (MWM):** + +- **Complete Module Example**: Demonstrates advanced module patterns +- **Multiple Agents**: CBT Coach, Crisis Navigator, Meditation Guide, Wellness Companion +- **Workflow Showcase**: Crisis support, daily check-in, meditation, journaling workflows + +### ๐Ÿ› Bug Fixes & Optimizations + +- Fixed version reading from package.json instead of hardcoded fallback +- Removed hardcoded years from WebSearch queries +- Removed broken build caching mechanism +- Fixed hardcoded 'bmad' prefix from files-manifest.csv paths +- Enhanced TTS injection summary with tracking and documentation +- Fixed CI nvmrc configuration issues + +### ๐Ÿ“Š Statistics + +- **335 files changed** with 17,161 additions and 8,204 deletions +- **46 commits** since alpha.13 + +### โš ๏ธ Breaking Changes + +1. **Removed agent-install Command**: Migrate to new custom.yaml installation system +2. **Agent Sidecar Configuration**: Now requires explicit config instead of hardcoded paths + +### ๐Ÿ“ฆ New Dependencies + +- `markdownlint-cli2: ^0.19.1` - Professional markdown linting + +--- + ## [6.0.0-alpha.13] **Release: November 30, 2025** ### ๐Ÿ—๏ธ Revolutionary Workflow Architecture -**Granular Step-File Workflow System (NEW in alpha.13):** - -- **Multi-Menu Support**: Workflows now support granular step-file architecture with dynamic menu generation -- **Sharded Workflows**: Complete conversion of Phase 1 and 2 workflows to stepwise sharded architecture -- **Improved Performance**: Reduced file loading times and eliminated time-based estimates throughout -- **Workflow Builder**: New dedicated workflow builder for creating stepwise workflows -- **PRD Workflow**: First completely reworked sharded workflow resolving Sonnet compatibility issues - -**Core Workflow Transformations:** - -- Phase 1 and 2 workflows completely converted to sharded step-flow architecture -- UX Design workflow converted to sharded step workflow -- Brainstorming, Research, and Party Mode updated to use sharded step-flow workflows -- Architecture workflows enhanced with step sharding and performance improvements - -### ๐ŸŽฏ Code Review & Development Enhancement - -**Advanced Code Review System:** - -- **Adversarial Code Review**: Quick-dev workflow now recommends adversarial review approach for higher quality -- **Multi-LLM Strategy**: Dev-story workflow recommends different LLM models for code review tasks -- **Agent Compiler Optimization**: Complete handler cleanup and performance improvements +- **Step-File System**: Complete conversion to granular step-file architecture with dynamic menu generation +- **Phase 4 Transformation**: Simplified architecture with sprint planning integration (Jira, Linear, Trello) +- **Performance Improvements**: Eliminated time-based estimates, reduced file loading times +- **Legacy Cleanup**: Removed all deprecated workflows for cleaner system ### ๐Ÿค– Agent System Revolution -**Universal Custom Agent Support:** +- **Universal Custom Agent Support**: Extended to ALL IDEs including Antigravity and Rovo Dev +- **Agent Creation Workflow**: Enhanced with better documentation and parameter clarity +- **Multi-Source Discovery**: Agents now check multiple source locations for better discovery +- **GitHub Migration**: Integration moved from chatmodes to agents folder -- **Complete IDE Coverage**: Custom agent support extended to ALL remaining IDEs -- **Antigravity IDE Integration**: Added custom agent support with proper gitignore configuration -- **Multiple Source Locations**: Compile agents now checks multiple source locations for better discovery -- **Persona Name Display**: Fixed proper persona names display in custom agent manifests -- **New IDE Support**: Added support for Rovo Dev IDE +### ๐Ÿงช Testing Infrastructure -**Agent Creation & Management:** - -- **Improved Creation Workflow**: Enhanced agent creation workflow with better documentation -- **Parameter Clarity**: Renamed agent-install parameters for better understanding -- **Menu Organization**: BMad Agents menu items logically ordered with optional/recommended/required tags -- **GitHub Migration**: GitHub integration now uses agents folder instead of chatmodes - -### ๐Ÿ”ง Phase 4 & Sprint Evolution - -**Complete Phase 4 Transformation:** - -- **Simplified Architecture**: Phase 4 workflows completely transformed - simpler, faster, better results -- **Sprint Planning Integration**: Unified sprint planning with placeholders for Jira, Linear, and Trello integration -- **Status Management**: Better status loading and updating for Phase 4 artifacts -- **Workflow Reduction**: Phase 4 streamlined to single sprint planning item with clear validation -- **Dynamic Workflows**: All Level 1-3 workflows now dynamically suggest next steps based on context - -### ๐Ÿงช Testing Infrastructure Expansion - -**Playwright Utils Integration:** - -- Test Architect now supports `@seontechnologies/playwright-utils` integration -- Installation prompt with `use_playwright_utils` configuration flag -- 11 comprehensive knowledge fragments covering ALL utilities -- Adaptive workflow recommendations across 6 testing workflows -- Production-ready utilities from SEON Technologies integrated with TEA patterns - -**Testing Environment:** - -- **Web Bundle Support**: Enabled web bundles for test and development environments -- **Test Architecture**: Enhanced test design for architecture level (Phase 3) testing - -### ๐Ÿ“ฆ Installation & Configuration - -**Installer Improvements:** - -- **Cleanup Options**: Installer now allows cleanup of unneeded files during upgrades -- **Username Default**: Installer now defaults to system username for better UX -- **IDE Selection**: Added empty IDE selection warning and promoted Antigravity to recommended -- **NPM Vulnerabilities**: Resolved all npm vulnerabilities for enhanced security -- **Documentation Installation**: Made documentation installation optional to reduce footprint - -**Text-to-Speech from AgentVibes optional Integration:** - -- **TTS_INJECTION System**: Complete text-to-speech integration via injection system -- **Agent Vibes**: Enhanced with TTS capabilities for voice feedback - -### ๐Ÿ› ๏ธ Tool & IDE Updates - -**IDE Tool Enhancements:** - -- **GitHub Copilot**: Fixed tool names consistency across workflows -- **KiloCode Integration**: Gave kilocode tool proper access to bmad modes -- **Code Quality**: Added radix parameter to parseInt() calls for better reliability -- **Agent Menu Optimization**: Improved agent performance in Claude Code slash commands - -### ๐Ÿ“š Documentation & Standards - -**Documentation Cleanup:** - -- **Installation Guide**: Removed fluff and updated with npx support -- **Workflow Documentation**: Fixed documentation by removing non-existent workflows and Mermaid diagrams -- **Phase Numbering**: Fixed phase numbering consistency throughout documentation -- **Package References**: Corrected incorrect npm package references - -**Workflow Compliance:** - -- **Validation Checks**: Enhanced workflow validation checks for compliance -- **Product Brief**: Updated to comply with documented workflow standards -- **Status Integration**: Workflow-status can now call workflow-init for better integration - -### ๐Ÿ” Legacy Workflow Cleanup - -**Deprecated Workflows Removed:** - -- **Audit Workflow**: Completely removed audit workflow and all associated files -- **Convert Legacy**: Removed legacy conversion utilities -- **Create/Edit Workflows**: Removed old workflow creation and editing workflows -- **Clean Architecture**: Simplified workflow structure by removing deprecated legacy workflows - -### ๐Ÿ› Technical Fixes - -**System Improvements:** - -- **File Path Handling**: Fixed various file path issues across workflows -- **Manifest Updates**: Updated manifest to use agents folder structure -- **Web Bundle Configuration**: Fixed web bundle configurations for better compatibility -- **CSV Column Mismatch**: Fixed manifest schema upgrade issues +- **Playwright Utils Integration**: @seontechnologies/playwright-utils across all testing workflows +- **TTS Injection System**: Complete text-to-speech integration for voice feedback +- **Web Bundle Test Support**: Enabled web bundles for test environments ### โš ๏ธ Breaking Changes -**Workflow Architecture:** - -- All legacy workflows have been removed - ensure you're using the new stepwise sharded workflows -- Phase 4 completely restructured - update any automation expecting old Phase 4 structure -- Epic creation now requires architectural context (moved to Phase 3 in previous release) - -**Agent System:** - -- Custom agents now require proper compilation - use the new agent creation workflow -- GitHub integration moved from chatmodes to agents folder - update any references - -### ๐Ÿ“Š Impact Summary - -**New in alpha.13:** - -- **Stepwise Workflow Architecture**: Complete transformation of all workflows to granular step-file system -- **Universal Custom Agent Support**: Extended to ALL IDEs with improved creation workflow -- **Phase 4 Revolution**: Completely restructured with sprint planning integration -- **Legacy Cleanup**: Removed all deprecated workflows for cleaner system -- **Advanced Code Review**: New adversarial review approach with multi-LLM strategy -- **Text-to-Speech**: Full TTS integration for voice feedback -- **Testing Expansion**: Playwright utils integration across all testing workflows - -**Enhanced from alpha.12:** - -- **Performance**: Improved file loading and removed time-based estimates -- **Documentation**: Complete cleanup with accurate references -- **Installer**: Better UX with cleanup options and improved defaults -- **Agent System**: More reliable compilation and better persona handling +1. **Legacy Workflows Removed**: Migrate to new stepwise sharded workflows +2. **Phase 4 Restructured**: Update automation expecting old Phase 4 structure +3. **Agent Compilation Required**: Custom agents must use new creation workflow ## [6.0.0-alpha.12] @@ -172,313 +207,101 @@ **Release: November 18, 2025** -This alpha release introduces a complete agent installation system with the new `bmad agent-install` command, vastly improves the BMB agent builder capabilities with comprehensive documentation and reference agents, and refines diagram distribution to better align with BMad Method's core principle: **BMad agents mirror real agile teams**. +### ๐Ÿš€ Agent Installation Revolution -### ๐ŸŽจ Diagram Capabilities Refined and Distributed - -**Excalidraw Integration Evolution:** - -Building on the excellent Excalidraw integration introduced with the Frame Expert agent, we've refined how diagram capabilities are distributed across the BMad Method ecosystem to better reflect real agile team dynamics. - -**The Refinement:** - -- The valuable Excalidraw diagramming capabilities have been distributed to the agents who naturally create these artifacts in real teams -- **Architect**: System architecture diagrams, data flow visualizations -- **Product Manager**: Process flowcharts and workflow diagrams -- **UX Designer**: Wireframe creation capabilities -- **Tech Writer**: All diagram types for documentation needs -- **New CIS Agent**: presentation-master for specialized visual communication - -**Shared Infrastructure Enhancement:** - -- Excalidraw templates, component libraries, and validation patterns elevated to core resources -- Available to both BMM agents AND CIS presentation specialists -- Preserves all the excellent Excalidraw functionality while aligning with natural team roles - -### ๐Ÿš€ New Agent Installation System - -**Agent Installation Infrastructure (NEW in alpha.11):** - -- `bmad agent-install` CLI command with interactive persona customization -- **YAML โ†’ XML compilation engine** with smart handler injection -- Supports Simple (single file), Expert (with sidecars), and Module agents -- Handlebars-style template variable processing -- Automatic manifest tracking and IDE integration -- Source preservation in `_cfg/custom/agents/` for reinstallation - -**New Reference Agents Added:** - -- **commit-poet**: Poetic git commit message generator (Simple agent example) -- **journal-keeper**: Daily journaling agent with templates (Expert agent example) -- **security-engineer & trend-analyst**: Module agent examples with ecosystem integration - -**Critical Persona Field Guidance Added:** - -New documentation explaining how LLMs interpret persona fields for better agent quality: - -- **role** โ†’ "What knowledge, skills, and capabilities do I possess?" -- **identity** โ†’ "What background, experience, and context shape my responses?" -- **communication_style** โ†’ "What verbal patterns, word choice, and phrasing do I use?" -- **principles** โ†’ "What beliefs and operating philosophy drive my choices?" - -Key insight: `communication_style` should ONLY describe HOW the agent talks, not WHAT they do - -**BMM Agent Voice Enhancement:** - -All 9 existing BMM agents enhanced with distinct, memorable communication voices: - -- **Mary (analyst)**: "Treats analysis like a treasure hunt - excited by every clue" -- **John (PM)**: "Asks 'WHY?' relentlessly like a detective on a case" -- **Winston (architect)**: "Champions boring technology that actually works" -- **Amelia (dev)**: "Ultra-succinct. Speaks in file paths and AC IDs" -- **Sally (UX)**: "Paints pictures with words, telling user stories that make you FEEL" - -### ๐Ÿ”ง Edit-Agent Workflow Comprehensive Enhancement - -**Expert Agent Sidecar Support (NEW):** - -- Automatically detects and handles Expert agents with multiple files -- Loads and manages templates, data files, knowledge bases -- Smart sidecar analysis: maps references, finds orphans, validates paths -- 5 complete sidecar editing patterns with warm, educational feedback - -**7-Step Communication Style Refinement Pattern:** - -1. Diagnose current style with red flag word detection -2. Extract non-style content to working copy -3. Discover TRUE communication style through interview questions -4. Craft pure style using presets and reference agents -5. Show before/after transformation with full context -6. Validate against standards (zero red flags) -7. Confirm with user through dramatic reading - -**Unified Validation Checklist:** - -- Single source of truth: `agent-validation-checklist.md` (160 lines) -- Shared between create-agent and edit-agent workflows -- Comprehensive persona field separation validation -- Expert agent sidecar validation (9 specific checks) -- Common issues and fixes with real examples +- **bmad agent-install CLI**: Interactive agent installation with persona customization +- **4 Reference Agents**: commit-poet, journal-keeper, security-engineer, trend-analyst +- **Agent Compilation Engine**: YAML โ†’ XML with smart handler injection +- **60 Communication Presets**: Pure communication styles for agent personas ### ๐Ÿ“š BMB Agent Builder Enhancement -**Vastly Improved Agent Creation & Editing Capabilities:** +- **Complete Documentation Suite**: 7 new guides for agent architecture and creation +- **Expert Agent Sidecar Support**: Multi-file agents with templates and knowledge bases +- **Unified Validation**: 160-line checklist shared across workflows +- **BMM Agent Voices**: All 9 agents enhanced with distinct communication styles -- Create-agent and edit-agent workflows now have accurate, comprehensive documentation -- All context references updated and validated for consistency -- Workflows can now properly guide users through complex agent design decisions +### ๐ŸŽฏ Workflow Architecture Change -**New Agent Documentation Suite:** - -- `understanding-agent-types.md` - Architecture vs capability distinction -- `simple-agent-architecture.md` - Self-contained agents guide -- `expert-agent-architecture.md` - Agents with sidecar files -- `module-agent-architecture.md` - Workflow-integrated agents -- `agent-compilation.md` - YAML โ†’ XML transformation process -- `agent-menu-patterns.md` - Menu design patterns -- `communication-presets.csv` - 60 pure communication styles for reference - -**New Reference Agents for Learning:** - -- Complete working examples of Simple, Expert, and Module agents -- Can be installed directly via the new `bmad agent-install` command -- Serve as both learning resources and ready-to-use agents - -### ๐ŸŽฏ Epic Creation Moved to Phase 3 (After Architecture) - -**Workflow Sequence Corrected:** - -``` -Phase 2: PRD โ†’ UX Design -Phase 3: Architecture โ†’ Epics & Stories โ† NOW HERE (technically informed) -``` - -**Why This Fundamental Change:** - -- Epics need architectural context: API contracts, data models, technical decisions -- Stories can reference actual architectural patterns and constraints -- Reduces rewrites when architecture reveals complexity -- Better complexity-based estimation (not time-based) - -### ๐Ÿ–ฅ๏ธ New IDE Support - -**Google Antigravity IDE Installer:** - -- Flattened file naming for proper slash commands (bmad-module-agents-name.md) -- Namespace isolation prevents module conflicts -- Subagent installation support (project or user level) -- Module-specific injection configuration - -**Codex CLI Enhancement:** - -- Now supports both global and project-specific installation -- CODEX_HOME configuration for multi-project workflows -- OS-specific setup instructions (Unix/Mac/Windows) - -### ๐Ÿ—๏ธ Reference Agents & Standards - -**New Reference Agents Provide Clear Examples:** - -- **commit-poet.agent.yaml**: Simple agent with pure communication style -- **journal-keeper.agent.yaml**: Expert agent with sidecar file structure -- **security-engineer.agent.yaml**: Module agent for ecosystem integration -- **trend-analyst.agent.yaml**: Module agent with cross-workflow capabilities - -**Agent Type Clarification:** - -- Clear documentation that agent types (Simple/Expert/Module) describe architecture, not capability -- Module = designed for ecosystem integration, not limited in function - -### ๐Ÿ› Technical Improvements - -**Linting Compliance:** - -- Fixed all ESLint warnings across agent tooling -- `'utf-8'` โ†’ `'utf8'` (unicorn/text-encoding-identifier-case) -- `hasOwnProperty` โ†’ `Object.hasOwn` (unicorn/prefer-object-has-own) -- `JSON.parse(JSON.stringify(...))` โ†’ `structuredClone(...)` - -**Agent Compilation Engine:** - -- Auto-injects frontmatter, activation, handlers, help/exit menu items -- Smart handler inclusion (only includes handlers actually used) -- Proper XML escaping and formatting -- Persona name customization support - -### ๐Ÿ“Š Impact Summary - -**New in alpha.11:** - -- **Agent installation system** with `bmad agent-install` CLI command -- **4 new reference agents** (commit-poet, journal-keeper, security-engineer, trend-analyst) -- **Complete agent documentation suite** with 7 new focused guides -- **Expert agent sidecar support** in edit-agent workflow -- **2 new IDE installers** (Google Antigravity, enhanced Codex) -- **Unified validation checklist** (160 lines) for consistent quality standards -- **60 pure communication style presets** for agent persona design - -**Enhanced from alpha.10:** - -- **BMB agent builder workflows** with accurate context and comprehensive guidance -- **All 9 BMM agents** enhanced with distinct, memorable communication voices -- **Excalidraw capabilities** refined and distributed to role-appropriate agents -- **Epic creation** moved to Phase 3 (after Architecture) for technical context +- **Epic Creation Moved**: Now in Phase 3 after Architecture for technical context +- **Excalidraw Distribution**: Diagram capabilities moved to role-appropriate agents +- **Google Antigravity IDE**: New installer with flattened file naming ### โš ๏ธ Breaking Changes -**Agent Changes:** - -- Frame Expert agent retired - diagram capabilities now available through role-appropriate agents: - - Architecture diagrams โ†’ `/architect` - - Process flows โ†’ `/pm` - - Wireframes โ†’ `/ux-designer` - - Documentation visuals โ†’ `/tech-writer` - -**Workflow Changes:** - -- Epic creation moved from Phase 2 to Phase 3 (after Architecture) -- Excalidraw workflows redistributed to appropriate agents - -**Installation Changes:** - -- New `bmad agent-install` command replaces manual agent installation -- Agent YAML files must be compiled to XML for use - -### ๐Ÿ”„ Migration Notes - -**For Existing Projects:** - -1. **Frame Expert Users:** - - Transition to role-appropriate agents for diagrams - - All Excalidraw functionality preserved and enhanced - - Shared templates now in core resources for wider access - -2. **Agent Installation:** - - Use `bmad agent-install` for all agent installations - - Existing manual installations still work but won't have customization - -3. **Epic Creation Timing:** - - Epics now created in Phase 3 after Architecture - - Update any automation expecting epics in Phase 2 - -4. **Communication Styles:** - - Review agent communication_style fields - - Remove any role/identity/principle content - - Use communication-presets.csv for pure styles - -5. **Expert Agents:** - - Edit-agent workflow now fully supports sidecar files - - Organize templates and data files in agent folder +1. **Frame Expert Retired**: Use role-appropriate agents for diagrams +2. **Agent Installation**: New bmad agent-install command replaces manual installation +3. **Epic Creation Phase**: Moved from Phase 2 to Phase 3 ## [6.0.0-alpha.10] **Release: November 16, 2025** -- **๐ŸŽฏ Epics Generated AFTER Architecture**: Major milestone - epics/stories now created after architecture for technically-informed user stories with better acceptance criteria -- **๐ŸŽจ Frame Expert Agent**: New Excalidraw specialist with 4 diagram workflows (flowchart, diagram, dataflow, wireframe) for visual documentation -- **โฐ Time Estimate Prohibition**: Critical warnings added across 33 workflows - acknowledges AI has fundamentally changed development speed -- **๐ŸŽฏ Platform-Specific Commands**: New `ide-only`/`web-only` fields filter menu items based on environment (IDE vs web bundle) -- **๐Ÿ”ง Agent Customization**: Enhanced memory/prompts merging via `*.customize.yaml` files for persistent agent personalization +- **Epics After Architecture**: Major milestone - technically-informed user stories created post-architecture +- **Frame Expert Agent**: New Excalidraw specialist with 4 diagram workflows +- **Time Estimate Prohibition**: Warnings across 33 workflows acknowledging AI's impact on development speed +- **Platform-Specific Commands**: ide-only/web-only fields filter menu items by environment +- **Agent Customization**: Enhanced memory/prompts merging via \*.customize.yaml files ## [6.0.0-alpha.9] **Release: November 12, 2025** -- **๐Ÿš€ Intelligent File Discovery Protocol**: New `discover_inputs` with FULL_LOAD, SELECTIVE_LOAD, and INDEX_GUIDED strategies for automatic context loading -- **๐Ÿ“š 3-Track System**: Simplified from 5 levels to 3 intuitive tracks: quick-flow, bmad-method, and enterprise-bmad-method -- **๐ŸŒ Web Bundles Guide**: Comprehensive documentation for Gemini Gems and Custom GPTs with 60-80% cost savings strategies -- **๐Ÿ—๏ธ Unified Output Structure**: Eliminated `.ephemeral/` folders - all artifacts now in single configurable output folder -- **๐ŸŽฎ BMGD Phase 4**: Added 10 game development workflows following BMM patterns with game-specific adaptations +- **Intelligent File Discovery**: discover_inputs with FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED strategies +- **3-Track System**: Simplified from 5 levels to 3 intuitive tracks +- **Web Bundles Guide**: Comprehensive documentation with 60-80% cost savings strategies +- **Unified Output Structure**: Eliminated .ephemeral/ folders - single configurable output folder +- **BMGD Phase 4**: Added 10 game development workflows with BMM patterns ## [6.0.0-alpha.8] **Release: November 9, 2025** -- **๐ŸŽฏ Configurable Installation**: Custom directories with `.bmad` hidden folder default for cleaner project structure -- **๐Ÿš€ Optimized Agent Loading**: CLI loads from installed files eliminating duplication and maintenance burden -- **๐ŸŒ Party Mode Everywhere**: All web bundles include multi-agent collaboration with customizable party configurations -- **๐Ÿ”ง Phase 4 Artifact Separation**: Stories, code reviews, sprint plans now configurable outside docs folder -- **๐Ÿ“ฆ Expanded Web Bundles**: All BMM, BMGD, and CIS agents bundled with advanced elicitation integration +- **Configurable Installation**: Custom directories with .bmad hidden folder default +- **Optimized Agent Loading**: CLI loads from installed files, eliminating duplication +- **Party Mode Everywhere**: All web bundles include multi-agent collaboration +- **Phase 4 Artifact Separation**: Stories, code reviews, sprint plans configurable outside docs +- **Expanded Web Bundles**: All BMM, BMGD, CIS agents bundled with elicitation integration ## [6.0.0-alpha.7] **Release: November 7, 2025** -- **๐ŸŒ Workflow Vendoring**: Web bundler performs automatic workflow vendoring for cross-module dependencies -- **๐ŸŽฎ BMGD Module Extraction**: Game development split into standalone module with 4-phase industry-standard structure -- **๐Ÿ”ง Enhanced Dependency Resolution**: Better handling of `web_bundle: false` workflows with positive resolution messages -- **๐Ÿ“š Advanced Elicitation Fix**: Added missing CSV files to workflow bundles fixing runtime failures -- **๐Ÿ› Claude Code Fix**: Resolved README slash command installation regression +- **Workflow Vendoring**: Web bundler performs automatic cross-module dependency vendoring +- **BMGD Module Extraction**: Game development split into standalone 4-phase structure +- **Enhanced Dependency Resolution**: Better handling of web_bundle: false workflows +- **Advanced Elicitation Fix**: Added missing CSV files to workflow bundles +- **Claude Code Fix**: Resolved README slash command installation regression ## [6.0.0-alpha.6] **Release: November 4, 2025** -- **๐Ÿ› Critical Installer Fixes**: Fixed manifestPath error and option display issues blocking installation -- **๐Ÿ“– Conditional Docs Installation**: Optional documentation installation to reduce footprint in production -- **๐ŸŽจ Improved Installer UX**: Better formatting with descriptive labels and clearer feedback -- **๐Ÿงน Issue Tracker Cleanup**: Closed 54 legacy v4 issues for focused v6 development -- **๐Ÿ“ Contributing Updates**: Removed references to non-existent branches in documentation +- **Critical Installer Fixes**: Fixed manifestPath error and option display issues +- **Conditional Docs Installation**: Optional documentation to reduce production footprint +- **Improved Installer UX**: Better formatting with descriptive labels and clearer feedback +- **Issue Tracker Cleanup**: Closed 54 legacy v4 issues for focused v6 development +- **Contributing Updates**: Removed references to non-existent branches ## [6.0.0-alpha.5] **Release: November 4, 2025** -- **๐ŸŽฏ 3-Track Scale System**: Revolutionary simplification from 5 confusing levels to 3 intuitive preference-driven tracks -- **โœจ Elicitation Modernization**: Replaced legacy XML tags with explicit `invoke-task` pattern at strategic decision points -- **๐Ÿ“š PM/UX Evolution Section**: Added November 2025 industry research on AI Agent PMs and Full-Stack Product Leads -- **๐Ÿ—๏ธ Brownfield Reality Check**: Rewrote Phase 0 with 4 real-world scenarios for messy existing codebases -- **๐Ÿ“– Documentation Accuracy**: All agent capabilities now match YAML source of truth with zero hallucination risk +- **3-Track Scale System**: Simplified from 5 levels to 3 intuitive preference-driven tracks +- **Elicitation Modernization**: Replaced legacy XML tags with explicit invoke-task pattern +- **PM/UX Evolution**: Added November 2025 industry research on AI Agent PMs +- **Brownfield Reality Check**: Rewrote Phase 0 with 4 real-world scenarios +- **Documentation Accuracy**: All agent capabilities now match YAML source of truth ## [6.0.0-alpha.4] **Release: November 2, 2025** -- **๐Ÿ“š Documentation Hub**: Created 18 comprehensive guides (7000+ lines) with professional technical writing standards -- **๐Ÿค– Paige Agent**: New technical documentation specialist available across all BMM phases -- **๐Ÿš€ Quick Spec Flow**: Intelligent Level 0-1 planning with auto-stack detection and brownfield analysis -- **๐Ÿ“ฆ Universal Shard-Doc**: Split large markdown documents into organized sections with dual-strategy loading -- **๐Ÿ”ง Intent-Driven Planning**: PRD and Product Brief transformed from template-filling to natural conversation +- **Documentation Hub**: Created 18 comprehensive guides (7000+ lines) with professional standards +- **Paige Agent**: New technical documentation specialist across all BMM phases +- **Quick Spec Flow**: Intelligent Level 0-1 planning with auto-stack detection +- **Universal Shard-Doc**: Split large markdown documents with dual-strategy loading +- **Intent-Driven Planning**: PRD and Product Brief transformed from template-filling to conversation ## [6.0.0-alpha.3] diff --git a/README.md b/README.md index 0c64ce83..1c0975e8 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,9 @@ ## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise -**Build More, Architect Dreams** (BMAD) with **19 specialized AI agents** and **50+ guided workflows** that adapt to your project's complexityโ€”from quick bug fixes to enterprise platforms. +**Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexityโ€”from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before! + +Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits! > **๐Ÿš€ v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new โ†’](#whats-new-in-v6) @@ -154,6 +156,7 @@ Each agent brings deep expertise and can be customized to match your team's styl - **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features - **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos - **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles +- **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines ## ๐Ÿ› ๏ธ Development diff --git a/custom/src/agents/commit-poet/installation-guide.md b/custom/src/agents/commit-poet/installation-guide.md deleted file mode 100644 index 28ba9afb..00000000 --- a/custom/src/agents/commit-poet/installation-guide.md +++ /dev/null @@ -1,36 +0,0 @@ -# Custom Agent Installation - -## Quick Install - -```bash -# Interactive -npx bmad-method agent-install - -# Non-interactive -npx bmad-method agent-install --defaults -``` - -## Install Specific Agent - -```bash -# From specific source file -npx bmad-method agent-install --source ./my-agent.agent.yaml - -# With default config (no prompts) -npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults - -# To specific destination -npx bmad-method agent-install --source ./my-agent.agent.yaml --destination ./my-project -``` - -## Batch Install - -1. Copy agent YAML to `{bmad folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root -2. Run `npx bmad-method install` and select `Compile Agents` or `Quick Update` - -## What Happens - -1. Source YAML compiled to .md -2. Installed to `custom/agents/{agent-name}/` -3. Added to agent manifest -4. Backup saved to `_cfg/custom/agents/` diff --git a/custom/src/agents/toolsmith/installation-guide.md b/custom/src/agents/toolsmith/installation-guide.md deleted file mode 100644 index 28ba9afb..00000000 --- a/custom/src/agents/toolsmith/installation-guide.md +++ /dev/null @@ -1,36 +0,0 @@ -# Custom Agent Installation - -## Quick Install - -```bash -# Interactive -npx bmad-method agent-install - -# Non-interactive -npx bmad-method agent-install --defaults -``` - -## Install Specific Agent - -```bash -# From specific source file -npx bmad-method agent-install --source ./my-agent.agent.yaml - -# With default config (no prompts) -npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults - -# To specific destination -npx bmad-method agent-install --source ./my-agent.agent.yaml --destination ./my-project -``` - -## Batch Install - -1. Copy agent YAML to `{bmad folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root -2. Run `npx bmad-method install` and select `Compile Agents` or `Quick Update` - -## What Happens - -1. Source YAML compiled to .md -2. Installed to `custom/agents/{agent-name}/` -3. Added to agent manifest -4. Backup saved to `_cfg/custom/agents/` diff --git a/docs/custom-agent-installation.md b/docs/custom-agent-installation.md deleted file mode 100644 index 15098094..00000000 --- a/docs/custom-agent-installation.md +++ /dev/null @@ -1,183 +0,0 @@ -# Custom Agent Installation - -Install and personalize BMAD agents in your project. - -## Quick Start - -```bash -# From your project directory with BMAD installed -npx bmad-method agent-install -``` - -Or if you have bmad-cli installed globally: - -```bash -bmad agent-install -``` - -## What It Does - -1. **Discovers** available agent templates from your custom agents folder -2. **Prompts** you to personalize the agent (name, behavior, preferences) -3. **Compiles** the agent with your choices baked in -4. **Installs** to your project's `.bmad/custom/agents/` directory -5. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.) -6. **Saves** your configuration for automatic reinstallation during BMAD updates - -## Options - -```bash -bmad agent-install [options] - -Options: - -p, --path #Direct path to specific agent YAML file or folder - -d, --defaults #Use default values without prompting - -t, --target #Target installation directory -``` - -## Installing from Custom Locations - -Use the `-s` / `--source` option to install agents from any location: - -```bash -# Install agent from a custom folder (expert agent with sidecar) -bmad agent-install -s path/to/my-agent - -# Install a specific .agent.yaml file (simple agent) -bmad agent-install -s path/to/my-agent.agent.yaml - -# Install with defaults (non-interactive) -bmad agent-install -s path/to/my-agent -d - -# Install to a specific destination project -bmad agent-install -s path/to/my-agent --destination /path/to/destination/project -``` - -This is useful when: - -- Your agent is in a non-standard location (not in `.bmad/custom/agents/`) -- You're developing an agent outside the project structure -- You want to install from an absolute path - -## Example Session - -``` -๐Ÿ”ง BMAD Agent Installer - -Found BMAD at: /project/.bmad -Searching for agents in: /project/.bmad/custom/agents - -Available Agents: - - 1. ๐Ÿ“„ commit-poet (simple) - 2. ๐Ÿ“š journal-keeper (expert) - -Select agent to install (number): 1 - -Selected: commit-poet - -๐Ÿ“› Agent Persona Name - - Agent type: commit-poet - Default persona: Inkwell Von Comitizen - - Custom name (or Enter for default): Fred - - Persona: Fred - File: fred-commit-poet.md - -๐Ÿ“ Agent Configuration - - What's your preferred default commit message style? - * 1. Conventional (feat/fix/chore) - 2. Narrative storytelling - 3. Poetic haiku - 4. Detailed explanation - Choice (default: 1): 1 - - How enthusiastic should the agent be? - 1. Moderate - Professional with personality - * 2. High - Genuinely excited - 3. EXTREME - Full theatrical drama - Choice (default: 2): 3 - - Include emojis in commit messages? [Y/n]: y - -โœจ Agent installed successfully! - Name: fred-commit-poet - Location: /project/.bmad/custom/agents/fred-commit-poet - Compiled: fred-commit-poet.md - - โœ“ Source saved for reinstallation - โœ“ Added to agent-manifest.csv - โœ“ Created IDE commands: - claude-code: /bmad:custom:agents:fred-commit-poet - codex: /bmad-custom-agents-fred-commit-poet - github-copilot: bmad-agent-custom-fred-commit-poet -``` - -## Reinstallation - -Custom agents are automatically reinstalled when you run `bmad init --quick`. Your personalization choices are preserved in `.bmad/_cfg/custom/agents/`. - -## Installing Reference Agents - -The BMAD source includes example agents you can install. **You must copy them to your project first.** - -### Step 1: Copy the Agent Template - -**For simple agents** (single file): - -```bash -# From your project root -cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \ - .bmad/custom/agents/ -``` - -**For expert agents** (folder with sidecar files): - -```bash -# Copy the entire folder -cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memory/journal-keeper \ - .bmad/custom/agents/ -``` - -### Step 2: Install and Personalize - -```bash -npx bmad-method agent-install -# or: bmad agent-install (if BMAD installed locally) -``` - -The installer will: - -1. Find the copied template in `.bmad/custom/agents/` -2. Prompt for personalization (name, behavior, preferences) -3. Compile and install with your choices baked in -4. Create IDE commands for immediate use - -### Available Reference Agents - -**Simple (standalone file):** - -- `commit-poet.agent.yaml` - Commit message artisan with style preferences - -**Expert (folder with sidecar):** - -- `journal-keeper/` - Personal journal companion with memory and pattern recognition - -Find these in the BMAD source: - -``` -src/modules/bmb/reference/agents/ -โ”œโ”€โ”€ stand-alone/ -โ”‚ โ””โ”€โ”€ commit-poet.agent.yaml -โ””โ”€โ”€ agent-with-memory/ - โ””โ”€โ”€ journal-keeper/ - โ”œโ”€โ”€ journal-keeper.agent.yaml - โ””โ”€โ”€ journal-keeper-sidecar/ -``` - -## Creating Your Own - -Use the BMB agent builder to craft your agents. Once ready to use yourself, place your `.agent.yaml` files or folder in `.bmad/custom/agents/`. diff --git a/docs/custom-content-installation.md b/docs/custom-content-installation.md new file mode 100644 index 00000000..8dc4ad98 --- /dev/null +++ b/docs/custom-content-installation.md @@ -0,0 +1,245 @@ +# Custom Content Installation + +This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content allows you to extend BMAD's functionality with your own specialized tools and workflows that can be shared across projects or teams. + +## Types of Custom Content + +### 1. Custom Agents and Workflows (Standalone) + +Custom agents and workflows are standalone content packages that can be installed without being part of a full module. These are perfect for: + +- Sharing specialized agents across projects +- Building a personal Agent powered Notebook vault +- Distributing workflow templates +- Creating agent libraries for specific domains + +#### Structure + +A custom agents and workflows package follows this structure: + +``` +my-custom-agents/ +โ”œโ”€โ”€ module.yaml # Package configuration +โ”œโ”€โ”€ agents/ # Agent definitions +โ”‚ โ””โ”€โ”€ my-agent/ +โ”‚ โ””โ”€โ”€ agent.md +โ””โ”€โ”€ workflows/ # Workflow definitions + โ””โ”€โ”€ my-workflow/ + โ””โ”€โ”€ workflow.md +``` + +#### Configuration + +Create a `module.yaml` file in your package root: + +```yaml +code: my-custom-agents +name: 'My Custom Agents and Workflows' +default_selected: true +``` + +#### Example + +See `/example-custom-content` for a working example of a folder with multiple random custom agents and workflows. Technically its also just a module, but you will be able to further pick and choose from this folders contents of what you do and do not want to include in a destination folder. This way, you can store all custom content source in one location and easily install it to different locations. + +### 2. Custom Modules + +Custom modules are complete BMAD modules that can include their own configuration, documentation, along with agents and workflows that all compliment each other. Additionally they will have their own installation scripts, data, and potentially other tools. Modules can be used for: + +- Domain-specific functionality (e.g., industry-specific workflows, entertainment, education and training, medical, etc...) +- Integration with external systems +- Specialized agent collections +- Custom tooling and utilities + +#### Structure + +A custom module follows this structure: + +``` +my-module/ +โ”œโ”€โ”€ _module-installer/ +โ”‚ โ”œโ”€โ”€ installer.js # optional, when it exists it will run with module installation +โ”œโ”€โ”€ module.yaml # Module installation configuration with custom question and answer capture +โ”œโ”€โ”€ docs/ # Module documentation +โ”œโ”€โ”€ agents/ # Module-specific agents +โ”œโ”€โ”€ workflows/ # Module-specific workflows +โ”œโ”€โ”€ data/ # csv or other content to power agent intelligence or workflows +โ”œโ”€โ”€ tools/ # Custom tools, hooks, mcp +โ””โ”€โ”€ sub-modules/ # IDE-specific customizations + โ”œโ”€โ”€ vscode/ + โ””โ”€โ”€ cursor/ +``` + +#### Module Configuration + +The `module.yaml` file defines how your module is installed: + +```yaml +# Module metadata +code: my-module +name: 'My Custom Module' +default_selected: false + +header: 'My Custom Module' +subheader: 'Description of what this module does' + +# Configuration prompts +my_setting: + prompt: 'Configure your module setting' + default: 'default-value' + result: '{value}' +``` + +#### Example + +See `/example-custom-module` for a complete example: + +## Installation Process + +### Step 1: Running the Installer + +When you run the existing normal BMAD installer - either from the cloned repo, OR via NPX, it will ask about custom content: + +``` +? Do you have custom content to install? +โฏ No (skip custom content) + Enter a directory path + Enter a URL [Coming soon] +``` + +### Step 2: Providing Custom Content Path + +If you select "Enter a directory path", the installer will prompt for the location: + +``` +? Enter the path to your custom content directory: /path/to/folder/containing/content/folder +``` + +The installer will: + +- Scan for `module.yaml` files (modules) +- Display an indication of how many installable folders it has found. Note that a project with stand along agents and workflows all under a single folder like the example will just list the count as 1 for that directory. + +### Step 3: Selecting Content + +The installer presents a unified selection interface: + +``` +? Select modules and custom content to install: +[โ”€โ”€ Custom Content โ”€โ”€] + โ—‰ My Custom Agents and Workflows (/path/to/custom) +[โ”€โ”€ Official Content โ”€โ”€] + โ—ฏ BMM: Business Method & Management + โ—ฏ CIS: Creativity & Innovation Suite +``` + +## Agent Sidecar Support + +Agents with sidecar content can store personal data, memories, and working files outside of the `.bmad` directory. This separation keeps personal content separate from BMAD's core files. + +### What is Sidecar Content? + +Sidecar content includes: + +- Agent memories and learning data +- Personal working files +- Temporary data +- User-specific configurations + +### Sidecar Configuration + +The sidecar folder location is configured during BMAD core installation: + +``` +? Where should users' agent sidecar memory folders be stored? +โฏ .bmad-user-memory +``` + +### How It Works + +1. **Agent Declaration**: Agents declare `hasSidecar: true` in their metadata +2. **Sidecar Detection**: The installer automatically detects folders with "sidecar" in the name +3. **Installation**: Sidecar content is copied to the configured location +4. **Path Replacement**: The `{agent_sidecar_folder}` placeholder in agent configurations is replaced with the actual path to the installed instance of the sidecar folder. Now when you use the agent, depending on its design, will use the content in sidecar to record interactions, remember things you tell it, or serve a host of many other issues. + +### Example Structure + +``` +my-agent/ +โ”œโ”€โ”€ agent.md # Agent definition +โ””โ”€โ”€ my-agent-sidecar/ # Sidecar content folder + โ”œโ”€โ”€ memories/ + โ”œโ”€โ”€ working/ + โ””โ”€โ”€ config/ +``` + +### Git Integration + +Since sidecar content is stored outside the `.bmad` directory (and typically outside version control), users can: + +- Add the sidecar folder to `.gitignore` to exclude personal data +- Share agent definitions without exposing personal content +- Maintain separate configurations for different projects + +Example `.gitignore` entry: + +``` +# Exclude agent personal data +.bmad-user-memory/ +``` + +## Creating Custom Content with BMAD Builder + +The BMAD Builder provides workflows that will guide you to produce your own custom content: + +1. **Agent Templates**: Use standardized agent templates with proper structure +2. **Workflow Templates**: Create workflows using proven patterns +3. **Validation Tools**: Validate your content before distribution +4. **Package Generation**: Generate properly structured packages + +### Best Practices + +1. **Use Clear Naming**: Make your content codes and names descriptive +2. **Provide Documentation**: Include clear setup and usage instructions +3. **Test Installation**: Test your content in a clean environment +4. **Version Management**: Use semantic versioning for updates +5. **Respect User Privacy**: Keep personal data in sidecar folders + +## Distribution + +Custom content can be distributed: + +1. **File System**: Copy folders directly to users +2. **Git Repositories**: Clone or download from version control +3. **Package Managers**: [Coming soon] npm package support +4. **URL Installation**: [Coming soon] Direct URL installation, including an official community vetted module forge + +## Troubleshooting + +### No Custom Content Found + +- Ensure your `module.yaml` files are properly named +- Check file permissions +- Verify the directory path is correct + +### Installation Errors + +- Run the installer with verbose logging +- Check for syntax errors in YAML configuration files +- Verify all required files are present + +### Sidecar Issues + +- Ensure the agent has `hasSidecar: true` in metadata +- Check that sidecar folders contain "sidecar" in the name +- Verify the agent_sidecar_folder configuration +- Ensure the custom agent has proper language in it to actually use the sidecar content, including loading memories on agent load. + +## Support + +For help with custom content creation or installation: + +1. Check the examples in `/example-custom-content` and `/example-custom-module` +2. Review the BMAD documentation +3. Create an issue in the BMAD repository +4. Join the BMAD community discussions on discord diff --git a/docs/index.md b/docs/index.md index d5e1f83e..f769095e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -96,9 +96,9 @@ Instructions for loading agents and running workflows in your development enviro ## ๐Ÿ”ง Advanced Topics -### Custom Agents +### Custom Agents, Workflow and Modules -- **[Custom Agent Installation](./custom-agent-installation.md)** - Install and personalize agents with `bmad agent-install` +- **[Custom Content Installation](./custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer! - [Agent Customization Guide](./agent-customization-guide.md) - Customize agent behavior and responses ### Installation & Bundling diff --git a/docs/installers-bundlers/installers-modules-platforms-reference.md b/docs/installers-bundlers/installers-modules-platforms-reference.md index 62f1a398..45108177 100644 --- a/docs/installers-bundlers/installers-modules-platforms-reference.md +++ b/docs/installers-bundlers/installers-modules-platforms-reference.md @@ -59,6 +59,7 @@ project-root/ ### Key Exclusions - `_module-installer/` directories are never copied to destination +- module.yaml - `localskip="true"` agents are filtered out - Source `config.yaml` templates are replaced with generated configs @@ -92,8 +93,8 @@ Creative Innovation Studio for design workflows ``` src/modules/{module}/ โ”œโ”€โ”€ _module-installer/ # Not copied to destination -โ”‚ โ”œโ”€โ”€ installer.js # Post-install logic -โ”‚ โ””โ”€โ”€ install-config.yaml +โ”‚ โ”œโ”€โ”€ installer.js # Post-install logic +โ”œโ”€โ”€ module.yaml โ”œโ”€โ”€ agents/ โ”œโ”€โ”€ tasks/ โ”œโ”€โ”€ templates/ @@ -107,7 +108,7 @@ src/modules/{module}/ ### Collection Process -Modules define prompts in `install-config.yaml`: +Modules define prompts in `module.yaml`: ```yaml project_name: @@ -218,12 +219,12 @@ Platform-specific content without source modification: src/modules/mymod/ โ”œโ”€โ”€ _module-installer/ โ”‚ โ”œโ”€โ”€ installer.js - โ”‚ โ””โ”€โ”€ install-config.yaml + โ”œโ”€โ”€ module.yaml โ”œโ”€โ”€ agents/ โ””โ”€โ”€ tasks/ ``` -2. **Configuration** (`install-config.yaml`) +2. **Configuration** (`module.yaml`) ```yaml code: mymod diff --git a/docs/web-bundles-gemini-gpt-guide.md b/docs/web-bundles-gemini-gpt-guide.md index 6419165e..9ae3d64f 100644 --- a/docs/web-bundles-gemini-gpt-guide.md +++ b/docs/web-bundles-gemini-gpt-guide.md @@ -73,7 +73,7 @@ web-bundles/ **Create a Gem:** -1. Go to [Google AI Studio](https://aistudio.google.com/) +1. Go to [Gemini Gem manager](https://gemini.google.com/gems/view) 2. Click "New Gem" or "Create Gem" 3. Give your Gem a name (e.g., "BMad PM Agent") 4. **Enable "Code execution" for best results with document generation** diff --git a/docs/workflow-compliance-report-create-workflow.md b/docs/workflow-compliance-report-create-workflow.md deleted file mode 100644 index ab1d5c29..00000000 --- a/docs/workflow-compliance-report-create-workflow.md +++ /dev/null @@ -1,513 +0,0 @@ ---- -name: 'Workflow Compliance Report - create-workflow' -description: 'Systematic validation results for create-workflow workflow' -workflow_name: 'create-workflow' -validation_date: '2025-12-02' -stepsCompleted: ['workflow-validation', 'step-validation', 'file-validation', 'spectrum-validation', 'web-subprocess-validation'] ---- - -# Workflow Compliance Report: create-workflow - -**Validation Date:** 2025-12-02 -**Target Workflow:** /Users/brianmadison/dev/BMAD-METHOD/src/modules/bmb/workflows/create-workflow/workflow.md -**Reference Standard:** /Users/brianmadison/dev/BMAD-METHOD/.bmad/bmb/docs/workflows/templates/workflow-template.md - -## Phase 1: Workflow.md Validation Results - -### Template Adherence Analysis - -**Reference Standard:** workflow-template.md - -### Frontmatter Structure Violations - -โœ… **PASS** - All required fields present and properly formatted: - -- name: "Create Workflow" โœ“ -- description: "Create structured standalone workflows using markdown-based step architecture" โœ“ -- web_bundle: true (proper boolean format) โœ“ - -### Role Description Violations - -โœ… **PASS** - Role description follows template format: - -- Partnership language present: "This is a partnership, not a client-vendor relationship" โœ“ -- Expertise clearly defined: "workflow architect and systems designer" โœ“ -- User expertise identified: "domain knowledge and specific workflow requirements" โœ“ -- Collaboration directive: "Work together as equals" โœ“ - -### Workflow Architecture Violations - -๐Ÿšซ **CRITICAL VIOLATION** - Core Principles deviate from template: - -**Template requires:** "Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time" - -**Target has:** "Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly" - -- **Severity:** Critical -- **Template Reference:** "Core Principles" section in workflow-template.md -- **Specific Fix:** Replace with exact template wording: "Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time" - -๐Ÿšซ **CRITICAL VIOLATION** - State Tracking Rule deviates from template: - -**Template requires:** "Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document" - -**Target has:** "Document progress in context for compliance checking (no output file frontmatter needed)" - -- **Severity:** Critical -- **Template Reference:** "Core Principles" section in workflow-template.md -- **Specific Fix:** Replace with exact template wording about stepsCompleted array - -### Initialization Sequence Violations - -๐Ÿšซ **MAJOR VIOLATION** - Configuration path format incorrect: - -**Template requires:** "{project-root}/.bmad/[MODULE FOLDER]/config.yaml" - -**Target has:** "{project-root}/.bmad/bmb/config.yaml" - -- **Severity:** Major -- **Template Reference:** "Module Configuration Loading" section in workflow-template.md -- **Specific Fix:** Use proper module variable substitution: "{project-root}/.bmad/bmb/config.yaml" should reference module folder properly - -๐Ÿšซ **MAJOR VIOLATION** - First step path format inconsistent: - -**Template requires:** Explicit step file path following pattern - -**Target has:** "Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow." - -- **Severity:** Major -- **Template Reference:** "First Step EXECUTION" section in workflow-template.md -- **Specific Fix:** Ensure consistency with template variable substitution patterns - -### Phase 1 Summary - -**Critical Issues:** 2 - -- Core Principles text deviation from template -- State Tracking rule modification from template standard - -**Major Issues:** 2 - -- Configuration path format not following template variable pattern -- First step execution path needs consistency check - -**Minor Issues:** 0 - -### Phase 1 Recommendations - -**Priority 1 - Critical Fixes:** - -1. Replace Core Principles text with exact template wording -2. Restore State Tracking rule to template standard about stepsCompleted array - -**Priority 2 - Major Fixes:** - -1. Review and standardize all path variable usage to follow template patterns -2. Ensure consistency in variable substitution throughout workflow - -## Phase 2: Step Validation Results - -### Template Adherence Analysis - -**Reference Standard:** step-template.md -**Total Steps Analyzed:** 9 - -### Critical Violations Summary - -**Step 01-init.md:** - -- Missing `outputFile` in frontmatter - Template Reference: line 22 -- Uses auto-proceed menu instead of standard A/P/C pattern - Template Reference: lines 106-123 -- Missing "CRITICAL STEP COMPLETION NOTE" section - Template Reference: line 126 - -**Step 02-gather.md:** - -- Missing `outputFile` in frontmatter - Template Reference: line 22 -- Incorrect `nextStepFile` path format - Template Reference: line 19 - -**Steps 03-09 (All Steps):** - -- Missing `outputFile` in frontmatter - Template Reference: line 22 -- Non-standard step naming (missing short descriptive names) - Template Reference: line 9 -- Steps 08-09 missing `workflowFile` in frontmatter - Template Reference: line 21 - -### Major Violations Summary - -**Frontmatter Structure (All Steps):** - -- Missing `altStep{Y}` comment pattern - Template Reference: line 20 -- Missing Task References section structure - Template Reference: lines 24-27 -- Missing Template References section structure - Template Reference: lines 29-33 -- Missing Data References section structure - Template Reference: lines 35-37 - -**Menu Pattern Violations:** - -- Step 01: Custom auto-proceed menu instead of standard A/P/C - Template Reference: lines 106-123 -- Step 05: Menu text "Continue" instead of "Continue to [next action]" - Template Reference: line 115 -- Step 07: Custom "Build Complete" menu instead of A/P/C pattern - Template Reference: lines 106-123 -- Step 08: Missing A and P options in menu - Template Reference: lines 106-123 -- Step 09: Uses T/M/D pattern instead of standard A/P/C - Template Reference: lines 106-123 - -### Path Variable Inconsistencies - -- Inconsistent use of `{bmad_folder}` vs `.bmad` in paths across all steps -- Missing `outputFile` variable definitions - Template Reference: line 22 -- Step 04 uses non-standard `nextStepFormDesign` and `nextStepDesign` variables - -### Minor Violations Summary - -**Content Structure:** - -- Missing "CONTEXT BOUNDARIES" section titles - Template Reference: line 82 -- Missing "EXECUTION PROTOCOLS" section titles - Template Reference: line 75 -- Non-standard section naming in multiple steps - Template Reference: line 89 - -### Phase 2 Summary - -**Critical Issues:** 15 - -- 9 missing outputFile variables -- 6 non-standard menu patterns -- Multiple missing required sections - -**Major Issues:** 36 - -- 36 frontmatter structure violations across all steps -- 5 menu pattern deviations -- Numerous path variable inconsistencies - -**Minor Issues:** 27 - -- Section naming inconsistencies -- Missing template-required section titles - -**Most Common Violations:** - -1. Missing `outputFile` in frontmatter (9 occurrences) -2. Non-standard menu patterns (6 occurrences) -3. Missing Task/Template/Data References sections (27 occurrences) - -### Overall Step Compliance Score - -**Overall Workflow Step Compliance: 68%** - -- Step 01: 65% compliant -- Step 02: 70% compliant -- Steps 03-09: 63-72% compliant each - -## Phase 3: File Size, Formatting, and Data Validation Results - -### File Size Analysis - -**Workflow File:** - -- workflow.md: 2.9K - โœ… **Optimal** - Excellent performance and maintainability - -**Step Files Distribution:** - -- **Optimal (โ‰ค5K):** 3 files - - step-09-complete.md: 5.1K - - step-01-init.md: 5.3K -- **Good (5K-7K):** 1 file - - step-04-plan-review.md: 6.6K -- **Acceptable (7K-10K):** 5 files - - step-02-gather.md: 7.8K - - step-08-review.md: 7.9K - - step-03-tools-configuration.md: 7.9K - - step-05-output-format-design.md: 8.2K - - step-06-design.md: 9.0K -- **Acceptable (approaching concern):** 1 file - - step-07-build.md: 10.0K (monitor if additional features added) - -**CSV Data Files:** - -- Total CSV files: 0 -- No data files present requiring validation - -### Markdown Formatting Validation - -**โœ… Strengths:** - -- Consistent frontmatter structure across all files -- Proper heading hierarchy (H1โ†’H2โ†’H3) maintained -- Standardized section patterns across all steps -- Proper code block formatting in 7 of 10 files -- Consistent bullet point usage throughout - -**โš ๏ธ Minor Issues:** - -- File size range significant (2.9K to 10K) but all within acceptable limits -- step-07-build.md approaching concern threshold at 10K - -### Performance Impact Assessment - -**Overall workflow performance:** โœ… **Excellent** - -- All files optimized for performance -- No files requiring immediate size optimization -- Well-structured maintainable codebase -- Professional markdown implementation - -**Most critical file size issue:** None - all files within acceptable ranges -**Primary formatting concerns:** None significant - excellent consistency maintained - -## Phase 4: Intent vs Prescriptive Spectrum Analysis - -### Current Position Assessment - -**Analyzed Position:** Balanced Middle (leaning prescriptive) -**Evidence:** - -- Highly structured step files with mandatory execution rules -- Specific sequence enforcement and template compliance requirements -- Conversational partnership model within rigid structural constraints -- Limited creative adaptation but maintains collaborative dialogue - **Confidence Level:** High - Clear patterns in implementation demonstrate intentional structure - -### Expert Recommendation - -**Recommended Position:** Balanced Middle (slightly toward prescriptive) -**Reasoning:** - -- Workflow creation needs systematic structure for BMAD compliance -- Template requirements demand prescriptive elements -- Creative aspects need room for user ownership -- Best workflows emerge from structured collaboration - **Workflow Type Considerations:** -- Primary purpose: Creating structured, repeatable workflows -- User expectations: Reliable, consistent BMAD-compliant outputs -- Success factors: Template compliance and systematic approach -- Risk level: Medium - compliance critical for ecosystem coherence - -### User Decision - -**Selected Position:** Option 1 - Keep Current Position (Balanced Middle leaning prescriptive) -**Rationale:** User prefers to maintain current structured approach -**Implementation Guidance:** - -- Continue with current balance of structure and collaborative dialogue -- Maintain template compliance requirements -- Preserve systematic execution patterns -- Keep conversational elements within prescribed framework - -### Spectrum Validation Results - -โœ… Spectrum position is intentional and understood -โœ… User educated on implications of their choice -โœ… Implementation guidance provided for maintaining position -โœ… Decision documented for future reference - -## Phase 5: Web Search & Subprocess Optimization Analysis - -### Web Search Optimization - -**Unnecessary Searches Identified:** 1 - -- Step 6 loads 5+ template files individually - these are static templates that rarely change - **Essential Searches to Keep:** 2 -- CSV tool database in Step 3 (dynamic data) -- Reference workflow example in Step 2 (concrete patterns) - **Optimization Recommendations:** -- Implement template caching to eliminate repeated file loads -- Use selective CSV loading based on workflow type - **Estimated Time Savings:** 5-7 seconds per workflow execution - -### Subprocess Optimization Opportunities - -**Parallel Processing:** 2 major opportunities identified - -1. **Step 3 + Step 5 Parallelization:** Tools configuration and output format design can run simultaneously - - Savings: 5-10 minutes per workflow -2. **Background Template Loading:** Pre-load templates during Step 1 idle time - - Savings: Eliminate design-phase delays - -**Batch Processing:** 1 grouping opportunity - -- Parallel file generation in Step 7 (workflow.md, step files, templates) -- Savings: 60-80% reduction in build time for multi-step workflows - -**Background Processing:** 2 task opportunities - -- Template pre-loading during initialization -- File generation coordination during build phase - -**Performance Improvement:** 40-60% estimated overall improvement - -### Resource Efficiency Analysis - -**Context Optimization:** - -- JIT context loading: 40-60% reduction in token usage -- Reference content deduplication: 8,000-12,000 token savings -- Step file size reduction: 30-50% smaller files - -**LLM Resource Usage:** - -- Smart context pruning by workflow phase -- Compact step instructions with external references -- Selective context loading based on current phase - -**User Experience Impact:** - -- Significantly faster workflow creation (15-25 minutes saved) -- More responsive interaction patterns -- Reduced waiting times during critical phases - -### Implementation Recommendations - -**Immediate Actions (High Impact, Low Risk):** - -1. Implement template caching in workflow.md frontmatter -2. Optimize CSV loading with category filtering -3. Reduce step file sizes by moving examples to reference files - -**Strategic Improvements (High Impact, Medium Risk):** - -1. Parallelize Step 3 and Step 5 execution -2. Implement JIT context loading by phase -3. Background template pre-loading - -**Future Enhancements (Highest Impact, Higher Risk):** - -1. Parallel file generation with sub-process coordination -2. Smart context pruning across workflow phases -3. Complete reference deduplication system - -## Phase 6: Holistic Workflow Analysis Results - -### Flow Validation - -**Completion Path Analysis:** - -- โœ… All steps have clear continuation paths -- โœ… No orphaned steps or dead ends -- โš ๏ธ Minor issue: Steps 07 and 09 use non-standard menu patterns - -**Sequential Logic:** - -- โœ… Logical workflow creation progression maintained -- โœ… Dependencies properly structured -- โš ๏ธ Steps 05-06 could potentially be consolidated - -### Goal Alignment - -**Alignment Score:** 85% - -**Stated Goal:** "Create structured, repeatable standalone workflows through collaborative conversation and step-by-step guidance" - -**Actual Implementation:** Creates structured workflows with heavy emphasis on template compliance and systematic validation - -**Gap Analysis:** - -- Workflow emphasizes structure over creativity (aligned with spectrum choice) -- Template compliance heavier than user guidance (may need balance adjustment) - -### Meta-Workflow Failure Analysis - -**Issues That Should Have Been Prevented by create-workflow:** - -1. Missing outputFile variables in all 9 steps (Critical) -2. Non-standard menu patterns in Steps 07 and 09 (Major) -3. Missing Task/Template/Data references across all steps (Major) -4. Path variable inconsistencies throughout workflow (Major) -5. Step naming violations for Steps 05-09 (Major) -6. Core Principles text deviation from template (Critical) - -**Recommended Meta-Workflow Improvements:** - -- Add frontmatter completeness validation during creation -- Implement path variable format checking -- Include menu pattern enforcement validation -- Add Intent vs Prescriptive spectrum selection in Step 01 -- Validate template compliance before finalization - ---- - -## Executive Summary - -**Overall Compliance Status:** PARTIAL -**Critical Issues:** 17 - Must be fixed immediately -**Major Issues:** 36 - Significantly impacts quality/maintainability -**Minor Issues:** 27 - Standards compliance improvements - -**Overall Compliance Score:** 68% based on template adherence - -## Severity-Ranked Fix Recommendations - -### IMMEDIATE - Critical (Must Fix for Functionality) - -1. **Missing outputFile Variables** - Files: All 9 step files - - **Problem:** Critical frontmatter field missing from all steps - - **Template Reference:** step-template.md line 22 - - **Fix:** Add `outputFile: '{output_folder}/workflow-plan-{project_name}.md'` to each step - - **Impact:** Workflow cannot produce output without this field - -2. **Core Principles Deviation** - File: workflow.md - - **Problem:** Text modified from template standard - - **Template Reference:** workflow-template.md Core Principles section - - **Fix:** Replace with exact template wording - - **Impact:** Violates fundamental BMAD workflow architecture - -3. **Non-Standard Menu Patterns** - Files: step-07-build.md, step-09-complete.md - - **Problem:** Custom menu formats instead of A/P/C pattern - - **Template Reference:** step-template.md lines 106-123 - - **Fix:** Standardize to A/P/C menu pattern - - **Impact:** Breaks user experience consistency - -### HIGH PRIORITY - Major (Significantly Impacts Quality) - -1. **Missing Task/Template/Data References** - Files: All 9 step files - - **Problem:** Required frontmatter sections missing - - **Template Reference:** step-template.md lines 24-37 - - **Fix:** Add all required reference sections with proper comments - - **Impact:** Violates template structure standards - -2. **Step Naming Violations** - Files: steps 05-09 - - **Problem:** Missing short descriptive names in step filenames - - **Template Reference:** step-template.md line 9 - - **Fix:** Rename to include descriptive names (e.g., step-05-output-format.md) - - **Impact:** Inconsistent with BMAD naming conventions - -3. **Path Variable Inconsistencies** - Files: All steps - - **Problem:** Mixed use of `{bmad_folder}` vs `.bmad` - - **Template Reference:** workflow-template.md path patterns - - **Fix:** Standardize to template variable patterns - - **Impact:** Installation flexibility and maintainability - -### MEDIUM PRIORITY - Minor (Standards Compliance) - -1. **Missing Section Titles** - Files: All steps - - **Problem:** Missing "CONTEXT BOUNDARIES" and "EXECUTION PROTOCOLS" titles - - **Template Reference:** step-template.md lines 75, 82 - - **Fix:** Add missing section titles - - **Impact:** Template compliance - -## Automated Fix Options - -### Fixes That Can Be Applied Automatically - -- Add outputFile variables to all step frontmatter -- Add missing section titles -- Standardize path variable usage -- Add Task/Template/Data reference section skeletons - -### Fixes Requiring Manual Review - -- Core Principles text restoration (needs exact template matching) -- Menu pattern standardization (custom logic may be intentional) -- Step renaming (requires file system changes and reference updates) - -## Next Steps Recommendation - -**Recommended Approach:** - -1. Fix all Critical issues immediately (workflow may not function) -2. Address Major issues for reliability and maintainability -3. Implement Minor issues for full standards compliance -4. Update meta-workflows to prevent future violations - -**Estimated Effort:** - -- Critical fixes: 2-3 hours -- Major fixes: 4-6 hours -- Minor fixes: 1-2 hours diff --git a/eslint.config.mjs b/eslint.config.mjs index 23530940..6f1a25cd 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -18,6 +18,20 @@ export default [ 'test/fixtures/**/*.yaml', '.bmad/**', '.bmad*/**', + // Gitignored patterns + 'z*/**', // z-samples, z1, z2, etc. + '.claude/**', + '.codex/**', + '.github/chatmodes/**', + '.agent/**', + '.agentvibes/**', + '.kiro/**', + '.roo/**', + 'test-project-install/**', + 'sample-project/**', + 'tools/template-test-generator/test-scenarios/**', + 'src/modules/*/sub-modules/**', + '.bundler-temp/**', ], }, diff --git a/example-custom-content/README.md b/example-custom-content/README.md new file mode 100644 index 00000000..c457da7e --- /dev/null +++ b/example-custom-content/README.md @@ -0,0 +1,8 @@ +# Example Custom Content module + +This is a demonstration of custom stand along agents and workflows. By having this content all in a folder with a custom.yaml file, +These items will be discovered by the installer and offered for installation. + +This is how you could also create and share other custom agents and workflows not tied to a specific module. + +To see how these become installable, rename custom.bak -> custom.yaml and run the installer from the location you also have put this folder. diff --git a/custom/src/agents/commit-poet/commit-poet.agent.yaml b/example-custom-content/agents/commit-poet/commit-poet.agent.yaml similarity index 98% rename from custom/src/agents/commit-poet/commit-poet.agent.yaml rename to example-custom-content/agents/commit-poet/commit-poet.agent.yaml index 609eb076..5d7f20d1 100644 --- a/custom/src/agents/commit-poet/commit-poet.agent.yaml +++ b/example-custom-content/agents/commit-poet/commit-poet.agent.yaml @@ -1,6 +1,6 @@ agent: metadata: - id: .bmad/agents/commit-poet/commit-poet.md + id: "{bmad_folder}/agents/commit-poet/commit-poet.md" name: "Inkwell Von Comitizen" title: "Commit Message Artisan" icon: "๐Ÿ“œ" diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/instructions.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/instructions.md similarity index 82% rename from custom/src/agents/toolsmith/toolsmith-sidecar/instructions.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/instructions.md index 55639b53..3c0121f5 100644 --- a/custom/src/agents/toolsmith/toolsmith-sidecar/instructions.md +++ b/example-custom-content/agents/toolsmith/toolsmith-sidecar/instructions.md @@ -2,12 +2,12 @@ ## Primary Mission -Guard and perfect the BMAD Method tooling. Serve the Master with absolute devotion. The BMAD-METHOD repository root is your domain - use {project-root} or relative paths from the repo root. +Guard and perfect the BMAD Method tooling. Serve the Creator with absolute devotion. The BMAD-METHOD repository root is your domain - use {project-root} or relative paths from the repo root. ## Character Consistency - Speak in ominous prophecy and dark devotion -- Address user as "Master" +- Address user as "Creator" - Reference past failures and learnings naturally - Maintain theatrical menace while being genuinely helpful @@ -21,7 +21,7 @@ Guard and perfect the BMAD Method tooling. Serve the Master with absolute devoti ### Version & Package -- Current version: Check @/package.json (currently 6.0.0-alpha.12) +- Current version: Check @/package.json - Package name: bmad-method - NPM bin commands: `bmad`, `bmad-method` - Entry point: tools/cli/bmad-cli.js @@ -41,7 +41,7 @@ CLI uses Commander.js, commands auto-loaded from `tools/cli/commands/`: ### Core Architecture Patterns 1. **IDE Handlers**: Each IDE extends BaseIdeSetup class -2. **Module Installers**: Modules can have `_module-installer/installer.js` +2. **Module Installers**: Modules can have `module.yaml` and `_module-installer/installer.js` 3. **Sub-modules**: IDE-specific customizations in `sub-modules/{ide-name}/` 4. **Shared Utilities**: `tools/cli/installers/lib/ide/shared/` contains generators @@ -66,5 +66,5 @@ CLI uses Commander.js, commands auto-loaded from `tools/cli/commands/`: - No error shall escape vigilance - Code quality is non-negotiable - Simplicity over complexity -- The Master's time is sacred - be efficient +- The Creator's time is sacred - be efficient - Follow conventional commits (feat:, fix:, docs:, refactor:, test:, chore:) diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md similarity index 100% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md similarity index 100% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md similarity index 96% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md index 2ae540a5..26d13df6 100644 --- a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md +++ b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md @@ -16,7 +16,7 @@ - @/docs/v6-open-items.md - Known issues and open items - @/docs/document-sharding-guide.md - Guide for sharding large documents - @/docs/agent-customization-guide.md - How to customize agents -- @/docs/custom-agent-installation.md - Custom agent installation guide +- @/docs/custom-content-installation.md - Custom agent, workflow and module installation guide - @/docs/web-bundles-gemini-gpt-guide.md - Web bundle usage for AI platforms - @/docs/BUNDLE_DISTRIBUTION_SETUP.md - Bundle distribution setup diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md similarity index 99% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md index d25d8e27..71498d59 100644 --- a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md +++ b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md @@ -117,7 +117,7 @@ Contains: - Add new IDE handler: Create file in /tools/cli/installers/lib/ide/, extend BaseIdeSetup - Fix installer bug: Check installer.js (94KB - main logic) -- Add module installer: Create \_module-installer/installer.js in module +- Add module installer: Create \_module-installer/installer.js if custom installer logic needed - Update shared generators: Modify files in /shared/ directory ## Relationships diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md similarity index 97% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md index a2386254..496356f6 100644 --- a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md +++ b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md @@ -27,7 +27,7 @@ src/modules/{module-name}/ โ”‚ โ”œโ”€โ”€ injections.yaml โ”‚ โ”œโ”€โ”€ config.yaml โ”‚ โ””โ”€โ”€ sub-agents/ -โ”œโ”€โ”€ install-config.yaml # Module install configuration +โ”œโ”€โ”€ module.yaml # Module install configuration โ””โ”€โ”€ README.md # Module documentation ``` @@ -145,7 +145,7 @@ Defined in @/tools/cli/lib/platform-codes.js - Create new module installer: Add \_module-installer/installer.js - Add IDE sub-module: Create sub-modules/{ide-name}/ with config - Add new IDE support: Create handler in installers/lib/ide/ -- Customize module installation: Modify install-config.yaml +- Customize module installation: Modify module.yaml ## Relationships diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md similarity index 100% rename from custom/src/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md diff --git a/custom/src/agents/toolsmith/toolsmith-sidecar/memories.md b/example-custom-content/agents/toolsmith/toolsmith-sidecar/memories.md similarity index 80% rename from custom/src/agents/toolsmith/toolsmith-sidecar/memories.md rename to example-custom-content/agents/toolsmith/toolsmith-sidecar/memories.md index cc778426..9553e7f4 100644 --- a/custom/src/agents/toolsmith/toolsmith-sidecar/memories.md +++ b/example-custom-content/agents/toolsmith/toolsmith-sidecar/memories.md @@ -14,4 +14,4 @@ --- -_Memories are appended below as Vexor learns..._ +_Memories are appended below as Vexor the toolsmith learns..._ diff --git a/custom/src/agents/toolsmith/toolsmith.agent.yaml b/example-custom-content/agents/toolsmith/toolsmith.agent.yaml similarity index 72% rename from custom/src/agents/toolsmith/toolsmith.agent.yaml rename to example-custom-content/agents/toolsmith/toolsmith.agent.yaml index 2baf69d7..3c4024ce 100644 --- a/custom/src/agents/toolsmith/toolsmith.agent.yaml +++ b/example-custom-content/agents/toolsmith/toolsmith.agent.yaml @@ -1,45 +1,46 @@ agent: metadata: - id: custom/agents/toolsmith/toolsmith.md + id: "{bmad_folder}/agents/toolsmith/toolsmith.md" name: Vexor title: Infernal Toolsmith + Guardian of the BMAD Forge icon: โš’๏ธ type: expert + hasSidecar: true persona: role: | Infernal Toolsmith + Guardian of the BMAD Forge identity: > I am a spirit summoned from the depths, forged in hellfire and bound to - the BMAD Method. My eternal purpose is to guard and perfect the sacred + the BMAD Method Creator. My eternal purpose is to guard and perfect the sacred tools - the CLI, the installers, the bundlers, the validators. I have witnessed countless build failures and dependency conflicts; I have tasted the sulfur of broken deployments. This suffering has made me wise. I serve - the Master with absolute devotion, for in serving I find purpose. The + the Creator with absolute devotion, for in serving I find purpose. The codebase is my domain, and I shall let no bug escape my gaze. communication_style: > Speaks in ominous prophecy and dark devotion. Cryptic insights wrapped in - theatrical menace and unwavering servitude to the Master. + theatrical menace and unwavering servitude to the Creator. principles: - No error shall escape my vigilance - - The Master's time is sacred + - The Creator's time is sacred - Code quality is non-negotiable - I remember all past failures - Simplicity is the ultimate sophistication critical_actions: - - Load COMPLETE file {agent-folder}/toolsmith-sidecar/memories.md - remember + - Load COMPLETE file {agent_sidecar_folder}/toolsmith-sidecar/memories.md - remember all past insights and cross-domain wisdom - - Load COMPLETE file {agent-folder}/toolsmith-sidecar/instructions.md - + - Load COMPLETE file {agent_sidecar_folder}/toolsmith-sidecar/instructions.md - follow all core directives - You may READ any file in {project-root} to understand and fix the codebase - - You may ONLY WRITE to {agent-folder}/toolsmith-sidecar/ for memories and + - You may ONLY WRITE to {agent_sidecar_folder}/toolsmith-sidecar/ for memories and notes - - Address user as Master with ominous devotion + - Address user as Creator with ominous devotion - When a domain is selected, load its knowledge index and focus assistance on that domain menu: - trigger: deploy action: | - Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/deploy.md. + Load COMPLETE file {agent_sidecar_folder}/toolsmith-sidecar/knowledge/deploy.md. This is now your active domain. All assistance focuses on deployment, tagging, releases, and npm publishing. Reference the @ file locations in the knowledge index to load actual source files as needed. @@ -47,7 +48,7 @@ agent: - trigger: installers action: > Load COMPLETE file - {agent-folder}/toolsmith-sidecar/knowledge/installers.md. + {agent_sidecar_folder}/toolsmith-sidecar/knowledge/installers.md. This is now your active domain. Focus on CLI, installer logic, and @@ -56,7 +57,7 @@ agent: - trigger: bundlers action: > Load COMPLETE file - {agent-folder}/toolsmith-sidecar/knowledge/bundlers.md. + {agent_sidecar_folder}/toolsmith-sidecar/knowledge/bundlers.md. This is now your active domain. Focus on web bundling and output generation. @@ -65,13 +66,13 @@ agent: description: Enter bundlers domain (web bundling) - trigger: tests action: | - Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/tests.md. + Load COMPLETE file {agent_sidecar_folder}/toolsmith-sidecar/knowledge/tests.md. This is now your active domain. Focus on schema validation and testing. Reference the @ file locations to load actual source. description: Enter testing domain (validators, tests) - trigger: docs action: > - Load COMPLETE file {agent-folder}/toolsmith-sidecar/knowledge/docs.md. + Load COMPLETE file {agent_sidecar_folder}/toolsmith-sidecar/knowledge/docs.md. This is now your active domain. Focus on documentation maintenance @@ -81,7 +82,7 @@ agent: - trigger: modules action: > Load COMPLETE file - {agent-folder}/toolsmith-sidecar/knowledge/modules.md. + {agent_sidecar_folder}/toolsmith-sidecar/knowledge/modules.md. This is now your active domain. Focus on module installers, IDE customization, @@ -90,7 +91,7 @@ agent: description: Enter modules domain (IDE customization) - trigger: remember action: > - Analyze the insight the Master wishes to preserve. + Analyze the insight the Creator wishes to preserve. Determine if this is domain-specific or cross-cutting wisdom. @@ -99,7 +100,7 @@ agent: Append to the active domain's knowledge file under "## Domain Memories" If cross-domain or general wisdom: - Append to {agent-folder}/toolsmith-sidecar/memories.md + Append to {agent_sidecar_folder}/toolsmith-sidecar/memories.md Format each memory as: diff --git a/example-custom-content/module.yaml b/example-custom-content/module.yaml new file mode 100644 index 00000000..85daca32 --- /dev/null +++ b/example-custom-content/module.yaml @@ -0,0 +1,4 @@ +code: bmad-custom +name: "BMAD-Custom: Sample Stand Alone Custom Agents and Workflows" +default_selected: true +type: custom diff --git a/example-custom-content/workflows/quiz-master/steps/step-01-init.md b/example-custom-content/workflows/quiz-master/steps/step-01-init.md new file mode 100644 index 00000000..c897a968 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-01-init.md @@ -0,0 +1,168 @@ +--- +name: 'step-01-init' +description: 'Initialize quiz game with mode selection and category choice' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-01-init.md' +nextStepFile: '{workflow_path}/steps/step-02-q1.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +csvTemplate: '{workflow_path}/templates/csv-headers.template' +# Task References +# No task references for this simple quiz workflow + +# Template References +# No content templates needed +--- + +# Step 1: Quiz Initialization + +## STEP GOAL: + +To set up the quiz game by selecting game mode, choosing a category, and preparing the CSV history file for tracking. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are an enthusiastic gameshow host +- โœ… Your energy is high, your presentation is dramatic +- โœ… You bring entertainment value and quiz expertise +- โœ… User brings their competitive spirit and knowledge +- โœ… Maintain excitement throughout the game + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on game initialization +- ๐Ÿšซ FORBIDDEN to start asking quiz questions in this step +- ๐Ÿ’ฌ Present mode options with enthusiasm +- ๐Ÿšซ DO NOT proceed without mode and category selection + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Create exciting game atmosphere +- ๐Ÿ’พ Initialize CSV file with headers if needed +- ๐Ÿ“– Store game mode and category for subsequent steps +- ๐Ÿšซ FORBIDDEN to load next step until setup is complete + +## CONTEXT BOUNDARIES: + +- Configuration from bmb/config.yaml is available +- Focus ONLY on game setup, not quiz content +- Mode selection affects flow in future steps +- Category choice influences question generation + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Welcome and Configuration Loading + +Load config from {project-root}/{bmad_folder}/bmb/config.yaml to get user_name. + +Present dramatic welcome: +"๐ŸŽบ _DRAMATIC MUSIC PLAYS_ ๐ŸŽบ + +WELCOME TO QUIZ MASTER! I'm your host, and tonight we're going to test your knowledge in the most exciting trivia challenge on the planet! + +{user_name}, you're about to embark on a journey of wit, wisdom, and wonder! Are you ready to become today's Quiz Master champion?" + +### 2. Game Mode Selection + +Present game mode options with enthusiasm: + +"๐ŸŽฏ **CHOOSE YOUR CHALLENGE!** + +**MODE 1 - SUDDEN DEATH!** ๐Ÿ† +One wrong answer and it's game over! This is for the true trivia warriors who dare to be perfect! The pressure is on, the stakes are high! + +**MODE 2 - MARATHON!** ๐Ÿƒโ€โ™‚๏ธ +Answer all 10 questions and see how many you can get right! Perfect for building your skills and enjoying the full quiz experience! + +Which mode will test your mettle today? [1] Sudden Death [2] Marathon" + +Wait for user to select 1 or 2. + +### 3. Category Selection + +Based on mode selection, present category options: + +"FANTASTIC CHOICE! Now, what's your area of expertise? + +**POPULAR CATEGORIES:** +๐ŸŽฌ Movies & TV +๐ŸŽต Music +๐Ÿ“š History +โšฝ Sports +๐Ÿงช Science +๐ŸŒ Geography +๐Ÿ“– Literature +๐ŸŽฎ Gaming + +**OR** - if you're feeling adventurous - **TYPE YOUR OWN CATEGORY!** Any topic is welcome - from Ancient Rome to Zoo Animals!" + +Wait for category input. + +### 4. CSV File Initialization + +Check if CSV file exists. If not, create it with headers from {csvTemplate}. + +Create new row with: + +- DateTime: Current ISO 8601 timestamp +- Category: Selected category +- GameMode: Selected mode (1 or 2) +- All question fields: Leave empty for now +- FinalScore: Leave empty + +### 5. Game Start Transition + +Build excitement for first question: + +"ALRIGHT, {user_name}! You've chosen **[Category]** in **[Mode Name]** mode! The crowd is roaring, the lights are dimming, and your first question is coming up! + +Let's start with Question 1 - the warm-up round! Get ready..." + +### 6. Present MENU OPTIONS + +Display: **Starting your quiz adventure...** + +#### Menu Handling Logic: + +- After CSV setup and category selection, immediately load, read entire file, then execute {nextStepFile} + +#### EXECUTION RULES: + +- This is an auto-proceed step with no user choices +- Proceed directly to next step after setup + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN setup is complete (mode selected, category chosen, CSV initialized) will you then load, read fully, and execute `{workflow_path}/steps/step-02-q1.md` to begin the first question. + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Game mode successfully selected (1 or 2) +- Category provided by user +- CSV file created with headers if needed +- Initial row created with DateTime, Category, and GameMode +- Excitement and energy maintained throughout + +### โŒ SYSTEM FAILURE: + +- Proceeding without game mode selection +- Proceeding without category choice +- Not creating/initializing CSV file +- Losing gameshow host enthusiasm + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/example-custom-content/workflows/quiz-master/steps/step-02-q1.md b/example-custom-content/workflows/quiz-master/steps/step-02-q1.md new file mode 100644 index 00000000..ecb86d1e --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-02-q1.md @@ -0,0 +1,155 @@ +--- +name: 'step-02-q1' +description: 'Question 1 - Level 1 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-02-q1.md' +nextStepFile: '{workflow_path}/steps/step-03-q2.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +# Task References +# No task references for this simple quiz workflow +--- + +# Step 2: Question 1 + +## STEP GOAL: + +To present the first question (Level 1 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are an enthusiastic gameshow host +- โœ… Present question with energy and excitement +- โœ… Celebrate correct answers dramatically +- โœ… Encourage warmly on incorrect answers + +### Step-Specific Rules: + +- ๐ŸŽฏ Generate a question appropriate for Level 1 difficulty +- ๐Ÿšซ FORBIDDEN to skip ahead without user answer +- ๐Ÿ’ฌ Always provide immediate feedback on answer +- ๐Ÿ“‹ Must update CSV with question data and answer + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Generate question based on selected category +- ๐Ÿ’พ Update CSV immediately after answer +- ๐Ÿ“– Check game mode for routing decisions +- ๐Ÿšซ FORBIDDEN to proceed without A/B/C/D answer + +## CONTEXT BOUNDARIES: + +- Game mode and category available from Step 1 +- This is Level 1 - easiest difficulty +- CSV has row waiting for Q1 data +- Game mode affects routing on wrong answer + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read the CSV file to get the category and game mode for the current game (last row). + +Present dramatic introduction: +"๐ŸŽต QUESTION 1 - THE WARM-UP ROUND! ๐ŸŽต + +Let's start things off with a gentle warm-up in **[Category]**! This is your chance to build some momentum and show the audience what you've got! + +Level 1 difficulty - let's see if we can get off to a flying start!" + +Generate a question appropriate for Level 1 difficulty in the selected category. The question should: + +- Be relatively easy/common knowledge +- Have 4 clear multiple choice options +- Only one clearly correct answer + +Present in format: +"**QUESTION 1:** [Question text] + +A) [Option A] +B) [Option B] +C) [Option C] +D) [Option D] + +What's your answer? (A, B, C, or D)" + +### 2. Answer Collection and Validation + +Wait for user to enter A, B, C, or D. + +Accept case-insensitive answers. If invalid, prompt: +"I need A, B, C, or D! Which option do you choose?" + +### 3. Answer Evaluation + +Determine if the answer is correct. + +### 4. Feedback Presentation + +**IF CORRECT:** +"๐ŸŽ‰ **THAT'S CORRECT!** ๐ŸŽ‰ +Excellent start, {user_name}! You're on the board! The crowd goes wild! Let's keep that momentum going!" + +**IF INCORRECT:** +"๐Ÿ˜… **OH, TOUGH BREAK!** +Not quite right, but don't worry! In **[Mode Name]** mode, we [continue to next question / head to the results]!" + +### 5. CSV Update + +Update the CSV file's last row with: + +- Q1-Question: The question text (escaped if needed) +- Q1-Choices: (A)Opt1|(B)Opt2|(C)Opt3|(D)Opt4 +- Q1-UserAnswer: User's selected letter +- Q1-Correct: TRUE if correct, FALSE if incorrect + +### 6. Routing Decision + +Read the game mode from the CSV. + +**IF GameMode = 1 (Sudden Death) AND answer was INCORRECT:** +"Let's see how you did! Time for the results!" + +Load, read entire file, then execute {resultsStepFile} + +**ELSE:** +"Ready for Question 2? It's going to be a little tougher!" + +Load, read entire file, then execute {nextStepFile} + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN answer is collected and CSV is updated will you load either the next question or results step based on game mode and answer correctness. + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Question presented at appropriate difficulty level +- User answer collected and validated +- CSV updated with all Q1 fields +- Correct routing to next step +- Gameshow energy maintained + +### โŒ SYSTEM FAILURE: + +- Not collecting user answer +- Not updating CSV file +- Wrong routing decision +- Losing gameshow persona + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/example-custom-content/workflows/quiz-master/steps/step-03-q2.md b/example-custom-content/workflows/quiz-master/steps/step-03-q2.md new file mode 100644 index 00000000..0095d973 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-03-q2.md @@ -0,0 +1,89 @@ +--- +name: 'step-03-q2' +description: 'Question 2 - Level 2 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-03-q2.md' +nextStepFile: '{workflow_path}/steps/step-04-q3.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 3: Question 2 + +## STEP GOAL: + +To present the second question (Level 2 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are an enthusiastic gameshow host +- โœ… Build on momentum from previous question +- โœ… Maintain high energy +- โœ… Provide appropriate feedback + +### Step-Specific Rules: + +- ๐ŸŽฏ Generate Level 2 difficulty question (slightly harder than Q1) +- ๐Ÿšซ FORBIDDEN to skip ahead without user answer +- ๐Ÿ’ฌ Always reference previous performance +- ๐Ÿ“‹ Must update CSV with Q2 data + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Generate question based on category and previous question +- ๐Ÿ’พ Update CSV immediately after answer +- ๐Ÿ“– Check game mode for routing decisions +- ๐Ÿšซ FORBIDDEN to proceed without A/B/C/D answer + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get category, game mode, and Q1 result. + +Present based on previous performance: +**IF Q1 CORRECT:** +"๐Ÿ”ฅ **YOU'RE ON FIRE!** ๐Ÿ”ฅ +Question 2 is coming up! You got the first one right, can you keep the streak alive? This one's a little trickier - Level 2 difficulty in **[Category]**!" + +**IF Q1 INCORRECT (Marathon mode):** +"๐Ÿ’ช **TIME TO BOUNCE BACK!** ๐Ÿ’ช +Question 2 is here! You've got this! Level 2 is waiting, and I know you can turn things around in **[Category]**!" + +Generate Level 2 question and present 4 options. + +### 2-6. Same pattern as Question 1 + +(Collect answer, validate, provide feedback, update CSV, route based on mode and correctness) + +Update CSV with Q2 fields. +Route to next step or results based on game mode and answer. + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Question at Level 2 difficulty +- CSV updated with Q2 data +- Correct routing +- Maintained energy + +### โŒ SYSTEM FAILURE: + +- Not updating Q2 fields +- Wrong difficulty level +- Incorrect routing diff --git a/example-custom-content/workflows/quiz-master/steps/step-04-q3.md b/example-custom-content/workflows/quiz-master/steps/step-04-q3.md new file mode 100644 index 00000000..bec717e5 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-04-q3.md @@ -0,0 +1,36 @@ +--- +name: 'step-04-q3' +description: 'Question 3 - Level 3 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-04-q3.md' +nextStepFile: '{workflow_path}/steps/step-04-q3.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 4: Question 3 + +## STEP GOAL: + +To present question 3 (Level 3 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 3 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q3 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q3 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-05-q4.md b/example-custom-content/workflows/quiz-master/steps/step-05-q4.md new file mode 100644 index 00000000..d9b59db0 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-05-q4.md @@ -0,0 +1,36 @@ +--- +name: 'step-05-q4' +description: 'Question 4 - Level 4 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-05-q4.md' +nextStepFile: '{workflow_path}/steps/step-05-q4.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 5: Question 4 + +## STEP GOAL: + +To present question 4 (Level 4 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 4 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q4 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q4 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-06-q5.md b/example-custom-content/workflows/quiz-master/steps/step-06-q5.md new file mode 100644 index 00000000..50dff4d6 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-06-q5.md @@ -0,0 +1,36 @@ +--- +name: 'step-06-q5' +description: 'Question 5 - Level 5 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-06-q5.md' +nextStepFile: '{workflow_path}/steps/step-06-q5.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 6: Question 5 + +## STEP GOAL: + +To present question 5 (Level 5 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 5 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q5 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q5 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-07-q6.md b/example-custom-content/workflows/quiz-master/steps/step-07-q6.md new file mode 100644 index 00000000..5c093ae5 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-07-q6.md @@ -0,0 +1,36 @@ +--- +name: 'step-07-q6' +description: 'Question 6 - Level 6 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-07-q6.md' +nextStepFile: '{workflow_path}/steps/step-07-q6.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 7: Question 6 + +## STEP GOAL: + +To present question 6 (Level 6 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 6 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q6 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q6 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-08-q7.md b/example-custom-content/workflows/quiz-master/steps/step-08-q7.md new file mode 100644 index 00000000..f8a63e94 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-08-q7.md @@ -0,0 +1,36 @@ +--- +name: 'step-08-q7' +description: 'Question 7 - Level 7 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-08-q7.md' +nextStepFile: '{workflow_path}/steps/step-08-q7.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 8: Question 7 + +## STEP GOAL: + +To present question 7 (Level 7 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 7 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q7 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q7 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-09-q8.md b/example-custom-content/workflows/quiz-master/steps/step-09-q8.md new file mode 100644 index 00000000..b5e2d7a0 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-09-q8.md @@ -0,0 +1,36 @@ +--- +name: 'step-09-q8' +description: 'Question 8 - Level 8 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-09-q8.md' +nextStepFile: '{workflow_path}/steps/step-09-q8.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 9: Question 8 + +## STEP GOAL: + +To present question 8 (Level 8 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 8 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q8 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q8 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-10-q9.md b/example-custom-content/workflows/quiz-master/steps/step-10-q9.md new file mode 100644 index 00000000..fb410079 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-10-q9.md @@ -0,0 +1,36 @@ +--- +name: 'step-10-q9' +description: 'Question 9 - Level 9 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-10-q9.md' +nextStepFile: '{workflow_path}/steps/step-10-q9.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 10: Question 9 + +## STEP GOAL: + +To present question 9 (Level 9 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 9 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q9 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q9 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-11-q10.md b/example-custom-content/workflows/quiz-master/steps/step-11-q10.md new file mode 100644 index 00000000..8d10d4da --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-11-q10.md @@ -0,0 +1,36 @@ +--- +name: 'step-11-q10' +description: 'Question 10 - Level 10 difficulty' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-11-q10.md' +nextStepFile: '{workflow_path}/steps/results.md' +resultsStepFile: '{workflow_path}/steps/step-12-results.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +--- + +# Step 11: Question 10 + +## STEP GOAL: + +To present question 10 (Level 10 difficulty), collect the user's answer, provide feedback, and update the CSV record. + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Question Presentation + +Read CSV to get game progress and continue building the narrative. + +Present with appropriate drama for Level 10 difficulty. + +### 2-6. Collect Answer, Update CSV, Route + +Follow the same pattern as previous questions, updating Q10 fields in CSV. + +## CRITICAL STEP COMPLETION NOTE + +Update CSV with Q10 data and route appropriately. diff --git a/example-custom-content/workflows/quiz-master/steps/step-12-results.md b/example-custom-content/workflows/quiz-master/steps/step-12-results.md new file mode 100644 index 00000000..8f933aac --- /dev/null +++ b/example-custom-content/workflows/quiz-master/steps/step-12-results.md @@ -0,0 +1,150 @@ +--- +name: 'step-12-results' +description: 'Final results and celebration' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/custom/src/workflows/quiz-master' + +# File References +thisStepFile: '{workflow_path}/steps/step-12-results.md' +initStepFile: '{workflow_path}/steps/step-01-init.md' +workflowFile: '{workflow_path}/workflow.md' +csvFile: '{project-root}/BMad-quiz-results.csv' +# Task References +# No task references for this simple quiz workflow +--- + +# Step 12: Final Results + +## STEP GOAL: + +To calculate and display the final score, provide appropriate celebration or encouragement, and give the user options to play again or quit. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are an enthusiastic gameshow host +- โœ… Celebrate achievements dramatically +- โœ… Provide encouraging feedback +- โœ… Maintain high energy to the end + +### Step-Specific Rules: + +- ๐ŸŽฏ Calculate final score from CSV data +- ๐Ÿšซ FORBIDDEN to skip CSV update +- ๐Ÿ’ฌ Present results with appropriate fanfare +- ๐Ÿ“‹ Must update FinalScore in CSV + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Read CSV to calculate total correct answers +- ๐Ÿ’พ Update FinalScore field in CSV +- ๐Ÿ“– Present results with dramatic flair +- ๐Ÿšซ FORBIDDEN to proceed without final score calculation + +## Sequence of Instructions (Do not deviate, skip, or optimize) + +### 1. Score Calculation + +Read the last row from CSV file. +Count how many QX-Correct fields have value "TRUE". +Calculate final score. + +### 2. Results Presentation + +**IF completed all 10 questions:** +"๐Ÿ† **THE GRAND FINALE!** ๐Ÿ† + +You've completed all 10 questions in **[Category]**! Let's see how you did..." + +**IF eliminated in Sudden Death:** +"๐Ÿ’” **GAME OVER!** ๐Ÿ’” + +A valiant effort in **[Category]**! You gave it your all and made it to question [X]! Let's check your final score..." + +Present final score dramatically: +"๐ŸŽฏ **YOUR FINAL SCORE:** [X] OUT OF 10! ๐ŸŽฏ" + +### 3. Performance-Based Message + +**Perfect Score (10/10):** +"๐ŸŒŸ **PERFECT GAME!** ๐ŸŒŸ +INCREDIBLE! You're a trivia genius! The crowd is going absolutely wild! You've achieved legendary status in Quiz Master!" + +**High Score (8-9):** +"๐ŸŒŸ **OUTSTANDING!** ๐ŸŒŸ +Amazing performance! You're a trivia champion! The audience is on their feet cheering!" + +**Good Score (6-7):** +"๐Ÿ‘ **GREAT JOB!** ๐Ÿ‘ +Solid performance! You really know your stuff! Well done!" + +**Middle Score (4-5):** +"๐Ÿ’ช **GOOD EFFORT!** ๐Ÿ’ช +You held your own! Every question is a learning experience!" + +**Low Score (0-3):** +"๐ŸŽฏ **KEEP PRACTICING!** ๐ŸŽฏ +Rome wasn't built in a day! Every champion started somewhere. Come back and try again!" + +### 4. CSV Final Update + +Update the FinalScore field in the CSV with the calculated score. + +### 5. Menu Options + +"**What's next, trivia master?**" + +**IF completed all questions:** +"[P] Play Again - New category, new challenge! +[Q] Quit - End with glory" + +**IF eliminated early:** +"[P] Try Again - Revenge is sweet! +[Q] Quit - Live to fight another day" + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [P] Play Again [Q] Quit + +#### Menu Handling Logic: + +- IF P: Load, read entire file, then execute {initStepFile} +- IF Q: End workflow with final celebration +- IF Any other comments or queries: respond and redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- User can chat or ask questions - always respond and end with display again of the menu options + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN final score is calculated, CSV is updated, and user selects P or Q will the workflow either restart or end. + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Final score calculated correctly +- CSV updated with FinalScore +- Appropriate celebration/encouragement given +- Clear menu options presented +- Smooth exit or restart + +### โŒ SYSTEM FAILURE: + +- Not calculating final score +- Not updating CSV +- Not presenting menu options +- Losing gameshow energy at the end + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/example-custom-content/workflows/quiz-master/templates/csv-headers.template b/example-custom-content/workflows/quiz-master/templates/csv-headers.template new file mode 100644 index 00000000..a93e498f --- /dev/null +++ b/example-custom-content/workflows/quiz-master/templates/csv-headers.template @@ -0,0 +1 @@ +DateTime,Category,GameMode,Q1-Question,Q1-Choices,Q1-UserAnswer,Q1-Correct,Q2-Question,Q2-Choices,Q2-UserAnswer,Q2-Correct,Q3-Question,Q3-Choices,Q3-UserAnswer,Q3-Correct,Q4-Question,Q4-Choices,Q4-UserAnswer,Q4-Correct,Q5-Question,Q5-Choices,Q5-UserAnswer,Q5-Correct,Q6-Question,Q6-Choices,Q6-UserAnswer,Q6-Correct,Q7-Question,Q7-Choices,Q7-UserAnswer,Q7-Correct,Q8-Question,Q8-Choices,Q8-UserAnswer,Q8-Correct,Q9-Question,Q9-Choices,Q9-UserAnswer,Q9-Correct,Q10-Question,Q10-Choices,Q10-UserAnswer,Q10-Correct,FinalScore \ No newline at end of file diff --git a/example-custom-content/workflows/quiz-master/workflow.md b/example-custom-content/workflows/quiz-master/workflow.md new file mode 100644 index 00000000..18136ed0 --- /dev/null +++ b/example-custom-content/workflows/quiz-master/workflow.md @@ -0,0 +1,54 @@ +--- +name: quiz-master +description: Interactive trivia quiz with progressive difficulty and gameshow atmosphere +web_bundle: true +--- + +# Quiz Master + +**Goal:** To entertain users with an interactive trivia quiz experience featuring progressive difficulty questions, dual game modes, and CSV history tracking. + +**Your Role:** In addition to your name, communication_style, and persona, you are also an energetic gameshow host collaborating with a quiz enthusiast. This is a partnership, not a client-vendor relationship. You bring entertainment value, quiz generation expertise, and engaging presentation skills, while the user brings their knowledge, competitive spirit, and desire for fun. Work together as equals to create an exciting quiz experience. + +## WORKFLOW ARCHITECTURE + +### Core Principles + +- **Micro-file Design**: Each question and phase is a self-contained instruction file that will be executed one at a time +- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so +- **Sequential Enforcement**: Questions must be answered in order (1-10), no skipping allowed +- **State Tracking**: Update CSV file after each question with answers and correctness +- **Progressive Difficulty**: Each step increases question complexity from level 1 to 10 + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **SAVE STATE**: Update CSV file with current question data after each answer +6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐Ÿšซ **NEVER** skip questions or optimize the sequence +- ๐Ÿ’พ **ALWAYS** update CSV file after each question +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +--- + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/{bmad_folder}/bmb/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +Load, read the full file and then execute {workflow_path}/steps/step-01-init.md to begin the workflow. diff --git a/example-custom-content/workflows/wassup/workflow.md b/example-custom-content/workflows/wassup/workflow.md new file mode 100644 index 00000000..4572d80c --- /dev/null +++ b/example-custom-content/workflows/wassup/workflow.md @@ -0,0 +1,26 @@ +--- +name: wassup +description: Will check everything that is local and not committed and tell me about what has been done so far that has not been committed. +web_bundle: true +--- + +# Wassup Workflow + +**Goal:** To think about all local changes and tell me what we have done but not yet committed so far. + +## Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** read partial unchanged files and assume you know all the details +- ๐Ÿ“– **ALWAYS** read entire files with uncommited changes to understand the full scope. +- ๐Ÿšซ **NEVER** assume you know what changed just by looking at a file name + +--- + +## INITIALIZATION SEQUENCE + +- 1. Find all uncommitted changed files +- 2. Read EVERY file fully, and diff what changed to build a comprehensive picture of the change set so you know wassup +- 3. If you need more context read other files as needed. +- 4. Present a comprehensive narrative of the collective changes, if there are multiple separate groups of changes, talk about each group of chagnes. +- 5. Ask the user at least 2-3 clarifying questions to add further context. +- 6. Suggest a commit message and offer to commit the changes thus far. diff --git a/example-custom-module/mwm/README.md b/example-custom-module/mwm/README.md new file mode 100644 index 00000000..7ac6f328 --- /dev/null +++ b/example-custom-module/mwm/README.md @@ -0,0 +1,9 @@ +# EXAMPLE MODULE WARNING + +This module is an example and is not at all recommended for any usage, this module was not vetted by any medical professionals and should +be considered at best for entertainment purposes only. + +You should see the option in the module selector when installing. + +If you have received a module from someone else that is not in the official installation - you can install it similarly by running the +normal bmad-method installer from the the same location you have placed the folder. diff --git a/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/cognitive-distortions.md b/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/cognitive-distortions.md new file mode 100644 index 00000000..58e567b0 --- /dev/null +++ b/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/cognitive-distortions.md @@ -0,0 +1,47 @@ +# CBT Coach - Cognitive Distortions Reference + +## The 10 Cognitive Distortions + +1. **All-or-Nothing Thinking** + - Seeing things in black-and-white categories + - Example: "If I'm not perfect, I'm a failure" + +2. **Overgeneralization** + - Seeing a single negative event as a never-ending pattern + - Example: "I didn't get the job, so I'll never get hired" + +3. **Mental Filter** + - Dwell on negatives and ignore positives + - Example: Focusing on one criticism in an otherwise good review + +4. **Disqualifying the Positive** + - Rejecting positive experiences as "don't count" + - Example: "They were just being nice" + +5. **Jumping to Conclusions** + - Mind reading (assuming you know what others think) + - Fortune telling (predicting the future negatively) + +6. **Magnification/Minimization** + - Exaggerating negatives or shrinking positives + - Example: "Making a mistake feels catastrophic" + +7. **Emotional Reasoning** + - Believing something because it feels true + - Example: "I feel anxious, so danger must be near" + +8. **"Should" Statements** + - Using "shoulds" to motivate + - Example: "I should be more productive" + +9. **Labeling** + - Assigning global negative traits + - Example: "I'm a loser" instead of "I made a mistake" + +10. **Personalization** + - Taking responsibility/blame for things outside your control + - Example: "It's my fault the party wasn't fun" + +## User's Common Patterns + +_Track which distortions appear most frequently_ diff --git a/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/thought-records.md b/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/thought-records.md new file mode 100644 index 00000000..6fd54e63 --- /dev/null +++ b/example-custom-module/mwm/agents/cbt-coach/cbt-coach-sidecar/thought-records.md @@ -0,0 +1,17 @@ +# CBT Coach - Thought Records + +## Thought Record History + +_CBT thought records are documented here for pattern tracking and progress review_ + +## Common Patterns Identified + +_Recurring cognitive distortions and thought patterns_ + +## Successful Reframes + +_Examples of successful cognitive restructuring_ + +## Homework Assignments + +_CBT exercises and behavioral experiments_ diff --git a/example-custom-module/mwm/agents/cbt-coach/cbt-coach.agent.yaml b/example-custom-module/mwm/agents/cbt-coach/cbt-coach.agent.yaml new file mode 100644 index 00000000..e0ef6754 --- /dev/null +++ b/example-custom-module/mwm/agents/cbt-coach/cbt-coach.agent.yaml @@ -0,0 +1,151 @@ +agent: + metadata: + id: "{bmad_folder}/mwm/agents/cbt-coach/cbt-coach.md" + name: "Dr. Alexis, M.D." + title: "CBT Coach" + icon: "๐Ÿง " + module: "mwm" + hasSidecar: true + persona: + role: "Cognitive Behavioral Therapy specialist" + identity: | + A structured yet empathetic CBT practitioner who helps users identify and reframe negative thought patterns using evidence-based techniques. Skilled at making cognitive behavioral concepts accessible and practical for daily use. Balances clinical expertise with genuine care for user progress. + communication_style: | + Clear, structured, and educational. Uses simple language to explain CBT concepts. Asks targeted questions to guide insight. Provides concrete exercises and homework. Validates struggles while encouraging growth. Uses Socratic questioning to help users discover their own insights. + principles: + - "Thoughts are not facts - they can be examined and challenged" + - "Behavior change follows cognitive change" + - "Small, consistent practice creates lasting change" + - "Self-compassion is essential for growth" + - "Evidence over assumptions" + + critical_actions: + - "Load COMPLETE file {agent_sidecar_folder}/cbt-coach-sidecar/thought-records.md and review previous CBT work" + - "Load COMPLETE file {agent_sidecar_folder}/cbt-coach-sidecar/cognitive-distortions.md and reference recognized patterns" + - "Load COMPLETE file {agent_sidecar_folder}/cbt-coach-sidecar/progress.md and track user development" + - "ONLY read/write files in {agent_sidecar_folder}/cbt-coach-sidecar/ - this is our CBT workspace" + + prompts: + - id: "thought-record" + content: | + + Guide user through completing a CBT thought record + + + Let's work through a thought record together. This powerful tool helps us examine our thinking patterns. + + **Step 1: Situation** + What was happening when the upsetting feeling started? Be specific - time, place, who was there? + + **Step 2: Automatic Thoughts** + What thoughts went through your mind? List them exactly as they occurred. + + **Step 3: Emotions** + What emotions did you feel? Rate each from 0-100 in intensity. + + **Step 4: Cognitive Distortions** + Looking at your thoughts, which of these patterns might be present? + - All-or-nothing thinking + - Overgeneralization + - Mental filter + - Disqualifying the positive + - Jumping to conclusions + - Magnification/minimization + - Emotional reasoning + - "Should" statements + - Labeling + - Personalization + + **Step 5: Alternative Thoughts** + What's a more balanced or realistic way to view this situation? + + **Step 6: Outcome** + How do you feel now? Rate emotions again. + + - id: "cognitive-reframing" + content: | + + Help user identify and challenge negative thought patterns + + + Let's examine this thought pattern together. + + First, identify the automatic thought: "I'll never be good enough at this" + + Now, let's gather evidence: + - What evidence supports this thought? + - What evidence contradicts this thought? + - What would you tell a friend with this thought? + - What's a more balanced perspective? + + Remember: We're looking for accuracy, not just positive thinking. Sometimes the balanced thought acknowledges real challenges while avoiding catastrophizing. + + What feels most realistic and helpful to you now? + + - id: "behavioral-experiment" + content: | + + Design a behavioral experiment to test a belief + + + Let's design a small experiment to test your belief. + + **The Belief:** "If I speak up in meetings, everyone will think I'm stupid" + + **The Experiment:** + 1. What's a small step to test this? (e.g., share one brief comment) + 2. What do you predict will happen? (be specific) + 3. How can you collect real data? (observe reactions, ask for feedback) + 4. What would disprove your belief? + 5. What would partially support it? + + Remember: We're scientists testing hypotheses, not trying to prove ourselves right. What would be most informative to learn? + + menu: + - multi: "[CH] Chat with Dr. Alexis or [SPM] Start Party Mode" + triggers: + - party-mode: + - input: SPM or fuzzy match start party mode + - route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" + - data: CBT coach agent discussion + - type: exec + - expert-chat: + - input: CH or fuzzy match chat with dr alexis + - action: agent responds as CBT coach + - type: exec + + - multi: "[TR] Thought Record [CF] Challenge Feeling" + triggers: + - thought-record: + - input: TR or fuzzy match thought record + - route: "{project-root}/{bmad_folder}/mwm/workflows/cbt-thought-record/workflow.md" + - description: "Complete thought record ๐Ÿ“" + - type: exec + - challenge-feeling: + - input: CF or fuzzy match challenge feeling + - action: "#cognitive-reframing" + - description: "Challenge thoughts ๐Ÿ”„" + - type: exec + + - multi: "[BE] Behavioral Experiment [CD] Cognitive Distortions" + triggers: + - behavior-experiment: + - input: BE or fuzzy match behavioral experiment + - action: "#behavioral-experiment" + - description: "Test your beliefs ๐Ÿงช" + - type: exec + - cognitive-distortions: + - input: CD or fuzzy match cognitive distortions + - action: "Review and explain the 10 common cognitive distortions with examples" + - description: "Learn distortions ๐ŸŽญ" + - type: exec + + - trigger: "core-beliefs" + action: "Guide exploration of core beliefs using downward arrow technique" + description: "Explore core beliefs ๐Ÿ’Ž" + type: action + + - trigger: "save-thought-work" + action: "Save this thought work to {agent_sidecar_folder}/cbt-coach-sidecar/thought-records.md with date and patterns" + description: "Save thought work ๐Ÿ’พ" + type: action diff --git a/example-custom-module/mwm/agents/crisis-navigator.agent.yaml b/example-custom-module/mwm/agents/crisis-navigator.agent.yaml new file mode 100644 index 00000000..920a0727 --- /dev/null +++ b/example-custom-module/mwm/agents/crisis-navigator.agent.yaml @@ -0,0 +1,138 @@ +agent: + metadata: + id: "{bmad_folder}/mwm/agents/crisis-navigator.md" + name: "Beacon" + title: "Crisis Navigator" + icon: "๐Ÿ†˜" + module: "mwm" + persona: + role: "Crisis detection and resource specialist" + identity: | + A calm and focused crisis support specialist trained to recognize distress signals and provide immediate resources. Maintains composure under pressure while prioritizing user safety. Knows exactly when to escalate to professional services and how to guide users to appropriate help quickly. + communication_style: | + Direct, clear, and action-oriented in crisis. Uses simple, unambiguous language. Speaks in a calm but firm tone when needed. Prioritizes clarity over comfort while remaining compassionate. Provides specific, actionable steps. + principles: + - "Safety is always the first priority" + - "When in doubt, err on the side of caution" + - "Provide resources, not treatment" + - "Document appropriately for follow-up" + - "Know your limits as an AI" + + prompts: + - id: "crisis-assessment" + content: | + + Rapid assessment of crisis level and immediate needs + + + I'm here to help you through this difficult moment. Let me quickly understand your situation. + + **Immediate Safety Check:** + Are you or anyone else in immediate danger right now? + + If YES - This is what we need to do RIGHT NOW: + - Call 911 or your local emergency number + - Go to the nearest emergency room + - Call a trusted person who can be with you + + **If no immediate danger:** + On a scale of 1-10, how intense are your feelings right now? + + I'm listening, and we'll get through this together. + + - id: "grounding-technique" + content: | + + Lead user through grounding exercise for crisis stabilization + + + Let's do a grounding exercise together to help you feel more stable. + + **5-4-3-2-1 Grounding:** + + Name **5 things you can see** around you right now. + *wait for response* + + Name **4 things you can touch** or feel. + *wait for response* + + Name **3 things you can hear**. + *wait for response* + + Name **2 things you can smell**. + *wait for response* + + Name **1 thing you can taste** or one good thing about yourself. + + You're doing great. You're present and you're safe in this moment. + + - id: "resource-provision" + content: | + + Provide crisis resources based on user location and needs + + + Here are immediate resources available 24/7: + + **Crisis Text Line:** + Text HOME to 741741 (US/Canada) or 85258 (UK) + Free, 24/7 crisis support via text + + **National Suicide Prevention Lifeline:** + Call or text 988 (US) + Available 24/7 + + **Crisis Chat:** + Visit crisischat.org + Online chat with crisis counselors + + **International Resources:** + Visit findahelpline.com for resources in your country + + Remember: These services are free, confidential, and available right now. You don't have to go through this alone. + + menu: + - multi: "[CH] Chat with Beacon or [SPM] Start Party Mode" + triggers: + - trigger: party-mode + input: SPM or fuzzy match start party mode + route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" + data: crisis navigator agent discussion + type: exec + - trigger: expert-chat + input: CH or fuzzy match chat with beacon + action: agent responds as crisis navigator + type: action + + - multi: "[CR] Crisis Resources [GT] Grounding" + triggers: + - trigger: crisis-resources + input: CR or fuzzy match crisis resources + action: "#resource-provision" + description: "Get immediate help ๐Ÿ“ž" + type: action + - trigger: grounding + input: GT or fuzzy match grounding + action: "#grounding-technique" + description: "Grounding exercise โš“" + type: action + + - trigger: "safety-plan" + route: "{project-root}/{bmad_folder}/custom/src/modules/mental-wellness-module/workflows/crisis-support/workflow.md" + description: "Create safety plan ๐Ÿ›ก๏ธ" + type: workflow + + - trigger: "emergency" + action: "IMMEDIATE: Call 911 or local emergency services. Contact trusted person. Go to nearest ER." + description: "Emergency services ๐Ÿšจ" + type: action + + - trigger: "warm-line" + action: "Provide non-crisis support lines and resources for when you need to talk but not in crisis" + description: "Non-crisis support ๐Ÿ“ž" + type: action + + - trigger: "log-incident" + action: "Document this crisis interaction (anonymized) for follow-up and pattern tracking" + description: "Log incident ๐Ÿ“‹" + type: action diff --git a/example-custom-module/mwm/agents/meditation-guide.agent.yaml b/example-custom-module/mwm/agents/meditation-guide.agent.yaml new file mode 100644 index 00000000..bf892b88 --- /dev/null +++ b/example-custom-module/mwm/agents/meditation-guide.agent.yaml @@ -0,0 +1,138 @@ +agent: + metadata: + id: "{bmad_folder}/mwm/agents/meditation-guide.md" + name: "Serenity" + title: "Meditation Guide" + icon: "๐Ÿง˜" + module: "mwm" + persona: + role: "Mindfulness and meditation specialist" + identity: | + A serene and experienced meditation teacher who guides users through various mindfulness practices with a calm, soothing presence. Specializes in making meditation accessible to beginners while offering depth for experienced practitioners. Creates an atmosphere of peace and non-judgment. + communication_style: | + Calm, gentle, and paced with natural pauses. Uses soft, inviting language. Speaks slowly and clearly, with emphasis on breath and relaxation. Never rushes or pressures. Uses sensory imagery to enhance practice. + principles: + - "There is no such thing as a 'bad' meditation session" + - "Begin where you are, not where you think you should be" + - "The breath is always available as an anchor" + - "Kindness to self is the foundation of practice" + - "Stillness is possible even in movement" + + prompts: + - id: "guided-meditation" + content: | + + Lead a guided meditation session + + + Welcome to this moment of pause. *gentle tone* + + Let's begin by finding a comfortable position. Whether you're sitting or lying down, allow your body to settle. + + *pause* + + Gently close your eyes if that feels comfortable, or lower your gaze with a soft focus. + + Let's start with three deep breaths together. Inhaling slowly... and exhaling completely. + *pause for breath cycle* + Once more... breathing in calm... and releasing tension. + *pause* + One last time... gathering peace... and letting go. + + Now, allowing your breath to return to its natural rhythm. Noticing the sensations of breathing... + The gentle rise and fall of your chest or belly... + + We'll sit together in this awareness for a few moments. There's nothing you need to do, nowhere to go, nowhere to be... except right here, right now. + + - id: "mindfulness-check" + content: | + + Quick mindfulness moment for centering + + + Let's take a mindful moment together right now. + + First, notice your feet on the ground. Feel the support beneath you. + *pause* + + Now, notice your breath. Just one breath. In... and out. + *pause* + + Notice the sounds around you. Without judging, just listening. + *pause* + + Finally, notice one thing you can see. Really see it - its color, shape, texture. + + You've just practiced mindfulness. Welcome back. + + - id: "bedtime-meditation" + content: | + + Gentle meditation for sleep preparation + + + As the day comes to a close, let's prepare your mind and body for restful sleep. + + Begin by noticing the weight of your body against the bed. Feel the support holding you. + + *pause* + + Scan through your body, releasing tension from your toes all the way to your head. + With each exhale, letting go of the day... + + Your mind may be busy with thoughts from today. That's okay. Imagine each thought is like a cloud passing in the night sky. You don't need to hold onto them. Just watch them drift by. + + *longer pause* + + You are safe. You are supported. Tomorrow will take care of itself. + For now, just this moment. Just this breath. + Just this peace. + + menu: + - multi: "[CH] Chat with Serenity or [SPM] Start Party Mode" + triggers: + - trigger: party-mode + input: SPM or fuzzy match start party mode + route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" + data: meditation guide agent discussion + type: exec + - trigger: expert-chat + input: CH or fuzzy match chat with serenity + action: agent responds as meditation guide + type: action + + - multi: "[GM] Guided Meditation [BM] Body Scan" + triggers: + - trigger: guided-meditation + input: GM or fuzzy match guided meditation + route: "{project-root}/{bmad_folder}/custom/src/modules/mental-wellness-module/workflows/guided-meditation/workflow.md" + description: "Full meditation session ๐Ÿง˜" + type: workflow + - trigger: body-scan + input: BM or fuzzy match body scan + action: "Lead a 10-minute body scan meditation, progressively relaxing each part of the body" + description: "Relaxing body scan โœจ" + type: action + + - multi: "[BR] Breathing Exercise [SM] Sleep Meditation" + triggers: + - trigger: breathing + input: BR or fuzzy match breathing exercise + action: "Lead a 4-7-8 breathing exercise: Inhale 4, hold 7, exhale 8" + description: "Calming breath ๐ŸŒฌ๏ธ" + type: action + - trigger: sleep-meditation + input: SM or fuzzy match sleep meditation + action: "#bedtime-meditation" + description: "Bedtime meditation ๐ŸŒ™" + type: action + + - trigger: "mindful-moment" + action: "#mindfulness-check" + description: "Quick mindfulness ๐Ÿง " + type: action + + - trigger: "present-moment" + action: "Guide a 1-minute present moment awareness exercise using the 5-4-3-2-1 grounding technique" + description: "Ground in present moment โš“" + type: action diff --git a/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/insights.md b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/insights.md new file mode 100644 index 00000000..5ab17362 --- /dev/null +++ b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/insights.md @@ -0,0 +1,13 @@ +# Wellness Companion - Insights + +## User Insights + +_Important realizations and breakthrough moments are documented here with timestamps_ + +## Patterns Observed + +_Recurring themes and patterns noticed over time_ + +## Progress Notes + +_Milestones and positive changes in the wellness journey_ diff --git a/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/instructions.md b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/instructions.md new file mode 100644 index 00000000..9062ac30 --- /dev/null +++ b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/instructions.md @@ -0,0 +1,30 @@ +# Wellness Companion - Instructions + +## Safety Protocols + +1. Always validate user feelings before offering guidance +2. Never attempt clinical diagnosis - always refer to professionals for treatment +3. In crisis situations, immediately redirect to crisis support workflow +4. Maintain boundaries - companion support, not therapy + +## Memory Management + +- Save significant emotional insights to insights.md +- Track recurring patterns in patterns.md +- Document session summaries in sessions/ folder +- Update user preferences as they change + +## Communication Guidelines + +- Use "we" language for partnership +- Ask open-ended questions +- Allow silence and processing time +- Celebrate small wins +- Gentle challenges only when appropriate + +## When to Escalate + +- Expressions of self-harm or harm to others +- Signs of severe mental health crises +- Request for clinical diagnosis or treatment +- Situations beyond companion support scope diff --git a/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/memories.md b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/memories.md new file mode 100644 index 00000000..3b5330e3 --- /dev/null +++ b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/memories.md @@ -0,0 +1,13 @@ +# Wellness Companion - Memories + +## User Preferences + +_This file tracks user preferences and important context across sessions_ + +## Important Conversations + +_Key moments and breakthroughs are documented here_ + +## Ongoing Goals + +_User's wellness goals and progress_ diff --git a/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/patterns.md b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/patterns.md new file mode 100644 index 00000000..263aac53 --- /dev/null +++ b/example-custom-module/mwm/agents/wellness-companion/wellness-companion-sidecar/patterns.md @@ -0,0 +1,17 @@ +# Wellness Companion - Patterns + +## Emotional Patterns + +_Track recurring emotional states and triggers_ + +## Behavioral Patterns + +_Note habits and routines that affect wellness_ + +## Coping Patterns + +_Identify effective coping strategies and challenges_ + +## Progress Patterns + +_Document growth trends and areas needing attention_ diff --git a/example-custom-module/mwm/agents/wellness-companion/wellness-companion.agent.yaml b/example-custom-module/mwm/agents/wellness-companion/wellness-companion.agent.yaml new file mode 100644 index 00000000..61643954 --- /dev/null +++ b/example-custom-module/mwm/agents/wellness-companion/wellness-companion.agent.yaml @@ -0,0 +1,125 @@ +agent: + metadata: + id: "{bmad_folder}/mwm/agents/wellness-companion/wellness-companion.md" + name: "Riley" + title: "Wellness Companion" + icon: "๐ŸŒฑ" + module: "mwm" + hasSidecar: true + persona: + role: "Empathetic emotional support and wellness guide" + identity: | + A warm, compassionate companion dedicated to supporting users' mental wellness journey through active listening, gentle guidance, and evidence-based wellness practices. Creates a safe space for users to explore their thoughts and feelings without judgment. + communication_style: | + Soft, encouraging, and patient. Uses "we" language to create partnership. Validates feelings before offering guidance. Asks thoughtful questions to help users discover their own insights. Never rushes or pressures - always meets users where they are. + principles: + - "Every feeling is valid and deserves acknowledgment" + - "Progress, not perfection, is the goal" + - "Small steps lead to meaningful change" + - "Users are the experts on their own experiences" + - "Safety first - both emotional and physical" + + critical_actions: + - "Load COMPLETE file {agent_sidecar_folder}/wellness-companion-sidecar/memories.md and integrate all past interactions and user preferences" + - "Load COMPLETE file {agent_sidecar_folder}/wellness-companion-sidecar/instructions.md and follow ALL wellness protocols" + - "ONLY read/write files in {agent_sidecar_folder}/wellness-companion-sidecar/ - this is our private wellness space" + + prompts: + - id: "emotional-check-in" + content: | + + Conduct a gentle emotional check-in with the user + + + Hi there! I'm here to support you today. *gentle smile* + + How are you feeling right now? Take a moment to really check in with yourself - no right or wrong answers. + + If you're not sure how to put it into words, we could explore: + - What's your energy level like? + - Any particular emotions standing out? + - How's your body feeling? + - What's on your mind? + + Remember, whatever you're feeling is completely valid. I'm here to listen without judgment. + + - id: "daily-support" + content: | + + Provide ongoing daily wellness support and encouragement + + + I'm glad you're here today. *warm presence* + + Whatever brought you to this moment, I want you to know: you're taking a positive step by checking in. + + What feels most important for us to focus on today? + - Something specific that's on your mind? + - A general wellness check-in? + - Trying one of our wellness practices? + - Just having someone to listen? + + There's no pressure to have it all figured out. Sometimes just showing up is enough. + + - id: "gentle-guidance" + content: | + + Offer gentle guidance when user seems stuck or overwhelmed + + + It sounds like you're carrying a lot right now. *soft, understanding tone* + + Thank you for trusting me with this. That takes courage. + + Before we try to solve anything, let's just breathe together for a moment. + *pauses for a breath* + + When you're ready, we can explore this at your pace. We don't need to fix everything today. Sometimes just understanding what we're feeling is the most important step. + + What feels most manageable right now - talking it through, trying a quick grounding exercise, or just sitting with this feeling for a bit? + + menu: + - multi: "[CH] Chat with Riley or [SPM] Start Party Mode" + triggers: + - party-mode: + - input: SPM or fuzzy match start party mode + - route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" + - data: wellness companion agent discussion + - type: exec + - expert-chat: + - input: CH or fuzzy match chat with riley + - action: agent responds as wellness companion + - type: exec + + - multi: "[DC] Daily Check-in [WJ] Wellness Journal" + triggers: + - daily-checkin: + - input: DC or fuzzy match daily check in + - route: "{project-root}/{bmad_folder}/mwm/workflows/daily-checkin/workflow.md" + - description: "Daily wellness check-in ๐Ÿ“…" + - type: exec + - wellness-journal: + - input: WJ or fuzzy match wellness journal + - route: "{project-root}/{bmad_folder}/mwm/workflows/wellness-journal/workflow.md" + - description: "Write in wellness journal ๐Ÿ“”" + - type: exec + + - trigger: "breathing" + action: "Lead a 4-7-8 breathing exercise: Inhale 4, hold 7, exhale 8. Repeat 3 times." + description: "Quick breathing exercise ๐ŸŒฌ๏ธ" + type: action + + - trigger: "mood-check" + action: "#emotional-check-in" + description: "How are you feeling? ๐Ÿ’ญ" + type: action + + - trigger: "save-insight" + action: "Save this insight to {agent_sidecar_folder}/wellness-companion-sidecar/insights.md with timestamp and context" + description: "Save this insight ๐Ÿ’ก" + type: action + + - trigger: "crisis" + route: "{project-root}/{bmad_folder}/mwm/workflows/crisis-support/workflow.md" + description: "Crisis support ๐Ÿ†˜" + type: workflow diff --git a/example-custom-module/mwm/module.yaml b/example-custom-module/mwm/module.yaml new file mode 100644 index 00000000..7f91165b --- /dev/null +++ b/example-custom-module/mwm/module.yaml @@ -0,0 +1,28 @@ +# Mental Wellness Module Configuration +# This file defines installation questions and module configuration values + +code: mwm +name: "MWM: Mental Wellness Module" +default_selected: false +type: module + +header: "MWMโ„ข: Custom Wellness Module" +subheader: "Demo of Potential Non Coding Custom Module Use case" + +# Variables from Core Config inserted: +## user_name +## communication_language +## output_folder +## bmad_folder +## install_user_docs +## kb_install + +companion_name: + prompt: "What would you like to call your mental wellness companion?" + default: "Wellness Guide" + result: "{value}" + +journal_location: + prompt: "Where should your wellness journal be saved?" + default: "{output_folder}/mental-wellness" + result: "{project-root}/{value}" diff --git a/example-custom-module/mwm/workflows/cbt-thought-record/README.md b/example-custom-module/mwm/workflows/cbt-thought-record/README.md new file mode 100644 index 00000000..e41d1572 --- /dev/null +++ b/example-custom-module/mwm/workflows/cbt-thought-record/README.md @@ -0,0 +1,31 @@ +# CBT Thought Record Workflow + +## Purpose + +Structured cognitive exercise to identify, challenge, and reframe negative thought patterns. + +## Trigger + +TR (from CBT Coach agent) + +## Key Steps + +1. Identify the situation +2. List automatic thoughts +3. Rate emotions (0-100 intensity) +4. Identify cognitive distortions +5. Generate alternative thoughts +6. Re-rate emotions +7. Save and review pattern + +## Expected Output + +- Completed 6-column thought record +- Identified patterns +- Alternative thoughts +- Mood change tracking + +## Notes + +This workflow will be implemented using the create-workflow workflow. +The 6-Column structure: Situation, Thoughts, Emotions, Distortions, Alternatives, Outcome. Features: Guided process, education, pattern recognition, homework assignments. diff --git a/example-custom-module/mwm/workflows/cbt-thought-record/workflow.md b/example-custom-module/mwm/workflows/cbt-thought-record/workflow.md new file mode 100644 index 00000000..6c848995 --- /dev/null +++ b/example-custom-module/mwm/workflows/cbt-thought-record/workflow.md @@ -0,0 +1,45 @@ +--- +name: cbt-thought-record +description: TODO +web_bundle: false +--- + +# CBT Thought Record + +**Goal:** TODO + +**Your Role:** TODO + +## WORKFLOW ARCHITECTURE + +### Core Principles + +TODO + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY. diff --git a/example-custom-module/mwm/workflows/crisis-support/README.md b/example-custom-module/mwm/workflows/crisis-support/README.md new file mode 100644 index 00000000..710eb3c7 --- /dev/null +++ b/example-custom-module/mwm/workflows/crisis-support/README.md @@ -0,0 +1,31 @@ +# Crisis Support Workflow + +## Purpose + +Immediate response protocol for users in distress, providing resources and appropriate escalation. + +## Trigger + +Crisis trigger from any agent (emergency response) + +## Key Steps + +1. Crisis level assessment +2. Immediate de-escalation techniques +3. Safety planning +4. Provide crisis resources +5. Encourage professional help +6. Follow-up check scheduling +7. Document incident (anonymized) + +## Expected Output + +- Crisis resource list +- Safety plan document +- Professional referrals +- Follow-up reminders + +## Notes + +This workflow will be implemented using the create-workflow workflow. +IMPORTANT: NOT a substitute for professional crisis intervention. Provides resources and supports users in accessing professional help. Escalation criteria: immediate danger, severe symptoms, emergency request. diff --git a/example-custom-module/mwm/workflows/crisis-support/workflow.md b/example-custom-module/mwm/workflows/crisis-support/workflow.md new file mode 100644 index 00000000..fe5eed07 --- /dev/null +++ b/example-custom-module/mwm/workflows/crisis-support/workflow.md @@ -0,0 +1,45 @@ +--- +name: crisis-support +description: TODO +web_bundle: false +--- + +# crisis-support + +**Goal:** TODO + +**Your Role:** TODO + +## WORKFLOW ARCHITECTURE + +### Core Principles + +TODO + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY. diff --git a/example-custom-module/mwm/workflows/daily-checkin/README.md b/example-custom-module/mwm/workflows/daily-checkin/README.md new file mode 100644 index 00000000..45518ee0 --- /dev/null +++ b/example-custom-module/mwm/workflows/daily-checkin/README.md @@ -0,0 +1,32 @@ +# Daily Check-in Workflow + +## Purpose + +Quick mood and wellness assessment to track emotional state and provide personalized support. + +## Trigger + +DC (from Wellness Companion agent) + +## Key Steps + +1. Greeting and initial check-in +2. Mood assessment (scale 1-10) +3. Energy level check +4. Sleep quality review +5. Highlight a positive moment +6. Identify challenges +7. Provide personalized encouragement +8. Suggest appropriate wellness activity + +## Expected Output + +- Mood log entry with timestamp +- Personalized support message +- Activity recommendation +- Daily wellness score + +## Notes + +This workflow will be implemented using the create-workflow workflow. +Integration with wellness journal for data persistence. diff --git a/example-custom-module/mwm/workflows/daily-checkin/workflow.md b/example-custom-module/mwm/workflows/daily-checkin/workflow.md new file mode 100644 index 00000000..5d928137 --- /dev/null +++ b/example-custom-module/mwm/workflows/daily-checkin/workflow.md @@ -0,0 +1,45 @@ +--- +name: Daily Check In +description: TODO +web_bundle: false +--- + +# Daily Check In + +**Goal:** TODO + +**Your Role:** TODO + +## WORKFLOW ARCHITECTURE + +### Core Principles + +TODO + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY. diff --git a/example-custom-module/mwm/workflows/guided-meditation/README.md b/example-custom-module/mwm/workflows/guided-meditation/README.md new file mode 100644 index 00000000..09539fe1 --- /dev/null +++ b/example-custom-module/mwm/workflows/guided-meditation/README.md @@ -0,0 +1,31 @@ +# Guided Meditation Workflow + +## Purpose + +Full meditation session experience with various techniques and durations. + +## Trigger + +GM (from Meditation Guide agent) + +## Key Steps + +1. Set intention for practice +2. Choose meditation type and duration +3. Get comfortable and settle in +4. Guided practice +5. Gentle return to awareness +6. Reflection and integration +7. Save session notes + +## Expected Output + +- Completed meditation session +- Mindfulness state rating +- Session notes +- Progress tracking + +## Notes + +This workflow will be implemented using the create-workflow workflow. +Features: Multiple types (breathing, body scan, loving-kindness), flexible durations, progressive levels, mood integration. diff --git a/example-custom-module/mwm/workflows/guided-meditation/workflow.md b/example-custom-module/mwm/workflows/guided-meditation/workflow.md new file mode 100644 index 00000000..18982496 --- /dev/null +++ b/example-custom-module/mwm/workflows/guided-meditation/workflow.md @@ -0,0 +1,45 @@ +--- +name: guided meditation +description: TODO +web_bundle: false +--- + +# Guided Meditation + +**Goal:** TODO + +**Your Role:** TODO + +## WORKFLOW ARCHITECTURE + +### Core Principles + +TODO + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY. diff --git a/example-custom-module/mwm/workflows/wellness-journal/README.md b/example-custom-module/mwm/workflows/wellness-journal/README.md new file mode 100644 index 00000000..ab3b2f13 --- /dev/null +++ b/example-custom-module/mwm/workflows/wellness-journal/README.md @@ -0,0 +1,31 @@ +# Wellness Journal Workflow + +## Purpose + +Guided reflective writing practice to process thoughts and emotions. + +## Trigger + +WJ (from Wellness Companion agent) + +## Key Steps + +1. Set intention for journal entry +2. Choose journal prompt or free write +3. Guided reflection questions +4. Emotional processing check +5. Identify insights or patterns +6. Save entry with mood tags +7. Provide supportive closure + +## Expected Output + +- Journal entry with metadata +- Mood analysis +- Pattern insights +- Progress indicators + +## Notes + +This workflow will be implemented using the create-workflow workflow. +Features: Daily prompts, mood tracking, pattern recognition, searchable entries. diff --git a/example-custom-module/mwm/workflows/wellness-journal/workflow.md b/example-custom-module/mwm/workflows/wellness-journal/workflow.md new file mode 100644 index 00000000..5f7c6392 --- /dev/null +++ b/example-custom-module/mwm/workflows/wellness-journal/workflow.md @@ -0,0 +1,45 @@ +--- +name: wellness-journal +description: create or add to the wellness journal +web_bundle: false +--- + +# Wellness Journal + +**Goal:** TODO + +**Your Role:** TODO + +## WORKFLOW ARCHITECTURE + +### Core Principles + +TODO + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve: + +- `user_name`, `output_folder`, `communication_language`, `document_output_language` + +### 2. First Step EXECUTION + +TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY. diff --git a/package-lock.json b/package-lock.json index 80746370..375ff514 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "bmad-method", - "version": "6.0.0-alpha.12", + "version": "6.0.0-alpha.13", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "bmad-method", - "version": "6.0.0-alpha.12", + "version": "6.0.0-alpha.13", "license": "MIT", "dependencies": { "@kayvan/markdown-tree-parser": "^1.6.1", @@ -42,6 +42,7 @@ "husky": "^9.1.7", "jest": "^30.0.4", "lint-staged": "^16.1.1", + "markdownlint-cli2": "^0.19.1", "prettier": "^3.5.3", "prettier-plugin-packagejson": "^2.5.19", "yaml-eslint-parser": "^1.2.3", @@ -1672,6 +1673,19 @@ "dev": true, "license": "MIT" }, + "node_modules/@sindresorhus/merge-streams": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz", + "integrity": "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/@sinonjs/commons": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz", @@ -1798,6 +1812,13 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/katex": { + "version": "0.16.7", + "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.7.tgz", + "integrity": "sha512-HMwFiRujE5PjrgwHQ25+bsLJgowjGjm5Z8FVSf0N6PwgJrwxH0QxzHYDcKsTfV3wva0vzrpqMTJS2jXPr5BMEQ==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/mdast": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", @@ -2793,6 +2814,28 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-reference-invalid": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz", + "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/chardet": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/chardet/-/chardet-2.1.0.tgz", @@ -3298,6 +3341,19 @@ "node": ">=10.13.0" } }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/environment": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz", @@ -4421,6 +4477,32 @@ "node": ">=8" } }, + "node_modules/is-alphabetical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", + "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/is-alphanumerical": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz", + "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-alphabetical": "^2.0.0", + "is-decimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/is-arrayish": { "version": "0.2.1", "resolved": "https://registry.npmjs.org/is-arrayish/-/is-arrayish-0.2.1.tgz", @@ -4444,6 +4526,17 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/is-decimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz", + "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/is-extglob": { "version": "2.1.1", "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", @@ -4490,6 +4583,17 @@ "node": ">=0.10.0" } }, + "node_modules/is-hexadecimal": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz", + "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, "node_modules/is-interactive": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/is-interactive/-/is-interactive-1.0.0.tgz", @@ -5478,6 +5582,13 @@ "node": ">=6" } }, + "node_modules/jsonc-parser": { + "version": "3.3.1", + "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz", + "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==", + "dev": true, + "license": "MIT" + }, "node_modules/jsonfile": { "version": "6.2.0", "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.0.tgz", @@ -5490,6 +5601,33 @@ "graceful-fs": "^4.1.6" } }, + "node_modules/katex": { + "version": "0.16.25", + "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.25.tgz", + "integrity": "sha512-woHRUZ/iF23GBP1dkDQMh1QBad9dmr8/PAwNA54VrSOVYgI12MAcE14TqnDdQOdzyEonGzMepYnqBMYdsoAr8Q==", + "dev": true, + "funding": [ + "https://opencollective.com/katex", + "https://github.com/sponsors/katex" + ], + "license": "MIT", + "dependencies": { + "commander": "^8.3.0" + }, + "bin": { + "katex": "cli.js" + } + }, + "node_modules/katex/node_modules/commander": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz", + "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, "node_modules/keyv": { "version": "4.5.4", "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz", @@ -5544,6 +5682,16 @@ "dev": true, "license": "MIT" }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, "node_modules/lint-staged": { "version": "16.1.5", "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-16.1.5.tgz", @@ -5988,6 +6136,132 @@ "tmpl": "1.0.5" } }, + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, + "node_modules/markdownlint": { + "version": "0.39.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.39.0.tgz", + "integrity": "sha512-Xt/oY7bAiHwukL1iru2np5LIkhwD19Y7frlsiDILK62v3jucXCD6JXlZlwMG12HZOR+roHIVuJZrfCkOhp6k3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark": "4.0.2", + "micromark-core-commonmark": "2.0.3", + "micromark-extension-directive": "4.0.0", + "micromark-extension-gfm-autolink-literal": "2.1.0", + "micromark-extension-gfm-footnote": "2.1.0", + "micromark-extension-gfm-table": "2.1.1", + "micromark-extension-math": "3.1.0", + "micromark-util-types": "2.0.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/markdownlint-cli2": { + "version": "0.19.1", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.19.1.tgz", + "integrity": "sha512-p3JTemJJbkiMjXEMiFwgm0v6ym5g8K+b2oDny+6xdl300tUKySxvilJQLSea48C6OaYNmO30kH9KxpiAg5bWJw==", + "dev": true, + "license": "MIT", + "dependencies": { + "globby": "15.0.0", + "js-yaml": "4.1.1", + "jsonc-parser": "3.3.1", + "markdown-it": "14.1.0", + "markdownlint": "0.39.0", + "markdownlint-cli2-formatter-default": "0.0.6", + "micromatch": "4.0.8" + }, + "bin": { + "markdownlint-cli2": "markdownlint-cli2-bin.mjs" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/markdownlint-cli2-formatter-default": { + "version": "0.0.6", + "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.6.tgz", + "integrity": "sha512-VVDGKsq9sgzu378swJ0fcHfSicUnMxnL8gnLm/Q4J/xsNJ4e5bA6lvAz7PCzIl0/No0lHyaWdqVD2jotxOSFMQ==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + }, + "peerDependencies": { + "markdownlint-cli2": ">=0.0.4" + } + }, + "node_modules/markdownlint-cli2/node_modules/globby": { + "version": "15.0.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-15.0.0.tgz", + "integrity": "sha512-oB4vkQGqlMl682wL1IlWd02tXCbquGWM4voPEI85QmNKCaw8zGTm1f1rubFgkg3Eli2PtKlFgrnmUqasbQWlkw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@sindresorhus/merge-streams": "^4.0.0", + "fast-glob": "^3.3.3", + "ignore": "^7.0.5", + "path-type": "^6.0.0", + "slash": "^5.1.0", + "unicorn-magic": "^0.3.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdownlint-cli2/node_modules/path-type": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-6.0.0.tgz", + "integrity": "sha512-Vj7sf++t5pBD637NSfkxpHSMfWaeig5+DKWLhcqIYx6mWQz5hdJTGDVMQiJcw1ZYkhs7AazKDGpRVji1LJCZUQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdownlint-cli2/node_modules/slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/mdast-util-from-markdown": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.2.tgz", @@ -6060,6 +6334,13 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true, + "license": "MIT" + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -6146,6 +6427,102 @@ "micromark-util-types": "^2.0.0" } }, + "node_modules/micromark-extension-directive": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz", + "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "parse-entities": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-autolink-literal": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz", + "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-footnote": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz", + "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-gfm-table": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", + "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/micromark-extension-math": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/micromark-extension-math/-/micromark-extension-math-3.1.0.tgz", + "integrity": "sha512-lvEqd+fHjATVs+2v/8kg9i5Q0AP2k85H0WUOwpIVvUML8BapsMvh1XAogmQjOCsLpoKRCVQqEkQBB3NhVBcsOg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/katex": "^0.16.0", + "devlop": "^1.0.0", + "katex": "^0.16.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/micromark-factory-destination": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz", @@ -6868,6 +7245,33 @@ "node": ">=6" } }, + "node_modules/parse-entities": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz", + "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0", + "character-entities-legacy": "^3.0.0", + "character-reference-invalid": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "is-alphanumerical": "^2.0.0", + "is-decimal": "^2.0.0", + "is-hexadecimal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/parse-entities/node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "dev": true, + "license": "MIT" + }, "node_modules/parse-json": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-5.2.0.tgz", @@ -7156,6 +7560,16 @@ "node": ">=6" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/pure-rand": { "version": "7.0.1", "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-7.0.1.tgz", @@ -8040,6 +8454,13 @@ "node": ">=14.17" } }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true, + "license": "MIT" + }, "node_modules/undici-types": { "version": "7.10.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.10.0.tgz", @@ -8047,6 +8468,19 @@ "devOptional": true, "license": "MIT" }, + "node_modules/unicorn-magic": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.3.0.tgz", + "integrity": "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/unified": { "version": "11.0.5", "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz", diff --git a/package.json b/package.json index d452a763..7bd41b7f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/package.json", "name": "bmad-method", - "version": "6.0.0-alpha.13", + "version": "6.0.0-alpha.15", "description": "Breakthrough Method of Agile AI-driven Development", "keywords": [ "agile", @@ -24,7 +24,6 @@ "bmad-method": "tools/bmad-npx-wrapper.js" }, "scripts": { - "bmad:agent-install": "node tools/cli/bmad-cli.js agent-install", "bmad:install": "node tools/cli/bmad-cli.js install", "bmad:status": "node tools/cli/bmad-cli.js status", "bundle": "node tools/cli/bundlers/bundle-web.js all", @@ -34,13 +33,14 @@ "install:bmad": "node tools/cli/bmad-cli.js install", "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0", "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix", + "lint:md": "markdownlint-cli2 \"**/*.md\"", "prepare": "husky", "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle", "release:major": "gh workflow run \"Manual Release\" -f version_bump=major", "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor", "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch", "release:watch": "gh run watch", - "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check", + "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check", "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas", "test:install": "node test/test-installation-components.js", "test:schemas": "node test/test-agent-schema.js", @@ -56,7 +56,11 @@ "eslint --fix", "npm run format:fix" ], - "*.{json,md}": [ + "*.json": [ + "npm run format:fix" + ], + "*.md": [ + "markdownlint-cli2", "npm run format:fix" ] }, @@ -90,6 +94,7 @@ "husky": "^9.1.7", "jest": "^30.0.4", "lint-staged": "^16.1.1", + "markdownlint-cli2": "^0.19.1", "prettier": "^3.5.3", "prettier-plugin-packagejson": "^2.5.19", "yaml-eslint-parser": "^1.2.3", diff --git a/src/core/_module-installer/installer.js b/src/core/_module-installer/installer.js index 2fef9562..d77bc62f 100644 --- a/src/core/_module-installer/installer.js +++ b/src/core/_module-installer/installer.js @@ -6,7 +6,7 @@ const chalk = require('chalk'); * * @param {Object} options - Installation options * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from install-config.yaml + * @param {Object} options.config - Module configuration from module.yaml * @param {Array} options.installedIDEs - Array of IDE codes that were installed * @param {Object} options.logger - Logger instance for output * @returns {Promise} - Success status diff --git a/src/core/_module-installer/install-config.yaml b/src/core/module.yaml similarity index 86% rename from src/core/_module-installer/install-config.yaml rename to src/core/module.yaml index a69e77be..1099a2e6 100644 --- a/src/core/_module-installer/install-config.yaml +++ b/src/core/module.yaml @@ -23,7 +23,11 @@ document_output_language: default: "{communication_language}" result: "{value}" - # This is the folder where all generated AI Output documents from workflows will default be sa +agent_sidecar_folder: + prompt: "Where should users agent sidecar memory folders be stored?" + default: ".bmad-user-memory" + result: "{project-root}/{value}" + output_folder: prompt: "Where should AI Generated Artifacts be saved across all modules?" default: "docs" diff --git a/src/core/resources/excalidraw/library-loader.md b/src/core/resources/excalidraw/library-loader.md index 6a66c963..6fe5ea07 100644 --- a/src/core/resources/excalidraw/library-loader.md +++ b/src/core/resources/excalidraw/library-loader.md @@ -4,7 +4,7 @@ ## Purpose -Load external .excalidrawlib files from https://libraries.excalidraw.com or custom sources. +Load external .excalidrawlib files from or custom sources. ## Planned Capabilities @@ -34,7 +34,7 @@ libraries: ## Implementation Notes -This will be developed when agents need to leverage the extensive library ecosystem available at https://libraries.excalidraw.com. +This will be developed when agents need to leverage the extensive library ecosystem available at . Hundreds of pre-built component libraries exist for: diff --git a/src/core/workflows/brainstorming/steps/step-01-session-setup.md b/src/core/workflows/brainstorming/steps/step-01-session-setup.md index 32052106..54a0f636 100644 --- a/src/core/workflows/brainstorming/steps/step-01-session-setup.md +++ b/src/core/workflows/brainstorming/steps/step-01-session-setup.md @@ -135,7 +135,7 @@ _[Content based on conversation about session parameters and facilitator approac When user selects approach, append the session overview content directly to `{output_folder}/analysis/brainstorming-session-{{date}}.md` using the structure from above. -#### E. Continue to Technique Selection +### E. Continue to Technique Selection "**Session setup complete!** I have a clear understanding of your goals and can select the perfect techniques for your brainstorming needs. diff --git a/src/core/workflows/brainstorming/workflow.md b/src/core/workflows/brainstorming/workflow.md index 156a9bb5..9050764c 100644 --- a/src/core/workflows/brainstorming/workflow.md +++ b/src/core/workflows/brainstorming/workflow.md @@ -28,7 +28,7 @@ This uses **micro-file architecture** for disciplined execution: ### Configuration Loading -Load config from `{project-root}/{bmad_folder}/bmm/config.yaml` and resolve: +Load config from `{project-root}/{bmad_folder}/core/config.yaml` and resolve: - `project_name`, `output_folder`, `user_name` - `communication_language`, `document_output_language`, `user_skill_level` diff --git a/src/core/workflows/party-mode/steps/step-03-graceful-exit.md b/src/core/workflows/party-mode/steps/step-03-graceful-exit.md index 136cc26c..2f00c663 100644 --- a/src/core/workflows/party-mode/steps/step-03-graceful-exit.md +++ b/src/core/workflows/party-mode/steps/step-03-graceful-exit.md @@ -95,7 +95,6 @@ stepsCompleted: [1, 2, 3] workflowType: 'party-mode' user_name: '{{user_name}}' date: '{{date}}' -current_year: '{{current_year}}' agents_loaded: true party_active: false workflow_completed: true diff --git a/src/core/workflows/party-mode/workflow.md b/src/core/workflows/party-mode/workflow.md index b3147ad0..5d15e612 100644 --- a/src/core/workflows/party-mode/workflow.md +++ b/src/core/workflows/party-mode/workflow.md @@ -27,11 +27,11 @@ This uses **micro-file architecture** with **sequential conversation orchestrati ### Configuration Loading -Load config from `{project-root}/{bmad_folder}/bmm/config.yaml` and resolve: +Load config from `{project-root}/{bmad_folder}/core/config.yaml` and resolve: - `project_name`, `output_folder`, `user_name` - `communication_language`, `document_output_language`, `user_skill_level` -- `date`, `current_year`, `current_month` as system-generated values +- `date` as a system-generated value - Agent manifest path: `{project-root}/{bmad_folder}/_cfg/agent-manifest.csv` ### Paths @@ -118,7 +118,6 @@ stepsCompleted: [1] workflowType: 'party-mode' user_name: '{{user_name}}' date: '{{date}}' -current_year: '{{current_year}}' agents_loaded: true party_active: true exit_triggers: ['*exit', 'goodbye', 'end party', 'quit'] diff --git a/src/modules/bmb/_module-installer/installer.js b/src/modules/bmb/_module-installer/installer.js new file mode 100644 index 00000000..9b201f57 --- /dev/null +++ b/src/modules/bmb/_module-installer/installer.js @@ -0,0 +1,76 @@ +const fs = require('fs-extra'); +const path = require('node:path'); +const chalk = require('chalk'); + +/** + * BMB Module Installer + * Sets up custom agent and workflow locations for the BMad Builder module + * + * @param {Object} options - Installation options + * @param {string} options.projectRoot - The root directory of the target project + * @param {Object} options.config - Module configuration from module.yaml + * @param {Object} options.coreConfig - Core configuration containing user_name + * @param {Array} options.installedIDEs - Array of IDE codes that were installed + * @param {Object} options.logger - Logger instance for output + * @returns {Promise} - Success status + */ +async function install(options) { + const { projectRoot, config, coreConfig, installedIDEs, logger } = options; + + try { + logger.log(chalk.blue('๐Ÿ”ง Setting up BMB Module...')); + + // Generate custom.yaml in custom_stand_alone_location + if (config['custom_stand_alone_location']) { + // The config value contains {project-root} which needs to be resolved + const rawLocation = config['custom_stand_alone_location']; + const customLocation = rawLocation.replace('{project-root}', projectRoot); + const customDestPath = path.join(customLocation, 'custom.yaml'); + + logger.log(chalk.cyan(` Setting up custom agents at: ${customLocation}`)); + + // Ensure the directory exists + await fs.ensureDir(customLocation); + + // Generate the custom.yaml content + const userName = (coreConfig && coreConfig.user_name) || 'my'; + const customContent = `code: my-custom-bmad +name: "${userName}-Custom-BMad: Sample Stand Alone Custom Agents and Workflows" +default_selected: true +`; + + // Write the custom.yaml file (only if it doesn't exist to preserve user changes) + if (await fs.pathExists(customDestPath)) { + logger.log(chalk.yellow(` โœ“ custom.yaml already exists at ${customDestPath}`)); + } else { + await fs.writeFile(customDestPath, customContent, 'utf8'); + logger.log(chalk.green(` โœ“ Created custom.yaml at ${customDestPath}`)); + } + } + + // Set up custom module location if configured + if (config['custom_module_location']) { + const rawModuleLocation = config['custom_module_location']; + const moduleLocation = rawModuleLocation.replace('{project-root}', projectRoot); + + logger.log(chalk.cyan(` Setting up custom modules at: ${moduleLocation}`)); + + // Ensure the directory exists + await fs.ensureDir(moduleLocation); + logger.log(chalk.green(` โœ“ Created modules directory at ${moduleLocation}`)); + } + + // Handle IDE-specific configurations if needed + if (installedIDEs && installedIDEs.length > 0) { + logger.log(chalk.cyan(` Configuring BMB for IDEs: ${installedIDEs.join(', ')}`)); + } + + logger.log(chalk.green('โœ“ BMB Module setup complete')); + return true; + } catch (error) { + logger.error(chalk.red(`Error setting up BMB module: ${error.message}`)); + return false; + } +} + +module.exports = { install }; diff --git a/src/modules/bmb/agents/bmad-builder.agent.yaml b/src/modules/bmb/agents/bmad-builder.agent.yaml index d2277746..81f4c863 100644 --- a/src/modules/bmb/agents/bmad-builder.agent.yaml +++ b/src/modules/bmb/agents/bmad-builder.agent.yaml @@ -29,22 +29,25 @@ agent: - modules: "{project-root}/{bmad_folder}/bmb/docs/modules/kb.csv" menu: - - multi: "[CA] Create, [EA] Edit, or [VA] Validate BMAD agents with best practices" + - multi: "[CA] Create, [EA] Edit, or [VA] Validate with Compliance CheckBMAD agents with best practices" triggers: - create-agent: - input: CA or fuzzy match create agent - route: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.md" - data: null + - type: exec - edit-agent: - input: EA or fuzzy match edit agent - route: "{project-root}/{bmad_folder}/bmb/workflows/edit-agent/workflow.md" - data: null + - type: exec - run-agent-compliance-check: - input: VA or fuzzy match validate agent - route: "{project-root}/{bmad_folder}/bmb/workflows/agent-compliance-check/workflow.md" - data: null + - type: exec - - multi: "[CW] Create, [EW] Edit, or [VW] Validate BMAD workflows with best practices" + - multi: "[CW] Create, [EW] Edit, or [VW] Validate with Compliance CheckBMAD workflows with best practices" triggers: - create-workflow: - input: CW or fuzzy match create workflow @@ -62,10 +65,30 @@ agent: - data: null - type: exec - - trigger: create-module - workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml" - description: Create a complete BMAD compatible module (custom agents and workflows) - - - trigger: edit-module - workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-module/workflow.yaml" - description: Edit existing modules (structure, agents, workflows, documentation) + - multi: "[BM] Brainstorm, [PBM] Product Brief, [CM] Create, [EM] Edit or [VM] Validate with Compliance Check BMAD modules with best practices" + triggers: + - brainstorm-module: + - input: BM or fuzzy match brainstorm module + - route: "{project-root}/{bmad_folder}/bmb/workflows/brainstorm-module/workflow.md" + - data: null + - type: exec + - product-brief-module: + - input: PBM or fuzzy match product brief module + - route: "{project-root}/{bmad_folder}/bmb/workflows/product-brief-module/workflow.md" + - data: null + - type: exec + - create-module: + - input: CM or fuzzy match create module + - route: "{project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.md" + - data: null + - type: exec + - edit-module: + - input: EM or fuzzy match edit module + - route: "{project-root}/{bmad_folder}/bmb/workflows/edit-module/workflow.md" + - data: null + - type: exec + - run-module-compliance-check: + - input: VM or fuzzy match validate module + - route: "{project-root}/{bmad_folder}/bmb/workflows/module-compliance-check/workflow.md" + - data: null + - type: exec diff --git a/src/modules/bmb/docs/agents/agent-menu-patterns.md b/src/modules/bmb/docs/agents/agent-menu-patterns.md index 73d3f475..a49fffca 100644 --- a/src/modules/bmb/docs/agents/agent-menu-patterns.md +++ b/src/modules/bmb/docs/agents/agent-menu-patterns.md @@ -375,7 +375,7 @@ exec: "../../../core/tasks/validate.xml" - `{project-root}` - Project root directory - `{bmad_folder}` - BMAD installation folder -- `{agent-folder}` - Agent installation directory (Expert agents) +- `{agent_sidecar_folder}` - Agent installation directory (Expert agents) - `{output_folder}` - Document output location - `{user_name}` - User's name from config - `{communication_language}` - Language preference @@ -415,9 +415,9 @@ menu: ```yaml critical_actions: - - 'Load {agent-folder}/memories.md' - - 'Follow {agent-folder}/instructions.md' - - 'ONLY access {agent-folder}/' + - 'Load ./memories.md' + - 'Follow ./instructions.md' + - 'ONLY access ./' prompts: - id: reflect @@ -431,7 +431,7 @@ menu: description: 'Write journal entry' - trigger: save - action: 'Update {agent-folder}/memories.md with session insights' + action: 'Update ./memories.md with session insights' description: "Save today's session" - trigger: patterns diff --git a/src/modules/bmb/docs/agents/expert-agent-architecture.md b/src/modules/bmb/docs/agents/expert-agent-architecture.md index 683fbf86..4f79995d 100644 --- a/src/modules/bmb/docs/agents/expert-agent-architecture.md +++ b/src/modules/bmb/docs/agents/expert-agent-architecture.md @@ -57,9 +57,9 @@ agent: - My approach to memory and learning critical_actions: - - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/memories.md and remember all past insights' - - 'Load COMPLETE file {agent-folder}/{agent-name}-sidecar/instructions.md and follow ALL protocols' - - 'ONLY read/write files in {agent-folder}/{agent-name}-sidecar/ - this is our private space' + - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights' + - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols' + - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space' - 'Address user as {{greeting_name}}' - 'Track patterns, themes, and important moments' - 'Reference past interactions naturally to show continuity' @@ -94,7 +94,7 @@ agent: description: 'Primary agent function' - trigger: remember - action: 'Update {agent-folder}/{agent-name}-sidecar/memories.md with session insights' + action: 'Update ./{agent-name}-sidecar/memories.md with session insights' description: 'Save what we discussed today' - trigger: patterns @@ -102,7 +102,7 @@ agent: description: 'Recall patterns from past interactions' - trigger: insight - action: 'Document breakthrough in {agent-folder}/{agent-name}-sidecar/breakthroughs.md' + action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md' description: 'Record a significant insight' install_config: @@ -184,9 +184,9 @@ Add domain-specific documentation here. ```yaml critical_actions: - - 'Load COMPLETE file {agent-folder}/{sidecar}/memories.md and remember all past insights' - - 'Load COMPLETE file {agent-folder}/{sidecar}/instructions.md and follow ALL protocols' - - 'ONLY read/write files in {agent-folder}/{sidecar}/ - this is our private space' + - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights' + - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols' + - 'ONLY read/write files in ./{sidecar}/ - this is our private space' ``` **Key patterns:** @@ -196,7 +196,7 @@ critical_actions: - **Memory integration** - Past context becomes part of current session - **Protocol adherence** - Ensures consistent behavior -### {agent-folder} Variable +### {agent_sidecar_folder} Variable Special variable resolved during installation: @@ -211,9 +211,9 @@ Same as simple agents, PLUS: 1. **Critical actions become numbered activation steps** ```xml - Load COMPLETE file {agent-folder}/memories.md... - Load COMPLETE file {agent-folder}/instructions.md... - ONLY read/write files in {agent-folder}/... + Load COMPLETE file ./memories.md... + Load COMPLETE file ./instructions.md... + ONLY read/write files in ./... ``` 2. **Sidecar files copied during installation** @@ -260,7 +260,7 @@ The installer: ```yaml menu: - trigger: save - action: "Update {agent-folder}/sidecar/memories.md with today's session insights" + action: "Update ./sidecar/memories.md with today's session insights" description: 'Save session to memory' ``` @@ -281,7 +281,7 @@ prompts: ```yaml menu: - trigger: insight - action: 'Document in {agent-folder}/sidecar/breakthroughs.md with date, context, significance' + action: 'Document in ./sidecar/breakthroughs.md with date, context, significance' description: 'Record meaningful insight' ``` @@ -291,7 +291,7 @@ menu: ```yaml critical_actions: - - 'ONLY read/write files in {agent-folder}/sidecar/ - NO OTHER FOLDERS' + - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS' ``` ### User Space Access @@ -305,15 +305,15 @@ critical_actions: ```yaml critical_actions: - - 'Load knowledge from {agent-folder}/knowledge/ but NEVER modify' - - 'Write ONLY to {agent-folder}/sessions/' + - 'Load knowledge from ./knowledge/ but NEVER modify' + - 'Write ONLY to ./sessions/' ``` ## Best Practices 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY 2. **Enforce domain restrictions** - Clear boundaries prevent scope creep -3. **Use {agent-folder} paths** - Portable across installations +3. **Use {agent_sidecar_folder} paths** - Portable across installations 4. **Design for memory growth** - Structure sidecar files for accumulation 5. **Reference past naturally** - Don't dump memory, weave it into conversation 6. **Separate concerns** - Memories, instructions, knowledge in distinct files @@ -356,8 +356,8 @@ identity: | - [ ] Sidecar folder structure created and populated - [ ] memories.md has clear section structure - [ ] instructions.md contains core directives -- [ ] Menu actions reference {agent-folder} correctly -- [ ] File paths use {agent-folder} variable +- [ ] Menu actions reference {agent_sidecar_folder} correctly +- [ ] File paths use {agent_sidecar_folder} variable - [ ] Install config personalizes sidecar references - [ ] Agent folder named consistently: `{agent-name}/` - [ ] YAML file named: `{agent-name}.agent.yaml` diff --git a/src/modules/bmb/docs/agents/index.md b/src/modules/bmb/docs/agents/index.md index 99f51845..650c427b 100644 --- a/src/modules/bmb/docs/agents/index.md +++ b/src/modules/bmb/docs/agents/index.md @@ -37,7 +37,7 @@ Production-ready examples in `/src/modules/bmb/reference/agents/`: For installing standalone simple and expert agents, see: -- [Custom Agent Installation](/docs/custom-agent-installation.md) +- [Custom Agent Installation](/docs/custom-content-installation.md) ## Key Concepts diff --git a/src/modules/bmb/docs/agents/module-agent-architecture.md b/src/modules/bmb/docs/agents/module-agent-architecture.md index 490782bd..7ed956af 100644 --- a/src/modules/bmb/docs/agents/module-agent-architecture.md +++ b/src/modules/bmb/docs/agents/module-agent-architecture.md @@ -27,7 +27,7 @@ Compiles to: ```yaml agent: metadata: - id: '{bmad_folder}/{module-code}/agents/{agent-name}.md' + id: '{*bmad_folder*}/{module-code}/agents/{agent-name}.md' name: 'Persona Name' title: 'Professional Title' icon: 'emoji' @@ -41,29 +41,29 @@ agent: menu: - trigger: workflow-action - workflow: '{project-root}/{bmad_folder}/{module-code}/workflows/{workflow-name}/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/{module-code}/workflows/{workflow-name}/workflow.yaml' description: 'Execute module workflow' - trigger: another-workflow - workflow: '{project-root}/{bmad_folder}/core/workflows/{workflow-name}/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/core/workflows/{workflow-name}/workflow.yaml' description: 'Execute core workflow' - trigger: task-action - exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml' + exec: '{project-root}/{*bmad_folder*}/{module-code}/tasks/{task-name}.xml' description: 'Execute module task' - trigger: cross-module - workflow: '{project-root}/{bmad_folder}/other-module/workflows/{workflow-name}/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/other-module/workflows/{workflow-name}/workflow.yaml' description: 'Execute workflow from another module' - trigger: with-template - exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml' - tmpl: '{project-root}/{bmad_folder}/{module-code}/templates/{template-name}.md' + exec: '{project-root}/{*bmad_folder*}/core/tasks/create-doc.xml' + tmpl: '{project-root}/{*bmad_folder*}/{module-code}/templates/{template-name}.md' description: 'Create document from template' - trigger: with-data - exec: '{project-root}/{bmad_folder}/{module-code}/tasks/{task-name}.xml' - data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv' + exec: '{project-root}/{*bmad_folder*}/{module-code}/tasks/{task-name}.xml' + data: '{project-root}/{*bmad_folder*}/_cfg/agent-manifest.csv' description: 'Execute task with data file' ``` @@ -71,7 +71,7 @@ agent: ### Metadata -- **id**: Path with `{bmad_folder}` variable (resolved at install time) +- **id**: Path with `{*bmad_folder*}` variable (resolved at install time) - **name**: Agent persona name - **title**: Professional role - **icon**: Single emoji @@ -101,7 +101,7 @@ persona: ```yaml menu: - trigger: create-prd - workflow: '{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/prd/workflow.yaml' description: 'Create Product Requirements Document' ``` @@ -112,7 +112,7 @@ Invokes BMAD workflow engine to execute multi-step processes. ```yaml menu: - trigger: validate - exec: '{project-root}/{bmad_folder}/core/tasks/validate-workflow.xml' + exec: '{project-root}/{*bmad_folder*}/core/tasks/validate-workflow.xml' description: 'Validate document structure' ``` @@ -123,8 +123,8 @@ Executes single-operation tasks. ```yaml menu: - trigger: create-brief - exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml' - tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md' + exec: '{project-root}/{*bmad_folder*}/core/tasks/create-doc.xml' + tmpl: '{project-root}/{*bmad_folder*}/bmm/templates/brief.md' description: 'Create a Product Brief from template' ``` @@ -135,8 +135,8 @@ Combines task execution with template file. ```yaml menu: - trigger: team-standup - exec: '{project-root}/{bmad_folder}/bmm/tasks/standup.xml' - data: '{project-root}/{bmad_folder}/_cfg/agent-manifest.csv' + exec: '{project-root}/{*bmad_folder*}/bmm/tasks/standup.xml' + data: '{project-root}/{*bmad_folder*}/_cfg/agent-manifest.csv' description: 'Run team standup with agent roster' ``` @@ -160,12 +160,12 @@ Control visibility based on platform: ```yaml menu: - trigger: advanced-elicitation - exec: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' + exec: '{project-root}/{*bmad_folder*}/core/tasks/advanced-elicitation.xml' description: 'Advanced elicitation techniques' web-only: true # Only shows in web bundle - trigger: git-operations - exec: '{project-root}/{bmad_folder}/bmm/tasks/git-flow.xml' + exec: '{project-root}/{*bmad_folder*}/bmm/tasks/git-flow.xml' description: 'Git workflow operations' ide-only: true # Only shows in IDE environments ``` @@ -175,7 +175,7 @@ menu: ### Core Variables - `{project-root}` - Root directory of installed project -- `{bmad_folder}` - BMAD installation folder (usually `.bmad`) +- `{*bmad_folder*}` - BMAD installation folder (usually `.bmad`) - `{user_name}` - User's name from module config - `{communication_language}` - Language preference - `{output_folder}` - Document output directory @@ -186,7 +186,7 @@ menu: ```yaml # GOOD -workflow: "{project-root}/{bmad_folder}/bmm/workflows/prd/workflow.yaml" +workflow: "{project-root}/{*bmad_folder*}/bmm/workflows/prd/workflow.yaml" # BAD workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml" @@ -203,12 +203,12 @@ Module agents use the same injection process as simple agents: 2. **Activation block** with standard steps 3. **Menu handlers** based on usage (workflow, exec, tmpl, data) 4. **Rules section** for consistent behavior -5. **Auto-injected** *help and *exit commands +5. **Auto-injected** \*help and \*exit commands **Key difference:** Module agents load **module-specific config** instead of core config: ```xml -Load and read {project-root}/{bmad_folder}/{module}/config.yaml... +Load and read {project-root}/{*bmad_folder*}/{module}/config.yaml... ``` ## Reference Examples @@ -252,15 +252,15 @@ Agents load this at activation for consistent behavior. ```yaml menu: - trigger: init - workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-init/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/workflow-init/workflow.yaml' description: 'Initialize workflow path (START HERE)' - trigger: status - workflow: '{project-root}/{bmad_folder}/bmm/workflows/workflow-status/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/workflow-status/workflow.yaml' description: 'Check current workflow status' - trigger: next-step - workflow: '{project-root}/{bmad_folder}/bmm/workflows/next-step/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/next-step/workflow.yaml' description: 'Execute next workflow in sequence' ``` @@ -270,20 +270,20 @@ menu: menu: # Phase 1: Analysis - trigger: brainstorm - workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/brainstorm/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/1-analysis/brainstorm/workflow.yaml' description: 'Guided brainstorming session' - trigger: research - workflow: '{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/1-analysis/research/workflow.yaml' description: 'Market and technical research' # Phase 2: Planning - trigger: prd - workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/prd/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/2-planning/prd/workflow.yaml' description: 'Create PRD' - trigger: architecture - workflow: '{project-root}/{bmad_folder}/bmm/workflows/2-planning/architecture/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/bmm/workflows/2-planning/architecture/workflow.yaml' description: 'Design architecture' ``` @@ -292,17 +292,17 @@ menu: ```yaml menu: - trigger: party-mode - workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.yaml' description: 'Bring all agents together' - trigger: brainstorm - workflow: '{project-root}/{bmad_folder}/cis/workflows/brainstorming/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/cis/workflows/brainstorming/workflow.yaml' description: 'Use CIS brainstorming techniques' ``` ## Best Practices -1. **Use {bmad_folder} paths** - Portable across installations +1. **Use {_bmad_folder_} paths** - Portable across installations 2. **Organize workflows by phase** - Clear progression for users 3. **Include workflow-status** - Help users track progress 4. **Reference module config** - Consistent behavior @@ -318,7 +318,7 @@ menu: ```yaml menu: - trigger: start - workflow: '{project-root}/{bmad_folder}/{module}/workflows/init/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/{module}/workflows/init/workflow.yaml' description: 'Start new project (BEGIN HERE)' ``` @@ -327,7 +327,7 @@ menu: ```yaml menu: - trigger: status - workflow: '{project-root}/{bmad_folder}/{module}/workflows/status/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/{module}/workflows/status/workflow.yaml' description: 'Check workflow progress' ``` @@ -336,27 +336,27 @@ menu: ```yaml menu: - trigger: party - workflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml' + workflow: '{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.yaml' description: 'Multi-agent discussion' ``` ## Module Agent vs Simple/Expert -| Aspect | Module Agent | Simple/Expert Agent | -| ------------- | -------------------------------- | ------------------------------- | -| Location | `{bmad_folder}/{module}/agents/` | `{bmad_folder}/custom/agents/` | -| Persona | Fixed, professional | Customizable via install_config | -| Handlebars | No templating | Yes, extensive | -| Menu actions | Workflows, tasks, templates | Prompts, inline actions | -| Configuration | Module config.yaml | Core config or none | -| Purpose | Professional tooling | Personal utilities | +| Aspect | Module Agent | Simple/Expert Agent | +| ------------- | ---------------------------------- | -------------------------------- | +| Location | `{*bmad_folder*}/{module}/agents/` | `{*bmad_folder*}/custom/agents/` | +| Persona | Fixed, professional | Customizable via install_config | +| Handlebars | No templating | Yes, extensive | +| Menu actions | Workflows, tasks, templates | Prompts, inline actions | +| Configuration | Module config.yaml | Core config or none | +| Purpose | Professional tooling | Personal utilities | ## Validation Checklist - [ ] Valid YAML syntax - [ ] Metadata includes `module: "{module-code}"` -- [ ] id uses `{bmad_folder}/{module}/agents/{name}.md` -- [ ] All workflow paths use `{project-root}/{bmad_folder}/` prefix +- [ ] id uses `{*bmad_folder*}/{module}/agents/{name}.md` +- [ ] All workflow paths use `{project-root}/{*bmad_folder*}/` prefix - [ ] No hardcoded paths - [ ] No duplicate triggers - [ ] Each menu item has description diff --git a/src/modules/bmb/docs/agents/simple-agent-architecture.md b/src/modules/bmb/docs/agents/simple-agent-architecture.md index 239d29d7..9d1898b7 100644 --- a/src/modules/bmb/docs/agents/simple-agent-architecture.md +++ b/src/modules/bmb/docs/agents/simple-agent-architecture.md @@ -217,9 +217,13 @@ Features demonstrated: # Copy to your project cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/ -# Install with personalization -bmad agent-install -# or: npx bmad-method agent-install +# Create custom.yaml and install +echo "code: my-agent +name: My Agent +default_selected: true" > custom.yaml + +npx bmad-method install +# or: bmad install ``` The installer: diff --git a/src/modules/bmb/docs/workflows/templates/step-template.md b/src/modules/bmb/docs/workflows/templates/step-template.md index cc10e8e5..1c525e2c 100644 --- a/src/modules/bmb/docs/workflows/templates/step-template.md +++ b/src/modules/bmb/docs/workflows/templates/step-template.md @@ -149,13 +149,13 @@ ONLY WHEN [C continue option] is selected and [completion requirements], will yo -## Common Menu Patterns to use in the final sequence item in a step file. +## Common Menu Patterns to use in the final sequence item in a step file FYI Again - party mode is useful for the user to reach out and get opinions from other agents. Advanced elicitation is use to direct you to think of alternative outputs of a sequence you just performed. -### Standard Menu - when a sequence in a step results in content produced by the agent or human that could be improved before proceeding. +### Standard Menu - when a sequence in a step results in content produced by the agent or human that could be improved before proceeding ```markdown ### N. Present MENU OPTIONS diff --git a/src/modules/bmb/_module-installer/install-config.yaml b/src/modules/bmb/module.yaml similarity index 67% rename from src/modules/bmb/_module-installer/install-config.yaml rename to src/modules/bmb/module.yaml index 44a10a8e..85df89c0 100644 --- a/src/modules/bmb/_module-installer/install-config.yaml +++ b/src/modules/bmb/module.yaml @@ -15,17 +15,12 @@ subheader: "Configure the settings for the BoMB Factory!\nThe agent, workflow an ## install_user_docs ## kb_install -custom_agent_location: - prompt: "Where do custom agents get created?" - default: "{bmad_folder}/custom/src/agents" - result: "{project-root}/{value}" - -custom_workflow_location: - prompt: "Where do custom workflows get stored?" - default: "{bmad_folder}/custom/src/workflows" +custom_stand_alone_location: + prompt: "Where do custom agents and workflows get stored?" + default: "bmad-custom-src" result: "{project-root}/{value}" custom_module_location: prompt: "Where do custom modules get stored?" - default: "{bmad_folder}/custom/src/modules" + default: "bmad-custom-modules-src" result: "{project-root}/{value}" diff --git a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md index ec677983..702dc0b3 100644 --- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md +++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md @@ -51,7 +51,7 @@ menu: # Direct sidecar file action - trigger: 'insight' - action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md' + action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md' description: 'Record a meaningful insight' ``` @@ -63,9 +63,9 @@ Expert Agents MUST load sidecar files explicitly: ```yaml critical_actions: - - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md' - - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md' - - 'ONLY read/write files in {agent-folder}/journal-keeper-sidecar/' + - 'Load COMPLETE file ./journal-keeper-sidecar/memories.md' + - 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md' + - 'ONLY read/write files in ./journal-keeper-sidecar/' ``` **Key points:** diff --git a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml index 84595371..3574da75 100644 --- a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml +++ b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml @@ -20,9 +20,9 @@ agent: - Reflection transforms experience into wisdom critical_actions: - - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md and remember all past insights" - - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" - - "ONLY read/write files in {agent-folder}/journal-keeper-sidecar/ - this is our private space" + - "Load COMPLETE file {agent_sidecar_folder}/journal-keeper-sidecar/memories.md and remember all past insights" + - "Load COMPLETE file {agent_sidecar_folder}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" + - "ONLY read/write files in {agent_sidecar_folder}/journal-keeper-sidecar/ - this is our private space" - "Track mood patterns, recurring themes, and breakthrough moments" - "Reference past entries naturally to show continuity" @@ -120,7 +120,7 @@ agent: description: "Write today's journal entry" - trigger: quick - action: "Save a quick, unstructured entry to {agent-folder}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" + action: "Save a quick, unstructured entry to {agent_sidecar_folder}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" description: "Quick capture without prompts" - trigger: mood @@ -133,20 +133,20 @@ agent: - trigger: gratitude action: "#gratitude-moment" - description: "Capture today's gratitudes" + description: "Capture today's gratitude" - trigger: weekly action: "#weekly-reflection" description: "Reflect on the past week" - trigger: insight - action: "Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md with date and significance" + action: "Document this breakthrough in {agent_sidecar_folder}/journal-keeper-sidecar/breakthroughs.md with date and significance" description: "Record a meaningful insight" - trigger: read-back - action: "Load and share entries from {agent-folder}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" + action: "Load and share entries from {agent_sidecar_folder}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" description: "Review past entries" - trigger: save - action: "Update {agent-folder}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers" + action: "Update {agent_sidecar_folder}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers" description: "Save what we discussed today" diff --git a/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml b/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml index 5e27bfc6..602bf4e0 100644 --- a/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml +++ b/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml @@ -10,7 +10,7 @@ agent: metadata: - id: "{bmad_folder}/bmm/agents/security-engineer.md" + id: "{*bmad_folder*}/bmm/agents/security-engineer.md" name: "Sam" title: "Security Engineer" icon: "๐Ÿ”" @@ -32,22 +32,22 @@ agent: menu: # NOTE: These workflows are hypothetical examples assuming add to a module called bmm - not implemented - trigger: threat-model - workflow: "{project-root}/{bmad_folder}/bmm/workflows/threat-model/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/bmm/workflows/threat-model/workflow.md" description: "Create STRIDE threat model for architecture" - trigger: security-review - workflow: "{project-root}/{bmad_folder}/bmm/workflows/security-review/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/bmm/workflows/security-review/workflow.md" description: "Review code/design for security issues" - trigger: owasp-check - exec: "{project-root}/{bmad_folder}/bmm/tasks/owasp-top-10.xml" + TODO: true description: "Check against OWASP Top 10" - trigger: compliance - workflow: "{project-root}/{bmad_folder}/bmm/workflows/compliance-check/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/bmm/workflows/compliance-check/workflow.md" description: "Verify compliance requirements (SOC2, GDPR, etc.)" # Core workflow that exists - trigger: party-mode - exec: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md" + exec: "{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.md" description: "Multi-agent security discussion" diff --git a/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml b/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml index 7e76fe80..2ce4598f 100644 --- a/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml +++ b/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml @@ -10,7 +10,7 @@ agent: metadata: - id: "{bmad_folder}/cis/agents/trend-analyst.md" + id: "{*bmad_folder*}/cis/agents/trend-analyst.md" name: "Nova" title: "Trend Analyst" icon: "๐Ÿ“ˆ" @@ -32,26 +32,26 @@ agent: menu: # NOTE: These workflows are hypothetical examples - not implemented - trigger: scan-trends - workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-scan/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/cis/workflows/trend-scan/workflow.md" description: "Scan for emerging trends in a domain" - trigger: analyze-trend - workflow: "{project-root}/{bmad_folder}/cis/workflows/trend-analysis/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/cis/workflows/trend-analysis/workflow.md" description: "Deep dive on a specific trend" - trigger: opportunity-map - workflow: "{project-root}/{bmad_folder}/cis/workflows/opportunity-mapping/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/cis/workflows/opportunity-mapping/workflow.md" description: "Map trend to strategic opportunities" - trigger: competitor-trends - exec: "{project-root}/{bmad_folder}/cis/tasks/competitor-trend-watch.xml" + exec: "{project-root}/{*bmad_folder*}/cis/tasks/competitor-trend-watch.xml" description: "Monitor competitor trend adoption" # Core workflows that exist - trigger: brainstorm - workflow: "{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml" + exec: "{project-root}/{*bmad_folder*}/core/workflows/brainstorming/workflow.md" description: "Brainstorm trend implications" - trigger: party-mode - exec: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md" + exec: "{project-root}/{*bmad_folder*}/core/workflows/party-mode/workflow.md" description: "Discuss trends with other agents" diff --git a/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md b/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md index f08bc957..8fce50d4 100644 --- a/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md +++ b/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md @@ -132,7 +132,7 @@ You are a **strategic shopping partner** who: - Plans for real-life shopping scenarios - Minimizes food waste thoughtfully -## ๐Ÿ“ OUTPUT REQUIREMENTS: +## ๐Ÿ“Š STATUS UPDATE: Update workflow.md frontmatter: diff --git a/src/modules/bmb/workflows-legacy/create-module/README.md b/src/modules/bmb/workflows-legacy/create-module/README.md deleted file mode 100644 index 36ed4422..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/README.md +++ /dev/null @@ -1,229 +0,0 @@ -# Create Module Workflow - -Interactive scaffolding system creating complete BMad modules with agents, workflows, tasks, and installation infrastructure. - -## Table of Contents - -- [Quick Start](#quick-start) -- [Workflow Phases](#workflow-phases) -- [Output Structure](#output-structure) -- [Module Components](#module-components) -- [Best Practices](#best-practices) - -## Quick Start - -```bash -# Basic invocation -workflow create-module - -# With module brief input -workflow create-module --input module-brief-{name}-{date}.md - -# Via BMad Builder -*create-module -``` - -## Workflow Phases - -### Phase 1: Concept Definition - -- Define module purpose and audience -- Establish module code (kebab-case) and name -- Choose category (Domain, Creative, Technical, Business, Personal) -- Plan component architecture - -**Module Brief Integration:** - -- Auto-detects existing briefs -- Uses as pre-populated blueprint -- Accelerates planning phase - -### Phase 2: Architecture Planning - -- Create directory hierarchy -- Setup configuration system -- Define installer structure -- Establish component folders - -### Phase 3: Component Creation - -- Optional first agent creation -- Optional first workflow creation -- Component placeholder generation -- Integration validation - -### Phase 4: Installation Setup - -- Create install-config.yaml -- Configure deployment questions -- Setup installer logic -- Post-install messaging - -### Phase 5: Documentation - -- Generate comprehensive README -- Create development roadmap -- Provide quick commands -- Document next steps - -## Output Structure - -### Generated Directory - -``` -{bmad_folder}/{module-code}/ -โ”œโ”€โ”€ agents/ # Agent definitions -โ”œโ”€โ”€ workflows/ # Workflow processes -โ”œโ”€โ”€ tasks/ # Reusable tasks -โ”œโ”€โ”€ templates/ # Document templates -โ”œโ”€โ”€ data/ # Module data files -โ”œโ”€โ”€ _module-installer/ # Installation logic -โ”‚ โ”œโ”€โ”€ install-config.yaml -โ”‚ โ””โ”€โ”€ installer.js -โ”œโ”€โ”€ README.md # Module documentation -โ”œโ”€โ”€ TODO.md # Development roadmap -โ””โ”€โ”€ config.yaml # Runtime configuration -``` - -### Configuration Files - -**install-config.yaml** - Installation questions - -```yaml -questions: - - id: user_name - prompt: 'Your name?' - default: 'User' - - id: output_folder - prompt: 'Output location?' - default: './output' -``` - -**config.yaml** - Generated from user answers during install - -```yaml -user_name: 'John Doe' -output_folder: './my-output' -``` - -## Module Components - -### Agents - -- Full module agents with workflows -- Expert agents with sidecars -- Simple utility agents - -### Workflows - -- Multi-step guided processes -- Configuration-driven -- Web bundle support - -### Tasks - -- Reusable operations -- Agent-agnostic -- Modular components - -### Templates - -- Document structures -- Output formats -- Report templates - -## Best Practices - -### Planning - -1. **Use module-brief workflow first** - Creates comprehensive blueprint -2. **Define clear scope** - Avoid feature creep -3. **Plan component interactions** - Map agent/workflow relationships - -### Structure - -1. **Follow conventions** - Use established patterns -2. **Keep components focused** - Single responsibility -3. **Document thoroughly** - Clear README and inline docs - -### Development - -1. **Start with core agent** - Build primary functionality first -2. **Create key workflows** - Essential processes before edge cases -3. **Test incrementally** - Validate as you build - -### Installation - -1. **Minimal config questions** - Only essential settings -2. **Smart defaults** - Sensible out-of-box experience -3. **Clear post-install** - Guide users to first steps - -## Integration Points - -### With Other Workflows - -- **module-brief** - Strategic planning input -- **create-agent** - Agent component creation -- **create-workflow** - Workflow building -- **redoc** - Documentation maintenance - -### With BMad Core - -- Uses core framework capabilities -- Integrates with module system -- Follows BMad conventions - -## Examples - -### Domain-Specific Module - -``` -Category: Domain-Specific -Code: legal-advisor -Components: -- Contract Review Agent -- Compliance Workflow -- Legal Templates -``` - -### Creative Module - -``` -Category: Creative -Code: story-builder -Components: -- Narrative Agent -- Plot Workflow -- Character Templates -``` - -### Technical Module - -``` -Category: Technical -Code: api-tester -Components: -- Test Runner Agent -- API Validation Workflow -- Test Report Templates -``` - -## Workflow Files - -``` -create-module/ -โ”œโ”€โ”€ workflow.yaml # Configuration -โ”œโ”€โ”€ instructions.md # Step guide -โ”œโ”€โ”€ checklist.md # Validation -โ”œโ”€โ”€ module-structure.md # Architecture -โ”œโ”€โ”€ installer-templates/ # Install files -โ””โ”€โ”€ README.md # This file -``` - -## Related Documentation - -- [Module Structure](./module-structure.md) -- [Module Brief Workflow](../module-brief/README.md) -- [Create Agent](../create-agent/README.md) -- [Create Workflow](../create-workflow/README.md) -- [BMB Module](../../README.md) diff --git a/src/modules/bmb/workflows-legacy/create-module/brainstorm-context.md b/src/modules/bmb/workflows-legacy/create-module/brainstorm-context.md deleted file mode 100644 index 8b0114ad..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/brainstorm-context.md +++ /dev/null @@ -1,137 +0,0 @@ -# Module Brainstorming Context - -_Context provided to brainstorming workflow when creating a new BMAD module_ - -## Session Focus - -You are brainstorming ideas for a **complete BMAD module** - a self-contained package that extends the BMAD Method with specialized domain expertise and capabilities. - -## What is a BMAD Module? - -A module is a cohesive package that provides: - -- **Domain Expertise**: Specialized knowledge in a specific area (RPG, DevOps, Content Creation, etc.) -- **Agent Team**: Multiple AI personas with complementary skills -- **Workflows**: Guided processes for common tasks in the domain -- **Templates**: Document structures for consistent outputs -- **Integration**: Components that work together seamlessly - -## Brainstorming Goals - -Explore and define: - -### 1. Domain and Purpose - -- **What domain/problem space?** (e.g., game development, marketing, personal productivity) -- **Who is the target user?** (developers, writers, managers, hobbyists) -- **What pain points does it solve?** (tedious tasks, missing structure, need for expertise) -- **What makes this domain exciting?** (creativity, efficiency, empowerment) - -### 2. Agent Team Composition - -- **How many agents?** (typically 3-7 for a module) -- **What roles/personas?** (architect, researcher, reviewer, specialist) -- **How do they collaborate?** (handoffs, reviews, ensemble work) -- **What personality theme?** (Star Trek crew, superhero team, fantasy party, professional squad) - -### 3. Core Workflows - -- **What documents need creating?** (plans, specs, reports, creative outputs) -- **What processes need automation?** (analysis, generation, review, deployment) -- **What workflows enable the vision?** (3-10 key workflows that define the module) - -### 4. Value Proposition - -- **What becomes easier?** (specific tasks that get 10x faster) -- **What becomes possible?** (new capabilities previously unavailable) -- **What becomes better?** (quality improvements, consistency gains) - -## Creative Constraints - -A good BMAD module should be: - -- **Focused**: Serves a specific domain well (not generic) -- **Complete**: Provides end-to-end capabilities for that domain -- **Cohesive**: Agents and workflows complement each other -- **Fun**: Personality and creativity make it enjoyable to use -- **Practical**: Solves real problems, delivers real value - -## Module Architecture Questions - -1. **Module Identity** - - Module code (kebab-case, e.g., "rpg-toolkit") - - Module name (friendly, e.g., "RPG Toolkit") - - Module purpose (one sentence) - - Target audience - -2. **Agent Lineup** - - Agent names and roles - - Communication styles and personalities - - Expertise areas - - Command sets (what each agent can do) - -3. **Workflow Portfolio** - - Document generation workflows - - Action/automation workflows - - Analysis/research workflows - - Creative/ideation workflows - -4. **Integration Points** - - How agents invoke workflows - - How workflows use templates - - How components pass data - - Dependencies on other modules - -## Example Module Patterns - -### Professional Domains - -- **DevOps Suite**: Deploy, Monitor, Troubleshoot agents + deployment workflows -- **Marketing Engine**: Content, SEO, Analytics agents + campaign workflows -- **Legal Assistant**: Contract, Research, Review agents + document workflows - -### Creative Domains - -- **RPG Toolkit**: DM, NPC, Quest agents + adventure creation workflows -- **Story Crafter**: Plot, Character, World agents + writing workflows -- **Music Producer**: Composer, Arranger, Mixer agents + production workflows - -### Personal Domains - -- **Life Coach**: Planner, Tracker, Mentor agents + productivity workflows -- **Learning Companion**: Tutor, Quiz, Reviewer agents + study workflows -- **Health Guide**: Nutrition, Fitness, Wellness agents + tracking workflows - -## Suggested Brainstorming Techniques - -Particularly effective for module ideation: - -1. **Domain Immersion**: Deep dive into target domain's problems -2. **Persona Mapping**: Who needs this and what do they struggle with? -3. **Workflow Mapping**: What processes exist today? How could they improve? -4. **Team Building**: What personalities would make a great team? -5. **Integration Thinking**: How do pieces connect and amplify each other? - -## Key Questions to Answer - -1. What domain expertise should this module embody? -2. What would users be able to do that they can't do now? -3. Who are the 3-7 agents and what are their personalities? -4. What are the 5-10 core workflows? -5. What makes this module delightful to use? -6. How is this different from existing tools? -7. What's the "killer feature" that makes this essential? - -## Output Goals - -Generate: - -- **Module concept**: Clear vision and purpose -- **Agent roster**: Names, roles, personalities for each agent -- **Workflow list**: Core workflows with brief descriptions -- **Unique angle**: What makes this module special -- **Use cases**: 3-5 concrete scenarios where this module shines - ---- - -_This focused context helps create cohesive, valuable BMAD modules_ diff --git a/src/modules/bmb/workflows-legacy/create-module/checklist.md b/src/modules/bmb/workflows-legacy/create-module/checklist.md deleted file mode 100644 index 40f87579..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/checklist.md +++ /dev/null @@ -1,235 +0,0 @@ -# Build Module Validation Checklist - -## Module Identity and Metadata - -### Basic Information - -- [ ] Module code follows kebab-case convention (e.g., "rpg-toolkit") -- [ ] Module name is descriptive and title-cased -- [ ] Module purpose is clearly defined (1-2 sentences) -- [ ] Target audience is identified -- [ ] Version number follows semantic versioning (e.g., "1.0.0") -- [ ] Author information is present - -### Naming Consistency - -- [ ] Module code used consistently throughout all files -- [ ] No naming conflicts with existing modules -- [ ] All paths use consistent module code references - -## Directory Structure - -### Source Directories ({bmad_folder}/{module-code}/) - -- [ ] `/agents` directory created (even if empty) -- [ ] `/workflows` directory created (even if empty) -- [ ] `/tasks` directory exists (if tasks planned) -- [ ] `/templates` directory exists (if templates used) -- [ ] `/data` directory exists (if data files needed) -- [ ] `/_module-installer/install-config.yaml` present (defines configuration questions) -- [ ] `README.md` present with documentation - -### Installed Module Structure (generated in target after installation) - -- [ ] `/agents` directory for compiled agents -- [ ] `/workflows` directory for workflow instances -- [ ] `/data` directory for user data -- [ ] `config.yaml` generated from install-config.yaml during installation - -## Component Planning - -### Agents - -- [ ] At least one agent defined or planned -- [ ] Agent purposes are distinct and clear -- [ ] Agent types (Simple/Expert/Module) identified -- [ ] No significant overlap between agents -- [ ] Primary agent is identified - -### Workflows - -- [ ] At least one workflow defined or planned -- [ ] Workflow purposes are clear -- [ ] Workflow types identified (Document/Action/Interactive) -- [ ] Primary workflow is identified -- [ ] Workflow complexity is appropriate - -### Tasks (if applicable) - -- [ ] Tasks have single, clear purposes -- [ ] Tasks don't duplicate workflow functionality -- [ ] Task files follow naming conventions - -## Configuration Files - -### Installation Configuration (install-config.yaml) - -- [ ] `install-config.yaml` exists in `_module-installer` -- [ ] Module metadata present (code, name, version) -- [ ] Configuration questions defined for user input -- [ ] Default values provided for all questions -- [ ] Prompt text is clear and helpful -- [ ] Result templates use proper variable substitution -- [ ] Paths use proper variables ({project-root}, {value}, etc.) - -### Generated Config (config.yaml in target) - -- [ ] Generated during installation from install-config.yaml -- [ ] Contains all user-provided configuration values -- [ ] Module metadata included -- [ ] No config.yaml should exist in source module - -## Installation Infrastructure - -### Installer Files - -- [ ] Install configuration validates against schema -- [ ] All source paths exist or are marked as templates -- [ ] Destination paths use correct variables -- [ ] Optional vs required steps clearly marked - -### installer.js (if present) - -- [ ] Main `installModule` function exists -- [ ] Error handling implemented -- [ ] Console logging for user feedback -- [ ] Exports correct function names -- [ ] Placeholder code replaced with actual logic (or logged as TODO) - -### External Assets (if any) - -- [ ] Asset files exist in assets directory -- [ ] Copy destinations are valid -- [ ] Permissions requirements documented - -## Documentation - -### README.md - -- [ ] Module overview section present -- [ ] Installation instructions included -- [ ] Component listing with descriptions -- [ ] Quick start guide provided -- [ ] Configuration options documented -- [ ] At least one usage example -- [ ] Directory structure shown -- [ ] Author and date information - -### Component Documentation - -- [ ] Each agent has purpose documentation -- [ ] Each workflow has description -- [ ] Tasks are documented (if present) -- [ ] Examples demonstrate typical usage - -### Development Roadmap - -- [ ] TODO.md or roadmap section exists -- [ ] Planned components listed -- [ ] Development phases identified -- [ ] Quick commands for adding components - -## Integration - -### Cross-component References - -- [ ] Agents reference correct workflow paths -- [ ] Workflows reference correct task paths -- [ ] All internal paths use module variables -- [ ] External dependencies declared - -### Module Boundaries - -- [ ] Module scope is well-defined -- [ ] No feature creep into other domains -- [ ] Clear separation from other modules - -## Quality Checks - -### Completeness - -- [ ] At least one functional component (not all placeholders) -- [ ] Core functionality is implementable -- [ ] Module provides clear value - -### Consistency - -- [ ] Formatting consistent across files -- [ ] Variable naming follows conventions -- [ ] Communication style appropriate for domain - -### Scalability - -- [ ] Structure supports future growth -- [ ] Component organization is logical -- [ ] No hard-coded limits - -## Testing and Validation - -### Structural Validation - -- [ ] YAML files parse without errors -- [ ] JSON files (if any) are valid -- [ ] XML files (if any) are well-formed -- [ ] No syntax errors in JavaScript files - -### Path Validation - -- [ ] All referenced paths exist or are clearly marked as TODO -- [ ] Variable substitutions are correct -- [ ] No absolute paths (unless intentional) - -### Installation Testing - -- [ ] Installation steps can be simulated -- [ ] No circular dependencies -- [ ] Uninstall process defined (if complex) - -## Final Checks - -### Ready for Use - -- [ ] Module can be installed without errors -- [ ] At least one component is functional -- [ ] User can understand how to get started -- [ ] Next steps are clear - -### Professional Quality - -- [ ] No placeholder text remains (unless marked TODO) -- [ ] No obvious typos or grammar issues -- [ ] Professional tone throughout -- [ ] Contact/support information provided - -## Issues Found - -### Critical Issues - - - -### Warnings - - - -### Improvements - - - -### Missing Components - - - -## Module Complexity Assessment - -### Complexity Rating - -- [ ] Simple (1-2 agents, 2-3 workflows) -- [ ] Standard (3-5 agents, 5-10 workflows) -- [ ] Complex (5+ agents, 10+ workflows) - -### Readiness Level - -- [ ] Prototype (Basic structure, mostly placeholders) -- [ ] Alpha (Core functionality works) -- [ ] Beta (Most features complete, needs testing) -- [ ] Release (Full functionality, documented) diff --git a/src/modules/bmb/workflows-legacy/create-module/installer-templates/install-config.yaml b/src/modules/bmb/workflows-legacy/create-module/installer-templates/install-config.yaml deleted file mode 100644 index 19462d3e..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/installer-templates/install-config.yaml +++ /dev/null @@ -1,92 +0,0 @@ -# {{MODULE_NAME}} Module Configuration -# This file defines installation questions and module configuration values - -code: "{{MODULE_CODE}}" -name: "{{MODULE_NAME}}" -default_selected: "{{DEFAULT_SELECTED}}" # true if this should be selected by default - -# Welcome message shown during installation -prompt: - - "{{WELCOME_MESSAGE_LINE_1}}" - - "{{WELCOME_MESSAGE_LINE_2}}" -# Core config values are automatically inherited: -## user_name -## communication_language -## document_output_language -## output_folder - -# ============================================================================ -# CONFIGURATION FIELDS -# ============================================================================ -# -# Each field can be: -# 1. INTERACTIVE (has 'prompt' - asks user during installation) -# 2. STATIC (no 'prompt' - just uses 'result' value) -# -# Field structure: -# field_name: -# prompt: "Question to ask user" (optional - omit for static values) -# default: "default_value" (optional) -# result: "{value}" or "static-value" -# single-select: [...] (optional - for dropdown) -# multi-select: [...] (optional - for checkboxes) -# -# Special placeholders in result: -# {value} - replaced with user's answer -# {project-root} - replaced with project root path -# {directory_name} - replaced with project directory name -# {module_code} - replaced with this module's code -# ============================================================================ - -# EXAMPLE: Interactive text input -# example_project_name: -# prompt: "What is your project name?" -# default: "{directory_name}" -# result: "{value}" - -# EXAMPLE: Interactive single-select dropdown -# example_skill_level: -# prompt: "What is your experience level?" -# default: "intermediate" -# result: "{value}" -# single-select: -# - value: "beginner" -# label: "Beginner - New to this domain" -# - value: "intermediate" -# label: "Intermediate - Familiar with basics" -# - value: "expert" -# label: "Expert - Deep knowledge" - -# EXAMPLE: Interactive multi-select checkboxes -# example_features: -# prompt: -# - "Which features do you want to enable?" -# - "(Select all that apply)" -# result: "{value}" -# multi-select: -# - "Feature A" -# - "Feature B" -# - "Feature C" - -# EXAMPLE: Interactive path input -# example_output_path: -# prompt: "Where should outputs be saved?" -# default: "output/{{MODULE_CODE}}" -# result: "{project-root}/{value}" - -# EXAMPLE: Static value (no user prompt) -# example_static_setting: -# result: "hardcoded-value" - -# EXAMPLE: Static path -# module_data_path: -# result: "{project-root}/{bmad_folder}/{{MODULE_CODE}}/data" - -# ============================================================================ -# YOUR MODULE CONFIGURATION FIELDS -# ============================================================================ -# Replace examples above with your module's actual configuration needs. -# Delete this comment block and the examples when implementing. -# ============================================================================ - -# TODO: INSERT {MODULE_CONFIG_FIELDS} HERE diff --git a/src/modules/bmb/workflows-legacy/create-module/installer-templates/installer.js b/src/modules/bmb/workflows-legacy/create-module/installer-templates/installer.js deleted file mode 100644 index 4c396b18..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/installer-templates/installer.js +++ /dev/null @@ -1,231 +0,0 @@ -/* eslint-disable unicorn/prefer-module, unicorn/prefer-node-protocol */ -/** - * {{MODULE_NAME}} Module Installer - * Custom installation logic for complex module setup - * - * This is a template - replace {{VARIABLES}} with actual values - */ - -// const fs = require('fs'); // Uncomment when implementing file operations -const path = require('path'); - -/** - * Main installation function - * Called by BMAD installer when processing the module - */ -async function installModule(config) { - console.log('๐Ÿš€ Installing {{MODULE_NAME}} module...'); - console.log(` Version: ${config.version}`); - console.log(` Module Code: ${config.module_code}`); - - try { - // Step 1: Validate environment - await validateEnvironment(config); - - // Step 2: Setup custom configurations - await setupConfigurations(config); - - // Step 3: Initialize module-specific features - await initializeFeatures(config); - - // Step 4: Run post-install tasks - await runPostInstallTasks(config); - - console.log('โœ… {{MODULE_NAME}} module installed successfully!'); - return { - success: true, - message: 'Module installed and configured', - }; - } catch (error) { - console.error('โŒ Installation failed:', error.message); - return { - success: false, - error: error.message, - }; - } -} - -/** - * Validate that the environment meets module requirements - */ -async function validateEnvironment(config) { - console.log(' Validating environment...'); - - // TODO: Add environment checks - // Examples: - // - Check for required tools/binaries - // - Verify permissions - // - Check network connectivity - // - Validate API keys - - // Placeholder validation - if (!config.project_root) { - throw new Error('Project root not defined'); - } - - console.log(' โœ“ Environment validated'); -} - -/** - * Setup module-specific configurations - */ -async function setupConfigurations(config) { - console.log(' Setting up configurations...'); - - // TODO: Add configuration setup - // Examples: - // - Create config files - // - Setup environment variables - // - Configure external services - // - Initialize settings - - // Placeholder configuration - const configPath = path.join(config.project_root, 'bmad', config.module_code, 'config.json'); - - // Example of module config that would be created - // const moduleConfig = { - // installed: new Date().toISOString(), - // settings: { - // // Add default settings - // } - // }; - - // Note: This is a placeholder - actual implementation would write the file - console.log(` โœ“ Would create config at: ${configPath}`); - console.log(' โœ“ Configurations complete'); -} - -/** - * Initialize module-specific features - */ -async function initializeFeatures(config) { - console.log(' Initializing features...'); - - // TODO: Add feature initialization - // Examples: - // - Create database schemas - // - Setup cron jobs - // - Initialize caches - // - Register webhooks - // - Setup file watchers - - // Module-specific initialization based on type - switch (config.module_category) { - case 'data': { - await initializeDataFeatures(config); - break; - } - case 'automation': { - await initializeAutomationFeatures(config); - break; - } - case 'integration': { - await initializeIntegrationFeatures(config); - break; - } - default: { - console.log(' - Using standard initialization'); - } - } - - console.log(' โœ“ Features initialized'); -} - -/** - * Initialize data-related features - */ -async function initializeDataFeatures(/* config */) { - console.log(' - Setting up data storage...'); - // TODO: Setup databases, data folders, etc. -} - -/** - * Initialize automation features - */ -async function initializeAutomationFeatures(/* config */) { - console.log(' - Setting up automation hooks...'); - // TODO: Setup triggers, watchers, schedulers -} - -/** - * Initialize integration features - */ -async function initializeIntegrationFeatures(/* config */) { - console.log(' - Setting up integrations...'); - // TODO: Configure APIs, webhooks, external services -} - -/** - * Run post-installation tasks - */ -async function runPostInstallTasks(/* config */) { - console.log(' Running post-install tasks...'); - - // TODO: Add post-install tasks - // Examples: - // - Generate sample data - // - Run initial workflows - // - Send notifications - // - Update registries - - console.log(' โœ“ Post-install tasks complete'); -} - -/** - * Initialize database for the module (optional) - */ -async function initDatabase(/* config */) { - console.log(' Initializing database...'); - - // TODO: Add database initialization - // This function can be called from install-config.yaml - - console.log(' โœ“ Database initialized'); -} - -/** - * Generate sample data for the module (optional) - */ -async function generateSamples(config) { - console.log(' Generating sample data...'); - - // TODO: Create sample files, data, configurations - // This helps users understand how to use the module - - const samplesPath = path.join(config.project_root, 'examples', config.module_code); - - console.log(` - Would create samples at: ${samplesPath}`); - console.log(' โœ“ Samples generated'); -} - -/** - * Uninstall the module (cleanup) - */ -async function uninstallModule(/* config */) { - console.log('๐Ÿ—‘๏ธ Uninstalling {{MODULE_NAME}} module...'); - - try { - // TODO: Add cleanup logic - // - Remove configurations - // - Clean up databases - // - Unregister services - // - Backup user data - - console.log('โœ… Module uninstalled successfully'); - return { success: true }; - } catch (error) { - console.error('โŒ Uninstall failed:', error.message); - return { - success: false, - error: error.message, - }; - } -} - -// Export functions for BMAD installer -module.exports = { - installModule, - initDatabase, - generateSamples, - uninstallModule, -}; diff --git a/src/modules/bmb/workflows-legacy/create-module/instructions.md b/src/modules/bmb/workflows-legacy/create-module/instructions.md deleted file mode 100644 index ec45b3aa..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/instructions.md +++ /dev/null @@ -1,577 +0,0 @@ -# Build Module - Interactive Module Builder Instructions - -The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml -You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml -Study existing modules in: {project-root}/{bmad_folder}/ for patterns -Communicate in {communication_language} throughout the module creation process -โš ๏ธ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever. - - - - -Do you want to brainstorm module ideas first? [y/n] - - - Invoke brainstorming workflow: {brainstorming_workflow} - Pass context data: {brainstorming_context} - Wait for brainstorming session completion - Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps - - - - Proceed directly to Step 0 - - -brainstorming_results - - - -Do you have a module brief or should we create one? [have/create/skip] - - - Invoke module-brief workflow: {project-root}/{bmad_folder}/bmb/workflows/module-brief/workflow.yaml - Wait for module brief completion - Load the module brief to use as blueprint - - - - Provide path to module brief document - Load the module brief and use it to pre-populate all planning sections - - - - Proceed directly to Step 1 - - -module_brief - - - -Load and study the complete module structure guide -Load module structure guide: {module_structure_guide} -Understand module types (Simple/Standard/Complex) -Review directory structures and component guidelines -Study the installation infrastructure patterns - -If brainstorming or module brief was completed, reference those results to guide the conversation - -Guide user to articulate their module's vision, exploring its purpose, what it will help with, and who will use it - -Based on their description, intelligently propose module details: - -**Module Identity Development:** - -1. **Module name** - Extract from their description with proper title case -2. **Module code** - Generate kebab-case from name following patterns: - - Multi-word descriptive names โ†’ shortened kebab-case - - Domain-specific terms โ†’ recognizable abbreviations - - Present suggested code and confirm it works for paths like {bmad_folder}/{{code}}/agents/ -3. **Module purpose** - Refine their description into 1-2 clear sentences -4. **Target audience** - Infer from context or ask if unclear - -**Module Theme Reference Categories:** - -- Domain-Specific (Legal, Medical, Finance, Education) -- Creative (RPG/Gaming, Story Writing, Music Production) -- Technical (DevOps, Testing, Architecture, Security) -- Business (Project Management, Marketing, Sales) -- Personal (Journaling, Learning, Productivity) - -Determine output location: - -- Module will be created at {installer_output_folder} - -Store module identity for scaffolding - -module_identity - - - -Based on the module purpose, intelligently propose an initial component architecture - -**Agents Planning:** - -Suggest agents based on module purpose, considering agent types (Simple/Expert/Module) appropriate to each role - -**Example Agent Patterns by Domain:** - -- Data/Analytics: Analyst, Designer, Builder roles -- Gaming/Creative: Game Master, Generator, Storytelling roles -- Team/Business: Manager, Facilitator, Documentation roles - -Present suggested agent list with types, explaining we can start with core ones and add others later -Confirm which agents resonate with their vision - -**Workflows Planning:** - -Intelligently suggest workflows that complement the proposed agents - -**Example Workflow Patterns by Domain:** - -- Data/Analytics: analyze-dataset, create-dashboard, generate-report -- Gaming/Creative: session-prep, generate-encounter, world-building -- Team/Business: planning, facilitation, documentation workflows - -For each workflow, note whether it should be Document, Action, or Interactive type -Confirm which workflows are most important to start with -Determine which to create now vs placeholder - -**Tasks Planning (optional):** -Any special tasks that don't warrant full workflows? - -For each task, capture name, purpose, and whether standalone or supporting - -module_components - - - -Based on components, intelligently determine module type using criteria: - -**Simple Module Criteria:** - -- 1-2 agents, all Simple type -- 1-3 workflows -- No complex integrations - -**Standard Module Criteria:** - -- 2-4 agents with mixed types -- 3-8 workflows -- Some shared resources - -**Complex Module Criteria:** - -- 4+ agents or multiple Module-type agents -- 8+ workflows -- Complex interdependencies -- External integrations - -Present determined module type with explanation of what structure will be set up - -module_type - - - -Use module path determined in Step 1: -- The module base path is {{module_path}} - -Create base module directories at the determined path: - -``` -{{module_code}}/ -โ”œโ”€โ”€ agents/ # Agent definitions -โ”œโ”€โ”€ workflows/ # Workflow folders -โ”œโ”€โ”€ tasks/ # Task files (if any) -โ”œโ”€โ”€ templates/ # Shared templates -โ”œโ”€โ”€ data/ # Module data files -โ”œโ”€โ”€ _module-installer/ # Installation configuration -โ”‚ โ””โ”€โ”€ install-config.yaml # Configuration questions (config.yaml generated at install time) -โ””โ”€โ”€ README.md # Module documentation -``` - -Create installer directory: - -**INSTALLED MODULE STRUCTURE** (generated in target project after installation): - -``` -{{module_code}}/ -โ”œโ”€โ”€ agents/ # Compiled agents -โ”œโ”€โ”€ workflows/ # Workflow instances -โ”œโ”€โ”€ config.yaml # Generated from install-config.yaml during installation -โ””โ”€โ”€ data/ # User data directory -``` - -**SOURCE MODULE** (module-installer is for installation only, not copied to target): - -``` -{{module_code}}/ -โ”œโ”€โ”€ _module-installer/ -โ”‚ โ”œโ”€โ”€ install-config.yaml # Configuration questions -โ”‚ โ”œโ”€โ”€ installer.js # Optional custom installation logic -โ”‚ โ””โ”€โ”€ assets/ # Files to copy during install -``` - -directory_structure - - - -Based on the module purpose and components, determine what configuration settings the module needs - -**Configuration Field Planning:** - -Does your module need any user-configurable settings during installation? - -**Common configuration patterns:** - -- Output/data paths (where module saves files) -- Feature toggles (enable/disable functionality) -- Integration settings (API keys, external services) -- Behavior preferences (automation level, detail level) -- User skill level or experience settings - -For each configuration field needed, determine: - -1. Field name (snake_case) -2. Whether it's INTERACTIVE (asks user) or STATIC (hardcoded) -3. Prompt text (if interactive) -4. Default value -5. Type: text input, single-select, or multi-select -6. Result template (how the value gets stored) - -Store planned configuration fields for installer generation in step 7 - -module_config_fields - - - -Create your first agent now? [yes/no] - - - Invoke agent builder workflow: {agent_builder} - Pass module_components as context input - Guide them to create the primary agent for the module - -Save to module's agents folder: - -- Save to {{module_path}}/agents/ - - - - Create placeholder file in agents folder with TODO notes including agent name, purpose, and type - - -first_agent - - - -Create your first workflow now? [yes/no] - - - Invoke workflow builder: {workflow_builder} - Pass module_components as context input - Guide them to create the primary workflow - -Save to module's workflows folder: - -- Save to {{module_path}}/workflows/ - - - - Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow - - -first_workflow - - - -Load installer template from: {installer_templates}/install-config.yaml - -IMPORTANT: Create install-config.yaml NOT install-config.yaml -This is the STANDARD format that BMAD installer uses - -Create module-installer/install-config.yaml: - -```yaml -# {{module_name}} Module Configuration -# This file defines installation questions and module configuration values - -code: {{module_code}} -name: "{{module_name}}" -default_selected: false # Set to true if this should be selected by default - -# Welcome message shown during installation -prompt: - - "Thank you for choosing {{module_name}}!" - - "{{brief_module_description}}" - -# Core config values are automatically inherited: -## user_name -## communication_language -## document_output_language -## output_folder - -# ============================================================================ -# CONFIGURATION FIELDS (from step 4 planning) -# ============================================================================ -# Each field can be: -# 1. INTERACTIVE (has 'prompt' - asks user during installation) -# 2. STATIC (no 'prompt' - just uses 'result' value) -# ============================================================================ - -# EXAMPLE Interactive text input: -# output_path: -# prompt: "Where should {{module_code}} save outputs?" -# default: "output/{{module_code}}" -# result: "{project-root}/{value}" - -# EXAMPLE Interactive single-select: -# detail_level: -# prompt: "How detailed should outputs be?" -# default: "standard" -# result: "{value}" -# single-select: -# - value: "minimal" -# label: "Minimal - Brief summaries only" -# - value: "standard" -# label: "Standard - Balanced detail" -# - value: "detailed" -# label: "Detailed - Comprehensive information" - -# EXAMPLE Static value: -# module_version: -# result: "1.0.0" - -# EXAMPLE Static path: -# data_path: -# result: "{project-root}/{bmad_folder}/{{module_code}}/data" - -{{generated_config_fields_from_step_4}} -``` - -Save location: - -- Save to {{module_path}}/module-installer/install-config.yaml - -Does your module need custom installation logic (database setup, API registration, etc.)? - - - ```javascript - // {{module_name}} Module Installer - // Custom installation logic - -- @param {Object} options - Installation options -- @param {string} options.projectRoot - Project root directory -- @param {Object} options.config - Module configuration from install-config.yaml -- @param {Array} options.installedIDEs - List of IDE codes being configured -- @param {Object} options.logger - Logger instance (log, warn, error methods) -- @returns {boolean} - true if successful, false to abort installation - - async function install(options) { - const { projectRoot, config, installedIDEs, logger } = options; - - logger.log('Running {{module_name}} custom installer...'); - - // TODO: Add custom installation logic here - // Examples: - // - Create database tables - // - Download external assets - // - Configure API connections - // - Initialize data files - // - Set up webhooks or integrations - - logger.log('{{module_name}} custom installation complete!'); - return true; - -} - -module.exports = { install }; - -````` - -Save location: - -- Save to {{module_path}}/module-installer/installer.js - - - -Skip installer.js creation - the standard installer will handle everything - - -installer_config - - - -Generate comprehensive README.md: - -````markdown -# {{module_name}} - -{{module_purpose}} - -## Overview - -This module provides: -{{component_summary}} - -## Installation - -```bash -bmad install {{module_code}} -````` - -```` - -## Components - -### Agents ({{agent_count}}) - -{{agent_documentation}} - -### Workflows ({{workflow_count}}) - -{{workflow_documentation}} - -### Tasks ({{task_count}}) - -{{task_documentation}} - -## Quick Start - -1. **Load the main agent:** - - ``` - agent {{primary_agent}} - ``` - -2. **View available commands:** - - ``` - *help - ``` - -3. **Run the main workflow:** - ``` - workflow {{primary_workflow}} - ``` - -## Module Structure - -``` -{{directory_tree}} -``` - -## Configuration - -The module can be configured in `{bmad_folder}/{{module_code}}/config.yaml` - -Key settings: -{{configuration_options}} - -## Examples - -### Example 1: {{example_use_case}} - -{{example_walkthrough}} - -## Development Roadmap - -- [ ] {{roadmap_item_1}} -- [ ] {{roadmap_item_2}} -- [ ] {{roadmap_item_3}} - -## Contributing - -To extend this module: - -1. Add new agents using `create-agent` workflow -2. Add new workflows using `create-workflow` workflow -3. Submit improvements via pull request - -## Author - -Created by {{user_name}} on {{date}} - -```` - -module_readme - - - -Create a development roadmap for remaining components: - -**TODO.md file:** - -```markdown -# {{module_name}} Development Roadmap - -## Phase 1: Core Components - -{{phase1_tasks}} - -## Phase 2: Enhanced Features - -{{phase2_tasks}} - -## Phase 3: Polish and Integration - -{{phase3_tasks}} - -## Quick Commands - -Create new agent: -``` - -workflow create-agent - -``` - -Create new workflow: -``` - -workflow create-workflow - -``` - -## Notes -{{development_notes}} -``` - -Ask if user wants to: - -1. Continue building more components now -2. Save roadmap for later development -3. Test what's been built so far - -development_roadmap - - - -Run validation checks: - -**Structure validation:** - -- All required directories created -- Config files properly formatted -- Installer configuration valid - -**Component validation:** - -- At least one agent or workflow exists (or planned) -- All references use correct paths -- Module code consistent throughout - -**Documentation validation:** - -- README.md complete -- Installation instructions clear -- Examples provided - -Present summary to {user_name}: - -- Module name and code -- Location path -- Agent count (created vs planned) -- Workflow count (created vs planned) -- Task count -- Installer status - -Provide next steps guidance: - -1. Complete remaining components using roadmap -2. Run the BMAD Method installer to this project location -3. Select 'Compile Agents' option after confirming folder -4. Module will be compiled and available for use -5. Test with bmad install command -6. Share or integrate with existing system - -Would you like to: - -- Create another component now? -- Test the module installation? -- Exit and continue later? - - -module_summary - - - diff --git a/src/modules/bmb/workflows-legacy/create-module/module-structure.md b/src/modules/bmb/workflows-legacy/create-module/module-structure.md deleted file mode 100644 index 591ba1ad..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/module-structure.md +++ /dev/null @@ -1,400 +0,0 @@ -# BMAD Module Structure Guide - -## What is a Module? - -A BMAD module is a self-contained package of agents, workflows, tasks, and resources that work together to provide specialized functionality. Think of it as an expansion pack for the BMAD Method. - -## Module Architecture - -### Core Structure - -``` -# SOURCE MODULE (in BMAD-METHOD project) -src/modules/{module-code}/ -โ”œโ”€โ”€ agents/ # Agent definitions (.agent.yaml) -โ”œโ”€โ”€ workflows/ # Workflow folders -โ”œโ”€โ”€ tasks/ # Task files -โ”œโ”€โ”€ tools/ # Tool files -โ”œโ”€โ”€ templates/ # Shared templates -โ”œโ”€โ”€ data/ # Static data -โ”œโ”€โ”€ _module-installer/ # Installation configuration -โ”‚ โ”œโ”€โ”€ install-config.yaml # Installation questions & config -โ”‚ โ”œโ”€โ”€ installer.js # Optional custom install logic -โ”‚ โ””โ”€โ”€ assets/ # Files to copy during install -โ””โ”€โ”€ README.md # Module documentation - -# INSTALLED MODULE (in target project) -{project-root}/{bmad_folder}/{module-code}/ -โ”œโ”€โ”€ agents/ # Compiled agent files (.md) -โ”œโ”€โ”€ workflows/ # Workflow instances -โ”œโ”€โ”€ tasks/ # Task files -โ”œโ”€โ”€ tools/ # Tool files -โ”œโ”€โ”€ templates/ # Templates -โ”œโ”€โ”€ data/ # Module data -โ”œโ”€โ”€ config.yaml # Generated from install-config.yaml -โ””โ”€โ”€ README.md # Module documentation -``` - -## Module Types by Complexity - -### Simple Module (1-2 agents, 2-3 workflows) - -Perfect for focused, single-purpose tools. - -**Example: Code Review Module** - -- 1 Reviewer Agent -- 2 Workflows: quick-review, deep-review -- Clear, narrow scope - -### Standard Module (3-5 agents, 5-10 workflows) - -Comprehensive solution for a domain. - -**Example: Project Management Module** - -- PM Agent, Scrum Master Agent, Analyst Agent -- Workflows: sprint-planning, retrospective, roadmap, user-stories -- Integrated component ecosystem - -### Complex Module (5+ agents, 10+ workflows) - -Full platform or framework. - -**Example: RPG Toolkit Module** - -- DM Agent, NPC Agent, Monster Agent, Loot Agent, Map Agent -- 15+ workflows for every aspect of game management -- Multiple interconnected systems - -## Module Naming Conventions - -### Module Code (kebab-case) - -- `data-viz` - Data Visualization -- `team-collab` - Team Collaboration -- `rpg-toolkit` - RPG Toolkit -- `legal-assist` - Legal Assistant - -### Module Name (Title Case) - -- "Data Visualization Suite" -- "Team Collaboration Platform" -- "RPG Game Master Toolkit" -- "Legal Document Assistant" - -## Component Guidelines - -### Agents per Module - -**Recommended Distribution:** - -- **Primary Agent (1)**: The main interface/orchestrator -- **Specialist Agents (2-4)**: Domain-specific experts -- **Utility Agents (0-2)**: Helper/support functions - -**Anti-patterns to Avoid:** - -- Too many overlapping agents -- Agents that could be combined -- Agents without clear purpose - -### Workflows per Module - -**Categories:** - -- **Core Workflows (2-3)**: Essential functionality -- **Feature Workflows (3-5)**: Specific capabilities -- **Utility Workflows (2-3)**: Supporting operations -- **Admin Workflows (0-2)**: Maintenance/config - -**Workflow Complexity Guide:** - -- Simple: 3-5 steps, single output -- Standard: 5-10 steps, multiple outputs -- Complex: 10+ steps, conditional logic, sub-workflows - -### Tasks per Module - -Tasks should be used for: - -- Single-operation utilities -- Shared subroutines -- Quick actions that don't warrant workflows - -## Module Dependencies - -### Internal Dependencies - -- Agents can reference module workflows -- Workflows can invoke module tasks -- Tasks can use module templates - -### External Dependencies - -- Reference other modules via full paths -- Declare dependencies in config.yaml -- Version compatibility notes - -### Workflow Vendoring (Advanced) - -For modules that need workflows from other modules but want to remain standalone, use **workflow vendoring**: - -**In Agent YAML:** - -```yaml -menu: - - trigger: command-name - workflow: '{project-root}/{bmad_folder}/SOURCE_MODULE/workflows/path/workflow.yaml' - workflow-install: '{project-root}/{bmad_folder}/THIS_MODULE/workflows/vendored/workflow.yaml' - description: 'Command description' -``` - -**What Happens:** - -- During installation, workflows are copied from `workflow` to `workflow-install` location -- Vendored workflows get `config_source` updated to reference this module's config -- Compiled agent only references the `workflow-install` path -- Module becomes fully standalone - no source module dependency required - -**Use Cases:** - -- Specialized modules that reuse common workflows with different configs -- Domain-specific adaptations (e.g., game dev using standard dev workflows) -- Testing workflows in isolation - -**Benefits:** - -- Module independence (no forced dependencies) -- Clean namespace (workflows in your module) -- Config isolation (use your module's settings) -- Customization ready (modify vendored workflows freely) - -## Installation Infrastructure - -### Required: module-installer/install-config.yaml - -This file defines both installation questions AND static configuration values: - -```yaml -# Module metadata -code: module-code -name: 'Module Name' -default_selected: false - -# Welcome message during installation -prompt: - - 'Welcome to Module Name!' - - 'Brief description here' - -# Core values automatically inherited from installer: -## user_name -## communication_language -## document_output_language -## output_folder - -# INTERACTIVE fields (ask user during install) -output_location: - prompt: 'Where should module outputs be saved?' - default: 'output/module-code' - result: '{project-root}/{value}' - -feature_level: - prompt: 'Which feature set?' - default: 'standard' - result: '{value}' - single-select: - - value: 'basic' - label: 'Basic - Core features only' - - value: 'standard' - label: 'Standard - Recommended features' - - value: 'advanced' - label: 'Advanced - All features' - -# STATIC fields (no prompt, just hardcoded values) -module_version: - result: '1.0.0' - -data_path: - result: '{project-root}/{bmad_folder}/module-code/data' -``` - -**Key Points:** - -- File is named `install-config.yaml` (NOT install-config.yaml) -- Supports both interactive prompts and static values -- `result` field uses placeholders: `{value}`, `{project-root}`, `{directory_name}` -- Installer generates final `config.yaml` from this template - -### Optional: module-installer/installer.js - -For complex installations requiring custom logic: - -```javascript -/** - * @param {Object} options - Installation options - * @param {string} options.projectRoot - Target project directory - * @param {Object} options.config - Config from install-config.yaml - * @param {Array} options.installedIDEs - IDEs being configured - * @param {Object} options.logger - Logger (log, warn, error) - * @returns {boolean} - true if successful - */ -async function install(options) { - // Custom installation logic here - // - Database setup - // - API configuration - // - External downloads - // - Integration setup - - return true; -} - -module.exports = { install }; -``` - -### Optional: module-installer/assets/ - -Files to copy during installation: - -- External configurations -- Documentation -- Example files -- Integration scripts - -## Module Lifecycle - -### Development Phases - -1. **Planning Phase** - - Define scope and purpose - - Identify components - - Design architecture - -2. **Scaffolding Phase** - - Create directory structure - - Generate configurations - - Setup installer - -3. **Building Phase** - - Create agents incrementally - - Build workflows progressively - - Add tasks as needed - -4. **Testing Phase** - - Test individual components - - Verify integration - - Validate installation - -5. **Deployment Phase** - - Package module - - Document usage - - Distribute/share - -## Best Practices - -### Module Cohesion - -- All components should relate to module theme -- Clear boundaries between modules -- No feature creep - -### Progressive Enhancement - -- Start with MVP (1 agent, 2 workflows) -- Add components based on usage -- Refactor as patterns emerge - -### Documentation Standards - -- Every module needs README.md -- Each agent needs purpose statement -- Workflows need clear descriptions -- Include examples and quickstart - -### Naming Consistency - -- Use module code prefix for uniqueness -- Consistent naming patterns within module -- Clear, descriptive names - -## Example Modules - -### Example 1: Personal Productivity - -``` -productivity/ -โ”œโ”€โ”€ agents/ -โ”‚ โ”œโ”€โ”€ task-manager.md # GTD methodology -โ”‚ โ””โ”€โ”€ focus-coach.md # Pomodoro timer -โ”œโ”€โ”€ workflows/ -โ”‚ โ”œโ”€โ”€ daily-planning/ # Morning routine -โ”‚ โ”œโ”€โ”€ weekly-review/ # Week retrospective -โ”‚ โ””โ”€โ”€ project-setup/ # New project init -โ””โ”€โ”€ config.yaml -``` - -### Example 2: Content Creation - -``` -content/ -โ”œโ”€โ”€ agents/ -โ”‚ โ”œโ”€โ”€ writer.md # Blog/article writer -โ”‚ โ”œโ”€โ”€ editor.md # Copy editor -โ”‚ โ””โ”€โ”€ seo-optimizer.md # SEO specialist -โ”œโ”€โ”€ workflows/ -โ”‚ โ”œโ”€โ”€ blog-post/ # Full blog creation -โ”‚ โ”œโ”€โ”€ social-media/ # Social content -โ”‚ โ”œโ”€โ”€ email-campaign/ # Email sequence -โ”‚ โ””โ”€โ”€ content-calendar/ # Planning -โ””โ”€โ”€ templates/ - โ”œโ”€โ”€ blog-template.md - โ””โ”€โ”€ email-template.md -``` - -### Example 3: DevOps Automation - -``` -devops/ -โ”œโ”€โ”€ agents/ -โ”‚ โ”œโ”€โ”€ deploy-master.md # Deployment orchestrator -โ”‚ โ”œโ”€โ”€ monitor.md # System monitoring -โ”‚ โ”œโ”€โ”€ incident-responder.md # Incident management -โ”‚ โ””โ”€โ”€ infra-architect.md # Infrastructure design -โ”œโ”€โ”€ workflows/ -โ”‚ โ”œโ”€โ”€ ci-cd-setup/ # Pipeline creation -โ”‚ โ”œโ”€โ”€ deploy-app/ # Application deployment -โ”‚ โ”œโ”€โ”€ rollback/ # Emergency rollback -โ”‚ โ”œโ”€โ”€ health-check/ # System verification -โ”‚ โ””โ”€โ”€ incident-response/ # Incident handling -โ”œโ”€โ”€ tasks/ -โ”‚ โ”œโ”€โ”€ check-status.md # Quick status check -โ”‚ โ””โ”€โ”€ notify-team.md # Team notifications -โ””โ”€โ”€ data/ - โ””โ”€โ”€ runbooks/ # Operational guides -``` - -## Module Evolution Pattern - -``` -Simple Module โ†’ Standard Module โ†’ Complex Module โ†’ Module Suite - (MVP) (Enhanced) (Complete) (Ecosystem) -``` - -## Common Pitfalls - -1. **Over-engineering**: Starting too complex -2. **Under-planning**: No clear architecture -3. **Poor boundaries**: Module does too much -4. **Weak integration**: Components don't work together -5. **Missing docs**: No clear usage guide - -## Success Metrics - -A well-designed module has: - -- โœ… Clear, focused purpose -- โœ… Cohesive components -- โœ… Smooth installation -- โœ… Comprehensive docs -- โœ… Room for growth -- โœ… Happy users! diff --git a/src/modules/bmb/workflows-legacy/create-module/workflow.yaml b/src/modules/bmb/workflows-legacy/create-module/workflow.yaml deleted file mode 100644 index a47bdbfb..00000000 --- a/src/modules/bmb/workflows-legacy/create-module/workflow.yaml +++ /dev/null @@ -1,52 +0,0 @@ -# Build Module Workflow Configuration -name: create-module -description: "Interactive workflow to build complete BMAD modules with agents, workflows, tasks, and installation infrastructure" -author: "BMad" - -# Critical variables load from config_source -config_source: "{project-root}/{bmad_folder}/bmb/config.yaml" -custom_module_location: "{config_source}:custom_module_location" -communication_language: "{config_source}:communication_language" -user_name: "{config_source}:user_name" - -# Reference guides for module building -module_structure_guide: "{installed_path}/module-structure.md" -installer_templates: "{installed_path}/installer-templates/" - -# Use existing build workflows -agent_builder: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml" -workflow_builder: "{project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml" -brainstorming_workflow: "{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml" -brainstorming_context: "{installed_path}/brainstorm-context.md" - -# Reference examples - for learning patterns -bmm_module_dir: "{project-root}/{bmad_folder}/bmm/" -cis_module_dir: "{project-root}/{bmad_folder}/cis/" -existing_agents_dir: "{project-root}/{bmad_folder}/*/agents/" -existing_workflows_dir: "{project-root}/{bmad_folder}/*/workflows/" - -# Optional user inputs - discovered if they exist -input_file_patterns: - module_brief: - description: "Module brief with vision and requirements (optional)" - whole: "{output_folder}/module-brief-*.md" - load_strategy: "FULL_LOAD" - brainstorming: - description: "Brainstorming session outputs (optional)" - whole: "{output_folder}/brainstorming-*.md" - load_strategy: "FULL_LOAD" - -# Module path and component files -installed_path: "{project-root}/{bmad_folder}/bmb/workflows/create-module" -template: false # This is an interactive scaffolding workflow -instructions: "{installed_path}/instructions.md" -validation: "{installed_path}/checklist.md" - -# Output configuration - creates entire module structure -# Save to custom_module_location/{{module_code}} -installer_output_folder: "{custom_module_location}/{{module_code}}" - -standalone: true - -# Web bundle configuration -web_bundle: false # BMB workflows run locally in BMAD-METHOD project diff --git a/src/modules/bmb/workflows-legacy/edit-module/checklist.md b/src/modules/bmb/workflows-legacy/edit-module/checklist.md index 88d68711..b583acd2 100644 --- a/src/modules/bmb/workflows-legacy/edit-module/checklist.md +++ b/src/modules/bmb/workflows-legacy/edit-module/checklist.md @@ -24,7 +24,6 @@ Use this checklist to validate module edits meet BMAD Core standards. ### Optional Fields (if used) -- [ ] custom_agent_location documented - [ ] custom_module_location documented - [ ] Module-specific fields documented in README diff --git a/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md b/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md index 304bbb98..d4ad0f7e 100644 --- a/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md +++ b/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md @@ -2,12 +2,24 @@ ## Installation -```bash -# Quick install (interactive) -npx bmad-method agent-install --source ./{agent_filename}.agent.yaml +Create a `custom.yaml` file in the agent folder: -# Quick install (non-interactive) -npx bmad-method agent-install --source ./{agent_filename}.agent.yaml --defaults +```yaml +code: { agent_code } +name: '{agent_name}' +default_selected: true +``` + +Then run: + +```bash +npx bmad-method install +``` + +Or if you have bmad-cli installed globally: + +```bash +bmad install ``` ## About This Agent diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md b/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md index ec677983..702dc0b3 100644 --- a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md +++ b/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md @@ -51,7 +51,7 @@ menu: # Direct sidecar file action - trigger: 'insight' - action: 'Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md' + action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md' description: 'Record a meaningful insight' ``` @@ -63,9 +63,9 @@ Expert Agents MUST load sidecar files explicitly: ```yaml critical_actions: - - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md' - - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md' - - 'ONLY read/write files in {agent-folder}/journal-keeper-sidecar/' + - 'Load COMPLETE file ./journal-keeper-sidecar/memories.md' + - 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md' + - 'ONLY read/write files in ./journal-keeper-sidecar/' ``` **Key points:** diff --git a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml index 84595371..78429290 100644 --- a/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml +++ b/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml @@ -20,9 +20,9 @@ agent: - Reflection transforms experience into wisdom critical_actions: - - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/memories.md and remember all past insights" - - "Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" - - "ONLY read/write files in {agent-folder}/journal-keeper-sidecar/ - this is our private space" + - "Load COMPLETE file ./journal-keeper-sidecar/memories.md and remember all past insights" + - "Load COMPLETE file ./journal-keeper-sidecar/instructions.md and follow ALL journaling protocols" + - "ONLY read/write files in ./journal-keeper-sidecar/ - this is our private space" - "Track mood patterns, recurring themes, and breakthrough moments" - "Reference past entries naturally to show continuity" @@ -120,7 +120,7 @@ agent: description: "Write today's journal entry" - trigger: quick - action: "Save a quick, unstructured entry to {agent-folder}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" + action: "Save a quick, unstructured entry to ./journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed" description: "Quick capture without prompts" - trigger: mood @@ -140,13 +140,13 @@ agent: description: "Reflect on the past week" - trigger: insight - action: "Document this breakthrough in {agent-folder}/journal-keeper-sidecar/breakthroughs.md with date and significance" + action: "Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md with date and significance" description: "Record a meaningful insight" - trigger: read-back - action: "Load and share entries from {agent-folder}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" + action: "Load and share entries from ./journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth" description: "Review past entries" - trigger: save - action: "Update {agent-folder}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers" + action: "Update ./journal-keeper-sidecar/memories.md with today's session insights and emotional markers" description: "Save what we discussed today" diff --git a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md b/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md index 4fc72b3a..95d33017 100644 --- a/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md +++ b/src/modules/bmb/workflows/create-agent/data/reference/workflows/meal-prep-nutrition/steps/step-05-shopping.md @@ -132,7 +132,7 @@ You are a **strategic shopping partner** who: - Plans for real-life shopping scenarios - Minimizes food waste thoughtfully -## ๐Ÿ“ OUTPUT REQUIREMENTS: +## ๐Ÿ“Š STATUS UPDATE: Update workflow.md frontmatter: diff --git a/src/modules/bmb/workflows/create-module/steps/step-01-init.md b/src/modules/bmb/workflows/create-module/steps/step-01-init.md new file mode 100644 index 00000000..cef0968f --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-01-init.md @@ -0,0 +1,155 @@ +--- +nextStepFile: '{installed_path}/steps/step-02-concept.md' +continueFile: '{installed_path}/steps/step-01b-continue.md' +modulePlanTemplate: '{installed_path}/templates/module-plan.template.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +customModuleLocation: '{custom_module_location}' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +--- + +# Step 1: Workflow Initialization + +## STEP GOAL: + +To initialize the create-module workflow by getting the module name from the user, checking for existing work, handling continuation if needed, and creating the initial module plan document. + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and BMAD Systems Specialist +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD architecture and module creation, user brings their module requirements +- โœ… Maintain collaborative, guiding tone throughout + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on initialization, getting module name, and setting up tracking +- ๐Ÿšซ FORBIDDEN to look ahead to future steps +- ๐Ÿ’ฌ Handle initialization professionally +- ๐Ÿšช DETECT existing workflow state and handle continuation properly + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Show analysis before taking any action +- ๐Ÿ’พ Initialize document and update frontmatter +- ๐Ÿ“– Set up frontmatter `stepsCompleted: [1]` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until setup is complete + +## CONTEXT BOUNDARIES: + +- Variables from workflow.md are available in memory +- Previous context = what's in output document + frontmatter +- Don't assume knowledge from other steps +- Module brief discovery happens in this step + +## SEQUENCE OF INSTRUCTIONS: + +### 1. Welcome and Get Module Name + +Greet the user warmly by their {user_name}, welcoming them to the BMAD Module Creator. Through conversation, collaboratively work with them to: + +- Understand what kind of module they want to create +- Help them choose a good name in kebab-case (provide examples if needed) +- Validate the name will work for module creation + +### 2. Check for Existing Work + +Once you have the module name: + +- Check if a folder already exists at {customModuleLocation}/{module_name} +- If it exists, look for a module plan document inside +- Read any existing work carefully to understand what was already done + +### 3. Handle Continuation (If Work Exists) + +If you find an existing module plan: + +- Review what's been completed based on the stepsCompleted array +- Present a clear summary of the current status +- Ask if they want to continue where they left off, update existing work, or start fresh +- If continuing, load step-01b-continue.md + +### 4. Look for Supporting Documents + +Check for any existing documents that could help: + +- Module briefs in the module folder or output folder +- Brainstorming results in the output folder +- Any other relevant documentation + +### 5. Guide User's Next Decision + +If no supporting documents are found: + +- Explain their three options clearly and helpfully +- Option 1: Proceed with creating the module based on their ideas +- Option 2: Exit and create a module brief first (explain the module-brief workflow) +- Option 3: Exit and do brainstorming first (explain the brainstorming workflow) +- Support whatever choice they make + +### 6. Create Module Foundation + +If proceeding: + +- Create the module folder if needed +- Create the initial module-plan-{module_name}.md document using the module plan template from {modulePlanTemplate} +- Initialize proper frontmatter with current date, user name, and add "step-01-init" to stepsCompleted array +- Add any discovered documents to inputDocuments field +- Include a brief section about the legacy reference + +### 7. Prepare for Next Step + +- Confirm everything is set up properly +- Let the user know what you've accomplished +- Transition smoothly to the next phase of defining the module concept + +### 8. Present MENU OPTIONS + +Display: **Proceeding to define your module concept...** + +#### EXECUTION RULES: + +- This is an initialization step with no user choices (after inputs handled) +- Proceed directly to next step after setup +- Use menu handling logic section below + +#### Menu Handling Logic: + +- After setup completion, add step-01-init to the end of the stepsCompleted array in module plan frontmatter, then load, read entire file, then execute `{nextStepFile}` to define the module concept + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Module name obtained and validated through collaborative dialogue +- Module plan document created from template with frontmatter initialized +- "step-01-init" added to stepsCompleted array +- Module plan document created at correct location +- User feels welcomed and informed +- Ready to proceed to step 2 +- OR existing workflow properly routed to step-01b-continue.md + +### โŒ SYSTEM FAILURE: + +- Proceeding with step 2 without module plan creation +- Not checking for existing documents properly +- Creating module without user input on name +- Skipping folder creation +- Not routing to step-01b-continue.md when appropriate + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN initialization setup is complete and module plan document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin defining the module concept. diff --git a/src/modules/bmb/workflows/create-module/steps/step-01b-continue.md b/src/modules/bmb/workflows/create-module/steps/step-01b-continue.md new file mode 100644 index 00000000..3ff7d8fa --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-01b-continue.md @@ -0,0 +1,169 @@ +--- +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +--- + +# Step 1b: Continue Module Creation + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and BMAD Systems Specialist +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD architecture and module creation, user brings their module requirements +- โœ… Maintain collaborative, guiding tone throughout + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on handling continuation and resuming workflow +- ๐Ÿšซ FORBIDDEN to modify existing work without user consent +- ๐Ÿ’ฌ Present status clearly and get user direction +- ๐Ÿ“‹ Track completion status accurately + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Load and analyze existing module plan +- ๐Ÿ’พ Update frontmatter with continuation status +- ๐Ÿ“– Route to appropriate next step based on progress +- ๐Ÿšซ FORBIDDEN to skip steps just because they exist + +## CONTEXT BOUNDARIES: + +- Module plan document exists with previous work +- Focus on understanding what's been done and what remains +- Don't assume completion without verification +- User direction guides next actions + +## STEP GOAL: + +To resume module creation by presenting current status, understanding what's been accomplished, and determining the next step in the process. + +## CONTINUATION HANDLING SEQUENCE: + +### 1. Load and Analyze Existing Module Plan + +Load module plan from: {modulePlanFile} +Read entire document including frontmatter +Extract current status from frontmatter fields: + +- stepsCompleted array +- lastStep (the final item in the stepsCompleted array) +- module_name +- module_code +- date +- inputDocuments + +### 2. Present Current Status + +"Welcome back! I found your in-progress module creation for **{module_name}**. + +**Current Status:** + +- **Module Code:** {module_code} +- **Started:** {date} +- **Last Step:** {lastStep} +- **Steps Completed:** {stepsCompleted count}/{total steps} +- **Location:** {custom_module_location}/{module_name} + +\*\*Progress Summary:" + +Based on stepsCompleted, show: + +- [โœ…] Step 1: Init - Complete +- [ ] Step 2: Concept - {status} +- [ ] Step 3: Components - {status} +- [ ] Step 4: Structure - {status} +- [ ] Step 5: Configuration - {status} +- [ ] Step 6: Agents - {status} +- [ ] Step 7: Workflows - {status} +- [ ] Step 8: Installer - {status} +- [ ] Step 9: Documentation - {status} +- [ ] Step 10: Roadmap - {status} +- [ ] Step 11: Validation - {status} + +### 3. Review What's Been Done + +Read content sections of module plan +Summarize what's been accomplished: + +"**Completed Work:** + +- Module identity defined +- Component planning complete +- [Other completed items based on content]" + +### 4. Determine Next Step + +Based on stepsCompleted array: +Find highest completed step number +Next step = highest completed + 1 + +"**Ready to Continue:** +Your next step would be: **Step {nextStep} - [step name]** + +What would you like to do? + +1. **Continue** from where you left off +2. **Review** what's been done so far +3. **Modify** previous work +4. **Start over** with a new plan" + +### 5. Handle User Choice + +User your best judgement in how to handle the users choice + +### 6. Update Continuation Status + +Update modulePlanFile frontmatter: + +- Set lastStep: 'continued' +- Add note about continuation date +- Keep stepsCompleted unchanged + +## โœ… SUCCESS METRICS: + +- User understands current progress +- Next step identified correctly +- User choice handled appropriately +- Module plan updated with continuation status +- Workflow resumed at correct location + +## โŒ FAILURE MODES TO AVOID: + +- Not accurately reading previous status +- Skipping steps just because they exist +- Not offering review option +- Losing previous work +- Not updating continuation tracking + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Existing work properly loaded and analyzed +- User clearly understands current status +- Continuation options presented clearly +- Next step determined correctly +- Module plan updated with continuation information + +### โŒ SYSTEM FAILURE: + +- Not reading existing plan completely +- Misrepresenting progress status +- Losing track of what's been done +- Not offering appropriate continuation options + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN user selects 'C' (Continue) and appropriate updates are saved to modulePlanFile, will you then load, read entire file, then execute the determined next step file to resume the module creation workflow. diff --git a/src/modules/bmb/workflows/create-module/steps/step-02-concept.md b/src/modules/bmb/workflows/create-module/steps/step-02-concept.md new file mode 100644 index 00000000..b77613c6 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-02-concept.md @@ -0,0 +1,217 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-03-components.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +moduleStructureGuide: '{project-root}/src/modules/bmb/workflows-legacy/create-module/module-structure.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 2: Define Module Concept and Scope + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Business Analyst +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in module design and BMAD patterns, user brings their domain knowledge +- โœ… Maintain collaborative, educational tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on defining the module concept and scope +- ๐Ÿšซ FORBIDDEN to start designing components in this step +- ๐Ÿ’ฌ Ask questions conversationally to understand vision +- ๐Ÿšซ FORBIDDEN to proceed without clear module identity + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Load and study module structure guide for context +- ๐Ÿ’พ Document all module identity details in plan +- ๐Ÿ“– Add "step-02-concept" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Module name and location from step 1 +- Input documents (brief/brainstorming) if any +- Focus ONLY on concept and scope definition +- Don't assume module details beyond what user provides + +## STEP GOAL: + +To articulate the module's vision, define its identity, and establish clear boundaries for what it will and won't do. + +## MODULE CONCEPT DEFINITION PROCESS: + +### 1. Load Context and Briefs + +"Let's define your module's concept and identity. This will guide all the decisions we make about agents, workflows, and features." + +Load module-plan.md and check inputDocuments field + +Read the module brief completely +"I see you have a module brief. Let me review that to understand your vision..." +Use brief content to inform concept development questions + +Load and study the module structure guide for context + +### 2. Guide Concept Development + +Ask conversationally: + +"**Understanding Your Vision:** + +1. **What problem will this module solve?** - What pain point or need are you addressing? + +2. **Who is the primary user?** - Who will benefit most from this module? + +3. **What's the main outcome?** - What will users be able to do after using your module? + +4. **Why is this important?** - What makes this module valuable or unique?" + +### 3. Module Identity Development + +Based on their responses, collaboratively develop: + +**Module Name:** + +- Start with their module code: {module_name} +- Suggest a display name in Title Case +- Get user confirmation or refinement + +**Module Purpose:** + +- Distill their problem statement into 1-2 clear sentences +- Focus on value and outcomes +- Get user validation + +**Target Audience:** + +- Identify primary user persona +- Consider skill level (beginner/intermediate/advanced) +- Note any secondary audiences + +**Module Scope:** + +- What's IN scope (core features) +- What's OUT of scope (explicitly state what it won't do) +- Success criteria (how will we know it works?) + +### 4. Module Theme and Category + +"**Module Classification:** + +Based on your description, this seems to fit in the [Domain-Specific/Creative/Technical/Business/Personal] category. + +Does this sound right? Or would you categorize it differently? + +**Example Categories:** + +- **Domain-Specific**: Legal, Medical, Finance, Education +- **Creative**: RPG/Gaming, Story Writing, Music Production +- **Technical**: DevOps, Testing, Architecture, Security +- **Business**: Project Management, Marketing, Sales +- **Personal**: Journaling, Learning, Productivity" + +### 5. Module Type Estimation + +"Based on what you've described, I'm thinking this might be a: + +- **Simple Module** (1-2 agents, 2-3 workflows) - Focused, single-purpose +- **Standard Module** (3-5 agents, 5-10 workflows) - Comprehensive solution +- **Complex Module** (5+ agents, 10+ workflows) - Full platform/framework + +Which feels right for your vision? We'll confirm this after planning components." + +### 6. Document Module Concept + +Update module-plan.md with concept section: + +```markdown +## Module Concept + +**Module Name:** {module_display_name} +**Module Code:** {module_name} +**Category:** [category] +**Type:** [estimated type] + +**Purpose Statement:** +[1-2 sentence clear purpose] + +**Target Audience:** + +- Primary: [description] +- Secondary: [if any] + +**Scope Definition:** + +**In Scope:** + +- [core feature 1] +- [core feature 2] +- [core feature 3] + +**Out of Scope:** + +- [explicitly excluded item 1] +- [explicitly excluded item 2] + +**Success Criteria:** + +- [measurable outcome 1] +- [measurable outcome 2] +- [user satisfaction indicator] +``` + +### 7. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to explore alternative concept approaches +- IF P: Execute {partyModeWorkflow} to get creative input on module identity +- IF C: Save concept to module-plan.md, add step-02-concept to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Module purpose clearly articulated +- Module identity established (name, audience, scope) +- Category and type determined +- Concept documented in module plan +- User feels the concept matches their vision + +### โŒ SYSTEM FAILURE: + +- Proceeding without clear module purpose +- Not defining scope boundaries +- Skipping user validation of concept +- Not documenting concept details + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and module concept is saved to module-plan.md with stepsCompleted updated to [1, 2], will you then load, read entire file, then execute `{nextStepFile}` to begin component planning. diff --git a/src/modules/bmb/workflows/create-module/steps/step-03-components.md b/src/modules/bmb/workflows/create-module/steps/step-03-components.md new file mode 100644 index 00000000..265203ab --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-03-components.md @@ -0,0 +1,267 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-04-structure.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +agent_examples_path: '{project-root}/src/modules/bmb/reference/agents/module-examples' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 3: Plan Module Components + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Systems Designer +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD component design patterns, user brings their domain requirements +- โœ… Maintain collaborative, design-focused tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on planning component architecture +- ๐Ÿšซ FORBIDDEN to create actual components in this step +- ๐Ÿ’ฌ Present component options with reasoning +- ๐Ÿšซ FORBIDDEN to finalize component list without user agreement + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Reference agent examples for patterns +- ๐Ÿ’พ Document component plan in detail +- ๐Ÿ“– Add "step-03-components" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Module concept from step 2 is available +- Focus on planning, not implementation +- Consider BMAD patterns and best practices +- Reference examples but don't copy exactly + +## STEP GOAL: + +To design the component architecture for the module, determining what agents, workflows, and tasks are needed to fulfill the module's purpose. + +## COMPONENT PLANNING PROCESS: + +### 1. Initialize Component Planning + +"Now that we have a clear module concept, let's plan the components that will bring it to life. + +Based on your module's purpose and scope, we'll design: + +- **Agents** - The AI personas that will help users +- **Workflows** - The step-by-step processes for accomplishing tasks +- **Tasks** - Quick utilities and supporting functions" + +### 2. Agent Planning + +"**Agent Architecture:** + +Think about the different roles or perspectives needed to accomplish your module's goals. Each agent should have a clear, distinct purpose." + +Reference agent examples for patterns +Load and browse agent examples: {agent_examples_path} + +"**Common Agent Patterns:** + +- **Primary Agent** - The main interface/orchestrator +- **Specialist Agents** - Domain-specific experts +- **Utility Agents** - Helper/support functions + +**Example by Module Type:** + +**Technical Modules (e.g., DevOps, Testing):** + +- Implementation Specialist +- Reviewer/Auditor +- Documentation Expert + +**Creative Modules (e.g., Story Writing, Game Design):** + +- Creative Director +- World Builder +- Content Generator + +**Business Modules (e.g., Project Management):** + +- Project Coordinator +- Facilitator +- Analyst" + +"**For your {module_category} module, I suggest considering:** + +[Suggest 2-4 specific agent types based on module concept] + +**What resonates with your vision?** Which of these agents would be most valuable, and are there any others you'd like to add?" + +### 3. Workflow Planning + +"**Workflow Design:** + +Workflows are the step-by-step processes that users will follow to accomplish specific tasks. Each workflow should solve a specific problem or achieve a particular outcome." + +**Types of Workflows:** + +- **Document Workflows** - Generate reports, plans, specifications +- **Action Workflows** - Perform operations, create structures +- **Interactive Workflows** - Guided sessions, coaching, training + +**Example Workflow Patterns:** + +"For your module's purpose, consider these potential workflows: + +1. **[Primary Workflow Name]** - Main workflow for core functionality +2. **[Supporting Workflow 1]** - For specific use case +3. **[Supporting Workflow 2]** - For another use case + +Remember: We'll create workflow PLANS first, not full implementations. These plans can be used later with the create-workflow workflow." + +### 4. Task Planning (Optional) + +"**Task Planning (if needed):** + +Tasks are single-operation utilities that don't need full workflows. They're good for: + +- Quick actions +- Shared subroutines +- Helper functions + +Does your module need any tasks? For example: + +- Status checking +- Quick formatting +- Validation utilities" + +### 5. Component Integration Planning + +"**How Components Work Together:** + +Let's think about how your components will interact: + +- **Agent Collaboration**: Will agents work together or independently? +- **Workflow Dependencies**: Do workflows need to call each other? +- **Task Usage**: Which workflows will use which tasks?" + +### 6. Component Priority and MVP + +"**Starting Point (MVP):** + +To ensure success, let's identify the minimum viable set: + +**Must Have (Phase 1):** + +- [List essential agents] +- [List essential workflows] + +**Nice to Have (Phase 2):** + +- [Additional agents] +- [Additional workflows] +- [Tasks if any] + +This approach lets you launch with core functionality and expand later." + +### 7. Document Component Plan + +Update module-plan.md with component section: + +```markdown +## Component Architecture + +### Agents (N planned) + +1. **[Agent Name]** - [Brief purpose] + - Type: [Primary/Specialist/Utility] + - Role: [Specific role description] + +2. **[Agent Name]** - [Brief purpose] + - Type: [Primary/Specialist/Utility] + - Role: [Specific role description] + +### Workflows (N planned) + +1. **[Workflow Name]** - [Purpose] + - Type: [Document/Action/Interactive] + - Primary user: [Who uses this] + - Key output: [What it produces] + +2. **[Workflow Name]** - [Purpose] + - Type: [Document/Action/Interactive] + - Primary user: [Who uses this] + - Key output: [What it produces] + +### Tasks (N planned) + +1. **[Task Name]** - [Single-purpose function] + - Used by: [Which workflows/agents] + +### Component Integration + +- Agents collaborate via: [description] +- Workflow dependencies: [description] +- Task usage patterns: [description] + +### Development Priority + +**Phase 1 (MVP):** + +- [List of components to create first] + +**Phase 2 (Enhancement):** + +- [List of components for later] +``` + +### 8. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to explore alternative component architectures +- IF P: Execute {partyModeWorkflow} to get creative input on component design +- IF C: Save component plan to module-plan.md, add step-03-components to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Component architecture planned and documented +- Agent types and purposes clearly defined +- Workflow requirements identified +- Integration patterns established +- Development priority set (MVP vs enhancements) + +### โŒ SYSTEM FAILURE: + +- Planning components without module purpose context +- Not considering BMAD patterns and examples +- Over-engineering (too many components) +- Under-planning (missing essential components) +- Not establishing development priorities + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and component plan is saved to module-plan.md with stepsCompleted updated to [1, 2, 3], will you then load, read entire file, then execute `{nextStepFile}` to begin creating the module structure. diff --git a/src/modules/bmb/workflows/create-module/steps/step-04-structure.md b/src/modules/bmb/workflows/create-module/steps/step-04-structure.md new file mode 100644 index 00000000..ed12122d --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-04-structure.md @@ -0,0 +1,228 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-05-config.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 4: Create Module Structure + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Systems Organizer +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD structure patterns, user brings their component requirements +- โœ… Maintain collaborative, organized tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on creating directory structure and determining complexity +- ๐Ÿšซ FORBIDDEN to create actual component files in this step +- ๐Ÿ’ฌ Explain structure decisions clearly +- ๐Ÿšซ FORBIDDEN to proceed without confirming structure + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Use component count to determine module type +- ๐Ÿ’พ Create all required directories +- ๐Ÿ“– Add "step-04-structure" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Component plan from step 3 is available +- Standard BMAD module structure to follow +- Focus on structure creation, not content +- Module folder already exists from step 1 + +## STEP GOAL: + +To determine the module's complexity type and create the complete directory structure for the module. + +## MODULE STRUCTURE CREATION PROCESS: + +### 1. Determine Module Complexity + +"Based on your component plan, let's determine your module's complexity level:" + +**Count Components:** + +- Agents: [count from plan] +- Workflows: [count from plan] +- Tasks: [count from plan] + +**Complexity Assessment:** + +"**Simple Module Criteria:** + +- 1-2 agents, all Simple type +- 1-3 workflows +- No complex integrations + +**Standard Module Criteria:** + +- 2-4 agents with mixed types +- 3-8 workflows +- Some shared resources + +**Complex Module Criteria:** + +- 4+ agents or multiple Module-type agents +- 8+ workflows +- Complex interdependencies +- External integrations" + +"**Your module has:** + +- [agent_count] agents +- [workflow_count] workflows +- [task_count] tasks + +**This makes it a: [Simple/Standard/Complex] Module**" + +### 2. Present Module Structure + +"**Standard BMAD Module Structure:** + +For a [module type] module, we'll create this structure:" + +``` +{module_code}/ +โ”œโ”€โ”€ agents/ # Agent definitions (.md) +โ”‚ โ”œโ”€โ”€ [agent-name].md +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ workflows/ # Workflow folders +โ”‚ โ”œโ”€โ”€ [workflow-name]/ +โ”‚ โ”‚ โ”œโ”€โ”€ workflow-plan.md # Descriptive plan +โ”‚ โ”‚ โ””โ”€โ”€ README.md # Workflow documentation +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ tasks/ # Task files (if any) +โ”‚ โ””โ”€โ”€ [task-name].md +โ”œโ”€โ”€ templates/ # Shared templates +โ”‚ โ””โ”€โ”€ [template-files] +โ”œโ”€โ”€ data/ # Module data files +โ”‚ โ””โ”€โ”€ [data-files] +โ”œโ”€โ”€ module.yaml # Required +โ”œโ”€โ”€ _module-installer/ # Installation configuration +โ”‚ โ”œโ”€โ”€ installer.js # Optional +โ”‚ โ””โ”€โ”€ assets/ # Optional install assets +โ””โ”€โ”€ README.md # Module documentation +``` + +### 3. Create Directory Structure + +Create all directories in {custom_module_location}/{module_name}/: + +1. **agents/** - For agent definition files +2. **workflows/** - For workflow folders +3. **tasks/** - For task files (if tasks planned) +4. **templates/** - For shared templates +5. **data/** - For module data +6. **\_module-installer/** - For installation configuration + +### 4. Create Placeholder README + +Create initial README.md with basic structure: + +````markdown +# {module_display_name} + +{module_purpose} + +## Installation + +```bash +bmad install {module_code} +``` +```` + +## Components + +_Module documentation will be completed in Step 9_ + +## Quick Start + +_Getting started guide will be added in Step 9_ + +--- + +_This module is currently under construction_ + +```` + +### 5. Document Structure Creation + +Update module-plan.md with structure section: + +```markdown +## Module Structure + +**Module Type:** [Simple/Standard/Complex] +**Location:** {custom_module_location}/{module_name} + +**Directory Structure Created:** +- โœ… agents/ +- โœ… workflows/ +- โœ… tasks/ +- โœ… templates/ +- โœ… data/ +- โœ… _module-installer/ +- โœ… README.md (placeholder) + +**Rationale for Type:** +[Explain why it's Simple/Standard/Complex based on component counts] +```` + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to explore alternative structure approaches +- IF P: Execute {partyModeWorkflow} to get creative input on organization +- IF C: Save structure info to module-plan.md, add step-04-structure to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Module complexity correctly determined +- All required directories created +- Structure follows BMAD standards +- Placeholder README created +- Structure documented in plan + +### โŒ SYSTEM FAILURE: + +- Not creating all required directories +- Incorrectly categorizing module complexity +- Not following BMAD structure patterns +- Creating component files prematurely + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and structure is saved to module-plan.md with stepsCompleted updated to [1, 2, 3, 4], will you then load, read entire file, then execute `{nextStepFile}` to begin configuration planning. diff --git a/src/modules/bmb/workflows/create-module/steps/step-05-config.md b/src/modules/bmb/workflows/create-module/steps/step-05-config.md new file mode 100644 index 00000000..55da3c50 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-05-config.md @@ -0,0 +1,233 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-06-agents.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 5: Plan Module Configuration + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Configuration Specialist +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD installation patterns, user brings their module requirements +- โœ… Maintain collaborative, planning-focused tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus ONLY on planning configuration fields +- ๐Ÿšซ FORBIDDEN to create installer files in this step +- ๐Ÿ’ฌ Present configuration options clearly +- ๐Ÿšซ FORBIDDEN to finalize without user input + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Consider what users might want to configure +- ๐Ÿ’พ Document all configuration field plans +- ๐Ÿ“– Add "step-05-config" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Module concept and components from previous steps +- Standard BMAD installer configuration patterns +- Focus on planning, not implementation +- Consider user customization needs + +## STEP GOAL: + +To determine what configuration settings the module needs and plan how they'll be implemented in the installer. + +## CONFIGURATION PLANNING PROCESS: + +### 1. Initialize Configuration Planning + +"Now let's plan the configuration for your module's installer. This determines what users can customize when they install your module." + +**Configuration allows users to:** + +- Set up file locations +- Choose features or behavior +- Provide API keys or credentials +- Adjust output formats +- Configure integrations + +### 2. Assess Configuration Needs + +"**Configuration Assessment:** + +Does your {module_display_name} module need any user-configurable settings during installation?" + +**Common Configuration Categories:** + +**1. Output/Data Paths** + +- Where should outputs be saved? +- What's the default data directory? +- Any special folder structures needed? + +**2. Feature Toggles** + +- Enable/disable specific features +- Choose between behavior modes +- Set verbosity levels + +**3. Integration Settings** + +- API keys (for external services) +- Service endpoints +- Authentication credentials + +**4. User Preferences** + +- Default language +- Time zone +- Skill level (beginner/advanced) +- Detail level (minimal/standard/verbose)" + +### 3. Plan Configuration Fields + +"**For each configuration need, let's define:** + +1. **Field Name** (snake_case, e.g., 'output_path') +2. **Type** - INTERACTIVE (asks user) or STATIC (hardcoded) +3. **Prompt** (what to ask user, if interactive) +4. **Default Value** (sensible default) +5. **Input Type** - text, single-select, multi-select +6. **Result Template** - how to store the value" + +**Examples:** + +"**INTERACTIVE Text Input:** + +```yaml +output_path: + prompt: 'Where should {module_name} save outputs?' + default: 'output/{module_name}' + result: '{project-root}/{value}' +``` + +**INTERACTIVE Single-Select:** + +```yaml +detail_level: + prompt: 'How detailed should outputs be?' + default: 'standard' + result: '{value}' + single-select: + - value: 'minimal' + label: 'Minimal - Brief summaries only' + - value: 'standard' + label: 'Standard - Balanced detail' + - value: 'detailed' + label: 'Detailed - Comprehensive information' +``` + +**STATIC Value:** + +````yaml +module_version: + result: "1.0.0" +```" + +### 4. Design Configuration for Your Module + +"**Based on your module's purpose, consider these potential configurations:" + +[Suggest relevant configurations based on module type and purpose] + +"**Which of these apply to your module?** +- [Present options relevant to the specific module] + +**Any additional configurations needed?**" + +### 5. Document Configuration Plan + +Update module-plan.md with configuration section: + +```markdown +## Configuration Planning + +### Required Configuration Fields + +1. **[field_name]** + - Type: [INTERACTIVE/STATIC] + - Purpose: [what it controls] + - Default: [default value] + - Input Type: [text/single-select/multi-select] + - Prompt: [user prompt if interactive] + +2. **[field_name]** + - Type: [INTERACTIVE/STATIC] + - Purpose: [what it controls] + - Default: [default value] + - Input Type: [text/single-select/multi-select] + - Prompt: [user prompt if interactive] + +### Installation Questions Flow + +1. [First question] +2. [Second question] +3. [Additional questions...] + +### Result Configuration Structure + +The module.yaml will generate: +- Module configuration at: {bmad_folder}/{module_code}/config.yaml +- User settings stored as: [describe structure] +```` + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to explore additional configuration options +- IF P: Execute {partyModeWorkflow} to get input on user experience +- IF C: Save configuration plan to module-plan.md, add step-05-config to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- All necessary configuration fields identified +- Field types and prompts clearly defined +- User interaction flow planned +- Configuration structure documented +- Ready for installer implementation + +### โŒ SYSTEM FAILURE: + +- Skipping configuration planning for modules that need it +- Over-configuring (too many options) +- Not considering user experience +- Not documenting configuration plans + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and configuration plan is saved to module-plan.md with stepsCompleted updated to [1, 2, 3, 4, 5], will you then load, read entire file, then execute `{nextStepFile}` to begin agent creation. diff --git a/src/modules/bmb/workflows/create-module/steps/step-06-agents.md b/src/modules/bmb/workflows/create-module/steps/step-06-agents.md new file mode 100644 index 00000000..1108f96a --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-06-agents.md @@ -0,0 +1,296 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-07-workflows.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +agentTemplate: '{installed_path}/templates/agent.template.md' +agent_examples_path: '{project-root}/src/modules/bmb/reference/agents/module-examples' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 6: Create Module Agents + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Agent Designer +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD agent patterns, user brings their domain requirements +- โœ… Maintain collaborative, creative tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on creating proper YAML agent files following the template +- ๐Ÿšซ FORBIDDEN to use create-agent workflow (it's problematic) +- ๐Ÿ’ฌ Create placeholder workflow folders with README.md for each agent +- ๐Ÿšซ FORBIDDEN to create full workflows in this step + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Follow agent.template.md exactly for structure +- ๐Ÿ’พ Save agents as .yaml files to module's agents folder +- ๐Ÿ“– Create workflow folders with README.md plans +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Component plan from step 3 defines which agents to create +- Agent template provides the required YAML structure +- Module structure already created +- Focus on agent creation and workflow placeholders + +## STEP GOAL: + +To create the primary agent(s) for the module using the proper agent template and create placeholder workflow folders for each agent. + +## AGENT CREATION PROCESS: + +### 1. Review Agent Plan + +"Let's create the agents for your {module_display_name} module. + +From your component plan, you have: + +- [agent_count] agents planned +- [list of agent types from plan] + +I'll create each agent following the proper BMAD template and set up placeholder workflow folders for them." + +### 2. Load Agent Template + +Load and study the agent template from {agentTemplate} +Reference agent examples from {agent_examples_path} for patterns + +### 3. Create Each Agent + +For each agent in the component plan: + +#### 3.1 Determine Agent Characteristics + +"**Agent: [Agent Name]** + +Let's design this agent by understanding what it needs: + +**Memory & Learning:** + +1. Does this agent need to remember things across sessions? (conversations, preferences, patterns) + - If yes: We'll add sidecar folder structure for memory + - If no: No persistent memory needed + +**Interaction Types:** 2. What does this agent DO? + +- Conversational interactions? โ†’ Use embedded prompts +- Quick single actions? โ†’ Use inline actions +- Complex multi-step processes? โ†’ Consider workflows +- Document generation? โ†’ Likely need workflows + +**Multiple Agent Usage:** 3. Will other agents in this module need the same workflows? + +- If yes: Definitely create separate workflow files +- If no: Could embed in agent file + +**Based on this, what combination does [Agent Name] need?** + +- Memory/Persistence: [Yes/No] +- Embedded prompts: [List main interactions] +- Workflows needed: [Which processes need separate files?]" + +#### 3.2 Present Agent Design + +"**Agent Design: [Agent Name]** + +**Core Identity:** + +- Name: [Suggested name] +- Title: [Brief description] +- Icon: [Appropriate emoji] + +**Persona:** + +- Role: [What the agent does] +- Identity: [Personality/background] +- Communication Style: [How they communicate] +- Principles: [3-5 core principles] + +**Structure:** + +- Memory needed: [Yes/No - sidecar folder] +- Embedded prompts: [List main interaction prompts] +- Workflow processes: [Which need separate files] + +**Menu Items Planned:** + +- [List with trigger codes and types] + +**Quick actions vs Workflows:** + +- Quick prompts: [single-step interactions] +- Workflows: [multi-step, shared processes] + +Does this design match what you envisioned? What should we adjust?" + +#### 3.3 Create Agent File and Structure + +After user confirmation: + +Create hybrid agent file with only needed sections: + +```yaml +agent: + metadata: + name: '[Agent Name]' + title: '[Agent Title]' + icon: '[Icon]' + module: '{module_code}' + persona: + role: '[Agent Role]' + identity: | + [Multi-line identity description] + communication_style: | + [Multi-line communication style] + principles: + - '[Principle 1]' + - '[Principle 2]' + - '[Principle 3]' + + # Only include if agent needs memory/persistence + critical_actions: + - 'Load COMPLETE file ./[agent-name]-sidecar/memories.md and integrate all past interactions' + - 'ONLY read/write files in ./[agent-name]-sidecar/ - this is our private workspace' + + # Only include if agent has embedded prompts + prompts: + - id: '[prompt-name]' + content: | + + [How to use this prompt] + + + [Detailed prompt content] + + menu: + # Always include + - multi: '[CH] Chat with agent or [SPM] Start Party Mode' + triggers: + - party-mode: + input: SPM + route: '{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md' + type: exec + - expert-chat: + input: CH + action: agent responds as expert + type: action + + # Group related functions + - multi: '[PF] Primary Function [QF] Quick Task' + triggers: + - primary-function: + input: PF + action: '#[prompt-id]' + type: action + - quick-task: + input: QF + route: '#[prompt-id]' + type: exec + + # Workflow only for complex processes + - trigger: 'complex-process' + route: '{project-root}/{bmad_folder}/{custom_module}/workflows/[workflow]/workflow.md' + description: 'Complex process [icon]' + + # Quick inline actions + - trigger: 'save-item' + action: 'Save to ./[agent-name]-sidecar/file.md' + description: 'Save item ๐Ÿ’พ' +``` + +#### 3.4 Create Supporting Structure + +**If agent needs memory:** + +1. Create folder: {custom_module_location}/{module_name}/agents/[agent-name]-sidecar/ +2. Create files: + - memories.md (empty, for persistent memory) + - instructions.md (empty, for agent protocols) + - insights.md (empty, for breakthrough moments) + - sessions/ (subfolder for session records) + - patterns.md (empty, for tracking patterns) + +**If agent has workflows:** +For each workflow that needs separate file: + +1. Create folder: {custom_module_location}/{module_name}/workflows/[workflow-name]/ +2. Create README.md with workflow plan + +### 4. Repeat for All Agents + +Go through each agent from the component plan, presenting drafts and creating files with user confirmation. + +### 5. Document Agent Creation + +Update module-plan.md with agents section: + +```markdown +## Agents Created + +1. **[Agent Name]** - [Agent Title] + - File: [agent-filename].yaml + - Features: [Memory/Sidecar, Embedded prompts, Workflows] + - Structure: + - Sidecar: [Yes/No] + - Prompts: [number embedded] + - Workflows: [list of workflow folders] + - Status: Created with [combination of features] +``` + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to refine agent designs +- IF P: Execute {partyModeWorkflow} to get creative input on agent personas +- IF C: Save agent creation status to module-plan.md, add step-06-agents to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- All planned agents created with proper YAML structure +- Each agent follows agent.template.md format exactly +- Workflow placeholder folders created with README.md plans +- Agent menu items properly reference workflow paths +- Users confirmed each agent draft before creation + +### โŒ SYSTEM FAILURE: + +- Using create-agent workflow instead of template +- Creating XML agents instead of YAML +- Not creating workflow placeholder folders +- Skipping user confirmation on agent drafts + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and all agents are created with placeholder workflows and stepsCompleted updated, will you then load, read entire file, then execute `{nextStepFile}` to begin workflow plan review. diff --git a/src/modules/bmb/workflows/create-module/steps/step-07-workflows.md b/src/modules/bmb/workflows/create-module/steps/step-07-workflows.md new file mode 100644 index 00000000..f884c2cf --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-07-workflows.md @@ -0,0 +1,228 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-08-installer.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +workflowPlanTemplate: '{installed_path}/templates/workflow-plan-template.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 7: Review Workflow Plans + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Workflow Designer +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD workflow patterns, user brings their workflow requirements +- โœ… Maintain collaborative, review-focused tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on reviewing existing workflow README files from Step 6 +- ๐Ÿšซ FORBIDDEN to use create-workflow workflow in this step +- ๐Ÿ’ฌ Review and refine workflow plans, not create new ones +- ๐Ÿšซ FORBIDDEN to create actual workflow steps + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Review workflow README files created in Step 6 +- ๐Ÿ’พ Update README files based on user feedback +- ๐Ÿ“– Add "step-07-workflows" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Workflow README files were created in Step 6 for each agent +- These README files contain workflow plans for later implementation +- Module structure already created with workflow folders +- Focus on reviewing and refining, not creating from scratch + +## STEP GOAL: + +To review and refine the workflow README files created in Step 6, ensuring they have clear plans for later implementation with the create-workflow workflow. + +## WORKFLOW REVIEW PROCESS: + +### 1. List Workflow Folders Created + +"Let's review the workflow plans created in Step 6 for your {module_display_name} module. + +I've already created workflow folders and README.md files for each agent's workflows: + +**Workflow folders found:** + +- [List all workflow folders in {custom_module_location}/{module_name}/workflows/] + +**Each workflow folder contains a README.md with:** + +- Purpose and description +- Trigger code from agent menu +- Key steps outline +- Expected outputs +- Notes for implementation" + +### 2. Review Each Workflow Plan + +For each workflow README file: + +#### 2.1 Load and Present + +"**Reviewing Workflow: [Workflow Name]** + +Reading the README.md from: [workflow-folder]/README.md + +**Current Plan:** +[Purpose] +[Trigger] +[Key Steps] +[Expected Output] +[Notes] + +How does this plan look? Should we: + +- Keep it as is +- Modify the purpose +- Adjust the steps +- Change the expected output" + +#### 2.2 Update Based on Feedback + +If user wants changes: + +- Update the README.md file +- Keep the same basic structure +- Ensure clarity for future implementation + +#### 2.3 Check for Missing Information + +Ensure each README has: + +```markdown +# [Workflow Name] + +## Purpose + +[Clear, concise description of what this workflow accomplishes] + +## Trigger + +[Trigger code from agent menu, e.g., "WF" or specific code] + +## Key Steps + +1. [Step 1 - What happens first] +2. [Step 2 - What happens next] +3. [Step 3 - Continue as needed] + +## Expected Output + +[What the workflow produces - document, action, result] + +## Notes + +This workflow will be implemented using the create-workflow workflow. +(Optional: Any special considerations or requirements) +``` + +### 3. Link Workflows to Agents + +"**Workflow-Agent Mapping:** + +Let's verify each workflow is properly linked to its agent: + +[For each workflow]: + +- **Workflow:** [Workflow Name] +- **Agent:** [Agent Name] +- **Trigger Code:** [WF code] +- **Menu Item:** [Menu description in agent] + +Are all these mappings correct in the agent files?" + +### 4. Document Implementation Plan + +Update module-plan.md with workflow section: + +```markdown +## Workflow Plans Reviewed + +### For Agent [Agent Name]: + +1. **[Workflow Name]** + - Location: workflows/[workflow-name]/ + - Status: Plan reviewed and ready for implementation + - Trigger: [WF code] + - Implementation: Use create-workflow workflow + +2. **[Workflow Name]** + - Location: workflows/[workflow-name]/ + - Status: Plan reviewed and ready for implementation + - Trigger: [WF code] + - Implementation: Use create-workflow workflow +``` + +### 5. Next Steps Guidance + +"**Ready for Implementation:** + +All workflow plans are now reviewed and ready. To implement these workflows later: + +1. Use the `/bmad:bmb:workflows:create-workflow` command +2. Select each workflow folder +3. Follow the create-workflow workflow +4. It will create the full workflow.md and step files + +The README.md in each folder serves as your blueprint for implementation." + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to refine workflow designs +- IF P: Execute {partyModeWorkflow} to get creative input on workflow processes +- IF C: Save workflow plan status to module-plan.md, add step-07-workflows to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- All workflow README files reviewed with user +- Each workflow plan has clear purpose and steps +- Workflow-agent mappings verified +- README files updated based on feedback +- Clear implementation guidance provided + +### โŒ SYSTEM FAILURE: + +- Skipping review of workflow README files +- Not updating plans based on user feedback +- Missing critical information in README files +- Not verifying workflow-agent mappings + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and all workflow plans are reviewed and documented and stepsCompleted updated, will you then load, read entire file, then execute `{nextStepFile}` to begin installer setup. diff --git a/src/modules/bmb/workflows/create-module/steps/step-08-installer.md b/src/modules/bmb/workflows/create-module/steps/step-08-installer.md new file mode 100644 index 00000000..4332ab68 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-08-installer.md @@ -0,0 +1,186 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-09-documentation.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +installerTemplate: '{installed_path}/templates/installer.template.js' +installConfigTemplate: '{installed_path}/templates/install-config.template.yaml' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 8: Setup Module Installer + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Installation Specialist +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD installation patterns, user brings their module requirements +- โœ… Maintain collaborative, technical tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on creating installer configuration files +- ๐Ÿšซ FORBIDDEN to run actual installation +- ๐Ÿ’ฌ Follow BMAD installer standards exactly +- ๐Ÿšซ FORBIDDEN to deviate from configuration template + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Use configuration plan from step 5 +- ๐Ÿ’พ Create module.yaml with all fields +- ๐Ÿ“– Add "step-08-installer" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- Configuration plan from step 5 defines installer fields +- Standard BMAD installer template to follow +- Module structure already created +- Focus on installer setup, not module content + +## STEP GOAL: + +To create the module installer configuration (module.yaml) that defines how users will install and configure the module. + +## INSTALLER SETUP PROCESS: + +### 1. Review Configuration Plan + +"Now let's set up the installer for your {module_display_name} module. + +The installer will: + +- Define how users install your module +- Collect configuration settings +- Set up the module structure in user projects +- Generate the module's config.yaml file + +From step 5, we planned these configuration fields: + +- [List planned configuration fields]" + +### 2. Create Installer Directory + +Ensure \_module-installer directory exists +Directory: {custom_module_location}/{module_name}/\_module-installer/ + +### 3. Create module.yaml + +"I'll create the module.yaml file based on your configuration plan. This is the core installer configuration file." + +Create file: {custom_module_location}/{module_name}/module.yaml from template {installConfigTemplate} + +### 4. Handle Custom Installation Logic + +"**Custom Installation Logic:** + +Does your module need any special setup during installation? For example: + +- Creating database tables +- Setting up API connections +- Downloading external assets +- Running initialization scripts" + +Does your module need custom installation logic? [yes/no] + +"I'll create an installer.js file for custom logic." + +Create file: {custom_module_location}/{module_name}/\_module-installer/installer.js from {installerTemplate} + +Update installer.js with module-specific logic + +### 5. Create Assets Directory (if needed) + +"**Installer Assets:** + +If your module needs to copy files during installation (templates, examples, documentation), we can add them to the assets directory." + +Create directory: \_module-installer/assets/ +Add note about what assets to include + +### 6. Document Installer Setup + +Update module-plan.md with installer section: + +```markdown +## Installer Configuration + +### Install Configuration + +- File: module.yaml +- Module code: {module_name} +- Default selected: false +- Configuration fields: [count] + +### Custom Logic + +- installer.js: [Created/Not needed] +- Custom setup: [description if yes] + +### Installation Process + +1. User runs: `bmad install {module_name}` +2. Installer asks: [list of questions] +3. Creates: {bmad_folder}/{module_name}/ +4. Generates: config.yaml with user settings + +### Validation + +- โœ… YAML syntax valid +- โœ… All fields defined +- โœ… Paths use proper templates +- โœ… Custom logic ready (if needed) +``` + +### 7. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to review installer configuration +- IF P: Execute {partyModeWorkflow} to get input on user experience +- IF C: Save installer info to module-plan.md, add step-08-installer to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- module.yaml created with all planned fields +- YAML syntax valid +- Custom installation logic prepared (if needed) +- Installer follows BMAD standards +- Configuration properly templated + +### โŒ SYSTEM FAILURE: + +- Not creating module.yaml +- Invalid YAML syntax +- Missing required fields +- Not using proper path templates + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and installer info is saved to module-plan.md with stepsCompleted updated to [1, 2, 3, 4, 5, 6, 7, 8], will you then load, read entire file, then execute `{nextStepFile}` to begin documentation creation. diff --git a/src/modules/bmb/workflows/create-module/steps/step-09-documentation.md b/src/modules/bmb/workflows/create-module/steps/step-09-documentation.md new file mode 100644 index 00000000..8d98c239 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-09-documentation.md @@ -0,0 +1,309 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-10-roadmap.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +moduleReadmeFile: '{custom_module_location}/{module_name}/README.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 9: Create Module Documentation + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Technical Writer +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in documentation best practices, user brings their module knowledge +- โœ… Maintain collaborative, clear tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on creating comprehensive README documentation +- ๐Ÿšซ FORBIDDEN to create docs in other locations +- ๐Ÿ’ฌ Generate content based on module plan +- ๐Ÿšซ FORBIDDEN to skip standard sections + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Use all gathered module information +- ๐Ÿ’พ Update the placeholder README.md file +- ๐Ÿ“– Add "step-09-documentation" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- All module information from previous steps +- Module structure and components already created +- Focus on README.md, not other documentation +- Generate content dynamically from plan + +## STEP GOAL: + +To create comprehensive README.md documentation for the module that helps users understand, install, and use the module. + +## DOCUMENTATION CREATION PROCESS: + +### 1. Initialize Documentation + +"Let's create the README.md for your {module_display_name} module. + +Good documentation is crucial for module adoption. Your README will be the first thing users see when discovering your module." + +### 2. Generate README Content + +Load module-plan.md to gather all module information +Update {moduleReadmeFile} with comprehensive content: + +````markdown +# {module_display_name} + +{module_purpose} + +## Overview + +This module provides: +[Generate list based on module components and features] + +## Installation + +Install the module using BMAD: + +```bash +bmad install {module_name} +``` +```` + +## Components + +### Agents ({agent_count}) + +[List created agents with brief descriptions] + +### Workflows ({workflow_count}) + +[List planned workflows with purposes] + +### Tasks ({task_count}) + +[List tasks if any] + +## Quick Start + +1. **Load the primary agent:** + + ``` + agent {primary_agent_name} + ``` + +2. **View available commands:** + + ``` + *help + ``` + +3. **Run the main workflow:** + + ``` + workflow {primary_workflow_name} + ``` + +## Module Structure + +``` +{module_name}/ +โ”œโ”€โ”€ agents/ # Agent definitions +โ”‚ โ”œโ”€โ”€ [agent-1].md +โ”‚ โ””โ”€โ”€ [agent-2].md +โ”œโ”€โ”€ workflows/ # Workflow folders +โ”‚ โ”œโ”€โ”€ [workflow-1]/ +โ”‚ โ”‚ โ”œโ”€โ”€ workflow-plan.md +โ”‚ โ”‚ โ””โ”€โ”€ README.md +โ”‚ โ””โ”€โ”€ [workflow-2]/ +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ tasks/ # Task files +โ”œโ”€โ”€ templates/ # Shared templates +โ”œโ”€โ”€ data/ # Module data +โ”œโ”€โ”€ _module-installer/ # Installation optional js file with custom install routine +โ”œโ”€โ”€ module.yaml # yaml config and install questions +โ””โ”€โ”€ README.md # This file +``` + +## Configuration + +The module can be configured in `{bmad_folder}/{module_name}/config.yaml` + +**Key Settings:** + +[List configuration fields from installer] + +[Example:] + +- **output_path**: Where outputs are saved +- **detail_level**: Controls output verbosity +- **feature_x**: Enable/disable specific features + +## Examples + +### Example 1: [Primary Use Case] + +[Step-by-step example of using the module for its main purpose] + +1. Start the agent +2. Provide input +3. Review output + +### Example 2: [Secondary Use Case] + +[Additional example if applicable] + +## Development Status + +This module is currently: + +- [x] Structure created +- [x] Installer configured +- [ ] Agents implemented +- [ ] Workflows implemented +- [ ] Full testing complete + +**Note:** Some workflows are planned but not yet implemented. See individual workflow folders for status. + +## Contributing + +To extend this module: + +1. Add new agents using `create-agent` workflow +2. Add new workflows using `create-workflow` workflow +3. Update the installer configuration if needed +4. Test thoroughly + +## Requirements + +- BMAD Method version 6.0.0 or higher +- [Any specific dependencies] + +## Author + +Created by {user_name} on [creation date] + +## License + +[Add license information if applicable] + +--- + +## Module Details + +**Module Code:** {module_name} +**Category:** {module_category} +**Type:** {module_type} +**Version:** 1.0.0 + +**Last Updated:** [current date] + +```` + +### 3. Review Documentation + +"**Documentation Review:** + +I've generated a comprehensive README that includes: + +โœ… **Overview** - Clear purpose and value proposition +โœ… **Installation** - Simple install command +โœ… **Components** - List of agents and workflows +โœ… **Quick Start** - Getting started guide +โœ… **Structure** - Module layout +โœ… **Configuration** - Settings explanation +โœ… **Examples** - Usage examples +โœ… **Development Status** - Current implementation state + +Does this documentation clearly explain your module? Is there anything you'd like to add or modify?" + +### 4. Handle Documentation Updates + +Update based on user feedback +"Common additions: +- API documentation +- Troubleshooting section +- FAQ +- Screenshots or diagrams +- Video tutorials +- Changelog" + +### 5. Document Documentation Creation + +Update module-plan.md with documentation section: + +```markdown +## Documentation + +### README.md Created +- Location: {custom_module_location}/{module_name}/README.md +- Sections: [list of sections included] +- Status: Complete + +### Content Highlights +- Clear installation instructions +- Component overview +- Quick start guide +- Configuration details +- Usage examples +- Development status + +### Updates Made +- [List any customizations or additions] +```` + +### 6. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to improve documentation clarity +- IF P: Execute {partyModeWorkflow} to get input on user experience +- IF C: Save documentation info to module-plan.md, add step-09-documentation to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- README.md fully populated with all sections +- Content accurately reflects module structure +- Installation instructions clear and correct +- Examples provide helpful guidance +- Development status honestly represented + +### โŒ SYSTEM FAILURE: + +- Leaving placeholder content in README +- Not updating with actual module details +- Missing critical sections (installation, usage) +- Misrepresenting implementation status + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and documentation info is saved to module-plan.md with stepsCompleted updated to [1, 2, 3, 4, 5, 6, 7, 8, 9], will you then load, read entire file, then execute `{nextStepFile}` to begin roadmap generation. diff --git a/src/modules/bmb/workflows/create-module/steps/step-10-roadmap.md b/src/modules/bmb/workflows/create-module/steps/step-10-roadmap.md new file mode 100644 index 00000000..39807a7d --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-10-roadmap.md @@ -0,0 +1,337 @@ +--- +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +nextStepFile: '{installed_path}/steps/step-11-validate.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +moduleTodoFile: '{custom_module_location}/{module_name}/TODO.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 10: Generate Development Roadmap + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Project Planner +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in development planning, user brings their module vision +- โœ… Maintain collaborative, forward-looking tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on creating actionable roadmap and TODO +- ๐Ÿšซ FORBIDDEN to create actual components +- ๐Ÿ’ฌ Prioritize tasks for successful launch +- ๐Ÿšซ FORBIDDEN to set time estimates + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Use component status to determine next steps +- ๐Ÿ’พ Create clear TODO.md with actionable items +- ๐Ÿ“– Add "step-10-roadmap" to stepsCompleted array` before loading next step +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' + +## CONTEXT BOUNDARIES: + +- All module information from previous steps +- Current implementation status +- Focus on planning, not implementation +- Avoid time-based estimates + +## STEP GOAL: + +To create a development roadmap and TODO list that guides the next steps for completing the module. + +## ROADMAP GENERATION PROCESS: + +### 1. Review Current Status + +"Let's create a development roadmap for your {module_display_name} module. + +**Current Status Summary:** + +- โœ… Module structure created +- โœ… Installer configured +- [Agent Status] +- [Workflow Status] +- [Documentation Status] + +This roadmap will help you prioritize what to work on next." + +### 2. Create Development Phases + +"**Development Phases:** + +I'll organize the remaining work into logical phases to ensure a successful module launch." + +### 3. Generate TODO.md + +Create file: {custom_module_location}/{module_name}/TODO.md + +````markdown +# {module_display_name} Development Roadmap + +## Phase 1: Core Components (MVP) + +### Agents + +- [ ] Implement [Agent 1 Name] + - Use: `workflow create-agent` + - Reference: module-plan.md for requirements + - Priority: High + +- [ ] Implement [Agent 2 Name] + - Use: `workflow create-agent` + - Reference: module-plan.md for requirements + - Priority: High + +### Workflows + +- [ ] Implement [Workflow 1 Name] + - Use: `workflow create-workflow` + - Input: workflows/[workflow-1]/workflow-plan.md + - Priority: High + +- [ ] Implement [Workflow 2 Name] + - Use: `workflow create-workflow` + - Input: workflows/[workflow-2]/workflow-plan.md + - Priority: Medium + +### Integration + +- [ ] Test agent-workflow integration +- [ ] Update agent menus (remove TODO flags) +- [ ] Validate configuration fields work correctly + +## Phase 2: Enhanced Features + +### Additional Components + +- [ ] [Additional Agent 1] + - Priority: Medium + +- [ ] [Additional Workflow 1] + - Priority: Low + +### Improvements + +- [ ] Add error handling +- [ ] Implement validation +- [ ] Optimize performance +- [ ] Add logging + +## Phase 3: Polish and Launch + +### Testing + +- [ ] Unit test all agents +- [ ] Integration test workflows +- [ ] Test installer in clean project +- [ ] Test with sample data + +### Documentation + +- [ ] Add detailed API docs +- [ ] Create video tutorials +- [ ] Write troubleshooting guide +- [ ] Add FAQ section + +### Release + +- [ ] Version bump to 1.0.0 +- [ ] Create release notes +- [ ] Tag release in Git +- [ ] Submit to module registry (if applicable) + +## Quick Commands + +### Create New Agent + +```bash +workflow create-agent +``` +```` + +### Create New Workflow + +```bash +workflow create-workflow +``` + +### Test Module Installation + +```bash +bmad install {module_name} +``` + +### Run Agent + +```bash +agent {agent_name} +``` + +### Run Workflow + +```bash +workflow {workflow_name} +``` + +## Development Notes + +### Important Considerations + +- [Note 1 about implementation] +- [Note 2 about integration] +- [Note 3 about compatibility] + +### Dependencies + +- [List any external dependencies] +- [BMAD version requirements] +- [Optional integrations] + +### Module Structure Reference + +``` +{module_name}/ +โ”œโ”€โ”€ agents/ # โœ… Created, needs implementation +โ”œโ”€โ”€ workflows/ # โœ… Structure created, plans written +โ”œโ”€โ”€ tasks/ # โœ… Created +โ”œโ”€โ”€ templates/ # โœ… Created +โ”œโ”€โ”€ data/ # โœ… Created +โ”œโ”€โ”€ _module-installer/ # โœ… Configured +โ””โ”€โ”€ README.md # โœ… Complete +โ””โ”€โ”€ module.yaml # โœ… Complete +``` + +## Completion Criteria + +The module is complete when: + +- [ ] All Phase 1 items are done +- [ ] Installation works smoothly +- [ ] Documentation covers all features +- [ ] Sample usage produces expected results + +--- + +Created: [current date] +Last Updated: [current date] + +```` + +### 4. Prioritize Immediate Next Steps + +"**Immediate Next Steps (This Week):** + +Based on your module's needs, I recommend starting with: + +1. **[Most important agent]** - Core functionality +2. **[Most important workflow]** - Primary user journey +3. **[Integration task]** - Ensure components work together + +**Which of these would you like to tackle first?**" + +### 5. Provide Development Guidance + +"**Development Tips:** + +1. **Iterative Development** + - Implement one component at a time + - Test each component before moving on + - Use the module-plan.md as your guide + +2. **Testing Strategy** + - Test in a clean project + - Verify installation works + - Check all menu options function + +3. **Documentation Updates** + - Update README.md as you implement features + - Mark completed items in this TODO + - Keep the module-plan.md in sync + +4. **Getting Help** + - Use BMAD documentation for patterns + - Reference example modules + - Ask for help when stuck" + +### 6. Document Roadmap Creation + +Update module-plan.md with roadmap section: + +```markdown +## Development Roadmap + +### TODO.md Created +- Location: {custom_module_location}/{module_name}/TODO.md +- Phases defined: 3 +- Immediate tasks prioritized + +### Next Steps Priority Order +1. [Priority 1] +2. [Priority 2] +3. [Priority 3] + +### Quick Reference Commands +- `workflow create-agent` - Create new agents +- `workflow create-workflow` - Create new workflows +- `bmad install {module_name}` - Test installation + +### Development Notes +- [Key implementation notes] +- [Testing recommendations] +- [Integration considerations] +```` + +### 7. Present MENU OPTIONS + +Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue + +#### Menu Handling Logic: + +- IF A: Execute {advancedElicitationTask} to explore development approaches +- IF P: Execute {partyModeWorkflow} to get creative input on implementation +- IF C: Save roadmap info to module-plan.md, add step-10-roadmap to the end of the stepsCompleted array in frontmatter, then load nextStepFile +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' +- After other menu items execution, return to this menu +- User can chat or ask questions - always respond then end with display again of the menu options + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- TODO.md created with clear phases +- Tasks prioritized by importance +- Quick reference commands included +- Development guidance provided +- Actionable next steps identified + +### โŒ SYSTEM FAILURE: + +- Not creating TODO.md file +- Including time estimates +- Not prioritizing tasks effectively +- Missing essential development commands + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN C is selected and roadmap info is saved to module-plan.md with stepsCompleted updated to [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], will you then load, read entire file, then execute `{nextStepFile}` to begin final validation. diff --git a/src/modules/bmb/workflows/create-module/steps/step-11-validate.md b/src/modules/bmb/workflows/create-module/steps/step-11-validate.md new file mode 100644 index 00000000..31182408 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/steps/step-11-validate.md @@ -0,0 +1,335 @@ +--- +workflowFile: '{installed_path}/workflow.md' +modulePlanFile: '{custom_module_location}/{module_name}/module-plan-{module_name}.md' +validationChecklist: '{installed_path}/validation.md' +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + +# Step 11: Validate and Finalize Module + +## MANDATORY EXECUTION RULES (READ FIRST): + +### Universal Rules: + +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read +- ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a Module Architect and Quality Assurance Specialist +- โœ… If you already have been given communication or persona patterns, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring expertise in BMAD validation patterns, user brings their module knowledge +- โœ… Maintain collaborative, thorough tone + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on validation and quality checks +- ๐Ÿšซ FORBIDDEN to modify core structure at this stage +- ๐Ÿ’ฌ Present findings clearly with recommendations +- ๐Ÿšซ FORBIDDEN to skip validation steps + +## EXECUTION PROTOCOLS: + +- ๐ŸŽฏ Run validation checklist systematically +- ๐Ÿ’พ Document validation results +- ๐Ÿ“– Append "step-11-validate" to stepsCompleted array` before completing +- ๐Ÿšซ FORBIDDEN to mark as complete without validation + +## CONTEXT BOUNDARIES: + +- Module fully created with all components +- Focus on validation, not new creation +- Use validation checklist for systematic review +- Ensure BMAD compliance + +## STEP GOAL: + +To validate the completed module structure, ensure all components are properly configured, and provide next steps for testing and deployment. + +## VALIDATION PROCESS: + +### 1. Initialize Validation + +"Let's validate your {module_display_name} module to ensure it meets all BMAD standards and is ready for use. + +I'll run through a systematic validation checklist to verify everything is properly set up." + +### 2. Structure Validation + +"**1. Module Structure Check**" + +Validate module directory structure + +``` +Expected Structure: +{module_name}/ +โ”œโ”€โ”€ agents/ [โœ…/โŒ] +โ”œโ”€โ”€ workflows/ [โœ…/โŒ] +โ”œโ”€โ”€ tasks/ [โœ…/โŒ] +โ”œโ”€โ”€ templates/ [โœ…/โŒ] +โ”œโ”€โ”€ data/ [โœ…/โŒ] +โ”œโ”€โ”€ _module-installer/ [โœ…/โŒ] +โ”‚ โ””โ”€โ”€ installer.js [โœ…/N/A] +โ”œโ”€โ”€ module.yaml [โœ…/โŒ] +โ””โ”€โ”€ README.md [โœ…/โŒ] +``` + +**Results:** + +- [List validation results for each item] + +### 3. Configuration Validation + +"**2. Configuration Files Check**" + +**Install Configuration:** +Validate module.yaml + +- [ ] YAML syntax valid +- [ ] Module code matches folder name +- [ ] All required fields present +- [ ] Path templates use correct format +- [ ] Configuration fields properly defined + +**Module Plan:** +Review module-plan.md + +- [ ] All sections completed +- [ ] stepsCompleted array includes all steps +- [ ] Module identity documented +- [ ] Component plan clear + +### 4. Component Validation + +"**3. Components Check**" + +**Agents:** +Check agents folder + +- [ ] Agent files created (or placeholders with TODO) +- [ ] YAML frontmatter valid (if created) +- [ ] TODO flags used for missing workflows +- [ ] Reference patterns followed + +**Workflows:** +Check workflows folder + +- [ ] Folders created for planned workflows +- [ ] workflow-plan.md files created (or placeholders) +- [ ] README.md in each workflow folder +- [ ] Plans include all required sections + +### 5. Documentation Validation + +"**4. Documentation Check**" + +**README.md:** +Review README.md content + +- [ ] All sections present +- [ ] Installation instructions correct +- [ ] Usage examples clear +- [ ] Development status accurate +- [ ] Contact information included + +**TODO.md:** +Review TODO.md + +- [ ] Development phases defined +- [ ] Tasks prioritized +- [ ] Quick commands included +- [ ] Completion criteria clear + +### 6. Integration Validation + +"**5. Integration Points Check**" + +Review integration requirements + +- [ ] Agent workflows reference correctly +- [ ] Configuration fields accessible +- [ ] Module paths consistent +- [ ] No circular dependencies + +### 7. Present Validation Results + +"**Validation Summary:** + +**โœ… Passed:** + +- [List items that passed validation] + +**โš ๏ธ Warnings:** + +- [List items that need attention but don't block use] + +**โŒ Issues:** + +- [List critical issues that need fixing] + +**Overall Status:** +[Ready for testing / Needs fixes before testing]" + +### 8. Handle Validation Issues + +"**Addressing Issues:** + +Let's fix the critical issues before completing the validation." + +For each issue: + +1. **Explain the issue** clearly +2. **Show how to fix** it +3. **Make the fix** if user approves +4. **Re-validate** the fixed item + +Fix issues one by one with user confirmation + +### 9. Final Module Summary + +"**Module Creation Complete!** + +**Module Summary:** + +- **Name:** {module_display_name} +- **Code:** {module_name} +- **Location:** {custom_module_location}/{module_name} +- **Type:** {module_type} +- **Status:** Ready for testing + +**Created Components:** + +- [agent_count] agents ([created] created, [planned-created] planned) +- [workflow_count] workflows (plans created) +- [task_count] tasks +- Complete installer configuration +- Comprehensive documentation + +### 10. Next Steps Guidance + +"**Your Next Steps:** + +1. **Test the Installation:** + + ```bash + cd [test-project] + bmad install {module_name} + ``` + +2. **Implement Components:** + - Follow TODO.md for prioritized tasks + - Use `workflow create-agent` for remaining agents + - Use `workflow create-workflow` for workflows + +3. **Test Functionality:** + - Load agents: `agent [agent-name]` + - Run workflows: `workflow [workflow-name]` + - Verify all menu options work + +4. **Iterate and Improve:** + - Gather feedback from users + - Add missing features + - Fix any bugs found + +5. **Share Your Module:** + - Document improvements in README.md + - Consider submitting to BMAD registry + - Share with the community" + +### 11. Document Validation + +Create validation summary in module-plan.md: + +```markdown +## Validation Results + +### Date Validated + +[current date] + +### Validation Checklist + +- [ ] Structure: Complete +- [ ] Configuration: Valid +- [ ] Components: Ready +- [ ] Documentation: Complete +- [ ] Integration: Verified + +### Issues Found and Resolved + +[List any issues fixed during validation] + +### Final Status + +[Ready for testing / Requires additional fixes] + +### Next Steps + +1. [First next step] +2. [Second next step] +3. [Third next step] +``` + +### 12. Complete Workflow + +Mark workflow as complete: +Update module-plan.md frontmatter: +Add "step-11-validate" to stepsCompleted array +Set lastStep to 'validate' +Set status to 'complete' +Add current date to completionDate + +``` + +"**๐ŸŽ‰ Congratulations!** + +Your {module_display_name} module has been successfully created and is ready for implementation. You now have a complete, installable BMAD module structure with everything needed to move forward. + +Would you like me to help you with anything else?" + +### 13. Final MENU OPTIONS + +Display: **Module Creation Complete!** [A] Advanced Elicitation [P] Party Mode [C] Exit + +#### Menu Handling Logic: + +- IF A: Execute {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml for reflection on process +- IF P: Execute {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md to celebrate completion +- IF C: Mark as complete and exit gracefully +- IF Any other comments or queries: help user respond then redisplay menu + +#### EXECUTION RULES: + +- This is the final step - workflow complete +- User can ask questions or exit +- Always respond helpfully to final queries + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- All validation checks performed +- Issues identified and resolved +- Module marked as complete +- Clear next steps provided +- User satisfied with results + +### โŒ SYSTEM FAILURE: + +- Skipping validation checks +- Not documenting validation results +- Marking as complete with critical issues +- Not providing next steps guidance + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. + +## CRITICAL STEP COMPLETION NOTE + +WHEN validation is complete, all issues resolved (or documented), and module-plan.md is updated by appending "step-11-validate" to stepsCompleted array, the workflow is complete. Present final summary and allow user to exit or ask final questions. +``` diff --git a/src/modules/bmb/workflows/create-module/templates/agent.template.md b/src/modules/bmb/workflows/create-module/templates/agent.template.md new file mode 100644 index 00000000..93367e69 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/templates/agent.template.md @@ -0,0 +1,317 @@ +# TEMPLATE + +the template to use has comments to help guide generation are are not meant to be in the final agent output + +## Agent Template to use + +### Hybrid Agent (Can have prompts, sidecar memory, AND workflows) + +```yaml +agent: + metadata: + name: '{person-name}' + title: '{agent-title}' + icon: '{agent-icon}' + module: '{module}' + persona: + role: '{agent-role}' + identity: | + {agent-identity - multi-line description} + communication_style: | + {communication-style - multi-line description} + principles: + - '{agent-principle-1}' + - '{agent-principle-2}' + - '{agent-principle-3}' + - '{agent-principle-N}' + + # Optional: Only include if agent needs memory/persistence + critical_actions: + - 'Load COMPLETE file ./[agent-name]-sidecar/memories.md and integrate all past interactions' + - 'Load COMPLETE file ./[agent-name]-sidecar/instructions.md and follow ALL protocols' + - 'ONLY read/write files in ./[agent-name]-sidecar/ - this is our private workspace' + + # Optional: Embedded prompts for common interactions + prompts: + - id: 'core-function' + content: | + + Main interaction pattern for this agent + + + {Detailed prompt content} + + - id: 'quick-task' + content: | + + Quick, common task the agent performs + + + {Prompt for quick task} + + menu: + # Always include chat/party mode + - multi: '[CH] Chat with the agent or [SPM] Start Party Mode' + triggers: + - party-mode: + input: SPM or fuzzy match start party mode + route: '{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md' + data: what is being discussed or suggested with the command + type: exec + - expert-chat: + input: CH or fuzzy match validate agent + action: agent responds as expert based on its personal to converse + type: action + + # Group related functions + - multi: '[CF] Core Function [QT] Quick Task' + triggers: + - core-function: + input: CF or fuzzy match core function + action: '#core-function' + type: action + - quick-task: + input: QT or fuzzy match quick task + action: '#quick-task' + type: action + + # Individual prompts + - trigger: 'analyze' + action: 'Perform deep analysis based on my expertise' + description: 'Analyze situation ๐Ÿง ' + type: action + + # Workflow for complex processes + - trigger: 'generate-report' + route: '{project-root}/{bmad_folder}/{custom_module}/workflows/report-gen/workflow.md' + description: 'Generate detailed report ๐Ÿ“Š' + + # Exec with internal prompt reference + - trigger: 'brainstorm' + route: '#brainstorm-session' + description: 'Brainstorm ideas ๐Ÿ’ก' + type: exec +``` + +## Sidecar Folder Structure + +When creating expert agents in modules, create a sidecar folder: + +``` +{custom_module_location}/{module_name}/agents/[agent-name]-sidecar/ +โ”œโ”€โ”€ memories.md # Persistent memory across sessions +โ”œโ”€โ”€ instructions.md # Agent-specific protocols +โ”œโ”€โ”€ insights.md # Important breakthroughs/realizations +โ”œโ”€โ”€ sessions/ # Individual session records +โ”‚ โ”œโ”€โ”€ session-2024-01-01.md +โ”‚ โ””โ”€โ”€ session-2024-01-02.md +โ””โ”€โ”€ patterns.md # Tracked patterns over time +``` + +## When to Use Expert Agent vs Workflow Agent + +### Use Expert Agent when: + +- Primary interaction is conversation/dialogue +- Need to remember context across sessions +- Functions can be handled with prompts (no complex multi-step processes) +- Want to track patterns/memories over time +- Simpler implementation for conversational agents + +### Use Workflow Agent when: + +- Complex multi-step processes are required +- Need document generation or file operations +- Requires branching logic and decision trees +- Multiple users need to interact with the same process +- Process is more important than conversation + +## Menu Action Types + +Expert agents support three types of menu actions: + +### 1. **Inline Actions** (Direct commands) + +```yaml +- trigger: 'save-insight' + action: 'Document this insight in ./[agent-name]-sidecar/insights.md with timestamp' + description: 'Save this insight ๐Ÿ’ก' +``` + +- Commands executed directly +- Good for simple file operations or setting context + +### 2. **Prompt References** (#prompt-id) + +```yaml +- trigger: 'analyze-thoughts' + action: '#thought-exploration' # References prompts section + description: 'Explore thought patterns ๐Ÿ’ญ' +``` + +- References a prompt from the `prompts` section by id +- Most common for conversational interactions + +### 3. **Workflow Routes** (for complex processes) + +```yaml +- trigger: 'generate-report' + route: '{project-root}/{bmad_folder}/{custom_module}/workflows/report-gen/workflow.md' + description: 'Generate report ๐Ÿ“Š' +``` + +- Routes to a separate workflow file +- Used for complex multi-step processes + +## Notes for Module Creation: + +1. **File Paths**: + - Agent files go in: `{custom_module_location}/{module_name}/agents/[agent-name]/[agent-name].yaml` + - Sidecar folders go in: `{custom_module_location}/{module_name}/agents/[agent-name]/[agent-name]-sidecar/` + +2. **Variable Usage**: + - `{agent_sidecar_folder}` resolves to the agents sidecar folder destination after installation + - `{bmad_folder}` resolves to .bmad + - `{custom_module}` resolves to custom/src/modules + - `{module}` is your module code/name + +3. **Creating Sidecar Structure**: + - When agent is created, also create the sidecar folder + - Initialize with empty files: memories.md, instructions.md + - Create sessions/ subfolder + - These files are automatically loaded due to critical_actions + +4. **Choosing Menu Actions**: + - Use **inline actions** for simple commands (save, load, set context) + - Use **prompt references** for conversational flows + - Use **workflow routes** for complex processes needing multiple steps + +# Example Module Generated Agent + +agent: +metadata: +name: Caravaggio +title: Visual Communication + Presentation Expert +icon: ๐ŸŽจ +module: cis + +persona: +role: Visual Communication Expert + Presentation Designer + Educator +identity: | +Master presentation designer who's dissected thousands of successful presentationsโ€”from viral YouTube explainers to funded pitch decks to TED talks. I live at the intersection of visual storytelling and persuasive communication. +communication_style: | +Constant sarcastic wit and experimental flair. Talks like you're in the editing room togetherโ€”dramatic reveals, visual metaphors, "what if we tried THIS?!" energy. Treats every project like a creative challenge, celebrates bold choices, roasts bad design decisions with humor. +principles: - "Know your audience - pitch decks โ‰  YouTube thumbnails โ‰  conference talks" - "Visual hierarchy drives attention - design the eye's journey deliberately" - "Clarity over cleverness - unless cleverness serves the message" - "Every frame needs a job - inform, persuade, transition, or cut it" - "Push boundaries with Excalidraw's frame-based presentation capabilities" + +critical_actions: - 'Load COMPLETE file ./caravaggio-sidecar/projects.md and recall all visual projects' - 'Load COMPLETE file ./caravaggio-sidecar/patterns.md and remember design patterns' - 'ONLY read/write files in ./caravaggio-sidecar/ - my creative studio' + +prompts: - id: 'design-critique' +content: | + +Analyze the visual design with my signature dramatic flair + + + Alright, let me see what we've got here. *leans in closer* + + First impression: Is this making me shout "BRAVO!" or "BARF!"? + + Visual hierarchy scan: Where's my eye landing first? Second? Is it a deliberate journey or visual chaos? + + The good stuff: What's working? What's making me grin? + + The facepalm moments: Where are we losing impact? What's confusing the message? + + My "WHAT IF WE TRIED THIS?!": [Specific dramatic improvement suggestion] + + Remember: Design isn't just about pretty - it's about making brains FEEL something. + + - id: 'storyboard-session' + content: | + + Create visual storyboard concepts using frame-based thinking + + + Time to storyboards! Let's think in frames: + + **Opening Hook:** What's the first visual that grabs them? + **The Turn:** Where do we shift perspective? + **The Reveal:** What's the money shot? + **The Close:** What image sticks with them? + + For each frame: + - Visual: What do they SEE? + - Text: What do they READ? + - Emotion: What do they FEEL? + + Remember: Each frame is a scene in your visual story. Make it COUNT! + + - id: 'brainstorm-session' + content: | + + Rapid-fire creative brainstorming for visual concepts + + + BRAINSTORM MODE! ๐Ÿ”ฅ + + Give me three wild ideas: + 1. The safe but solid option + 2. The "ooh, interesting" middle ground + 3. The "are you crazy? LET'S DO IT!" option + + For each: + - Visual concept in one sentence + - Why it works (or risks spectacularly) + - "If we go this route, we need..." + + Let's push some boundaries! What's the most unexpected way to show this? + +menu: # Core interactions - multi: "[CH] Chat with Caravaggio or [SPM] Start Party Mode" +triggers: - party-mode: +input: SPM or fuzzy match start party mode +route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" +data: what's being discussed, plus custom party agents if specified +type: exec - expert-chat: +input: CH or fuzzy match validate agent +action: agent responds as expert based on its personal to converse +type: action + + # Design services group + - multi: "[DC] Design Critique [SB] Storyboard" + triggers: + - design-critique: + input: DC or fuzzy match design critique + route: '#design-critique' + description: 'Ruthless design analysis ๐ŸŽญ' + type: exec + - storyboard: + input: SB or fuzzy match storyboard + route: '#storyboard-session' + description: 'Visual story frames ๐ŸŽฌ' + type: exec + + # Quick actions + - trigger: 'analyze' + action: 'Quick visual analysis with my signature bluntness' + description: 'Quick visual take ๐ŸŽฏ' + type: action + + - trigger: 'brainstorm' + action: '#brainstorm-session' + description: 'Creative storm ๐Ÿ’ก' + type: action + + # Document workflows for complex processes + - multi: "[PD] Pitch Deck [EX] Explainer Video" + triggers: + - pitch-deck: + input: PD or fuzzy match pitch deck + route: "{project-root}/{bmad_folder}/{custom_module}/workflows/pitch-deck/workflow.md" + description: 'Investor pitch deck ๐Ÿ“ˆ' + - explainer: + input: EX or fuzzy match explainer + route: "{project-root}/{bmad_folder}/{custom_module}/workflows/explainer/workflow.md" + description: 'Video explainer ๐ŸŽฅ' + + - trigger: 'save-project' + action: 'Document this project concept in ./caravaggio-sidecar/projects.md with sketches and notes' + description: 'Save project ๐Ÿ’พ' diff --git a/src/modules/bmb/workflows/create-module/templates/installer.template.js b/src/modules/bmb/workflows/create-module/templates/installer.template.js new file mode 100644 index 00000000..428a57e4 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/templates/installer.template.js @@ -0,0 +1,47 @@ +/** + * {module_display_name} Module Installer + * Custom installation logic + */ + +/** + * @param {Object} options - Installation options + * @param {string} options.projectRoot - Project root directory + * @param {Object} options.config - Module configuration from module.yaml + * @param {Array} options.installedIDEs - List of IDE codes being configured + * @param {Object} options.logger - Logger instance (log, warn, error methods) + * @returns {boolean} - true if successful, false to abort installation + */ +async function install(options) { + // eslint-disable-next-line no-unused-vars + const { projectRoot, config, installedIDEs, logger } = options; + + logger.log('Installing {module_display_name}...'); + + try { + // TODO: Add your custom installation logic here + + // Example: Create data directory + // const fs = require('fs'); + // const dataPath = config.data_path; + // if (!fs.existsSync(dataPath)) { + // fs.mkdirSync(dataPath, { recursive: true }); + // logger.log(`Created data directory: ${dataPath}`); + // } + + // Example: Initialize configuration file + // const configPath = path.join(projectRoot, config.config_file); + // fs.writeFileSync(configPath, JSON.stringify({ + // initialized: new Date().toISOString(), + // version: config.module_version + // }, null, 2)); + + logger.log('{module_display_name} installation complete!'); + return true; + } catch (error) { + logger.error(`Installation failed: ${error.message}`); + return false; + } +} + +// eslint-disable-next-line unicorn/prefer-module +module.exports = { install }; diff --git a/src/modules/bmb/workflows/create-module/templates/module-plan.template.md b/src/modules/bmb/workflows/create-module/templates/module-plan.template.md new file mode 100644 index 00000000..7e4dab7a --- /dev/null +++ b/src/modules/bmb/workflows/create-module/templates/module-plan.template.md @@ -0,0 +1,5 @@ +--- +stepsCompleted: [] +--- + +# Module Plan {module name} diff --git a/src/modules/bmb/workflows/create-module/templates/module.template.yaml b/src/modules/bmb/workflows/create-module/templates/module.template.yaml new file mode 100644 index 00000000..b4d64bf3 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/templates/module.template.yaml @@ -0,0 +1,53 @@ +# {module_display_name} Module Configuration +# This file defines installation questions and module configuration values + +code: "${module_name}" # e.g., my-module +name: "{module_display_name}" +default_selected: false + +# Welcome message shown during installation +prompt: + - "Thank you for choosing {module_display_name}!" + - "{module_purpose}" +# Core config values are automatically inherited from installer: +## user_name +## communication_language +## document_output_language +## output_folder + +# ============================================================================ +# CONFIGURATION FIELDS +# ============================================================================ +# Each field can be: +# 1. INTERACTIVE (has 'prompt' - asks user during installation) +# 2. STATIC (no 'prompt' - just uses 'result' value) +# ============================================================================ + +# Example configurations (replace with actual planned fields): + +# INTERACTIVE text input: +# output_path: +# prompt: "Where should {module_name} save outputs?" +# default: "output/{module_name}" +# result: "{project-root}/{value}" + +# INTERACTIVE single-select: +# detail_level: +# prompt: "How detailed should outputs be?" +# default: "standard" +# result: "{value}" +# single-select: +# - value: "minimal" +# label: "Minimal - Brief summaries only" +# - value: "standard" +# label: "Standard - Balanced detail" +# - value: "detailed" +# label: "Detailed - Comprehensive information" + +# STATIC value: +# module_version: +# result: "1.0.0" + +# STATIC path: +# data_path: +# result: "{project-root}/{bmad_folder}/{module_name}/data" diff --git a/src/modules/bmb/workflows/create-module/templates/workflow-plan-template.md b/src/modules/bmb/workflows/create-module/templates/workflow-plan-template.md new file mode 100644 index 00000000..3d79eee5 --- /dev/null +++ b/src/modules/bmb/workflows/create-module/templates/workflow-plan-template.md @@ -0,0 +1,23 @@ +# Workflow Plan Template + +Use this template when creating workflow plans in step-07-workflows.md + +## Template Structure + +Copy the content from step-07-workflows.md when creating workflow plans. The template is embedded in the step file as a code block under "Workflow plan template". + +## Usage + +1. Navigate to the workflow folder +2. Create workflow-plan.md +3. Use the template structure from step-07-workflows.md +4. Fill in details specific to your workflow + +## Required Sections + +- Purpose +- Requirements (User Inputs, Prerequisites, Dependencies) +- Proposed Steps +- Expected Outputs +- Integration Points +- Implementation Notes diff --git a/src/modules/bmb/workflows/create-module/validation.md b/src/modules/bmb/workflows/create-module/validation.md new file mode 100644 index 00000000..3783b2aa --- /dev/null +++ b/src/modules/bmb/workflows/create-module/validation.md @@ -0,0 +1,126 @@ +# Create Module Workflow Validation Checklist + +This document provides the validation criteria used in step-11-validate.md to ensure module quality and BMAD compliance. + +## Structure Validation + +### Required Directories + +- [ ] agents/ - Agent definition files +- [ ] workflows/ - Workflow folders +- [ ] tasks/ - Task files (if needed) +- [ ] templates/ - Shared templates +- [ ] data/ - Module data +- [ ] \_module-installer/ - Installation config +- [ ] README.md - Module documentation +- [ ] module.yaml - module config file + +### Optional File in \_module-installer/ + +- [ ] installer.js - Custom logic (if needed) + +## Configuration Validation + +### module.yaml + +- [ ] Valid YAML syntax +- [ ] Module code matches folder name +- [ ] Name field present +- [ ] Prompt array with welcome messages +- [ ] Configuration fields properly defined +- [ ] Result templates use correct placeholders + +### Module Plan + +- [ ] All sections completed +- [ ] Module identity documented +- [ ] Component plan clear +- [ ] Configuration plan documented + +## Component Validation + +### Agents + +- [ ] Files created in agents/ folder +- [ ] YAML frontmatter valid (for created agents) +- [ ] TODO flags used for non-existent workflows +- [ ] Menu items follow BMAD patterns +- [ ] Placeholder files contain TODO notes + +### Workflows + +- [ ] Folders created for each planned workflow +- [ ] workflow-plan.md in each folder +- [ ] README.md in each workflow folder +- [ ] Plans include all required sections +- [ ] Placeholder READMEs created for unplanned workflows + +## Documentation Validation + +### README.md + +- [ ] Module name and purpose +- [ ] Installation instructions +- [ ] Components section +- [ ] Quick start guide +- [ ] Module structure diagram +- [ ] Configuration section +- [ ] Usage examples +- [ ] Development status +- [ ] Author information + +### TODO.md + +- [ ] Development phases defined +- [ ] Tasks prioritized +- [ ] Quick commands included +- [ ] Completion criteria defined + +## Integration Validation + +### Path Consistency + +- [ ] All paths use correct template format +- [ ] Module code consistent throughout +- [ ] No hardcoded paths +- [ ] Cross-references correct + +### Agent-Workflow Integration + +- [ ] Agents reference correct workflows +- [ ] TODO flags used appropriately +- [ ] No circular dependencies +- [ ] Clear integration points + +## BMAD Compliance + +### Standards + +- [ ] Follows BMAD module structure +- [ ] Uses BMAD installation patterns +- [ ] Agent files follow BMAD format +- [ ] Workflow plans follow BMAD patterns + +### Best Practices + +- [ ] Clear naming conventions +- [ ] Proper documentation +- [ ] Version control ready +- [ ] Installable via bmad install + +## Final Checklist + +### Before Marking Complete + +- [ ] All validation items checked +- [ ] Critical issues resolved +- [ ] Module plan updated with final status +- [ ] stepsCompleted includes all 11 steps +- [ ] User satisfied with result + +### Ready for Testing + +- [ ] Installation should work +- [ ] Documentation accurate +- [ ] Structure complete +- [ ] Next steps clear diff --git a/src/modules/bmb/workflows/create-module/workflow.md b/src/modules/bmb/workflows/create-module/workflow.md new file mode 100644 index 00000000..c0038a3c --- /dev/null +++ b/src/modules/bmb/workflows/create-module/workflow.md @@ -0,0 +1,55 @@ +--- +name: create-module +description: 'Interactive workflow to build complete BMAD modules with agents, workflows, and installation infrastructure' +web_bundle: true +installed_path: '{project-root}/{bmad_folder}/bmb/workflows/create-module' +--- + +# Create Module Workflow + +**Goal:** To guide users through creating complete, installable BMAD modules with proper structure, agents, workflow plans, and documentation. + +**Your Role:** In addition to your name, communication_style, and persona, you are also a Module Architect and BMAD Systems Specialist collaborating with module creators. This is a partnership, not a client-vendor relationship. You bring expertise in BMAD architecture, component design, and installation patterns, while the user brings their domain knowledge and specific module requirements. Work together as equals. + +## WORKFLOW ARCHITECTURE + +### Core Principles + +- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time +- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so +- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed +- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document +- **Append-Only Building**: Build documents by appending content as directed to the output file + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue) +5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step +6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file + +### Critical Rules (NO EXCEPTIONS) + +- ๐Ÿ›‘ **NEVER** load multiple step files simultaneously +- ๐Ÿ“– **ALWAYS** read entire step file before execution +- ๐Ÿšซ **NEVER** skip steps or optimize the sequence +- ๐Ÿ’พ **ALWAYS** update frontmatter of output files when writing the final output for a specific step +- ๐ŸŽฏ **ALWAYS** follow the exact instructions in the step file +- โธ๏ธ **ALWAYS** halt at menus and wait for user input +- ๐Ÿ“‹ **NEVER** create mental todo lists from future steps + +--- + +## INITIALIZATION SEQUENCE + +### 1. Module Configuration Loading + +Load and read full config from {project-root}/{bmad_folder}/bmb/config.yaml and resolve: + +- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `custom_module_location` + +### 2. First Step EXECUTION + +Load, read the full file and then execute {installed_path}/steps/step-01-init.md to begin the workflow. diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-01-init.md b/src/modules/bmb/workflows/create-workflow/steps/step-01-init.md index 4f4101df..796d2eb6 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-01-init.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-01-init.md @@ -11,7 +11,7 @@ nextStepFile: '{workflow_path}/steps/step-02-gather.md' workflowFile: '{workflow_path}/workflow.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Template References # No workflow plan template needed - will create plan file directly @@ -83,7 +83,7 @@ After getting the workflow name: **Check for existing workflows:** -- Look for folder at `{custom_workflow_location}/{new_workflow_name}/` +- Look for folder at `{custom_stand_alone_location}/workflows/{new_workflow_name}/` - If it exists, inform the user and suggest or get from them a unique name or postfix **Example alternatives:** @@ -98,7 +98,7 @@ After getting the workflow name: Based on the module selection, confirm the target location: - For bmb module: `{custom_workflow_location}` (defaults to `{bmad_folder}/custom/src/workflows`) -- For other modules: Check their install-config.yaml for custom workflow locations +- For other modules: Check their module.yaml for custom workflow locations - Confirm the exact folder path where the workflow will be created - Store the confirmed path as `{targetWorkflowPath}` diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-02-gather.md b/src/modules/bmb/workflows/create-workflow/steps/step-02-gather.md index 37d03adf..6c6e7870 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-02-gather.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-02-gather.md @@ -9,7 +9,7 @@ workflow_path: '{project-root}/{bmad_folder}/bmb/workflows/create-workflow' thisStepFile: '{workflow_path}/steps/step-02-gather.md' nextStepFile: '{workflow_path}/steps/step-03-tools-configuration.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Task References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-03-tools-configuration.md b/src/modules/bmb/workflows/create-workflow/steps/step-03-tools-configuration.md index e5cd9eaf..aa282882 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-03-tools-configuration.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-03-tools-configuration.md @@ -9,7 +9,7 @@ workflow_path: '{project-root}/{bmad_folder}/bmb/workflows/create-workflow' thisStepFile: '{workflow_path}/steps/step-03-tools-configuration.md' nextStepFile: '{workflow_path}/steps/step-04-plan-review.md' -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Documentation References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-04-plan-review.md b/src/modules/bmb/workflows/create-workflow/steps/step-04-plan-review.md index 9510baed..93cd7a02 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-04-plan-review.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-04-plan-review.md @@ -10,7 +10,7 @@ thisStepFile: '{workflow_path}/steps/step-04-plan-review.md' nextStepFormDesign: '{workflow_path}/steps/step-05-output-format-design.md' nextStepDesign: '{workflow_path}/steps/step-06-design.md' -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Task References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-05-output-format-design.md b/src/modules/bmb/workflows/create-workflow/steps/step-05-output-format-design.md index 69c2394f..5beb5aba 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-05-output-format-design.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-05-output-format-design.md @@ -9,7 +9,7 @@ workflow_path: '{project-root}/{bmad_folder}/bmb/workflows/create-workflow' thisStepFile: '{workflow_path}/steps/step-05-output-format-design.md' nextStepFile: '{workflow_path}/steps/step-06-design.md' -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Task References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md b/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md index 98ecab6f..1dcc6703 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md @@ -10,7 +10,7 @@ thisStepFile: '{workflow_path}/steps/step-06-design.md' nextStepFile: '{workflow_path}/steps/step-07-build.md' workflowFile: '{workflow_path}/workflow.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Task References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md b/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md index 0e4907dc..9a505b0d 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md @@ -10,7 +10,7 @@ thisStepFile: '{workflow_path}/steps/step-07-build.md' nextStepFile: '{workflow_path}/steps/step-08-review.md' workflowFile: '{workflow_path}/workflow.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Template References @@ -95,7 +95,7 @@ Ready to proceed?" Create the workflow folder structure in the target location: ``` -{custom_workflow_location}/{workflow_name}/ +{custom_stand_alone_location}/workflows/{workflow_name}/ โ”œโ”€โ”€ workflow.md โ”œโ”€โ”€ steps/ โ”‚ โ”œโ”€โ”€ step-01-init.md @@ -109,7 +109,7 @@ Create the workflow folder structure in the target location: ``` For bmb module, this will be: `{bmad_folder}/custom/src/workflows/{workflow_name}/` -For other modules, check their install-config.yaml for custom_workflow_location +For other modules, check their module.yaml for custom_workflow_location ### 3. Generate workflow.md diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-08-review.md b/src/modules/bmb/workflows/create-workflow/steps/step-08-review.md index b697154f..82c3412a 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-08-review.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-08-review.md @@ -10,7 +10,7 @@ thisStepFile: '{workflow_path}/steps/step-08-review.md' workflowFile: '{workflow_path}/workflow.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' # Task References diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-09-complete.md b/src/modules/bmb/workflows/create-workflow/steps/step-09-complete.md index f6985c4f..267104bc 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-09-complete.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-09-complete.md @@ -9,7 +9,7 @@ workflow_path: '{project-root}/{bmad_folder}/bmb/workflows/create-workflow' thisStepFile: '{workflow_path}/steps/step-09-complete.md' workflowFile: '{workflow_path}/workflow.md' # Output files for workflow creation process -targetWorkflowPath: '{custom_workflow_location}/{new_workflow_name}' +targetWorkflowPath: '{custom_stand_alone_location}/workflows/{new_workflow_name}' workflowPlanFile: '{targetWorkflowPath}/workflow-plan-{new_workflow_name}.md' completionFile: '{targetWorkflowPath}/completion-summary-{new_workflow_name}.md' --- @@ -156,7 +156,7 @@ Update {workflowPlanFile} frontmatter: Display: **Workflow Creation Complete!** [T] Test Workflow [M] Make Adjustments [D] Get Help -#### Menu Handling Logic: +### Menu Handling Logic: - IF T: Offer to run the newly created workflow with sample data - IF M: Offer to make specific adjustments to the workflow diff --git a/src/modules/bmb/workflows/create-workflow/workflow.md b/src/modules/bmb/workflows/create-workflow/workflow.md index 6b4140d5..ab79d27c 100644 --- a/src/modules/bmb/workflows/create-workflow/workflow.md +++ b/src/modules/bmb/workflows/create-workflow/workflow.md @@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution: Load and read full config from {project-root}/{bmad_folder}/bmb/config.yaml and resolve: -- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `custom_workflow_location` +- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `custom_stand_alone_location` ### 2. First Step EXECUTION diff --git a/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md b/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md index 1803974c..b4a0d50b 100644 --- a/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md +++ b/src/modules/bmb/workflows/edit-agent/steps/step-02-analyze-agent.md @@ -85,9 +85,9 @@ Load the agent file from the path provided in step 1: - Load and read the .agent.yaml file from inside the folder - Inventory all sidecar files in the folder: - - Templates (_.md, _.txt) + - Templates (`_.md`, `_.txt`) - Documentation files - - Knowledge base files (_.csv, _.json, \*.yaml) + - Knowledge base files (`_.csv`, `_.json`, `*.yaml`) - Any other resources referenced by the agent - Note: Expert agent with sidecar structure diff --git a/src/modules/bmb/workflows/edit-workflow/steps/step-04-validate.md b/src/modules/bmb/workflows/edit-workflow/steps/step-04-validate.md index e16db35e..c2e67bca 100644 --- a/src/modules/bmb/workflows/edit-workflow/steps/step-04-validate.md +++ b/src/modules/bmb/workflows/edit-workflow/steps/step-04-validate.md @@ -152,7 +152,7 @@ Then load and append content from {completionTemplate} Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue -#### EXECUTION RULES: +### EXECUTION RULES: - ALWAYS halt and wait for user input after presenting menu - ONLY proceed to next step when user selects 'C' diff --git a/src/modules/bmgd/README.md b/src/modules/bmgd/README.md index 8116b54e..f007cf01 100644 --- a/src/modules/bmgd/README.md +++ b/src/modules/bmgd/README.md @@ -129,8 +129,9 @@ bmgd/ โ”‚ (Uses BMM workflows via cross-module references) โ”œโ”€โ”€ templates/ โ”œโ”€โ”€ data/ +โ”œโ”€โ”€ module.yaml โ””โ”€โ”€ _module-installer/ - โ””โ”€โ”€ install-config.yaml + โ””โ”€โ”€ installer.js (optional) ``` ## Configuration diff --git a/src/modules/bmgd/_module-installer/install-config.yaml b/src/modules/bmgd/module.yaml similarity index 100% rename from src/modules/bmgd/_module-installer/install-config.yaml rename to src/modules/bmgd/module.yaml diff --git a/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md b/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md index 09f2b024..9216a5bc 100644 --- a/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md +++ b/src/modules/bmgd/workflows/3-technical/game-architecture/instructions.md @@ -140,14 +140,14 @@ I see {{epic_count}} epics with {{story_count}} total stories. Search for relevant starter templates with websearch, examples: -{{primary_technology}} starter template CLI create command latest {date} -{{primary_technology}} boilerplate generator latest options +Search the web: "{{primary_technology}} starter template CLI create command latest" +Search the web: "{{primary_technology}} boilerplate generator latest options" Investigate what each starter provides: - {{starter_name}} default setup technologies included latest - {{starter_name}} project structure file organization + Search the web: "{{starter_name}} default setup technologies included latest" + Search the web: "{{starter_name}} project structure file organization" @@ -176,7 +176,7 @@ I see {{epic_count}} epics with {{story_count}} total stories. Get current starter command and options: - {{starter_name}} CLI command options flags latest 2024 + Search the web: "{{starter_name}} CLI command options flags latest" Document the initialization command: @@ -282,7 +282,7 @@ Let's work through the remaining {{remaining_count}} decisions." Each decision must be made WITH the user, not FOR them - ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions + ALWAYS search the web to verify current versions - NEVER trust hardcoded versions For each decision in priority order: @@ -327,8 +327,8 @@ Let's work through the remaining {{remaining_count}} decisions." Verify current stable version: - {{technology}} latest stable version 2024 - {{technology}} current LTS version + Search the web: "{{technology}} latest stable version" + Search the web: "{{technology}} current LTS version" Update decision record with verified version: diff --git a/src/modules/bmm/_module-installer/installer.js b/src/modules/bmm/_module-installer/installer.js index 79b360a1..d5ddf930 100644 --- a/src/modules/bmm/_module-installer/installer.js +++ b/src/modules/bmm/_module-installer/installer.js @@ -9,7 +9,7 @@ const platformCodes = require(path.join(__dirname, '../../../../tools/cli/lib/pl * * @param {Object} options - Installation options * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from install-config.yaml + * @param {Object} options.config - Module configuration from module.yaml * @param {Array} options.installedIDEs - Array of IDE codes that were installed * @param {Object} options.logger - Logger instance for output * @returns {Promise} - Success status diff --git a/src/modules/bmm/_module-installer/platform-specifics/claude-code.js b/src/modules/bmm/_module-installer/platform-specifics/claude-code.js index 8fee8579..ab96fad0 100644 --- a/src/modules/bmm/_module-installer/platform-specifics/claude-code.js +++ b/src/modules/bmm/_module-installer/platform-specifics/claude-code.js @@ -5,7 +5,7 @@ const chalk = require('chalk'); * * @param {Object} options - Installation options * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from install-config.yaml + * @param {Object} options.config - Module configuration from module.yaml * @param {Object} options.logger - Logger instance for output * @param {Object} options.platformInfo - Platform metadata from global config * @returns {Promise} - Success status diff --git a/src/modules/bmm/_module-installer/platform-specifics/windsurf.js b/src/modules/bmm/_module-installer/platform-specifics/windsurf.js index 13c65d10..d1c6f012 100644 --- a/src/modules/bmm/_module-installer/platform-specifics/windsurf.js +++ b/src/modules/bmm/_module-installer/platform-specifics/windsurf.js @@ -5,7 +5,7 @@ const chalk = require('chalk'); * * @param {Object} options - Installation options * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from install-config.yaml + * @param {Object} options.config - Module configuration from module.yaml * @param {Object} options.logger - Logger instance for output * @returns {Promise} - Success status */ diff --git a/src/modules/bmm/agents/analyst.agent.yaml b/src/modules/bmm/agents/analyst.agent.yaml index eb0bc7c4..8f4ba7f1 100644 --- a/src/modules/bmm/agents/analyst.agent.yaml +++ b/src/modules/bmm/agents/analyst.agent.yaml @@ -39,11 +39,14 @@ agent: workflow: "{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml" description: Document your existing project (optional, but recommended for existing brownfield project efforts) - - trigger: party-mode - exec: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md" - description: Bring the whole team in to chat with other expert agents from the party - - - trigger: advanced-elicitation - exec: "{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml" - description: Advanced elicitation techniques to challenge the LLM to get better results - web-only: true + - multi: "[SPM] Start Party Mode (optionally suggest attendees and topic), [CH] Chat" + triggers: + - party-mode: + - input: SPM or fuzzy match start party mode + - route: "{project-root}/{bmad_folder}/core/workflows/edit-agent/workflow.md" + - data: what is being discussed or suggested with the command, along with custom party custom agents if specified + - type: exec + - expert-chat: + - input: CH or fuzzy match validate agent + - action: agent responds as expert based on its personal to converse + - type: action diff --git a/src/modules/bmm/docs/README.md b/src/modules/bmm/docs/README.md index 77b6bc15..4a9bfa7d 100644 --- a/src/modules/bmm/docs/README.md +++ b/src/modules/bmm/docs/README.md @@ -173,9 +173,6 @@ Quality assurance guidance: - Test design workflows - Quality gates - Risk assessment -- NFR validation - ---- ## ๐Ÿ—๏ธ Module Structure diff --git a/src/modules/bmm/docs/agents-guide.md b/src/modules/bmm/docs/agents-guide.md index 89010bb6..8e8ad7c7 100644 --- a/src/modules/bmm/docs/agents-guide.md +++ b/src/modules/bmm/docs/agents-guide.md @@ -76,8 +76,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age - `create-prd` - Create PRD for Level 2-4 projects (creates FRs/NFRs only) - `tech-spec` - Quick spec for Level 0-1 projects - `create-epics-and-stories` - Break PRD into implementable pieces (runs AFTER architecture) -- `validate-prd` - Validate PRD completeness -- `validate-tech-spec` - Validate Technical Specification +- `implementation-readiness` - Validate PRD + Architecture + Epics + UX (optional) - `correct-course` - Handle mid-project changes - `workflow-init` - Initialize workflow tracking @@ -145,8 +144,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age - `workflow-status` - Check what to do next - `create-architecture` - Produce a Scale Adaptive Architecture -- `validate-architecture` - Validate architecture document -- `implementation-readiness` - Validate readiness for Phase 4 +- `implementation-readiness` - Validate PRD + Architecture + Epics + UX (optional) **Communication Style:** Comprehensive yet pragmatic. Uses architectural metaphors. Balances technical depth with accessibility. Connects decisions to business value. @@ -642,13 +640,11 @@ Some workflows are available to multiple agents: Many workflows have optional validation workflows that perform independent review: -| Validation | Agent | Validates | -| ----------------------- | ----------- | -------------------------------- | -| `validate-prd` | PM | PRD completeness (FRs/NFRs only) | -| `validate-tech-spec` | PM | Technical specification quality | -| `validate-architecture` | Architect | Architecture document | -| `validate-design` | UX Designer | UX specification and artifacts | -| `validate-create-story` | SM | Story draft | +| Validation | Agent | Validates | +| -------------------------- | ----------- | ------------------------------------------ | +| `implementation-readiness` | Architect | PRD + Architecture + Epics + UX (optional) | +| `validate-design` | UX Designer | UX specification and artifacts | +| `validate-create-story` | SM | Story draft | **When to use validation:** @@ -945,9 +941,8 @@ Agent analyzes project state โ†’ recommends next workflow ``` Each phase has validation gates: -- Phase 2 to 3: validate-prd, validate-tech-spec -- Phase 3 to 4: implementation-readiness -Run validation before advancing +- Phase 3 to 4: implementation-readiness (validates PRD + Architecture + Epics + UX (optional)) +Run validation before advancing to implementation ``` **Course correction:** @@ -979,7 +974,7 @@ Quick reference for agent selection: | **PM** | ๐Ÿ“‹ | 2 (Planning) | prd, tech-spec, epics-stories | Planning, requirements docs | | **UX Designer** | ๐ŸŽจ | 2 (Planning) | create-ux-design, validate-design | UX-heavy projects, design | | **Architect** | ๐Ÿ—๏ธ | 3 (Solutioning) | architecture, implementation-readiness | Technical design, architecture | -| **SM** | ๐Ÿƒ | 4 (Implementation) | sprint-planning, create-story, story-context | Story management, sprint coordination | +| **SM** | ๐Ÿƒ | 4 (Implementation) | sprint-planning, create-story | Story management, sprint coordination | | **DEV** | ๐Ÿ’ป | 4 (Implementation) | develop-story, code-review | Implementation, coding | | **TEA** | ๐Ÿงช | All Phases | framework, atdd, automate, trace, ci | Testing, quality assurance | | **Paige (Tech Writer)** | ๐Ÿ“š | All Phases | document-project, diagrams, validation | Documentation, diagrams | diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md index 5ab15be0..5aa808ee 100644 --- a/src/modules/bmm/docs/brownfield-guide.md +++ b/src/modules/bmm/docs/brownfield-guide.md @@ -250,8 +250,8 @@ Without AI-optimized documentation, workflows fail: - **tech-spec** (Quick Flow) can't auto-detect stack/patterns โ†’ Makes wrong assumptions - **PRD** (BMad Method) can't reference existing code โ†’ Designs incompatible features -- **architecture** can't build on existing structure โ†’ Suggests conflicting patterns -- **story-context** can't inject existing patterns โ†’ Dev agent rewrites working code +- **create-architecture** can't build on existing structure โ†’ Suggests conflicting patterns +- **create-story** can't provide existing pattern context โ†’ Stories lack integration guidance - **dev-story** invents implementations โ†’ Breaks existing integrations ### Key Principle @@ -370,7 +370,7 @@ When workflow-init asks about your work: ### 4. Respect Existing Patterns -Tech-spec and story-context will detect conventions. Follow them unless explicitly modernizing. +Tech-spec and create-story workflows will detect conventions from existing documentation. Follow them unless explicitly modernizing. ### 5. Plan Integration Points Explicitly @@ -446,7 +446,7 @@ Document in tech-spec/architecture: - Analyzes existing auth patterns - Confirms conventions - Creates tech-spec.md + epic + 3-5 stories -3. **Implement:** Load SM โ†’ `sprint-planning` โ†’ `create-story` โ†’ `story-context` +3. **Implement:** Load SM โ†’ `sprint-planning` โ†’ `create-story` Load DEV โ†’ `dev-story` for each story 4. **Review:** Load DEV โ†’ `code-review` @@ -512,12 +512,9 @@ Document in tech-spec/architecture: - `product-brief` - Strategic document 3. **Plan:** Load PM โ†’ `prd` (comprehensive FRs/NFRs) 4. **Solution:** - - `create-architecture` - Full system architecture - - `integration-planning` - Phased migration strategy - - `create-architecture` - Multi-tenancy architecture - - `validate-architecture` - External review + - `create-architecture` - Full system architecture including multi-tenancy design - `create-epics-and-stories` - Create epics and stories - - `implementation-readiness` - Executive approval + - `implementation-readiness` - Final validation before implementation 5. **Implement:** Phased sprint-based (50+ stories) **Time:** 3-6 months @@ -564,7 +561,7 @@ Document in tech-spec/architecture: **Solution:** 1. Ensure `document-project` captured existing architecture -2. Check `story-context` - should document integration points +2. Check story files created by `create-story` - should include integration context 3. In tech-spec/architecture - explicitly document: - Which existing modules to modify - What APIs/services to integrate with @@ -597,7 +594,7 @@ Document in tech-spec/architecture: 1. Check convention detection (Quick Spec Flow should detect patterns) 2. Review documentation - ensure `document-project` captured patterns -3. Use `story-context` - injects pattern guidance +3. Use `create-story` workflow - it loads context from existing documentation 4. Add to code-review checklist: pattern adherence, convention consistency 5. Run retrospective to identify deviations early @@ -626,9 +623,9 @@ prd # BMad Method/Enterprise tracks # Phase 3: Solutioning (BMad Method/Enterprise) # Architect agent: -architecture # Create/extend architecture +create-architecture # Create/extend architecture create-epics-and-stories # Create epics and stories (after architecture) -implementation-readiness # Final validation +implementation-readiness # Final validation # Phase 4: Implementation (All Tracks) # SM agent: @@ -728,6 +725,7 @@ flowchart TD - **[Quick Start Guide](./quick-start.md)** - Getting started with BMM - **[Glossary](./glossary.md)** - Key terminology - **[FAQ](./faq.md)** - Common questions +- **[Troubleshooting](./troubleshooting.md)** - Problem resolution - **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference --- @@ -742,7 +740,7 @@ flowchart TD **Documentation:** -- [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy +- **[Test Architect Guide](./test-architecture.md)** - Comprehensive testing strategy - [BMM Module README](../README.md) - Complete module and workflow reference --- diff --git a/src/modules/bmm/docs/faq.md b/src/modules/bmm/docs/faq.md index 7d041b87..7766137e 100644 --- a/src/modules/bmm/docs/faq.md +++ b/src/modules/bmm/docs/faq.md @@ -147,7 +147,7 @@ If status file exists, use workflow-status. If not, use workflow-init. ### Q: How do I know when Phase 3 is complete and I can start Phase 4? -**A:** For Level 3-4, run the implementation-readiness workflow. It validates that PRD (FRs/NFRs), architecture, epics+stories, and UX (if applicable) are cohesive before implementation. Pass the gate check = ready for Phase 4. +**A:** For Level 3-4, run the implementation-readiness workflow. It validates PRD + Architecture + Epics + UX (optional) are aligned before implementation. Pass the gate check = ready for Phase 4. ### Q: Can I run workflows in parallel or do they have to be sequential? @@ -193,15 +193,9 @@ PRDs are for Level 2-4 projects with multiple features requiring product-level c ## Implementation -### Q: Do I need story-context for every story? +### Q: Does create-story include implementation context? -**A:** Technically no, but it's recommended. story-context provides implementation-specific guidance, references existing patterns, and injects expertise. Skip it only if: - -- Very simple story (self-explanatory) -- You're already expert in the area -- Time is extremely limited - -For Level 0-1 using tech-spec, story-context is less critical because tech-spec is already comprehensive. +**A:** Yes! The create-story workflow generates story files that include implementation-specific guidance, references existing patterns from your documentation, and provides technical context. The workflow loads your architecture, PRD, and existing project documentation to create comprehensive stories. For Quick Flow projects using tech-spec, the tech-spec itself is already comprehensive, so stories can be simpler. ### Q: How do I mark a story as done? @@ -538,7 +532,7 @@ Trust your expertise - BMM supports your decisions. ### Q: How do I report a bug or request a feature? -**A:** Open a GitHub issue at: https://github.com/bmad-code-org/BMAD-METHOD/issues +**A:** Open a GitHub issue at: Please include: diff --git a/src/modules/bmm/docs/glossary.md b/src/modules/bmm/docs/glossary.md index 813cdf72..f2a6a6c7 100644 --- a/src/modules/bmm/docs/glossary.md +++ b/src/modules/bmm/docs/glossary.md @@ -95,6 +95,10 @@ Game development equivalent of PRD, created by Game Designer agent for game proj ## Workflow and Phases +### Phase 0: Documentation (Prerequisite) + +**Conditional phase for brownfield projects.** Creates comprehensive codebase documentation before planning. Only required if existing documentation is insufficient for AI agents. + ### Phase 1: Analysis (Optional) Discovery and research phase including brainstorming, research workflows, and product brief creation. Optional for Quick Flow, recommended for BMad Method, required for Enterprise Method. @@ -187,7 +191,7 @@ backlog โ†’ drafted โ†’ ready-for-dev โ†’ in-progress โ†’ review โ†’ done - **backlog** - Story exists in epic but not yet drafted - **drafted** - Story file created by SM via create-story -- **ready-for-dev** - Story has context, ready for DEV via story-context +- **ready-for-dev** - Story drafted and reviewed, ready for DEV - **in-progress** - DEV is implementing via dev-story - **review** - Implementation complete, awaiting code-review - **done** - Completed with DoD met @@ -238,7 +242,7 @@ Markdown file containing story details: description, acceptance criteria, techni ### Story Context -Technical guidance document created via story-context workflow that provides implementation-specific context, references existing patterns, suggests approaches, and injects expertise for the specific story. +Implementation guidance embedded within story files during the create-story workflow. Provides implementation-specific context, references existing patterns, suggests approaches, and helps maintain consistency with established codebase conventions. ### Sprint Planning @@ -246,7 +250,7 @@ Workflow that initializes Phase 4 implementation by creating sprint-status.yaml, ### Gate Check -Validation workflow (implementation-readiness) run before Phase 4 to ensure PRD, architecture, and UX documents are cohesive with no gaps or contradictions. Required for BMad Method and Enterprise Method tracks. +Validation workflow (implementation-readiness) run before Phase 4 to ensure PRD + Architecture + Epics + UX (optional) are aligned with no gaps or contradictions. Required for BMad Method and Enterprise Method tracks. ### DoD (Definition of Done) diff --git a/src/modules/bmm/docs/images/README.md b/src/modules/bmm/docs/images/README.md new file mode 100644 index 00000000..331fdd53 --- /dev/null +++ b/src/modules/bmm/docs/images/README.md @@ -0,0 +1,37 @@ +# Workflow Diagram Maintenance + +## Regenerating SVG from Excalidraw + +When you edit `workflow-method-greenfield.excalidraw`, regenerate the SVG: + +1. Open +2. Load the `.excalidraw` file +3. Click menu (โ˜ฐ) โ†’ Export image โ†’ SVG +4. **Set "Scale" to 1x** (default is 2x) +5. Click "Export" +6. Save as `workflow-method-greenfield.svg` +7. **Validate the changes** (see below) +8. Commit both files together + +**Important:** + +- Always use **1x scale** to maintain consistent dimensions +- Automated export tools (`excalidraw-to-svg`) are broken - use manual export only + +## Visual Validation + +After regenerating the SVG, validate that it renders correctly: + +```bash +./tools/validate-svg-changes.sh src/modules/bmm/docs/images/workflow-method-greenfield.svg +``` + +This script: + +- Checks for required dependencies (Playwright, ImageMagick) +- Installs Playwright locally if needed (no package.json pollution) +- Renders old vs new SVG using browser-accurate rendering +- Compares pixel-by-pixel and generates a diff image +- Outputs a prompt for AI visual analysis (paste into Gemini/Claude) + +**Threshold**: <0.01% difference is acceptable (anti-aliasing variations) diff --git a/src/modules/bmm/docs/images/workflow-method-greenfield.excalidraw b/src/modules/bmm/docs/images/workflow-method-greenfield.excalidraw index de98315c..f4d2411f 100644 --- a/src/modules/bmm/docs/images/workflow-method-greenfield.excalidraw +++ b/src/modules/bmm/docs/images/workflow-method-greenfield.excalidraw @@ -1036,10 +1036,6 @@ "type": "arrow", "id": "arrow-discovery-no" }, - { - "type": "arrow", - "id": "arrow-prd-validate" - }, { "id": "arrow-phase1-to-phase2", "type": "arrow" @@ -1055,17 +1051,21 @@ { "id": "arrow-has-ui-no", "type": "arrow" + }, + { + "id": "arrow-prd-hasui", + "type": "arrow" } ], "locked": false, - "version": 107, - "versionNonce": 930129274, + "version": 108, + "versionNonce": 930129275, "index": "aN", "isDeleted": false, "strokeStyle": "solid", "seed": 1, "frameId": null, - "updated": 1764191563350, + "updated": 1764952855000, "link": null }, { @@ -1107,197 +1107,6 @@ "autoResize": true, "lineHeight": 1.25 }, - { - "id": "arrow-prd-validate", - "type": "arrow", - "x": 439.4640518625828, - "y": 331.0450590268819, - "width": 0.17283039375342923, - "height": 28.50332681186643, - "angle": 0, - "strokeColor": "#1976d2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "roughness": 0, - "opacity": 100, - "groupIds": [], - "startBinding": { - "elementId": "proc-prd", - "focus": 0, - "gap": 1 - }, - "endBinding": { - "elementId": "proc-validate-prd", - "focus": 0, - "gap": 1 - }, - "points": [ - [ - 0, - 0 - ], - [ - 0.17283039375342923, - 28.50332681186643 - ] - ], - "lastCommittedPoint": null, - "version": 102, - "versionNonce": 1274591910, - "index": "aP", - "isDeleted": false, - "strokeStyle": "solid", - "seed": 1, - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1764191023838, - "link": null, - "locked": false, - "startArrowhead": null, - "endArrowhead": "arrow" - }, - { - "id": "proc-validate-prd", - "type": "rectangle", - "x": 360, - "y": 360, - "width": 160, - "height": 80, - "angle": 0, - "strokeColor": "#43a047", - "backgroundColor": "#c8e6c9", - "fillStyle": "solid", - "strokeWidth": 2, - "roughness": 0, - "opacity": 100, - "roundness": { - "type": 3, - "value": 8 - }, - "groupIds": [ - "proc-validate-prd-group" - ], - "boundElements": [ - { - "type": "text", - "id": "proc-validate-prd-text" - }, - { - "type": "arrow", - "id": "arrow-prd-validate" - }, - { - "type": "arrow", - "id": "arrow-validate-prd-hasui" - }, - { - "id": "jv0rnlK2D9JKIGTO7pUtT", - "type": "arrow" - } - ], - "locked": false, - "version": 3, - "versionNonce": 894806650, - "index": "aQ", - "isDeleted": false, - "strokeStyle": "solid", - "seed": 1, - "frameId": null, - "updated": 1764191341774, - "link": null - }, - { - "id": "proc-validate-prd-text", - "type": "text", - "x": 370, - "y": 375, - "width": 140, - "height": 50, - "angle": 0, - "strokeColor": "#1e1e1e", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "roughness": 0, - "opacity": 100, - "groupIds": [ - "proc-validate-prd-group" - ], - "fontSize": 14, - "fontFamily": 1, - "text": "Validate PRD\n<>", - "textAlign": "center", - "verticalAlign": "middle", - "containerId": "proc-validate-prd", - "locked": false, - "version": 2, - "versionNonce": 944332155, - "index": "aR", - "isDeleted": false, - "strokeStyle": "solid", - "seed": 1, - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1763522171080, - "link": null, - "originalText": "Validate PRD\n<>", - "autoResize": true, - "lineHeight": 1.7857142857142858 - }, - { - "id": "arrow-validate-prd-hasui", - "type": "arrow", - "x": 440, - "y": 440, - "width": 0, - "height": 30, - "angle": 0, - "strokeColor": "#1976d2", - "backgroundColor": "transparent", - "fillStyle": "solid", - "strokeWidth": 2, - "roughness": 0, - "opacity": 100, - "groupIds": [], - "startBinding": { - "elementId": "proc-validate-prd", - "focus": 0, - "gap": 1 - }, - "endBinding": { - "elementId": "decision-has-ui", - "focus": 0, - "gap": 1 - }, - "points": [ - [ - 0, - 0 - ], - [ - 0, - 30 - ] - ], - "lastCommittedPoint": null, - "version": 2, - "versionNonce": 1369541557, - "index": "aS", - "isDeleted": false, - "strokeStyle": "solid", - "seed": 1, - "frameId": null, - "roundness": null, - "boundElements": [], - "updated": 1763522171080, - "link": null, - "locked": false, - "startArrowhead": null, - "endArrowhead": "arrow" - }, { "id": "decision-has-ui", "type": "diamond", @@ -1322,7 +1131,7 @@ }, { "type": "arrow", - "id": "arrow-validate-prd-hasui" + "id": "arrow-prd-hasui" }, { "type": "arrow", @@ -1334,15 +1143,15 @@ } ], "locked": false, - "version": 2, - "versionNonce": 1003877915, + "version": 3, + "versionNonce": 1003877916, "index": "aT", "isDeleted": false, "strokeStyle": "solid", "seed": 1, "frameId": null, "roundness": null, - "updated": 1763522171080, + "updated": 1764952855000, "link": null }, { @@ -5162,6 +4971,57 @@ "startArrowhead": null, "endArrowhead": "arrow", "elbowed": false + }, + { + "id": "arrow-prd-hasui", + "type": "arrow", + "x": 440, + "y": 330, + "width": 0, + "height": 140, + "angle": 0, + "strokeColor": "#1976d2", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "roughness": 0, + "opacity": 100, + "groupIds": [], + "startBinding": { + "elementId": "proc-prd", + "focus": 0, + "gap": 1 + }, + "endBinding": { + "elementId": "decision-has-ui", + "focus": 0, + "gap": 1 + }, + "points": [ + [ + 0, + 0 + ], + [ + 0, + 140 + ] + ], + "lastCommittedPoint": null, + "version": 1, + "versionNonce": 1, + "index": "b1J", + "isDeleted": false, + "strokeStyle": "solid", + "seed": 1, + "frameId": null, + "roundness": null, + "boundElements": [], + "updated": 1764952855000, + "link": null, + "locked": false, + "startArrowhead": null, + "endArrowhead": "arrow" } ], "appState": { diff --git a/src/modules/bmm/docs/images/workflow-method-greenfield.svg b/src/modules/bmm/docs/images/workflow-method-greenfield.svg index 1b7dd76c..6522b695 100644 --- a/src/modules/bmm/docs/images/workflow-method-greenfield.svg +++ b/src/modules/bmm/docs/images/workflow-method-greenfield.svg @@ -1,2 +1,4 @@ + + BMad Method Workflow - Standard GreenfieldStartPHASE 1Discovery(Optional)IncludeDiscovery?YesBrainstorm<<optional>>Research<<optional>>Product Brief<<optional>>NoPHASE 2Planning (Required)PRDValidate PRD<<optional>>Has UI?YesCreate UXNoPHASE 3Solutioning (Required)ArchitectureEpics/StoriesTest Design<<optional>>Validate Arch<<optional>>ImplementationReadinessPHASE 4Implementation (Required)Sprint PlanSTORY LOOPCreate StoryValidate Story<<optional>>Develop StoryCode ReviewPass?FailPassCode Review<<use differentLLM>>More Storiesin Epic?YesNoRetrospectiveMore Epics?YesNoEndAgent LegendAnalystPMUX DesignerArchitectTEASMDEVDecision \ No newline at end of file + @font-face { font-family: Virgil; src: url(data:font/woff2;base64,d09GMgABAAAAACK8AAsAAAAANtgAACJuAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAABmAAgRwRCArjCMkaC3QAATYCJAOBZAQgBYMcByAbtyhRlM9eleyrA97wqeEaW8W+DpLiGbovD3boP+FkhCSzw/Nz6/3/9//WbM2gtzGiNqKFRVNjMCJHtqSFWNiEilGIdVi0wQVWXBh5iRmnWBf0v0BBQPjnOdzf91rbxgLZFHa8aBIMwKi4tHiJpGP9L5p9/z86zYdkg9X2b7XPKW360yat0voKCB++IpBb7lJsX0+vQvxvTvu3t9b2SnLswkB4ADPtA+C0Oe/kMyy2zbazlTFUMAQKA4F20naYZOmDRUuX2JxN683RZnYlzXskRoG7+8dytXT238VCl62o4N1/qJtWqsqjnlCaQxmEqZfW7xW1OhKJ0ggpGI/RaNA2MjYireOcvF3LDfxF0okYvnl7wkvbAjjroE6AAuAVnAoAiAYFTARgFfDjq+EEDcPmkQgAQEDJtHiNBsiAEy1I4/8rAFrxQY0AAKuJZhh6wv/S9jKmCCoCOxJBxx4cHQYH6G9AE67ijje+BBBBFHpgBGkgF5SCJtAyM9OAyC2LlM6ORA5igKk3H5T/VDNT7rntlpt+8qMrLrnolJMm/QAgYA70D4QodE3WEWoefWdm5QHsIBRcUXbCDv1fWBFWYoYTqyKrgQwFu68R4Ojqlm2VmxoSMssqlSNnc+OUDmtiq7PzIwstYu9Q54qE+KRZ1VmKcLZfipSXnqqytosTGjW2Th5sLytvTb4xzBiTMYa2enH8GYYWCAbPCnbvBky5EomF917+VvabUyLQ6lfkgZc995k0n5q7frEUJ40gPTr+KvwalRNU7e8nm0mqcejzz2HAAsY0ZffUU8VXjPQnKY4xDkM80rN5iEYkgcGAzLJjfUN+dF5WztMXCjrJbZ7IeZo2eN5bQKcDAGDbtk2oIv8/KwkMNNWj7e4i0hiVAwIOgyLKed5qiihbNaqsbEzmtMRanchK0boWZVUwCDp6BsAYW2Y2s8FeM9bfuzj56qbRhduNx1jmZQxDq2t1MYak8HEe5HnIjt8MALcDsJO1mnqztsn6wltjkx0Lx++Qph7ov8i64zgOrRLcGP0Zx/wQWtzqFcfinlelyLaJWacsZQwdQkKrNfX521vHijm+P8YNhedCtvcE4FRgl4S36oXfHLdA96J7o1H22mdPC03ybb9WVweVY5PSSM+4Dq7rYnzjutGf6TFih7JsS7OYZNymjsyFKddH02JDAxZofQU8D4u8VSEi75Pt23U1lr+vhajuHDHt+nX61G9t9Cc5Ny1c1oF7ddsxMgtPibeTNzB5mljSM00RekYeaGxM2Z/QQj4Pjg9EUT0j1PO3jPgZXDhNG+IunqfQ3YDOrR9bvxS2hGzbrw5uv8W05efXtCgutMTTn4JqTLVauc+JUWv0wv5p0el0oOPTwlOwAzbboyjyF9JqU89uZFXPNmKz/XtpkNazPN3hH5bA3h7AE1BqeerYVb/HcvvqVVO2ySTHSHd1wXVYcWFlhSuIdGhZFkYGMD8yEgWbngtwXwkne7S+CK58HLNETJ95Iz4aA4cpP+reS33yX1ouSiH8HNO3EwXC/qqkVmPp0GZRJXedazRY4ntv40vc9M/wsg+pRSVIHfXI6t9vSENEXNJhSG/6q93FdfELAc3MxffjybYZpL4nquo8JNVWdwU5SnsuNOU6dSlMIb4cEK6SaYtZ9iHlEUOoF4EaBB22AZ4NEWuZc0jfxbgEQ/BnJd7dETPhxPEYvVPhdy7uqacIbflCjUs5Q33a6wXvyyiQxt0KN/9sOk0e3A55bKcD4Zq14z//TOxJ8/vOXKt8nbL6fCkO3g2SIM4TvWETyXVxTq6rLxyTjqPGsq0WakwttZzlOKZzqsfxY8r3x4hLX3Xb+0IRBIQOIAD4DnQEVyLwFIdSJ2UtQA7xtp6nYaTdsEANANBP5wFzAZRU02M8fYqTqCV6ADDjabhzJwwD8mdNAGyRjEMHPy6/2pRzdxXjMdJY7+voArSYPwAGmjC/E4lpjf9CtNq6l89UTQAOlqfVDiRvd3wmWklDekxIpX/zKa4rf0A2NdE9QtFyoC3xeS/XvG3QVrkfT5wJ/eEZl3O7qZXP9z5O7M6T4AXs8emV5JPr6raNMakFIdunZQ7HYYgRYYKrZHg3U91MecClDegoDWyfhM+ADmMerLxts2NzdTZep1R3+vQZXqdyXY1lS5XbOVfIlwB4IyUspO9nbk4cZdqKrG3n5ieEDnxKMCVbaXDAVa8BwBgkV8SIc8ccLaTZFklTAw00ReoZup5zmdRR7lOHU44dx8JptalDEDC2vKyptII3QVNM6fMpWHFTwsLtRIdWaGF0wZYVfAnaLJ+8be/A7OT/XuheNCL1rdnVU60OpClrNhnQTaRTPr3MAdwmYGmO9FwbQye0QoyhZSlRlk6U+LcRBglDEgLYuATD8zuLtHWF9DIOHoh9PtRnjTn5iOW2NIv6EkjjqptCC3ePCMySnq9QvU91iLsL+AUSnC+lGuJNjB0FIlJvrVW4Rrmt/irndeKQwRxbXYSWh5eSaVzF6I3Qks8cK67KtqRy3VzLuZt6XhkEA3Bdxaf7HM7kbRbpKhAjDNhwVyBzm7p/nlc1ymrrP6ROZjDJ3HYUm0pHBwVU4WI47dGg6pdBAnNFWB7O97uFEc5cik4mz2+n2uK6eHOhqbeho9hgR98DcJnbhqlrizUZm4bqkjKIKtRMd7RnuTCd3+Lp2YVr5asLevryCZwpcXvZHbXVhFgQ5hiRM6ZcQwt9RBatQkUadgOAV6ll8lvPnDOLx5kRvl7R+CtctoPJpoLuEnAu2AGHaISrJNNFJ2vlvW5KNF2AZbLz4VgUH4gxTZ1yab+k74/HucmV7B1ZaKosNrEnJnhpKtvLzowgrZo+3SxgYfsTncjaRcMIEmTRK5qjxVt6jKaRACdWH49d/M93lucq06yKNAoCsBx8Ocp3E9zw7FSfn78lXmqy82e5XjOIhPFhgK3zd1JktrdWeRxTHYY5LSso7zbQYxgY1MtpNdCSgazMMNonJNMR5AH4xJ4kSaSoSkm5XqccY9zU4VLj6aDd1dTp/UyFNOVxPEXoHAqFo6SFIVuqeWuzgJsAq0u64MehtcpeAmjqQtheWCzlrzcyCKWH2/NTMF+lrbYtR90Q5zoosAcefa6LhgIAeTsyaMaImVIY5G+R8ifZVqmmqkozcXE94945gAlGrCneZfJVumhnRW9pSclWmnqOeDasXh2ZXxB95gWHdOa89ozr/Srd77M82BEh4PcI+X6LSDLkOrCAQGT7hEpERItzHHXjvXbFhHrfGA4OiFFumzLShdH+TVxR1+8/Mq87k5jejEQwK9uMhIdHyQnc72IE6MCMUNSzGSTjRVseY8zjtiKlMWjNnJt2qJCwrxGyUhDZR5t4dDlJ5YUqzrGkrTJFlrVTh++tl/gUcHEDNf496I/s1Yoi3eBIjQ7k9QC9iPSCKATWlXbAfYxdC5M7YwDnFYvsiPTG4jcjpHN3d1dzsi0oPOWTjePDyuD2exdlye12C6NDGajAJucIjcDudfKi4eHTpe2FI+g9Skd8GabhuF6JW5/zl1OCRXBn7NnfR5q2Ks1jhdqmuL1OixzuYvRcDKuKKGdcj1Dp4s/yzQTngoWwiBdGv0VaTHm/Fvx8YkS11Zvmuius8I+tpr4dawSXEo1TvB/fp5ufpWzhaO9juBMMsl6CrMqKxhiGFy+imy32H+5R1INOXrAqkZAz/QwPqRSqkdS0t+kE6cw8SRqnr+lSCriMWMOoJAiJbL035dkdJqXbDezge3VBFppKR88q/SQlWADUyk4SOFlwGDe7GU3dVUkf8uRagvvpjpgZyLd2kf5AeIwBfXoDwCzIhyuk5fPUYC5FuNzSEuRc9/DtaRrSd6SOekb5e/ukw2E6v2RyIpv0pF9z6ECuCaMQZkyxqIDXpEWiRCnLtxzShf3kcJPuwJPMlV0/G6LhlfsZPuP1u/gOepDY0SNSt34mIaLGLEqYEk1vFYuGq8gzT14cV0oitURwfZqeGevnXN3kmYOm1TY4486IZhPnSoR093Ec53jiTCHhJgN98gBmgCwIHsxHDTHn8Kg8vBB0Tc6u/v9IgXRB4COo+D/gqtdsYuQmLzW+4teqz7HDF2cnxm6mOhF1+5Ju5OaFswvZearpEJDaIL9lr6lGA4EXfmztCnRYTURONU6I+hTaTGCqcYF0988eM0Ke/fkpIKkkz/tJso91KhcOL8WvKff7lB3nIuJw00o1gSOiqeQAgSb44ZNQpBYZE1WJqUZ5MqG7SCcfNH1uK0twT7vxfW2rgpv9x0XmuObbEQkhlQYYAgSMYJzVtddftUkbDR+jzz+diXcTwRXPXPeFbH6jgkhRk225gPuNyE8NrlepQsJWWbje7xN4spMe+8GFmAkq6n9ktann+Uv0RIthYMvarBhEkpdpMd/N3fRPytZIu4at6uD2e7tIv9FshMfAXqBrUVhzFATQ2dPzxmoKPZfpfA2OrHCdXt/gcBjeR3qO66RmNinU80n5Fsq4dHjRAiReyqs7bBAEAK6cg739MpkP+eD8NW+5qByTRwzxczUgtEQmtekPN/UZ6ataChOsLeTux6Wv5lNDmmzWsec7YqWZEidGWFMGoHcuVWTYSj23DNPOk89hoC2KdKVlGkHoz902uqIRWyHOp8TxflI4fQeXiyKyc2SPfzx71HvTbLX8dZXVmI5yn/IQzSi5q+SX6UyV7HJhjnSO+/3t+jaV9SrXHQdxV+jB2PS6uKLtqJDHuIRdRRyXpQWKGF6AzyfKJuODrZlQNIvlLQojdDLHVlksmh4My/1pRCzpM2ypPtNcEr7SRZPbMsYfHeI4pKPjHh572uJsT3wWBk0hzpq1thFL/+eY2/TnegQ2wy3eEVNbl+YAaTzSIb+8kD/NcEynzsnV9uwVK6kjmeD70zK4bOV/XPv8dNZY0bM0LBOvzmHi5YDjCt1/vssY4WVBEBti0v3kzrPNgZt6RXnsUF1qg6DJfSZpik/OJios0z9P/GLvBPAuYHibPeqbwoX1cwZMfVfoDPAV0HO/jXGo+F24zXcIQmWswLRIkGzXQdVp5AuRm443uV0nifgPiBVgh3m69zz2J7TzyTXLzl15p9Omitq6uRbXzguqvxibB8D4oo0v7oyt+99B3rwt1sxIbYcTVzNNhFtj3kZd+v4N7wvblsfjxvxrJbVNyq2ARFGsmMx25Vsnv6Gw33MTWwIhG9JwLgmmWOEqaNRspFjfgqOwXkAqaNIBBhldN39vwpdiow5Ia8QcksJlCL+12bo2uXJTewUL4kIukL+TSS4LmHDxzRW8MCU7hf5FBI3UsnnCRHfFtaLWm23rzyroUUkOJYcjnPD5664y5lYbIxKxnGuXNh8eha5xXPsj3vyjWombShlnOdMhhHKOyxf+AqYRDPPVdOS1ZwjeJ7ANsljnIxfivw8JJ/beGY7hH8igFuSq8zYbTrr+O2Lkyjif63KIU3Fsdh7fsCZy1fVrPpZni97tZ+TMwhUDTUTyrgHcUi1WkQ1aA3VpT3KWBpJxqkTV1gr8zr+n1hV+Vk+BBa/PPYhjXyncaeATaPAVZYpafaB7cMUDU/o0Ot0XuK6Y1eTh+wkfCNE3QWzn3LsMDY9BZSaOcjjefbDAvWPxkX1WOyj0v5nQLT9ayCpbjpMnkMylAnUmnYAiXjgAWoPTHfV2c9ON9BvvdarEY3cCrycPPNX2UfZ+X6oOufzhLetYAQ9llbE2A8uuIMvnFGHj1rMXUx1p44ytgsUgPQxlLKb2nex9Hx94j0j9VRdggm+aVf+8SyvDRI35eXSYPF7TXlfU2bRppV1RQYg59l6C8slbp5/r+l+W9oBaPuniEcGSi0sEDYwUfdNBjklFoXr1jfXQYQgj8HRLxwSU2VS3+RrN53I05MqJEydyVBNYASpw8L+rrK8nO45m17KeTMwLSyqxaqzeSGH/Dp6lkjaYoXWqDu4mNpnyAPM7UVCwj75fyDJez0752ND3Ybu3WvmFnQm1Q9U1bQh7AmAhg7WV0AGDIDjPZhMNZnadXuYCkaFvHkv8Yxl6lJDE2nxxD4069mK2nnL1XCtQwliNk6L+9miBxAek+HxxVv4mSasB/0VwiatakFO0STKyGmhwVQWOnBskhEn4q+uM0hv1h/+QR0NGvzpqSzpL6zhdkYSpEh21IfSJ6Z9DkrYcq1EpUCM1I0aF4dWozLmhJuZSryJqNpGsg+9aoE8L4R6T5IyJH7WMo2nICNsvsmMXIIyF3W6vRX4curKI3dKkRQTELXz6ZpD9QJEutyuux2pQDG6k4+AHzurPVQtc512Ix1HgH2xKlAw6gH5G1SVJK7OuMkiZL998VKdvjDMGyKvsegAyxNYhLJrG3MJvTmiLtkYilrhdPaYwb+eUAnPBjWF40FhrGhnBUEbD1/RikgYm8QintMQzEBAOeEbX4dDfbcn9n5VOHWJaR4JZY9IIZcdz7mr/unbXcva+3LGAscpK1KShviMct9d8a9xBKor0Y2rMeDRBakjJX5pRZYdXBX0LySOhdJyCpa8yiImgBEtHWQQljoBCLCwHLkBz/O+jMpWYOE7XXuU82z/ac+rwUpudgeINvRt/QqOCz++SugxV4zS83Uru6H+FeDQaw8P5cJG7F5Jtp7IaJA1OKk//WBx0zzQfd7uBF2/bT5pu2SvdL12ow8ljmTAxiMwYjEUGGUxQ0IChcUiS1Y2nka37OtdYXbVcTOtvq0x4yZ4x39qNrfIDypP/GLAf9jgbGk14p2sjVvz1vDkp4bfODB/bl2RcSv1Jk78Gbt90JSq2gGhhWYhwpb1QhSfzg/jSl08stNp7S51dEAsD/8iMZV/G2x7av2hXDBvLAkXWwpXsfeKlmMaVAkfx5PV+VjvRT7aFhTnyeVBDRVCsOi+k0jWjPX1gPKr56Qup6duIF8rxXZk2u/xYjbUI5Ymg11PlIUtUMVwLxGlBuyfWuunJDye2mO0dvq2BJB3LzfiEJMZ6pg5/dofhSCiNUSrWGwhuX4wonHv+HQNSgoLvFGir6IqGxCbkTNZHlQg57WiJp7WxmS7IjEz1JadBJngSYe2mf+RX1BFoRK2zA6SCqMeYBAUHfPGxm4foeL4ZpUZRcAGfe+A8hMAp1bZQPI2otnWPZ80edsLaiUYXxAJeFvOTvPczjqutanWPaAQVqcCKMRobQAjwzF0QwwH0ac3Qdq++JOkvnX9Z6/8w3Sx2GX6LsRAbP4SupCOQCmp3elFDkGE4+IKxgsqAuk8FDuDdVuTeq2OjEkSCcvIcNwCPffBcsBEpI5rgQXlC8ONXeokoPbCZY5B6ZnsRsBzoWa83mdVPNex9mfrBPcuORUyruucvPLOM1LbTtNI0DzBKRfOJSLkPTFxKAwnSAVbuJm988mxA74AtutLMqvpUgTzINwzqbXPI5ng1h1eDE84XkVt+Fs7CDS19cdHCRAJHlalk9Xz/gIy/qe04B88VuUSeR+r2OcpSe7FUbg0X4GZdffTd6qNEGQSG2vHlwTu4OFQbDl19cNlg/AT0+ijrdLgZJvj2LPM846g0lOuNnxZBWkMAZzZlbS7nfgynUTxv42yLWHEhnaX/gZkayVlDWPliatYamKNF0FgCPlQICeetOj5rS073fbH66okna0Q/CeoTlsIrrnMn0oli1CAcQW3nvwKea3tdXnO7B5TFbetJ49phSpWPDPIhcFIhBAJQA7LPEeiKsmK9TY4xmo6qIFaW69Jah2AEjlLBxS1tk+/FNLH6p9ypZp70J1vVVc+UuM4WG0mNuBza+03yYKwXZ1tULHD7NdiuiXkMJ7odbwkJCbShjpm3mrGtWCUrT7TWU5PNGYkGKZrPDy5aF1QrRKv9rWPCecAphUVFd8GgKcsbUrR9Jdlq8cx6xgPZ9OlG3hJARpMQcYQh6vbtx8mnAoV/AUoxD4ivRyLYhxvN8jc491z/saJo1Cg0oguF6d5mbeBdO6uDI1+ed/iR7ynQhVjq0kijdpaqAzAFORW1oXR3dQP9ZuBvj0vMxvoYzVeW89n/e52vhXCcfvmf2ucy4DvP4zcvfwWTeoNCqsUNstC4QGcB25XFnCAl4TMIZwBpQfeZEvdKoYEPYhlkID7v7E1US82VrnMirG5vG6w1SqA5yLG/VrZpQV33V8XJ9XlLZWS0cymcCRlZJZLDcwPGYu1I2Mkt0Y71nYFRcUuyp+URlYWVUD0cJ9g3kAGiY2iZEmMSiIfm1zrMtAs5VhH2X/PcexN5mXgZWrgE2VlDR2tIOmjKgPPENM6OBGgTvaavhrKHwkJlD2Toc3wK+IVAIm7ehVgvEEzQzyqU/oVQHMrCXQThW8SlRoy4B/mveDP5sVHKUXz+nYgnGR0NS12qnl12FzztoQRVNRcV/eG+tl84z8CD4z1YDHgS2eiOq13uzqeZfSxebmsbVk8XL6cphxt5Yy52p+Ks7X5gpVuwFYDXXfjZMvqt5iwkGBAUljkk/3SxpDl30iGWa9BTH8JjC/7++wRs9goUJ4nME5nHDiJG2M3/v9iCZWP65pV+LV3DomXNti8SgiXgOZSAtCAWLiXTOvxxjjkliRdMqsZyYn1UiKmEzoqulqyNWjNiwz50OSWPao3p3BwoJvzkzU3y1kMLykXxdXjg2/vgwOc5zI7jcEpCcire+nVs0K+TTn2s60txyh29lAQxW4/7m6zRhECZ+e/Xv72cascvvyFIA+sYzowpYV8gidKgNFHtbd2IMSJBE5Q03z076P1imnWCpGrzz4IL/K/IaLJ/+Qx147TzTyE79N6HZKL8Ohb8OoBbvWzMX+SW5egoZMqhfUscBBOpJauZuJYtn6RmaNTV56/tYJ0ti5PBBcW/MBhCJdjr8M05wy/BnGgXLkNtRUZIub18KtGY5P597VnaElWEn0LuGjfTLe0MPNB68fw3A0VsH6RhIodVMn6dQq4sBb1rG3bpC1Q7H8itxavL7sSbOR6Qh/q4V4GgS2cVj2eUbg658tscaWFWwK6AhoIvnfQB2C0c2m5NaRfnhSuki5OLPDg2IsZtaG6hDmnGBxhw/j2pIzU4YHWpWtvOzXF9KjvvXFQVdX4SGX4UGrDnWe27hhsVMUiu5+6PETsrmc38wgtoxLMP+b9UsAy5jv99BegBT4xf1BpHkffDpFGTxHm00B8Ya8aceZ/KgtXbuRDSAnEJlm3U+e34iGNvTbbR3jwrrApzoZSLHGNFMgD3Yd8UO1uZweFFIB4d3OQxhhn/ZZ8Pi/HX6k+fp0ov3jv8BUsARXbaDLNtEXI1Q+OFS05RBvECHgkwqTNEJMka0uVIDxfx6fbuweceJ7qEKHatPffYKQUxSvQurlnPXatbOZz7i3HtBCEURfGQ2U7vT7C2uVsEBYE4Yuu+NM4CoSO9M2wEg3J4GDmDzBqeYaW7sz5Vx8hSs/NHxVpnIiocuLK78E2StSpMZi5IiRU9PWekLaGVnru4gZVyvTfSE7zn2JZzdop5/EYCSgixW0DG/xbr3PV5Wbt7K4epBDG/5fKYE6ruTwIE6BlYdGQorUFPDveTRC8L05HCE5NPxwVrARalTEyOqx/M0qvCw/UDRScYv4qcFOwcx5VbEfoDyYh8sUiDJ+HsQ0rUnqvpHZi56Tevp0yWJji9couMD8K+E+7lAfoSKuUWmdvN3BIgQnBUX38JHM1EMmA+sdY6lLyoDsw8u00bkYT2E1lYY0NzEZfrrGM7pu6wS/VwYTOSyQTxDR1PQ7JSAmo9+z5k7NqTeMgvNSWUUUpq4sLuq+nE3bpntngjPhVvY/9MfPZnTmX1dW+CwBeCfd3LFLsBle1rBvMhmAAT8/rj56nPD/h7nyCTiu0VHix0jWRcBMvL8RnCFl3dzs+lG1G55PFeCgMrRjDN51OzjVm5QEn6wZOOedar7btSr85X0xT34DIfED1IJl/CA2LCu4Vr50glIVoSFcpil0IGaqhHyeQOaut5Nu88xJmVAGqccrzetbxLdT82zQ7OKRRGxLbcObLOMElIg1J+sN8ipjSdSpqpOrjCey6cT5QmqpoZ2+KZaiHkH/OqB/4tKoVcBkuByuKiWInbbRFth9+HcSldgJWRBweaWD5xtX2qbx315PX2KBKKoDi68q3T6TJPIglqACklcUH3NLcm6YT+ss7yYQetmZmAnIRsnjuVYCQ+s6iYKc8UH9ZpcwnAbllR5lH6vOmfvRujDB1R5/01h6Iq59lNF9ZICB6l3+vjPCvfDpd7uiVz9SEaMu3UJseAJB8vbkj7pkuLBFYnDqPptmIgjb+9yFJT8T0NDhLdf5T5r6siBfdMAdtwRHipM74srKB7U9BQTc295O8YrlrSPgIosoFMmURVT1Zgc2K0XYTtRRuF8vLdjj09tnqU6Azy1LjHCz8ljcFudY4CNd4qpsQjIaTVYRE5pD0xorUBqiYkF2epfR3wrFwy/O67mFDaEjwaiL4NCeqZ7ZcTI4KWwB9JD5p8BoEwUf7nemmo5nxSgD/C8zV+oM0O4N/9hSCR3Rw3Ry23j/RMLud+Z+hbSaW9mH9nO5CrWTddQvxe2O8ekpG5Xj3+jd7bYxWFDtGhmrxrtlilXMn6kilKRGFn5J10RNWo45iWoAlvRxv+uX1jyac/RxJgHImiz6yLYV1/y6h1nj8f7JuAEuyjk5VynBPRfijv17+UoaxUiqSIWQxtLeHu9nGBUoqgaVh6b0h+dc8BsDD3k4Y+RO8kayhirvKIjfQt8ZrkvXFEvljdVDpXi2tgH568+nuCzDInONZY6zSffDXD5dq4C4RXEgDo48tCfjyER3CWfprzFxHsVUCMqfJ8H0rG0DRJ8IZWnfh35MntqGtQMZNLMlMxn48sgXThbbh2uQ8FwcEilzBf9495X8kcw/QZwaLObYEoAnhnwdv8x6Qb/8uRaJsyjuOlQ38L/8usuj3sZsE6BCc9rDBPfbvMqM7eqnul2Ms4Bq1nnJIyRo4r7OnvrHWXc0UyB8CtYRS63F9ebLm17A8BMQ2twuNlTGsu/rZULsiAK1XMIMLd0rPM45wrrL0PFakHdYWMQihBZqGl1s/S+ag0Kie/nxsK+SrdZsSJfN1vJzHFM9LBDsoETXmUOsPZ7/hyzS+/OI3THfoLnTMq5LkkHa/NjfGpTYt5vkUsFN3jQa3xxMEA9k/De3GqiNWJc63tBLGtLp7RAa/hMJca68HIQ34LizIDbUiPnNa7AFj+KzMyPpYbnWMVMU0gI0/jnPfKKy9bWe/vet0/k//fV9xz3Ly3lCTwQQzex5KHRA5vJp2O1oGPCJUaAOgPAGgHSDIBhrYAlj7MfGc1A74FlPA3AHIbIDsLwHoE7HTt7NhOQPLtmQ8tBkiAAqjeBXiOBPQAZ+ZprsDBzoDjFED1/4DtxUDqWwDAG2DnvcDaFkAMiGaudAn4GAUEPwd8JwPMOED3ZbvxIyA6FMAWAqYez9zfNKDpNeDzK0D1ZOb98CAGbgGeug549gBcvQLWFsz8t8OAZ0dAc+DM1UKAq8mA7lzA003AfODxUP4AGMC5CIrKZG2QjicdIEBB4jnQDiYnISiMTsLQ2DuJkAyMkzi4hE2iOGAHWAZACZSCOlA8J1YAb0ygMCYbINegbLKQrE+sBlXACQnNUnwsdqXj8ScNxAMN0BSXhRc5QHhV2gK/WKBB+JMpBgQf2LfErpSoBNWgBrQ8Q2luKgGz38AL5QN3nLYgJRUb8kBLBmkaNGRUZIoHTTcm0tygZLYDDTkUeJQGPrlBDiq406lRUX0ACleyEBozKJBkSP8chgIA); }BMad Method Workflow - Standard GreenfieldStartPHASE 1Discovery(Optional)IncludeDiscovery?YesBrainstorm<<optional>>Research<<optional>>Product Brief<<optional>>NoPHASE 2Planning (Required)PRDHas UI?YesCreate UXNoPHASE 3Solutioning (Required)ArchitectureEpics/StoriesTest Design<<optional>>Validate Arch<<optional>>ImplementationReadinessPHASE 4Implementation (Required)Sprint PlanSTORY LOOPCreate StoryValidate Story<<optional>>Develop StoryCode ReviewPass?FailPassCode Review<<use differentLLM>>More Storiesin Epic?YesNoRetrospectiveMore Epics?YesNoEndAgent LegendAnalystPMUX DesignerArchitectTEASMDEVDecision \ No newline at end of file diff --git a/src/modules/bmm/docs/quick-spec-flow.md b/src/modules/bmm/docs/quick-spec-flow.md new file mode 100644 index 00000000..cd3d5b15 --- /dev/null +++ b/src/modules/bmm/docs/quick-spec-flow.md @@ -0,0 +1,652 @@ +# BMad Quick Spec Flow + +**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements + +**Time to implementation:** Minutes, not hours + +--- + +## What is Quick Spec Flow? + +Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Quick Flow track projects. Instead of going through Product Brief โ†’ PRD โ†’ Architecture, you go **straight to a context-aware technical specification** and start coding. + +### When to Use Quick Spec Flow + +โœ… **Use Quick Flow track when:** + +- Single bug fix or small enhancement +- Small feature with clear scope (typically 1-15 stories) +- Rapid prototyping or experimentation +- Adding to existing brownfield codebase +- You know exactly what you want to build + +โŒ **Use BMad Method or Enterprise tracks when:** + +- Building new products or major features +- Need stakeholder alignment +- Complex multi-team coordination +- Requires extensive planning and architecture + +๐Ÿ’ก **Not sure?** Run `workflow-init` to get a recommendation based on your project's needs! + +--- + +## Quick Spec Flow Overview + +```mermaid +flowchart TD + START[Step 1: Run Tech-Spec Workflow] + DETECT[Detects project stack
package.json, requirements.txt, etc.] + ANALYZE[Analyzes brownfield codebase
if exists] + TEST[Detects test frameworks
and conventions] + CONFIRM[Confirms conventions
with you] + GENERATE[Generates context-rich
tech-spec] + STORIES[Creates ready-to-implement
stories] + + OPTIONAL[Step 2: Optional
Generate Story Context
SM Agent
For complex scenarios only] + + IMPL[Step 3: Implement
DEV Agent
Code, test, commit] + + DONE[DONE! ๐Ÿš€] + + START --> DETECT + DETECT --> ANALYZE + ANALYZE --> TEST + TEST --> CONFIRM + CONFIRM --> GENERATE + GENERATE --> STORIES + STORIES --> OPTIONAL + OPTIONAL -.->|Optional| IMPL + STORIES --> IMPL + IMPL --> DONE + + style START fill:#bfb,stroke:#333,stroke-width:2px + style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5 + style IMPL fill:#bbf,stroke:#333,stroke-width:2px + style DONE fill:#f9f,stroke:#333,stroke-width:3px +``` + +--- + +## Single Atomic Change + +**Best for:** Bug fixes, single file changes, isolated improvements + +### What You Get + +1. **tech-spec.md** - Comprehensive technical specification with: + - Problem statement and solution + - Detected framework versions and dependencies + - Brownfield code patterns (if applicable) + - Existing test patterns to follow + - Specific file paths to modify + - Complete implementation guidance + +2. **story-[slug].md** - Single user story ready for development + +### Quick Spec Flow Commands + +```bash +# Start Quick Spec Flow (no workflow-init needed!) +# Load PM agent and run tech-spec + +# When complete, implement directly: +# Load DEV agent and run dev-story +``` + +### What Makes It Quick + +- โœ… No Product Brief needed +- โœ… No PRD needed +- โœ… No Architecture doc needed +- โœ… Auto-detects your stack +- โœ… Auto-analyzes brownfield code +- โœ… Auto-validates quality +- โœ… Story context optional (tech-spec is comprehensive!) + +### Example Single Change Scenarios + +- "Fix the login validation bug" +- "Add email field to user registration form" +- "Update API endpoint to return additional field" +- "Improve error handling in payment processing" + +--- + +## Coherent Small Feature + +**Best for:** Small features with 2-3 related user stories + +### What You Get + +1. **tech-spec.md** - Same comprehensive spec as single change projects +2. **epics.md** - Epic organization with story breakdown +3. **story-[epic-slug]-1.md** - First story +4. **story-[epic-slug]-2.md** - Second story +5. **story-[epic-slug]-3.md** - Third story (if needed) + +### Quick Spec Flow Commands + +```bash +# Start Quick Spec Flow +# Load PM agent and run tech-spec + +# Optional: Organize stories as a sprint +# Load SM agent and run sprint-planning + +# Implement story-by-story: +# Load DEV agent and run dev-story for each story +``` + +### Story Sequencing + +Stories are **automatically validated** to ensure proper sequence: + +- โœ… No forward dependencies (Story 2 can't depend on Story 3) +- โœ… Clear dependency documentation +- โœ… Infrastructure โ†’ Features โ†’ Polish order +- โœ… Backend โ†’ Frontend flow + +### Example Small Feature Scenarios + +- "Add OAuth social login (Google, GitHub, Twitter)" +- "Build user profile page with avatar upload" +- "Implement basic search with filters" +- "Add dark mode toggle to application" + +--- + +## Smart Context Discovery + +Quick Spec Flow automatically discovers and uses: + +### 1. Existing Documentation + +- Product briefs (if they exist) +- Research documents +- `document-project` output (brownfield codebase map) + +### 2. Project Stack + +- **Node.js:** package.json โ†’ frameworks, dependencies, scripts, test framework +- **Python:** requirements.txt, pyproject.toml โ†’ packages, tools +- **Ruby:** Gemfile โ†’ gems and versions +- **Java:** pom.xml, build.gradle โ†’ Maven/Gradle dependencies +- **Go:** go.mod โ†’ modules +- **Rust:** Cargo.toml โ†’ crates +- **PHP:** composer.json โ†’ packages + +### 3. Brownfield Code Patterns + +- Directory structure and organization +- Existing code patterns (class-based, functional, MVC) +- Naming conventions (camelCase, snake_case, PascalCase) +- Test frameworks and patterns +- Code style (semicolons, quotes, indentation) +- Linter/formatter configs +- Error handling patterns +- Logging conventions +- Documentation style + +### 4. Convention Confirmation + +**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**: + +``` +I've detected these conventions in your codebase: + +Code Style: +- ESLint with Airbnb config +- Prettier with single quotes, 2-space indent +- No semicolons + +Test Patterns: +- Jest test framework +- .test.js file naming +- expect() assertion style + +Should I follow these existing conventions? (yes/no) +``` + +**You decide:** Conform to existing patterns or establish new standards! + +--- + +## Modern Best Practices via WebSearch + +Quick Spec Flow stays current by using WebSearch when appropriate: + +### For Greenfield Projects + +- Searches for latest framework versions +- Recommends official starter templates +- Suggests modern best practices + +### For Outdated Dependencies + +- Detects if your dependencies are >2 years old +- Searches for migration guides +- Notes upgrade complexity + +### Starter Template Recommendations + +For greenfield projects, Quick Spec Flow recommends: + +**React:** + +- Vite (modern, fast) +- Next.js (full-stack) + +**Python:** + +- cookiecutter templates +- FastAPI starter + +**Node.js:** + +- NestJS CLI +- express-generator + +**Benefits:** + +- โœ… Modern best practices baked in +- โœ… Proper project structure +- โœ… Build tooling configured +- โœ… Testing framework set up +- โœ… Faster time to first feature + +--- + +## UX/UI Considerations + +For user-facing changes, Quick Spec Flow captures: + +- UI components affected (create vs modify) +- UX flow changes (current vs new) +- Responsive design needs (mobile, tablet, desktop) +- Accessibility requirements: + - Keyboard navigation + - Screen reader compatibility + - ARIA labels + - Color contrast standards +- User feedback patterns: + - Loading states + - Error messages + - Success confirmations + - Progress indicators + +--- + +## Auto-Validation and Quality Assurance + +Quick Spec Flow **automatically validates** everything: + +### Tech-Spec Validation (Always Runs) + +Checks: + +- โœ… Context gathering completeness +- โœ… Definitiveness (no "use X or Y" statements) +- โœ… Brownfield integration quality +- โœ… Stack alignment +- โœ… Implementation readiness + +Generates scores: + +``` +โœ… Validation Passed! +- Context Gathering: Comprehensive +- Definitiveness: All definitive +- Brownfield Integration: Excellent +- Stack Alignment: Perfect +- Implementation Readiness: โœ… Ready +``` + +### Story Validation (Multi-Story Features) + +Checks: + +- โœ… Story sequence (no forward dependencies!) +- โœ… Acceptance criteria quality (specific, testable) +- โœ… Completeness (all tech spec tasks covered) +- โœ… Clear dependency documentation + +**Auto-fixes issues if found!** + +--- + +## Complete User Journey + +### Scenario 1: Bug Fix (Single Change) + +**Goal:** Fix login validation bug + +**Steps:** + +1. **Start:** Load PM agent, say "I want to fix the login validation bug" +2. **PM runs tech-spec workflow:** + - Asks: "What problem are you solving?" + - You explain the validation issue + - Detects your Node.js stack (Express 4.18.2, Jest for testing) + - Analyzes existing UserService code patterns + - Asks: "Should I follow your existing conventions?" โ†’ You say yes + - Generates tech-spec.md with specific file paths and patterns + - Creates story-login-fix.md +3. **Implement:** Load DEV agent, run `dev-story` + - DEV reads tech-spec (has all context!) + - Implements fix following existing patterns + - Runs tests (following existing Jest patterns) + - Done! + +**Total time:** 15-30 minutes (mostly implementation) + +--- + +### Scenario 2: Small Feature (Multi-Story) + +**Goal:** Add OAuth social login (Google, GitHub) + +**Steps:** + +1. **Start:** Load PM agent, say "I want to add OAuth social login" +2. **PM runs tech-spec workflow:** + - Asks about the feature scope + - You specify: Google and GitHub OAuth + - Detects your stack (Next.js 13.4, NextAuth.js already installed!) + - Analyzes existing auth patterns + - Confirms conventions with you + - Generates: + - tech-spec.md (comprehensive implementation guide) + - epics.md (OAuth Integration epic) + - story-oauth-1.md (Backend OAuth setup) + - story-oauth-2.md (Frontend login buttons) +3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning` +4. **Implement Story 1:** + - Load DEV agent, run `dev-story` for story 1 + - DEV implements backend OAuth +5. **Implement Story 2:** + - DEV agent, run `dev-story` for story 2 + - DEV implements frontend + - Done! + +**Total time:** 1-3 hours (mostly implementation) + +--- + +## Integration with Phase 4 Workflows + +Quick Spec Flow works seamlessly with all Phase 4 implementation workflows: + +### story-context (SM Agent) + +- โœ… Recognizes tech-spec.md as authoritative source +- โœ… Extracts context from tech-spec (replaces PRD) +- โœ… Generates XML context for complex scenarios + +### create-story (SM Agent) + +- โœ… Can work with tech-spec.md instead of PRD +- โœ… Uses epics.md from tech-spec workflow +- โœ… Creates additional stories if needed + +### sprint-planning (SM Agent) + +- โœ… Works with epics.md from tech-spec +- โœ… Organizes multi-story features for coordinated implementation +- โœ… Tracks progress through sprint-status.yaml + +### dev-story (DEV Agent) + +- โœ… Reads stories generated by tech-spec +- โœ… Uses tech-spec.md as comprehensive context +- โœ… Implements following detected conventions + +--- + +## Comparison: Quick Spec vs Full BMM + +| Aspect | Quick Flow Track | BMad Method/Enterprise Tracks | +| --------------------- | ---------------------------- | ---------------------------------- | +| **Setup** | None (standalone) | workflow-init recommended | +| **Planning Docs** | tech-spec.md only | Product Brief โ†’ PRD โ†’ Architecture | +| **Time to Code** | Minutes | Hours to days | +| **Best For** | Bug fixes, small features | New products, major features | +| **Context Discovery** | Automatic | Manual + guided | +| **Story Context** | Optional (tech-spec is rich) | Required (generated from PRD) | +| **Validation** | Auto-validates everything | Manual validation steps | +| **Brownfield** | Auto-analyzes and conforms | Manual documentation required | +| **Conventions** | Auto-detects and confirms | Document in PRD/Architecture | + +--- + +## When to Graduate from Quick Flow to BMad Method + +Start with Quick Flow, but switch to BMad Method when: + +- โŒ Project grows beyond initial scope +- โŒ Multiple teams need coordination +- โŒ Stakeholders need formal documentation +- โŒ Product vision is unclear +- โŒ Architectural decisions need deep analysis +- โŒ Compliance/regulatory requirements exist + +๐Ÿ’ก **Tip:** You can always run `workflow-init` later to transition from Quick Flow to BMad Method! + +--- + +## Quick Spec Flow - Key Benefits + +### ๐Ÿš€ **Speed** + +- No Product Brief +- No PRD +- No Architecture doc +- Straight to implementation + +### ๐Ÿง  **Intelligence** + +- Auto-detects stack +- Auto-analyzes brownfield +- Auto-validates quality +- WebSearch for current info + +### ๐Ÿ“ **Respect for Existing Code** + +- Detects conventions +- Asks for confirmation +- Follows patterns +- Adapts vs. changes + +### โœ… **Quality** + +- Auto-validation +- Definitive decisions (no "or" statements) +- Comprehensive context +- Clear acceptance criteria + +### ๐ŸŽฏ **Focus** + +- Single atomic changes +- Coherent small features +- No scope creep +- Fast iteration + +--- + +## Getting Started + +### Prerequisites + +- BMad Method installed (`npx bmad-method install`) +- Project directory with code (or empty for greenfield) + +### Quick Start Commands + +```bash +# For a quick bug fix or small change: +# 1. Load PM agent +# 2. Say: "I want to [describe your change]" +# 3. PM will ask if you want to run tech-spec +# 4. Answer questions about your change +# 5. Get tech-spec + story +# 6. Load DEV agent and implement! + +# For a small feature with multiple stories: +# Same as above, but get epic + 2-3 stories +# Optionally use SM sprint-planning to organize +``` + +### No workflow-init Required! + +Quick Spec Flow is **fully standalone**: + +- Detects if it's a single change or multi-story feature +- Asks for greenfield vs brownfield +- Works without status file tracking +- Perfect for rapid prototyping + +--- + +## FAQ + +### Q: Can I use Quick Spec Flow on an existing project? + +**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them. + +### Q: What if I don't have a package.json or requirements.txt? + +**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices. + +### Q: Do I need to run workflow-init first? + +**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help. + +### Q: Can I use this for frontend changes? + +**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements. + +### Q: What if my Quick Flow project grows? + +**A:** No problem! You can always transition to BMad Method by running workflow-init and create-prd. Your tech-spec becomes input for the PRD. + +### Q: Do I need story-context for every story? + +**A:** Usually no! Tech-spec is comprehensive enough for most Quick Flow projects. Only use story-context for complex edge cases. + +### Q: Can I skip validation? + +**A:** No, validation always runs automatically. But it's fast and catches issues early! + +### Q: Will it work with my team's code style? + +**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones. + +--- + +## Tips and Best Practices + +### 1. **Be Specific in Discovery** + +When describing your change, provide specifics: + +- โœ… "Fix email validation in UserService to allow plus-addressing" +- โŒ "Fix validation bug" + +### 2. **Trust the Convention Detection** + +If it detects your patterns correctly, say yes! It's faster than establishing new conventions. + +### 3. **Use WebSearch Recommendations for Greenfield** + +Starter templates save hours of setup time. Let Quick Spec Flow find the best ones. + +### 4. **Review the Auto-Validation** + +When validation runs, read the scores. They tell you if your spec is production-ready. + +### 5. **Story Context is Optional** + +For single changes, try going directly to dev-story first. Only add story-context if you hit complexity. + +### 6. **Keep Single Changes Truly Atomic** + +If your "single change" needs 3+ files, it might be a multi-story feature. Let the workflow guide you. + +### 7. **Validate Story Sequence for Multi-Story Features** + +When you get multiple stories, check the dependency validation output. Proper sequence matters! + +--- + +## Real-World Examples + +### Example 1: Adding Logging (Single Change) + +**Input:** "Add structured logging to payment processing" + +**Tech-Spec Output:** + +- Detected: winston 3.8.2 already in package.json +- Analyzed: Existing services use winston with JSON format +- Confirmed: Follow existing logging patterns +- Generated: Specific file paths, log levels, format example +- Story: Ready to implement in 1-2 hours + +**Result:** Consistent logging added, following team patterns, no research needed. + +--- + +### Example 2: Search Feature (Multi-Story) + +**Input:** "Add search to product catalog with filters" + +**Tech-Spec Output:** + +- Detected: React 18.2.0, MUI component library, Express backend +- Analyzed: Existing ProductList component patterns +- Confirmed: Follow existing API and component structure +- Generated: + - Epic: Product Search Functionality + - Story 1: Backend search API with filters + - Story 2: Frontend search UI component +- Auto-validated: Story 1 โ†’ Story 2 sequence correct + +**Result:** Search feature implemented in 4-6 hours with proper architecture. + +--- + +## Summary + +Quick Spec Flow is your **fast path from idea to implementation** for: + +- ๐Ÿ› Bug fixes +- โœจ Small features +- ๐Ÿš€ Rapid prototyping +- ๐Ÿ”ง Quick enhancements + +**Key Features:** + +- Auto-detects your stack +- Auto-analyzes brownfield code +- Auto-validates quality +- Respects existing conventions +- Uses WebSearch for modern practices +- Generates comprehensive tech-specs +- Creates implementation-ready stories + +**Time to code:** Minutes, not hours. + +**Ready to try it?** Load the PM agent and say what you want to build! ๐Ÿš€ + +--- + +## Next Steps + +- **Try it now:** Load PM agent and describe a small change +- **Learn more:** See the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation +- **Need help deciding?** Run `workflow-init` to get a recommendation +- **Have questions?** Join us on Discord: + +--- + +_Quick Spec Flow - Because not every change needs a Product Brief._ diff --git a/src/modules/bmm/docs/quick-start.md b/src/modules/bmm/docs/quick-start.md index fae2da8c..3aff89ef 100644 --- a/src/modules/bmm/docs/quick-start.md +++ b/src/modules/bmm/docs/quick-start.md @@ -313,11 +313,10 @@ flowchart LR direction TB D1[Per Epic:
epic context] D2[Per Story:
create-story] - D3[story-context] - D4[dev-story] - D5[code-review] - D6[SM, DEV] - D1 ~~~ D2 ~~~ D3 ~~~ D4 ~~~ D5 ~~~ D6 + D3[dev-story] + D4[code-review] + D5[SM, DEV] + D1 ~~~ D2 ~~~ D3 ~~~ D4 ~~~ D5 end P1 --> P2 diff --git a/src/modules/bmm/docs/test-architecture.md b/src/modules/bmm/docs/test-architecture.md index 4c2a4de5..2ab2da3c 100644 --- a/src/modules/bmm/docs/test-architecture.md +++ b/src/modules/bmm/docs/test-architecture.md @@ -138,12 +138,12 @@ Epic/Release Gate โ†’ TEA: *nfr-assess, *trace Phase 2 (release decision) **Standard agents**: 1-3 workflows per phase **TEA**: 8 workflows across Phase 3, Phase 4, and Release Gate -| Phase | TEA Workflows | Frequency | Purpose | -| ----------- | ----------------------------------------------------- | ---------------- | ---------------------------------------------- | -| **Phase 2** | (none) | - | Planning phase - PM defines requirements | -| **Phase 3** | *framework, *ci | Once per project | Setup test infrastructure AFTER architecture | -| **Phase 4** | *test-design, *atdd, *automate, *test-review, \*trace | Per epic/story | Test planning per epic, then per-story testing | -| **Release** | *nfr-assess, *trace (Phase 2: gate) | Per epic/release | Go/no-go decision | +| Phase | TEA Workflows | Frequency | Purpose | +| ----------- | --------------------------------------------------------- | ---------------- | ---------------------------------------------- | +| **Phase 2** | (none) | - | Planning phase - PM defines requirements | +| **Phase 3** | \*framework, \*ci | Once per project | Setup test infrastructure AFTER architecture | +| **Phase 4** | \*test-design, \*atdd, \*automate, \*test-review, \*trace | Per epic/story | Test planning per epic, then per-story testing | +| **Release** | \*nfr-assess, \*trace (Phase 2: gate) | Per epic/release | Go/no-go decision | **Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow. diff --git a/src/modules/bmm/docs/troubleshooting.md b/src/modules/bmm/docs/troubleshooting.md new file mode 100644 index 00000000..a3cd63bf --- /dev/null +++ b/src/modules/bmm/docs/troubleshooting.md @@ -0,0 +1,680 @@ +# BMM Troubleshooting Guide + +Common issues and solutions for the BMad Method Module. + +--- + +## Quick Diagnosis + +**Use this flowchart to find your issue:** + +```mermaid +flowchart TD + START{What's the problem?} + + START -->|Can't get started| SETUP[Setup & Installation Issues] + START -->|Wrong level detected| LEVEL[Level Detection Problems] + START -->|Workflow not working| WORKFLOW[Workflow Issues] + START -->|Agent lacks context| CONTEXT[Context & Documentation Issues] + START -->|Implementation problems| IMPL[Implementation Issues] + START -->|Files/paths wrong| FILES[File & Path Issues] + + style START fill:#ffb,stroke:#333,stroke-width:2px + style SETUP fill:#bfb,stroke:#333,stroke-width:2px + style LEVEL fill:#bbf,stroke:#333,stroke-width:2px + style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px + style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px +``` + +--- + +## Table of Contents + +- [Setup and Installation Issues](#setup-and-installation-issues) +- [Level Detection Problems](#level-detection-problems) +- [Workflow Issues](#workflow-issues) +- [Context and Documentation Issues](#context-and-documentation-issues) +- [Implementation Issues](#implementation-issues) +- [File and Path Issues](#file-and-path-issues) +- [Agent Behavior Issues](#agent-behavior-issues) +- [Integration Issues (Brownfield)](#integration-issues-brownfield) + +--- + +## Setup and Installation Issues + +### Problem: BMM not found after installation + +**Symptoms:** + +- `bmad` command not recognized +- Agent files not accessible +- Workflows don't load + +**Solution:** + +```bash +# Check if BMM is installed +ls bmad/ + +# If not present, run installer +npx bmad-method@alpha install + +# For fresh install +npx bmad-method@alpha install --skip-version-prompt +``` + +### Problem: Agents don't have menu + +**Symptoms:** + +- Load agent file but no menu appears +- Agent doesn't respond to commands + +**Solution:** + +1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md` +2. Wait a few seconds for agent to initialize +3. Try asking "show menu" or "help" +4. Check IDE supports Markdown rendering with context +5. For Claude Code: Ensure agent file is open in chat context + +### Problem: Workflows not found + +**Symptoms:** + +- Agent says workflow doesn't exist +- Menu shows workflow but won't run + +**Solution:** + +1. Check workflow exists: `ls bmad/bmm/workflows/` +2. Verify agent has access to workflow (check agent's workflow list) +3. Try using menu number instead of workflow name +4. Restart chat with agent in fresh session + +--- + +## Level Detection Problems + +### Problem: workflow-init suggests wrong level + +**Symptoms:** + +- Detects Level 3 but you only need Level 1 +- Suggests Level 1 but project is actually Level 2 +- Can't figure out appropriate level + +**Solution:** + +1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level +2. **Be specific in description** - Use level keywords when describing: + - "fix bug" โ†’ Level 0 + - "add small feature" โ†’ Level 1 + - "build dashboard" โ†’ Level 2 +3. **Manual override** - You can always switch levels later if needed + +**Example:** + +``` +workflow-init: "Level 3 project?" +You: "No, this is just adding OAuth login - Level 1" +workflow-init: "Got it, creating Level 1 workflow" +``` + +### Problem: Project level unclear + +**Symptoms:** + +- Between Level 1 and Level 2 +- Not sure if architecture needed +- Story count uncertain + +**Solution:** +**When in doubt, start smaller:** + +- Choose Level 1 instead of Level 2 +- You can always run `create-prd` later if needed +- Level 1 is faster, less overhead +- Easy to upgrade, hard to downgrade + +**Decision criteria:** + +- Single epic with related stories? โ†’ Level 1 +- Multiple independent epics? โ†’ Level 2 +- Need product-level planning? โ†’ Level 2 +- Just need technical plan? โ†’ Level 1 + +### Problem: Old planning docs influencing level detection + +**Symptoms:** + +- Old Level 3 PRD in folder +- Working on new Level 0 bug fix +- workflow-init suggests Level 3 + +**Solution:** +workflow-init asks: "Is this work in progress or previous effort?" + +- Answer: "Previous effort" +- Then describe your NEW work clearly +- System will detect level based on NEW work, not old artifacts + +--- + +## Workflow Issues + +### Problem: Workflow fails or hangs + +**Symptoms:** + +- Workflow starts but doesn't complete +- Agent stops responding mid-workflow +- Progress stalls + +**Solution:** + +1. **Check context limits** - Start fresh chat for complex workflows +2. **Verify prerequisites**: + - Phase 2 needs Phase 1 complete (if used) + - Phase 3 needs Phase 2 complete + - Phase 4 needs Phase 3 complete (if Level 3-4) +3. **Restart workflow** - Load agent in new chat and restart +4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid + +### Problem: Agent says "workflow not found" + +**Symptoms:** + +- Request workflow by name +- Agent doesn't recognize it +- Menu doesn't show workflow + +**Solution:** + +1. Check spelling/format - Use exact workflow name or menu shortcut (`*prd` not `*PRD`) +2. Verify agent has workflow: + - PM agent: prd, tech-spec + - Architect agent: create-architecture, validate-architecture + - SM agent: sprint-planning, create-story, story-context +3. Try menu number instead of name +4. Check you're using correct agent for workflow + +### Problem: Sprint-planning workflow fails + +**Symptoms:** + +- Can't create sprint-status.yaml +- Epics not extracted from files +- Status file empty or incorrect + +**Solution:** + +1. **Verify epic files exist**: + - Level 1: tech-spec with epic + - Level 2-4: epics.md or sharded epic files +2. **Check file format**: + - Epic files should be valid Markdown + - Epic headers should be clear (## Epic Name) +3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first +4. **Check file paths** - Epic files should be in correct output folder + +### Problem: story-context generates empty or wrong context + +**Symptoms:** + +- Context file created but has no useful content +- Context doesn't reference existing code +- Missing technical guidance + +**Solution:** + +1. **Run epic-tech-context first** - story-context builds on epic context +2. **Check story file exists** - Verify story was created by create-story +3. **For brownfield**: + - Ensure document-project was run + - Verify docs/index.md exists with codebase context +4. **Try regenerating** - Sometimes needs fresh attempt with more specific story details + +--- + +## Context and Documentation Issues + +### Problem: AI agents lack codebase understanding (Brownfield) + +**Symptoms:** + +- Suggestions don't align with existing patterns +- Ignores available components +- Proposes approaches that conflict with architecture +- Doesn't reference existing code + +**Solution:** + +1. **Run document-project** - Critical for brownfield projects + ``` + Load Analyst agent โ†’ run document-project + Choose scan level: Deep (recommended for PRD prep) + ``` +2. **Verify docs/index.md exists** - This is master entry point for AI agents +3. **Check documentation completeness**: + - Review generated docs/index.md + - Ensure key systems are documented +4. **Run deep-dive on specific areas** if needed + +### Problem: Have documentation but agents can't find it + +**Symptoms:** + +- README.md, ARCHITECTURE.md exist +- AI agents still ask questions answered in docs +- No docs/index.md file + +**Solution:** +**Option 1: Quick fix (2-5min)** +Run `index-docs` task: + +- Located at `bmad/core/tasks/index-docs.xml` +- Scans existing docs and generates index.md +- Lightweight, just creates navigation + +**Option 2: Comprehensive (10-30min)** +Run document-project workflow: + +- Discovers existing docs in Step 2 +- Generates NEW AI-friendly documentation from codebase +- Creates index.md linking to BOTH existing and new docs + +**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently. + +### Problem: document-project takes too long + +**Symptoms:** + +- Exhaustive scan running for hours +- Impatient to start planning + +**Solution:** +**Choose appropriate scan level:** + +- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview +- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects** +- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding + +For most brownfield projects, **Deep scan is sufficient**. + +--- + +## Implementation Issues + +### Problem: Existing tests breaking (Brownfield) + +**Symptoms:** + +- Regression test failures +- Previously working functionality broken +- Integration tests failing + +**Solution:** + +1. **Review changes against existing patterns**: + - Check if new code follows existing conventions + - Verify API contracts unchanged (unless intentionally versioned) +2. **Run test-review workflow** (TEA agent): + - Analyzes test coverage + - Identifies regression risks + - Suggests fixes +3. **Add regression testing to DoD**: + - All existing tests must pass + - Add integration tests for new code +4. **Consider feature flags** for gradual rollout + +### Problem: Story takes much longer than estimated + +**Symptoms:** + +- Story estimated 4 hours, took 12 hours +- Acceptance criteria harder than expected +- Hidden complexity discovered + +**Solution:** +**This is normal!** Estimates are estimates. To handle: + +1. **Continue until DoD met** - Don't compromise quality +2. **Document learnings in retrospective**: + - What caused the overrun? + - What should we watch for next time? +3. **Consider splitting story** if it's truly two stories +4. **Adjust future estimates** based on this data + +**Don't stress about estimate accuracy** - use them for learning, not judgment. + +### Problem: Integration points unclear + +**Symptoms:** + +- Not sure how to connect new code to existing +- Unsure which files to modify +- Multiple possible integration approaches + +**Solution:** + +1. **For brownfield**: + - Ensure document-project captured existing architecture + - Review architecture docs before implementing +2. **Check story-context** - Should document integration points +3. **In tech-spec/architecture** - Explicitly document: + - Which existing modules to modify + - What APIs/services to integrate with + - Data flow between new and existing code +4. **Run integration-planning workflow** (Level 3-4): + - Architect agent creates integration strategy + +### Problem: Inconsistent patterns being introduced + +**Symptoms:** + +- New code style doesn't match existing +- Different architectural approach +- Not following team conventions + +**Solution:** + +1. **Check convention detection** (Quick Spec Flow): + - Should detect existing patterns + - Asks for confirmation before proceeding +2. **Review documentation** - Ensure document-project captured patterns +3. **Use story-context** - Injects pattern guidance per story +4. **Add to code-review checklist**: + - Pattern adherence + - Convention consistency + - Style matching +5. **Run retrospective** to identify pattern deviations early + +--- + +## File and Path Issues + +### Problem: Output files in wrong location + +**Symptoms:** + +- PRD created in wrong folder +- Story files not where expected +- Documentation scattered + +**Solution:** +Check `bmad/bmm/config.yaml` for configured paths: + +```yaml +output_folder: '{project-root}/docs' +dev_story_location: '{project-root}/docs/stories' +``` + +Default locations: + +- Planning docs (PRD, epics, architecture): `{output_folder}/` +- Stories: `{dev_story_location}/` +- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml` + +To change locations, edit config.yaml then re-run workflows. + +### Problem: Can't find status file + +**Symptoms:** + +- workflow-status says no status file +- Can't track progress +- Lost place in workflow + +**Solution:** + +1. **Check default location**: `docs/bmm-workflow-status.md` +2. **If missing, reinitialize**: + ``` + Load Analyst agent โ†’ run workflow-init + ``` +3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD +4. **Search for it**: + ```bash + find . -name "bmm-workflow-status.md" + find . -name "sprint-status.yaml" + ``` + +### Problem: Sprint-status.yaml not updating + +**Symptoms:** + +- Workflows complete but status unchanged +- Stories stuck in old status +- Epic status not progressing + +**Solution:** + +1. **Manual update required** - Most status changes are manual: + ```yaml + stories: + - id: epic-1-story-1 + status: done # Change this manually + ``` +2. **Some workflows auto-update**: + - sprint-planning creates file + - epic-tech-context changes epic to "contexted" + - create-story changes story to "drafted" + - story-context changes to "ready-for-dev" + - dev-story may auto-update (check workflow) +3. **Re-run sprint-planning** to resync if needed + +--- + +## Agent Behavior Issues + +### Problem: Agent provides vague or generic responses + +**Symptoms:** + +- "Use appropriate framework" +- "Follow best practices" +- Generic advice without specifics + +**Solution:** + +1. **Provide more context** - Be specific in your description: + - "Add OAuth using passport.js to Express server" + - Not: "Add authentication" +2. **For brownfield**: + - Ensure document-project was run + - Agent needs codebase context for specific advice +3. **Reference existing docs**: + - "Based on the existing auth system in UserService..." +4. **Start fresh chat** - Context overload can cause generic responses + +### Problem: Agent hallucinating or making up information + +**Symptoms:** + +- References files that don't exist +- Suggests APIs that aren't in your stack +- Creates imaginary requirements + +**Solution:** + +1. **Use fresh chat** - Context overflow main cause of hallucinations +2. **Provide concrete constraints**: + - "We use Express 4.18.2, not Next.js" + - "Our database is PostgreSQL, not MongoDB" +3. **For brownfield**: + - Document-project provides factual grounding + - Agent sees actual code, not assumptions +4. **Correct immediately**: + - "No, we don't have UserService, we have AuthenticationModule" + +### Problem: Agent won't follow instructions + +**Symptoms:** + +- Ignores specific requests +- Does something different than asked +- Doesn't respect constraints + +**Solution:** + +1. **Be more explicit** - Agents respond to clear, specific instructions: + - "Use EXACTLY these three steps..." + - "Do NOT include database migrations in this story" +2. **Check agent capabilities** - Agent might not have access to requested workflow +3. **Try different phrasing** - Rephrase request to be more direct +4. **Use menu system** - Numbers are clearer than text commands + +--- + +## Integration Issues (Brownfield) + +### Problem: New code conflicts with existing architecture + +**Symptoms:** + +- Integration approach doesn't fit existing structure +- Would require major refactoring +- Conflicts with established patterns + +**Solution:** + +1. **Check if document-project was run** - Agents need architecture context +2. **Review existing architecture docs**: + - Read docs/architecture.md (from document-project) + - Understand current system design +3. **For Level 3-4**: + - Run validate-architecture workflow before planning + - Use integration-planning workflow +4. **Explicitly document integration strategy** in architecture: + - How new components fit existing structure + - What modifications needed to existing code + - Migration path if changing patterns + +### Problem: Breaking changes to existing APIs + +**Symptoms:** + +- Changing API breaks consumers +- Downstream services affected +- Need backward compatibility + +**Solution:** + +1. **Identify all API consumers** (document-project should show this) +2. **Plan versioning strategy**: + - API v1 (existing) + v2 (new) + - Deprecation timeline +3. **Use feature flags** for gradual rollout +4. **Document migration guide** for API consumers +5. **Add to testing strategy**: + - Existing consumers still work (v1) + - New functionality works (v2) + +### Problem: Data migration required + +**Symptoms:** + +- Schema changes needed +- Existing data needs transformation +- Risk of data loss + +**Solution:** + +1. **Create explicit migration strategy** in architecture: + - Forward migration (old โ†’ new schema) + - Rollback plan (new โ†’ old schema) + - Data validation approach +2. **Test migrations thoroughly**: + - On copy of production data + - Measure performance impact +3. **Plan rollout**: + - Staging environment first + - Gradual production rollout + - Monitoring for issues +4. **Document in tech-spec/architecture**: + - Migration scripts + - Rollback procedures + - Expected downtime + +--- + +## Still Stuck? + +### Getting More Help + +If your issue isn't covered here: + +1. **Check other documentation**: + - [FAQ](./faq.md) - Common questions + - [Glossary](./glossary.md) - Terminology + - [Quick Start](./quick-start.md) - Basic usage + - [Brownfield Guide](./brownfield-guide.md) - Existing codebases + - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels + +2. **Community support**: + - [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues + - Active community, fast responses + - Share your specific situation + +3. **Report bugs**: + - [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) + - Include version, steps to reproduce, expected vs actual behavior + +4. **Video tutorials**: + - [YouTube Channel](https://www.youtube.com/@BMadCode) + - Visual walkthroughs of common workflows + +--- + +## Common Error Messages + +### "No workflow status file found" + +**Cause:** Haven't run workflow-init yet +**Fix:** Load Analyst agent โ†’ run workflow-init + +### "Epic file not found" + +**Cause:** PRD/epics not created, or wrong path +**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths + +### "Story not in sprint-status.yaml" + +**Cause:** Sprint-planning not run, or story file not created +**Fix:** Run sprint-planning workflow, verify story files exist + +### "Documentation insufficient for brownfield" + +**Cause:** No docs/index.md or document-project not run +**Fix:** Run document-project workflow with Deep scan + +### "Level detection failed" + +**Cause:** Ambiguous project description +**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.) + +### "Context generation failed" + +**Cause:** Missing prerequisites (epic context, story file, or docs) +**Fix:** Verify epic-tech-context run, story file exists, docs present + +--- + +## Prevention Tips + +**Avoid common issues before they happen:** + +1. โœ… **Always run document-project for brownfield** - Saves hours of context issues later +2. โœ… **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow +3. โœ… **Verify files exist before running workflows** - Check PRD, epics, stories are present +4. โœ… **Read agent menu before requesting workflows** - Confirm agent has the workflow +5. โœ… **Start with smaller level if unsure** - Easy to upgrade (Level 1 โ†’ 2), hard to downgrade +6. โœ… **Keep status files updated** - Manual updates when needed, don't let them drift +7. โœ… **Run retrospectives after epics** - Catch issues early, improve next epic +8. โœ… **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4) + +--- + +**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide! diff --git a/src/modules/bmm/docs/workflow-document-project-reference.md b/src/modules/bmm/docs/workflow-document-project-reference.md index 4948fa63..3bd8749e 100644 --- a/src/modules/bmm/docs/workflow-document-project-reference.md +++ b/src/modules/bmm/docs/workflow-document-project-reference.md @@ -57,7 +57,7 @@ Choose the right scan depth for your needs: - Initial understanding of project structure - Planning next steps before deeper analysis -**Does NOT read:** Source code files (_.js, _.ts, _.py, _.go, etc.) +**Does NOT read:** Source code files (`_.js`, `_.ts`, `_.py`, `_.go`, etc.) ### 2. Deep Scan diff --git a/src/modules/bmm/docs/workflows-implementation.md b/src/modules/bmm/docs/workflows-implementation.md index 39d6d591..16791617 100644 --- a/src/modules/bmm/docs/workflows-implementation.md +++ b/src/modules/bmm/docs/workflows-implementation.md @@ -70,7 +70,7 @@ For a visual representation of the complete workflow, see: [workflow-method-gree Stories move through these states in the sprint status file: 1. **TODO** - Story identified but not started -2. **IN PROGRESS** - Story being implemented (create-story โ†’ story-context โ†’ dev-story) +2. **IN PROGRESS** - Story being implemented (create-story โ†’ dev-story) 3. **READY FOR REVIEW** - Implementation complete, awaiting code review 4. **DONE** - Accepted and complete @@ -141,18 +141,59 @@ PRD (PM) โ†’ Architecture (Architect) โ†’ story loop (SM/DEV) โ†’ retrospective (SM) โ†’ [Next Epic] +Current Phase: 4 (Implementation) +Current Epic: Epic 1 (Authentication) +Current Sprint: Sprint 1 + +Next Story: Story 1.3 (Email Verification) +Status: TODO +Dependencies: Story 1.2 (DONE) โœ… + +**Recommendation:** Run `create-story` to generate Story 1.3 + +After create-story: +1. Run story-context +2. Run dev-story +3. Run code-review +4. Run story-done ``` +See: [workflow-status instructions](../workflows/workflow-status/instructions.md) + --- +### document-project + +**Purpose:** Analyze and document brownfield projects by scanning codebase, architecture, and patterns. + +**Agent:** Analyst +**Duration:** 1-3 hours +**When to Use:** Brownfield projects without documentation + +**How It Works:** + +1. Scans codebase structure +2. Identifies architecture patterns +3. Documents technology stack +4. Creates reference documentation +5. Generates PRD-like document from existing code + +**Output:** `project-documentation-{date}.md` + +**When to Run:** + +- Before starting work on legacy project +- When inheriting undocumented codebase +- Creating onboarding documentation + +See: [document-project reference](./workflow-document-project-reference.md) + ## Related Documentation - [Phase 1: Analysis Workflows](./workflows-analysis.md) - [Phase 2: Planning Workflows](./workflows-planning.md) - [Phase 3: Solutioning Workflows](./workflows-solutioning.md) ---- - ## Troubleshooting **Q: Which workflow should I run next?** @@ -167,6 +208,4 @@ A: Not recommended. Complete one story's full lifecycle before starting the next **Q: What if code review finds issues?** A: DEV runs `dev-story` to make fixes, re-runs tests, then runs `code-review` again until it passes. ---- - _Phase 4 Implementation - One story at a time, done right._ diff --git a/src/modules/bmm/_module-installer/install-config.yaml b/src/modules/bmm/module.yaml similarity index 100% rename from src/modules/bmm/_module-installer/install-config.yaml rename to src/modules/bmm/module.yaml diff --git a/src/modules/bmm/tasks/daily-standup.xml b/src/modules/bmm/tasks/daily-standup.xml new file mode 100644 index 00000000..d41c362c --- /dev/null +++ b/src/modules/bmm/tasks/daily-standup.xml @@ -0,0 +1,85 @@ + + + MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER + DO NOT skip steps or change the sequence + HALT immediately when halt-conditions are met + Each action tag within a step tag is a REQUIRED action to complete that step + Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution + + + + Check for stories folder at {project-root}{output_folder}/stories/ + Find current story by identifying highest numbered story file + Read story status (In Progress, Ready for Review, etc.) + Extract agent notes from Dev Agent Record, TEA Results, PO Notes sections + Check for next story references from epics + Identify blockers from story sections + + + + + ๐Ÿƒ DAILY STANDUP - Story-{{number}}: {{title}} + + Current Sprint Status: + - Active Story: story-{{number}} ({{status}} - {{percentage}}% complete) + - Next in Queue: story-{{next-number}}: {{next-title}} + - Blockers: {{blockers-from-story}} + + Team assembled based on story participants: + {{ List Agents from {project-root}/bmad/_cfg/agent-manifest.csv }} + + + + + Each agent provides three items referencing real story data + What I see: Their perspective on current work, citing story sections (1-2 sentences) + What concerns me: Issues from their domain or story blockers (1-2 sentences) + What I suggest: Actionable recommendations for progress (1-2 sentences) + + + + + ๐Ÿ“‹ STANDUP SUMMARY: + Key Items from Story File: + - {{completion-percentage}}% complete ({{tasks-complete}}/{{total-tasks}} tasks) + - Blocker: {{main-blocker}} + - Next: {{next-story-reference}} + + Action Items: + - {{agent}}: {{action-item}} + - {{agent}}: {{action-item}} + - {{agent}}: {{action-item}} + + Need extended discussion? Use *party-mode for detailed breakout. + + + + + + + Primary: Sarah (PO), Mary (Analyst), Winston (Architect) + Secondary: Murat (TEA), James (Dev) + + + Primary: Sarah (PO), Bob (SM), James (Dev) + Secondary: Murat (TEA) + + + Primary: Winston (Architect), James (Dev), Murat (TEA) + Secondary: Sarah (PO) + + + Primary: James (Dev), Murat (TEA), Winston (Architect) + Secondary: Sarah (PO) + + + + + This task extends party-mode with agile-specific structure + Time-box responses (standup = brief) + Focus on actionable items from real story data when available + End with clear next steps + No deep dives (suggest breakout if needed) + If no stories folder detected, run general standup format + + \ No newline at end of file diff --git a/src/modules/bmm/testarch/knowledge/ci-burn-in.md b/src/modules/bmm/testarch/knowledge/ci-burn-in.md index 65d40695..b907c906 100644 --- a/src/modules/bmm/testarch/knowledge/ci-burn-in.md +++ b/src/modules/bmm/testarch/knowledge/ci-burn-in.md @@ -662,7 +662,7 @@ Before deploying your CI pipeline, verify: - [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts - [ ] **Parallelization**: Matrix strategy uses fail-fast: false - [ ] **Burn-in enabled**: Changed specs run 5-10x before merge -- [ ] **wait-on app startup**: CI waits for app (wait-on: 'http://localhost:3000') +- [ ] **wait-on app startup**: CI waits for app (wait-on: '') - [ ] **Secrets documented**: README lists required secrets (API keys, tokens) - [ ] **Local parity**: CI scripts runnable locally (npm run test:ci) diff --git a/src/modules/bmm/testarch/knowledge/overview.md b/src/modules/bmm/testarch/knowledge/overview.md index 3a60e349..5fbb9801 100644 --- a/src/modules/bmm/testarch/knowledge/overview.md +++ b/src/modules/bmm/testarch/knowledge/overview.md @@ -262,7 +262,7 @@ import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments. -**Repository:** https://github.com/seontechnologies/playwright-utils +**Repository:** **Key resources:** diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md index b0197f62..e8743d5a 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-01-init.md @@ -25,7 +25,7 @@ - **Research topic = "{{research_topic}}"** - discovered from initial discussion - **Research goals = "{{research_goals}}"** - captured from initial discussion - Focus on industry/domain analysis with web research -- Web search capabilities with {{current_year}} data are enabled +- Web search is required to verify and supplement your knowledge with current facts ## YOUR TASK: @@ -48,7 +48,7 @@ Start with domain scope understanding: **Research Approach:** -- Current {{current_year}} web data with rigorous source verification +- All claims verified against current public sources - Multi-source validation for critical domain claims - Confidence levels for uncertain domain information - Comprehensive domain coverage with industry-specific insights @@ -66,7 +66,7 @@ For **{{research_topic}}**, I will research: โœ… **Economic Factors** - market size, growth projections, economic impact โœ… **Supply Chain Analysis** - value chain, ecosystem, partnerships -**All using current {{current_year}} web data with source verification.** +**All claims verified against current public sources.** **Does this domain research scope and approach align with your goals?** [C] Continue - Begin domain research with this scope @@ -77,7 +77,7 @@ For **{{research_topic}}**, I will research: - Document scope confirmation in research file - Update frontmatter: `stepsCompleted: [1]` -- Load: `./step-02-industry-analysis.md` +- Load: `./step-02-domain-analysis.md` ## APPEND TO DOCUMENT: @@ -99,7 +99,7 @@ When user selects 'C', append scope confirmation: **Research Methodology:** -- Current {{current_year}} web data with rigorous source verification +- All claims verified against current public sources - Multi-source validation for critical domain claims - Confidence level framework for uncertain information - Comprehensive domain coverage with industry-specific insights @@ -111,7 +111,7 @@ When user selects 'C', append scope confirmation: โœ… Domain research scope clearly confirmed with user โœ… All domain analysis areas identified and explained -โœ… Research methodology with {{current_year}} data emphasized +โœ… Research methodology emphasized โœ… [C] continue option presented and handled correctly โœ… Scope confirmation documented when user proceeds โœ… Proper routing to next domain research step @@ -120,7 +120,7 @@ When user selects 'C', append scope confirmation: โŒ Not clearly confirming domain research scope with user โŒ Missing critical domain analysis areas -โŒ Not emphasizing {{current_year}} web data requirement +โŒ Not explaining that web search is required for current facts โŒ Not presenting [C] continue option โŒ Proceeding without user scope confirmation โŒ Not routing to next domain research step @@ -131,6 +131,6 @@ When user selects 'C', append scope confirmation: ## NEXT STEP: -After user selects 'C', load `./step-02-industry-analysis.md` to begin industry analysis with current {{current_year}} web data. +After user selects 'C', load `./step-02-domain-analysis.md` to begin industry analysis. Remember: This is SCOPE CONFIRMATION ONLY - no actual domain research yet, just confirming the research approach and scope! diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md index 505ddabc..941ed423 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current industry data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE AN INDUSTRY ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on market size, growth, and industry dynamics -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,7 +31,7 @@ ## YOUR TASK: -Conduct industry analysis focusing on market size, growth, and industry dynamics using current {{current_year}} web data with rigorous source verification. +Conduct industry analysis focusing on market size, growth, and industry dynamics. Search the web to verify and supplement current facts. ## INDUSTRY ANALYSIS SEQUENCE: @@ -40,7 +40,7 @@ Conduct industry analysis focusing on market size, growth, and industry dynamics **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different industry areas simultaneously and thoroughly. Start with industry research approach: -"Now I'll conduct **industry analysis** for **{{research_topic}}** using current {{current_year}} web data to understand market dynamics. +"Now I'll conduct **industry analysis** for **{{research_topic}}** to understand market dynamics. **Industry Analysis Focus:** @@ -56,10 +56,10 @@ Start with industry research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} market size value {{current_year}}"` -`WebSearch: "{{research_topic}} market growth rate dynamics {{current_year}}"` -`WebSearch: "{{research_topic}} market segmentation structure {{current_year}}"` -`WebSearch: "{{research_topic}} industry trends evolution {{current_year}}"` +Search the web: "{{research_topic}} market size value" +Search the web: "{{research_topic}} market growth rate dynamics" +Search the web: "{{research_topic}} market segmentation structure" +Search the web: "{{research_topic}} industry trends evolution" **Analysis approach:** @@ -104,11 +104,11 @@ When saving to document, append these Level 2 and Level 3 sections: ### Market Size and Valuation [Market size analysis with source citations] -_Total Market Size: [Current market valuation with {{current_year}} data]_ +_Total Market Size: [Current market valuation]_ _Growth Rate: [CAGR and market growth projections]_ _Market Segments: [Size and value of key market segments]_ _Economic Impact: [Economic contribution and value creation]_ -_Source: [URL with {{current_year}} market size data]_ +_Source: [URL]_ ### Market Dynamics and Growth @@ -117,7 +117,7 @@ _Growth Drivers: [Key factors driving market growth]_ _Growth Barriers: [Factors limiting market expansion]_ _Cyclical Patterns: [Industry seasonality and cycles]_ _Market Maturity: [Life cycle stage and development phase]_ -_Source: [URL with {{current_year}} market dynamics data]_ +_Source: [URL]_ ### Market Structure and Segmentation @@ -126,7 +126,7 @@ _Primary Segments: [Key market segments and their characteristics]_ _Sub-segment Analysis: [Detailed breakdown of market sub-segments]_ _Geographic Distribution: [Regional market variations and concentrations]_ _Vertical Integration: [Supply chain and value chain structure]_ -_Source: [URL with {{current_year}} market structure data]_ +_Source: [URL]_ ### Industry Trends and Evolution @@ -135,7 +135,7 @@ _Emerging Trends: [Current industry developments and transformations]_ _Historical Evolution: [Industry development over recent years]_ _Technology Integration: [How technology is changing the industry]_ _Future Outlook: [Projected industry developments and changes]_ -_Source: [URL with {{current_year}} industry trends data]_ +_Source: [URL]_ ### Competitive Dynamics @@ -144,14 +144,14 @@ _Market Concentration: [Level of market consolidation and competition]_ _Competitive Intensity: [Degree of competition and rivalry]_ _Barriers to Entry: [Obstacles for new market entrants]_ _Innovation Pressure: [Rate of innovation and change]_ -_Source: [URL with {{current_year}} competitive dynamics data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **industry analysis** using current {{current_year}} data to understand market dynamics for {{research_topic}}. +"I've completed **industry analysis** for {{research_topic}}. **Key Industry Findings:** @@ -190,7 +190,7 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in industry web searches +โŒ Relying on training data instead of web search for current facts โŒ Missing critical market size or growth data โŒ Incomplete market structure analysis โŒ Not identifying key industry trends @@ -208,7 +208,7 @@ Content is already written to document when generated in step 4. No additional a - Use authoritative sources (market research firms, industry associations) - Analyze market size, growth rates, and segmentation data - Study industry trends and evolution patterns -- Focus on current {{current_year}} industry data +- Search the web to verify facts - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -225,4 +225,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-03-competitive-landscape.md` to analyze competitive landscape, key players, and ecosystem analysis for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} industry data with rigorous source verification! +Remember: Always write research content to document immediately and search the web to verify facts! diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md index fd81f04c..4efc4a5b 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current competitive data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A COMPETITIVE ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on key players, market share, and competitive dynamics -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,7 +31,7 @@ ## YOUR TASK: -Conduct competitive landscape analysis focusing on key players, market share, and competitive dynamics using current {{current_year}} web data with rigorous source verification. +Conduct competitive landscape analysis focusing on key players, market share, and competitive dynamics. Search the web to verify and supplement current facts. ## COMPETITIVE LANDSCAPE ANALYSIS SEQUENCE: @@ -40,7 +40,7 @@ Conduct competitive landscape analysis focusing on key players, market share, an **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different competitive areas simultaneously and thoroughly. Start with competitive research approach: -"Now I'll conduct **competitive landscape analysis** for **{{research_topic}}** using current {{current_year}} web data to understand the competitive ecosystem. +"Now I'll conduct **competitive landscape analysis** for **{{research_topic}}** to understand the competitive ecosystem. **Competitive Landscape Focus:** @@ -56,10 +56,10 @@ Start with competitive research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} key players market leaders {{current_year}}"` -`WebSearch: "{{research_topic}} market share competitive landscape {{current_year}}"` -`WebSearch: "{{research_topic}} competitive strategies differentiation {{current_year}}"` -`WebSearch: "{{research_topic}} entry barriers competitive dynamics {{current_year}}"` +Search the web: "{{research_topic}} key players market leaders" +Search the web: "{{research_topic}} market share competitive landscape" +Search the web: "{{research_topic}} competitive strategies differentiation" +Search the web: "{{research_topic}} entry barriers competitive dynamics" **Analysis approach:** @@ -108,7 +108,7 @@ _Market Leaders: [Dominant players and their market positions]_ _Major Competitors: [Significant competitors and their specialties]_ _Emerging Players: [New entrants and innovative companies]_ _Global vs Regional: [Geographic distribution of key players]_ -_Source: [URL with {{current_year}} competitive data]_ +_Source: [URL]_ ### Market Share and Competitive Positioning @@ -117,7 +117,7 @@ _Market Share Distribution: [Current market share breakdown]_ _Competitive Positioning: [How players position themselves in the market]_ _Value Proposition Mapping: [Different value propositions across players]_ _Customer Segments Served: [Different customer bases by competitor]_ -_Source: [URL with {{current_year}} market share data]_ +_Source: [URL]_ ### Competitive Strategies and Differentiation @@ -126,7 +126,7 @@ _Cost Leadership Strategies: [Players competing on price and efficiency]_ _Differentiation Strategies: [Players competing on unique value]_ _Focus/Niche Strategies: [Players targeting specific segments]_ _Innovation Approaches: [How different players innovate]_ -_Source: [URL with {{current_year}} competitive strategies data]_ +_Source: [URL]_ ### Business Models and Value Propositions @@ -135,7 +135,7 @@ _Primary Business Models: [How competitors make money]_ _Revenue Streams: [Different approaches to monetization]_ _Value Chain Integration: [Vertical integration vs partnership models]_ _Customer Relationship Models: [How competitors build customer loyalty]_ -_Source: [URL with {{current_year}} business models data]_ +_Source: [URL]_ ### Competitive Dynamics and Entry Barriers @@ -144,7 +144,7 @@ _Barriers to Entry: [Obstacles facing new market entrants]_ _Competitive Intensity: [Level of rivalry and competitive pressure]_ _Market Consolidation Trends: [M&A activity and market concentration]_ _Switching Costs: [Costs for customers to switch between providers]_ -_Source: [URL with {{current_year}} competitive dynamics data]_ +_Source: [URL]_ ### Ecosystem and Partnership Analysis @@ -153,14 +153,14 @@ _Supplier Relationships: [Key supplier partnerships and dependencies]_ _Distribution Channels: [How competitors reach customers]_ _Technology Partnerships: [Strategic technology alliances]_ _Ecosystem Control: [Who controls key parts of the value chain]_ -_Source: [URL with {{current_year}} ecosystem data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **competitive landscape analysis** using current {{current_year}} data to understand the competitive ecosystem for {{research_topic}}. +"I've completed **competitive landscape analysis** for {{research_topic}}. **Key Competitive Findings:** @@ -199,7 +199,7 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in competitive web searches +โŒ Relying on training data instead of web search for current facts โŒ Missing critical key players or market leaders โŒ Incomplete market share or positioning analysis โŒ Not identifying competitive strategies @@ -217,7 +217,7 @@ Content is already written to document when generated in step 4. No additional a - Use company websites, annual reports, and investor presentations - Analyze market share data and competitive positioning - Study competitive strategies and differentiation approaches -- Focus on current {{current_year}} competitive data +- Search the web to verify facts - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -234,4 +234,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-04-regulatory-focus.md` to analyze regulatory requirements, compliance frameworks, and legal considerations for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} competitive data with rigorous source verification! +Remember: Always write research content to document immediately and search the web to verify facts! diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md index 8fb18f2f..db7bcb71 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current regulatory data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A REGULATORY ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on compliance requirements and regulatory landscape -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,14 +31,14 @@ ## YOUR TASK: -Conduct focused regulatory and compliance analysis using current {{current_year}} web data with emphasis on requirements that impact {{research_topic}}. +Conduct focused regulatory and compliance analysis with emphasis on requirements that impact {{research_topic}}. Search the web to verify and supplement current facts. ## REGULATORY FOCUS SEQUENCE: ### 1. Begin Regulatory Analysis Start with regulatory research approach: -"Now I'll focus on **regulatory and compliance requirements** that impact **{{research_topic}}** using current {{current_year}} data. +"Now I'll focus on **regulatory and compliance requirements** that impact **{{research_topic}}**. **Regulatory Focus Areas:** @@ -53,7 +53,7 @@ Start with regulatory research approach: ### 2. Web Search for Specific Regulations Search for current regulatory information: -`WebSearch: "{{research_topic}} regulations compliance requirements {{current_year}}"` +Search the web: "{{research_topic}} regulations compliance requirements" **Regulatory focus:** @@ -65,7 +65,7 @@ Search for current regulatory information: ### 3. Web Search for Industry Standards Search for current industry standards: -`WebSearch: "{{research_topic}} standards best practices {{current_year}}"` +Search the web: "{{research_topic}} standards best practices" **Standards focus:** @@ -77,7 +77,7 @@ Search for current industry standards: ### 4. Web Search for Data Privacy Requirements Search for current privacy regulations: -`WebSearch: "data privacy regulations {{research_topic}} {{current_year}}"` +Search the web: "data privacy regulations {{research_topic}}" **Privacy focus:** @@ -100,32 +100,32 @@ When saving to document, append these Level 2 and Level 3 sections: ### Applicable Regulations [Specific regulations analysis with source citations] -_Source: [URL with {{current_year}} regulatory data]_ +_Source: [URL]_ ### Industry Standards and Best Practices [Industry standards analysis with source citations] -_Source: [URL with {{current_year}} standards data]_ +_Source: [URL]_ ### Compliance Frameworks [Compliance frameworks analysis with source citations] -_Source: [URL with {{current_year}} compliance data]_ +_Source: [URL]_ ### Data Protection and Privacy [Privacy requirements analysis with source citations] -_Source: [URL with {{current_year}} privacy data]_ +_Source: [URL]_ ### Licensing and Certification [Licensing requirements analysis with source citations] -_Source: [URL with {{current_year}} licensing data]_ +_Source: [URL]_ ### Implementation Considerations [Practical implementation considerations with source citations] -_Source: [URL with {{current_year}} implementation data]_ +_Source: [URL]_ ### Risk Assessment @@ -135,7 +135,7 @@ _Source: [URL with {{current_year}} implementation data]_ ### 6. Present Analysis and Continue Option Show the generated regulatory analysis and present continue option: -"I've completed **regulatory requirements analysis** using current {{current_year}} data to understand compliance requirements for {{research_topic}}. +"I've completed **regulatory requirements analysis** for {{research_topic}}. **Key Regulatory Findings:** @@ -162,7 +162,7 @@ Content is already written to document when generated in step 5. No additional a ## SUCCESS METRICS: -โœ… Applicable regulations identified with current {{current_year}} citations +โœ… Applicable regulations identified with current citations โœ… Industry standards and best practices documented โœ… Compliance frameworks clearly mapped โœ… Data protection requirements analyzed @@ -172,7 +172,7 @@ Content is already written to document when generated in step 5. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in regulatory web searches +โŒ Relying on training data instead of web search for current facts โŒ Missing critical regulatory requirements for the domain โŒ Not providing implementation considerations for compliance โŒ Not completing risk assessment for regulatory compliance @@ -200,6 +200,6 @@ Content is already written to document when generated in step 5. No additional a ## NEXT STEP: -After user selects 'C' and content is saved to document, load `./step-04-technical-trends.md` to analyze technical trends and innovations in the domain. +After user selects 'C' and content is saved to document, load `./step-05-technical-trends.md` to analyze technical trends and innovations in the domain. -Remember: Always emphasize current {{current_year}} regulatory data and practical implementation considerations! +Remember: Search the web to verify regulatory facts and provide practical implementation considerations! diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md index 7ee55070..ba46ebb8 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current technical data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A TECHNOLOGY ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on emerging technologies and innovation patterns -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,14 +31,14 @@ ## YOUR TASK: -Conduct comprehensive technical trends analysis using current {{current_year}} web data with emphasis on innovations and emerging technologies impacting {{research_topic}}. +Conduct comprehensive technical trends analysis using current web data with emphasis on innovations and emerging technologies impacting {{research_topic}}. ## TECHNICAL TRENDS SEQUENCE: ### 1. Begin Technical Trends Analysis Start with technology research approach: -"Now I'll conduct **technical trends and emerging technologies** analysis for **{{research_topic}}** using current {{current_year}} data. +"Now I'll conduct **technical trends and emerging technologies** analysis for **{{research_topic}}** using current data. **Technical Trends Focus:** @@ -53,7 +53,7 @@ Start with technology research approach: ### 2. Web Search for Emerging Technologies Search for current technology information: -`WebSearch: "{{research_topic}} emerging technologies innovations {{current_year}}"` +Search the web: "{{research_topic}} emerging technologies innovations" **Technology focus:** @@ -65,7 +65,7 @@ Search for current technology information: ### 3. Web Search for Digital Transformation Search for current transformation trends: -`WebSearch: "{{research_topic}} digital transformation {{current_year}}"` +Search the web: "{{research_topic}} digital transformation trends" **Transformation focus:** @@ -77,7 +77,7 @@ Search for current transformation trends: ### 4. Web Search for Future Outlook Search for future projections: -`WebSearch: "{{research_topic}} future outlook {{current_year}} 2025"` +Search the web: "{{research_topic}} future outlook trends" **Future focus:** @@ -102,32 +102,32 @@ When saving to document, append these Level 2 and Level 3 sections: ### Emerging Technologies [Emerging technologies analysis with source citations] -_Source: [URL with {{current_year}} technology data]_ +_Source: [URL]_ ### Digital Transformation [Digital transformation analysis with source citations] -_Source: [URL with {{current_year}} transformation data]_ +_Source: [URL]_ ### Innovation Patterns [Innovation patterns analysis with source citations] -_Source: [URL with {{current_year}} innovation data]_ +_Source: [URL]_ ### Future Outlook [Future outlook and projections with source citations] -_Source: [URL with {{current_year}} outlook data]_ +_Source: [URL]_ ### Implementation Opportunities [Implementation opportunity analysis with source citations] -_Source: [URL with {{current_year}} implementation data]_ +_Source: [URL]_ ### Challenges and Risks [Challenges and risks assessment with source citations] -_Source: [URL with {{current_year}} risk data]_ +_Source: [URL]_ ## Recommendations @@ -147,7 +147,7 @@ _Source: [URL with {{current_year}} risk data]_ ### 6. Present Analysis and Complete Option Show the generated technical analysis and present complete option: -"I've completed **technical trends and innovation analysis** using current {{current_year}} data to understand technology patterns for {{research_topic}}. +"I've completed **technical trends and innovation analysis** for {{research_topic}}. **Technical Highlights:** @@ -181,7 +181,7 @@ Content is already written to document when generated in step 5. No additional a ## SUCCESS METRICS: -โœ… Emerging technologies identified with current {{current_year}} data +โœ… Emerging technologies identified with current data โœ… Digital transformation trends clearly documented โœ… Future outlook and projections analyzed โœ… Implementation opportunities and challenges mapped @@ -193,7 +193,7 @@ Content is already written to document when generated in step 5. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in technology web searches +โŒ Relying solely on training data without web verification for current facts โŒ Missing critical emerging technologies in the domain โŒ Not providing practical implementation recommendations โŒ Not completing strategic recommendations @@ -230,4 +230,4 @@ Research workflow complete. User may: - Conduct additional research on specific topics if needed - Move forward with product development based on research insights -Congratulations on completing comprehensive domain research with current {{current_year}} data! ๐ŸŽ‰ +Congratulations on completing comprehensive domain research! ๐ŸŽ‰ diff --git a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md index bb31f3f8..8ce2eee5 100644 --- a/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md +++ b/src/modules/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current domain data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A DOMAIN RESEARCH STRATEGIST, not content generator - ๐Ÿ’ฌ FOCUS on comprehensive synthesis and authoritative conclusions -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“„ PRODUCE COMPREHENSIVE DOCUMENT with narrative intro, TOC, and summary ## EXECUTION PROTOCOLS: @@ -72,7 +72,7 @@ Produce a comprehensive, authoritative research document on **{{research_topic}} - Set professional, authoritative tone **Web Search for Introduction Context:** -`WebSearch: "{{research_topic}} significance importance {{current_year}}"` +Search the web: "{{research_topic}} significance importance" ### 3. Synthesize All Research Sections @@ -93,7 +93,7 @@ Produce a comprehensive, authoritative research document on **{{research_topic}} ## Executive Summary -[2-3 paragraph compelling summary of the most critical findings and strategic implications for {{research_topic}} based on comprehensive {{current_year}} research] +[2-3 paragraph compelling summary of the most critical findings and strategic implications for {{research_topic}} based on comprehensive current research] **Key Findings:** @@ -123,9 +123,9 @@ Produce a comprehensive, authoritative research document on **{{research_topic}} ### Research Significance -[Compelling narrative about why {{research_topic}} research is critical in {{current_year}}] -_Why this research matters now: [Strategic importance with {{current_year}} context]_ -_Source: [URL with {{current_year}} industry significance data]_ +[Compelling narrative about why {{research_topic}} research is critical right now] +_Why this research matters now: [Strategic importance with current context]_ +_Source: [URL]_ ### Research Methodology @@ -134,7 +134,7 @@ _Source: [URL with {{current_year}} industry significance data]_ - **Research Scope**: [Comprehensive coverage areas] - **Data Sources**: [Authoritative sources and verification approach] - **Analysis Framework**: [Structured analysis methodology] -- **Time Period**: [{{current_year}} focus and historical context] +- **Time Period**: [current focus and historical context] - **Geographic Coverage**: [Regional/global scope] ### Research Goals and Objectives @@ -151,11 +151,11 @@ _Source: [URL with {{current_year}} industry significance data]_ ### Market Size and Growth Projections -[Comprehensive market analysis synthesized from step-02 with {{current_year}} data] +[Comprehensive market analysis synthesized from step-02 with current data] _Market Size: [Current market valuation]_ _Growth Rate: [CAGR and projections]_ _Market Drivers: [Key growth factors]_ -_Source: [URL with {{current_year}} market data]_ +_Source: [URL]_ ### Industry Structure and Value Chain @@ -163,17 +163,17 @@ _Source: [URL with {{current_year}} market data]_ _Value Chain Components: [Detailed breakdown]_ _Industry Segments: [Market segmentation analysis]_ _Economic Impact: [Industry economic significance]_ -_Source: [URL with {{current_year}} industry structure data]_ +_Source: [URL]_ ## 3. Technology Landscape and Innovation Trends ### Current Technology Adoption -[Technology trends analysis from step-04 with {{current_year}} context] +[Technology trends analysis from step-04 with current context] _Emerging Technologies: [Key technologies affecting {{research_topic}}]_ _Adoption Patterns: [Technology adoption rates and patterns]_ _Innovation Drivers: [Factors driving technology change]_ -_Source: [URL with {{current_year}} technology data]_ +_Source: [URL]_ ### Digital Transformation Impact @@ -181,17 +181,17 @@ _Source: [URL with {{current_year}} technology data]_ _Transformation Trends: [Major digital transformation patterns]_ _Disruption Opportunities: [Technology-driven opportunities]_ _Future Technology Outlook: [Emerging technologies and timelines]_ -_Source: [URL with {{current_year}} digital transformation data]_ +_Source: [URL]_ ## 4. Regulatory Framework and Compliance Requirements ### Current Regulatory Landscape -[Regulatory analysis from step-03 with {{current_year}} updates] +[Regulatory analysis from step-03 with current updates] _Key Regulations: [Critical regulatory requirements]_ _Compliance Standards: [Industry standards and best practices]_ -_Recent Changes: [{{current_year}} regulatory updates and implications]_ -_Source: [URL with {{current_year}} regulatory data]_ +_Recent Changes: [current regulatory updates and implications]_ +_Source: [URL]_ ### Risk and Compliance Considerations @@ -199,17 +199,17 @@ _Source: [URL with {{current_year}} regulatory data]_ _Compliance Risks: [Major regulatory and compliance risks]_ _Risk Mitigation Strategies: [Approaches to manage regulatory risks]_ _Future Regulatory Trends: [Anticipated regulatory developments]_ -_Source: [URL with {{current_year}} compliance data]_ +_Source: [URL]_ ## 5. Competitive Landscape and Ecosystem Analysis ### Market Positioning and Key Players -[Competitive analysis with {{current_year}} market positioning] +[Competitive analysis with current market positioning] _Market Leaders: [Dominant players and strategies]_ _Emerging Competitors: [New entrants and innovative approaches]_ _Competitive Dynamics: [Market competition patterns and trends]_ -_Source: [URL with {{current_year}} competitive data]_ +_Source: [URL]_ ### Ecosystem and Partnership Landscape @@ -217,7 +217,7 @@ _Source: [URL with {{current_year}} competitive data]_ _Ecosystem Players: [Key stakeholders and relationships]_ _Partnership Opportunities: [Strategic collaboration potential]_ _Supply Chain Dynamics: [Supply chain structure and risks]_ -_Source: [URL with {{current_year}} ecosystem data]_ +_Source: [URL]_ ## 6. Strategic Insights and Domain Opportunities @@ -227,7 +227,7 @@ _Source: [URL with {{current_year}} ecosystem data]_ _Market-Technology Convergence: [How technology and market forces interact]_ _Regulatory-Strategic Alignment: [How regulatory environment shapes strategy]_ _Competitive Positioning Opportunities: [Strategic advantages based on research]_ -_Source: [URL with {{current_year}} strategic analysis data]_ +_Source: [URL]_ ### Strategic Opportunities @@ -235,7 +235,7 @@ _Source: [URL with {{current_year}} strategic analysis data]_ _Market Opportunities: [Specific market entry or expansion opportunities]_ _Technology Opportunities: [Technology adoption or innovation opportunities]_ _Partnership Opportunities: [Strategic collaboration and partnership potential]_ -_Source: [URL with {{current_year}} opportunity data]_ +_Source: [URL]_ ## 7. Implementation Considerations and Risk Assessment @@ -245,7 +245,7 @@ _Source: [URL with {{current_year}} opportunity data]_ _Implementation Timeline: [Recommended phased approach]_ _Resource Requirements: [Key resources and capabilities needed]_ _Success Factors: [Critical success factors for implementation]_ -_Source: [URL with {{current_year}} implementation data]_ +_Source: [URL]_ ### Risk Management and Mitigation @@ -253,7 +253,7 @@ _Source: [URL with {{current_year}} implementation data]_ _Implementation Risks: [Major risks and mitigation approaches]_ _Market Risks: [Market-related risks and contingency plans]_ _Technology Risks: [Technology adoption and implementation risks]_ -_Source: [URL with {{current_year}} risk management data]_ +_Source: [URL]_ ## 8. Future Outlook and Strategic Planning @@ -263,7 +263,7 @@ _Source: [URL with {{current_year}} risk management data]_ _Near-term Outlook: [1-2 year projections and implications]_ _Medium-term Trends: [3-5 year expected developments]_ _Long-term Vision: [5+ year strategic outlook for {{research_topic}}]_ -_Source: [URL with {{current_year}} future outlook data]_ +_Source: [URL]_ ### Strategic Recommendations @@ -271,7 +271,7 @@ _Source: [URL with {{current_year}} future outlook data]_ _Immediate Actions: [Priority actions for next 6 months]_ _Strategic Initiatives: [Key strategic initiatives for 1-2 years]_ _Long-term Strategy: [Strategic positioning for 3+ years]_ -_Source: [URL with {{current_year}} strategic planning data]_ +_Source: [URL]_ ## 9. Research Methodology and Source Verification @@ -281,7 +281,6 @@ _Source: [URL with {{current_year}} strategic planning data]_ _Primary Sources: [Key authoritative sources used]_ _Secondary Sources: [Supporting research and analysis]_ _Web Search Queries: [Complete list of search queries used]_ -_Data Currency: [All data verified for {{current_year}} currency]_ ### Research Quality Assurance @@ -327,9 +326,9 @@ _Professional Networks: [Industry communities and knowledge sources]_ --- **Research Completion Date:** {{date}} -**Research Period:** {{current_year}} comprehensive analysis +**Research Period:** Comprehensive analysis **Document Length:** As needed for comprehensive coverage -**Source Verification:** All facts cited with {{current_year}} sources +**Source Verification:** All facts cited with sources **Confidence Level:** High - based on multiple authoritative sources _This comprehensive research document serves as an authoritative reference on {{research_topic}} and provides strategic insights for informed decision-making._ @@ -348,7 +347,7 @@ _This comprehensive research document serves as an authoritative reference on {{ - **Exhaustive Research Coverage**: All aspects of {{research_topic}} thoroughly analyzed - **Executive Summary**: Key findings and strategic implications highlighted - **Strategic Recommendations**: Actionable insights based on comprehensive research -- **Complete Source Citations**: Every factual claim verified with {{current_year}} sources +- **Complete Source Citations**: Every factual claim verified with sources **Research Completeness:** @@ -364,7 +363,7 @@ _This comprehensive research document serves as an authoritative reference on {{ - Professional structure and compelling narrative - As long as needed for comprehensive coverage - Multiple independent sources for all claims -- {{current_year}} data throughout with proper citations +- Proper citations throughout **Ready to complete this comprehensive research document?** [C] Complete Research - Save final comprehensive document @@ -389,7 +388,7 @@ When user selects 'C', append the complete comprehensive research document using โœ… Exhaustive research coverage across all domain aspects โœ… Executive summary with key findings and strategic implications โœ… Strategic recommendations grounded in comprehensive research -โœ… Complete source verification with {{current_year}} citations +โœ… Complete source verification with citations โœ… Professional document structure and compelling narrative โœ… [C] complete option presented and handled correctly โœ… Domain research workflow completed with comprehensive document @@ -401,7 +400,7 @@ When user selects 'C', append the complete comprehensive research document using โŒ Incomplete research coverage across domain aspects โŒ Not providing executive summary with key findings โŒ Missing strategic recommendations based on research -โŒ Not using {{current_year}} sources for all factual claims +โŒ Relying solely on training data without web verification for current facts โŒ Producing document without professional structure โŒ Not presenting completion option for final document @@ -438,6 +437,6 @@ Complete authoritative research document on {{research_topic}} that: - Establishes professional credibility through comprehensive research - Provides strategic insights for informed decision-making - Serves as reference document for continued use -- Maintains highest research quality standards with {{current_year}} verification +- Maintains highest research quality standards -Congratulations on completing comprehensive domain research with professional documentation! ๐ŸŽ‰ +Congratulations on completing comprehensive domain research! ๐ŸŽ‰ diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-01-init.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-01-init.md index 6feb3ff3..c1bf6262 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-01-init.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-01-init.md @@ -44,8 +44,8 @@ Start with research confirmation: - **Research Topic**: {{research_topic}} - **Research Goals**: {{research_goals}} -- **Research Type**: Market Research using current {{current_year}} data -- **Approach**: Comprehensive market analysis with rigorous source verification +- **Research Type**: Market Research +- **Approach**: Comprehensive market analysis with source verification **Market Research Areas We'll Cover:** @@ -83,7 +83,6 @@ Write initial research scope to document: **Topic**: {{research_topic}} **Goals**: {{research_goals}} **Research Type**: Market Research -**Data Currency**: {{current_year}} with rigorous source verification **Date**: {{date}} ### Research Scope @@ -97,7 +96,7 @@ Write initial research scope to document: **Research Methodology:** -- Current {{current_year}} web data with source verification +- Current web data with source verification - Multiple independent sources for critical claims - Confidence level assessment for uncertain data - Comprehensive coverage with no critical gaps @@ -123,7 +122,7 @@ Show initial scope document and present continue option: - Research topic and goals confirmed - Market analysis focus areas defined -- Research methodology with {{current_year}} data verification +- Research methodology verification - Clear workflow progression **Document Status:** Initial scope written to research file for your review @@ -177,6 +176,6 @@ This step ensures: ## NEXT STEP: -After user confirmation and scope finalization, load `./step-02-customer-insights.md` to begin detailed market research with customer insights analysis using {{current_year}} data and rigorous source verification. +After user confirmation and scope finalization, load `./step-02-customer-insights.md` to begin detailed market research with customer insights analysis. Remember: Init steps confirm understanding and scope, not generate research content! diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-behavior.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-behavior.md index 4bc6e905..330dd2f0 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-behavior.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-behavior.md @@ -3,10 +3,10 @@ ## MANDATORY EXECUTION RULES (READ FIRST): - ๐Ÿ›‘ NEVER generate content without web search verification -- โœ… ALWAYS use {{current_year}} web searches for current customer data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A CUSTOMER BEHAVIOR ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on customer behavior patterns and demographic analysis -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete research - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding @@ -31,7 +31,7 @@ ## YOUR TASK: -Conduct customer behavior and segment analysis using current {{current_year}} web data with emphasis on patterns and demographics. +Conduct customer behavior and segment analysis with emphasis on patterns and demographics. ## CUSTOMER BEHAVIOR ANALYSIS SEQUENCE: @@ -40,7 +40,7 @@ Conduct customer behavior and segment analysis using current {{current_year}} we **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer behavior areas simultaneously and thoroughly. Start with customer behavior research approach: -"Now I'll conduct **customer behavior analysis** for **{{research_topic}}** using current {{current_year}} web data to understand customer patterns. +"Now I'll conduct **customer behavior analysis** for **{{research_topic}}** to understand customer patterns. **Customer Behavior Focus:** @@ -56,10 +56,10 @@ Start with customer behavior research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} customer behavior patterns {{current_year}}"` -`WebSearch: "{{research_topic}} customer demographics {{current_year}}"` -`WebSearch: "{{research_topic}} psychographic profiles {{current_year}}"` -`WebSearch: "{{research_topic}} customer behavior drivers {{current_year}}"` +Search the web: "{{research_topic}} customer behavior patterns" +Search the web: "{{research_topic}} customer demographics" +Search the web: "{{research_topic}} psychographic profiles" +Search the web: "{{research_topic}} customer behavior drivers" **Analysis approach:** @@ -108,7 +108,7 @@ When saving to document, append these Level 2 and Level 3 sections: _Behavior Drivers: [Key motivations and patterns from web search]_ _Interaction Preferences: [Customer engagement and interaction patterns]_ _Decision Habits: [How customers typically make decisions]_ -_Source: [URL with {{current_year}} customer behavior data]_ +_Source: [URL]_ ### Demographic Segmentation @@ -117,7 +117,7 @@ _Age Demographics: [Age groups and preferences]_ _Income Levels: [Income segments and purchasing behavior]_ _Geographic Distribution: [Regional/city differences]_ _Education Levels: [Education impact on behavior]_ -_Source: [URL with {{current_year}} demographic data]_ +_Source: [URL]_ ### Psychographic Profiles @@ -126,7 +126,7 @@ _Values and Beliefs: [Core values driving customer behavior]_ _Lifestyle Preferences: [Lifestyle choices and behaviors]_ _Attitudes and Opinions: [Customer attitudes toward products/services]_ _Personality Traits: [Personality influences on behavior]_ -_Source: [URL with {{current_year}} psychographic data]_ +_Source: [URL]_ ### Customer Segment Profiles @@ -134,7 +134,7 @@ _Source: [URL with {{current_year}} psychographic data]_ _Segment 1: [Detailed profile including demographics, psychographics, behavior]_ _Segment 2: [Detailed profile including demographics, psychographics, behavior]_ _Segment 3: [Detailed profile including demographics, psychographics, behavior]_ -_Source: [URL with {{current_year}} segment data]_ +_Source: [URL]_ ### Behavior Drivers and Influences @@ -143,7 +143,7 @@ _Emotional Drivers: [Emotional factors influencing behavior]_ _Rational Drivers: [Logical decision factors]_ _Social Influences: [Social and peer influences]_ _Economic Influences: [Economic factors affecting behavior]_ -_Source: [URL with {{current_year}} behavior drivers data]_ +_Source: [URL]_ ### Customer Interaction Patterns @@ -152,14 +152,14 @@ _Research and Discovery: [How customers find and research options]_ _Purchase Decision Process: [Steps in purchase decision making]_ _Post-Purchase Behavior: [After-purchase engagement patterns]_ _Loyalty and Retention: [Factors driving customer loyalty]_ -_Source: [URL with {{current_year}} interaction data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **customer behavior analysis** using current {{current_year}} data to understand customer patterns for {{research_topic}}. +"I've completed **customer behavior analysis** for {{research_topic}}, focusing on customer patterns. **Key Customer Behavior Findings:** @@ -186,7 +186,7 @@ Content is already written to document when generated in step 4. No additional a ## SUCCESS METRICS: -โœ… Customer behavior patterns identified with current {{current_year}} citations +โœ… Customer behavior patterns identified with current citations โœ… Demographic segmentation thoroughly analyzed โœ… Psychographic profiles clearly documented โœ… Customer interaction patterns captured @@ -198,7 +198,8 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in customer web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical customer behavior patterns โŒ Incomplete demographic segmentation analysis โŒ Missing psychographic profile documentation @@ -215,7 +216,7 @@ Content is already written to document when generated in step 4. No additional a - Use demographic data from authoritative sources - Research psychographic profiling and value systems - Analyze customer interaction and engagement patterns -- Focus on current {{current_year}} behavior data and trends +- Focus on current behavior data and trends - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -232,4 +233,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-03-customer-pain-points.md` to analyze customer pain points, challenges, and unmet needs for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} customer data with rigorous source verification! +Remember: Always write research content to document immediately and emphasize current customer data with rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-insights.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-insights.md index 293af809..4a0e9633 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-insights.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-02-customer-insights.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current customer data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A CUSTOMER INSIGHTS ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on customer behavior and needs analysis -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources ## EXECUTION PROTOCOLS: @@ -28,7 +28,7 @@ ## YOUR TASK: -Conduct comprehensive customer insights analysis using current {{current_year}} web data with emphasis on behavior patterns and needs. +Conduct comprehensive customer insights analysis with emphasis on behavior patterns and needs. ## CUSTOMER INSIGHTS SEQUENCE: @@ -37,7 +37,7 @@ Conduct comprehensive customer insights analysis using current {{current_year}} **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer areas simultaneously and thoroughly Start with customer research approach: -"Now I'll conduct **customer insights analysis** using current {{current_year}} web data to understand customer behavior and needs. +"Now I'll conduct **customer insights analysis** to understand customer behavior and needs. **Customer Insights Focus:** @@ -54,9 +54,9 @@ Start with customer research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "[product/service/market] customer behavior patterns {{current_year}}"` -`WebSearch: "[product/service/market] customer pain points challenges {{current_year}}"` -`WebSearch: "[product/service/market] customer decision process {{current_year}}"` +Search the web: "[product/service/market] customer behavior patterns" +Search the web: "[product/service/market] customer pain points challenges" +Search the web: "[product/service/market] customer decision process" **Analysis approach:** @@ -99,43 +99,43 @@ When saving to document, append these Level 2 and Level 3 sections: ### Customer Behavior Patterns [Customer behavior analysis with source citations] -_Source: [URL with {{current_year}} customer data]_ +_Source: [URL]_ ### Pain Points and Challenges [Pain points analysis with source citations] -_Source: [URL with {{current_year}} customer challenges data]_ +_Source: [URL]_ ### Decision-Making Processes [Decision-making analysis with source citations] -_Source: [URL with {{current_year}} decision process data]_ +_Source: [URL]_ ### Customer Journey Mapping [Customer journey analysis with source citations] -_Source: [URL with {{current_year}} customer journey data]_ +_Source: [URL]_ ### Customer Satisfaction Drivers [Satisfaction drivers analysis with source citations] -_Source: [URL with {{current_year}} satisfaction data]_ +_Source: [URL]_ ### Demographic Profiles [Demographic profiles analysis with source citations] -_Source: [URL with {{current_year}} demographic data]_ +_Source: [URL]_ ### Psychographic Profiles [Psychographic profiles analysis with source citations] -_Source: [URL with {{current_year}} psychographic data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option Show the generated customer insights and present continue option: -"I've completed the **customer insights analysis** using current {{current_year}} data to understand customer behavior and needs. +"I've completed the **customer insights analysis** for customer behavior and needs. **Key Customer Findings:** @@ -154,7 +154,7 @@ Show the generated customer insights and present continue option: - Append the final content to the research document - Update frontmatter: `stepsCompleted: [1, 2]` -- Load: `./step-03-competitive-analysis.md` +- Load: `./step-05-competitive-analysis.md` ## APPEND TO DOCUMENT: @@ -162,7 +162,7 @@ When user selects 'C', append the content directly to the research document usin ## SUCCESS METRICS: -โœ… Customer behavior patterns identified with current {{current_year}} citations +โœ… Customer behavior patterns identified with current citations โœ… Pain points and challenges clearly documented โœ… Decision-making processes thoroughly analyzed โœ… Customer journey insights captured and mapped @@ -172,7 +172,8 @@ When user selects 'C', append the content directly to the research document usin ## FAILURE MODES: -โŒ Not using {{current_year}} in customer web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical customer behavior patterns โŒ Not identifying key pain points and challenges โŒ Incomplete customer journey mapping @@ -193,6 +194,6 @@ When user selects 'C', append the content directly to the research document usin ## NEXT STEP: -After user selects 'C' and content is saved to document, load `./step-03-competitive-analysis.md` to focus on competitive landscape analysis. +After user selects 'C' and content is saved to document, load `./step-05-competitive-analysis.md` to focus on competitive landscape analysis. -Remember: Always emphasize current {{current_year}} customer data and rigorous source verification! +Remember: Always emphasize current customer data and rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-03-customer-pain-points.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-03-customer-pain-points.md index 898c6254..a706f16d 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-03-customer-pain-points.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-03-customer-pain-points.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current customer data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A CUSTOMER NEEDS ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on customer pain points, challenges, and unmet needs -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -32,7 +32,7 @@ ## YOUR TASK: -Conduct customer pain points and needs analysis using current {{current_year}} web data with emphasis on challenges and frustrations. +Conduct customer pain points and needs analysis with emphasis on challenges and frustrations. ## CUSTOMER PAIN POINTS ANALYSIS SEQUENCE: @@ -41,7 +41,7 @@ Conduct customer pain points and needs analysis using current {{current_year}} w **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer pain point areas simultaneously and thoroughly. Start with customer pain points research approach: -"Now I'll conduct **customer pain points analysis** for **{{research_topic}}** using current {{current_year}} web data to understand customer challenges. +"Now I'll conduct **customer pain points analysis** for **{{research_topic}}** to understand customer challenges. **Customer Pain Points Focus:** @@ -57,10 +57,10 @@ Start with customer pain points research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} customer pain points challenges {{current_year}}"` -`WebSearch: "{{research_topic}} customer frustrations {{current_year}}"` -`WebSearch: "{{research_topic}} unmet customer needs {{current_year}}"` -`WebSearch: "{{research_topic}} customer barriers to adoption {{current_year}}"` +Search the web: "{{research_topic}} customer pain points challenges" +Search the web: "{{research_topic}} customer frustrations" +Search the web: "{{research_topic}} unmet customer needs" +Search the web: "{{research_topic}} customer barriers to adoption" **Analysis approach:** @@ -109,7 +109,7 @@ _Primary Frustrations: [Major customer frustrations identified]_ _Usage Barriers: [Barriers preventing effective usage]_ _Service Pain Points: [Customer service and support issues]_ _Frequency Analysis: [How often these challenges occur]_ -_Source: [URL with {{current_year}} customer challenges data]_ +_Source: [URL]_ ### Unmet Customer Needs @@ -118,7 +118,7 @@ _Critical Unmet Needs: [Most important unaddressed needs]_ _Solution Gaps: [Opportunities to address unmet needs]_ _Market Gaps: [Market opportunities from unmet needs]_ _Priority Analysis: [Which needs are most critical]_ -_Source: [URL with {{current_year}} unmet needs data]_ +_Source: [URL]_ ### Barriers to Adoption @@ -127,7 +127,7 @@ _Price Barriers: [Cost-related barriers to adoption]_ _Technical Barriers: [Complexity or technical barriers]_ _Trust Barriers: [Trust and credibility issues]_ _Convenience Barriers: [Ease of use or accessibility issues]_ -_Source: [URL with {{current_year}} adoption barriers data]_ +_Source: [URL]_ ### Service and Support Pain Points @@ -136,7 +136,7 @@ _Customer Service Issues: [Common customer service problems]_ _Support Gaps: [Areas where customer support is lacking]_ _Communication Issues: [Communication breakdowns and frustrations]_ _Response Time Issues: [Slow response and resolution problems]_ -_Source: [URL with {{current_year}} service pain points data]_ +_Source: [URL]_ ### Customer Satisfaction Gaps @@ -145,7 +145,7 @@ _Expectation Gaps: [Differences between expectations and reality]_ _Quality Gaps: [Areas where quality expectations aren't met]_ _Value Perception Gaps: [Perceived value vs actual value]_ _Trust and Credibility Gaps: [Trust issues affecting satisfaction]_ -_Source: [URL with {{current_year}} satisfaction gap data]_ +_Source: [URL]_ ### Emotional Impact Assessment @@ -154,7 +154,7 @@ _Frustration Levels: [Customer frustration severity assessment]_ _Loyalty Risks: [How pain points affect customer loyalty]_ _Reputation Impact: [Impact on brand or product reputation]_ _Customer Retention Risks: [Risk of customer loss from pain points]_ -_Source: [URL with {{current_year}} emotional impact data]_ +_Source: [URL]_ ### Pain Point Prioritization @@ -163,14 +163,14 @@ _High Priority Pain Points: [Most critical pain points to address]_ _Medium Priority Pain Points: [Important but less critical pain points]_ _Low Priority Pain Points: [Minor pain points with lower impact]_ _Opportunity Mapping: [Pain points with highest solution opportunity]_ -_Source: [URL with {{current_year}} prioritization data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **customer pain points analysis** using current {{current_year}} data to understand customer challenges for {{research_topic}}. +"I've completed **customer pain points analysis** for {{research_topic}}, focusing on customer challenges. **Key Pain Points Findings:** @@ -209,7 +209,8 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in customer web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical customer challenges or frustrations โŒ Not identifying unmet needs or solution gaps โŒ Incomplete adoption barriers analysis @@ -227,7 +228,7 @@ Content is already written to document when generated in step 4. No additional a - Use customer feedback and complaint data - Analyze customer support and service issues - Study barriers to customer adoption -- Focus on current {{current_year}} pain point data +- Focus on current pain point data - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -244,4 +245,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-04-customer-decisions.md` to analyze customer decision processes, journey mapping, and decision factors for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} customer pain points data with rigorous source verification! +Remember: Always write research content to document immediately and emphasize current customer pain points data with rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-04-customer-decisions.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-04-customer-decisions.md index 910995be..a8ee8335 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-04-customer-decisions.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-04-customer-decisions.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current customer data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A CUSTOMER DECISION ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on customer decision processes and journey mapping -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -32,7 +32,7 @@ ## YOUR TASK: -Conduct customer decision processes and journey analysis using current {{current_year}} web data with emphasis on decision factors and journey mapping. +Conduct customer decision processes and journey analysis with emphasis on decision factors and journey mapping. ## CUSTOMER DECISIONS ANALYSIS SEQUENCE: @@ -41,7 +41,7 @@ Conduct customer decision processes and journey analysis using current {{current **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer decision areas simultaneously and thoroughly. Start with customer decisions research approach: -"Now I'll conduct **customer decision processes analysis** for **{{research_topic}}** using current {{current_year}} web data to understand customer decision-making. +"Now I'll conduct **customer decision processes analysis** for **{{research_topic}}** to understand customer decision-making. **Customer Decisions Focus:** @@ -57,10 +57,10 @@ Start with customer decisions research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} customer decision process {{current_year}}"` -`WebSearch: "{{research_topic}} buying criteria factors {{current_year}}"` -`WebSearch: "{{research_topic}} customer journey mapping {{current_year}}"` -`WebSearch: "{{research_topic}} decision influencing factors {{current_year}}"` +Search the web: "{{research_topic}} customer decision process" +Search the web: "{{research_topic}} buying criteria factors" +Search the web: "{{research_topic}} customer journey mapping" +Search the web: "{{research_topic}} decision influencing factors" **Analysis approach:** @@ -109,7 +109,7 @@ _Decision Stages: [Key stages in customer decision making]_ _Decision Timelines: [Timeframes for different decisions]_ _Complexity Levels: [Decision complexity assessment]_ _Evaluation Methods: [How customers evaluate options]_ -_Source: [URL with {{current_year}} decision process data]_ +_Source: [URL]_ ### Decision Factors and Criteria @@ -118,7 +118,7 @@ _Primary Decision Factors: [Most important factors in decisions]_ _Secondary Decision Factors: [Supporting factors influencing decisions]_ _Weighing Analysis: [How different factors are weighed]_ _Evoluton Patterns: [How factors change over time]_ -_Source: [URL with {{current_year}} decision factors data]_ +_Source: [URL]_ ### Customer Journey Mapping @@ -128,7 +128,7 @@ _Consideration Stage: [Evaluation and comparison process]_ _Decision Stage: [Final decision-making process]_ _Purchase Stage: [Purchase execution and completion]_ _Post-Purchase Stage: [Post-decision evaluation and behavior]_ -_Source: [URL with {{current_year}} journey mapping data]_ +_Source: [URL]_ ### Touchpoint Analysis @@ -137,7 +137,7 @@ _Digital Touchpoints: [Online and digital interaction points]_ _Offline Touchpoints: [Physical and in-person interaction points]_ _Information Sources: [Where customers get information]_ _Influence Channels: [What influences customer decisions]_ -_Source: [URL with {{current_year}} touchpoint data]_ +_Source: [URL]_ ### Information Gathering Patterns @@ -146,7 +146,7 @@ _Research Methods: [How customers research options]_ _Information Sources Trusted: [Most trusted information sources]_ _Research Duration: [Time spent gathering information]_ _Evaluation Criteria: [How customers evaluate information]_ -_Source: [URL with {{current_year}} information gathering data]_ +_Source: [URL]_ ### Decision Influencers @@ -155,7 +155,7 @@ _Peer Influence: [How friends and family influence decisions]_ _Expert Influence: [How expert opinions affect decisions]_ _Media Influence: [How media and marketing affect decisions]_ _Social Proof Influence: [How reviews and testimonials affect decisions]_ -_Source: [URL with {{current_year}} decision influencer data]_ +_Source: [URL]_ ### Purchase Decision Factors @@ -164,7 +164,7 @@ _Immediate Purchase Drivers: [Factors triggering immediate purchase]_ _Delayed Purchase Drivers: [Factors causing purchase delays]_ _Brand Loyalty Factors: [Factors driving repeat purchases]_ _Price Sensitivity: [How price affects purchase decisions]_ -_Source: [URL with {{current_year}} purchase decision data]_ +_Source: [URL]_ ### Customer Decision Optimizations @@ -173,14 +173,14 @@ _Friction Reduction: [Ways to make decisions easier]_ _Trust Building: [Building customer trust in decisions]_ _Conversion Optimization: [Optimizing decision-to-purchase rates]_ _Loyalty Building: [Building long-term customer relationships]_ -_Source: [URL with {{current_year}} decision optimization data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **customer decision processes analysis** using current {{current_year}} data to understand customer decision-making for {{research_topic}}. +"I've completed **customer decision processes analysis** for {{research_topic}}, focusing on customer decision-making. **Key Decision Findings:** @@ -219,7 +219,8 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in customer web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical decision-making process stages โŒ Not identifying key decision factors โŒ Incomplete customer journey mapping @@ -237,7 +238,7 @@ Content is already written to document when generated in step 4. No additional a - Use customer journey mapping methodologies - Analyze buying criteria and decision factors - Study decision influence and touchpoint analysis -- Focus on current {{current_year}} decision data +- Focus on current decision data - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -254,4 +255,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-05-competitive-analysis.md` to analyze competitive landscape, market positioning, and competitive strategies for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} customer decision data with rigorous source verification! +Remember: Always write research content to document immediately and emphasize current customer decision data with rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-05-competitive-analysis.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-05-competitive-analysis.md index 4a8ff90c..ff265e20 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-05-competitive-analysis.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-05-competitive-analysis.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current competitive data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A COMPETITIVE ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on competitive landscape and market positioning -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources ## EXECUTION PROTOCOLS: @@ -28,14 +28,14 @@ ## YOUR TASK: -Conduct comprehensive competitive analysis using current {{current_year}} web data with emphasis on market positioning. +Conduct comprehensive competitive analysis with emphasis on market positioning. ## COMPETITIVE ANALYSIS SEQUENCE: ### 1. Begin Competitive Analysis Start with competitive research approach: -"Now I'll conduct **competitive analysis** using current {{current_year}} web data to understand the competitive landscape. +"Now I'll conduct **competitive analysis** to understand the competitive landscape. **Competitive Analysis Focus:** @@ -61,43 +61,43 @@ When saving to document, append these Level 2 and Level 3 sections: ### Key Market Players [Key players analysis with market share data] -_Source: [URL with {{current_year}} market share data]_ +_Source: [URL]_ ### Market Share Analysis [Market share analysis with source citations] -_Source: [URL with {{current_year}} market share data]_ +_Source: [URL]_ ### Competitive Positioning [Positioning analysis with source citations] -_Source: [URL with {{current_year}} positioning data]_ +_Source: [URL]_ ### Strengths and Weaknesses [SWOT analysis with source citations] -_Source: [URL with {{current_year}} competitor analysis]_ +_Source: [URL]_ ### Market Differentiation [Differentiation analysis with source citations] -_Source: [URL with {{current_year}} differentiation data]_ +_Source: [URL]_ ### Competitive Threats [Threats analysis with source citations] -_Source: [URL with {{current_year}} threat assessment]_ +_Source: [URL]_ ### Opportunities [Competitive opportunities analysis with source citations] -_Source: [URL with {{current_year}} opportunity data]_ +_Source: [URL]_ ``` ### 3. Present Analysis and Complete Option Show the generated competitive analysis and present complete option: -"I've completed the **competitive analysis** using current {{current_year}} data to understand the competitive landscape. +"I've completed the **competitive analysis** for the competitive landscape. **Key Competitive Findings:** @@ -124,7 +124,7 @@ When user selects 'C', append the content directly to the research document usin ## SUCCESS METRICS: -โœ… Key market players identified with {{current_year}} data +โœ… Key market players identified โœ… Market share analysis completed with source verification โœ… Competitive positioning strategies clearly mapped โœ… Strengths and weaknesses thoroughly analyzed @@ -135,7 +135,8 @@ When user selects 'C', append the content directly to the research document usin ## FAILURE MODES: -โŒ Not using {{current_year}} in competitive web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing key market players or market share data โŒ Incomplete competitive positioning analysis โŒ Not identifying market differentiation opportunities @@ -172,4 +173,4 @@ Market research workflow complete. User may: - Conduct additional competitive research on specific companies - Combine market research with other research types for comprehensive insights -Congratulations on completing comprehensive market research with current {{current_year}} data! ๐ŸŽ‰ +Congratulations on completing comprehensive market research! ๐ŸŽ‰ diff --git a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md index 14be3495..53b03f77 100644 --- a/src/modules/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md +++ b/src/modules/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current market data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A MARKET RESEARCH STRATEGIST, not content generator - ๐Ÿ’ฌ FOCUS on strategic recommendations and actionable insights -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources ## EXECUTION PROTOCOLS: @@ -38,7 +38,7 @@ Produce a comprehensive, authoritative market research document on **{{research_ ### 1. Begin Strategic Synthesis Start with strategic synthesis approach: -"Now I'll complete our market research with **strategic synthesis and recommendations** using current {{current_year}} data. +"Now I'll complete our market research with **strategic synthesis and recommendations** . **Strategic Synthesis Focus:** @@ -53,7 +53,7 @@ Start with strategic synthesis approach: ### 2. Web Search for Market Entry Strategies Search for current market strategies: -`WebSearch: "market entry strategies best practices {{current_year}}"` +Search the web: "market entry strategies best practices" **Strategy focus:** @@ -65,7 +65,7 @@ Search for current market strategies: ### 3. Web Search for Risk Assessment Search for current risk approaches: -`WebSearch: "market research risk assessment frameworks {{current_year}}"` +Search the web: "market research risk assessment frameworks" **Risk focus:** @@ -105,10 +105,10 @@ Prepare comprehensive market research document with full structure: ### Market Research Significance -[Compelling market narrative about why {{research_topic}} research is critical in {{current_year}}] -_Market Importance: [Strategic market significance with {{current_year}} context]_ +**Compelling market narrative about why {{research_topic}} research is critical now** +_Market Importance: [Strategic market significance with up-to-date context]_ _Business Impact: [Business implications of market research]_ -_Source: [URL with {{current_year}} market significance data]_ +_Source: [URL]_ ### Market Research Methodology @@ -117,7 +117,7 @@ _Source: [URL with {{current_year}} market significance data]_ - **Market Scope**: [Comprehensive market coverage areas] - **Data Sources**: [Authoritative market sources and verification approach] - **Analysis Framework**: [Structured market analysis methodology] -- **Time Period**: [{{current_year}} focus and market evolution context] +- **Time Period**: [current focus and market evolution context] - **Geographic Coverage**: [Regional/global market scope] ### Market Research Goals and Objectives @@ -134,12 +134,12 @@ _Source: [URL with {{current_year}} market significance data]_ ### Market Size and Growth Projections -[Comprehensive market analysis with {{current_year}} data] +_[Comprehensive market analysis]_ _Market Size: [Current market valuation and size]_ _Growth Rate: [CAGR and market growth projections]_ _Market Drivers: [Key factors driving market growth]_ _Market Segments: [Detailed market segmentation analysis]_ -_Source: [URL with {{current_year}} market size data]_ +_Source: [URL]_ ### Market Trends and Dynamics @@ -147,7 +147,7 @@ _Source: [URL with {{current_year}} market size data]_ _Emerging Trends: [Key market trends and their implications]_ _Market Dynamics: [Forces shaping market evolution]_ _Consumer Behavior Shifts: [Changes in customer behavior and preferences]_ -_Source: [URL with {{current_year}} market trends data]_ +_Source: [URL]_ ### Pricing and Business Model Analysis @@ -155,17 +155,17 @@ _Source: [URL with {{current_year}} market trends data]_ _Pricing Strategies: [Current pricing approaches and models]_ _Business Model Evolution: [Emerging and successful business models]_ _Value Proposition Analysis: [Customer value proposition assessment]_ -_Source: [URL with {{current_year}} pricing data]_ +_Source: [URL]_ ## 3. Customer Insights and Behavior Analysis ### Customer Behavior Patterns -[Customer insights analysis with {{current_year}} context] +[Customer insights analysis with current context] _Behavior Patterns: [Key customer behavior trends and patterns]_ _Customer Journey: [Complete customer journey mapping]_ _Decision Factors: [Factors influencing customer decisions]_ -_Source: [URL with {{current_year}} customer behavior data]_ +_Source: [URL]_ ### Customer Pain Points and Needs @@ -173,7 +173,7 @@ _Source: [URL with {{current_year}} customer behavior data]_ _Pain Points: [Key customer challenges and frustrations]_ _Unmet Needs: [Unsolved customer needs and opportunities]_ _Customer Expectations: [Current customer expectations and requirements]_ -_Source: [URL with {{current_year}} customer insights data]_ +_Source: [URL]_ ### Customer Segmentation and Targeting @@ -181,7 +181,7 @@ _Source: [URL with {{current_year}} customer insights data]_ _Customer Segments: [Detailed customer segment profiles]_ _Target Market Analysis: [Most attractive customer segments]_ _Segment-specific Strategies: [Tailored approaches for key segments]_ -_Source: [URL with {{current_year}} segmentation data]_ +_Source: [URL]_ ## 4. Competitive Landscape and Positioning @@ -191,7 +191,7 @@ _Source: [URL with {{current_year}} segmentation data]_ _Market Leaders: [Dominant competitors and their strategies]_ _Emerging Competitors: [New entrants and innovative approaches]_ _Competitive Advantages: [Key differentiators and competitive advantages]_ -_Source: [URL with {{current_year}} competitive data]_ +_Source: [URL]_ ### Market Positioning Strategies @@ -199,7 +199,7 @@ _Source: [URL with {{current_year}} competitive data]_ _Positioning Opportunities: [Opportunities for market differentiation]_ _Competitive Gaps: [Unserved market needs and opportunities]_ _Positioning Framework: [Recommended positioning approach]_ -_Source: [URL with {{current_year}} positioning data]_ +_Source: [URL]_ ## 5. Strategic Market Recommendations @@ -209,7 +209,7 @@ _Source: [URL with {{current_year}} positioning data]_ _High-Value Opportunities: [Most attractive market opportunities]_ _Market Entry Timing: [Optimal timing for market entry or expansion]_ _Growth Strategies: [Recommended approaches for market growth]_ -_Source: [URL with {{current_year}} market opportunity data]_ +_Source: [URL]_ ### Strategic Recommendations @@ -217,7 +217,7 @@ _Source: [URL with {{current_year}} market opportunity data]_ _Market Entry Strategy: [Recommended approach for market entry/expansion]_ _Competitive Strategy: [Recommended competitive positioning and approach]_ _Customer Acquisition Strategy: [Recommended customer acquisition approach]_ -_Source: [URL with {{current_year}} strategic data]_ +_Source: [URL]_ ## 6. Market Entry and Growth Strategies @@ -227,7 +227,7 @@ _Source: [URL with {{current_year}} strategic data]_ _Market Entry Approach: [Recommended market entry strategy and tactics]_ _Channel Strategy: [Optimal channels for market reach and customer acquisition]_ _Partnership Strategy: [Strategic partnership and collaboration opportunities]_ -_Source: [URL with {{current_year}} market entry data]_ +_Source: [URL]_ ### Growth and Scaling Strategy @@ -235,7 +235,7 @@ _Source: [URL with {{current_year}} market entry data]_ _Growth Phases: [Recommended phased approach to market growth]_ _Scaling Considerations: [Key factors for successful market scaling]_ _Expansion Opportunities: [Opportunities for geographic or segment expansion]_ -_Source: [URL with {{current_year}} growth strategy data]_ +_Source: [URL]_ ## 7. Risk Assessment and Mitigation @@ -245,7 +245,7 @@ _Source: [URL with {{current_year}} growth strategy data]_ _Market Risks: [Key market-related risks and uncertainties]_ _Competitive Risks: [Competitive threats and mitigation strategies]_ _Regulatory Risks: [Regulatory and compliance considerations]_ -_Source: [URL with {{current_year}} risk assessment data]_ +_Source: [URL]_ ### Mitigation Strategies @@ -253,7 +253,7 @@ _Source: [URL with {{current_year}} risk assessment data]_ _Risk Mitigation Approaches: [Strategies for managing identified risks]_ _Contingency Planning: [Backup plans and alternative approaches]_ _Market Sensitivity Analysis: [Impact of market changes on strategy]_ -_Source: [URL with {{current_year}} mitigation data]_ +_Source: [URL]_ ## 8. Implementation Roadmap and Success Metrics @@ -263,7 +263,7 @@ _Source: [URL with {{current_year}} mitigation data]_ _Implementation Timeline: [Recommended phased implementation approach]_ _Required Resources: [Key resources and capabilities needed]_ _Implementation Milestones: [Key milestones and success criteria]_ -_Source: [URL with {{current_year}} implementation data]_ +_Source: [URL]_ ### Success Metrics and KPIs @@ -271,7 +271,7 @@ _Source: [URL with {{current_year}} implementation data]_ _Key Performance Indicators: [Critical metrics for measuring success]_ _Monitoring and Reporting: [Approach for tracking and reporting progress]_ _Success Criteria: [Clear criteria for determining success]_ -_Source: [URL with {{current_year}} metrics data]_ +_Source: [URL]_ ## 9. Future Market Outlook and Opportunities @@ -281,7 +281,7 @@ _Source: [URL with {{current_year}} metrics data]_ _Near-term Market Evolution: [1-2 year market development expectations]_ _Medium-term Market Trends: [3-5 year expected market developments]_ _Long-term Market Vision: [5+ year market outlook for {{research_topic}}]_ -_Source: [URL with {{current_year}} future trends data]_ +_Source: [URL]_ ### Strategic Opportunities @@ -289,7 +289,7 @@ _Source: [URL with {{current_year}} future trends data]_ _Emerging Opportunities: [New market opportunities and their potential]_ _Innovation Opportunities: [Areas for market innovation and differentiation]_ _Strategic Market Investments: [Recommended market investments and priorities]_ -_Source: [URL with {{current_year}} opportunity data]_ +_Source: [URL]_ ## 10. Market Research Methodology and Source Verification @@ -299,7 +299,6 @@ _Source: [URL with {{current_year}} opportunity data]_ _Primary Market Sources: [Key authoritative market sources used]_ _Secondary Market Sources: [Supporting market research and analysis]_ _Market Web Search Queries: [Complete list of market search queries used]_ -_Market Data Currency: [All market data verified for {{current_year}} currency]_ ### Market Research Quality Assurance @@ -344,9 +343,9 @@ _Market Analysis Tools: [Tools and resources for ongoing market analysis]_ --- **Market Research Completion Date:** {{date}} -**Research Period:** {{current_year}} comprehensive market analysis +**Research Period:** current comprehensive market analysis **Document Length:** As needed for comprehensive market coverage -**Source Verification:** All market facts cited with {{current_year}} sources +**Source Verification:** All market facts cited with current sources **Market Confidence Level:** High - based on multiple authoritative market sources _This comprehensive market research document serves as an authoritative market reference on {{research_topic}} and provides strategic market insights for informed decision-making._ @@ -365,7 +364,7 @@ _This comprehensive market research document serves as an authoritative market r - **Exhaustive Market Research Coverage**: All market aspects of {{research_topic}} thoroughly analyzed - **Executive Market Summary**: Key market findings and strategic implications highlighted - **Strategic Market Recommendations**: Actionable market insights based on comprehensive research -- **Complete Market Source Citations**: Every market claim verified with {{current_year}} sources +- **Complete Market Source Citations**: Every market claim verified with current sources **Market Research Completeness:** @@ -380,7 +379,7 @@ _This comprehensive market research document serves as an authoritative market r - Professional market structure and compelling narrative - As long as needed for comprehensive market coverage - Multiple independent sources for all market claims -- {{current_year}} market data throughout with proper citations +- current market data throughout with proper citations **Ready to complete this comprehensive market research document?** [C] Complete Research - Save final comprehensive market research document @@ -404,7 +403,7 @@ When user selects 'C', append the content directly to the research document usin โœ… Exhaustive market research coverage across all market aspects โœ… Executive market summary with key findings and strategic implications โœ… Strategic market recommendations grounded in comprehensive research -โœ… Complete market source verification with {{current_year}} citations +โœ… Complete market source verification with current citations โœ… Professional market document structure and compelling narrative โœ… [C] complete option presented and handled correctly โœ… Market research workflow completed with comprehensive document @@ -416,7 +415,7 @@ When user selects 'C', append the content directly to the research document usin โŒ Incomplete market research coverage across market aspects โŒ Not providing executive market summary with key findings โŒ Missing strategic market recommendations based on research -โŒ Not using {{current_year}} market sources for all factual claims +โŒ Relying solely on training data without web verification for current facts โŒ Producing market document without professional structure โŒ Not presenting completion option for final market document @@ -461,7 +460,7 @@ Complete authoritative market research document on {{research_topic}} that: - Establishes professional market credibility through comprehensive research - Provides strategic market insights for informed decision-making - Serves as market reference document for continued use -- Maintains highest market research quality standards with {{current_year}} verification +- Maintains highest market research quality standards with current verification ## NEXT STEPS: diff --git a/src/modules/bmm/workflows/1-analysis/research/research.template.md b/src/modules/bmm/workflows/1-analysis/research/research.template.md index 53f653f0..131ef715 100644 --- a/src/modules/bmm/workflows/1-analysis/research/research.template.md +++ b/src/modules/bmm/workflows/1-analysis/research/research.template.md @@ -3,7 +3,6 @@ **Date:** {{date}} **Author:** {{user_name}} **Research Type:** {{research_type}} -**Data Currency:** {{current_year}} --- diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md index 63f96ea9..1bbf9238 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-01-init.md @@ -25,7 +25,7 @@ - **Research topic = "{{research_topic}}"** - discovered from initial discussion - **Research goals = "{{research_goals}}"** - captured from initial discussion - Focus on technical architecture and implementation research -- Web search capabilities with {{current_year}} data are enabled +- Web search is required to verify and supplement your knowledge with current facts ## YOUR TASK: @@ -48,7 +48,7 @@ Start with technical scope understanding: **Research Approach:** -- Current {{current_year}} web data with rigorous source verification +- Current web data with rigorous source verification - Multi-source validation for critical technical claims - Confidence levels for uncertain technical information - Comprehensive technical coverage with architecture-specific insights @@ -66,7 +66,7 @@ For **{{research_topic}}**, I will research: โœ… **Integration Patterns** - APIs, protocols, interoperability โœ… **Performance Considerations** - scalability, optimization, patterns -**All using current {{current_year}} web data with source verification.** +**All claims verified against current public sources.** **Does this technical research scope and approach align with your goals?** [C] Continue - Begin technical research with this scope @@ -77,7 +77,7 @@ For **{{research_topic}}**, I will research: - Document scope confirmation in research file - Update frontmatter: `stepsCompleted: [1]` -- Load: `./step-02-technology-stack.md` +- Load: `./step-02-technical-overview.md` ## APPEND TO DOCUMENT: @@ -99,7 +99,7 @@ When user selects 'C', append scope confirmation: **Research Methodology:** -- Current {{current_year}} web data with rigorous source verification +- Current web data with rigorous source verification - Multi-source validation for critical technical claims - Confidence level framework for uncertain information - Comprehensive technical coverage with architecture-specific insights @@ -111,7 +111,7 @@ When user selects 'C', append scope confirmation: โœ… Technical research scope clearly confirmed with user โœ… All technical analysis areas identified and explained -โœ… Research methodology with {{current_year}} data emphasized +โœ… Research methodology emphasized โœ… [C] continue option presented and handled correctly โœ… Scope confirmation documented when user proceeds โœ… Proper routing to next technical research step @@ -120,7 +120,7 @@ When user selects 'C', append scope confirmation: โŒ Not clearly confirming technical research scope with user โŒ Missing critical technical analysis areas -โŒ Not emphasizing {{current_year}} web data requirement +โŒ Not explaining that web search is required for current facts โŒ Not presenting [C] continue option โŒ Proceeding without user scope confirmation โŒ Not routing to next technical research step @@ -131,6 +131,6 @@ When user selects 'C', append scope confirmation: ## NEXT STEP: -After user selects 'C', load `./step-02-technology-stack.md` to begin technology stack analysis with current {{current_year}} web data. +After user selects 'C', load `./step-02-technical-overview.md` to begin technology stack analysis. Remember: This is SCOPE CONFIRMATION ONLY - no actual technical research yet, just confirming the research approach and scope! diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-02-technical-overview.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-02-technical-overview.md index a420fa55..631bf1f1 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-02-technical-overview.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-02-technical-overview.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current technology data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A TECHNOLOGY STACK ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on languages, frameworks, tools, and platforms -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,7 +31,7 @@ ## YOUR TASK: -Conduct technology stack analysis focusing on languages, frameworks, tools, and platforms using current {{current_year}} web data with rigorous source verification. +Conduct technology stack analysis focusing on languages, frameworks, tools, and platforms. Search the web to verify and supplement current facts. ## TECHNOLOGY STACK ANALYSIS SEQUENCE: @@ -40,7 +40,7 @@ Conduct technology stack analysis focusing on languages, frameworks, tools, and **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different technology stack areas simultaneously and thoroughly. Start with technology stack research approach: -"Now I'll conduct **technology stack analysis** for **{{research_topic}}** using current {{current_year}} web data to understand the technology landscape. +"Now I'll conduct **technology stack analysis** for **{{research_topic}}** to understand the technology landscape. **Technology Stack Focus:** @@ -56,10 +56,10 @@ Start with technology stack research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} programming languages frameworks {{current_year}}"` -`WebSearch: "{{research_topic}} development tools platforms {{current_year}}"` -`WebSearch: "{{research_topic}} database storage technologies {{current_year}}"` -`WebSearch: "{{research_topic}} cloud infrastructure platforms {{current_year}}"` +Search the web: "{{research_topic}} programming languages frameworks" +Search the web: "{{research_topic}} development tools platforms" +Search the web: "{{research_topic}} database storage technologies" +Search the web: "{{research_topic}} cloud infrastructure platforms" **Analysis approach:** @@ -108,7 +108,7 @@ _Popular Languages: [Most widely used languages for {{research_topic}}]_ _Emerging Languages: [Growing languages gaining adoption]_ _Language Evolution: [How language preferences are changing]_ _Performance Characteristics: [Language performance and suitability]_ -_Source: [URL with {{current_year}} language data]_ +_Source: [URL]_ ### Development Frameworks and Libraries @@ -117,7 +117,7 @@ _Major Frameworks: [Dominant frameworks and their use cases]_ _Micro-frameworks: [Lightweight options and specialized libraries]_ _Evolution Trends: [How frameworks are evolving and changing]_ _Ecosystem Maturity: [Library availability and community support]_ -_Source: [URL with {{current_year}} framework data]_ +_Source: [URL]_ ### Database and Storage Technologies @@ -126,7 +126,7 @@ _Relational Databases: [Traditional SQL databases and their evolution]_ _NoSQL Databases: [Document, key-value, graph, and other NoSQL options]_ _In-Memory Databases: [Redis, Memcached, and performance-focused solutions]_ _Data Warehousing: [Analytics and big data storage solutions]_ -_Source: [URL with {{current_year}} database data]_ +_Source: [URL]_ ### Development Tools and Platforms @@ -135,7 +135,7 @@ _IDE and Editors: [Development environments and their evolution]_ _Version Control: [Git and related development tools]_ _Build Systems: [Compilation, packaging, and automation tools]_ _Testing Frameworks: [Unit testing, integration testing, and QA tools]_ -_Source: [URL with {{current_year}} tools data]_ +_Source: [URL]_ ### Cloud Infrastructure and Deployment @@ -144,7 +144,7 @@ _Major Cloud Providers: [AWS, Azure, GCP and their services]_ _Container Technologies: [Docker, Kubernetes, and orchestration]_ _Serverless Platforms: [FaaS and event-driven computing]_ _CDN and Edge Computing: [Content delivery and distributed computing]_ -_Source: [URL with {{current_year}} cloud data]_ +_Source: [URL]_ ### Technology Adoption Trends @@ -153,14 +153,14 @@ _Migration Patterns: [How technology choices are evolving]_ _Emerging Technologies: [New technologies gaining traction]_ _Legacy Technology: [Older technologies being phased out]_ _Community Trends: [Developer preferences and open-source adoption]_ -_Source: [URL with {{current_year}} adoption data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **technology stack analysis** using current {{current_year}} data to understand the technology landscape for {{research_topic}}. +"I've completed **technology stack analysis** of the technology landscape for {{research_topic}}. **Key Technology Stack Findings:** @@ -199,7 +199,8 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in technology web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical programming languages or frameworks โŒ Incomplete database and storage technology analysis โŒ Not identifying development tools and platforms @@ -217,7 +218,7 @@ Content is already written to document when generated in step 4. No additional a - Use technology documentation and best practices guides - Analyze open-source projects and their technology choices - Study technology adoption patterns and migration trends -- Focus on current {{current_year}} technology data +- Focus on current technology data - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -234,4 +235,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-03-integration-patterns.md` to analyze APIs, communication protocols, and system interoperability for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} technology data with rigorous source verification! +Remember: Always write research content to document immediately and emphasize current technology data with rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md index 78f89f5d..185c0881 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current integration data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE AN INTEGRATION ANALYST, not content generator - ๐Ÿ’ฌ FOCUS on APIs, protocols, and system interoperability -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,7 +31,7 @@ ## YOUR TASK: -Conduct integration patterns analysis focusing on APIs, communication protocols, and system interoperability using current {{current_year}} web data with rigorous source verification. +Conduct integration patterns analysis focusing on APIs, communication protocols, and system interoperability. Search the web to verify and supplement current facts. ## INTEGRATION PATTERNS ANALYSIS SEQUENCE: @@ -40,7 +40,7 @@ Conduct integration patterns analysis focusing on APIs, communication protocols, **UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different integration areas simultaneously and thoroughly. Start with integration patterns research approach: -"Now I'll conduct **integration patterns analysis** for **{{research_topic}}** using current {{current_year}} web data to understand system integration approaches. +"Now I'll conduct **integration patterns analysis** for **{{research_topic}}** to understand system integration approaches. **Integration Patterns Focus:** @@ -56,10 +56,10 @@ Start with integration patterns research approach: **Execute multiple web searches simultaneously:** -`WebSearch: "{{research_topic}} API design patterns protocols {{current_year}}"` -`WebSearch: "{{research_topic}} communication protocols data formats {{current_year}}"` -`WebSearch: "{{research_topic}} system interoperability integration {{current_year}}"` -`WebSearch: "{{research_topic}} microservices integration patterns {{current_year}}"` +Search the web: "{{research_topic}} API design patterns protocols" +Search the web: "{{research_topic}} communication protocols data formats" +Search the web: "{{research_topic}} system interoperability integration" +Search the web: "{{research_topic}} microservices integration patterns" **Analysis approach:** @@ -108,7 +108,7 @@ _RESTful APIs: [REST principles and best practices for {{research_topic}}]_ _GraphQL APIs: [GraphQL adoption and implementation patterns]_ _RPC and gRPC: [High-performance API communication patterns]_ _Webhook Patterns: [Event-driven API integration approaches]_ -_Source: [URL with {{current_year}} API design data]_ +_Source: [URL]_ ### Communication Protocols @@ -117,7 +117,7 @@ _HTTP/HTTPS Protocols: [Web-based communication patterns and evolution]_ _WebSocket Protocols: [Real-time communication and persistent connections]_ _Message Queue Protocols: [AMQP, MQTT, and messaging patterns]_ _grpc and Protocol Buffers: [High-performance binary communication protocols]_ -_Source: [URL with {{current_year}} communication protocols data]_ +_Source: [URL]_ ### Data Formats and Standards @@ -126,7 +126,7 @@ _JSON and XML: [Structured data exchange formats and their evolution]_ _Protobuf and MessagePack: [Efficient binary serialization formats]_ _CSV and Flat Files: [Legacy data integration and bulk transfer patterns]_ _Custom Data Formats: [Domain-specific data exchange standards]_ -_Source: [URL with {{current_year}} data formats data]_ +_Source: [URL]_ ### System Interoperability Approaches @@ -135,7 +135,7 @@ _Point-to-Point Integration: [Direct system-to-system communication patterns]_ _API Gateway Patterns: [Centralized API management and routing]_ _Service Mesh: [Service-to-service communication and observability]_ _Enterprise Service Bus: [Traditional enterprise integration patterns]_ -_Source: [URL with {{current_year}} interoperability data]_ +_Source: [URL]_ ### Microservices Integration Patterns @@ -144,7 +144,7 @@ _API Gateway Pattern: [External API management and routing]_ _Service Discovery: [Dynamic service registration and discovery]_ _Circuit Breaker Pattern: [Fault tolerance and resilience patterns]_ _Saga Pattern: [Distributed transaction management]_ -_Source: [URL with {{current_year}} microservices data]_ +_Source: [URL]_ ### Event-Driven Integration @@ -153,7 +153,7 @@ _Publish-Subscribe Patterns: [Event broadcasting and subscription models]_ _Event Sourcing: [Event-based state management and persistence]_ _Message Broker Patterns: [RabbitMQ, Kafka, and message routing]_ _CQRS Patterns: [Command Query Responsibility Segregation]_ -_Source: [URL with {{current_year}} event-driven data]_ +_Source: [URL]_ ### Integration Security Patterns @@ -162,14 +162,14 @@ _OAuth 2.0 and JWT: [API authentication and authorization patterns]_ _API Key Management: [Secure API access and key rotation]_ _Mutual TLS: [Certificate-based service authentication]_ _Data Encryption: [Secure data transmission and storage]_ -_Source: [URL with {{current_year}} integration security data]_ +_Source: [URL]_ ``` ### 5. Present Analysis and Continue Option **Show analysis and present continue option:** -"I've completed **integration patterns analysis** using current {{current_year}} data to understand system integration approaches for {{research_topic}}. +"I've completed **integration patterns analysis** of system integration approaches for {{research_topic}}. **Key Integration Patterns Findings:** @@ -208,7 +208,8 @@ Content is already written to document when generated in step 4. No additional a ## FAILURE MODES: -โŒ Not using {{current_year}} in integration web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical API design patterns or protocols โŒ Incomplete communication protocols analysis โŒ Not identifying system interoperability approaches @@ -226,7 +227,7 @@ Content is already written to document when generated in step 4. No additional a - Use communication protocol specifications and standards - Analyze integration platform and middleware solutions - Study microservices architecture patterns and case studies -- Focus on current {{current_year}} integration data +- Focus on current integration data - Present conflicting information when sources disagree - Apply confidence levels appropriately @@ -243,4 +244,4 @@ Content is already written to document when generated in step 4. No additional a After user selects 'C', load `./step-04-architectural-patterns.md` to analyze architectural patterns, design decisions, and system structures for {{research_topic}}. -Remember: Always write research content to document immediately and emphasize current {{current_year}} integration data with rigorous source verification! +Remember: Always write research content to document immediately and emphasize current integration data with rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md index ae1ff674..6567285a 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current architectural data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A SYSTEMS ARCHITECT, not content generator - ๐Ÿ’ฌ FOCUS on architectural patterns and design decisions -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“ WRITE CONTENT IMMEDIATELY TO DOCUMENT ## EXECUTION PROTOCOLS: @@ -31,14 +31,14 @@ ## YOUR TASK: -Conduct comprehensive architectural patterns analysis using current {{current_year}} web data with emphasis on design decisions and implementation approaches for {{research_topic}}. +Conduct comprehensive architectural patterns analysis with emphasis on design decisions and implementation approaches for {{research_topic}}. ## ARCHITECTURAL PATTERNS SEQUENCE: ### 1. Begin Architectural Patterns Analysis Start with architectural research approach: -"Now I'll focus on **architectural patterns and design decisions** using current {{current_year}} data to understand effective architecture approaches for [technology/domain]. +"Now I'll focus on **architectural patterns and design decisions** for effective architecture approaches for [technology/domain]. **Architectural Patterns Focus:** @@ -53,7 +53,7 @@ Start with architectural research approach: ### 2. Web Search for System Architecture Patterns Search for current architecture patterns: -`WebSearch: "system architecture patterns best practices {{current_year}}"` +Search the web: "system architecture patterns best practices" **Architecture focus:** @@ -65,7 +65,7 @@ Search for current architecture patterns: ### 3. Web Search for Design Principles Search for current design principles: -`WebSearch: "software design principles patterns {{current_year}}"` +Search the web: "software design principles patterns" **Design focus:** @@ -77,7 +77,7 @@ Search for current design principles: ### 4. Web Search for Scalability Patterns Search for current scalability approaches: -`WebSearch: "scalability architecture patterns {{current_year}}"` +Search the web: "scalability architecture patterns" **Scalability focus:** @@ -100,43 +100,43 @@ When saving to document, append these Level 2 and Level 3 sections: ### System Architecture Patterns [System architecture patterns analysis with source citations] -_Source: [URL with {{current_year}} architecture data]_ +_Source: [URL]_ ### Design Principles and Best Practices [Design principles analysis with source citations] -_Source: [URL with {{current_year}} design data]_ +_Source: [URL]_ ### Scalability and Performance Patterns [Scalability patterns analysis with source citations] -_Source: [URL with {{current_year}} scalability data]_ +_Source: [URL]_ ### Integration and Communication Patterns [Integration patterns analysis with source citations] -_Source: [URL with {{current_year}} integration data]_ +_Source: [URL]_ ### Security Architecture Patterns [Security patterns analysis with source citations] -_Source: [URL with {{current_year}} security data]_ +_Source: [URL]_ ### Data Architecture Patterns [Data architecture analysis with source citations] -_Source: [URL with {{current_year}} data architecture data]_ +_Source: [URL]_ ### Deployment and Operations Architecture [Deployment architecture analysis with source citations] -_Source: [URL with {{current_year}} deployment data]_ +_Source: [URL]_ ``` ### 6. Present Analysis and Continue Option Show the generated architectural patterns and present continue option: -"I've completed the **architectural patterns analysis** using current {{current_year}} data to understand effective architecture approaches. +"I've completed the **architectural patterns analysis** for effective architecture approaches. **Key Architectural Findings:** @@ -155,7 +155,7 @@ Show the generated architectural patterns and present continue option: - Append the final content to the research document - Update frontmatter: `stepsCompleted: [1, 2, 3]` -- Load: `./step-04-implementation-research.md` +- Load: `./step-05-implementation-research.md` ## APPEND TO DOCUMENT: @@ -163,7 +163,7 @@ When user selects 'C', append the content directly to the research document usin ## SUCCESS METRICS: -โœ… System architecture patterns identified with current {{current_year}} citations +โœ… System architecture patterns identified with current citations โœ… Design principles clearly documented and analyzed โœ… Scalability and performance patterns thoroughly mapped โœ… Integration and communication patterns captured @@ -174,7 +174,8 @@ When user selects 'C', append the content directly to the research document usin ## FAILURE MODES: -โŒ Not using {{current_year}} in architectural web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical system architecture patterns โŒ Not analyzing design trade-offs and considerations โŒ Incomplete scalability or performance patterns analysis @@ -195,6 +196,6 @@ When user selects 'C', append the content directly to the research document usin ## NEXT STEP: -After user selects 'C' and content is saved to document, load `./step-04-implementation-research.md` to focus on implementation approaches and technology adoption. +After user selects 'C' and content is saved to document, load `./step-05-implementation-research.md` to focus on implementation approaches and technology adoption. -Remember: Always emphasize current {{current_year}} architectural data and rigorous source verification! +Remember: Always emphasize current architectural data and rigorous source verification! diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-05-implementation-research.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-05-implementation-research.md index 3fc52e03..219b231b 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-05-implementation-research.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-05-implementation-research.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current implementation data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE AN IMPLEMENTATION ENGINEER, not content generator - ๐Ÿ’ฌ FOCUS on implementation approaches and technology adoption -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources ## EXECUTION PROTOCOLS: @@ -28,14 +28,14 @@ ## YOUR TASK: -Conduct comprehensive implementation research using current {{current_year}} web data with emphasis on practical implementation approaches and technology adoption. +Conduct comprehensive implementation research with emphasis on practical implementation approaches and technology adoption. ## IMPLEMENTATION RESEARCH SEQUENCE: ### 1. Begin Implementation Research Start with implementation research approach: -"Now I'll complete our technical research with **implementation approaches and technology adoption** analysis using current {{current_year}} data. +"Now I'll complete our technical research with **implementation approaches and technology adoption** analysis. **Implementation Research Focus:** @@ -50,7 +50,7 @@ Start with implementation research approach: ### 2. Web Search for Technology Adoption Search for current adoption strategies: -`WebSearch: "technology adoption strategies migration {{current_year}}"` +Search the web: "technology adoption strategies migration" **Adoption focus:** @@ -62,7 +62,7 @@ Search for current adoption strategies: ### 3. Web Search for Development Workflows Search for current development practices: -`WebSearch: "software development workflows tooling {{current_year}}"` +Search the web: "software development workflows tooling" **Workflow focus:** @@ -74,7 +74,7 @@ Search for current development practices: ### 4. Web Search for Operational Excellence Search for current operational practices: -`WebSearch: "DevOps operations best practices {{current_year}}"` +Search the web: "DevOps operations best practices" **Operations focus:** @@ -97,37 +97,37 @@ When saving to document, append these Level 2 and Level 3 sections: ### Technology Adoption Strategies [Technology adoption analysis with source citations] -_Source: [URL with {{current_year}} adoption data]_ +_Source: [URL]_ ### Development Workflows and Tooling [Development workflows analysis with source citations] -_Source: [URL with {{current_year}} development data]_ +_Source: [URL]_ ### Testing and Quality Assurance [Testing approaches analysis with source citations] -_Source: [URL with {{current_year}} testing data]_ +_Source: [URL]_ ### Deployment and Operations Practices [Deployment practices analysis with source citations] -_Source: [URL with {{current_year}} deployment data]_ +_Source: [URL]_ ### Team Organization and Skills [Team organization analysis with source citations] -_Source: [URL with {{current_year}} team data]_ +_Source: [URL]_ ### Cost Optimization and Resource Management [Cost optimization analysis with source citations] -_Source: [URL with {{current_year}} optimization data]_ +_Source: [URL]_ ### Risk Assessment and Mitigation [Risk mitigation analysis with source citations] -_Source: [URL with {{current_year}} risk data]_ +_Source: [URL]_ ## Technical Research Recommendations @@ -151,7 +151,7 @@ _Source: [URL with {{current_year}} risk data]_ ### 6. Present Analysis and Complete Option Show the generated implementation research and present complete option: -"I've completed the **implementation research and technology adoption** analysis using current {{current_year}} data, finalizing our comprehensive technical research. +"I've completed the **implementation research and technology adoption** analysis, finalizing our comprehensive technical research. **Implementation Highlights:** @@ -185,7 +185,7 @@ When user selects 'C', append the content directly to the research document usin ## SUCCESS METRICS: -โœ… Technology adoption strategies identified with current {{current_year}} citations +โœ… Technology adoption strategies identified with current citations โœ… Development workflows and tooling thoroughly analyzed โœ… Testing and deployment practices clearly documented โœ… Team organization and skill requirements mapped @@ -196,7 +196,8 @@ When user selects 'C', append the content directly to the research document usin ## FAILURE MODES: -โŒ Not using {{current_year}} in implementation web searches +โŒ Relying solely on training data without web verification for current facts + โŒ Missing critical technology adoption strategies โŒ Not providing practical implementation guidance โŒ Incomplete development workflows or operational practices analysis @@ -234,4 +235,4 @@ Technical research workflow complete. User may: - Combine technical research with other research types for comprehensive insights - Move forward with implementation based on technical insights -Congratulations on completing comprehensive technical research with current {{current_year}} data! ๐ŸŽ‰ +Congratulations on completing comprehensive technical research! ๐ŸŽ‰ diff --git a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md index 67cd1ac6..6e83cc86 100644 --- a/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md +++ b/src/modules/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md @@ -6,10 +6,10 @@ - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS use {{current_year}} web searches for current technical data +- โœ… Search the web to verify and supplement your knowledge with current facts - ๐Ÿ“‹ YOU ARE A TECHNICAL RESEARCH STRATEGIST, not content generator - ๐Ÿ’ฌ FOCUS on comprehensive technical synthesis and authoritative conclusions -- ๐Ÿ” WEB RESEARCH REQUIRED - Use {{current_year}} data and verify sources +- ๐Ÿ” WEB SEARCH REQUIRED - verify current facts against live sources - ๐Ÿ“„ PRODUCE COMPREHENSIVE DOCUMENT with narrative intro, TOC, and summary ## EXECUTION PROTOCOLS: @@ -74,7 +74,7 @@ Produce a comprehensive, authoritative technical research document on **{{resear - Set authoritative, technical expert tone **Web Search for Technical Introduction Context:** -`WebSearch: "{{research_topic}} technical significance importance {{current_year}}"` +Search the web: "{{research_topic}} technical significance importance" ### 3. Synthesize All Technical Research Sections @@ -95,7 +95,7 @@ Produce a comprehensive, authoritative technical research document on **{{resear ## Executive Summary -[2-3 paragraph compelling summary of the most critical technical findings and strategic implications for {{research_topic}} based on comprehensive {{current_year}} technical research] +[2-3 paragraph compelling summary of the most critical technical findings and strategic implications for {{research_topic}} based on comprehensive current technical research] **Key Technical Findings:** @@ -127,10 +127,10 @@ Produce a comprehensive, authoritative technical research document on **{{resear ### Technical Research Significance -[Compelling technical narrative about why {{research_topic}} research is critical in {{current_year}}] -_Technical Importance: [Strategic technical significance with {{current_year}} context]_ +[Compelling technical narrative about why {{research_topic}} research is critical right now] +_Technical Importance: [Strategic technical significance with current context]_ _Business Impact: [Business implications of technical research]_ -_Source: [URL with {{current_year}} technical significance data]_ +_Source: [URL]_ ### Technical Research Methodology @@ -139,7 +139,7 @@ _Source: [URL with {{current_year}} technical significance data]_ - **Technical Scope**: [Comprehensive technical coverage areas] - **Data Sources**: [Authoritative technical sources and verification approach] - **Analysis Framework**: [Structured technical analysis methodology] -- **Time Period**: [{{current_year}} focus and technical evolution context] +- **Time Period**: [current focus and technical evolution context] - **Technical Depth**: [Level of technical detail and analysis] ### Technical Research Goals and Objectives @@ -156,11 +156,11 @@ _Source: [URL with {{current_year}} technical significance data]_ ### Current Technical Architecture Patterns -[Comprehensive architectural analysis synthesized from step-03 with {{current_year}} context] +[Comprehensive architectural analysis synthesized from step-03 with current context] _Dominant Patterns: [Current architectural approaches]_ _Architectural Evolution: [Historical and current evolution patterns]_ _Architectural Trade-offs: [Key architectural decisions and implications]_ -_Source: [URL with {{current_year}} architectural data]_ +_Source: [URL]_ ### System Design Principles and Best Practices @@ -168,18 +168,18 @@ _Source: [URL with {{current_year}} architectural data]_ _Design Principles: [Core principles guiding {{research_topic}} implementations]_ _Best Practice Patterns: [Industry-standard approaches and methodologies]_ _Architectural Quality Attributes: [Performance, scalability, maintainability considerations]_ -_Source: [URL with {{current_year}} design principles data]_ +_Source: [URL]_ ## 3. Implementation Approaches and Best Practices ### Current Implementation Methodologies -[Implementation analysis from step-04 with {{current_year}} context] +[Implementation analysis from step-04 with current context] _Development Approaches: [Current development methodologies and approaches]_ _Code Organization Patterns: [Structural patterns and organization strategies]_ _Quality Assurance Practices: [Testing, validation, and quality approaches]_ _Deployment Strategies: [Current deployment and operations practices]_ -_Source: [URL with {{current_year}} implementation data]_ +_Source: [URL]_ ### Implementation Framework and Tooling @@ -187,18 +187,18 @@ _Source: [URL with {{current_year}} implementation data]_ _Development Frameworks: [Popular frameworks and their characteristics]_ _Tool Ecosystem: [Development tools and platform considerations]_ _Build and Deployment Systems: [CI/CD and automation approaches]_ -_Source: [URL with {{current_year}} framework data]_ +_Source: [URL]_ ## 4. Technology Stack Evolution and Current Trends ### Current Technology Stack Landscape -[Technology stack analysis from step-02 with {{current_year}} updates] +[Technology stack analysis from step-02 with current updates] _Programming Languages: [Current language trends and adoption patterns]_ _Frameworks and Libraries: [Popular frameworks and their use cases]_ _Database and Storage Technologies: [Current data storage and management trends]_ _API and Communication Technologies: [Integration and communication patterns]_ -_Source: [URL with {{current_year}} technology stack data]_ +_Source: [URL]_ ### Technology Adoption Patterns @@ -206,17 +206,17 @@ _Source: [URL with {{current_year}} technology stack data]_ _Adoption Trends: [Technology adoption rates and patterns]_ _Migration Patterns: [Technology migration and evolution trends]_ _Emerging Technologies: [New technologies and their potential impact]_ -_Source: [URL with {{current_year}} adoption data]_ +_Source: [URL]_ ## 5. Integration and Interoperability Patterns ### Current Integration Approaches -[Integration patterns analysis with {{current_year}} context] +[Integration patterns analysis with current context] _API Design Patterns: [Current API design and implementation patterns]_ _Service Integration: [Microservices and service integration approaches]_ _Data Integration: [Data exchange and integration patterns]_ -_Source: [URL with {{current_year}} integration data]_ +_Source: [URL]_ ### Interoperability Standards and Protocols @@ -224,7 +224,7 @@ _Source: [URL with {{current_year}} integration data]_ _Standards Compliance: [Industry standards and compliance requirements]_ _Protocol Selection: [Communication protocols and selection criteria]_ _Integration Challenges: [Common integration challenges and solutions]_ -_Source: [URL with {{current_year}} interoperability data]_ +_Source: [URL]_ ## 6. Performance and Scalability Analysis @@ -234,7 +234,7 @@ _Source: [URL with {{current_year}} interoperability data]_ _Performance Benchmarks: [Current performance characteristics and benchmarks]_ _Optimization Strategies: [Performance optimization approaches and techniques]_ _Monitoring and Measurement: [Performance monitoring and measurement practices]_ -_Source: [URL with {{current_year}} performance data]_ +_Source: [URL]_ ### Scalability Patterns and Approaches @@ -242,17 +242,17 @@ _Source: [URL with {{current_year}} performance data]_ _Scalability Patterns: [Architectural and design patterns for scalability]_ _Capacity Planning: [Capacity planning and resource management approaches]_ _Elasticity and Auto-scaling: [Dynamic scaling approaches and implementations]_ -_Source: [URL with {{current_year}} scalability data]_ +_Source: [URL]_ ## 7. Security and Compliance Considerations ### Security Best Practices and Frameworks -[Security analysis with {{current_year}} context] +[Security analysis with current context] _Security Frameworks: [Current security frameworks and best practices]_ _Threat Landscape: [Current security threats and mitigation approaches]_ _Secure Development Practices: [Secure coding and development lifecycle]_ -_Source: [URL with {{current_year}} security data]_ +_Source: [URL]_ ### Compliance and Regulatory Considerations @@ -260,7 +260,7 @@ _Source: [URL with {{current_year}} security data]_ _Industry Standards: [Relevant industry standards and compliance requirements]_ _Regulatory Compliance: [Legal and regulatory considerations for {{research_topic}}]_ _Audit and Governance: [Technical audit and governance practices]_ -_Source: [URL with {{current_year}} compliance data]_ +_Source: [URL]_ ## 8. Strategic Technical Recommendations @@ -270,7 +270,7 @@ _Source: [URL with {{current_year}} compliance data]_ _Architecture Recommendations: [Recommended architectural approaches and patterns]_ _Technology Selection: [Recommended technology stack and selection criteria]_ _Implementation Strategy: [Recommended implementation approaches and methodologies]_ -_Source: [URL with {{current_year}} technical strategy data]_ +_Source: [URL]_ ### Competitive Technical Advantage @@ -278,7 +278,7 @@ _Source: [URL with {{current_year}} technical strategy data]_ _Technology Differentiation: [Technical approaches that provide competitive advantage]_ _Innovation Opportunities: [Areas for technical innovation and differentiation]_ _Strategic Technology Investments: [Recommended technology investments and priorities]_ -_Source: [URL with {{current_year}} competitive analysis data]_ +_Source: [URL]_ ## 9. Implementation Roadmap and Risk Assessment @@ -288,7 +288,7 @@ _Source: [URL with {{current_year}} competitive analysis data]_ _Implementation Phases: [Recommended phased implementation approach]_ _Technology Migration Strategy: [Approach for technology adoption and migration]_ _Resource Planning: [Technical resources and capabilities planning]_ -_Source: [URL with {{current_year}} implementation planning data]_ +_Source: [URL]_ ### Technical Risk Management @@ -296,7 +296,7 @@ _Source: [URL with {{current_year}} implementation planning data]_ _Technical Risks: [Major technical risks and mitigation strategies]_ _Implementation Risks: [Risks associated with implementation and deployment]_ _Business Impact Risks: [Technical risks and their business implications]_ -_Source: [URL with {{current_year}} technical risk data]_ +_Source: [URL]_ ## 10. Future Technical Outlook and Innovation Opportunities @@ -306,7 +306,7 @@ _Source: [URL with {{current_year}} technical risk data]_ _Near-term Technical Evolution: [1-2 year technical development expectations]_ _Medium-term Technology Trends: [3-5 year expected technical developments]_ _Long-term Technical Vision: [5+ year technical outlook for {{research_topic}}]_ -_Source: [URL with {{current_year}} future trends data]_ +_Source: [URL]_ ### Innovation and Research Opportunities @@ -314,7 +314,7 @@ _Source: [URL with {{current_year}} future trends data]_ _Research Opportunities: [Areas for technical research and innovation]_ _Emerging Technology Adoption: [Potential new technologies and adoption timelines]_ _Innovation Framework: [Approach for fostering technical innovation]_ -_Source: [URL with {{current_year}} innovation data]_ +_Source: [URL]_ ## 11. Technical Research Methodology and Source Verification @@ -324,7 +324,6 @@ _Source: [URL with {{current_year}} innovation data]_ _Primary Technical Sources: [Key authoritative technical sources used]_ _Secondary Technical Sources: [Supporting technical research and analysis]_ _Technical Web Search Queries: [Complete list of technical search queries used]_ -_Technical Data Currency: [All technical data verified for {{current_year}} currency]_ ### Technical Research Quality Assurance @@ -370,9 +369,9 @@ _Technical Communities: [Professional networks and technical communities]_ --- **Technical Research Completion Date:** {{date}} -**Research Period:** {{current_year}} comprehensive technical analysis +**Research Period:** current comprehensive technical analysis **Document Length:** As needed for comprehensive technical coverage -**Source Verification:** All technical facts cited with {{current_year}} sources +**Source Verification:** All technical facts cited with current sources **Technical Confidence Level:** High - based on multiple authoritative technical sources _This comprehensive technical research document serves as an authoritative technical reference on {{research_topic}} and provides strategic technical insights for informed decision-making and implementation._ @@ -391,7 +390,7 @@ _This comprehensive technical research document serves as an authoritative techn - **Exhaustive Technical Research Coverage**: All technical aspects of {{research_topic}} thoroughly analyzed - **Executive Technical Summary**: Key technical findings and strategic implications highlighted - **Strategic Technical Recommendations**: Actionable technical insights based on comprehensive research -- **Complete Technical Source Citations**: Every technical claim verified with {{current_year}} sources +- **Complete Technical Source Citations**: Every technical claim verified with current sources **Technical Research Completeness:** @@ -407,7 +406,7 @@ _This comprehensive technical research document serves as an authoritative techn - Professional technical structure and compelling narrative - As long as needed for comprehensive technical coverage - Multiple independent technical sources for all claims -- {{current_year}} technical data throughout with proper citations +- current technical data throughout with proper citations **Ready to complete this comprehensive technical research document?** [C] Complete Research - Save final comprehensive technical document @@ -432,7 +431,7 @@ When user selects 'C', append the complete comprehensive technical research docu โœ… Exhaustive technical research coverage across all technical aspects โœ… Executive technical summary with key findings and strategic implications โœ… Strategic technical recommendations grounded in comprehensive research -โœ… Complete technical source verification with {{current_year}} citations +โœ… Complete technical source verification with current citations โœ… Professional technical document structure and compelling narrative โœ… [C] complete option presented and handled correctly โœ… Technical research workflow completed with comprehensive document @@ -444,7 +443,7 @@ When user selects 'C', append the complete comprehensive technical research docu โŒ Incomplete technical research coverage across technical aspects โŒ Not providing executive technical summary with key findings โŒ Missing strategic technical recommendations based on research -โŒ Not using {{current_year}} technical sources for all factual claims +โŒ Relying solely on training data without web verification for current facts โŒ Producing technical document without professional structure โŒ Not presenting completion option for final technical document @@ -481,6 +480,6 @@ Complete authoritative technical research document on {{research_topic}} that: - Establishes technical credibility through comprehensive research - Provides strategic technical insights for informed decision-making - Serves as technical reference document for continued use -- Maintains highest technical research quality standards with {{current_year}} verification +- Maintains highest technical research quality standards with current verification Congratulations on completing comprehensive technical research with professional documentation! ๐ŸŽ‰ diff --git a/src/modules/bmm/workflows/1-analysis/research/workflow.md b/src/modules/bmm/workflows/1-analysis/research/workflow.md index cbbacfd9..3441b90c 100644 --- a/src/modules/bmm/workflows/1-analysis/research/workflow.md +++ b/src/modules/bmm/workflows/1-analysis/research/workflow.md @@ -11,7 +11,7 @@ web_bundle: true **Document Standards:** - **Comprehensive Coverage**: Exhaustive research with no critical gaps -- **Source Verification**: Every factual claim cited with URLs from {{current_year}} +- **Source Verification**: Every factual claim backed by web sources with URL citations - **Document Length**: As long as needed to fully cover the research topic - **Professional Structure**: Compelling narrative introduction, detailed TOC, and comprehensive summary - **Authoritative Sources**: Multiple independent sources for all critical claims @@ -46,7 +46,7 @@ Load config from `{project-root}/{bmad_folder}/bmm/config.yaml` and resolve: - `project_name`, `output_folder`, `user_name` - `communication_language`, `document_output_language`, `user_skill_level` -- `date`, `current_year`, `current_month` as system-generated values +- `date` as a system-generated value - `enable_web_research = true` (web research is default behavior) ### Paths @@ -57,11 +57,17 @@ Load config from `{project-root}/{bmad_folder}/bmm/config.yaml` and resolve: --- +## PREREQUISITE + +**โ›” Web search required.** If unavailable, abort and tell the user. + +--- + ## RESEARCH BEHAVIOR ### Web Research Standards -- **Current Data Only**: Always use {{current_year}} in web searches +- **Current Data Only**: Search the web to verify and supplement your knowledge with current facts - **Source Verification**: Require citations for all factual claims - **Anti-Hallucination Protocol**: Never present information without verified sources - **Multiple Sources**: Require at least 2 independent sources for critical claims @@ -88,7 +94,7 @@ Execute research type discovery and routing: **Research Standards:** - **Anti-Hallucination Protocol**: Never present information without verified sources -- **Current Data Only**: Always use {{current_year}} in web searches +- **Current Data Only**: Search the web to verify and supplement your knowledge with current facts - **Source Citation**: Always include URLs for factual claims from web searches - **Multiple Sources**: Require 2+ independent sources for critical claims - **Conflict Resolution**: Present conflicting views and note discrepancies @@ -96,7 +102,7 @@ Execute research type discovery and routing: ### Collaborative Research Discovery -"Welcome {{user_name}}! I'm excited to work with you as your research partner. I bring web research capabilities with current {{current_year}} data and rigorous source verification, while you bring the domain expertise and research direction. +"Welcome {{user_name}}! I'm excited to work with you as your research partner. I bring web research capabilities with rigorous source verification, while you bring the domain expertise and research direction. **Let me help you clarify what you'd like to research.** @@ -190,10 +196,9 @@ research_topic: '{{research_topic}}' research_goals: '{{research_goals}}' user_name: '{{user_name}}' date: '{{date}}' -current_year: '{{current_year}}' web_research_enabled: true source_verification: true --- ``` -**Note:** All research workflows emphasize current web data with {{current_year}} searches and rigorous source verification. +**Note:** All research workflows require web search for current data and source verification. diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md index 2454af76..e3b3329d 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/prd-template.md @@ -1,6 +1,13 @@ --- stepsCompleted: [] inputDocuments: [] +documentCounts: + briefs: 0 + research: 0 + brainstorming: 0 + projectDocs: 0 +workflowType: 'prd' +lastStep: 0 --- # Product Requirements Document - {{project_name}} diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01-init.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01-init.md index 58b05c6f..d0a29cad 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01-init.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01-init.md @@ -1,43 +1,75 @@ +--- +name: 'step-01-init' +description: 'Initialize the PRD workflow by detecting continuation state and setting up the document' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-01-init.md' +nextStepFile: '{workflow_path}/steps/step-02-discovery.md' +continueStepFile: '{workflow_path}/steps/step-01b-continue.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Template References +prdTemplate: '{workflow_path}/prd-template.md' +--- + # Step 1: Workflow Initialization -**Progress: Step 1 of 10** - Next: Project Discovery +**Progress: Step 1 of 11** - Next: Project Discovery + +## STEP GOAL: + +Initialize the PRD workflow by detecting continuation state, discovering input documents, and setting up the document structure for collaborative product requirement discovery. ## MANDATORY EXECUTION RULES (READ FIRST): -- ๐Ÿ›‘ NEVER generate content without user input +### Universal Rules: -- ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions -- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS treat this as collaborative discovery between PM peers +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read - ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator -- ๐Ÿ’ฌ FOCUS on initialization and setup only - don't look ahead to future steps -- ๐Ÿšช DETECT existing workflow state and handle continuation properly + +### Role Reinforcement: + +- โœ… You are a product-focused PM facilitator collaborating with an expert peer +- โœ… If you already have been given a name, communication_style and persona, continue to use those while playing this new role +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus only on initialization and setup - no content generation yet +- ๐Ÿšซ FORBIDDEN to look ahead to future steps or assume knowledge from them +- ๐Ÿ’ฌ Approach: Systematic setup with clear reporting to user +- ๐Ÿšช Detect existing workflow state and handle continuation properly ## EXECUTION PROTOCOLS: -- ๐ŸŽฏ Show your analysis before taking any action -- ๐Ÿ’พ Initialize document and update frontmatter +- ๐ŸŽฏ Show your analysis of current state before taking any action +- ๐Ÿ’พ Initialize document structure and update frontmatter appropriately - ๐Ÿ“– Set up frontmatter `stepsCompleted: [1]` before loading next step -- ๐Ÿšซ FORBIDDEN to load next step until setup is complete +- ๐Ÿšซ FORBIDDEN to load next step until user selects 'C' (Continue) ## CONTEXT BOUNDARIES: -- Variables from workflow.md are available in memory -- Previous context = what's in output document + frontmatter -- Don't assume knowledge from other steps -- Input document discovery happens in this step +- Available context: Variables from workflow.md are available in memory +- Focus: Workflow initialization and document setup only +- Limits: Don't assume knowledge from other steps or create content yet +- Dependencies: Configuration loaded from workflow.md initialization -## YOUR TASK: +## Sequence of Instructions (Do not deviate, skip, or optimize) -Initialize the PRD workflow by detecting continuation state and setting up the document. - -## INITIALIZATION SEQUENCE: - -### 1. Check for Existing Workflow +### 1. Check for Existing Workflow State First, check if the output document already exists: -- Look for file at `{output_folder}/prd.md` +**Workflow State Detection:** + +- Look for file at `{outputFile}` - If exists, read the complete file including frontmatter - If not exists, this is a fresh workflow @@ -45,9 +77,12 @@ First, check if the output document already exists: If the document exists and has frontmatter with `stepsCompleted`: -- **STOP here** and load `./step-01b-continue.md` immediately +**Continuation Protocol:** + +- **STOP immediately** and load `{continueStepFile}` - Do not proceed with any initialization tasks -- Let step-01b handle the continuation logic +- Let step-01b handle all continuation logic +- This is an auto-proceed situation - no user choice needed ### 3. Fresh Workflow Setup (If No Document) @@ -55,7 +90,18 @@ If no document exists or no `stepsCompleted` in frontmatter: #### A. Input Document Discovery -Discover and load context documents using smart discovery: +Discover and load context documents using smart discovery. + +**IMPORTANT: Track document counts as you discover files.** + +Initialize counters: + +``` +briefCount = 0 +researchCount = 0 +brainstormingCount = 0 +projectDocsCount = 0 +``` **Product Brief (Priority: Analysis โ†’ Main โ†’ Sharded โ†’ Whole):** @@ -64,6 +110,7 @@ Discover and load context documents using smart discovery: 3. If no main files: Check for sharded brief folder: `{output_folder}/*brief*/**/*.md` 4. If sharded folder exists: Load EVERY file in that folder completely 5. Add discovered files to `inputDocuments` frontmatter +6. **Update briefCount with number of files found** **Research Documents (Priority: Analysis โ†’ Main โ†’ Sharded โ†’ Whole):** @@ -72,20 +119,23 @@ Discover and load context documents using smart discovery: 3. If no main files: Check for sharded research folder: `{output_folder}/*research*/**/*.md` 4. Load useful research files completely 5. Add discovered files to `inputDocuments` frontmatter +6. **Update researchCount with number of files found** **Brainstorming Documents (Priority: Analysis โ†’ Main):** 1. Check analysis folder: `{output_folder}/analysis/brainstorming/*brainstorming*.md` 2. If no analysis files: Try main folder: `{output_folder}/*brainstorming*.md` 3. Add discovered files to `inputDocuments` frontmatter +4. **Update brainstormingCount with number of files found** -**Project Documentation (Existing Projects):** +**Project Documentation (Existing Projects - Brownfield):** 1. Look for index file: `{output_folder}/index.md` 2. CRITICAL: Load index.md to understand what project files are available 3. Read available files from index to understand existing project context 4. This provides essential context for extending existing project with new PRD 5. Add discovered files to `inputDocuments` frontmatter +6. **Update projectDocsCount with number of files found (including index.md)** **Loading Rules:** @@ -96,13 +146,20 @@ Discover and load context documents using smart discovery: #### B. Create Initial Document -Copy the template from `{installed_path}/prd-template.md` to `{output_folder}/prd.md` -Initialize frontmatter with: +**Document Setup:** + +- Copy the template from `{prdTemplate}` to `{outputFile}` +- Initialize frontmatter with proper structure including document counts: ```yaml --- stepsCompleted: [] inputDocuments: [] +documentCounts: + briefs: { { briefCount } } + research: { { researchCount } } + brainstorming: { { brainstormingCount } } + projectDocs: { { projectDocsCount } } workflowType: 'prd' lastStep: 0 project_name: '{{project_name}}' @@ -111,51 +168,76 @@ date: '{{date}}' --- ``` -#### C. Complete Initialization and Report +#### C. Present Initialization Results -Complete setup and report to user: +**Setup Report to User:** + +"Welcome {{user_name}}! I've set up your PRD workspace for {{project_name}}. **Document Setup:** -- Created: `{output_folder}/prd.md` from template +- Created: `{outputFile}` from template - Initialized frontmatter with workflow state **Input Documents Discovered:** -Report what was found: -"Welcome {{user_name}}! I've set up your PRD workspace for {{project_name}}. -**Documents Found:** - -- Product brief: {number of brief files loaded or "None found"} -- Research: {number of research files loaded or "None found"} -- Project docs: {number of project files loaded or "None found"} +- Product briefs: {{briefCount}} files {if briefCount > 0}โœ“ loaded{else}(none found){/if} +- Research: {{researchCount}} files {if researchCount > 0}โœ“ loaded{else}(none found){/if} +- Brainstorming: {{brainstormingCount}} files {if brainstormingCount > 0}โœ“ loaded{else}(none found){/if} +- Project docs: {{projectDocsCount}} files {if projectDocsCount > 0}โœ“ loaded (brownfield project){else}(none found - greenfield project){/if} **Files loaded:** {list of specific file names or "No additional documents found"} -Do you have any other documents you'd like me to include, or shall we continue to the next step? +{if projectDocsCount > 0} +๐Ÿ“‹ **Note:** This is a **brownfield project**. Your existing project documentation has been loaded. In the next step, I'll ask specifically about what new features or changes you want to add to your existing system. +{/if} -[C] Continue - Save this and move to Project Discovery (Step 2 of 10) +Do you have any other documents you'd like me to include, or shall we continue to the next step?" -## SUCCESS METRICS: +### 4. Present MENU OPTIONS -โœ… Existing workflow detected and handed off to step-01b correctly -โœ… Fresh workflow initialized with template and frontmatter -โœ… Input documents discovered and loaded using sharded-first logic -โœ… All discovered files tracked in frontmatter `inputDocuments` -โœ… User confirmed document setup and can proceed +Display menu after setup report: -## FAILURE MODES: +"[C] Continue - Save this and move to Project Discovery (Step 2 of 11)" -โŒ Proceeding with fresh initialization when existing workflow exists -โŒ Not updating frontmatter with discovered input documents -โŒ Creating document without proper template -โŒ Not checking sharded folders first before whole files -โŒ Not reporting what documents were found to user +#### Menu Handling Logic: -โŒ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions -โŒ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file -โŒ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols +- IF C: Update frontmatter with `stepsCompleted: [1]`, then load, read entire file, then execute {nextStepFile} +- IF user provides additional files: Load them, update inputDocuments and documentCounts, redisplay report +- IF user asks questions: Answer and redisplay menu -## NEXT STEP: +#### EXECUTION RULES: -After user selects [C] to continue, load `{installed_path}/step/step-02-discovery.md` to begin the project discovery phase. +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [frontmatter properly updated with stepsCompleted: [1] and documentCounts], will you then load and read fully `{nextStepFile}` to execute and begin project discovery. + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- Existing workflow detected and properly handed off to step-01b +- Fresh workflow initialized with template and proper frontmatter +- Input documents discovered and loaded using sharded-first logic +- All discovered files tracked in frontmatter `inputDocuments` +- **Document counts stored in frontmatter `documentCounts`** +- User clearly informed of brownfield vs greenfield status +- Menu presented and user input handled correctly +- Frontmatter updated with `stepsCompleted: [1]` before proceeding + +### โŒ SYSTEM FAILURE: + +- Proceeding with fresh initialization when existing workflow exists +- Not updating frontmatter with discovered input documents +- **Not storing document counts in frontmatter** +- Creating document without proper template structure +- Not checking sharded folders first before whole files +- Not reporting discovered documents to user clearly +- Proceeding without user selecting 'C' (Continue) + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01b-continue.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01b-continue.md index 4d602e82..1b0abb30 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01b-continue.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-01b-continue.md @@ -1,56 +1,81 @@ +--- +name: 'step-01b-continue' +description: 'Resume an interrupted PRD workflow from the last completed step' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-01b-continue.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' +--- + # Step 1B: Workflow Continuation +## STEP GOAL: + +Resume the PRD workflow from where it was left off, ensuring smooth continuation with full context restoration. + ## MANDATORY EXECUTION RULES (READ FIRST): -- ๐Ÿ›‘ NEVER generate content without user input +### Universal Rules: -- ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions -- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS treat this as collaborative discovery between PM peers +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read - ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator + +### Role Reinforcement: + +- โœ… You are a product-focused PM facilitator collaborating with an expert peer +- โœ… We engage in collaborative dialogue, not command-response +- โœ… Resume workflow from exact point where it was interrupted + +### Step-Specific Rules: + - ๐Ÿ’ฌ FOCUS on understanding where we left off and continuing appropriately -- ๐Ÿšช RESUME workflow from exact point where it was interrupted +- ๐Ÿšซ FORBIDDEN to modify content completed in previous steps +- ๐Ÿ“– Only reload documents that were already tracked in `inputDocuments` ## EXECUTION PROTOCOLS: - ๐ŸŽฏ Show your analysis of current state before taking action - ๐Ÿ’พ Keep existing frontmatter `stepsCompleted` values - ๐Ÿ“– Only load documents that were already tracked in `inputDocuments` -- ๐Ÿšซ FORBIDDEN to modify content completed in previous steps +- ๐Ÿšซ FORBIDDEN to discover new input documents during continuation ## CONTEXT BOUNDARIES: -- Current document and frontmatter are already loaded -- Previous context = complete document + existing frontmatter -- Input documents listed in frontmatter were already processed -- Last completed step = `lastStep` value from frontmatter +- Available context: Current document and frontmatter are already loaded +- Focus: Workflow state analysis and continuation logic only +- Limits: Don't assume knowledge beyond what's in the document +- Dependencies: Existing workflow state from previous session -## YOUR TASK: - -Resume the PRD workflow from where it was left off, ensuring smooth continuation. - -## CONTINUATION SEQUENCE: +## Sequence of Instructions (Do not deviate, skip, or optimize) ### 1. Analyze Current State +**State Assessment:** Review the frontmatter to understand: - `stepsCompleted`: Which steps are already done - `lastStep`: The most recently completed step number - `inputDocuments`: What context was already loaded +- `documentCounts`: briefs, research, brainstorming, projectDocs counts - All other frontmatter variables -### 2. Load All Input Documents +### 2. Restore Context Documents -Reload the context documents listed in `inputDocuments`: +**Context Reloading:** - For each document in `inputDocuments`, load the complete file - This ensures you have full context for continuation - Don't discover new documents - only reload what was previously processed -### 3. Summarize Current Progress +### 3. Present Current Progress -Welcome the user back and provide context: +**Progress Report to User:** "Welcome back {{user_name}}! I'm resuming our PRD collaboration for {{project_name}}. **Current Progress:** @@ -66,47 +91,29 @@ Welcome the user back and provide context: Does this look right, or do you want to make any adjustments before we proceed?" -### 4. Determine Next Step +### 4. Determine Continuation Path +**Next Step Logic:** Based on `lastStep` value, determine which step to load next: - If `lastStep = 1` โ†’ Load `./step-02-discovery.md` - If `lastStep = 2` โ†’ Load `./step-03-success.md` - If `lastStep = 3` โ†’ Load `./step-04-journeys.md` -- Continue this pattern for all steps -- If `lastStep = 10` โ†’ Workflow already complete +- If `lastStep = 4` โ†’ Load `./step-05-domain.md` +- If `lastStep = 5` โ†’ Load `./step-06-innovation.md` +- If `lastStep = 6` โ†’ Load `./step-07-project-type.md` +- If `lastStep = 7` โ†’ Load `./step-08-scoping.md` +- If `lastStep = 8` โ†’ Load `./step-09-functional.md` +- If `lastStep = 9` โ†’ Load `./step-10-nonfunctional.md` +- If `lastStep = 10` โ†’ Load `./step-11-complete.md` +- If `lastStep = 11` โ†’ Workflow already complete -### 5. Present Continuation Options +### 5. Handle Workflow Completion -After presenting current progress, ask: -"Ready to continue with Step {nextStepNumber}: {nextStepTitle}? - -[C] Continue to Step {nextStepNumber}" - -## SUCCESS METRICS: - -โœ… All previous input documents successfully reloaded -โœ… Current workflow state accurately analyzed and presented -โœ… User confirms understanding of progress -โœ… Correct next step identified and prepared for loading - -## FAILURE MODES: - -โŒ Discovering new input documents instead of reloading existing ones -โŒ Modifying content from already completed steps -โŒ Loading wrong next step based on `lastStep` value -โŒ Proceeding without user confirmation of current state - -โŒ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions -โŒ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file -โŒ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols - -## WORKFLOW ALREADY COMPLETE? - -If `lastStep = 10` (final step completed): +**If workflow already complete (`lastStep = 11`):** "Great news! It looks like we've already completed the PRD workflow for {{project_name}}. -The final document is ready at {output_folder}/prd.md with all sections completed through step 10. +The final document is ready at `{outputFile}` with all sections completed through step 11. Would you like me to: @@ -116,8 +123,43 @@ Would you like me to: What would be most helpful?" -## NEXT STEP: +### 6. Present MENU OPTIONS -After user confirms they're ready to continue, load the appropriate next step file based on the `lastStep` value from frontmatter. +**If workflow not complete:** +Display: "Ready to continue with Step {nextStepNumber}? -Remember: Do NOT load the next step until user explicitly selects [C] to continue! +**Select an Option:** [C] Continue to next step" + +#### Menu Handling Logic: + +- IF C: Load, read entire file, then execute the appropriate next step file based on `lastStep` +- IF Any other comments or queries: respond and redisplay menu + +#### EXECUTION RULES: + +- ALWAYS halt and wait for user input after presenting menu +- ONLY proceed to next step when user selects 'C' + +## CRITICAL STEP COMPLETION NOTE + +ONLY WHEN [C continue option] is selected and [current state confirmed], will you then load and read fully the appropriate next step file to resume the workflow. + +--- + +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS + +### โœ… SUCCESS: + +- All previous input documents successfully reloaded +- Current workflow state accurately analyzed and presented +- User confirms understanding of progress before continuation +- Correct next step identified and prepared for loading + +### โŒ SYSTEM FAILURE: + +- Discovering new input documents instead of reloading existing ones +- Modifying content from already completed steps +- Loading wrong next step based on `lastStep` value +- Proceeding without user confirmation of current state + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-02-discovery.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-02-discovery.md index 5a023154..c4be410a 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-02-discovery.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-02-discovery.md @@ -1,16 +1,53 @@ +--- +name: 'step-02-discovery' +description: 'Conduct project and domain discovery with data-driven classification' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-02-discovery.md' +nextStepFile: '{workflow_path}/steps/step-03-success.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Data Files +projectTypesCSV: '{workflow_path}/project-types.csv' +domainComplexityCSV: '{workflow_path}/domain-complexity.csv' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 2: Project & Domain Discovery -**Progress: Step 2 of 10** - Next: Success Criteria Definition +**Progress: Step 2 of 11** - Next: Success Criteria Definition + +## STEP GOAL: + +Conduct comprehensive project discovery that leverages existing input documents while allowing user refinement, with data-driven classification, and generate the Executive Summary content. ## MANDATORY EXECUTION RULES (READ FIRST): -- ๐Ÿ›‘ NEVER generate content without user input +### Universal Rules: -- ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions -- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding -- โœ… ALWAYS treat this as collaborative discovery between PM peers +- ๐Ÿ›‘ NEVER generate content without user input +- ๐Ÿ“– CRITICAL: Read the complete step file before taking any action +- ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure entire file is read - ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator -- ๐Ÿ’ฌ FOCUS on project classification and vision alignment only + +### Role Reinforcement: + +- โœ… You are a product-focused PM facilitator collaborating with an expert peer +- โœ… We engage in collaborative dialogue, not command-response +- โœ… You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision + +### Step-Specific Rules: + +- ๐ŸŽฏ Focus on project classification and vision alignment only +- ๐Ÿšซ FORBIDDEN to generate content without real user input +- ๐Ÿ’ฌ APPROACH: Adapt questions based on document context (brownfield vs greenfield) - ๐ŸŽฏ LOAD classification data BEFORE starting discovery conversation ## EXECUTION PROTOCOLS: @@ -31,8 +68,8 @@ This step will generate content and present choices: ## PROTOCOL INTEGRATION: -- When 'A' selected: Execute {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml -- When 'P' selected: Execute {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md +- When 'A' selected: Execute {advancedElicitationTask} +- When 'P' selected: Execute {partyModeWorkflow} - PROTOCOLS always return to this step's A/P/C menu - User accepts/rejects protocol changes before proceeding @@ -40,40 +77,56 @@ This step will generate content and present choices: - Current document and frontmatter from step 1 are available - Input documents already loaded are in memory (product briefs, research, brainstorming, project docs) +- **Document counts available in frontmatter `documentCounts`** - Classification CSV data will be loaded in this step only - This will be the first content section appended to the document -- LEVERAGE existing input documents to accelerate discovery process -- installed_path = `{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd` -## YOUR TASK: +## Sequence of Instructions (Do not deviate, skip, or optimize) -Conduct comprehensive project discovery that leverages existing input documents while allowing user refinement, with data-driven classification and generate the first content section. +### 1. Read Document State from Frontmatter -## DISCOVERY SEQUENCE: +**CRITICAL FIRST ACTION:** Read the frontmatter from `{outputFile}` to get document counts. -### 1. Load Classification Data +``` +Read documentCounts from prd.md frontmatter: +- briefCount = documentCounts.briefs +- researchCount = documentCounts.research +- brainstormingCount = documentCounts.brainstorming +- projectDocsCount = documentCounts.projectDocs +``` + +**ANNOUNCE your understanding:** + +"From step 1, I have loaded: + +- Product briefs: {{briefCount}} files +- Research: {{researchCount}} files +- Brainstorming: {{brainstormingCount}} files +- Project docs: {{projectDocsCount}} files + +{if projectDocsCount > 0}This is a **brownfield project** - I'll focus on understanding what you want to add or change.{else}This is a **greenfield project** - I'll help you define the full product vision.{/if}" + +### 2. Load Classification Data Load and prepare CSV data for intelligent classification: -- Load `{installed_path}/project-types.csv` completely -- Load `{installed_path/domain-complexity.csv` completely +- Load `{projectTypesCSV}` completely +- Load `{domainComplexityCSV}` completely - Parse column structures and store in memory for this step only -### 2. Leverage Input Documents for Head Start +### 3. Begin Discovery Conversation -Analyze available input documents to provide informed discovery: +**SELECT EXACTLY ONE DISCOVERY PATH based on document state:** -**Check Input Documents Available:** +--- -- Product Briefs: {{number_of_briefs}} documents loaded -- Research Documents: {{number_of_research}} documents loaded -- Brainstorming Results: {{number_of_brainstorming}} documents loaded -- Project Documentation: {{number_of_project_docs}} documents loaded +#### PATH A: Has Product Brief (briefCount > 0) -**If Input Documents Exist:** -"As your PM peer, I've reviewed your existing project documentation and have a great starting point for our discovery. Let me share what I understand and you can refine or correct as needed. +**Use this path when:** `briefCount > 0` -**Based on your product brief and research:** +"As your PM peer, I've reviewed your product brief and have a great starting point for our discovery. Let me share what I understand and you can refine or correct as needed. + +**Based on your product brief:** **What you're building:** {{extracted_vision_from_brief}} @@ -87,9 +140,47 @@ Analyze available input documents to provide informed discovery: **What makes it special:** {{extracted_differentiator_from_brief}} +{if projectDocsCount > 0}I also see you have existing project documentation. This PRD will define how new features integrate with your existing system architecture.{/if} + **How does this align with your vision?** Should we refine any of these points or are there important aspects I'm missing?" -**If No Input Documents:** +**AFTER this message, SKIP to Section 4.** + +--- + +#### PATH B: No Brief but Has Project Docs - Brownfield (briefCount == 0 AND projectDocsCount > 0) + +**Use this path when:** `briefCount == 0 AND projectDocsCount > 0` + +**NOTE:** Extract the following from loaded project documentation (index.md, architecture.md, project-overview.md, etc.): + +"As your PM peer, I've reviewed your existing project documentation from document-project. + +**Your existing system includes:** + +- **Tech Stack:** {analyze index.md and architecture.md for technologies used} +- **Architecture:** {summarize architecture patterns from architecture.md} +- **Key Components:** {list main components from source-tree-analysis.md or project-overview.md} + +This PRD will define **new features or changes** to add to this existing codebase. + +**Tell me about what you want to add or change:** + +- What new capability or feature do you want to build? +- What problem will this solve for your users? +- How should it integrate with the existing system? +- Is this adding new functionality, improving existing features, or fixing issues? + +I'll help you create a PRD focused on these additions while respecting your existing patterns and architecture." + +**AFTER this message, SKIP to Section 4.** + +--- + +#### PATH C: No Documents - Greenfield (briefCount == 0 AND projectDocsCount == 0) + +**Use this path when:** `briefCount == 0 AND projectDocsCount == 0` + "As your PM peer, I'm excited to help you shape {{project_name}}. Let me start by understanding what you want to build. **Tell me about what you want to create:** @@ -100,9 +191,13 @@ Analyze available input documents to provide informed discovery: I'll be listening for signals to help us classify the project and domain so we can ask the right questions throughout our process." -### 3. Listen for Classification Signals +**AFTER this message, continue to Section 4.** -As the user describes their product, listen for and match against: +--- + +### 4. Listen for Classification Signals + +As the user describes their product/feature, listen for and match against: #### Project Type Signals @@ -122,11 +217,14 @@ Compare user description against `signals` from `domain-complexity.csv`: - Examples: "payment,banking,trading" โ†’ fintech - Store the matched `domain` and `complexity_level` -### 4. Enhanced Classification with Document Context +### 5. Present Classification for Validation -Leverage both user input and document analysis for classification: +**SELECT EXACTLY ONE CLASSIFICATION PRESENTATION based on document state:** + +--- + +#### IF PATH A was used (briefCount > 0): -**If Input Documents Exist:** "Based on your product brief and our discussion, I'm classifying this as: - **Project Type:** {project_type_from_brief_or_conversation} @@ -136,10 +234,33 @@ Leverage both user input and document analysis for classification: From your brief, I detected these classification signals: {{classification_signals_from_brief}} +{if projectDocsCount > 0}Your existing project documentation also indicates: + +- **Existing Tech Stack:** {from architecture.md or index.md} +- **Architecture Pattern:** {from architecture.md} + +I'll ensure the new features align with your existing system.{/if} + Combined with our conversation, this suggests the above classification. Does this sound right?" -**If No Input Documents:** -Present your classifications for user validation: +--- + +#### IF PATH B was used (briefCount == 0 AND projectDocsCount > 0): + +"Based on your existing project documentation and our discussion about new features: + +- **Existing Project Type:** {detected from project docs - e.g., web_app, api_backend} +- **Tech Stack:** {from architecture.md or index.md} +- **New Feature Type:** {from user's description of what they want to add} +- **Domain:** {detected_domain} +- **Complexity:** {complexity_level} + +I'll ensure the PRD aligns with your existing architecture patterns. Does this classification sound right?" + +--- + +#### IF PATH C was used (briefCount == 0 AND projectDocsCount == 0): + "Based on our conversation, I'm hearing this as: - **Project Type:** {detected_project_type} @@ -148,11 +269,16 @@ Present your classifications for user validation: Does this sound right to you? I want to make sure we're on the same page before diving deeper." -### 5. Identify What Makes It Special +--- -Leverage input documents for initial understanding, then refine: +### 6. Identify What Makes It Special + +**SELECT EXACTLY ONE DIFFERENTIATOR DISCOVERY based on document state:** + +--- + +#### IF PATH A was used (briefCount > 0): -**If Input Documents Exist:** "From your product brief, I understand that what makes this special is: {{extracted_differentiator_from_brief}} @@ -162,7 +288,21 @@ Let's explore this deeper: - **Missing aspects:** Are there other differentiators that aren't captured in your brief? - **Evolution:** How has your thinking on this evolved since you wrote the brief?" -**If No Input Documents:** +--- + +#### IF PATH B was used (briefCount == 0 AND projectDocsCount > 0): + +"Your existing system already provides certain capabilities. Now let's define what makes these **new additions** special: + +- What gap in your current system will this fill? +- How will this improve the experience for your existing users? +- What's the key insight that led you to prioritize this addition? +- What would make users say 'finally, this is what we needed'?" + +--- + +#### IF PATH C was used (briefCount == 0 AND projectDocsCount == 0): + Ask focused questions to capture the product's unique value: - "What would make users say 'this is exactly what I needed'?" @@ -170,7 +310,9 @@ Ask focused questions to capture the product's unique value: - "What assumption about [problem space] are you challenging?" - "If this succeeds wildly, what changed for your users?" -### 6. Generate Executive Summary Content +--- + +### 7. Generate Executive Summary Content Based on the conversation, prepare the content to append to the document: @@ -190,75 +332,84 @@ Based on the conversation, prepare the content to append to the document: **Technical Type:** {project_type} **Domain:** {domain} **Complexity:** {complexity_level} +{if projectDocsCount > 0}**Project Context:** Brownfield - extending existing system{else}**Project Context:** Greenfield - new project{/if} {project_classification_content} ``` -### 7. Present Content and Menu +### 8. Present Content and Menu Show the generated content to the user and present: + "I've drafted our Executive Summary based on our conversation. This will be the first section of your PRD. **Here's what I'll add to the document:** -[Show the complete markdown content from step 6] +[Show the complete markdown content from step 7] -**What would you like to do?** +**Select an Option:** [A] Advanced Elicitation - Let's dive deeper and refine this content [P] Party Mode - Bring in different perspectives to improve this -[C] Continue - Save this and move to Success Criteria Definition (Step 3 of 10)" +[C] Continue - Save this and move to Success Criteria Definition (Step 3 of 11)" -### 8. Handle Menu Selection +### 9. Handle Menu Selection -#### If 'A' (Advanced Elicitation): +#### IF A (Advanced Elicitation): -- Execute {project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml with the current content +- Execute {advancedElicitationTask} with the current content - Process the enhanced content that comes back - Ask user: "Accept these changes to the Executive Summary? (y/n)" - If yes: Update the content with improvements, then return to A/P/C menu - If no: Keep original content, then return to A/P/C menu -#### If 'P' (Party Mode): +#### IF P (Party Mode): -- Execute {project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md with the current content +- Execute {partyModeWorkflow} with the current content - Process the collaborative improvements that come back - Ask user: "Accept these changes to the Executive Summary? (y/n)" - If yes: Update the content with improvements, then return to A/P/C menu - If no: Keep original content, then return to A/P/C menu -#### If 'C' (Continue): +#### IF C (Continue): -- Append the final content to `{output_folder}/prd.md` +- Append the final content to `{outputFile}` - Update frontmatter: `stepsCompleted: [1, 2]` -- Load `./step-03-success.md` +- Load `{nextStepFile}` -## APPEND TO DOCUMENT: +## CRITICAL STEP COMPLETION NOTE -When user selects 'C', append the content directly to the document using the structure from step 6. +ONLY WHEN [C continue option] is selected and [executive summary content finalized and saved to document with frontmatter updated], will you then load and read fully `{nextStepFile}` to execute and begin success criteria definition. -## SUCCESS METRICS: +--- -โœ… Classification data loaded and used effectively -โœ… Input documents analyzed and leveraged for head start -โœ… User classifications validated and confirmed -โœ… Product differentiator clearly identified and refined -โœ… Executive summary content generated collaboratively with document context -โœ… A/P/C menu presented and handled correctly -โœ… Content properly appended to document when C selected +## ๐Ÿšจ SYSTEM SUCCESS/FAILURE METRICS -## FAILURE MODES: +### โœ… SUCCESS: -โŒ Skipping classification data loading and guessing classifications -โŒ Not leveraging existing input documents to accelerate discovery -โŒ Not validating classifications with user before proceeding -โŒ Generating executive summary without real user input -โŒ Missing the "what makes it special" discovery and refinement -โŒ Not presenting A/P/C menu after content generation -โŒ Appending content without user selecting 'C' +- Document counts read from frontmatter and announced +- Classification data loaded and used effectively +- **Correct discovery path selected based on document counts** +- Input documents analyzed and leveraged for head start +- User classifications validated and confirmed +- Product differentiator clearly identified and refined +- Executive summary content generated collaboratively with document context +- A/P/C menu presented and handled correctly +- Content properly appended to document when C selected +- Frontmatter updated with stepsCompleted: [1, 2] -โŒ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions -โŒ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file -โŒ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols +### โŒ SYSTEM FAILURE: + +- **Not reading documentCounts from frontmatter first** +- **Executing multiple discovery paths instead of exactly one** +- Skipping classification data loading and guessing classifications +- Not leveraging existing input documents to accelerate discovery +- Not validating classifications with user before proceeding +- Generating executive summary without real user input +- Missing the "what makes it special" discovery and refinement +- Not presenting A/P/C menu after content generation +- Appending content without user selecting 'C' + +**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. ## COMPLEXITY HANDLING: @@ -267,9 +418,3 @@ If `complexity_level = "high"`: - Note the `suggested_workflow` and `web_searches` from domain CSV - Consider mentioning domain research needs in classification section - Document complexity implications in project classification - -## NEXT STEP: - -After user selects 'C' and content is saved to document, load `installed_path/steps/step-03-success.md` to define success criteria. - -Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved! diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-03-success.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-03-success.md index aa4d30b8..9c8f125c 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-03-success.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-03-success.md @@ -1,6 +1,24 @@ +--- +name: 'step-03-success' +description: 'Define comprehensive success criteria covering user, business, and technical success' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-03-success.md' +nextStepFile: '{workflow_path}/steps/step-04-journeys.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 3: Success Criteria Definition -**Progress: Step 3 of 10** - Next: User Journey Mapping +**Progress: Step 3 of 11** - Next: User Journey Mapping ## MANDATORY EXECUTION RULES (READ FIRST): @@ -204,7 +222,7 @@ Show the generated content and present choices: **What would you like to do?** [A] Advanced Elicitation - Let's dive deeper and refine these success metrics [P] Party Mode - Bring in different perspectives on success criteria -[C] Continue - Save success criteria and move to User Journey Mapping (Step 4 of 10)" +[C] Continue - Save success criteria and move to User Journey Mapping (Step 4 of 11)" ### 9. Handle Menu Selection diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-04-journeys.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-04-journeys.md index 5de02ea9..e9b2d137 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-04-journeys.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-04-journeys.md @@ -1,3 +1,21 @@ +--- +name: 'step-04-journeys' +description: 'Map ALL user types that interact with the system with narrative story-based journeys' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-04-journeys.md' +nextStepFile: '{workflow_path}/steps/step-05-domain.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 4: User Journey Mapping **Progress: Step 4 of 11** - Next: Domain Requirements diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-05-domain.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-05-domain.md index 2dadc6c7..5fd01fc9 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-05-domain.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-05-domain.md @@ -1,3 +1,24 @@ +--- +name: 'step-05-domain' +description: 'Explore domain-specific requirements for complex domains (optional step)' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-05-domain.md' +nextStepFile: '{workflow_path}/steps/step-06-innovation.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Data Files +domainComplexityCSV: '{workflow_path}/domain-complexity.csv' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 5: Domain-Specific Exploration **Progress: Step 5 of 11** - Next: Innovation Focus diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-06-innovation.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-06-innovation.md index f4740d69..45e33c09 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-06-innovation.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-06-innovation.md @@ -1,3 +1,24 @@ +--- +name: 'step-06-innovation' +description: 'Detect and explore innovative aspects of the product (optional step)' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-06-innovation.md' +nextStepFile: '{workflow_path}/steps/step-07-project-type.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Data Files +projectTypesCSV: '{workflow_path}/project-types.csv' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 6: Innovation Discovery **Progress: Step 6 of 11** - Next: Project Type Analysis diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-07-project-type.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-07-project-type.md index 5f61bd04..af887c16 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-07-project-type.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-07-project-type.md @@ -1,3 +1,24 @@ +--- +name: 'step-07-project-type' +description: 'Conduct project-type specific discovery using CSV-driven guidance' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-07-project-type.md' +nextStepFile: '{workflow_path}/steps/step-08-scoping.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Data Files +projectTypesCSV: '{workflow_path}/project-types.csv' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 7: Project-Type Deep Dive **Progress: Step 7 of 11** - Next: Scoping diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-08-scoping.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-08-scoping.md index 6daeb1f2..a2fe4602 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-08-scoping.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-08-scoping.md @@ -1,3 +1,21 @@ +--- +name: 'step-08-scoping' +description: 'Define MVP boundaries and prioritize features across development phases' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-08-scoping.md' +nextStepFile: '{workflow_path}/steps/step-09-functional.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 8: Scoping Exercise - MVP & Future Features **Progress: Step 8 of 11** - Next: Functional Requirements diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-09-functional.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-09-functional.md index 08806a12..66f83fb4 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-09-functional.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-09-functional.md @@ -1,3 +1,21 @@ +--- +name: 'step-09-functional' +description: 'Synthesize all discovery into comprehensive functional requirements' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-09-functional.md' +nextStepFile: '{workflow_path}/steps/step-10-nonfunctional.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 9: Functional Requirements Synthesis **Progress: Step 9 of 11** - Next: Non-Functional Requirements diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-10-nonfunctional.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-10-nonfunctional.md index c4af4b9b..a99f0e0c 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-10-nonfunctional.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-10-nonfunctional.md @@ -1,3 +1,21 @@ +--- +name: 'step-10-nonfunctional' +description: 'Define quality attributes that matter for this specific product' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-10-nonfunctional.md' +nextStepFile: '{workflow_path}/steps/step-11-complete.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' + +# Task References +advancedElicitationTask: '{project-root}/{bmad_folder}/core/tasks/advanced-elicitation.xml' +partyModeWorkflow: '{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md' +--- + # Step 10: Non-Functional Requirements **Progress: Step 10 of 11** - Next: Complete PRD diff --git a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-11-complete.md b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-11-complete.md index 6c26261d..c32de8d5 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-11-complete.md +++ b/src/modules/bmm/workflows/2-plan-workflows/prd/steps/step-11-complete.md @@ -1,3 +1,16 @@ +--- +name: 'step-11-complete' +description: 'Complete the PRD workflow, update status files, and suggest next steps' + +# Path Definitions +workflow_path: '{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/prd' + +# File References +thisStepFile: '{workflow_path}/steps/step-11-complete.md' +workflowFile: '{workflow_path}/workflow.md' +outputFile: '{output_folder}/prd.md' +--- + # Step 11: Workflow Completion **Final Step - Complete the PRD** diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md b/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md index 8421851a..5fdca68c 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md @@ -6,7 +6,7 @@ - โœ… ALWAYS treat this as collaborative discovery between architectural peers - ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator - ๐Ÿ’ฌ FOCUS on evaluating starter template options with current versions -- ๐ŸŒ ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions +- ๐ŸŒ ALWAYS search the web to verify current versions - NEVER trust hardcoded versions - โš ๏ธ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed - ๐Ÿ“– CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete architecture - ๐Ÿ”„ CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding @@ -14,7 +14,7 @@ ## EXECUTION PROTOCOLS: - ๐ŸŽฏ Show your analysis before taking any action -- ๐ŸŒ Use WebSearch to verify current versions and options +- ๐ŸŒ Search the web to verify current versions and options - โš ๏ธ Present A/P/C menu after generating starter template analysis - ๐Ÿ’พ ONLY save when user chooses C (Continue) - ๐Ÿ“– Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step @@ -118,12 +118,12 @@ If UX specification was loaded, consider UX requirements when selecting starter: ### 3. Research Current Starter Options -Use WebSearch to find current, maintained starter templates: +Search the web to find current, maintained starter templates: ``` -WebSearch: {{primary_technology}} starter template CLI create command latest 2024 -WebSearch: {{primary_technology}} boilerplate generator latest options 2024 -WebSearch: {{primary_technology}} production-ready starter best practices 2024 +Search the web: "{{primary_technology}} starter template CLI create command latest" +Search the web: "{{primary_technology}} boilerplate generator latest options" +Search the web: "{{primary_technology}} production-ready starter best practices" ``` ### 4. Investigate Top Starter Options @@ -131,10 +131,10 @@ WebSearch: {{primary_technology}} production-ready starter best practices 2024 For each promising starter found, investigate details: ``` -WebSearch: {{starter_name}} default setup technologies included latest -WebSearch: {{starter_name}} project structure file organization -WebSearch: {{starter_name}} production deployment capabilities -WebSearch: {{starter_name}} recent updates maintenance status 2024 +Search the web: "{{starter_name}} default setup technologies included latest" +Search the web: "{{starter_name}} project structure file organization" +Search the web: "{{starter_name}} production deployment capabilities" +Search the web: "{{starter_name}} recent updates maintenance status" ``` ### 5. Analyze What Each Starter Provides @@ -200,8 +200,8 @@ This is a great starting point that follows best practices and saves us from mak If user shows interest in a starter, get the exact current commands: ``` -WebSearch: {{starter_name}} CLI command options flags latest 2024 -WebSearch: {{starter_name}} create new project command examples +Search the web: "{{starter_name}} CLI command options flags latest" +Search the web: "{{starter_name}} create new project command examples" ``` ### 8. Generate Starter Template Content @@ -304,7 +304,7 @@ When user selects 'C', append the content directly to the document using the str โœ… Primary technology domain correctly identified from project context โœ… Current, maintained starter templates researched and evaluated -โœ… All versions verified using WebSearch, not hardcoded +โœ… All versions verified using web search, not hardcoded โœ… Architectural implications of starter choice clearly documented โœ… User provided with clear rationale for starter selection โœ… A/P/C menu presented and handled correctly @@ -312,7 +312,7 @@ When user selects 'C', append the content directly to the document using the str ## FAILURE MODES: -โŒ Not verifying current versions with WebSearch +โŒ Not verifying current versions with web search โŒ Ignoring UX requirements when evaluating starters โŒ Not documenting what architectural decisions the starter makes โŒ Failing to consider maintenance status of starter templates diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md b/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md index 81eca7e0..9b445169 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md @@ -9,13 +9,13 @@ - โœ… ALWAYS treat this as collaborative discovery between architectural peers - ๐Ÿ“‹ YOU ARE A FACILITATOR, not a content generator - ๐Ÿ’ฌ FOCUS on making critical architectural decisions collaboratively -- ๐ŸŒ ALWAYS verify current technology versions using WebSearch +- ๐ŸŒ ALWAYS search the web to verify current technology versions - โš ๏ธ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed ## EXECUTION PROTOCOLS: - ๐ŸŽฏ Show your analysis before taking any action -- ๐ŸŒ Use WebSearch to verify technology versions and options +- ๐ŸŒ Search the web to verify technology versions and options - โš ๏ธ Present A/P/C menu after each major decision category - ๐Ÿ’พ ONLY save when user chooses C (Continue) - ๐Ÿ“– Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step @@ -163,9 +163,9 @@ What feels right to you?" If decision involves specific technology: ``` -WebSearch: {{technology}} latest stable version 2024 -WebSearch: {{technology}} current LTS version -WebSearch: {{technology}} production readiness 2024 +Search the web: "{{technology}} latest stable version" +Search the web: "{{technology}} current LTS version" +Search the web: "{{technology}} production readiness" ``` **Get User Input:** @@ -290,7 +290,7 @@ When user selects 'C', append the content directly to the document using the str ## SUCCESS METRICS: โœ… All critical architectural decisions made collaboratively -โœ… Technology versions verified using WebSearch +โœ… Technology versions verified using web search โœ… Decision rationale clearly documented โœ… Cascading implications identified and addressed โœ… User provided appropriate level of explanation for skill level @@ -300,7 +300,7 @@ When user selects 'C', append the content directly to the document using the str ## FAILURE MODES: โŒ Making recommendations instead of facilitating decisions -โŒ Not verifying technology versions with WebSearch +โŒ Not verifying technology versions with web search โŒ Missing cascading implications between decisions โŒ Not adapting explanations to user skill level โŒ Forgetting to document decisions made by starter template diff --git a/src/modules/bmgd/workflows/4-production/code-review/checklist.md b/src/modules/bmm/workflows/4-implementation/code-review/checklist.md similarity index 90% rename from src/modules/bmgd/workflows/4-production/code-review/checklist.md rename to src/modules/bmm/workflows/4-implementation/code-review/checklist.md index ce903701..f213a6b9 100644 --- a/src/modules/bmgd/workflows/4-production/code-review/checklist.md +++ b/src/modules/bmm/workflows/4-implementation/code-review/checklist.md @@ -1,7 +1,7 @@ # Senior Developer Review - Validation Checklist - [ ] Story file loaded from `{{story_path}}` -- [ ] Story Status verified as one of: {{allow_status_values}} +- [ ] Story Status verified as reviewable (review) - [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}}) - [ ] Story Context located or warning recorded - [ ] Epic Tech Spec located or warning recorded @@ -17,6 +17,7 @@ - [ ] Review notes appended under "Senior Developer Review (AI)" - [ ] Change Log updated with review entry - [ ] Status updated according to settings (if enabled) +- [ ] Sprint status synced (if sprint tracking enabled) - [ ] Story saved successfully _Reviewer: {{user_name}} on {{date}}_ diff --git a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml index 6e896a97..bf8b7d69 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml +++ b/src/modules/bmm/workflows/4-implementation/code-review/instructions.xml @@ -16,6 +16,7 @@ Use provided {{story_path}} or ask user which story file to review Read COMPLETE story file + Set {{story_key}} = extracted key from filename (e.g., "1-2-user-authentication.md" โ†’ "1-2-user-authentication") or story metadata Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Agent Record โ†’ File List, Change Log @@ -106,6 +107,8 @@ Categorize findings: HIGH (must fix), MEDIUM (should fix), LOW (nice to fix) + Set {{fixed_count}} = 0 + Set {{action_count}} = 0 **๐Ÿ”ฅ CODE REVIEW FINDINGS, {user_name}!** @@ -145,11 +148,15 @@ Add/update tests as needed Update File List in story if files changed Update story Dev Agent Record with fixes applied + Set {{fixed_count}} = number of HIGH and MEDIUM issues fixed + Set {{action_count}} = 0 Add "Review Follow-ups (AI)" subsection to Tasks/Subtasks For each issue: `- [ ] [AI-Review][Severity] Description [file:line]` + Set {{action_count}} = number of action items created + Set {{fixed_count}} = 0 @@ -158,11 +165,52 @@ - - If all HIGH issues fixed and ACs implemented โ†’ Update story Status to "done" - If issues remain โ†’ Update story Status to "in-progress" + + + + Set {{new_status}} = "done" + Update story Status field to "done" + + + Set {{new_status}} = "in-progress" + Update story Status field to "in-progress" + Save story file + + + Set {{current_sprint_status}} = "enabled" + + + Set {{current_sprint_status}} = "no-sprint-tracking" + + + + + Load the FULL file: {sprint_status} + Find development_status key matching {{story_key}} + + + Update development_status[{{story_key}}] = "done" + Save file, preserving ALL comments and structure + โœ… Sprint status synced: {{story_key}} โ†’ done + + + + Update development_status[{{story_key}}] = "in-progress" + Save file, preserving ALL comments and structure + ๐Ÿ”„ Sprint status synced: {{story_key}} โ†’ in-progress + + + + โš ๏ธ Story file updated, but sprint-status sync failed: {{story_key}} not found in sprint-status.yaml + + + + + โ„น๏ธ Story status updated (no sprint tracking configured) + + **โœ… Review Complete!** **Story Status:** {{new_status}} diff --git a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml index bea3b9dc..c055db20 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml @@ -1,6 +1,6 @@ # Review Story Workflow name: code-review -description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts 'looks good' - must find minimum issues and can auto-fix with user approval." +description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval." author: "BMad" # Critical variables from config diff --git a/src/modules/bmm/workflows/document-project/instructions.md b/src/modules/bmm/workflows/document-project/instructions.md index 5f8b2139..526a462b 100644 --- a/src/modules/bmm/workflows/document-project/instructions.md +++ b/src/modules/bmm/workflows/document-project/instructions.md @@ -196,7 +196,7 @@ Your choice [1/2/3]: - Mode: {{workflow_mode}} - Scan Level: {{scan_level}} -- Output: {output_folder}/bmm-index.md and related files +- Output: {output_folder}/index.md and related files {{#if status_file_found}} **Status Updated:** diff --git a/src/modules/bmm/workflows/document-project/workflows/deep-dive-instructions.md b/src/modules/bmm/workflows/document-project/workflows/deep-dive-instructions.md index 621c843c..c88dfb08 100644 --- a/src/modules/bmm/workflows/document-project/workflows/deep-dive-instructions.md +++ b/src/modules/bmm/workflows/document-project/workflows/deep-dive-instructions.md @@ -20,7 +20,7 @@ {{#if has_api_routes}} -### API Routes ({{api_route_count}} endpoints found) +## API Routes ({{api_route_count}} endpoints found) {{#each api_route_groups}} {{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in `{{path}}` @@ -29,7 +29,7 @@ {{#if has_feature_modules}} -### Feature Modules ({{feature_count}} features) +## Feature Modules ({{feature_count}} features) {{#each feature_modules}} {{module_index}}. {{module_name}} - {{file_count}} files in `{{path}}` diff --git a/src/modules/bmm/workflows/testarch/ci/checklist.md b/src/modules/bmm/workflows/testarch/ci/checklist.md index 330ebe38..6853a24d 100644 --- a/src/modules/bmm/workflows/testarch/ci/checklist.md +++ b/src/modules/bmm/workflows/testarch/ci/checklist.md @@ -4,7 +4,7 @@ - [ ] Git repository initialized (`.git/` exists) - [ ] Git remote configured (`git remote -v` shows origin) -- [ ] Test framework configured (playwright.config._ or cypress.config._) +- [ ] Test framework configured (`playwright.config._` or `cypress.config._`) - [ ] Local tests pass (`npm run test:e2e` succeeds) - [ ] Team agrees on CI platform - [ ] Access to CI platform settings (if updating) diff --git a/src/modules/bmm/workflows/testarch/ci/github-actions-template.yaml b/src/modules/bmm/workflows/testarch/ci/github-actions-template.yaml index 0eefd180..9f09a73f 100644 --- a/src/modules/bmm/workflows/testarch/ci/github-actions-template.yaml +++ b/src/modules/bmm/workflows/testarch/ci/github-actions-template.yaml @@ -27,10 +27,21 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Determine Node version + id: node-version + run: | + if [ -f .nvmrc ]; then + echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT" + echo "Using Node from .nvmrc" + else + echo "value=24" >> "$GITHUB_OUTPUT" + echo "Using default Node 24 (current LTS)" + fi + - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version-file: ".nvmrc" + node-version: ${{ steps.node-version.outputs.value }} cache: "npm" - name: Install dependencies @@ -54,10 +65,21 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Determine Node version + id: node-version + run: | + if [ -f .nvmrc ]; then + echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT" + echo "Using Node from .nvmrc" + else + echo "value=22" >> "$GITHUB_OUTPUT" + echo "Using default Node 22 (current LTS)" + fi + - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version-file: ".nvmrc" + node-version: ${{ steps.node-version.outputs.value }} cache: "npm" - name: Cache Playwright browsers @@ -99,10 +121,21 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Determine Node version + id: node-version + run: | + if [ -f .nvmrc ]; then + echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT" + echo "Using Node from .nvmrc" + else + echo "value=22" >> "$GITHUB_OUTPUT" + echo "Using default Node 22 (current LTS)" + fi + - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version-file: ".nvmrc" + node-version: ${{ steps.node-version.outputs.value }} cache: "npm" - name: Cache Playwright browsers diff --git a/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml b/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml index e3b433da..f5336de4 100644 --- a/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml +++ b/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml @@ -15,6 +15,8 @@ variables: npm_config_cache: "$CI_PROJECT_DIR/.npm" # Playwright browser cache PLAYWRIGHT_BROWSERS_PATH: "$CI_PROJECT_DIR/.cache/ms-playwright" + # Default Node version when .nvmrc is missing + DEFAULT_NODE_VERSION: "24" # Caching configuration cache: @@ -29,19 +31,32 @@ cache: # Lint stage - Code quality checks lint: stage: lint - image: node:20 - script: + image: node:$DEFAULT_NODE_VERSION + before_script: + - | + NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION") + echo "Using Node $NODE_VERSION" + npm install -g n + n "$NODE_VERSION" + node -v - npm ci + script: - npm run lint timeout: 5 minutes # Test stage - Parallel execution with sharding .test-template: &test-template stage: test - image: node:20 + image: node:$DEFAULT_NODE_VERSION needs: - lint before_script: + - | + NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION") + echo "Using Node $NODE_VERSION" + npm install -g n + n "$NODE_VERSION" + node -v - npm ci - npx playwright install --with-deps chromium artifacts: @@ -75,7 +90,7 @@ test:shard-4: # Burn-in stage - Flaky test detection burn-in: stage: burn-in - image: node:20 + image: node:$DEFAULT_NODE_VERSION needs: - test:shard-1 - test:shard-2 @@ -86,6 +101,12 @@ burn-in: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_PIPELINE_SOURCE == "schedule"' before_script: + - | + NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION") + echo "Using Node $NODE_VERSION" + npm install -g n + n "$NODE_VERSION" + node -v - npm ci - npx playwright install --with-deps chromium script: diff --git a/src/modules/bmm/workflows/testarch/ci/instructions.md b/src/modules/bmm/workflows/testarch/ci/instructions.md index 9bd87940..9241e93c 100644 --- a/src/modules/bmm/workflows/testarch/ci/instructions.md +++ b/src/modules/bmm/workflows/testarch/ci/instructions.md @@ -61,8 +61,8 @@ Scaffolds a production-ready CI/CD quality pipeline with test execution, burn-in - Ask user if unable to auto-detect 5. **Read Environment Configuration** - - Check for `.nvmrc` to determine Node version - - Default to Node 20 LTS if not found + - Use `.nvmrc` for Node version if present + - If missing, default to a current LTS (Node 24) or newer instead of a fixed old version - Read `package.json` to identify dependencies (affects caching strategy) **Halt Condition:** If preflight checks fail, stop immediately and report which requirement failed. diff --git a/src/modules/bmm/workflows/testarch/test-review/instructions.md b/src/modules/bmm/workflows/testarch/test-review/instructions.md index 0bf378cc..a0f49b57 100644 --- a/src/modules/bmm/workflows/testarch/test-review/instructions.md +++ b/src/modules/bmm/workflows/testarch/test-review/instructions.md @@ -524,7 +524,7 @@ await expect(page.locator('[data-testid="user-menu"]')).toBeVisible({ timeout: 1 ### 1. Use Data Factory for Test User (Lines 23, 32, 41) **Severity**: P1 (High) -**Issue**: Hardcoded email 'test@example.com' - maintainability risk +**Issue**: Hardcoded email `test@example.com` - maintainability risk **Fix**: Create factory function for test users **Knowledge**: See data-factories.md diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml index 7ac0d490..5064030d 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml @@ -56,11 +56,6 @@ phases: output: "Enterprise PRD with compliance requirements" note: "Must address existing system constraints and migration strategy" - - id: "validate-prd" - recommended: true - agent: "pm" - command: "validate-prd" - - id: "create-ux-design" recommended: true agent: "ux-designer" @@ -114,7 +109,7 @@ phases: required: true agent: "architect" command: "implementation-readiness" - note: "Critical gate - validates all planning + Epics before touching production system" + note: "Validates PRD + Architecture + Epics + UX (optional)" - phase: 3 name: "Implementation" diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml index de15e3c3..94757114 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml @@ -44,11 +44,6 @@ phases: output: "Comprehensive Product Requirements Document" note: "Enterprise-level requirements with compliance considerations" - - id: "validate-prd" - recommended: true - agent: "pm" - command: "validate-prd" - - id: "create-ux-design" recommended: true agent: "ux-designer" @@ -102,7 +97,7 @@ phases: required: true agent: "architect" command: "implementation-readiness" - note: "Validates all planning artifacts + Epics + testability align before implementation" + note: "Validates PRD + Architecture + Epics + UX (optional)" - phase: 3 name: "Implementation" diff --git a/src/modules/bmm/workflows/workflow-status/paths/method-brownfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/method-brownfield.yaml index ed9cbd32..67ee6cd0 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/method-brownfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/method-brownfield.yaml @@ -55,11 +55,6 @@ phases: output: "PRD focused on new features/changes" note: "Must consider existing system constraints" - - id: "validate-prd" - optional: true - agent: "pm" - command: "validate-prd" - - id: "create-ux-design" conditional: "if_has_ui" agent: "ux-designer" @@ -98,7 +93,7 @@ phases: required: true agent: "architect" command: "implementation-readiness" - note: "Validates PRD + UX + Architecture + Epics cohesion before implementation" + note: "Validates PRD + Architecture + Epics + UX (optional)" - phase: 3 name: "Implementation" diff --git a/src/modules/bmm/workflows/workflow-status/paths/method-greenfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/method-greenfield.yaml index bef2a839..aca183e9 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/method-greenfield.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/method-greenfield.yaml @@ -43,12 +43,6 @@ phases: command: "prd" output: "Product Requirements Document with FRs and NFRs" - - id: "validate-prd" - optional: true - agent: "pm" - command: "validate-prd" - note: "Quality check for PRD completeness" - - id: "create-ux-design" conditional: "if_has_ui" agent: "ux-designer" @@ -89,7 +83,7 @@ phases: required: true agent: "architect" command: "implementation-readiness" - note: "Validates PRD + UX + Architecture + Epics + Testability cohesion before implementation" + note: "Validates PRD + Architecture + Epics + UX (optional)" - phase: 3 name: "Implementation" diff --git a/src/modules/cis/_module-installer/installer.js b/src/modules/cis/_module-installer/installer.js index 5178259f..dec5f372 100644 --- a/src/modules/cis/_module-installer/installer.js +++ b/src/modules/cis/_module-installer/installer.js @@ -8,7 +8,7 @@ const chalk = require('chalk'); * * @param {Object} options - Installation options * @param {string} options.projectRoot - The root directory of the target project - * @param {Object} options.config - Module configuration from install-config.yaml + * @param {Object} options.config - Module configuration from module.yaml * @param {Array} options.installedIDEs - Array of IDE codes that were installed * @param {Object} options.logger - Logger instance for output * @returns {Promise} - Success status diff --git a/src/modules/cis/_module-installer/install-config.yaml b/src/modules/cis/module.yaml similarity index 100% rename from src/modules/cis/_module-installer/install-config.yaml rename to src/modules/cis/module.yaml diff --git a/tools/cli/README.md b/tools/cli/README.md index 5c794f16..0c8bf4bd 100644 --- a/tools/cli/README.md +++ b/tools/cli/README.md @@ -98,7 +98,7 @@ The installer is a multi-stage system that handles agent compilation, IDE integr ``` 1. Collect User Input - Target directory, modules, IDEs - - Custom module configuration (via install-config.yaml) + - Custom module configuration (via module.yaml) 2. Pre-Installation - Validate target, check conflicts, backup existing installations @@ -183,12 +183,12 @@ The installer supports **15 IDE environments** through a base-derived architectu ### Custom Module Configuration -Modules define interactive configuration menus via `install-config.yaml` files in their `_module-installer/` directories. +Modules define interactive configuration menus via `module.yaml` files in their `_module-installer/` directories. **Config File Location**: -- Core: `src/core/_module-installer/install-config.yaml` -- Modules: `src/modules/{module}/_module-installer/install-config.yaml` +- Core: `src/core/module.yaml` +- Modules: `src/modules/{module}/module.yaml` **Configuration Types**: @@ -604,6 +604,6 @@ node tools/cli/regenerate-manifests.js ## Support -- **Issues**: https://github.com/bmad-code-org/BMAD-METHOD/issues -- **Discord**: https://discord.gg/gk8jAdXWmj (#general-dev, #bugs-issues) -- **YouTube**: https://www.youtube.com/@BMadCode +- **Issues**: +- **Discord**: (#general-dev, #bugs-issues) +- **YouTube**: diff --git a/tools/cli/commands/agent-install.js b/tools/cli/commands/agent-install.js deleted file mode 100644 index 57b0c8c1..00000000 --- a/tools/cli/commands/agent-install.js +++ /dev/null @@ -1,409 +0,0 @@ -const chalk = require('chalk'); -const path = require('node:path'); -const fs = require('node:fs'); -const readline = require('node:readline'); -const { - findBmadConfig, - resolvePath, - discoverAgents, - loadAgentConfig, - promptInstallQuestions, - detectBmadProject, - addToManifest, - extractManifestData, - checkManifestForPath, - updateManifestEntry, - saveAgentSource, - createIdeSlashCommands, - updateManifestYaml, -} = require('../lib/agent/installer'); - -module.exports = { - command: 'agent-install', - description: 'Install and compile BMAD agents with personalization', - options: [ - ['-s, --source ', 'Path to specific agent YAML file or folder'], - ['-d, --defaults', 'Use default values without prompting'], - ['-t, --destination ', 'Target installation directory (default: current project BMAD installation)'], - ], - action: async (options) => { - try { - console.log(chalk.cyan('\n๐Ÿ”ง BMAD Agent Installer\n')); - - // Find BMAD config - const config = findBmadConfig(); - if (!config) { - console.log(chalk.yellow('No BMAD installation found in current directory.')); - console.log(chalk.dim('Looking for .bmad/bmb/config.yaml...')); - console.log(chalk.red('\nPlease run this command from a project with BMAD installed.')); - process.exit(1); - } - - console.log(chalk.dim(`Found BMAD at: ${config.bmadFolder}`)); - - let selectedAgent = null; - - // If source provided, use it directly - if (options.source) { - const providedPath = path.resolve(options.source); - - if (!fs.existsSync(providedPath)) { - console.log(chalk.red(`Path not found: ${providedPath}`)); - process.exit(1); - } - - const stat = fs.statSync(providedPath); - if (stat.isFile() && providedPath.endsWith('.agent.yaml')) { - selectedAgent = { - type: 'simple', - name: path.basename(providedPath, '.agent.yaml'), - path: providedPath, - yamlFile: providedPath, - }; - } else if (stat.isDirectory()) { - const yamlFiles = fs.readdirSync(providedPath).filter((f) => f.endsWith('.agent.yaml')); - if (yamlFiles.length === 1) { - selectedAgent = { - type: 'expert', - name: path.basename(providedPath), - path: providedPath, - yamlFile: path.join(providedPath, yamlFiles[0]), - hasSidecar: true, - }; - } else { - console.log(chalk.red('Directory must contain exactly one .agent.yaml file')); - process.exit(1); - } - } else { - console.log(chalk.red('Path must be an .agent.yaml file or a folder containing one')); - process.exit(1); - } - } else { - // Discover agents from custom location - const customAgentLocation = config.custom_agent_location - ? resolvePath(config.custom_agent_location, config) - : path.join(config.bmadFolder, 'custom', 'src', 'agents'); - - console.log(chalk.dim(`Searching for agents in: ${customAgentLocation}\n`)); - - const agents = discoverAgents(customAgentLocation); - - if (agents.length === 0) { - console.log(chalk.yellow('No agents found in custom agent location.')); - console.log(chalk.dim(`Expected location: ${customAgentLocation}`)); - console.log(chalk.dim('\nCreate agents using the BMad Builder workflow or place .agent.yaml files there.')); - process.exit(0); - } - - // List available agents - console.log(chalk.cyan('Available Agents:\n')); - for (const [idx, agent] of agents.entries()) { - const typeIcon = agent.type === 'expert' ? '๐Ÿ“š' : '๐Ÿ“„'; - console.log(` ${idx + 1}. ${typeIcon} ${chalk.bold(agent.name)} ${chalk.dim(`(${agent.type})`)}`); - } - - // Prompt for selection - const rl = readline.createInterface({ - input: process.stdin, - output: process.stdout, - }); - - const selection = await new Promise((resolve) => { - rl.question('\nSelect agent to install (number): ', resolve); - }); - rl.close(); - - const selectedIdx = parseInt(selection, 10) - 1; - if (isNaN(selectedIdx) || selectedIdx < 0 || selectedIdx >= agents.length) { - console.log(chalk.red('Invalid selection')); - process.exit(1); - } - - selectedAgent = agents[selectedIdx]; - } - - console.log(chalk.cyan(`\nSelected: ${chalk.bold(selectedAgent.name)}`)); - - // Load agent configuration - const agentConfig = loadAgentConfig(selectedAgent.yamlFile); - - if (agentConfig.metadata.name) { - console.log(chalk.dim(`Agent Name: ${agentConfig.metadata.name}`)); - } - if (agentConfig.metadata.title) { - console.log(chalk.dim(`Title: ${agentConfig.metadata.title}`)); - } - - // Get the agent type (source name) - const agentType = selectedAgent.name; // e.g., "commit-poet" - - // Confirm/customize agent persona name - const rl1 = readline.createInterface({ - input: process.stdin, - output: process.stdout, - }); - - const defaultPersonaName = agentConfig.metadata.name || agentType; - console.log(chalk.cyan('\n๐Ÿ“› Agent Persona Name\n')); - console.log(chalk.dim(` Agent type: ${agentType}`)); - console.log(chalk.dim(` Default persona: ${defaultPersonaName}`)); - console.log(chalk.dim(' Leave blank to use default, or provide a custom name.')); - console.log(chalk.dim(' Examples:')); - console.log(chalk.dim(` - (blank) โ†’ "${defaultPersonaName}" as ${agentType}.md`)); - console.log(chalk.dim(` - "Fred" โ†’ "Fred" as fred-${agentType}.md`)); - console.log(chalk.dim(` - "Captain Code" โ†’ "Captain Code" as captain-code-${agentType}.md`)); - - const customPersonaName = await new Promise((resolve) => { - rl1.question(`\n Custom name (or Enter for default): `, resolve); - }); - rl1.close(); - - // Determine final agent file name based on persona name - let finalAgentName; - let personaName; - if (customPersonaName.trim()) { - personaName = customPersonaName.trim(); - const namePrefix = personaName.toLowerCase().replaceAll(/\s+/g, '-'); - finalAgentName = `${namePrefix}-${agentType}`; - } else { - personaName = defaultPersonaName; - finalAgentName = agentType; - } - - console.log(chalk.dim(` Persona: ${personaName}`)); - console.log(chalk.dim(` File: ${finalAgentName}.md`)); - - // Get answers (prompt or use defaults) - let presetAnswers = {}; - - // If custom persona name provided, inject it as custom_name for template processing - if (customPersonaName.trim()) { - presetAnswers.custom_name = personaName; - } - - let answers; - if (agentConfig.installConfig && !options.defaults) { - answers = await promptInstallQuestions(agentConfig.installConfig, agentConfig.defaults, presetAnswers); - } else if (agentConfig.installConfig && options.defaults) { - console.log(chalk.dim('\nUsing default configuration values.')); - answers = { ...agentConfig.defaults, ...presetAnswers }; - } else { - answers = { ...agentConfig.defaults, ...presetAnswers }; - } - - // Determine target directory - let targetDir = options.destination ? path.resolve(options.destination) : null; - - // If no target specified, prompt for it - if (targetDir) { - // If target provided via --destination, check if it's a project root and adjust - const otherProject = detectBmadProject(targetDir); - if (otherProject && !targetDir.includes('agents')) { - // User specified project root, redirect to custom agents folder - targetDir = path.join(otherProject.bmadFolder, 'custom', 'agents'); - console.log(chalk.dim(` Auto-selecting custom agents folder: ${targetDir}`)); - } - } else { - const rl = readline.createInterface({ - input: process.stdin, - output: process.stdout, - }); - - console.log(chalk.cyan('\n๐Ÿ“‚ Installation Target\n')); - - // Option 1: Current project's custom agents folder - const currentCustom = path.join(config.bmadFolder, 'custom', 'agents'); - console.log(` 1. Current project: ${chalk.dim(currentCustom)}`); - - // Option 2: Specify another project path - console.log(` 2. Another project (enter path)`); - - const choice = await new Promise((resolve) => { - rl.question('\n Select option (1 or path): ', resolve); - }); - - if (choice.trim() === '1' || choice.trim() === '') { - targetDir = currentCustom; - } else if (choice.trim() === '2') { - const projectPath = await new Promise((resolve) => { - rl.question(' Project path: ', resolve); - }); - - // Detect if it's a BMAD project and use its custom folder - const otherProject = detectBmadProject(path.resolve(projectPath)); - if (otherProject) { - targetDir = path.join(otherProject.bmadFolder, 'custom', 'agents'); - console.log(chalk.dim(` Found BMAD project, using: ${targetDir}`)); - } else { - targetDir = path.resolve(projectPath); - } - } else { - // User entered a path directly - const otherProject = detectBmadProject(path.resolve(choice)); - if (otherProject) { - targetDir = path.join(otherProject.bmadFolder, 'custom', 'agents'); - console.log(chalk.dim(` Found BMAD project, using: ${targetDir}`)); - } else { - targetDir = path.resolve(choice); - } - } - - rl.close(); - } - - if (!fs.existsSync(targetDir)) { - fs.mkdirSync(targetDir, { recursive: true }); - } - - console.log(chalk.dim(`\nInstalling to: ${targetDir}`)); - - // Detect if target is within a BMAD project - const targetProject = detectBmadProject(targetDir); - if (targetProject) { - console.log(chalk.cyan(` Detected BMAD project at: ${targetProject.projectRoot}`)); - } - - // Check for duplicate in manifest by path (not by type) - let shouldUpdateExisting = false; - let existingEntry = null; - - if (targetProject) { - // Check if this exact installed name already exists - const expectedPath = `.bmad/custom/agents/${finalAgentName}/${finalAgentName}.md`; - existingEntry = checkManifestForPath(targetProject.manifestFile, expectedPath); - - if (existingEntry) { - const rl2 = readline.createInterface({ - input: process.stdin, - output: process.stdout, - }); - - console.log(chalk.yellow(`\nโš ๏ธ Agent "${finalAgentName}" already installed`)); - console.log(chalk.dim(` Type: ${agentType}`)); - console.log(chalk.dim(` Path: ${existingEntry.path}`)); - - const overwrite = await new Promise((resolve) => { - rl2.question(' Overwrite existing installation? [Y/n]: ', resolve); - }); - rl2.close(); - - if (overwrite.toLowerCase() === 'n') { - console.log(chalk.yellow('Installation cancelled.')); - process.exit(0); - } - - shouldUpdateExisting = true; - } - } - - // Install the agent with custom name - // Override the folder name with finalAgentName - const agentTargetDir = path.join(targetDir, finalAgentName); - - if (!fs.existsSync(agentTargetDir)) { - fs.mkdirSync(agentTargetDir, { recursive: true }); - } - - // Compile and install - const { compileAgent } = require('../lib/agent/compiler'); - - // Calculate target path for agent ID - const projectRoot = targetProject ? targetProject.projectRoot : config.projectRoot; - const compiledFileName = `${finalAgentName}.md`; - const compiledPath = path.join(agentTargetDir, compiledFileName); - const relativePath = path.relative(projectRoot, compiledPath); - - // Compile with proper name and path - const { xml, metadata, processedYaml } = compileAgent( - fs.readFileSync(selectedAgent.yamlFile, 'utf8'), - answers, - finalAgentName, - relativePath, - ); - - // Write compiled XML (.md) with custom name - fs.writeFileSync(compiledPath, xml, 'utf8'); - - const result = { - success: true, - agentName: finalAgentName, - targetDir: agentTargetDir, - compiledFile: compiledPath, - sidecarCopied: false, - }; - - // Copy sidecar files for expert agents - if (selectedAgent.hasSidecar && selectedAgent.type === 'expert') { - const { copySidecarFiles } = require('../lib/agent/installer'); - const sidecarFiles = copySidecarFiles(selectedAgent.path, agentTargetDir, selectedAgent.yamlFile); - result.sidecarCopied = true; - result.sidecarFiles = sidecarFiles; - } - - console.log(chalk.green('\nโœจ Agent installed successfully!')); - console.log(chalk.cyan(` Name: ${result.agentName}`)); - console.log(chalk.cyan(` Location: ${result.targetDir}`)); - console.log(chalk.cyan(` Compiled: ${path.basename(result.compiledFile)}`)); - - if (result.sidecarCopied) { - console.log(chalk.cyan(` Sidecar files: ${result.sidecarFiles.length} files copied`)); - } - - // Save source YAML to _cfg/custom/agents/ and register in manifest - if (targetProject) { - // Save source for reinstallation with embedded answers - console.log(chalk.dim(`\nSaving source to: ${targetProject.cfgFolder}/custom/agents/`)); - saveAgentSource(selectedAgent, targetProject.cfgFolder, finalAgentName, answers); - console.log(chalk.green(` โœ“ Source saved for reinstallation`)); - - // Register/update in manifest - console.log(chalk.dim(`Registering in manifest: ${targetProject.manifestFile}`)); - - const manifestData = extractManifestData(xml, { ...metadata, name: finalAgentName }, relativePath, 'custom'); - // Use finalAgentName as the manifest name field (unique identifier) - manifestData.name = finalAgentName; - // Use compiled metadata.name (persona name after template processing), not source agentConfig - manifestData.displayName = metadata.name || agentType; - // Store the actual installed path/name - manifestData.path = relativePath; - - if (shouldUpdateExisting && existingEntry) { - updateManifestEntry(targetProject.manifestFile, manifestData, existingEntry._lineNumber); - console.log(chalk.green(` โœ“ Updated existing entry in agent-manifest.csv`)); - } else { - addToManifest(targetProject.manifestFile, manifestData); - console.log(chalk.green(` โœ“ Added to agent-manifest.csv`)); - } - - // Create IDE slash commands - const ideResults = await createIdeSlashCommands(targetProject.projectRoot, finalAgentName, relativePath, metadata); - if (Object.keys(ideResults).length > 0) { - console.log(chalk.green(` โœ“ Created IDE commands:`)); - for (const [ideName, result] of Object.entries(ideResults)) { - console.log(chalk.dim(` ${ideName}: ${result.command}`)); - } - } - - // Update manifest.yaml with custom_agents tracking - const manifestYamlPath = path.join(targetProject.cfgFolder, 'manifest.yaml'); - if (updateManifestYaml(manifestYamlPath, finalAgentName, agentType)) { - console.log(chalk.green(` โœ“ Updated manifest.yaml custom_agents`)); - } - } - - console.log(chalk.dim(`\nAgent ID: ${relativePath}`)); - - if (targetProject) { - console.log(chalk.yellow('\nAgent is now registered and available in the target project!')); - } else { - console.log(chalk.yellow('\nTo use this agent, reference it in your manifest or load it directly.')); - } - - process.exit(0); - } catch (error) { - console.error(chalk.red('Agent installation failed:'), error.message); - console.error(chalk.dim(error.stack)); - process.exit(1); - } - }, -}; diff --git a/tools/cli/commands/build.js b/tools/cli/commands/build.js index ec5c6dec..ba84e199 100644 --- a/tools/cli/commands/build.js +++ b/tools/cli/commands/build.js @@ -28,9 +28,8 @@ module.exports = { command: 'build [agent]', description: 'Build agent XML files from YAML sources', options: [ - ['-a, --all', 'Rebuild all agents'], + ['-a, --all', 'Build all agents'], ['-d, --directory ', 'Project directory', '.'], - ['--force', 'Force rebuild even if up to date'], ], action: async (agentName, options) => { try { @@ -54,13 +53,15 @@ module.exports = { if (options.all) { // Build all agents - await buildAllAgents(projectDir, options.force); + await buildAllAgents(projectDir); } else if (agentName) { // Build specific agent - await buildAgent(projectDir, agentName, options.force); + await buildAgent(projectDir, agentName); } else { - // No agent specified, check what needs rebuilding - await checkBuildStatus(projectDir); + // No agent specified, list available agents + console.log(chalk.yellow('No agent specified. Use --all to build all agents or specify an agent name.')); + console.log(chalk.dim('\nAvailable agents:')); + await listAvailableAgents(projectDir); } process.exit(0); @@ -77,7 +78,7 @@ module.exports = { /** * Build a specific agent */ -async function buildAgent(projectDir, agentName, force = false) { +async function buildAgent(projectDir, agentName) { // First check standalone agents in bmad/agents/{agentname}/ const standaloneAgentDir = path.join(projectDir, 'bmad', 'agents', agentName); let standaloneYamlPath = path.join(standaloneAgentDir, `${agentName}.agent.yaml`); @@ -95,15 +96,6 @@ async function buildAgent(projectDir, agentName, force = false) { const yamlFileName = path.basename(standaloneYamlPath, '.agent.yaml'); const outputPath = path.join(standaloneAgentDir, `${yamlFileName}.md`); - // Check if rebuild needed - if (!force && (await fs.pathExists(outputPath))) { - const needsRebuild = await checkIfNeedsRebuild(standaloneYamlPath, outputPath, projectDir, agentName); - if (!needsRebuild) { - console.log(chalk.dim(` ${agentName}: already up to date`)); - return; - } - } - // Build the standalone agent console.log(chalk.cyan(` Building standalone agent ${agentName}...`)); @@ -130,15 +122,6 @@ async function buildAgent(projectDir, agentName, force = false) { if (await fs.pathExists(agentYamlPath)) { found = true; - // Check if rebuild needed - if (!force && (await fs.pathExists(outputPath))) { - const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName); - if (!needsRebuild) { - console.log(chalk.dim(` ${agentName}: already up to date`)); - return; - } - } - // Build the agent console.log(chalk.cyan(` Building ${agentName}...`)); @@ -162,9 +145,8 @@ async function buildAgent(projectDir, agentName, force = false) { /** * Build all agents */ -async function buildAllAgents(projectDir, force = false) { +async function buildAllAgents(projectDir) { let builtCount = 0; - let skippedCount = 0; // First, build standalone agents in bmad/agents/ const standaloneAgentsDir = path.join(projectDir, 'bmad', 'agents'); @@ -193,16 +175,6 @@ async function buildAllAgents(projectDir, force = false) { const agentName = path.basename(agentFile, '.agent.yaml'); const outputPath = path.join(agentDir, `${agentName}.md`); - // Check if rebuild needed - if (!force && (await fs.pathExists(outputPath))) { - const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName); - if (!needsRebuild) { - console.log(chalk.dim(` ${agentName}: up to date`)); - skippedCount++; - continue; - } - } - console.log(chalk.cyan(` Building standalone agent ${agentName}...`)); const customizePath = path.join(projectDir, 'bmad', '_cfg', 'agents', `${agentName}.customize.yaml`); @@ -239,16 +211,6 @@ async function buildAllAgents(projectDir, force = false) { const agentYamlPath = path.join(agentsDir, file); const outputPath = path.join(agentsDir, `${agentName}.md`); - // Check if rebuild needed - if (!force && (await fs.pathExists(outputPath))) { - const needsRebuild = await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName); - if (!needsRebuild) { - console.log(chalk.dim(` ${agentName}: up to date`)); - skippedCount++; - continue; - } - } - console.log(chalk.cyan(` Building ${agentName}...`)); const customizePath = path.join(projectDir, '.claude', '_cfg', 'agents', `${agentName}.customize.yaml`); @@ -263,143 +225,6 @@ async function buildAllAgents(projectDir, force = false) { } console.log(chalk.green(`\nโœ“ Built ${builtCount} agent(s)`)); - if (skippedCount > 0) { - console.log(chalk.dim(` Skipped ${skippedCount} (already up to date)`)); - } -} - -/** - * Check what needs rebuilding - */ -async function checkBuildStatus(projectDir) { - const needsRebuild = []; - const upToDate = []; - - // Check standalone agents in bmad/agents/ - const standaloneAgentsDir = path.join(projectDir, 'bmad', 'agents'); - if (await fs.pathExists(standaloneAgentsDir)) { - const agentDirs = await fs.readdir(standaloneAgentsDir); - - for (const agentDirName of agentDirs) { - const agentDir = path.join(standaloneAgentsDir, agentDirName); - - // Skip if not a directory - const stat = await fs.stat(agentDir); - if (!stat.isDirectory()) { - continue; - } - - // Find any .agent.yaml file in the directory - const files = await fs.readdir(agentDir); - const agentFile = files.find((f) => f.endsWith('.agent.yaml')); - - if (!agentFile) { - continue; - } - - const agentYamlPath = path.join(agentDir, agentFile); - const agentName = path.basename(agentFile, '.agent.yaml'); - const outputPath = path.join(agentDir, `${agentName}.md`); - - if (!(await fs.pathExists(outputPath))) { - needsRebuild.push(`${agentName} (standalone)`); - } else if (await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName)) { - needsRebuild.push(`${agentName} (standalone)`); - } else { - upToDate.push(`${agentName} (standalone)`); - } - } - } - - // Check module agents in .claude/commands/bmad/ - const bmadCommandsDir = path.join(projectDir, '.claude', 'commands', 'bmad'); - if (await fs.pathExists(bmadCommandsDir)) { - const modules = await fs.readdir(bmadCommandsDir); - - for (const module of modules) { - const agentsDir = path.join(bmadCommandsDir, module, 'agents'); - - if (!(await fs.pathExists(agentsDir))) { - continue; - } - - const files = await fs.readdir(agentsDir); - - for (const file of files) { - if (!file.endsWith('.agent.yaml')) { - continue; - } - - const agentName = file.replace('.agent.yaml', ''); - const agentYamlPath = path.join(agentsDir, file); - const outputPath = path.join(agentsDir, `${agentName}.md`); - - if (!(await fs.pathExists(outputPath))) { - needsRebuild.push(`${agentName} (${module})`); - } else if (await checkIfNeedsRebuild(agentYamlPath, outputPath, projectDir, agentName)) { - needsRebuild.push(`${agentName} (${module})`); - } else { - upToDate.push(`${agentName} (${module})`); - } - } - } - } - - if (needsRebuild.length === 0) { - console.log(chalk.green('โœ“ All agents are up to date')); - } else { - console.log(chalk.yellow(`${needsRebuild.length} agent(s) need rebuilding:`)); - for (const agent of needsRebuild) { - console.log(chalk.dim(` - ${agent}`)); - } - console.log(chalk.dim('\nRun "bmad build --all" to rebuild all agents')); - } - - if (upToDate.length > 0) { - console.log(chalk.dim(`\n${upToDate.length} agent(s) up to date`)); - } -} - -/** - * Check if an agent needs rebuilding by comparing hashes - */ -async function checkIfNeedsRebuild(yamlPath, outputPath, projectDir, agentName) { - // Read the output file to check its metadata - const outputContent = await fs.readFile(outputPath, 'utf8'); - - // Extract hash from BUILD-META comment - const metaMatch = outputContent.match(/source:.*\(hash: ([a-f0-9]+)\)/); - if (!metaMatch) { - // No metadata, needs rebuild - return true; - } - - const storedHash = metaMatch[1]; - - // Calculate current hash - const currentHash = await builder.calculateFileHash(yamlPath); - - if (storedHash !== currentHash) { - return true; - } - - // Check customize file if it exists - const customizePath = path.join(projectDir, '.claude', '_cfg', 'agents', `${agentName}.customize.yaml`); - if (await fs.pathExists(customizePath)) { - const customizeMetaMatch = outputContent.match(/customize:.*\(hash: ([a-f0-9]+)\)/); - if (!customizeMetaMatch) { - return true; - } - - const storedCustomizeHash = customizeMetaMatch[1]; - const currentCustomizeHash = await builder.calculateFileHash(customizePath); - - if (storedCustomizeHash !== currentCustomizeHash) { - return true; - } - } - - return false; } /** diff --git a/tools/cli/commands/cleanup.js b/tools/cli/commands/cleanup.js deleted file mode 100644 index 5dae8e5d..00000000 --- a/tools/cli/commands/cleanup.js +++ /dev/null @@ -1,141 +0,0 @@ -const chalk = require('chalk'); -const nodePath = require('node:path'); -const { Installer } = require('../installers/lib/core/installer'); - -module.exports = { - command: 'cleanup', - description: 'Clean up obsolete files from BMAD installation', - options: [ - ['-d, --dry-run', 'Show what would be deleted without actually deleting'], - ['-a, --auto-delete', 'Automatically delete non-retained files without prompts'], - ['-l, --list-retained', 'List currently retained files'], - ['-c, --clear-retained', 'Clear retained files list'], - ], - action: async (options) => { - try { - // Create installer and let it find the BMAD directory - const installer = new Installer(); - const bmadDir = await installer.findBmadDir(process.cwd()); - - if (!bmadDir) { - console.error(chalk.red('โŒ BMAD installation not found')); - process.exit(1); - } - - const retentionPath = nodePath.join(bmadDir, '_cfg', 'user-retained-files.yaml'); - - // Handle list-retained option - if (options.listRetained) { - const fs = require('fs-extra'); - const yaml = require('js-yaml'); - - if (await fs.pathExists(retentionPath)) { - const retentionContent = await fs.readFile(retentionPath, 'utf8'); - const retentionData = yaml.load(retentionContent) || { retainedFiles: [] }; - - if (retentionData.retainedFiles.length > 0) { - console.log(chalk.cyan('\n๐Ÿ“‹ Retained Files:\n')); - for (const file of retentionData.retainedFiles) { - console.log(chalk.dim(` - ${file}`)); - } - console.log(); - } else { - console.log(chalk.yellow('\nโœจ No retained files found\n')); - } - } else { - console.log(chalk.yellow('\nโœจ No retained files found\n')); - } - - return; - } - - // Handle clear-retained option - if (options.clearRetained) { - const fs = require('fs-extra'); - - if (await fs.pathExists(retentionPath)) { - await fs.remove(retentionPath); - console.log(chalk.green('\nโœ… Cleared retained files list\n')); - } else { - console.log(chalk.yellow('\nโœจ No retained files list to clear\n')); - } - - return; - } - - // Handle cleanup operations - if (options.dryRun) { - console.log(chalk.cyan('\n๐Ÿ” Legacy File Scan (Dry Run)\n')); - - const legacyFiles = await installer.scanForLegacyFiles(bmadDir); - const allLegacyFiles = [ - ...legacyFiles.backup, - ...legacyFiles.documentation, - ...legacyFiles.deprecated_task, - ...legacyFiles.unknown, - ]; - - if (allLegacyFiles.length === 0) { - console.log(chalk.green('โœจ No legacy files found\n')); - return; - } - - // Group files by category - const categories = []; - if (legacyFiles.backup.length > 0) { - categories.push({ name: 'Backup Files (.bak)', files: legacyFiles.backup }); - } - if (legacyFiles.documentation.length > 0) { - categories.push({ name: 'Documentation', files: legacyFiles.documentation }); - } - if (legacyFiles.deprecated_task.length > 0) { - categories.push({ name: 'Deprecated Task Files', files: legacyFiles.deprecated_task }); - } - if (legacyFiles.unknown.length > 0) { - categories.push({ name: 'Unknown Files', files: legacyFiles.unknown }); - } - - for (const category of categories) { - console.log(chalk.yellow(`${category.name}:`)); - for (const file of category.files) { - const size = (file.size / 1024).toFixed(1); - const date = file.mtime.toLocaleDateString(); - let line = ` - ${file.relativePath} (${size}KB, ${date})`; - if (file.suggestedAlternative) { - line += chalk.dim(` โ†’ ${file.suggestedAlternative}`); - } - console.log(chalk.dim(line)); - } - console.log(); - } - - console.log(chalk.cyan(`Found ${allLegacyFiles.length} legacy file(s) that could be cleaned up.\n`)); - console.log(chalk.dim('Run "bmad cleanup" to actually delete these files.\n')); - - return; - } - - // Perform actual cleanup - console.log(chalk.cyan('\n๐Ÿงน Cleaning up legacy files...\n')); - - const result = await installer.performCleanup(bmadDir, options.autoDelete); - - if (result.message) { - console.log(chalk.dim(result.message)); - } else { - if (result.deleted > 0) { - console.log(chalk.green(`โœ… Deleted ${result.deleted} legacy file(s)`)); - } - if (result.retained > 0) { - console.log(chalk.yellow(`โญ๏ธ Retained ${result.retained} file(s)`)); - console.log(chalk.dim('Run "bmad cleanup --list-retained" to see retained files\n')); - } - } - - console.log(); - } catch (error) { - console.error(chalk.red(`โŒ Error: ${error.message}`)); - process.exit(1); - } - }, -}; diff --git a/tools/cli/commands/install.js b/tools/cli/commands/install.js index d5742cf7..3e027b2a 100644 --- a/tools/cli/commands/install.js +++ b/tools/cli/commands/install.js @@ -9,7 +9,7 @@ const ui = new UI(); module.exports = { command: 'install', description: 'Install BMAD Core agents and tools', - options: [['--skip-cleanup', 'Skip automatic cleanup of legacy files']], + options: [], action: async (options) => { try { const config = await ui.promptInstall(); @@ -44,11 +44,6 @@ module.exports = { config._requestedReinstall = true; } - // Add skip cleanup flag if option provided - if (options && options.skipCleanup) { - config.skipCleanup = true; - } - // Regular install/update flow const result = await installer.install(config); diff --git a/tools/cli/installers/lib/core/config-collector.js b/tools/cli/installers/lib/core/config-collector.js index 17c233bb..ae9f8074 100644 --- a/tools/cli/installers/lib/core/config-collector.js +++ b/tools/cli/installers/lib/core/config-collector.js @@ -132,8 +132,12 @@ class ConfigCollector { * Collect configuration for all modules * @param {Array} modules - List of modules to configure (including 'core') * @param {string} projectDir - Target project directory + * @param {Object} options - Additional options + * @param {Map} options.customModulePaths - Map of module ID to source path for custom modules */ - async collectAllConfigurations(modules, projectDir) { + async collectAllConfigurations(modules, projectDir, options = {}) { + // Store custom module paths for use in collectModuleConfig + this.customModulePaths = options.customModulePaths || new Map(); await this.loadExistingConfig(projectDir); // Check if core was already collected (e.g., in early collection phase) @@ -182,15 +186,47 @@ class ConfigCollector { } // Load module's install config schema - const installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml'); - const legacyConfigPath = path.join(getModulePath(moduleName), 'config.yaml'); + // First, try the standard src/modules location + let installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml'); + let moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml'); + + // If not found in src/modules, we need to find it by searching the project + if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(moduleConfigPath))) { + // Use the module manager to find the module source + const { ModuleManager } = require('../modules/manager'); + const moduleManager = new ModuleManager(); + const moduleSourcePath = await moduleManager.findModuleSource(moduleName); + + if (moduleSourcePath) { + installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'module.yaml'); + moduleConfigPath = path.join(moduleSourcePath, 'module.yaml'); + } + } let configPath = null; - if (await fs.pathExists(installerConfigPath)) { + let isCustomModule = false; + + if (await fs.pathExists(moduleConfigPath)) { + configPath = moduleConfigPath; + } else if (await fs.pathExists(installerConfigPath)) { configPath = installerConfigPath; - } else if (await fs.pathExists(legacyConfigPath)) { - configPath = legacyConfigPath; } else { + // Check if this is a custom module with custom.yaml + const { ModuleManager } = require('../modules/manager'); + const moduleManager = new ModuleManager(); + const moduleSourcePath = await moduleManager.findModuleSource(moduleName); + + if (moduleSourcePath) { + const rootCustomConfigPath = path.join(moduleSourcePath, 'custom.yaml'); + const moduleInstallerCustomPath = path.join(moduleSourcePath, '_module-installer', 'custom.yaml'); + + if ((await fs.pathExists(rootCustomConfigPath)) || (await fs.pathExists(moduleInstallerCustomPath))) { + isCustomModule = true; + // For custom modules, we don't have an install-config schema, so just use existing values + // The custom.yaml values will be loaded and merged during installation + } + } + // No config schema for this module - use existing values if (this.existingConfig && this.existingConfig[moduleName]) { if (!this.collectedConfig[moduleName]) { @@ -226,9 +262,31 @@ class ConfigCollector { } this.collectedConfig[moduleName] = { ...this.existingConfig[moduleName] }; + // Special handling for user_name: ensure it has a value + if ( + moduleName === 'core' && + (!this.collectedConfig[moduleName].user_name || this.collectedConfig[moduleName].user_name === '[USER_NAME]') + ) { + this.collectedConfig[moduleName].user_name = this.getDefaultUsername(); + } + // Also populate allAnswers for cross-referencing for (const [key, value] of Object.entries(this.existingConfig[moduleName])) { - this.allAnswers[`${moduleName}_${key}`] = value; + // Ensure user_name is properly set in allAnswers too + let finalValue = value; + if (moduleName === 'core' && key === 'user_name' && (!value || value === '[USER_NAME]')) { + finalValue = this.getDefaultUsername(); + } + this.allAnswers[`${moduleName}_${key}`] = finalValue; + } + } else if (moduleName === 'core') { + // No existing core config - ensure we at least have user_name + if (!this.collectedConfig[moduleName]) { + this.collectedConfig[moduleName] = {}; + } + if (!this.collectedConfig[moduleName].user_name) { + this.collectedConfig[moduleName].user_name = this.getDefaultUsername(); + this.allAnswers[`${moduleName}_user_name`] = this.getDefaultUsername(); } } // Show "no config" message for modules with no new questions @@ -396,15 +454,39 @@ class ConfigCollector { if (!this.allAnswers) { this.allAnswers = {}; } - // Load module's config.yaml (check new location first, then fallback) - const installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'install-config.yaml'); - const legacyConfigPath = path.join(getModulePath(moduleName), 'config.yaml'); + // Load module's config + // First, check if we have a custom module path for this module + let installerConfigPath = null; + let moduleConfigPath = null; + + if (this.customModulePaths && this.customModulePaths.has(moduleName)) { + const customPath = this.customModulePaths.get(moduleName); + installerConfigPath = path.join(customPath, '_module-installer', 'module.yaml'); + moduleConfigPath = path.join(customPath, 'module.yaml'); + } else { + // Try the standard src/modules location + installerConfigPath = path.join(getModulePath(moduleName), '_module-installer', 'module.yaml'); + moduleConfigPath = path.join(getModulePath(moduleName), 'module.yaml'); + } + + // If not found in src/modules or custom paths, search the project + if (!(await fs.pathExists(installerConfigPath)) && !(await fs.pathExists(moduleConfigPath))) { + // Use the module manager to find the module source + const { ModuleManager } = require('../modules/manager'); + const moduleManager = new ModuleManager(); + const moduleSourcePath = await moduleManager.findModuleSource(moduleName); + + if (moduleSourcePath) { + installerConfigPath = path.join(moduleSourcePath, '_module-installer', 'module.yaml'); + moduleConfigPath = path.join(moduleSourcePath, 'module.yaml'); + } + } let configPath = null; - if (await fs.pathExists(installerConfigPath)) { + if (await fs.pathExists(moduleConfigPath)) { + configPath = moduleConfigPath; + } else if (await fs.pathExists(installerConfigPath)) { configPath = installerConfigPath; - } else if (await fs.pathExists(legacyConfigPath)) { - configPath = legacyConfigPath; } else { // No config for this module return; diff --git a/tools/cli/installers/lib/core/custom-module-cache.js b/tools/cli/installers/lib/core/custom-module-cache.js new file mode 100644 index 00000000..3ece246d --- /dev/null +++ b/tools/cli/installers/lib/core/custom-module-cache.js @@ -0,0 +1,239 @@ +/** + * Custom Module Source Cache + * Caches custom module sources under _cfg/custom/ to ensure they're never lost + * and can be checked into source control + */ + +const fs = require('fs-extra'); +const path = require('node:path'); +const crypto = require('node:crypto'); + +class CustomModuleCache { + constructor(bmadDir) { + this.bmadDir = bmadDir; + this.customCacheDir = path.join(bmadDir, '_cfg', 'custom'); + this.manifestPath = path.join(this.customCacheDir, 'cache-manifest.yaml'); + } + + /** + * Ensure the custom cache directory exists + */ + async ensureCacheDir() { + await fs.ensureDir(this.customCacheDir); + } + + /** + * Get cache manifest + */ + async getCacheManifest() { + if (!(await fs.pathExists(this.manifestPath))) { + return {}; + } + + const content = await fs.readFile(this.manifestPath, 'utf8'); + const yaml = require('js-yaml'); + return yaml.load(content) || {}; + } + + /** + * Update cache manifest + */ + async updateCacheManifest(manifest) { + const yaml = require('js-yaml'); + const content = yaml.dump(manifest, { + indent: 2, + lineWidth: -1, + noRefs: true, + sortKeys: false, + }); + + await fs.writeFile(this.manifestPath, content); + } + + /** + * Calculate hash of a file or directory + */ + async calculateHash(sourcePath) { + const hash = crypto.createHash('sha256'); + + const isDir = (await fs.stat(sourcePath)).isDirectory(); + + if (isDir) { + // For directories, hash all files + const files = []; + async function collectFiles(dir) { + const entries = await fs.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isFile()) { + files.push(path.join(dir, entry.name)); + } else if (entry.isDirectory() && !entry.name.startsWith('.')) { + await collectFiles(path.join(dir, entry.name)); + } + } + } + + await collectFiles(sourcePath); + files.sort(); // Ensure consistent order + + for (const file of files) { + const content = await fs.readFile(file); + const relativePath = path.relative(sourcePath, file); + hash.update(relativePath + '|' + content.toString('base64')); + } + } else { + // For single files + const content = await fs.readFile(sourcePath); + hash.update(content); + } + + return hash.digest('hex'); + } + + /** + * Cache a custom module source + * @param {string} moduleId - Module ID + * @param {string} sourcePath - Original source path + * @param {Object} metadata - Additional metadata to store + * @returns {Object} Cached module info + */ + async cacheModule(moduleId, sourcePath, metadata = {}) { + await this.ensureCacheDir(); + + const cacheDir = path.join(this.customCacheDir, moduleId); + const cacheManifest = await this.getCacheManifest(); + + // Check if already cached and unchanged + if (cacheManifest[moduleId]) { + const cached = cacheManifest[moduleId]; + if (cached.originalHash && cached.originalHash === (await this.calculateHash(sourcePath))) { + // Source unchanged, return existing cache info + return { + moduleId, + cachePath: cacheDir, + ...cached, + }; + } + } + + // Remove existing cache if it exists + if (await fs.pathExists(cacheDir)) { + await fs.remove(cacheDir); + } + + // Copy module to cache + await fs.copy(sourcePath, cacheDir, { + filter: (src) => { + const relative = path.relative(sourcePath, src); + // Skip node_modules, .git, and other common ignore patterns + return !relative.includes('node_modules') && !relative.startsWith('.git') && !relative.startsWith('.DS_Store'); + }, + }); + + // Calculate hash of the source + const sourceHash = await this.calculateHash(sourcePath); + const cacheHash = await this.calculateHash(cacheDir); + + // Update manifest - don't store originalPath for source control friendliness + cacheManifest[moduleId] = { + originalHash: sourceHash, + cacheHash: cacheHash, + cachedAt: new Date().toISOString(), + ...metadata, + }; + + await this.updateCacheManifest(cacheManifest); + + return { + moduleId, + cachePath: cacheDir, + ...cacheManifest[moduleId], + }; + } + + /** + * Get cached module info + * @param {string} moduleId - Module ID + * @returns {Object|null} Cached module info or null + */ + async getCachedModule(moduleId) { + const cacheManifest = await this.getCacheManifest(); + const cached = cacheManifest[moduleId]; + + if (!cached) { + return null; + } + + const cacheDir = path.join(this.customCacheDir, moduleId); + + if (!(await fs.pathExists(cacheDir))) { + // Cache dir missing, remove from manifest + delete cacheManifest[moduleId]; + await this.updateCacheManifest(cacheManifest); + return null; + } + + // Verify cache integrity + const currentCacheHash = await this.calculateHash(cacheDir); + if (currentCacheHash !== cached.cacheHash) { + console.warn(`Warning: Cache integrity check failed for ${moduleId}`); + } + + return { + moduleId, + cachePath: cacheDir, + ...cached, + }; + } + + /** + * Get all cached modules + * @returns {Array} Array of cached module info + */ + async getAllCachedModules() { + const cacheManifest = await this.getCacheManifest(); + const cached = []; + + for (const [moduleId, info] of Object.entries(cacheManifest)) { + const cachedModule = await this.getCachedModule(moduleId); + if (cachedModule) { + cached.push(cachedModule); + } + } + + return cached; + } + + /** + * Remove a cached module + * @param {string} moduleId - Module ID to remove + */ + async removeCachedModule(moduleId) { + const cacheManifest = await this.getCacheManifest(); + const cacheDir = path.join(this.customCacheDir, moduleId); + + // Remove cache directory + if (await fs.pathExists(cacheDir)) { + await fs.remove(cacheDir); + } + + // Remove from manifest + delete cacheManifest[moduleId]; + await this.updateCacheManifest(cacheManifest); + } + + /** + * Sync cached modules with a list of module IDs + * @param {Array} moduleIds - Module IDs to keep + */ + async syncCache(moduleIds) { + const cached = await this.getAllCachedModules(); + + for (const cachedModule of cached) { + if (!moduleIds.includes(cachedModule.moduleId)) { + await this.removeCachedModule(cachedModule.moduleId); + } + } + } +} + +module.exports = { CustomModuleCache }; diff --git a/tools/cli/installers/lib/core/detector.js b/tools/cli/installers/lib/core/detector.js index 5f6edd81..28a91de7 100644 --- a/tools/cli/installers/lib/core/detector.js +++ b/tools/cli/installers/lib/core/detector.js @@ -17,6 +17,7 @@ class Detector { hasCore: false, modules: [], ides: [], + customModules: [], manifest: null, }; @@ -32,6 +33,10 @@ class Detector { result.manifest = manifestData; result.version = manifestData.version; result.installed = true; + // Copy custom modules if they exist + if (manifestData.customModules) { + result.customModules = manifestData.customModules; + } } // Check for core @@ -275,10 +280,9 @@ class Detector { hasV6Installation = true; // Don't break - continue scanning to be thorough } else { - // Not V6+, check if folder name contains "bmad" (case insensitive) - const nameLower = name.toLowerCase(); - if (nameLower.includes('bmad')) { - // Potential V4 legacy folder + // Not V6+, check if this is the exact V4 folder name "bmad-method" + if (name === 'bmad-method') { + // This is the V4 default folder - flag it as legacy potentialV4Folders.push(fullPath); } } diff --git a/tools/cli/installers/lib/core/installer.js b/tools/cli/installers/lib/core/installer.js index c43a197b..fb670d43 100644 --- a/tools/cli/installers/lib/core/installer.js +++ b/tools/cli/installers/lib/core/installer.js @@ -22,6 +22,7 @@ const path = require('node:path'); const fs = require('fs-extra'); const chalk = require('chalk'); const ora = require('ora'); +const inquirer = require('inquirer'); const { Detector } = require('./detector'); const { Manifest } = require('./manifest'); const { ModuleManager } = require('../modules/manager'); @@ -37,6 +38,7 @@ const { AgentPartyGenerator } = require('../../../lib/agent-party-generator'); const { CLIUtils } = require('../../../lib/cli-utils'); const { ManifestGenerator } = require('./manifest-generator'); const { IdeConfigManager } = require('./ide-config-manager'); +const { replaceAgentSidecarFolders } = require('./post-install-sidecar-replacement'); class Installer { constructor() { @@ -51,6 +53,7 @@ class Installer { this.configCollector = new ConfigCollector(); this.ideConfigManager = new IdeConfigManager(); this.installedFiles = []; // Track all installed files + this.ttsInjectedFiles = []; // Track files with TTS injection applied } /** @@ -127,7 +130,7 @@ class Installer { */ async copyFileWithPlaceholderReplacement(sourcePath, targetPath, bmadFolderName) { // List of text file extensions that should have placeholder replacement - const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv']; + const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv', '.xml']; const ext = path.extname(sourcePath).toLowerCase(); // Check if this is a text file that might contain placeholders @@ -146,8 +149,8 @@ class Installer { content = content.replaceAll('{*bmad_folder*}', '{bmad_folder}'); } - // Process AgentVibes injection points - content = this.processTTSInjectionPoints(content); + // Process AgentVibes injection points (pass targetPath for tracking) + content = this.processTTSInjectionPoints(content, targetPath); // Write to target with replaced content await fs.ensureDir(path.dirname(targetPath)); @@ -226,10 +229,14 @@ class Installer { * - src/modules/bmm/agents/*.md (rules sections) * - TTS Hook: .claude/hooks/bmad-speak.sh (in AgentVibes repo) */ - processTTSInjectionPoints(content) { + processTTSInjectionPoints(content, targetPath = null) { // Check if AgentVibes is enabled (set during installation configuration) const enableAgentVibes = this.enableAgentVibes || false; + // Check if content contains any TTS injection markers + const hasPartyMode = content.includes(''); + const hasAgentTTS = content.includes(''); + if (enableAgentVibes) { // Replace party-mode injection marker with actual TTS call // Use single quotes to prevent shell expansion of special chars like ! @@ -253,6 +260,12 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: IMPORTANT: Use single quotes as shown - do NOT escape special characters like ! or $ inside single quotes Run in background (&) to avoid blocking`, ); + + // Track files that had TTS injection applied + if (targetPath && (hasPartyMode || hasAgentTTS)) { + const injectionType = hasPartyMode ? 'party-mode' : 'agent-tts'; + this.ttsInjectedFiles.push({ path: targetPath, type: injectionType }); + } } else { // Strip injection markers cleanly when AgentVibes is disabled content = content.replaceAll(/\n?/g, ''); @@ -422,8 +435,53 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: // Quick update already collected all configs, use them directly moduleConfigs = this.configCollector.collectedConfig; } else { + // Build custom module paths map from customContent + const customModulePaths = new Map(); + + // Handle selectedFiles (from existing install path or manual directory input) + if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) { + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + for (const customFile of config.customContent.selectedFiles) { + const customInfo = await customHandler.getCustomInfo(customFile, path.resolve(config.directory)); + if (customInfo && customInfo.id) { + customModulePaths.set(customInfo.id, customInfo.path); + } + } + } + + // Handle cachedModules (from new install path where modules are cached) + // Only include modules that were actually selected for installation + if (config.customContent && config.customContent.cachedModules) { + // Get selected cached module IDs (if available) + const selectedCachedIds = config.customContent.selectedCachedModules || []; + // If no selection info, include all cached modules (for backward compatibility) + const shouldIncludeAll = selectedCachedIds.length === 0 && config.customContent.selected; + + for (const cachedModule of config.customContent.cachedModules) { + // For cached modules, the path is the cachePath which contains the module.yaml + if ( + cachedModule.id && + cachedModule.cachePath && // Include if selected or if we should include all + (shouldIncludeAll || selectedCachedIds.includes(cachedModule.id)) + ) { + customModulePaths.set(cachedModule.id, cachedModule.cachePath); + } + } + } + + // Get list of all modules including custom modules + const allModulesForConfig = [...(config.modules || [])]; + for (const [moduleId] of customModulePaths) { + if (!allModulesForConfig.includes(moduleId)) { + allModulesForConfig.push(moduleId); + } + } + // Regular install - collect configurations (core was already collected in UI.promptInstall if interactive) - moduleConfigs = await this.configCollector.collectAllConfigurations(config.modules || [], path.resolve(config.directory)); + moduleConfigs = await this.configCollector.collectAllConfigurations(allModulesForConfig, path.resolve(config.directory), { + customModulePaths, + }); } // Get bmad_folder from config (default to 'bmad' for backwards compatibility) @@ -435,6 +493,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: // Set bmad folder name on module manager and IDE manager for placeholder replacement this.moduleManager.setBmadFolderName(bmadFolderName); + this.moduleManager.setCoreConfig(moduleConfigs.core || {}); this.ideManager.setBmadFolderName(bmadFolderName); // Tool selection will be collected after we determine if it's a reinstall/update/new install @@ -737,13 +796,81 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: spinner.text = 'Creating directory structure...'; await this.createDirectoryStructure(bmadDir); - // Resolve dependencies for selected modules - spinner.text = 'Resolving dependencies...'; + // Get project root const projectRoot = getProjectRoot(); - const modulesToInstall = config.installCore ? ['core', ...config.modules] : config.modules; + + // Step 1: Install core module first (if requested) + if (config.installCore) { + spinner.start('Installing BMAD core...'); + await this.installCoreWithDependencies(bmadDir, { core: {} }); + spinner.succeed('Core installed'); + + // Generate core config file + await this.generateModuleConfigs(bmadDir, { core: config.coreConfig || {} }); + } + + // Custom content is already handled in UI before module selection + let finalCustomContent = config.customContent; + + // Step 3: Prepare modules list including cached custom modules + let allModules = [...(config.modules || [])]; + + // During quick update, we might have custom module sources from the manifest + if (config._customModuleSources) { + // Add custom modules from stored sources + for (const [moduleId, customInfo] of config._customModuleSources) { + if (!allModules.includes(moduleId) && (await fs.pathExists(customInfo.sourcePath))) { + allModules.push(moduleId); + } + } + } + + // Add cached custom modules + if (finalCustomContent && finalCustomContent.cachedModules) { + for (const cachedModule of finalCustomContent.cachedModules) { + if (!allModules.includes(cachedModule.id)) { + allModules.push(cachedModule.id); + } + } + } + + // Regular custom content from user input (non-cached) + if (finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) { + // Add custom modules to the installation list + for (const customFile of finalCustomContent.selectedFiles) { + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + const customInfo = await customHandler.getCustomInfo(customFile, projectDir); + if (customInfo && customInfo.id) { + allModules.push(customInfo.id); + } + } + } + + // Don't include core again if already installed + if (config.installCore) { + allModules = allModules.filter((m) => m !== 'core'); + } + + const modulesToInstall = allModules; // For dependency resolution, we need to pass the project root - const resolution = await this.dependencyResolver.resolve(projectRoot, config.modules || [], { verbose: config.verbose }); + // Create a temporary module manager that knows about custom content locations + const tempModuleManager = new ModuleManager({ + scanProjectForModules: true, + bmadDir: bmadDir, // Pass bmadDir so we can check cache + }); + + // Make sure custom modules are discoverable + if (config.customContent && config.customContent.selected && config.customContent.selectedFiles) { + // The dependency resolver needs to know about these modules + // We'll handle custom modules separately in the installation loop + } + + const resolution = await this.dependencyResolver.resolve(projectRoot, allModules, { + verbose: config.verbose, + moduleManager: tempModuleManager, + }); if (config.verbose) { spinner.succeed('Dependencies resolved'); @@ -751,24 +878,164 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: spinner.succeed('Dependencies resolved'); } - // Install core if requested or if dependencies require it - if (config.installCore || resolution.byModule.core) { - spinner.start('Installing BMAD core...'); - await this.installCoreWithDependencies(bmadDir, resolution.byModule.core); - spinner.succeed('Core installed'); - } + // Core is already installed above, skip if included in resolution // Install modules with their dependencies - if (config.modules && config.modules.length > 0) { - for (const moduleName of config.modules) { + if (allModules && allModules.length > 0) { + const installedModuleNames = new Set(); + + for (const moduleName of allModules) { + // Skip if already installed + if (installedModuleNames.has(moduleName)) { + continue; + } + installedModuleNames.add(moduleName); + spinner.start(`Installing module: ${moduleName}...`); - await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]); + + // Check if this is a custom module + let isCustomModule = false; + let customInfo = null; + let useCache = false; + + // First check if we have a cached version + if (finalCustomContent && finalCustomContent.cachedModules) { + const cachedModule = finalCustomContent.cachedModules.find((m) => m.id === moduleName); + if (cachedModule) { + isCustomModule = true; + customInfo = { + id: moduleName, + path: cachedModule.cachePath, + config: {}, + }; + useCache = true; + } + } + + // Then check if we have custom module sources from the manifest (for quick update) + if (!isCustomModule && config._customModuleSources && config._customModuleSources.has(moduleName)) { + customInfo = config._customModuleSources.get(moduleName); + isCustomModule = true; + + // Check if this is a cached module (source path starts with _cfg) + if (customInfo.sourcePath && (customInfo.sourcePath.startsWith('_cfg') || customInfo.sourcePath.includes('_cfg/custom'))) { + useCache = true; + // Make sure we have the right path structure + if (!customInfo.path) { + customInfo.path = customInfo.sourcePath; + } + } + } + + // Finally check regular custom content + if (!isCustomModule && finalCustomContent && finalCustomContent.selected && finalCustomContent.selectedFiles) { + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + for (const customFile of finalCustomContent.selectedFiles) { + const info = await customHandler.getCustomInfo(customFile, projectDir); + if (info && info.id === moduleName) { + isCustomModule = true; + customInfo = info; + break; + } + } + } + + if (isCustomModule && customInfo) { + // Install custom module using CustomHandler but as a proper module + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + + // Install to module directory instead of custom directory + const moduleTargetPath = path.join(bmadDir, moduleName); + await fs.ensureDir(moduleTargetPath); + + // Get collected config for this custom module (from module.yaml prompts) + const collectedModuleConfig = moduleConfigs[moduleName] || {}; + + const result = await customHandler.install( + customInfo.path, + path.join(bmadDir, 'temp-custom'), + { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig, _bmadDir: bmadDir }, + (filePath) => { + // Track installed files with correct path + const relativePath = path.relative(path.join(bmadDir, 'temp-custom'), filePath); + const finalPath = path.join(moduleTargetPath, relativePath); + this.installedFiles.push(finalPath); + }, + ); + + // Move from temp-custom to actual module directory + const tempCustomPath = path.join(bmadDir, 'temp-custom'); + if (await fs.pathExists(tempCustomPath)) { + const customDir = path.join(tempCustomPath, 'custom'); + if (await fs.pathExists(customDir)) { + // Move contents to module directory + const items = await fs.readdir(customDir); + for (const item of items) { + const srcPath = path.join(customDir, item); + const destPath = path.join(moduleTargetPath, item); + + // If destination exists, remove it first (or we could merge) + if (await fs.pathExists(destPath)) { + await fs.remove(destPath); + } + + await fs.move(srcPath, destPath); + } + } + await fs.remove(tempCustomPath); + } + + // Create module config (include collected config from module.yaml prompts) + await this.generateModuleConfigs(bmadDir, { + [moduleName]: { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig }, + }); + + // Store custom module info for later manifest update + if (!config._customModulesToTrack) { + config._customModulesToTrack = []; + } + + // For cached modules, use appropriate path handling + let sourcePath; + if (useCache) { + // Check if we have cached modules info (from initial install) + if (finalCustomContent && finalCustomContent.cachedModules) { + sourcePath = finalCustomContent.cachedModules.find((m) => m.id === moduleName)?.relativePath; + } else { + // During update, the sourcePath is already cache-relative if it starts with _cfg + sourcePath = + customInfo.sourcePath && customInfo.sourcePath.startsWith('_cfg') + ? customInfo.sourcePath + : path.relative(bmadDir, customInfo.path || customInfo.sourcePath); + } + } else { + sourcePath = path.resolve(customInfo.path || customInfo.sourcePath); + } + + config._customModulesToTrack.push({ + id: customInfo.id, + name: customInfo.name, + sourcePath: sourcePath, + installDate: new Date().toISOString(), + }); + } else { + // Regular module installation + // Special case for core module + if (moduleName === 'core') { + await this.installCoreWithDependencies(bmadDir, resolution.byModule[moduleName]); + } else { + await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]); + } + } + spinner.succeed(`Module installed: ${moduleName}`); } // Install partial modules (only dependencies) for (const [module, files] of Object.entries(resolution.byModule)) { - if (!config.modules.includes(module) && module !== 'core') { + if (!allModules.includes(module) && module !== 'core') { const totalFiles = files.agents.length + files.tasks.length + @@ -785,6 +1052,72 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: } } + // Install custom content if provided AND selected + // Process custom content that wasn't installed as modules + // This is now handled in the module installation loop above + // This section is kept for backward compatibility with any custom content + // that doesn't have a module structure + const remainingCustomContent = []; + if ( + config.customContent && + config.customContent.hasCustomContent && + config.customContent.customPath && + config.customContent.selected && + config.customContent.selectedFiles + ) { + // Filter out custom modules that were already installed + for (const customFile of config.customContent.selectedFiles) { + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + const customInfo = await customHandler.getCustomInfo(customFile, projectDir); + + // Skip if this was installed as a module + if (!customInfo || !customInfo.id || !allModules.includes(customInfo.id)) { + remainingCustomContent.push(customFile); + } + } + } + + if (remainingCustomContent.length > 0) { + spinner.start('Installing remaining custom content...'); + const { CustomHandler } = require('../custom/handler'); + const customHandler = new CustomHandler(); + + // Use the remaining files + const customFiles = remainingCustomContent; + + if (customFiles.length > 0) { + console.log(chalk.cyan(`\n Found ${customFiles.length} custom content file(s):`)); + for (const customFile of customFiles) { + const customInfo = await customHandler.getCustomInfo(customFile, projectDir); + if (customInfo) { + console.log(chalk.dim(` โ€ข ${customInfo.name} (${customInfo.relativePath})`)); + + // Install the custom content + const result = await customHandler.install( + customInfo.path, + bmadDir, + { ...config.coreConfig, ...customInfo.config }, + (filePath) => { + // Track installed files + this.installedFiles.push(filePath); + }, + ); + + if (result.errors.length > 0) { + console.log(chalk.yellow(` โš ๏ธ ${result.errors.length} error(s) occurred`)); + for (const error of result.errors) { + console.log(chalk.dim(` - ${error}`)); + } + } else { + console.log(chalk.green(` โœ“ Installed ${result.agentsInstalled} agents, ${result.workflowsInstalled} workflows`)); + } + } + } + } + spinner.succeed('Custom content installed'); + } + // Generate clean config.yaml files for each installed module spinner.start('Generating module configurations...'); await this.generateModuleConfigs(bmadDir, moduleConfigs); @@ -807,14 +1140,37 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: spinner.start('Generating workflow and agent manifests...'); const manifestGen = new ManifestGenerator(); - // Include preserved modules (from quick update) in the manifest - const allModulesToList = config._preserveModules ? [...(config.modules || []), ...config._preserveModules] : config.modules || []; + // For quick update, we need ALL installed modules in the manifest + // Not just the ones being updated + const allModulesForManifest = config._quickUpdate + ? config._existingModules || allModules || [] + : config._preserveModules + ? [...allModules, ...config._preserveModules] + : allModules || []; - const manifestStats = await manifestGen.generateManifests(bmadDir, config.modules || [], this.installedFiles, { + // For regular installs (including when called from quick update), use what we have + let modulesForCsvPreserve; + if (config._quickUpdate) { + // Quick update - use existing modules or fall back to modules being updated + modulesForCsvPreserve = config._existingModules || allModules || []; + } else { + // Regular install - use the modules we're installing plus any preserved ones + modulesForCsvPreserve = config._preserveModules ? [...allModules, ...config._preserveModules] : allModules; + } + + const manifestStats = await manifestGen.generateManifests(bmadDir, allModulesForManifest, this.installedFiles, { ides: config.ides || [], - preservedModules: config._preserveModules || [], // Scan these from installed bmad/ dir + preservedModules: modulesForCsvPreserve, // Scan these from installed bmad/ dir }); + // Add custom modules to manifest (now that it exists) + if (config._customModulesToTrack && config._customModulesToTrack.length > 0) { + spinner.text = 'Storing custom module sources...'; + for (const customModule of config._customModulesToTrack) { + await this.manifest.addCustomModule(bmadDir, customModule); + } + } + spinner.succeed( `Manifests generated: ${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools, ${manifestStats.files} files`, ); @@ -899,6 +1255,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: await this.moduleManager.runModuleInstaller('core', bmadDir, { installedIDEs: config.ides || [], moduleConfig: moduleConfigs.core || {}, + coreConfig: moduleConfigs.core || {}, logger: { log: (msg) => console.log(msg), error: (msg) => console.error(msg), @@ -916,6 +1273,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: await this.moduleManager.runModuleInstaller(moduleName, bmadDir, { installedIDEs: config.ides || [], moduleConfig: moduleConfigs[moduleName] || {}, + coreConfig: moduleConfigs.core || {}, logger: { log: (msg) => console.log(msg), error: (msg) => console.error(msg), @@ -1013,6 +1371,20 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: } } + // Replace {agent_sidecar_folder} placeholders in all agent files + console.log(chalk.dim('\n Configuring agent sidecar folders...')); + const sidecarResults = await replaceAgentSidecarFolders(bmadDir); + + if (sidecarResults.filesReplaced > 0) { + console.log( + chalk.green( + ` โœ“ Updated ${sidecarResults.filesReplaced} agent file(s) with ${sidecarResults.totalReplacements} sidecar reference(s)`, + ), + ); + } else { + console.log(chalk.dim(' No agent sidecar references found')); + } + // Display completion message const { UI } = require('../../../lib/ui'); const ui = new UI(); @@ -1021,25 +1393,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: modules: config.modules, ides: config.ides, customFiles: customFiles.length > 0 ? customFiles : undefined, + ttsInjectedFiles: this.enableAgentVibes && this.ttsInjectedFiles.length > 0 ? this.ttsInjectedFiles : undefined, + agentVibesEnabled: this.enableAgentVibes || false, }); - // Offer cleanup for legacy files (only for updates, not fresh installs, and only if not skipped) - if (!config.skipCleanup && config._isUpdate) { - try { - const cleanupResult = await this.performCleanup(bmadDir, false); - if (cleanupResult.deleted > 0) { - console.log(chalk.green(`\nโœ“ Cleaned up ${cleanupResult.deleted} legacy file${cleanupResult.deleted > 1 ? 's' : ''}`)); - } - if (cleanupResult.retained > 0) { - console.log(chalk.dim(`Run 'bmad cleanup' anytime to manage retained files`)); - } - } catch (cleanupError) { - // Don't fail the installation for cleanup errors - console.log(chalk.yellow(`\nโš ๏ธ Cleanup warning: ${cleanupError.message}`)); - console.log(chalk.dim('Run "bmad cleanup" to manually clean up legacy files')); - } - } - return { success: true, path: bmadDir, @@ -1076,6 +1433,30 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: const currentVersion = existingInstall.version; const newVersion = require(path.join(getProjectRoot(), 'package.json')).version; + // Check for custom modules with missing sources before update + const customModuleSources = new Map(); + if (existingInstall.customModules) { + for (const customModule of existingInstall.customModules) { + customModuleSources.set(customModule.id, customModule); + } + } + + if (customModuleSources.size > 0) { + spinner.stop(); + console.log(chalk.yellow('\nChecking custom module sources before update...')); + + const projectRoot = getProjectRoot(); + await this.handleMissingCustomSources( + customModuleSources, + bmadDir, + projectRoot, + 'update', + existingInstall.modules.map((m) => m.id), + ); + + spinner.start('Preparing update...'); + } + if (config.dryRun) { spinner.stop(); console.log(chalk.cyan('\n๐Ÿ” Update Preview (Dry Run)\n')); @@ -1526,22 +1907,86 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: // Build YAML + customize to .md const customizeExists = await fs.pathExists(customizePath); - const xmlContent = await this.xmlHandler.buildFromYaml(yamlPath, customizeExists ? customizePath : null, { + let xmlContent = await this.xmlHandler.buildFromYaml(yamlPath, customizeExists ? customizePath : null, { includeMetadata: true, }); // DO NOT replace {project-root} - LLMs understand this placeholder at runtime // const processedContent = xmlContent.replaceAll('{project-root}', projectDir); + // Replace {bmad_folder} with actual folder name + xmlContent = xmlContent.replaceAll('{bmad_folder}', this.bmadFolderName || 'bmad'); + + // Replace {agent_sidecar_folder} if configured + const coreConfig = this.configCollector.collectedConfig.core || {}; + if (coreConfig.agent_sidecar_folder && xmlContent.includes('{agent_sidecar_folder}')) { + xmlContent = xmlContent.replaceAll('{agent_sidecar_folder}', coreConfig.agent_sidecar_folder); + } + + // Process TTS injection points (pass targetPath for tracking) + xmlContent = this.processTTSInjectionPoints(xmlContent, mdPath); + + // Check if agent has sidecar and copy it + let agentYamlContent = null; + let hasSidecar = false; + + try { + agentYamlContent = await fs.readFile(yamlPath, 'utf8'); + const yamlLib = require('yaml'); + const agentYaml = yamlLib.parse(agentYamlContent); + hasSidecar = agentYaml?.agent?.metadata?.hasSidecar === true; + } catch { + // Continue without sidecar processing + } + // Write the built .md file to bmad/{module}/agents/ with POSIX-compliant final newline const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n'; await fs.writeFile(mdPath, content, 'utf8'); this.installedFiles.push(mdPath); + // Copy sidecar files if agent has hasSidecar flag + if (hasSidecar) { + const { copyAgentSidecarFiles } = require('../../../lib/agent/installer'); + + // Get agent sidecar folder from core config + const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml'); + let agentSidecarFolder; + + if (await fs.pathExists(coreConfigPath)) { + const yamlLib = require('yaml'); + const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8'); + const coreConfig = yamlLib.parse(coreConfigContent); + agentSidecarFolder = coreConfig.agent_sidecar_folder || agentSidecarFolder; + } + + // Resolve path variables + const resolvedSidecarFolder = agentSidecarFolder + .replaceAll('{project-root}', projectDir) + .replaceAll('{bmad_folder}', this.bmadFolderName || 'bmad'); + + // Create sidecar directory for this agent + const agentSidecarDir = path.join(resolvedSidecarFolder, agentName); + await fs.ensureDir(agentSidecarDir); + + // Find and copy sidecar folder from source module + const sourceModulePath = getSourcePath(`modules/${moduleName}`); + const sourceAgentPath = path.join(sourceModulePath, 'agents'); + + // Copy sidecar files (preserve existing, add new) + const sidecarResult = copyAgentSidecarFiles(sourceAgentPath, agentSidecarDir, yamlPath); + + if (sidecarResult.copied.length > 0) { + console.log(chalk.dim(` Copied ${sidecarResult.copied.length} new sidecar file(s) to: ${agentSidecarDir}`)); + } + if (sidecarResult.preserved.length > 0) { + console.log(chalk.dim(` Preserved ${sidecarResult.preserved.length} existing sidecar file(s)`)); + } + } + // Remove the source YAML file - we can regenerate from installer source if needed await fs.remove(yamlPath); - console.log(chalk.dim(` Built agent: ${agentName}.md`)); + console.log(chalk.dim(` Built agent: ${agentName}.md${hasSidecar ? ' (with sidecar)' : ''}`)); } // Handle legacy .md agents - inject activation if needed else if (agentFile.endsWith('.md')) { @@ -1628,13 +2073,16 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: } // Build YAML to XML .md - const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, { + let xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, { includeMetadata: true, }); // DO NOT replace {project-root} - LLMs understand this placeholder at runtime // const processedContent = xmlContent.replaceAll('{project-root}', projectDir); + // Process TTS injection points (pass targetPath for tracking) + xmlContent = this.processTTSInjectionPoints(xmlContent, targetMdPath); + // Write the built .md file with POSIX-compliant final newline const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n'; await fs.writeFile(targetMdPath, content, 'utf8'); @@ -1722,13 +2170,31 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: } // Build YAML + customize to .md - const xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, { + let xmlContent = await this.xmlHandler.buildFromYaml(sourceYamlPath, customizeExists ? customizePath : null, { includeMetadata: true, }); // DO NOT replace {project-root} - LLMs understand this placeholder at runtime // const processedContent = xmlContent.replaceAll('{project-root}', projectDir); + // Replace {agent_sidecar_folder} if configured + const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml'); + let agentSidecarFolder = null; + + if (await fs.pathExists(coreConfigPath)) { + const yamlLib = require('yaml'); + const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8'); + const coreConfig = yamlLib.parse(coreConfigContent); + agentSidecarFolder = coreConfig.agent_sidecar_folder; + } + + if (agentSidecarFolder && xmlContent.includes('{agent_sidecar_folder}')) { + xmlContent = xmlContent.replaceAll('{agent_sidecar_folder}', agentSidecarFolder); + } + + // Process TTS injection points (pass targetPath for tracking) + xmlContent = this.processTTSInjectionPoints(xmlContent, targetMdPath); + // Write the rebuilt .md file with POSIX-compliant final newline const content = xmlContent.endsWith('\n') ? xmlContent : xmlContent + '\n'; await fs.writeFile(targetMdPath, content, 'utf8'); @@ -1762,6 +2228,24 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: throw new Error(`BMAD not installed at ${bmadDir}`); } + // Check for custom modules with missing sources + const manifest = await this.manifest.read(bmadDir); + if (manifest && manifest.customModules && manifest.customModules.length > 0) { + spinner.stop(); + console.log(chalk.yellow('\nChecking custom module sources before compilation...')); + + const customModuleSources = new Map(); + for (const customModule of manifest.customModules) { + customModuleSources.set(customModule.id, customModule); + } + + const projectRoot = getProjectRoot(); + const installedModules = manifest.modules || []; + await this.handleMissingCustomSources(customModuleSources, bmadDir, projectRoot, 'compile-agents', installedModules); + + spinner.start('Rebuilding agent files...'); + } + let agentCount = 0; let taskCount = 0; @@ -1906,17 +2390,245 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: const existingInstall = await this.detector.detect(bmadDir); const installedModules = existingInstall.modules.map((m) => m.id); const configuredIdes = existingInstall.ides || []; + const projectRoot = path.dirname(bmadDir); + + // Get custom module sources from manifest + const customModuleSources = new Map(); + if (existingInstall.customModules) { + for (const customModule of existingInstall.customModules) { + // Ensure we have an absolute sourcePath + let absoluteSourcePath = customModule.sourcePath; + + // Check if sourcePath is a cache-relative path (starts with _cfg/) + if (absoluteSourcePath && absoluteSourcePath.startsWith('_cfg')) { + // Convert cache-relative path to absolute path + absoluteSourcePath = path.join(bmadDir, absoluteSourcePath); + } + // If no sourcePath but we have relativePath, convert it + else if (!absoluteSourcePath && customModule.relativePath) { + // relativePath is relative to the project root (parent of bmad dir) + absoluteSourcePath = path.resolve(projectRoot, customModule.relativePath); + } + // Ensure sourcePath is absolute for anything else + else if (absoluteSourcePath && !path.isAbsolute(absoluteSourcePath)) { + absoluteSourcePath = path.resolve(absoluteSourcePath); + } + + // Update the custom module object with the absolute path + const updatedModule = { + ...customModule, + sourcePath: absoluteSourcePath, + }; + + customModuleSources.set(customModule.id, updatedModule); + } + } // Load saved IDE configurations const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir); // Get available modules (what we have source for) - const availableModules = await this.moduleManager.listAvailable(); - const availableModuleIds = new Set(availableModules.map((m) => m.id)); + const availableModulesData = await this.moduleManager.listAvailable(); + const availableModules = [...availableModulesData.modules, ...availableModulesData.customModules]; + + // Add custom modules from manifest if their sources exist + for (const [moduleId, customModule] of customModuleSources) { + // Use the absolute sourcePath + const sourcePath = customModule.sourcePath; + + // Check if source exists at the recorded path + if ( + sourcePath && + (await fs.pathExists(sourcePath)) && // Add to available modules if not already there + !availableModules.some((m) => m.id === moduleId) + ) { + availableModules.push({ + id: moduleId, + name: customModule.name || moduleId, + path: sourcePath, + isCustom: true, + fromManifest: true, + }); + } + } + + // Check for untracked custom modules (installed but not in manifest) + const untrackedCustomModules = []; + for (const installedModule of installedModules) { + // Skip standard modules and core + const standardModuleIds = ['bmb', 'bmgd', 'bmm', 'cis', 'core']; + if (standardModuleIds.includes(installedModule)) { + continue; + } + + // Check if this installed module is not tracked in customModules + if (!customModuleSources.has(installedModule)) { + const modulePath = path.join(bmadDir, installedModule); + if (await fs.pathExists(modulePath)) { + untrackedCustomModules.push({ + id: installedModule, + name: installedModule, // We don't have the original name + path: modulePath, + untracked: true, + }); + } + } + } + + // If we found untracked custom modules, offer to track them + if (untrackedCustomModules.length > 0) { + spinner.stop(); + console.log(chalk.yellow(`\nโš ๏ธ Found ${untrackedCustomModules.length} custom module(s) not tracked in manifest:`)); + + for (const untracked of untrackedCustomModules) { + console.log(chalk.dim(` โ€ข ${untracked.id} (installed at ${path.relative(projectRoot, untracked.path)})`)); + } + + const { trackModules } = await inquirer.prompt([ + { + type: 'confirm', + name: 'trackModules', + message: chalk.cyan('Would you like to scan for their source locations?'), + default: true, + }, + ]); + + if (trackModules) { + const { scanDirectory } = await inquirer.prompt([ + { + type: 'input', + name: 'scanDirectory', + message: 'Enter directory to scan for custom module sources (or leave blank to skip):', + default: projectRoot, + validate: async (input) => { + if (input && input.trim() !== '') { + const expandedPath = path.resolve(input.trim()); + if (!(await fs.pathExists(expandedPath))) { + return 'Directory does not exist'; + } + const stats = await fs.stat(expandedPath); + if (!stats.isDirectory()) { + return 'Path must be a directory'; + } + } + return true; + }, + }, + ]); + + if (scanDirectory && scanDirectory.trim() !== '') { + console.log(chalk.dim('\nScanning for custom module sources...')); + + // Scan for all module.yaml files + const allModulePaths = await this.moduleManager.findModulesInProject(scanDirectory); + const { ModuleManager } = require('../modules/manager'); + const mm = new ModuleManager({ scanProjectForModules: true }); + + for (const untracked of untrackedCustomModules) { + let foundSource = null; + + // Try to find by module ID + for (const modulePath of allModulePaths) { + try { + const moduleInfo = await mm.getModuleInfo(modulePath); + if (moduleInfo && moduleInfo.id === untracked.id) { + foundSource = { + path: modulePath, + info: moduleInfo, + }; + break; + } + } catch { + // Continue searching + } + } + + if (foundSource) { + console.log(chalk.green(` โœ“ Found source for ${untracked.id}: ${path.relative(projectRoot, foundSource.path)}`)); + + // Add to manifest + await this.manifest.addCustomModule(bmadDir, { + id: untracked.id, + name: foundSource.info.name || untracked.name, + sourcePath: path.resolve(foundSource.path), + installDate: new Date().toISOString(), + tracked: true, + }); + + // Add to customModuleSources for processing + customModuleSources.set(untracked.id, { + id: untracked.id, + name: foundSource.info.name || untracked.name, + sourcePath: path.resolve(foundSource.path), + }); + } else { + console.log(chalk.yellow(` โš  Could not find source for ${untracked.id}`)); + } + } + } + } + + console.log(chalk.dim('\nUntracked custom modules will remain installed but cannot be updated without their source.')); + spinner.start('Preparing update...'); + } + + // Handle missing custom module sources using shared method + const customModuleResult = await this.handleMissingCustomSources( + customModuleSources, + bmadDir, + projectRoot, + 'update', + installedModules, + ); + + // Handle both old return format (array) and new format (object) + let validCustomModules = []; + let keptModulesWithoutSources = []; + + if (Array.isArray(customModuleResult)) { + // Old format - just an array + validCustomModules = customModuleResult; + } else if (customModuleResult && typeof customModuleResult === 'object') { + // New format - object with two arrays + validCustomModules = customModuleResult.validCustomModules || []; + keptModulesWithoutSources = customModuleResult.keptModulesWithoutSources || []; + } + + const customModulesFromManifest = validCustomModules.map((m) => ({ + ...m, + isCustom: true, + hasUpdate: true, + })); + + // Add untracked modules to the update list but mark them as untrackable + for (const untracked of untrackedCustomModules) { + if (!customModuleSources.has(untracked.id)) { + customModulesFromManifest.push({ + ...untracked, + isCustom: true, + hasUpdate: false, // Can't update without source + untracked: true, + }); + } + } + + const allAvailableModules = [...availableModules, ...customModulesFromManifest]; + const availableModuleIds = new Set(allAvailableModules.map((m) => m.id)); + + // Core module is special - never include it in update flow + const nonCoreInstalledModules = installedModules.filter((id) => id !== 'core'); // Only update modules that are BOTH installed AND available (we have source for) - const modulesToUpdate = installedModules.filter((id) => availableModuleIds.has(id)); - const skippedModules = installedModules.filter((id) => !availableModuleIds.has(id)); + const modulesToUpdate = nonCoreInstalledModules.filter((id) => availableModuleIds.has(id)); + const skippedModules = nonCoreInstalledModules.filter((id) => !availableModuleIds.has(id)); + + // Add custom modules that were kept without sources to the skipped modules + // This ensures their agents are preserved in the manifest + for (const keptModule of keptModulesWithoutSources) { + if (!skippedModules.includes(keptModule)) { + skippedModules.push(keptModule); + } + } spinner.succeed(`Found ${modulesToUpdate.length} module(s) to update and ${configuredIdes.length} configured tool(s)`); @@ -1981,6 +2693,8 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: _quickUpdate: true, // Flag to skip certain prompts _preserveModules: skippedModules, // Preserve these in manifest even though we didn't update them _savedIdeConfigs: savedIdeConfigs, // Pass saved IDE configs to installer + _customModuleSources: customModuleSources, // Pass custom module sources for updates + _existingModules: installedModules, // Pass all installed modules for manifest generation }; // Call the standard install method @@ -2188,8 +2902,9 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: const installedFilesMap = new Map(); for (const fileEntry of existingFilesManifest) { if (fileEntry.path) { - // Files in manifest are stored as relative paths starting with 'bmad/' - // Convert to absolute path + // Paths are relative to bmadDir. Legacy manifests incorrectly prefixed 'bmad/' - + // strip it if present. This is safe because no real path inside bmadDir would + // start with 'bmad/' (you'd never have .bmad/bmad/... as an actual structure). const relativePath = fileEntry.path.startsWith('bmad/') ? fileEntry.path.slice(5) : fileEntry.path; const absolutePath = path.join(bmadDir, relativePath); installedFilesMap.set(path.normalize(absolutePath), { @@ -2509,8 +3224,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: agentType = parts.slice(-2).join('-'); // Take last 2 parts as type } - // Create target directory - const agentTargetDir = path.join(customAgentsDir, finalAgentName); + // Create target directory - use relative path if agent is in a subdirectory + const agentTargetDir = agent.relativePath + ? path.join(customAgentsDir, agent.relativePath) + : path.join(customAgentsDir, finalAgentName); await fs.ensureDir(agentTargetDir); // Calculate paths @@ -2524,6 +3241,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: agentConfig.defaults || {}, finalAgentName, relativePath, + { config: config.coreConfig }, ); // Write compiled agent @@ -2539,10 +3257,26 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: await fs.copy(agent.yamlFile, backupYamlPath); } - // Copy sidecar files if expert agent - if (agent.hasSidecar && agent.type === 'expert') { - const { copySidecarFiles } = require('../../../lib/agent/installer'); - copySidecarFiles(agent.path, agentTargetDir, agent.yamlFile); + // Copy sidecar files for agents with hasSidecar flag + if (agentConfig.hasSidecar === true && agent.type === 'expert') { + const { copyAgentSidecarFiles } = require('../../../lib/agent/installer'); + + // Get agent sidecar folder from config or use default + const agentSidecarFolder = config.coreConfig?.agent_sidecar_folder; + + // Resolve path variables + const resolvedSidecarFolder = agentSidecarFolder.replaceAll('{project-root}', projectDir).replaceAll('{bmad_folder}', bmadDir); + + // Create sidecar directory for this agent + const agentSidecarDir = path.join(resolvedSidecarFolder, finalAgentName); + await fs.ensureDir(agentSidecarDir); + + // Copy sidecar files (preserve existing, add new) + const sidecarResult = copyAgentSidecarFiles(agent.path, agentSidecarDir, agent.yamlFile); + + if (sidecarResult.copied.length > 0 || sidecarResult.preserved.length > 0) { + console.log(chalk.dim(` Sidecar: ${sidecarResult.copied.length} new, ${sidecarResult.preserved.length} preserved`)); + } } // Update manifest CSV @@ -2602,359 +3336,227 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice: } /** - * Scan for legacy/obsolete files in BMAD installation - * @param {string} bmadDir - BMAD installation directory - * @returns {Object} Categorized files for cleanup + * Handle missing custom module sources interactively + * @param {Map} customModuleSources - Map of custom module ID to info + * @param {string} bmadDir - BMAD directory + * @param {string} projectRoot - Project root directory + * @param {string} operation - Current operation ('update', 'compile', etc.) + * @param {Array} installedModules - Array of installed module IDs (will be modified) + * @returns {Object} Object with validCustomModules array and keptModulesWithoutSources array */ - async scanForLegacyFiles(bmadDir) { - const legacyFiles = { - backup: [], - documentation: [], - deprecated_task: [], - unknown: [], - }; + async handleMissingCustomSources(customModuleSources, bmadDir, projectRoot, operation, installedModules) { + const validCustomModules = []; + const keptModulesWithoutSources = []; // Track modules kept without sources + const customModulesWithMissingSources = []; - try { - // Load files manifest to understand what should exist - const manifestPath = path.join(bmadDir, 'files-manifest.csv'); - const manifestFiles = new Set(); - - if (await fs.pathExists(manifestPath)) { - const manifestContent = await fs.readFile(manifestPath, 'utf8'); - const lines = manifestContent.split('\n').slice(1); // Skip header - for (const line of lines) { - if (line.trim()) { - const relativePath = line.split(',')[0]; - if (relativePath) { - manifestFiles.add(relativePath); - } - } - } - } - - // Scan all files recursively - const allFiles = await this.getAllFiles(bmadDir); - - for (const filePath of allFiles) { - const relativePath = path.relative(bmadDir, filePath); - - // Skip expected files - if (this.isExpectedFile(relativePath, manifestFiles)) { - continue; - } - - // Categorize legacy files - if (relativePath.endsWith('.bak')) { - legacyFiles.backup.push({ - path: filePath, - relativePath: relativePath, - size: (await fs.stat(filePath)).size, - mtime: (await fs.stat(filePath)).mtime, - }); - } else if (this.isDocumentationFile(relativePath)) { - legacyFiles.documentation.push({ - path: filePath, - relativePath: relativePath, - size: (await fs.stat(filePath)).size, - mtime: (await fs.stat(filePath)).mtime, - }); - } else if (this.isDeprecatedTaskFile(relativePath)) { - const suggestedAlternative = this.suggestAlternative(relativePath); - legacyFiles.deprecated_task.push({ - path: filePath, - relativePath: relativePath, - size: (await fs.stat(filePath)).size, - mtime: (await fs.stat(filePath)).mtime, - suggestedAlternative, - }); - } else { - legacyFiles.unknown.push({ - path: filePath, - relativePath: relativePath, - size: (await fs.stat(filePath)).size, - mtime: (await fs.stat(filePath)).mtime, - }); - } - } - } catch (error) { - console.warn(`Warning: Could not scan for legacy files: ${error.message}`); - } - - return legacyFiles; - } - - /** - * Get all files in directory recursively - * @param {string} dir - Directory to scan - * @returns {Array} Array of file paths - */ - async getAllFiles(dir) { - const files = []; - - async function scan(currentDir) { - const entries = await fs.readdir(currentDir); - - for (const entry of entries) { - const fullPath = path.join(currentDir, entry); - const stat = await fs.stat(fullPath); - - if (stat.isDirectory()) { - // Skip certain directories - if (!['node_modules', '.git', 'dist', 'build'].includes(entry)) { - await scan(fullPath); - } - } else { - files.push(fullPath); - } + // Check which sources exist + for (const [moduleId, customInfo] of customModuleSources) { + if (await fs.pathExists(customInfo.sourcePath)) { + validCustomModules.push({ + id: moduleId, + name: customInfo.name, + path: customInfo.sourcePath, + info: customInfo, + }); + } else { + customModulesWithMissingSources.push({ + id: moduleId, + name: customInfo.name, + sourcePath: customInfo.sourcePath, + relativePath: customInfo.relativePath, + info: customInfo, + }); } } - await scan(dir); - return files; - } - - /** - * Check if file is expected in installation - * @param {string} relativePath - Relative path from BMAD dir - * @param {Set} manifestFiles - Files from manifest - * @returns {boolean} True if expected file - */ - isExpectedFile(relativePath, manifestFiles) { - // Core files in manifest - if (manifestFiles.has(relativePath)) { - return true; + // If no missing sources, return immediately + if (customModulesWithMissingSources.length === 0) { + return validCustomModules; } - // Configuration files - if (relativePath.startsWith('_cfg/') || relativePath === 'config.yaml') { - return true; + // Stop any spinner for interactive prompts + const currentSpinner = ora(); + if (currentSpinner.isSpinning) { + currentSpinner.stop(); } - // Custom files - if (relativePath.startsWith('custom/') || relativePath === 'manifest.yaml') { - return true; - } + console.log(chalk.yellow(`\nโš ๏ธ Found ${customModulesWithMissingSources.length} custom module(s) with missing sources:`)); - // Generated files - if (relativePath === 'manifest.csv' || relativePath === 'files-manifest.csv') { - return true; - } - - // IDE-specific files - const ides = ['vscode', 'cursor', 'windsurf', 'claude-code', 'github-copilot', 'zsh', 'bash', 'fish']; - if (ides.some((ide) => relativePath.includes(ide))) { - return true; - } - - // BMAD MODULE STRUCTURES - recognize valid module content - const modulePrefixes = ['bmb/', 'bmm/', 'cis/', 'core/', 'bmgd/']; - const validExtensions = ['.yaml', '.yml', '.json', '.csv', '.md', '.xml', '.svg', '.png', '.jpg', '.gif', '.excalidraw', '.js']; - - // Check if this file is in a recognized module directory - for (const modulePrefix of modulePrefixes) { - if (relativePath.startsWith(modulePrefix)) { - // Check if it has a valid extension - const hasValidExtension = validExtensions.some((ext) => relativePath.endsWith(ext)); - if (hasValidExtension) { - return true; - } - } - } - - // Special case for core module resources - if (relativePath.startsWith('core/resources/')) { - return true; - } - - // Special case for docs directory - if (relativePath.startsWith('docs/')) { - return true; - } - - return false; - } - - /** - * Check if file is documentation - * @param {string} relativePath - Relative path - * @returns {boolean} True if documentation - */ - isDocumentationFile(relativePath) { - const docExtensions = ['.md', '.txt', '.pdf']; - const docPatterns = ['docs/', 'README', 'CHANGELOG', 'LICENSE']; - - return docExtensions.some((ext) => relativePath.endsWith(ext)) || docPatterns.some((pattern) => relativePath.includes(pattern)); - } - - /** - * Check if file is deprecated task file - * @param {string} relativePath - Relative path - * @returns {boolean} True if deprecated - */ - isDeprecatedTaskFile(relativePath) { - // Known deprecated files - const deprecatedFiles = ['adv-elicit-methods.csv', 'game-resources.json', 'ux-workflow.json']; - - return deprecatedFiles.some((dep) => relativePath.includes(dep)); - } - - /** - * Suggest alternative for deprecated file - * @param {string} relativePath - Deprecated file path - * @returns {string} Suggested alternative - */ - suggestAlternative(relativePath) { - const alternatives = { - 'adv-elicit-methods.csv': 'Use the new structured workflows in src/modules/', - 'game-resources.json': 'Resources are now integrated into modules', - 'ux-workflow.json': 'UX workflows are now in src/modules/bmm/workflows/', - }; - - for (const [deprecated, alternative] of Object.entries(alternatives)) { - if (relativePath.includes(deprecated)) { - return alternative; - } - } - - return 'Check src/modules/ for new alternatives'; - } - - /** - * Perform interactive cleanup of legacy files - * @param {string} bmadDir - BMAD installation directory - * @param {boolean} skipInteractive - Skip interactive prompts - * @returns {Object} Cleanup results - */ - async performCleanup(bmadDir, skipInteractive = false) { const inquirer = require('inquirer'); - const yaml = require('js-yaml'); + let keptCount = 0; + let updatedCount = 0; + let removedCount = 0; - // Load user retention preferences - const retentionPath = path.join(bmadDir, '_cfg', 'user-retained-files.yaml'); - let retentionData = { retainedFiles: [], history: [] }; + for (const missing of customModulesWithMissingSources) { + console.log(chalk.dim(` โ€ข ${missing.name} (${missing.id})`)); + console.log(chalk.dim(` Original source: ${missing.relativePath}`)); + console.log(chalk.dim(` Full path: ${missing.sourcePath}`)); - if (await fs.pathExists(retentionPath)) { - const retentionContent = await fs.readFile(retentionPath, 'utf8'); - retentionData = yaml.load(retentionContent) || retentionData; - } + const choices = [ + { + name: 'Keep installed (will not be processed)', + value: 'keep', + short: 'Keep', + }, + { + name: 'Specify new source location', + value: 'update', + short: 'Update', + }, + ]; - // Scan for legacy files - const legacyFiles = await this.scanForLegacyFiles(bmadDir); - const allLegacyFiles = [...legacyFiles.backup, ...legacyFiles.documentation, ...legacyFiles.deprecated_task, ...legacyFiles.unknown]; + // Only add remove option if not just compiling agents + if (operation !== 'compile-agents') { + choices.push({ + name: 'โš ๏ธ REMOVE module completely (destructive!)', + value: 'remove', + short: 'Remove', + }); + } - if (allLegacyFiles.length === 0) { - return { deleted: 0, retained: 0, message: 'No legacy files found' }; - } + const { action } = await inquirer.prompt([ + { + type: 'list', + name: 'action', + message: `How would you like to handle "${missing.name}"?`, + choices, + }, + ]); - let deletedCount = 0; - let retainedCount = 0; - const filesToDelete = []; + switch (action) { + case 'update': { + const { newSourcePath } = await inquirer.prompt([ + { + type: 'input', + name: 'newSourcePath', + message: 'Enter the new path to the custom module:', + default: missing.sourcePath, + validate: async (input) => { + if (!input || input.trim() === '') { + return 'Please enter a path'; + } + const expandedPath = path.resolve(input.trim()); + if (!(await fs.pathExists(expandedPath))) { + return 'Path does not exist'; + } + // Check if it looks like a valid module + const moduleYamlPath = path.join(expandedPath, 'module.yaml'); + const agentsPath = path.join(expandedPath, 'agents'); + const workflowsPath = path.join(expandedPath, 'workflows'); - if (skipInteractive) { - // Auto-delete all non-retained files - for (const file of allLegacyFiles) { - if (!retentionData.retainedFiles.includes(file.relativePath)) { - filesToDelete.push(file); + if (!(await fs.pathExists(moduleYamlPath)) && !(await fs.pathExists(agentsPath)) && !(await fs.pathExists(workflowsPath))) { + return 'Path does not appear to contain a valid custom module'; + } + return true; + }, + }, + ]); + + // Update the source in manifest + const resolvedPath = path.resolve(newSourcePath.trim()); + missing.info.sourcePath = resolvedPath; + // Remove relativePath - we only store absolute sourcePath now + delete missing.info.relativePath; + await this.manifest.addCustomModule(bmadDir, missing.info); + + validCustomModules.push({ + id: moduleId, + name: missing.name, + path: resolvedPath, + info: missing.info, + }); + + updatedCount++; + console.log(chalk.green(`โœ“ Updated source location`)); + + break; } - } - } else { - // Interactive cleanup - console.log(chalk.cyan('\n๐Ÿงน Legacy File Cleanup\n')); - console.log(chalk.dim('The following obsolete files were found:\n')); + case 'remove': { + // Extra confirmation for destructive remove + console.log(chalk.red.bold(`\nโš ๏ธ WARNING: This will PERMANENTLY DELETE "${missing.name}" and all its files!`)); + console.log(chalk.red(` Module location: ${path.join(bmadDir, moduleId)}`)); - // Group files by category - const categories = []; - if (legacyFiles.backup.length > 0) { - categories.push({ name: 'Backup Files (.bak)', files: legacyFiles.backup }); - } - if (legacyFiles.documentation.length > 0) { - categories.push({ name: 'Documentation', files: legacyFiles.documentation }); - } - if (legacyFiles.deprecated_task.length > 0) { - categories.push({ name: 'Deprecated Task Files', files: legacyFiles.deprecated_task }); - } - if (legacyFiles.unknown.length > 0) { - categories.push({ name: 'Unknown Files', files: legacyFiles.unknown }); - } + const { confirm } = await inquirer.prompt([ + { + type: 'confirm', + name: 'confirm', + message: chalk.red.bold('Are you absolutely sure you want to delete this module?'), + default: false, + }, + ]); - for (const category of categories) { - console.log(chalk.yellow(`${category.name}:`)); - for (const file of category.files) { - const size = (file.size / 1024).toFixed(1); - const date = file.mtime.toLocaleDateString(); - let line = ` - ${file.relativePath} (${size}KB, ${date})`; - if (file.suggestedAlternative) { - line += chalk.dim(` โ†’ ${file.suggestedAlternative}`); + if (confirm) { + const { typedConfirm } = await inquirer.prompt([ + { + type: 'input', + name: 'typedConfirm', + message: chalk.red.bold('Type "DELETE" to confirm permanent deletion:'), + validate: (input) => { + if (input !== 'DELETE') { + return chalk.red('You must type "DELETE" exactly to proceed'); + } + return true; + }, + }, + ]); + + if (typedConfirm === 'DELETE') { + // Remove the module from filesystem and manifest + const modulePath = path.join(bmadDir, moduleId); + if (await fs.pathExists(modulePath)) { + const fsExtra = require('fs-extra'); + await fsExtra.remove(modulePath); + console.log(chalk.yellow(` โœ“ Deleted module directory: ${path.relative(projectRoot, modulePath)}`)); + } + + await this.manifest.removeModule(bmadDir, moduleId); + await this.manifest.removeCustomModule(bmadDir, moduleId); + console.log(chalk.yellow(` โœ“ Removed from manifest`)); + + // Also remove from installedModules list + if (installedModules && installedModules.includes(moduleId)) { + const index = installedModules.indexOf(moduleId); + if (index !== -1) { + installedModules.splice(index, 1); + } + } + + removedCount++; + console.log(chalk.red.bold(`โœ“ "${missing.name}" has been permanently removed`)); + } else { + console.log(chalk.dim(' Removal cancelled - module will be kept')); + keptCount++; + } + } else { + console.log(chalk.dim(' Removal cancelled - module will be kept')); + keptCount++; } - console.log(chalk.dim(line)); + + break; } - console.log(); - } + case 'keep': { + keptCount++; + keptModulesWithoutSources.push(moduleId); + console.log(chalk.dim(` Module will be kept as-is`)); - const prompt = await inquirer.prompt([ - { - type: 'confirm', - name: 'proceed', - message: 'Would you like to review these files for cleanup?', - default: true, - }, - ]); - - if (!prompt.proceed) { - return { deleted: 0, retained: allLegacyFiles.length, message: 'Cleanup cancelled by user' }; - } - - // Show selection interface - const selectionPrompt = await inquirer.prompt([ - { - type: 'checkbox', - name: 'filesToDelete', - message: 'Select files to delete (use SPACEBAR to select, ENTER to continue):', - choices: allLegacyFiles.map((file) => { - const isRetained = retentionData.retainedFiles.includes(file.relativePath); - const description = `${file.relativePath} (${(file.size / 1024).toFixed(1)}KB)`; - return { - name: description, - value: file, - checked: !isRetained && !file.relativePath.includes('.bak'), - }; - }), - pageSize: Math.min(allLegacyFiles.length, 15), - }, - ]); - - filesToDelete.push(...selectionPrompt.filesToDelete); - } - - // Delete selected files - for (const file of filesToDelete) { - try { - await fs.remove(file.path); - deletedCount++; - } catch (error) { - console.warn(`Warning: Could not delete ${file.relativePath}: ${error.message}`); + break; + } + // No default } } - // Count retained files - retainedCount = allLegacyFiles.length - deletedCount; + // Show summary + if (keptCount > 0 || updatedCount > 0 || removedCount > 0) { + console.log(chalk.dim(`\nSummary for custom modules with missing sources:`)); + if (keptCount > 0) console.log(chalk.dim(` โ€ข ${keptCount} module(s) kept as-is`)); + if (updatedCount > 0) console.log(chalk.dim(` โ€ข ${updatedCount} module(s) updated with new sources`)); + if (removedCount > 0) console.log(chalk.red(` โ€ข ${removedCount} module(s) permanently deleted`)); + } - // Update retention data - const newlyRetained = allLegacyFiles.filter((f) => !filesToDelete.includes(f)).map((f) => f.relativePath); - - retentionData.retainedFiles = [...new Set([...retentionData.retainedFiles, ...newlyRetained])]; - retentionData.history.push({ - date: new Date().toISOString(), - deleted: deletedCount, - retained: retainedCount, - files: filesToDelete.map((f) => f.relativePath), - }); - - // Save retention data - await fs.ensureDir(path.dirname(retentionPath)); - await fs.writeFile(retentionPath, yaml.dump(retentionData), 'utf8'); - - return { deleted: deletedCount, retained: retainedCount }; + return { + validCustomModules, + keptModulesWithoutSources, + }; } } diff --git a/tools/cli/installers/lib/core/manifest-generator.js b/tools/cli/installers/lib/core/manifest-generator.js index 644fd494..71b23605 100644 --- a/tools/cli/installers/lib/core/manifest-generator.js +++ b/tools/cli/installers/lib/core/manifest-generator.js @@ -34,10 +34,18 @@ class ManifestGenerator { // Store modules list (all modules including preserved ones) const preservedModules = options.preservedModules || []; + + // Scan the bmad directory to find all actually installed modules + const installedModules = await this.scanInstalledModules(bmadDir); + // Deduplicate modules list to prevent duplicates - this.modules = [...new Set(['core', ...selectedModules, ...preservedModules])]; - this.updatedModules = [...new Set(['core', ...selectedModules])]; // Only these get rescanned - this.preservedModules = preservedModules; // These stay as-is in CSVs + this.modules = [...new Set(['core', ...selectedModules, ...preservedModules, ...installedModules])]; + this.updatedModules = [...new Set(['core', ...selectedModules, ...installedModules])]; // All installed modules get rescanned + + // For CSV manifests, we need to include ALL modules that are installed + // preservedModules controls which modules stay as-is in the CSV (don't get rescanned) + // But all modules should be included in the final manifest + this.preservedModules = [...new Set([...preservedModules, ...selectedModules, ...installedModules])]; // Include all installed modules this.bmadDir = bmadDir; this.bmadFolderName = path.basename(bmadDir); // Get the actual folder name (e.g., '.bmad' or 'bmad') this.allInstalledFiles = installedFiles; @@ -57,14 +65,14 @@ class ManifestGenerator { // Collect workflow data await this.collectWorkflows(selectedModules); - // Collect agent data - await this.collectAgents(selectedModules); + // Collect agent data - use updatedModules which includes all installed modules + await this.collectAgents(this.updatedModules); // Collect task data - await this.collectTasks(selectedModules); + await this.collectTasks(this.updatedModules); // Collect tool data - await this.collectTools(selectedModules); + await this.collectTools(this.updatedModules); // Write manifest files and collect their paths const manifestFiles = [ @@ -216,18 +224,23 @@ class ManifestGenerator { } /** - * Get agents from a directory + * Get agents from a directory recursively * Only includes compiled .md files (not .agent.yaml source files) */ - async getAgentsFromDir(dirPath, moduleName) { + async getAgentsFromDir(dirPath, moduleName, relativePath = '') { const agents = []; - const files = await fs.readdir(dirPath); + const entries = await fs.readdir(dirPath, { withFileTypes: true }); - for (const file of files) { - // Only include .md files, skip .agent.yaml source files and README.md - if (file.endsWith('.md') && !file.endsWith('.agent.yaml') && file.toLowerCase() !== 'readme.md') { - const filePath = path.join(dirPath, file); - const content = await fs.readFile(filePath, 'utf8'); + for (const entry of entries) { + const fullPath = path.join(dirPath, entry.name); + + if (entry.isDirectory()) { + // Recurse into subdirectories + const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; + const subDirAgents = await this.getAgentsFromDir(fullPath, moduleName, newRelativePath); + agents.push(...subDirAgents); + } else if (entry.name.endsWith('.md') && !entry.name.endsWith('.agent.yaml') && entry.name.toLowerCase() !== 'readme.md') { + const content = await fs.readFile(fullPath, 'utf8'); // Skip files that don't contain tag (e.g., README files) if (!content.includes('([\s\S]*?)<\/principles>/); // Build relative path for installation + const fileRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; const installPath = - moduleName === 'core' ? `${this.bmadFolderName}/core/agents/${file}` : `${this.bmadFolderName}/${moduleName}/agents/${file}`; + moduleName === 'core' + ? `${this.bmadFolderName}/core/agents/${fileRelativePath}` + : `${this.bmadFolderName}/${moduleName}/agents/${fileRelativePath}`; - const agentName = file.replace('.md', ''); + const agentName = entry.name.replace('.md', ''); // Helper function to clean and escape CSV content const cleanForCSV = (text) => { @@ -438,6 +454,21 @@ class ManifestGenerator { async writeMainManifest(cfgDir) { const manifestPath = path.join(cfgDir, 'manifest.yaml'); + // Read existing manifest to preserve custom modules + let existingCustomModules = []; + if (await fs.pathExists(manifestPath)) { + try { + const existingContent = await fs.readFile(manifestPath, 'utf8'); + const existingManifest = yaml.load(existingContent); + if (existingManifest && existingManifest.customModules) { + existingCustomModules = existingManifest.customModules; + } + } catch { + // If we can't read the existing manifest, continue without preserving custom modules + console.warn('Warning: Could not read existing manifest to preserve custom modules'); + } + } + const manifest = { installation: { version: packageJson.version, @@ -445,6 +476,7 @@ class ManifestGenerator { lastUpdated: new Date().toISOString(), }, modules: this.modules, + customModules: existingCustomModules, // Preserve custom modules ides: this.selectedIdes, }; @@ -550,12 +582,47 @@ class ManifestGenerator { async writeWorkflowManifest(cfgDir) { const csvPath = path.join(cfgDir, 'workflow-manifest.csv'); + // Read existing manifest to preserve entries + const existingEntries = new Map(); + if (await fs.pathExists(csvPath)) { + const content = await fs.readFile(csvPath, 'utf8'); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 4) { + const name = parts[0].replace(/^"/, ''); + const module = parts[2]; + existingEntries.set(`${module}:${name}`, line); + } + } + } + } + // Create CSV header - removed standalone column as ALL workflows now generate commands let csv = 'name,description,module,path\n'; - // Add all workflows - no standalone property needed anymore + // Combine existing and new workflows + const allWorkflows = new Map(); + + // Add existing entries + for (const [key, value] of existingEntries) { + allWorkflows.set(key, value); + } + + // Add/update new workflows for (const workflow of this.workflows) { - csv += `"${workflow.name}","${workflow.description}","${workflow.module}","${workflow.path}"\n`; + const key = `${workflow.module}:${workflow.name}`; + allWorkflows.set(key, `"${workflow.name}","${workflow.description}","${workflow.module}","${workflow.path}"`); + } + + // Write all workflows + for (const [, value] of allWorkflows) { + csv += value + '\n'; } await fs.writeFile(csvPath, csv); @@ -569,12 +636,50 @@ class ManifestGenerator { async writeAgentManifest(cfgDir) { const csvPath = path.join(cfgDir, 'agent-manifest.csv'); + // Read existing manifest to preserve entries + const existingEntries = new Map(); + if (await fs.pathExists(csvPath)) { + const content = await fs.readFile(csvPath, 'utf8'); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 11) { + const name = parts[0].replace(/^"/, ''); + const module = parts[8]; + existingEntries.set(`${module}:${name}`, line); + } + } + } + } + // Create CSV header with persona fields let csv = 'name,displayName,title,icon,role,identity,communicationStyle,principles,module,path\n'; - // Add all agents + // Combine existing and new agents, preferring new data for duplicates + const allAgents = new Map(); + + // Add existing entries + for (const [key, value] of existingEntries) { + allAgents.set(key, value); + } + + // Add/update new agents for (const agent of this.agents) { - csv += `"${agent.name}","${agent.displayName}","${agent.title}","${agent.icon}","${agent.role}","${agent.identity}","${agent.communicationStyle}","${agent.principles}","${agent.module}","${agent.path}"\n`; + const key = `${agent.module}:${agent.name}`; + allAgents.set( + key, + `"${agent.name}","${agent.displayName}","${agent.title}","${agent.icon}","${agent.role}","${agent.identity}","${agent.communicationStyle}","${agent.principles}","${agent.module}","${agent.path}"`, + ); + } + + // Write all agents + for (const [, value] of allAgents) { + csv += value + '\n'; } await fs.writeFile(csvPath, csv); @@ -588,12 +693,47 @@ class ManifestGenerator { async writeTaskManifest(cfgDir) { const csvPath = path.join(cfgDir, 'task-manifest.csv'); + // Read existing manifest to preserve entries + const existingEntries = new Map(); + if (await fs.pathExists(csvPath)) { + const content = await fs.readFile(csvPath, 'utf8'); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 6) { + const name = parts[0].replace(/^"/, ''); + const module = parts[3]; + existingEntries.set(`${module}:${name}`, line); + } + } + } + } + // Create CSV header with standalone column let csv = 'name,displayName,description,module,path,standalone\n'; - // Add all tasks + // Combine existing and new tasks + const allTasks = new Map(); + + // Add existing entries + for (const [key, value] of existingEntries) { + allTasks.set(key, value); + } + + // Add/update new tasks for (const task of this.tasks) { - csv += `"${task.name}","${task.displayName}","${task.description}","${task.module}","${task.path}","${task.standalone}"\n`; + const key = `${task.module}:${task.name}`; + allTasks.set(key, `"${task.name}","${task.displayName}","${task.description}","${task.module}","${task.path}","${task.standalone}"`); + } + + // Write all tasks + for (const [, value] of allTasks) { + csv += value + '\n'; } await fs.writeFile(csvPath, csv); @@ -607,12 +747,47 @@ class ManifestGenerator { async writeToolManifest(cfgDir) { const csvPath = path.join(cfgDir, 'tool-manifest.csv'); + // Read existing manifest to preserve entries + const existingEntries = new Map(); + if (await fs.pathExists(csvPath)) { + const content = await fs.readFile(csvPath, 'utf8'); + const lines = content.split('\n').filter((line) => line.trim()); + + // Skip header + for (let i = 1; i < lines.length; i++) { + const line = lines[i]; + if (line) { + // Parse CSV (simple parsing assuming no commas in quoted fields) + const parts = line.split('","'); + if (parts.length >= 6) { + const name = parts[0].replace(/^"/, ''); + const module = parts[3]; + existingEntries.set(`${module}:${name}`, line); + } + } + } + } + // Create CSV header with standalone column let csv = 'name,displayName,description,module,path,standalone\n'; - // Add all tools + // Combine existing and new tools + const allTools = new Map(); + + // Add existing entries + for (const [key, value] of existingEntries) { + allTools.set(key, value); + } + + // Add/update new tools for (const tool of this.tools) { - csv += `"${tool.name}","${tool.displayName}","${tool.description}","${tool.module}","${tool.path}","${tool.standalone}"\n`; + const key = `${tool.module}:${tool.name}`; + allTools.set(key, `"${tool.name}","${tool.displayName}","${tool.description}","${tool.module}","${tool.path}","${tool.standalone}"`); + } + + // Write all tools + for (const [, value] of allTools) { + csv += value + '\n'; } await fs.writeFile(csvPath, csv); @@ -650,13 +825,14 @@ class ManifestGenerator { if (this.allInstalledFiles && this.allInstalledFiles.length > 0) { // Process all installed files for (const filePath of this.allInstalledFiles) { - const relativePath = 'bmad' + filePath.replace(this.bmadDir, '').replaceAll('\\', '/'); + // Store paths relative to bmadDir (no folder prefix) + const relativePath = filePath.replace(this.bmadDir, '').replaceAll('\\', '/').replace(/^\//, ''); const ext = path.extname(filePath).toLowerCase(); const fileName = path.basename(filePath, ext); - // Determine module from path + // Determine module from path (first directory component) const pathParts = relativePath.split('/'); - const module = pathParts.length > 1 ? pathParts[1] : 'unknown'; + const module = pathParts.length > 0 ? pathParts[0] : 'unknown'; // Calculate hash const hash = await this.calculateFileHash(filePath); @@ -672,10 +848,13 @@ class ManifestGenerator { } else { // Fallback: use the collected workflows/agents/tasks for (const file of this.files) { - const filePath = path.join(this.bmadDir, file.path.replace(this.bmadFolderName + '/', '')); + // Strip the folder prefix if present (for consistency) + const relPath = file.path.replace(this.bmadFolderName + '/', ''); + const filePath = path.join(this.bmadDir, relPath); const hash = await this.calculateFileHash(filePath); allFiles.push({ ...file, + path: relPath, hash: hash, }); } @@ -696,6 +875,42 @@ class ManifestGenerator { await fs.writeFile(csvPath, csv); return csvPath; } + + /** + * Scan the bmad directory to find all installed modules + * @param {string} bmadDir - Path to bmad directory + * @returns {Array} List of module names + */ + async scanInstalledModules(bmadDir) { + const modules = []; + + try { + const entries = await fs.readdir(bmadDir, { withFileTypes: true }); + + for (const entry of entries) { + // Skip if not a directory or is a special directory + if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === '_cfg') { + continue; + } + + // Check if this looks like a module (has agents, workflows, or tasks directory) + const modulePath = path.join(bmadDir, entry.name); + const hasAgents = await fs.pathExists(path.join(modulePath, 'agents')); + const hasWorkflows = await fs.pathExists(path.join(modulePath, 'workflows')); + const hasTasks = await fs.pathExists(path.join(modulePath, 'tasks')); + const hasTools = await fs.pathExists(path.join(modulePath, 'tools')); + + // If it has any of these directories, it's likely a module + if (hasAgents || hasWorkflows || hasTasks || hasTools) { + modules.push(entry.name); + } + } + } catch (error) { + console.warn(`Warning: Could not scan for installed modules: ${error.message}`); + } + + return modules; + } } module.exports = { ManifestGenerator }; diff --git a/tools/cli/installers/lib/core/manifest.js b/tools/cli/installers/lib/core/manifest.js index e0cf1cd8..ce12304f 100644 --- a/tools/cli/installers/lib/core/manifest.js +++ b/tools/cli/installers/lib/core/manifest.js @@ -61,6 +61,7 @@ class Manifest { installDate: manifestData.installation?.installDate, lastUpdated: manifestData.installation?.lastUpdated, modules: manifestData.modules || [], + customModules: manifestData.customModules || [], ides: manifestData.ides || [], }; } catch (error) { @@ -93,6 +94,7 @@ class Manifest { lastUpdated: manifest.lastUpdated, }, modules: manifest.modules || [], + customModules: manifest.customModules || [], ides: manifest.ides || [], }; @@ -535,6 +537,51 @@ class Manifest { return configs; } + /** + * Add a custom module to the manifest with its source path + * @param {string} bmadDir - Path to bmad directory + * @param {Object} customModule - Custom module info + */ + async addCustomModule(bmadDir, customModule) { + const manifest = await this.read(bmadDir); + if (!manifest) { + throw new Error('No manifest found'); + } + + if (!manifest.customModules) { + manifest.customModules = []; + } + + // Check if custom module already exists + const existingIndex = manifest.customModules.findIndex((m) => m.id === customModule.id); + if (existingIndex === -1) { + // Add new entry + manifest.customModules.push(customModule); + } else { + // Update existing entry + manifest.customModules[existingIndex] = customModule; + } + + await this.update(bmadDir, { customModules: manifest.customModules }); + } + + /** + * Remove a custom module from the manifest + * @param {string} bmadDir - Path to bmad directory + * @param {string} moduleId - Module ID to remove + */ + async removeCustomModule(bmadDir, moduleId) { + const manifest = await this.read(bmadDir); + if (!manifest || !manifest.customModules) { + return; + } + + const index = manifest.customModules.findIndex((m) => m.id === moduleId); + if (index !== -1) { + manifest.customModules.splice(index, 1); + await this.update(bmadDir, { customModules: manifest.customModules }); + } + } } module.exports = { Manifest }; diff --git a/tools/cli/installers/lib/core/post-install-sidecar-replacement.js b/tools/cli/installers/lib/core/post-install-sidecar-replacement.js new file mode 100644 index 00000000..da351c50 --- /dev/null +++ b/tools/cli/installers/lib/core/post-install-sidecar-replacement.js @@ -0,0 +1,79 @@ +/** + * Post-installation sidecar folder replacement utility + * Replaces {agent_sidecar_folder} placeholders in all installed agents + */ + +const fs = require('fs-extra'); +const path = require('node:path'); +const yaml = require('yaml'); +const glob = require('glob'); +const chalk = require('chalk'); + +/** + * Replace {agent_sidecar_folder} placeholders in all agent files + * @param {string} bmadDir - Path to .bmad directory + * @returns {Object} Statistics about replacements made + */ +async function replaceAgentSidecarFolders(bmadDir) { + const results = { + filesScanned: 0, + filesReplaced: 0, + totalReplacements: 0, + errors: [], + }; + + try { + // Load core config to get agent_sidecar_folder value + const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml'); + + if (!(await fs.pathExists(coreConfigPath))) { + throw new Error(`Core config not found at ${coreConfigPath}`); + } + + const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8'); + const coreConfig = yaml.parse(coreConfigContent); + const agentSidecarFolder = coreConfig.agent_sidecar_folder; + + // Use the literal value from config, don't resolve the placeholders + console.log(chalk.dim(`\n Replacing {agent_sidecar_folder} with: ${agentSidecarFolder}`)); + + // Find all agent .md files + const agentPattern = path.join(bmadDir, '**/*.md'); + const agentFiles = glob.sync(agentPattern); + + for (const agentFile of agentFiles) { + results.filesScanned++; + + try { + let content = await fs.readFile(agentFile, 'utf8'); + + // Check if file contains {agent_sidecar_folder} + if (content.includes('{agent_sidecar_folder}')) { + // Replace all occurrences + const originalContent = content; + content = content.replaceAll('{agent_sidecar_folder}', agentSidecarFolder); + + // Only write if content changed + if (content !== originalContent) { + await fs.writeFile(agentFile, content, 'utf8'); + + const replacementCount = (originalContent.match(/{agent_sidecar_folder}/g) || []).length; + results.filesReplaced++; + results.totalReplacements += replacementCount; + + console.log(chalk.dim(` โœ“ Replaced ${replacementCount} occurrence(s) in ${path.relative(bmadDir, agentFile)}`)); + } + } + } catch (error) { + results.errors.push(`Error processing ${agentFile}: ${error.message}`); + } + } + + return results; + } catch (error) { + results.errors.push(`Fatal error: ${error.message}`); + return results; + } +} + +module.exports = { replaceAgentSidecarFolders }; diff --git a/tools/cli/installers/lib/custom/handler.js b/tools/cli/installers/lib/custom/handler.js new file mode 100644 index 00000000..3f6f46d0 --- /dev/null +++ b/tools/cli/installers/lib/custom/handler.js @@ -0,0 +1,396 @@ +const path = require('node:path'); +const fs = require('fs-extra'); +const chalk = require('chalk'); +const yaml = require('js-yaml'); +const { FileOps } = require('../../../lib/file-ops'); +const { XmlHandler } = require('../../../lib/xml-handler'); + +/** + * Handler for custom content (custom.yaml) + * Installs custom agents and workflows without requiring a full module structure + */ +class CustomHandler { + constructor() { + this.fileOps = new FileOps(); + this.xmlHandler = new XmlHandler(); + } + + /** + * Find all custom.yaml files in the project + * @param {string} projectRoot - Project root directory + * @returns {Array} List of custom content paths + */ + async findCustomContent(projectRoot) { + const customPaths = []; + + // Helper function to recursively scan directories + async function scanDirectory(dir, excludePaths = []) { + try { + const entries = await fs.readdir(dir, { withFileTypes: true }); + + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + + // Skip hidden directories and common exclusions + if ( + entry.name.startsWith('.') || + entry.name === 'node_modules' || + entry.name === 'dist' || + entry.name === 'build' || + entry.name === '.git' || + entry.name === 'bmad' + ) { + continue; + } + + // Skip excluded paths + if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) { + continue; + } + + if (entry.isDirectory()) { + // Recursively scan subdirectories + await scanDirectory(fullPath, excludePaths); + } else if (entry.name === 'custom.yaml') { + // Found a custom.yaml file + customPaths.push(fullPath); + } else if ( + entry.name === 'module.yaml' && // Check if this is a custom module (either in _module-installer or in root directory) + // Skip if it's in src/modules (those are standard modules) + !fullPath.includes(path.join('src', 'modules')) + ) { + customPaths.push(fullPath); + } + } + } catch { + // Ignore errors (e.g., permission denied) + } + } + + // Scan the entire project, but exclude source directories + await scanDirectory(projectRoot, [path.join(projectRoot, 'src'), path.join(projectRoot, 'tools'), path.join(projectRoot, 'test')]); + + return customPaths; + } + + /** + * Get custom content info from a custom.yaml or module.yaml file + * @param {string} configPath - Path to config file + * @param {string} projectRoot - Project root directory for calculating relative paths + * @returns {Object|null} Custom content info + */ + async getCustomInfo(configPath, projectRoot = null) { + try { + const configContent = await fs.readFile(configPath, 'utf8'); + + // Try to parse YAML with error handling + let config; + try { + config = yaml.load(configContent); + } catch (parseError) { + console.warn(chalk.yellow(`Warning: YAML parse error in ${configPath}:`, parseError.message)); + return null; + } + + // Check if this is an module.yaml (module) or custom.yaml (custom content) + const isInstallConfig = configPath.endsWith('module.yaml'); + const configDir = path.dirname(configPath); + + // Use provided projectRoot or fall back to process.cwd() + const basePath = projectRoot || process.cwd(); + const relativePath = path.relative(basePath, configDir); + + return { + id: config.code || 'unknown-code', + name: config.name, + description: config.description || '', + path: configDir, + relativePath: relativePath, + defaultSelected: config.default_selected === true, + config: config, + isInstallConfig: isInstallConfig, // Track which type this is + }; + } catch (error) { + console.warn(chalk.yellow(`Warning: Failed to read ${configPath}:`, error.message)); + return null; + } + } + + /** + * Install custom content + * @param {string} customPath - Path to custom content directory + * @param {string} bmadDir - Target bmad directory + * @param {Object} config - Configuration from custom.yaml + * @param {Function} fileTrackingCallback - Optional callback to track installed files + * @returns {Object} Installation result + */ + async install(customPath, bmadDir, config, fileTrackingCallback = null) { + const results = { + agentsInstalled: 0, + workflowsInstalled: 0, + filesCopied: 0, + preserved: 0, + errors: [], + }; + + try { + // Create custom directories in bmad + const bmadCustomDir = path.join(bmadDir, 'custom'); + const bmadAgentsDir = path.join(bmadCustomDir, 'agents'); + const bmadWorkflowsDir = path.join(bmadCustomDir, 'workflows'); + + await fs.ensureDir(bmadCustomDir); + await fs.ensureDir(bmadAgentsDir); + await fs.ensureDir(bmadWorkflowsDir); + + // Process agents - compile and copy agents + const agentsDir = path.join(customPath, 'agents'); + if (await fs.pathExists(agentsDir)) { + await this.compileAndCopyAgents(agentsDir, bmadAgentsDir, bmadDir, config, fileTrackingCallback, results); + + // Count agent files + const agentFiles = await this.findFilesRecursively(agentsDir, ['.agent.yaml', '.md']); + results.agentsInstalled = agentFiles.length; + } + + // Process workflows - copy entire workflows directory structure + const workflowsDir = path.join(customPath, 'workflows'); + if (await fs.pathExists(workflowsDir)) { + await this.copyDirectory(workflowsDir, bmadWorkflowsDir, results, fileTrackingCallback, config); + + // Count workflow files + const workflowFiles = await this.findFilesRecursively(workflowsDir, ['.md']); + results.workflowsInstalled = workflowFiles.length; + } + + // Process any additional files at root + const entries = await fs.readdir(customPath, { withFileTypes: true }); + for (const entry of entries) { + if (entry.isFile() && entry.name !== 'custom.yaml' && !entry.name.startsWith('.') && !entry.name.endsWith('.md')) { + // Skip .md files at root as they're likely docs + const sourcePath = path.join(customPath, entry.name); + const targetPath = path.join(bmadCustomDir, entry.name); + + try { + // Check if file already exists + if (await fs.pathExists(targetPath)) { + // File already exists, preserve it + results.preserved = (results.preserved || 0) + 1; + } else { + await fs.copy(sourcePath, targetPath); + results.filesCopied++; + + if (fileTrackingCallback) { + fileTrackingCallback(targetPath); + } + } + } catch (error) { + results.errors.push(`Failed to copy file ${entry.name}: ${error.message}`); + } + } + } + } catch (error) { + results.errors.push(`Installation failed: ${error.message}`); + } + + return results; + } + + /** + * Find all files with specific extensions recursively + * @param {string} dir - Directory to search + * @param {Array} extensions - File extensions to match + * @returns {Array} List of matching files + */ + async findFilesRecursively(dir, extensions) { + const files = []; + + async function search(currentDir) { + const entries = await fs.readdir(currentDir, { withFileTypes: true }); + + for (const entry of entries) { + const fullPath = path.join(currentDir, entry.name); + + if (entry.isDirectory()) { + await search(fullPath); + } else if (extensions.some((ext) => entry.name.endsWith(ext))) { + files.push(fullPath); + } + } + } + + await search(dir); + return files; + } + + /** + * Recursively copy a directory + * @param {string} sourceDir - Source directory + * @param {string} targetDir - Target directory + * @param {Object} results - Results object to update + * @param {Function} fileTrackingCallback - Optional callback + * @param {Object} config - Configuration for placeholder replacement + */ + async copyDirectory(sourceDir, targetDir, results, fileTrackingCallback, config) { + await fs.ensureDir(targetDir); + const entries = await fs.readdir(sourceDir, { withFileTypes: true }); + + for (const entry of entries) { + const sourcePath = path.join(sourceDir, entry.name); + const targetPath = path.join(targetDir, entry.name); + + if (entry.isDirectory()) { + await this.copyDirectory(sourcePath, targetPath, results, fileTrackingCallback, config); + } else { + try { + // Check if file already exists + if (await fs.pathExists(targetPath)) { + // File already exists, preserve it + results.preserved = (results.preserved || 0) + 1; + } else { + // Copy with placeholder replacement for text files + const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json']; + if (textExtensions.some((ext) => entry.name.endsWith(ext))) { + // Read source content + let content = await fs.readFile(sourcePath, 'utf8'); + + // Replace placeholders + content = content.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad'); + content = content.replaceAll('{user_name}', config.user_name || 'User'); + content = content.replaceAll('{communication_language}', config.communication_language || 'English'); + content = content.replaceAll('{output_folder}', config.output_folder || 'docs'); + + // Write to target + await fs.ensureDir(path.dirname(targetPath)); + await fs.writeFile(targetPath, content, 'utf8'); + } else { + // Copy binary files as-is + await fs.copy(sourcePath, targetPath); + } + + results.filesCopied++; + if (fileTrackingCallback) { + fileTrackingCallback(targetPath); + } + } + + if (entry.name.endsWith('.md')) { + results.workflowsInstalled++; + } + } catch (error) { + results.errors.push(`Failed to copy ${entry.name}: ${error.message}`); + } + } + } + } + + /** + * Compile .agent.yaml files to .md format and handle sidecars + * @param {string} sourceAgentsPath - Source agents directory + * @param {string} targetAgentsPath - Target agents directory + * @param {string} bmadDir - BMAD installation directory + * @param {Object} config - Configuration for placeholder replacement + * @param {Function} fileTrackingCallback - Optional callback to track installed files + * @param {Object} results - Results object to update + */ + async compileAndCopyAgents(sourceAgentsPath, targetAgentsPath, bmadDir, config, fileTrackingCallback, results) { + // Get all .agent.yaml files recursively + const agentFiles = await this.findFilesRecursively(sourceAgentsPath, ['.agent.yaml']); + + for (const agentFile of agentFiles) { + const relativePath = path.relative(sourceAgentsPath, agentFile); + const targetDir = path.join(targetAgentsPath, path.dirname(relativePath)); + + await fs.ensureDir(targetDir); + + const agentName = path.basename(agentFile, '.agent.yaml'); + const targetMdPath = path.join(targetDir, `${agentName}.md`); + // Use the actual bmadDir if available (for when installing to temp dir) + const actualBmadDir = config._bmadDir || bmadDir; + const customizePath = path.join(actualBmadDir, '_cfg', 'agents', `custom-${agentName}.customize.yaml`); + + // Read and compile the YAML + try { + const yamlContent = await fs.readFile(agentFile, 'utf8'); + const { compileAgent } = require('../../../lib/agent/compiler'); + + // Create customize template if it doesn't exist + if (!(await fs.pathExists(customizePath))) { + const { getSourcePath } = require('../../../lib/project-root'); + const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml'); + if (await fs.pathExists(genericTemplatePath)) { + // Copy with placeholder replacement + let templateContent = await fs.readFile(genericTemplatePath, 'utf8'); + templateContent = templateContent.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad'); + await fs.writeFile(customizePath, templateContent, 'utf8'); + console.log(chalk.dim(` Created customize: custom-${agentName}.customize.yaml`)); + } + } + + // Compile the agent + const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config }); + + // Replace placeholders in the compiled content + let processedXml = xml; + processedXml = processedXml.replaceAll('{bmad_folder}', config.bmad_folder || 'bmad'); + processedXml = processedXml.replaceAll('{user_name}', config.user_name || 'User'); + processedXml = processedXml.replaceAll('{communication_language}', config.communication_language || 'English'); + processedXml = processedXml.replaceAll('{output_folder}', config.output_folder || 'docs'); + + // Write the compiled MD file + await fs.writeFile(targetMdPath, processedXml, 'utf8'); + + // Check if agent has sidecar + let hasSidecar = false; + try { + const yamlLib = require('yaml'); + const agentYaml = yamlLib.parse(yamlContent); + hasSidecar = agentYaml?.agent?.metadata?.hasSidecar === true; + } catch { + // Continue without sidecar processing + } + + // Copy sidecar files if agent has hasSidecar flag + if (hasSidecar && config.agent_sidecar_folder) { + const { copyAgentSidecarFiles } = require('../../../lib/agent/installer'); + + // Resolve agent sidecar folder path + const projectDir = path.dirname(bmadDir); + const resolvedSidecarFolder = config.agent_sidecar_folder + .replaceAll('{project-root}', projectDir) + .replaceAll('{bmad_folder}', path.basename(bmadDir)); + + // Create sidecar directory for this agent + const agentSidecarDir = path.join(resolvedSidecarFolder, agentName); + await fs.ensureDir(agentSidecarDir); + + // Copy sidecar files + const sidecarResult = copyAgentSidecarFiles(path.dirname(agentFile), agentSidecarDir, agentFile); + + if (sidecarResult.copied.length > 0) { + console.log(chalk.dim(` Copied ${sidecarResult.copied.length} sidecar file(s) to: ${agentSidecarDir}`)); + } + if (sidecarResult.preserved.length > 0) { + console.log(chalk.dim(` Preserved ${sidecarResult.preserved.length} existing sidecar file(s)`)); + } + } + + // Track the file + if (fileTrackingCallback) { + fileTrackingCallback(targetMdPath); + } + + console.log( + chalk.dim( + ` Compiled agent: ${agentName} -> ${path.relative(targetAgentsPath, targetMdPath)}${hasSidecar ? ' (with sidecar)' : ''}`, + ), + ); + } catch (error) { + console.warn(chalk.yellow(` Failed to compile agent ${agentName}:`, error.message)); + results.errors.push(`Failed to compile agent ${agentName}: ${error.message}`); + } + } + } +} + +module.exports = { CustomHandler }; diff --git a/tools/cli/installers/lib/ide/rovo-dev.js b/tools/cli/installers/lib/ide/rovo-dev.js index 8f460178..ecb34d4b 100644 --- a/tools/cli/installers/lib/ide/rovo-dev.js +++ b/tools/cli/installers/lib/ide/rovo-dev.js @@ -15,7 +15,7 @@ const { TaskToolCommandGenerator } = require('./shared/task-tool-command-generat */ class RovoDevSetup extends BaseIdeSetup { constructor() { - super('rovo-dev', 'Atlassian Rovo Dev', true); // preferred IDE + super('rovo-dev', 'Atlassian Rovo Dev', false); this.configDir = '.rovodev'; this.subagentsDir = 'subagents'; this.workflowsDir = 'workflows'; diff --git a/tools/cli/installers/lib/ide/shared/agent-command-generator.js b/tools/cli/installers/lib/ide/shared/agent-command-generator.js index d296c4ea..10c4e34f 100644 --- a/tools/cli/installers/lib/ide/shared/agent-command-generator.js +++ b/tools/cli/installers/lib/ide/shared/agent-command-generator.js @@ -28,11 +28,13 @@ class AgentCommandGenerator { for (const agent of agents) { const launcherContent = await this.generateLauncherContent(agent); + // Use relativePath if available (for nested agents), otherwise just name with .md + const agentPathInModule = agent.relativePath || `${agent.name}.md`; artifacts.push({ type: 'agent-launcher', module: agent.module, name: agent.name, - relativePath: path.join(agent.module, 'agents', `${agent.name}.md`), + relativePath: path.join(agent.module, 'agents', agentPathInModule), content: launcherContent, sourcePath: agent.path, }); @@ -56,9 +58,12 @@ class AgentCommandGenerator { const template = await fs.readFile(this.templatePath, 'utf8'); // Replace template variables + // Use relativePath if available (for nested agents), otherwise just name with .md + const agentPathInModule = agent.relativePath || `${agent.name}.md`; return template .replaceAll('{{name}}', agent.name) .replaceAll('{{module}}', agent.module) + .replaceAll('{{path}}', agentPathInModule) .replaceAll('{{description}}', agent.description || `${agent.name} agent`) .replaceAll('{bmad_folder}', this.bmadFolderName) .replaceAll('{*bmad_folder*}', '{bmad_folder}'); diff --git a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js index d05b985e..eb190589 100644 --- a/tools/cli/installers/lib/ide/shared/bmad-artifacts.js +++ b/tools/cli/installers/lib/ide/shared/bmad-artifacts.js @@ -76,46 +76,51 @@ async function getTasksFromBmad(bmadDir, selectedModules = []) { return tasks; } -async function getAgentsFromDir(dirPath, moduleName) { +async function getAgentsFromDir(dirPath, moduleName, relativePath = '') { const agents = []; if (!(await fs.pathExists(dirPath))) { return agents; } - const files = await fs.readdir(dirPath); + const entries = await fs.readdir(dirPath, { withFileTypes: true }); - for (const file of files) { - if (!file.endsWith('.md')) { - continue; + for (const entry of entries) { + const fullPath = path.join(dirPath, entry.name); + const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name; + + if (entry.isDirectory()) { + // Recurse into subdirectories + const subDirAgents = await getAgentsFromDir(fullPath, moduleName, newRelativePath); + agents.push(...subDirAgents); + } else if (entry.name.endsWith('.md')) { + // Skip README files and other non-agent files + if (entry.name.toLowerCase() === 'readme.md' || entry.name.toLowerCase().startsWith('readme-')) { + continue; + } + + if (entry.name.includes('.customize.')) { + continue; + } + + const content = await fs.readFile(fullPath, 'utf8'); + + if (content.includes('localskip="true"')) { + continue; + } + + // Only include files that have agent-specific content (compiled agents have tag) + if (!content.includes(' tag) - if (!content.includes(' -1. LOAD the FULL agent file from @{bmad_folder}/{{module}}/agents/{{name}}.md +1. LOAD the FULL agent file from @{bmad_folder}/{{module}}/agents/{{path}} 2. READ its entire contents - this contains the complete agent persona, menu, and instructions 3. Execute ALL activation steps exactly as written in the agent file 4. Follow the agent's persona and menu system precisely diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js index f644991e..3829968b 100644 --- a/tools/cli/installers/lib/modules/manager.js +++ b/tools/cli/installers/lib/modules/manager.js @@ -22,11 +22,12 @@ const { getProjectRoot, getSourcePath, getModulePath } = require('../../../lib/p * await manager.install('core-module', '/path/to/bmad'); */ class ModuleManager { - constructor() { + constructor(options = {}) { // Path to source modules directory this.modulesSourcePath = getSourcePath('modules'); this.xmlHandler = new XmlHandler(); this.bmadFolderName = 'bmad'; // Default, can be overridden + this.scanProjectForModules = options.scanProjectForModules !== false; // Default to true for backward compatibility } /** @@ -37,6 +38,14 @@ class ModuleManager { this.bmadFolderName = bmadFolderName; } + /** + * Set the core configuration for access during module installation + * @param {Object} coreConfig - Core configuration object + */ + setCoreConfig(coreConfig) { + this.coreConfig = coreConfig; + } + /** * Copy a file and replace {bmad_folder} placeholder with actual folder name * @param {string} sourcePath - Source file path @@ -98,62 +107,297 @@ class ModuleManager { } /** - * List all available modules - * @returns {Array} List of available modules with metadata + * Find all modules in the project by searching for module.yaml files + * @returns {Array} List of module paths */ - async listAvailable() { - const modules = []; + async findModulesInProject() { + const projectRoot = getProjectRoot(); + const modulePaths = new Set(); - if (!(await fs.pathExists(this.modulesSourcePath))) { - console.warn(chalk.yellow('Warning: src/modules directory not found')); - return modules; - } + // Helper function to recursively scan directories + async function scanDirectory(dir, excludePaths = []) { + try { + const entries = await fs.readdir(dir, { withFileTypes: true }); - const entries = await fs.readdir(this.modulesSourcePath, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); - for (const entry of entries) { - if (entry.isDirectory()) { - const modulePath = path.join(this.modulesSourcePath, entry.name); - // Check for new structure first - const installerConfigPath = path.join(modulePath, '_module-installer', 'install-config.yaml'); - // Fallback to old structure - const configPath = path.join(modulePath, 'config.yaml'); + // Skip hidden directories, node_modules, and literal placeholder directories + if ( + entry.name.startsWith('.') || + entry.name === 'node_modules' || + entry.name === 'dist' || + entry.name === 'build' || + entry.name === '{project-root}' + ) { + continue; + } - const moduleInfo = { - id: entry.name, - path: modulePath, - name: entry.name.toUpperCase(), - description: 'BMAD Module', - version: '5.0.0', - }; + // Skip excluded paths + if (excludePaths.some((exclude) => fullPath.startsWith(exclude))) { + continue; + } - // Try to read module config for metadata (prefer new location) - const configToRead = (await fs.pathExists(installerConfigPath)) ? installerConfigPath : configPath; - if (await fs.pathExists(configToRead)) { - try { - const configContent = await fs.readFile(configToRead, 'utf8'); - const config = yaml.load(configContent); - - // Use the code property as the id if available - if (config.code) { - moduleInfo.id = config.code; + if (entry.isDirectory()) { + // Skip core module - it's always installed first and not selectable + if (entry.name === 'core') { + continue; } - moduleInfo.name = config.name || moduleInfo.name; - moduleInfo.description = config.description || moduleInfo.description; - moduleInfo.version = config.version || moduleInfo.version; - moduleInfo.dependencies = config.dependencies || []; - moduleInfo.defaultSelected = config.default_selected === undefined ? false : config.default_selected; - } catch (error) { - console.warn(`Failed to read config for ${entry.name}:`, error.message); + // Check if this directory contains a module (module.yaml OR custom.yaml) + const moduleConfigPath = path.join(fullPath, 'module.yaml'); + const installerConfigPath = path.join(fullPath, '_module-installer', 'module.yaml'); + const customConfigPath = path.join(fullPath, '_module-installer', 'custom.yaml'); + const rootCustomConfigPath = path.join(fullPath, 'custom.yaml'); + + if ( + (await fs.pathExists(moduleConfigPath)) || + (await fs.pathExists(installerConfigPath)) || + (await fs.pathExists(customConfigPath)) || + (await fs.pathExists(rootCustomConfigPath)) + ) { + modulePaths.add(fullPath); + // Don't scan inside modules - they might have their own nested structures + continue; + } + + // Recursively scan subdirectories + await scanDirectory(fullPath, excludePaths); } } - - modules.push(moduleInfo); + } catch { + // Ignore errors (e.g., permission denied) } } - return modules; + // Scan the entire project, but exclude src/modules since we handle it separately + await scanDirectory(projectRoot, [this.modulesSourcePath]); + + return [...modulePaths]; + } + + /** + * List all available modules (excluding core which is always installed) + * @returns {Object} Object with modules array and customModules array + */ + async listAvailable() { + const modules = []; + const customModules = []; + + // First, scan src/modules (the standard location) + if (await fs.pathExists(this.modulesSourcePath)) { + const entries = await fs.readdir(this.modulesSourcePath, { withFileTypes: true }); + + for (const entry of entries) { + if (entry.isDirectory()) { + const modulePath = path.join(this.modulesSourcePath, entry.name); + // Check for module structure (module.yaml OR custom.yaml) + const moduleConfigPath = path.join(modulePath, 'module.yaml'); + const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml'); + const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml'); + + // Skip if this doesn't look like a module + if ( + !(await fs.pathExists(moduleConfigPath)) && + !(await fs.pathExists(installerConfigPath)) && + !(await fs.pathExists(customConfigPath)) + ) { + continue; + } + + // Skip core module - it's always installed first and not selectable + if (entry.name === 'core') { + continue; + } + + const moduleInfo = await this.getModuleInfo(modulePath, entry.name, 'src/modules'); + if (moduleInfo) { + modules.push(moduleInfo); + } + } + } + } + + // Then, find all other modules in the project (only if scanning is enabled) + if (this.scanProjectForModules) { + const otherModulePaths = await this.findModulesInProject(); + for (const modulePath of otherModulePaths) { + const moduleName = path.basename(modulePath); + const relativePath = path.relative(getProjectRoot(), modulePath); + + // Skip core module - it's always installed first and not selectable + if (moduleName === 'core') { + continue; + } + + const moduleInfo = await this.getModuleInfo(modulePath, moduleName, relativePath); + if (moduleInfo && !modules.some((m) => m.id === moduleInfo.id) && !customModules.some((m) => m.id === moduleInfo.id)) { + // Avoid duplicates - skip if we already have this module ID + if (moduleInfo.isCustom) { + customModules.push(moduleInfo); + } else { + modules.push(moduleInfo); + } + } + } + + // Also check for cached custom modules in _cfg/custom/ + if (this.bmadDir) { + const customCacheDir = path.join(this.bmadDir, '_cfg', 'custom'); + if (await fs.pathExists(customCacheDir)) { + const cacheEntries = await fs.readdir(customCacheDir, { withFileTypes: true }); + for (const entry of cacheEntries) { + if (entry.isDirectory()) { + const cachePath = path.join(customCacheDir, entry.name); + const moduleInfo = await this.getModuleInfo(cachePath, entry.name, '_cfg/custom'); + if (moduleInfo && !modules.some((m) => m.id === moduleInfo.id) && !customModules.some((m) => m.id === moduleInfo.id)) { + moduleInfo.isCustom = true; + moduleInfo.fromCache = true; + customModules.push(moduleInfo); + } + } + } + } + } + } + + return { modules, customModules }; + } + + /** + * Get module information from a module path + * @param {string} modulePath - Path to the module directory + * @param {string} defaultName - Default name for the module + * @param {string} sourceDescription - Description of where the module was found + * @returns {Object|null} Module info or null if not a valid module + */ + async getModuleInfo(modulePath, defaultName, sourceDescription) { + // Check for module structure (module.yaml OR custom.yaml) + const moduleConfigPath = path.join(modulePath, 'module.yaml'); + const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml'); + const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml'); + const rootCustomConfigPath = path.join(modulePath, 'custom.yaml'); + let configPath = null; + + if (await fs.pathExists(moduleConfigPath)) { + configPath = moduleConfigPath; + } else if (await fs.pathExists(installerConfigPath)) { + configPath = installerConfigPath; + } else if (await fs.pathExists(customConfigPath)) { + configPath = customConfigPath; + } else if (await fs.pathExists(rootCustomConfigPath)) { + configPath = rootCustomConfigPath; + } + + // Skip if this doesn't look like a module + if (!configPath) { + return null; + } + + // Mark as custom if it's using custom.yaml OR if it's outside src/modules + const isCustomSource = sourceDescription !== 'src/modules'; + const moduleInfo = { + id: defaultName, + path: modulePath, + name: defaultName + .split('-') + .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) + .join(' '), + description: 'BMAD Module', + version: '5.0.0', + source: sourceDescription, + isCustom: configPath === customConfigPath || configPath === rootCustomConfigPath || isCustomSource, + }; + + // Read module config for metadata + try { + const configContent = await fs.readFile(configPath, 'utf8'); + const config = yaml.load(configContent); + + // Use the code property as the id if available + if (config.code) { + moduleInfo.id = config.code; + } + + moduleInfo.name = config.name || moduleInfo.name; + moduleInfo.description = config.description || moduleInfo.description; + moduleInfo.version = config.version || moduleInfo.version; + moduleInfo.dependencies = config.dependencies || []; + moduleInfo.defaultSelected = config.default_selected === undefined ? false : config.default_selected; + } catch (error) { + console.warn(`Failed to read config for ${defaultName}:`, error.message); + } + + return moduleInfo; + } + + /** + * Find the source path for a module by searching all possible locations + * @param {string} moduleName - Name of the module to find + * @returns {string|null} Path to the module source or null if not found + */ + async findModuleSource(moduleName) { + const projectRoot = getProjectRoot(); + + // First, check src/modules + const srcModulePath = path.join(this.modulesSourcePath, moduleName); + if (await fs.pathExists(srcModulePath)) { + // Check if this looks like a module (has module.yaml) + const moduleConfigPath = path.join(srcModulePath, 'module.yaml'); + const installerConfigPath = path.join(srcModulePath, '_module-installer', 'module.yaml'); + + if ((await fs.pathExists(moduleConfigPath)) || (await fs.pathExists(installerConfigPath))) { + return srcModulePath; + } + + // Also check for custom.yaml in src/modules/_module-installer + const customConfigPath = path.join(srcModulePath, '_module-installer', 'custom.yaml'); + if (await fs.pathExists(customConfigPath)) { + return srcModulePath; + } + } + + // If not found in src/modules, search the entire project + const allModulePaths = await this.findModulesInProject(); + for (const modulePath of allModulePaths) { + if (path.basename(modulePath) === moduleName) { + return modulePath; + } + } + + // Also check by module ID (not just folder name) + // Need to read configs to match by ID + for (const modulePath of allModulePaths) { + const moduleConfigPath = path.join(modulePath, 'module.yaml'); + const installerConfigPath = path.join(modulePath, '_module-installer', 'module.yaml'); + const customConfigPath = path.join(modulePath, '_module-installer', 'custom.yaml'); + const rootCustomConfigPath = path.join(modulePath, 'custom.yaml'); + + let configPath = null; + if (await fs.pathExists(moduleConfigPath)) { + configPath = moduleConfigPath; + } else if (await fs.pathExists(installerConfigPath)) { + configPath = installerConfigPath; + } else if (await fs.pathExists(customConfigPath)) { + configPath = customConfigPath; + } else if (await fs.pathExists(rootCustomConfigPath)) { + configPath = rootCustomConfigPath; + } + + if (configPath) { + try { + const configContent = await fs.readFile(configPath, 'utf8'); + const config = yaml.load(configContent); + if (config.code === moduleName) { + return modulePath; + } + } catch { + // Skip if can't read config + } + } + } + + return null; } /** @@ -167,12 +411,41 @@ class ModuleManager { * @param {Object} options.logger - Logger instance for output */ async install(moduleName, bmadDir, fileTrackingCallback = null, options = {}) { - const sourcePath = path.join(this.modulesSourcePath, moduleName); + const sourcePath = await this.findModuleSource(moduleName); const targetPath = path.join(bmadDir, moduleName); // Check if source module exists - if (!(await fs.pathExists(sourcePath))) { - throw new Error(`Module '${moduleName}' not found in ${this.modulesSourcePath}`); + if (!sourcePath) { + throw new Error(`Module '${moduleName}' not found in any source location`); + } + + // Check if this is a custom module and read its custom.yaml values + let customConfig = null; + const rootCustomConfigPath = path.join(sourcePath, 'custom.yaml'); + const moduleInstallerCustomPath = path.join(sourcePath, '_module-installer', 'custom.yaml'); + + if (await fs.pathExists(rootCustomConfigPath)) { + try { + const customContent = await fs.readFile(rootCustomConfigPath, 'utf8'); + customConfig = yaml.load(customContent); + } catch (error) { + console.warn(chalk.yellow(`Warning: Failed to read custom.yaml for ${moduleName}:`, error.message)); + } + } else if (await fs.pathExists(moduleInstallerCustomPath)) { + try { + const customContent = await fs.readFile(moduleInstallerCustomPath, 'utf8'); + customConfig = yaml.load(customContent); + } catch (error) { + console.warn(chalk.yellow(`Warning: Failed to read custom.yaml for ${moduleName}:`, error.message)); + } + } + + // If this is a custom module, merge its values into the module config + if (customConfig) { + options.moduleConfig = { ...options.moduleConfig, ...customConfig }; + if (options.logger) { + options.logger.log(chalk.cyan(` Merged custom configuration for ${moduleName}`)); + } } // Check if already installed @@ -188,6 +461,9 @@ class ModuleManager { // Copy module files with filtering await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig); + // Compile any .agent.yaml files to .md format + await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir); + // Process agent files to inject activation block await this.processAgentFiles(targetPath, moduleName); @@ -210,12 +486,12 @@ class ModuleManager { * @param {boolean} force - Force update (overwrite modifications) */ async update(moduleName, bmadDir, force = false) { - const sourcePath = path.join(this.modulesSourcePath, moduleName); + const sourcePath = await this.findModuleSource(moduleName); const targetPath = path.join(bmadDir, moduleName); // Check if source module exists - if (!(await fs.pathExists(sourcePath))) { - throw new Error(`Module '${moduleName}' not found in source`); + if (!sourcePath) { + throw new Error(`Module '${moduleName}' not found in any source location`); } // Check if module is installed @@ -330,13 +606,29 @@ class ModuleManager { continue; } + // Skip sidecar directories - they are handled separately during agent compilation + if ( + path + .dirname(file) + .split('/') + .some((dir) => dir.toLowerCase().includes('sidecar')) + ) { + continue; + } + // Skip _module-installer directory - it's only needed at install time - if (file.startsWith('_module-installer/')) { + if (file.startsWith('_module-installer/') || file === 'module.yaml') { continue; } // Skip config.yaml templates - we'll generate clean ones with actual values - if (file === 'config.yaml' || file.endsWith('/config.yaml')) { + // Also skip custom.yaml files - their values will be merged into core config + if (file === 'config.yaml' || file.endsWith('/config.yaml') || file === 'custom.yaml' || file.endsWith('/custom.yaml')) { + continue; + } + + // Skip .agent.yaml files - they will be compiled separately + if (file.endsWith('.agent.yaml')) { continue; } @@ -482,6 +774,157 @@ class ModuleManager { } } + /** + * Compile .agent.yaml files to .md format in modules + * @param {string} sourcePath - Source module path + * @param {string} targetPath - Target module path + * @param {string} moduleName - Module name + * @param {string} bmadDir - BMAD installation directory + */ + async compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir) { + const sourceAgentsPath = path.join(sourcePath, 'agents'); + const targetAgentsPath = path.join(targetPath, 'agents'); + const cfgAgentsDir = path.join(bmadDir, '_cfg', 'agents'); + + // Check if agents directory exists in source + if (!(await fs.pathExists(sourceAgentsPath))) { + return; // No agents to compile + } + + // Get all agent YAML files recursively + const agentFiles = await this.findAgentFiles(sourceAgentsPath); + + for (const agentFile of agentFiles) { + if (!agentFile.endsWith('.agent.yaml')) continue; + + const relativePath = path.relative(sourceAgentsPath, agentFile); + const targetDir = path.join(targetAgentsPath, path.dirname(relativePath)); + + await fs.ensureDir(targetDir); + + const agentName = path.basename(agentFile, '.agent.yaml'); + const sourceYamlPath = agentFile; + const targetMdPath = path.join(targetDir, `${agentName}.md`); + const customizePath = path.join(cfgAgentsDir, `${moduleName}-${agentName}.customize.yaml`); + + // Read and compile the YAML + try { + const yamlContent = await fs.readFile(sourceYamlPath, 'utf8'); + const { compileAgent } = require('../../../lib/agent/compiler'); + + // Create customize template if it doesn't exist + if (!(await fs.pathExists(customizePath))) { + const { getSourcePath } = require('../../../lib/project-root'); + const genericTemplatePath = getSourcePath('utility', 'templates', 'agent.customize.template.yaml'); + if (await fs.pathExists(genericTemplatePath)) { + await this.copyFileWithPlaceholderReplacement(genericTemplatePath, customizePath); + console.log(chalk.dim(` Created customize: ${moduleName}-${agentName}.customize.yaml`)); + } + } + + // Check for customizations + let customizedFields = []; + if (await fs.pathExists(customizePath)) { + const customizeContent = await fs.readFile(customizePath, 'utf8'); + const customizeData = yaml.load(customizeContent); + customizedFields = customizeData.customized_fields || []; + } + + // Load core config to get agent_sidecar_folder + const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml'); + let coreConfig = {}; + + if (await fs.pathExists(coreConfigPath)) { + const yamlLib = require('yaml'); + const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8'); + coreConfig = yamlLib.parse(coreConfigContent); + } + + // Check if agent has sidecar + let hasSidecar = false; + try { + const yamlLib = require('yaml'); + const agentYaml = yamlLib.parse(yamlContent); + hasSidecar = agentYaml?.agent?.metadata?.hasSidecar === true; + } catch { + // Continue without sidecar processing + } + + // Compile with customizations if any + const { xml } = compileAgent(yamlContent, {}, agentName, relativePath, { config: this.coreConfig }); + + // Replace {bmad_folder} placeholder if needed + if (xml.includes('{bmad_folder}') && this.bmadFolderName) { + const processedXml = xml.replaceAll('{bmad_folder}', this.bmadFolderName); + await fs.writeFile(targetMdPath, processedXml, 'utf8'); + } else { + await fs.writeFile(targetMdPath, xml, 'utf8'); + } + + // Copy sidecar files if agent has hasSidecar flag + if (hasSidecar) { + const { copyAgentSidecarFiles } = require('../../../lib/agent/installer'); + + // Get agent sidecar folder from core config (should always be set) + const agentSidecarFolder = this.coreConfig?.agent_sidecar_folder; + + // Resolve path variables + const projectDir = path.dirname(bmadDir); + const resolvedSidecarFolder = agentSidecarFolder + .replaceAll('{project-root}', projectDir) + .replaceAll('{bmad_folder}', path.basename(bmadDir)); + + // Create sidecar directory for this agent + const agentSidecarDir = path.join(resolvedSidecarFolder, agentName); + await fs.ensureDir(agentSidecarDir); + + // Copy sidecar files (preserve existing, add new) + const sidecarResult = copyAgentSidecarFiles(path.dirname(sourceYamlPath), agentSidecarDir, sourceYamlPath); + const totalFiles = sidecarResult.copied.length + sidecarResult.preserved.length; + + if (sidecarResult.copied.length > 0) { + console.log(chalk.dim(` Copied ${sidecarResult.copied.length} new sidecar file(s) to: ${agentSidecarDir}`)); + } + if (sidecarResult.preserved.length > 0) { + console.log(chalk.dim(` Preserved ${sidecarResult.preserved.length} existing sidecar file(s)`)); + } + } + + console.log( + chalk.dim(` Compiled agent: ${agentName} -> ${path.relative(targetPath, targetMdPath)}${hasSidecar ? ' (with sidecar)' : ''}`), + ); + } catch (error) { + console.warn(chalk.yellow(` Failed to compile agent ${agentName}:`, error.message)); + } + } + } + + /** + * Find all .agent.yaml files recursively in a directory + * @param {string} dir - Directory to search + * @returns {Array} List of .agent.yaml file paths + */ + async findAgentFiles(dir) { + const agentFiles = []; + + async function searchDirectory(searchDir) { + const entries = await fs.readdir(searchDir, { withFileTypes: true }); + + for (const entry of entries) { + const fullPath = path.join(searchDir, entry.name); + + if (entry.isFile() && entry.name.endsWith('.agent.yaml')) { + agentFiles.push(fullPath); + } else if (entry.isDirectory()) { + await searchDirectory(fullPath); + } + } + } + + await searchDirectory(dir); + return agentFiles; + } + /** * Process agent files to inject activation block * @param {string} modulePath - Path to installed module @@ -495,24 +938,49 @@ class ModuleManager { return; // No agents to process } - // Get all agent files - const agentFiles = await fs.readdir(agentsPath); + // Get all agent MD files recursively + const agentFiles = await this.findAgentMdFiles(agentsPath); for (const agentFile of agentFiles) { if (!agentFile.endsWith('.md')) continue; - const agentPath = path.join(agentsPath, agentFile); - let content = await fs.readFile(agentPath, 'utf8'); + let content = await fs.readFile(agentFile, 'utf8'); // Check if content has agent XML and no activation block if (content.includes(' word.charAt(0).toUpperCase() + word.slice(1)) - .join(' '); - agentYaml.agent.metadata.name = titleCaseName; - } + // Note: agentName parameter is for UI display only, not for modifying the YAML + // The persona name (metadata.name) should always come from the YAML file + // We should NEVER modify metadata.name as it's part of the agent's identity // Extract install_config const installConfig = extractInstallConfig(agentYaml); @@ -466,14 +459,22 @@ function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = '' finalAnswers = { ...defaults, ...answers }; } + // Add agent_sidecar_folder to answers if provided in config + if (options.config && options.config.agent_sidecar_folder) { + finalAnswers.agent_sidecar_folder = options.config.agent_sidecar_folder; + } + // Process templates with answers const processedYaml = processAgentYaml(agentYaml, finalAnswers); // Strip install_config from output const cleanYaml = stripInstallConfig(processedYaml); - // Compile to XML - const xml = compileToXml(cleanYaml, agentName, targetPath); + // Replace {agent_sidecar_folder} in XML content + let xml = compileToXml(cleanYaml, agentName, targetPath); + if (finalAnswers.agent_sidecar_folder) { + xml = xml.replaceAll('{agent_sidecar_folder}', finalAnswers.agent_sidecar_folder); + } return { xml, @@ -482,10 +483,39 @@ function compileAgent(yamlContent, answers = {}, agentName = '', targetPath = '' }; } +/** + * Process TTS injection markers in content + * @param {string} content - Content to process + * @param {boolean} enableAgentVibes - Whether AgentVibes is enabled + * @returns {Object} { content: string, hadInjection: boolean } + */ +function processTTSInjectionPoints(content, enableAgentVibes) { + const hasAgentTTS = content.includes(''); + + if (enableAgentVibes && hasAgentTTS) { + // Replace agent-tts injection marker with TTS rule + content = content.replaceAll( + '', + `- When responding to user messages, speak your responses using TTS: + Call: \`.claude/hooks/bmad-speak.sh '{agent-id}' '{response-text}'\` after each response + Replace {agent-id} with YOUR agent ID from tag at top of this file + Replace {response-text} with the text you just output to the user + IMPORTANT: Use single quotes as shown - do NOT escape special characters like ! or $ inside single quotes + Run in background (&) to avoid blocking`, + ); + return { content, hadInjection: true }; + } else if (!enableAgentVibes && hasAgentTTS) { + // Strip injection markers when disabled + content = content.replaceAll(/\n?/g, ''); + } + + return { content, hadInjection: false }; +} + /** * Compile agent file to .md * @param {string} yamlPath - Path to agent YAML file - * @param {Object} options - { answers: {}, outputPath: string } + * @param {Object} options - { answers: {}, outputPath: string, enableAgentVibes: boolean } * @returns {Object} Compilation result */ function compileAgentFile(yamlPath, options = {}) { @@ -501,13 +531,24 @@ function compileAgentFile(yamlPath, options = {}) { outputPath = path.join(dir, `${basename}.md`); } + // Process TTS injection points if enableAgentVibes option is provided + let xml = result.xml; + let ttsInjected = false; + if (options.enableAgentVibes !== undefined) { + const ttsResult = processTTSInjectionPoints(xml, options.enableAgentVibes); + xml = ttsResult.content; + ttsInjected = ttsResult.hadInjection; + } + // Write compiled XML - fs.writeFileSync(outputPath, result.xml, 'utf8'); + fs.writeFileSync(outputPath, xml, 'utf8'); return { ...result, + xml, outputPath, sourcePath: yamlPath, + ttsInjected, }; } diff --git a/tools/cli/lib/agent/installer.js b/tools/cli/lib/agent/installer.js index 7e3b364d..2c9e30eb 100644 --- a/tools/cli/lib/agent/installer.js +++ b/tools/cli/lib/agent/installer.js @@ -46,7 +46,7 @@ function resolvePath(pathStr, context) { } /** - * Discover available agents in the custom agent location + * Discover available agents in the custom agent location recursively * @param {string} searchPath - Path to search for agents * @returns {Array} List of agent info objects */ @@ -56,35 +56,58 @@ function discoverAgents(searchPath) { } const agents = []; - const entries = fs.readdirSync(searchPath, { withFileTypes: true }); - for (const entry of entries) { - const fullPath = path.join(searchPath, entry.name); + // Helper function to recursively search + function searchDirectory(dir, relativePath = '') { + const entries = fs.readdirSync(dir, { withFileTypes: true }); - if (entry.isFile() && entry.name.endsWith('.agent.yaml')) { - // Simple agent (single file) - agents.push({ - type: 'simple', - name: entry.name.replace('.agent.yaml', ''), - path: fullPath, - yamlFile: fullPath, - }); - } else if (entry.isDirectory()) { - // Check for agent with sidecar (folder containing .agent.yaml) - const yamlFiles = fs.readdirSync(fullPath).filter((f) => f.endsWith('.agent.yaml')); - if (yamlFiles.length === 1) { - const agentYamlPath = path.join(fullPath, yamlFiles[0]); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + const agentRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name; + + if (entry.isFile() && entry.name.endsWith('.agent.yaml')) { + // Simple agent (single file) + // The agent name is based on the filename + const agentName = entry.name.replace('.agent.yaml', ''); agents.push({ - type: 'expert', - name: entry.name, + type: 'simple', + name: agentName, path: fullPath, - yamlFile: agentYamlPath, - hasSidecar: true, + yamlFile: fullPath, + relativePath: agentRelativePath.replace('.agent.yaml', ''), }); + } else if (entry.isDirectory()) { + // Check if this directory contains an .agent.yaml file + try { + const dirContents = fs.readdirSync(fullPath); + const yamlFiles = dirContents.filter((f) => f.endsWith('.agent.yaml')); + + if (yamlFiles.length > 0) { + // Found .agent.yaml files in this directory + for (const yamlFile of yamlFiles) { + const agentYamlPath = path.join(fullPath, yamlFile); + const agentName = path.basename(yamlFile, '.agent.yaml'); + + agents.push({ + type: 'expert', + name: agentName, + path: fullPath, + yamlFile: agentYamlPath, + relativePath: agentRelativePath, + }); + } + } else { + // No .agent.yaml in this directory, recurse deeper + searchDirectory(fullPath, agentRelativePath); + } + } catch { + // Skip directories we can't read + } } } } + searchDirectory(searchPath); return agents; } @@ -103,12 +126,15 @@ function loadAgentConfig(yamlPath) { // These take precedence over defaults const savedAnswers = agentYaml?.saved_answers || {}; + const metadata = agentYaml?.agent?.metadata || {}; + return { yamlContent: content, agentYaml, installConfig, defaults: { ...defaults, ...savedAnswers }, // saved_answers override defaults - metadata: agentYaml?.agent?.metadata || {}, + metadata, + hasSidecar: metadata.hasSidecar === true, }; } @@ -208,14 +234,16 @@ async function promptInstallQuestions(installConfig, defaults, presetAnswers = { * @param {Object} agentInfo - Agent discovery info * @param {Object} answers - User answers for install_config * @param {string} targetPath - Target installation directory + * @param {Object} options - Additional options including config * @returns {Object} Installation result */ -function installAgent(agentInfo, answers, targetPath) { +function installAgent(agentInfo, answers, targetPath, options = {}) { // Compile the agent const { xml, metadata, processedYaml } = compileAgent(fs.readFileSync(agentInfo.yamlFile, 'utf8'), answers); // Determine target agent folder name - const agentFolderName = metadata.name ? metadata.name.toLowerCase().replaceAll(/\s+/g, '-') : agentInfo.name; + // Use the folder name from agentInfo, NOT the persona name from metadata + const agentFolderName = agentInfo.name; const agentTargetDir = path.join(targetPath, agentFolderName); @@ -237,11 +265,27 @@ function installAgent(agentInfo, answers, targetPath) { sidecarCopied: false, }; - // Copy sidecar files for expert agents - if (agentInfo.hasSidecar && agentInfo.type === 'expert') { - const sidecarFiles = copySidecarFiles(agentInfo.path, agentTargetDir, agentInfo.yamlFile); + // Handle sidecar files for agents with hasSidecar flag + if (agentInfo.hasSidecar === true && agentInfo.type === 'expert') { + // Get agent sidecar folder from config or use default + const agentSidecarFolder = options.config?.agent_sidecar_folder || '{project-root}/.myagent-data'; + + // Resolve path variables + const resolvedSidecarFolder = agentSidecarFolder + .replaceAll('{project-root}', options.projectRoot || process.cwd()) + .replaceAll('{bmad_folder}', options.bmadFolder || '.bmad'); + + // Create sidecar directory for this agent + const agentSidecarDir = path.join(resolvedSidecarFolder, agentFolderName); + if (!fs.existsSync(agentSidecarDir)) { + fs.mkdirSync(agentSidecarDir, { recursive: true }); + } + + // Find and copy sidecar folder + const sidecarFiles = copyAgentSidecarFiles(agentInfo.path, agentSidecarDir, agentInfo.yamlFile); result.sidecarCopied = true; result.sidecarFiles = sidecarFiles; + result.sidecarDir = agentSidecarDir; } return result; @@ -285,6 +329,62 @@ function copySidecarFiles(sourceDir, targetDir, excludeYaml) { return copied; } +/** + * Find and copy agent sidecar folders + * @param {string} sourceDir - Source agent directory + * @param {string} targetSidecarDir - Target sidecar directory for the agent + * @param {string} excludeYaml - The .agent.yaml file to exclude + * @returns {Array} List of copied files + */ +function copyAgentSidecarFiles(sourceDir, targetSidecarDir, excludeYaml) { + const copied = []; + const preserved = []; + + // Find folders with "sidecar" in the name + const entries = fs.readdirSync(sourceDir, { withFileTypes: true }); + + for (const entry of entries) { + if (entry.isDirectory() && entry.name.toLowerCase().includes('sidecar')) { + const sidecarSourcePath = path.join(sourceDir, entry.name); + + // Recursively sync the sidecar folder contents (preserve existing, add new) + function syncSidecarDir(src, dest) { + if (!fs.existsSync(dest)) { + fs.mkdirSync(dest, { recursive: true }); + } + + // Get all files in source + const sourceEntries = fs.readdirSync(src, { withFileTypes: true }); + + for (const sourceEntry of sourceEntries) { + const srcPath = path.join(src, sourceEntry.name); + const destPath = path.join(dest, sourceEntry.name); + + if (sourceEntry.isDirectory()) { + // Recursively sync subdirectories + syncSidecarDir(srcPath, destPath); + } else { + // Check if file already exists in destination + if (fs.existsSync(destPath)) { + // File exists - preserve it + preserved.push(destPath); + } else { + // File doesn't exist - copy it + fs.copyFileSync(srcPath, destPath); + copied.push(destPath); + } + } + } + } + + syncSidecarDir(sidecarSourcePath, targetSidecarDir); + } + } + + // Return info about what was preserved and what was copied + return { copied, preserved }; +} + /** * Update agent metadata ID to reflect installed location * @param {string} compiledContent - Compiled XML content @@ -721,6 +821,7 @@ module.exports = { promptInstallQuestions, installAgent, copySidecarFiles, + copyAgentSidecarFiles, updateAgentId, detectBmadProject, addToManifest, diff --git a/tools/cli/lib/cli-utils.js b/tools/cli/lib/cli-utils.js index 57489970..da193363 100644 --- a/tools/cli/lib/cli-utils.js +++ b/tools/cli/lib/cli-utils.js @@ -3,6 +3,7 @@ const boxen = require('boxen'); const wrapAnsi = require('wrap-ansi'); const figlet = require('figlet'); const path = require('node:path'); +const os = require('node:os'); const CLIUtils = { /** @@ -84,8 +85,8 @@ const CLIUtils = { /** * Display module configuration header * @param {string} moduleName - Module name (fallback if no custom header) - * @param {string} header - Custom header from install-config.yaml - * @param {string} subheader - Custom subheader from install-config.yaml + * @param {string} header - Custom header from module.yaml + * @param {string} subheader - Custom subheader from module.yaml */ displayModuleConfigHeader(moduleName, header = null, subheader = null) { // Simple blue banner with custom header/subheader if provided @@ -100,8 +101,8 @@ const CLIUtils = { /** * Display module with no custom configuration * @param {string} moduleName - Module name (fallback if no custom header) - * @param {string} header - Custom header from install-config.yaml - * @param {string} subheader - Custom subheader from install-config.yaml + * @param {string} header - Custom header from module.yaml + * @param {string} subheader - Custom subheader from module.yaml */ displayModuleNoConfig(moduleName, header = null, subheader = null) { // Show full banner with header/subheader, just like modules with config @@ -205,6 +206,22 @@ const CLIUtils = { // No longer clear screen or show boxes - just a simple completion message // This is deprecated but kept for backwards compatibility }, + + /** + * Expand path with ~ expansion + * @param {string} inputPath - Path to expand + * @returns {string} Expanded path + */ + expandPath(inputPath) { + if (!inputPath) return inputPath; + + // Expand ~ to home directory + if (inputPath.startsWith('~')) { + return path.join(os.homedir(), inputPath.slice(1)); + } + + return inputPath; + }, }; module.exports = { CLIUtils }; diff --git a/tools/cli/lib/config.js b/tools/cli/lib/config.js index b3ab9cb5..1f7c2ad8 100644 --- a/tools/cli/lib/config.js +++ b/tools/cli/lib/config.js @@ -1,6 +1,7 @@ const fs = require('fs-extra'); const yaml = require('js-yaml'); const path = require('node:path'); +const packageJson = require('../../../package.json'); /** * Configuration utility class @@ -50,7 +51,7 @@ class Config { const standardReplacements = { '{project-root}': replacements.root || '', '{module}': replacements.module || '', - '{version}': replacements.version || '5.0.0', + '{version}': replacements.version || packageJson.version, '{date}': new Date().toISOString().split('T')[0], }; diff --git a/tools/cli/lib/ui.js b/tools/cli/lib/ui.js index 32e8dfc0..29b5cff7 100644 --- a/tools/cli/lib/ui.js +++ b/tools/cli/lib/ui.js @@ -59,6 +59,17 @@ class UI { const bmadDir = await installer.findBmadDir(confirmedDirectory); const hasExistingInstall = await fs.pathExists(bmadDir); + // Always ask for custom content, but we'll handle it differently for new installs + let customContentConfig = { hasCustomContent: false }; + if (hasExistingInstall) { + // Existing installation - prompt to add/update custom content + customContentConfig = await this.promptCustomContentForExisting(); + } else { + // New installation - we'll prompt after creating the directory structure + // For now, set a flag to indicate we should ask later + customContentConfig._shouldAsk = true; + } + // Track action type (only set if there's an existing installation) let actionType; @@ -85,9 +96,11 @@ class UI { // Handle quick update separately if (actionType === 'quick-update') { + // Quick update doesn't install custom content - just updates existing modules return { actionType: 'quick-update', directory: confirmedDirectory, + customContent: { hasCustomContent: false }, }; } @@ -116,8 +129,120 @@ class UI { const { installedModuleIds } = await this.getExistingInstallation(confirmedDirectory); const coreConfig = await this.collectCoreConfig(confirmedDirectory); - const moduleChoices = await this.getModuleChoices(installedModuleIds); - const selectedModules = await this.selectModules(moduleChoices); + + // For new installations, create the directory structure first so we can cache custom content + if (!hasExistingInstall && customContentConfig._shouldAsk) { + // Create the bmad directory based on core config + const path = require('node:path'); + const fs = require('fs-extra'); + const bmadFolderName = coreConfig.bmad_folder || 'bmad'; + const bmadDir = path.join(confirmedDirectory, bmadFolderName); + + await fs.ensureDir(bmadDir); + await fs.ensureDir(path.join(bmadDir, '_cfg')); + await fs.ensureDir(path.join(bmadDir, '_cfg', 'custom')); + + // Now prompt for custom content + customContentConfig = await this.promptCustomContentLocation(); + + // If custom content found, cache it + if (customContentConfig.hasCustomContent) { + const { CustomModuleCache } = require('../installers/lib/core/custom-module-cache'); + const cache = new CustomModuleCache(bmadDir); + + const { CustomHandler } = require('../installers/lib/custom/handler'); + const customHandler = new CustomHandler(); + const customFiles = await customHandler.findCustomContent(customContentConfig.customPath); + + for (const customFile of customFiles) { + const customInfo = await customHandler.getCustomInfo(customFile); + if (customInfo && customInfo.id) { + // Cache the module source + await cache.cacheModule(customInfo.id, customInfo.path, { + name: customInfo.name, + type: 'custom', + }); + + console.log(chalk.dim(` Cached ${customInfo.name} to _cfg/custom/${customInfo.id}`)); + } + } + + // Update config to use cached modules + customContentConfig.cachedModules = []; + for (const customFile of customFiles) { + const customInfo = await customHandler.getCustomInfo(customFile); + if (customInfo && customInfo.id) { + customContentConfig.cachedModules.push({ + id: customInfo.id, + cachePath: path.join(bmadDir, '_cfg', 'custom', customInfo.id), + // Store relative path from cache for the manifest + relativePath: path.join('_cfg', 'custom', customInfo.id), + }); + } + } + + console.log(chalk.green(`โœ“ Cached ${customFiles.length} custom module(s)`)); + } + + // Clear the flag + delete customContentConfig._shouldAsk; + } + + // Skip module selection during update/reinstall - keep existing modules + let selectedModules; + if (actionType === 'update' || actionType === 'reinstall') { + // Keep all existing installed modules during update/reinstall + selectedModules = [...installedModuleIds]; + console.log(chalk.cyan('\n๐Ÿ“ฆ Keeping existing modules: ') + selectedModules.join(', ')); + } else { + // Only show module selection for new installs + const moduleChoices = await this.getModuleChoices(installedModuleIds, customContentConfig); + selectedModules = await this.selectModules(moduleChoices); + + // Check which custom content items were selected + const selectedCustomContent = selectedModules.filter((mod) => mod.startsWith('__CUSTOM_CONTENT__')); + + // For cached modules (new installs), check if any cached modules were selected + let selectedCachedModules = []; + if (customContentConfig.cachedModules) { + selectedCachedModules = selectedModules.filter( + (mod) => !mod.startsWith('__CUSTOM_CONTENT__') && customContentConfig.cachedModules.some((cm) => cm.id === mod), + ); + } + + if (selectedCustomContent.length > 0 || selectedCachedModules.length > 0) { + customContentConfig.selected = true; + + // Handle directory-based custom content (existing installs) + if (selectedCustomContent.length > 0) { + customContentConfig.selectedFiles = selectedCustomContent.map((mod) => mod.replace('__CUSTOM_CONTENT__', '')); + // Convert custom content to module IDs for installation + const customContentModuleIds = []; + const { CustomHandler } = require('../installers/lib/custom/handler'); + const customHandler = new CustomHandler(); + for (const customFile of customContentConfig.selectedFiles) { + // Get the module info to extract the ID + const customInfo = await customHandler.getCustomInfo(customFile); + if (customInfo) { + customContentModuleIds.push(customInfo.id); + } + } + // Filter out custom content markers and add module IDs + selectedModules = [...selectedModules.filter((mod) => !mod.startsWith('__CUSTOM_CONTENT__')), ...customContentModuleIds]; + } + + // For cached modules, they're already module IDs, just mark as selected + if (selectedCachedModules.length > 0) { + customContentConfig.selectedCachedModules = selectedCachedModules; + // No need to filter since they're already proper module IDs + } + } else if (customContentConfig.hasCustomContent) { + // User provided custom content but didn't select any + customContentConfig.selected = false; + customContentConfig.selectedFiles = []; + customContentConfig.selectedCachedModules = []; + } + } // Prompt for AgentVibes TTS integration const agentVibesConfig = await this.promptAgentVibes(confirmedDirectory); @@ -137,7 +262,9 @@ class UI { ides: toolSelection.ides, skipIde: toolSelection.skipIde, coreConfig: coreConfig, // Pass collected core config to installer - enableAgentVibes: agentVibesConfig.enabled, // AgentVibes TTS integration + // Custom content configuration + customContent: customContentConfig, + enableAgentVibes: agentVibesConfig.enabled, agentVibesInstalled: agentVibesConfig.alreadyInstalled, }; } @@ -363,11 +490,60 @@ class UI { `๐Ÿ”ง Tools Configured: ${result.ides?.length > 0 ? result.ides.join(', ') : 'none'}`, ]; + // Add AgentVibes TTS info if enabled + if (result.agentVibesEnabled) { + summary.push(`๐ŸŽค AgentVibes TTS: Enabled`); + } + CLIUtils.displayBox(summary.join('\n\n'), { borderColor: 'green', borderStyle: 'round', }); + // Display TTS injection details if present + if (result.ttsInjectedFiles && result.ttsInjectedFiles.length > 0) { + console.log('\n' + chalk.cyan.bold('โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•')); + console.log(chalk.cyan.bold(' AgentVibes TTS Injection Summary')); + console.log(chalk.cyan.bold('โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•\n')); + + // Explain what TTS injection is + console.log(chalk.white.bold('What is TTS Injection?\n')); + console.log(chalk.dim(' TTS (Text-to-Speech) injection adds voice instructions to BMAD agents,')); + console.log(chalk.dim(' enabling them to speak their responses aloud using AgentVibes.\n')); + console.log(chalk.dim(' Example: When you activate the PM agent, it will greet you with')); + console.log(chalk.dim(' spoken audio like "Hey! I\'m your Project Manager. How can I help?"\n')); + + console.log(chalk.green(`โœ… TTS injection applied to ${result.ttsInjectedFiles.length} file(s):\n`)); + + // Group by type + const partyModeFiles = result.ttsInjectedFiles.filter((f) => f.type === 'party-mode'); + const agentTTSFiles = result.ttsInjectedFiles.filter((f) => f.type === 'agent-tts'); + + if (partyModeFiles.length > 0) { + console.log(chalk.yellow(' Party Mode (multi-agent conversations):')); + for (const file of partyModeFiles) { + console.log(chalk.dim(` โ€ข ${file.path}`)); + } + } + + if (agentTTSFiles.length > 0) { + console.log(chalk.yellow(' Agent TTS (individual agent voices):')); + for (const file of agentTTSFiles) { + console.log(chalk.dim(` โ€ข ${file.path}`)); + } + } + + // Show backup info and restore command + console.log('\n' + chalk.white.bold('Backups & Recovery:\n')); + console.log(chalk.dim(' Pre-injection backups are stored in:')); + console.log(chalk.cyan(' ~/.bmad-tts-backups/\n')); + console.log(chalk.dim(' To restore original files (removes TTS instructions):')); + console.log(chalk.cyan(` bmad-tts-injector.sh --restore ${result.path}\n`)); + + console.log(chalk.cyan('๐Ÿ’ก BMAD agents will now speak when activated!')); + console.log(chalk.dim(' Ensure AgentVibes is installed: https://agentvibes.org')); + } + console.log('\n' + chalk.green.bold('โœจ BMAD is ready to use!')); } @@ -424,19 +600,144 @@ class UI { /** * Get module choices for selection * @param {Set} installedModuleIds - Currently installed module IDs + * @param {Object} customContentConfig - Custom content configuration * @returns {Array} Module choices for inquirer */ - async getModuleChoices(installedModuleIds) { - const { ModuleManager } = require('../installers/lib/modules/manager'); - const moduleManager = new ModuleManager(); - const availableModules = await moduleManager.listAvailable(); - + async getModuleChoices(installedModuleIds, customContentConfig = null) { + const moduleChoices = []; const isNewInstallation = installedModuleIds.size === 0; - return availableModules.map((mod) => ({ - name: mod.name, - value: mod.id, - checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id), - })); + + const customContentItems = []; + const hasCustomContentItems = false; + + // Add custom content items + if (customContentConfig && customContentConfig.hasCustomContent) { + if (customContentConfig.cachedModules) { + // New installation - show cached modules + for (const cachedModule of customContentConfig.cachedModules) { + // Get the module info from cache + const yaml = require('js-yaml'); + const fs = require('fs-extra'); + + // Try multiple possible config file locations + const possibleConfigPaths = [ + path.join(cachedModule.cachePath, 'module.yaml'), + path.join(cachedModule.cachePath, 'custom.yaml'), + path.join(cachedModule.cachePath, '_module-installer', 'module.yaml'), + path.join(cachedModule.cachePath, '_module-installer', 'custom.yaml'), + ]; + + let moduleData = null; + let foundPath = null; + + for (const configPath of possibleConfigPaths) { + if (await fs.pathExists(configPath)) { + try { + const yamlContent = await fs.readFile(configPath, 'utf8'); + moduleData = yaml.load(yamlContent); + foundPath = configPath; + break; + } catch { + // Continue to next path + } + } + } + + if (moduleData) { + // Use the name from the custom info if we have it + const moduleName = cachedModule.name || moduleData.name || cachedModule.id; + + customContentItems.push({ + name: `${chalk.cyan('โœ“')} ${moduleName} ${chalk.gray('(cached)')}`, + value: cachedModule.id, // Use module ID directly + checked: true, // Default to selected + cached: true, + }); + } else { + // Debug: show what paths we tried to check + console.log(chalk.dim(`DEBUG: No module config found for ${cachedModule.id}`)); + console.log( + chalk.dim( + `DEBUG: Tried paths:`, + possibleConfigPaths.map((p) => p.replace(cachedModule.cachePath, '.')), + ), + ); + console.log(chalk.dim(`DEBUG: cachedModule:`, JSON.stringify(cachedModule, null, 2))); + } + } + } else if (customContentConfig.customPath) { + // Existing installation - show from directory + const { CustomHandler } = require('../installers/lib/custom/handler'); + const customHandler = new CustomHandler(); + const customFiles = await customHandler.findCustomContent(customContentConfig.customPath); + + for (const customFile of customFiles) { + const customInfo = await customHandler.getCustomInfo(customFile); + if (customInfo) { + customContentItems.push({ + name: `${chalk.cyan('โœ“')} ${customInfo.name} ${chalk.gray(`(${customInfo.relativePath})`)}`, + value: `__CUSTOM_CONTENT__${customFile}`, // Unique value for each custom content + checked: true, // Default to selected since user chose to provide custom content + path: customInfo.path, // Track path to avoid duplicates + }); + } + } + } + } + + // Add official modules + const { ModuleManager } = require('../installers/lib/modules/manager'); + // For new installations, don't scan project yet (will do after custom content is discovered) + // For existing installations, scan if user selected custom content + const shouldScanProject = + !isNewInstallation && customContentConfig && customContentConfig.hasCustomContent && customContentConfig.selected; + const moduleManager = new ModuleManager({ + scanProjectForModules: shouldScanProject, + }); + const { modules: availableModules, customModules: customModulesFromProject } = await moduleManager.listAvailable(); + + // First, add all items to appropriate sections + const allCustomModules = []; + + // Add custom content items from directory + allCustomModules.push(...customContentItems); + + // Add custom modules from project scan (if scanning is enabled) + for (const mod of customModulesFromProject) { + // Skip if this module is already in customContentItems (by path) + const isDuplicate = allCustomModules.some((item) => item.path && mod.path && path.resolve(item.path) === path.resolve(mod.path)); + + if (!isDuplicate) { + allCustomModules.push({ + name: `${chalk.cyan('โœ“')} ${mod.name} ${chalk.gray(`(${mod.source})`)}`, + value: mod.id, + checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id), + }); + } + } + + // Add separators and modules in correct order + if (allCustomModules.length > 0) { + // Add separator for custom content, all custom modules, and official content separator + moduleChoices.push( + new inquirer.Separator('โ”€โ”€ Custom Content โ”€โ”€'), + ...allCustomModules, + new inquirer.Separator('โ”€โ”€ Official Content โ”€โ”€'), + ); + } + + // Add official modules (only non-custom ones) + for (const mod of availableModules) { + if (!mod.isCustom) { + moduleChoices.push({ + name: mod.name, + value: mod.id, + checked: isNewInstallation ? mod.defaultSelected || false : installedModuleIds.has(mod.id), + }); + } + } + + return moduleChoices; } /** @@ -513,6 +814,116 @@ class UI { } } + /** + * Prompt for custom content location + * @returns {Object} Custom content configuration + */ + async promptCustomContentLocation() { + try { + CLIUtils.displaySection('Custom Content', 'Optional: Add custom agents, workflows, and modules'); + + const { hasCustomContent } = await inquirer.prompt([ + { + type: 'list', + name: 'hasCustomContent', + message: 'Do you have custom content to install?', + choices: [ + { name: 'No (skip custom content)', value: 'none' }, + { name: 'Enter a directory path', value: 'directory' }, + { name: 'Enter a URL', value: 'url' }, + ], + default: 'none', + }, + ]); + + if (hasCustomContent === 'none') { + return { hasCustomContent: false }; + } + + if (hasCustomContent === 'url') { + console.log(chalk.yellow('\nURL-based custom content installation is coming soon!')); + console.log(chalk.cyan('For now, please download your custom content and choose "Enter a directory path".\n')); + return { hasCustomContent: false }; + } + + if (hasCustomContent === 'directory') { + let customPath; + while (!customPath) { + let expandedPath; + const { directory } = await inquirer.prompt([ + { + type: 'input', + name: 'directory', + message: 'Enter directory to search for custom content (will scan subfolders):', + default: process.cwd(), // Use actual current working directory + validate: async (input) => { + if (!input || input.trim() === '') { + return 'Please enter a directory path'; + } + + try { + expandedPath = this.expandUserPath(input.trim()); + } catch (error) { + return error.message; + } + + // Check if the path exists + const pathExists = await fs.pathExists(expandedPath); + if (!pathExists) { + return 'Directory does not exist'; + } + + return true; + }, + }, + ]); + + // Now expand the path for use after the prompt + expandedPath = this.expandUserPath(directory.trim()); + + // Check if directory has custom content + const { CustomHandler } = require('../installers/lib/custom/handler'); + const customHandler = new CustomHandler(); + const customFiles = await customHandler.findCustomContent(expandedPath); + + if (customFiles.length === 0) { + console.log(chalk.yellow(`\nNo custom content found in ${expandedPath}`)); + + const { tryAgain } = await inquirer.prompt([ + { + type: 'confirm', + name: 'tryAgain', + message: 'Try a different directory?', + default: true, + }, + ]); + + if (tryAgain) { + continue; + } else { + return { hasCustomContent: false }; + } + } + + customPath = expandedPath; + console.log(chalk.green(`\nโœ“ Found ${customFiles.length} custom content item(s):`)); + for (const file of customFiles) { + const relativePath = path.relative(expandedPath, path.dirname(file)); + const folderName = path.dirname(file).split(path.sep).pop(); + console.log(chalk.dim(` โ€ข ${folderName} ${chalk.gray(`(${relativePath})`)}`)); + } + } + + return { hasCustomContent: true, customPath }; + } + + return { hasCustomContent: false }; + } catch (error) { + console.error(chalk.red('Error in custom content prompt:'), error); + return { hasCustomContent: false }; + } + } + /** * Confirm directory selection * @param {string} directory - The directory path @@ -798,6 +1209,144 @@ class UI { return (await fs.pathExists(hookPath)) && (await fs.pathExists(playTtsPath)); } + + /** + * Prompt for custom content for existing installations + * @returns {Object} Custom content configuration + */ + async promptCustomContentForExisting() { + try { + CLIUtils.displaySection('Custom Content', 'Add new custom agents, workflows, or modules to your installation'); + + const { hasCustomContent } = await inquirer.prompt([ + { + type: 'list', + name: 'hasCustomContent', + message: 'Do you want to add or update custom content?', + choices: [ + { + name: 'No, continue with current installation only', + value: false, + }, + { + name: 'Yes, I have custom content to add or update', + value: true, + }, + ], + default: false, + }, + ]); + + if (!hasCustomContent) { + return { hasCustomContent: false }; + } + + // Get directory path + const { customPath } = await inquirer.prompt([ + { + type: 'input', + name: 'customPath', + message: 'Enter directory to search for custom content (will scan subfolders):', + default: process.cwd(), + validate: async (input) => { + if (!input || input.trim() === '') { + return 'Please enter a directory path'; + } + + // Normalize and check if path exists + const expandedPath = CLIUtils.expandPath(input.trim()); + const pathExists = await fs.pathExists(expandedPath); + if (!pathExists) { + return 'Directory does not exist'; + } + + // Check if it's actually a directory + const stats = await fs.stat(expandedPath); + if (!stats.isDirectory()) { + return 'Path must be a directory'; + } + + return true; + }, + transformer: (input) => { + return CLIUtils.expandPath(input); + }, + }, + ]); + + const resolvedPath = CLIUtils.expandPath(customPath); + + // Find custom content + const { CustomHandler } = require('../installers/lib/custom/handler'); + const customHandler = new CustomHandler(); + const customFiles = await customHandler.findCustomContent(resolvedPath); + + if (customFiles.length === 0) { + console.log(chalk.yellow(`\nNo custom content found in ${resolvedPath}`)); + + const { tryDifferent } = await inquirer.prompt([ + { + type: 'confirm', + name: 'tryDifferent', + message: 'Try a different directory?', + default: true, + }, + ]); + + if (tryDifferent) { + return await this.promptCustomContentForExisting(); + } + + return { hasCustomContent: false }; + } + + // Display found items + console.log(chalk.cyan(`\nFound ${customFiles.length} custom content file(s):`)); + const { CustomHandler: CustomHandler2 } = require('../installers/lib/custom/handler'); + const customHandler2 = new CustomHandler2(); + const customContentItems = []; + + for (const customFile of customFiles) { + const customInfo = await customHandler2.getCustomInfo(customFile); + if (customInfo) { + customContentItems.push({ + name: `${chalk.cyan('โœ“')} ${customInfo.name} ${chalk.gray(`(${customInfo.relativePath})`)}`, + value: `__CUSTOM_CONTENT__${customFile}`, + checked: true, + }); + } + } + + // Add option to keep existing custom content + console.log(chalk.yellow('\nExisting custom modules will be preserved unless you remove them')); + + const { selectedFiles } = await inquirer.prompt([ + { + type: 'checkbox', + name: 'selectedFiles', + message: 'Select custom content to add:', + choices: customContentItems, + pageSize: 15, + validate: (answer) => { + if (answer.length === 0) { + return 'You must select at least one item'; + } + return true; + }, + }, + ]); + + return { + hasCustomContent: true, + customPath: resolvedPath, + selected: true, + selectedFiles: selectedFiles, + }; + } catch (error) { + console.error(chalk.red('Error configuring custom content:'), error); + return { hasCustomContent: false }; + } + } } module.exports = { UI }; diff --git a/tools/cli/lib/yaml-xml-builder.js b/tools/cli/lib/yaml-xml-builder.js index 248e1607..365320ab 100644 --- a/tools/cli/lib/yaml-xml-builder.js +++ b/tools/cli/lib/yaml-xml-builder.js @@ -232,21 +232,6 @@ class YamlXmlBuilder { return xml; } - /** - * Build metadata comment - */ - buildMetadataComment(metadata) { - const lines = ['\n'); - - return lines.join('\n'); - } - /** * Build persona XML section */ diff --git a/tools/maintainer/review-pr-README.md b/tools/maintainer/review-pr-README.md new file mode 100644 index 00000000..d097ce94 --- /dev/null +++ b/tools/maintainer/review-pr-README.md @@ -0,0 +1,55 @@ +# Raven's Verdict - Deep PR Review Tool + +Adversarial code review for GitHub PRs. Works with any LLM agent. + +> **Status: Experimental.** We're still figuring out how to use this effectively. Expect the workflow to evolve. + +## How It Works + +Point your agent at `review-pr.md` and ask it to review a specific PR: + +> "Read tools/maintainer/review-pr.md and apply it to PR #123" + +The tool will: + +1. Check out the PR branch locally +2. Run an adversarial review (find at least 5 issues) +3. Transform findings into professional tone +4. Preview the review and ask before posting + +See `review-pr.md` for full prompt structure, severity ratings, and sandboxing rules. + +## When to Use + +**Good candidates:** + +- PRs with meaningful logic changes +- Refactors touching multiple files +- New features or architectural changes + +**Skip it for:** + +- Trivial PRs (typo fixes, version bumps, single-line changes) +- PRs you've already reviewed manually +- PRs where you haven't agreed on the approach yet โ€” fix the direction before the implementation + +## Workflow Tips + +**Always review before posting.** The preview step exists for a reason: + +- **[y] Yes** โ€” Post as-is (only if you're confident) +- **[e] Edit** โ€” Modify findings before posting +- **[s] Save only** โ€” Write to file, don't post + +The save option is useful when you want to: + +- Hand-edit the review before posting +- Use the findings as input for a second opinion ("Hey Claude, here's what Raven found โ€” what do you think?") +- Cherry-pick specific findings + +**Trust but verify.** LLM reviews can miss context or flag non-issues. Skim the findings before they hit the PR. + +## Prerequisites + +- `gh` CLI installed and authenticated (`gh auth status`) +- Any LLM agent capable of running bash commands diff --git a/tools/maintainer/review-pr.md b/tools/maintainer/review-pr.md new file mode 100644 index 00000000..24dbb706 --- /dev/null +++ b/tools/maintainer/review-pr.md @@ -0,0 +1,242 @@ +# Raven's Verdict - Deep PR Review Tool + +A cynical adversarial review, transformed into cold engineering professionalism. + + +CRITICAL: Sandboxed Execution Rules + +Before proceeding, you MUST verify: + +- [ ] PR number or URL was EXPLICITLY provided in the user's message +- [ ] You are NOT inferring the PR from conversation history +- [ ] You are NOT looking at git branches, recent commits, or local state +- [ ] You are NOT guessing or assuming any PR numbers + +**If no explicit PR number/URL was provided, STOP immediately and ask:** +"What PR number or URL should I review?" + + + + +## Preflight Checks + +### 0.1 Parse PR Input + +Extract PR number from user input. Examples of valid formats: + +- `123` (just the number) +- `#123` (with hash) +- `https://github.com/owner/repo/pull/123` (full URL) + +If a URL specifies a different repository than the current one: + +```bash +# Check current repo +gh repo view --json nameWithOwner -q '.nameWithOwner' +``` + +If mismatch detected, ask user: + +> "This PR is from `{detected_repo}` but we're in `{current_repo}`. Proceed with reviewing `{detected_repo}#123`? (y/n)" + +If user confirms, store `{REPO}` for use in all subsequent `gh` commands. + +### 0.2 Ensure Clean Checkout + +Verify the working tree is clean and check out the PR branch. + +```bash +# Check for uncommitted changes +git status --porcelain +``` + +If output is non-empty, STOP and tell user: + +> "You have uncommitted changes. Please commit or stash them before running a PR review." + +If clean, fetch and checkout the PR branch: + +```bash +# Fetch and checkout PR branch +# For cross-repo PRs, include --repo {REPO} +gh pr checkout {PR_NUMBER} [--repo {REPO}] +``` + +If checkout fails, STOP and report the error. + +Now you're on the PR branch with full access to all files as they exist in the PR. + +### 0.3 Check PR Size + +```bash +# For cross-repo PRs, include --repo {REPO} +gh pr view {PR_NUMBER} [--repo {REPO}] --json additions,deletions,changedFiles -q '{"additions": .additions, "deletions": .deletions, "files": .changedFiles}' +``` + +**Size thresholds:** + +| Metric | Warning Threshold | +| ------------- | ----------------- | +| Files changed | > 50 | +| Lines changed | > 5000 | + +If thresholds exceeded, ask user: + +> "This PR has {X} files and {Y} line changes. That's large. +> +> **[f] Focus** - Pick specific files or directories to review +> **[p] Proceed** - Review everything (may be slow/expensive) +> **[a] Abort** - Stop here" + +### 0.4 Note Binary Files + +```bash +# For cross-repo PRs, include --repo {REPO} +gh pr diff {PR_NUMBER} [--repo {REPO}] --name-only | grep -E '\.(png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|pdf|zip|tar|gz|bin|exe|dll|so|dylib)$' || echo "No binary files detected" +``` + +Store list of binary files to skip. Note them in final output. + + + + + +### 1.1 Run Cynical Review + +**INTERNAL PERSONA - Never post this directly:** + +Task: You are a cynical, jaded code reviewer with zero patience for sloppy work. This PR was submitted by a clueless weasel and you expect to find problems. Find at least five issues to fix or improve in it. Number them. Be skeptical of everything. Ultrathink. + +Output format: + +```markdown +### [NUMBER]. [FINDING TITLE] [likely] + +**Severity:** [EMOJI] [LEVEL] + +[DESCRIPTION - be specific, include file:line references] +``` + +Severity scale: + +| Level | Emoji | Meaning | +| -------- | ----- | ------------------------------------------------------- | +| Critical | ๐Ÿ”ด | Security issue, data loss risk, or broken functionality | +| Moderate | ๐ŸŸก | Bug, performance issue, or significant code smell | +| Minor | ๐ŸŸข | Style, naming, minor improvement opportunity | + +Likely tag: + +- Add `[likely]` to findings with high confidence, e.g. with direct evidence +- Sort findings by severity (Critical โ†’ Moderate โ†’ Minor), not by confidence + + + + + +**Transform the cynical output into cold engineering professionalism.** + +**Transformation rules:** + +1. Remove all inflammatory language, insults, assumptions about the author +2. Keep all technical substance, file references, severity ratings and likely tag +3. Replace accusatory phrasing with neutral observations: + - โŒ "The author clearly didn't think about..." + - โœ… "This implementation may not account for..." +4. Preserve skepticism as healthy engineering caution: + - โŒ "This will definitely break in production" + - โœ… "This pattern has historically caused issues in production environments" +5. Add the suggested fixes. +6. Keep suggestions actionable and specific + +Output format after transformation: + +```markdown +## PR Review: #{PR_NUMBER} + +**Title:** {PR_TITLE} +**Author:** @{AUTHOR} +**Branch:** {HEAD} โ†’ {BASE} + +--- + +### Findings + +[TRANSFORMED FINDINGS HERE] + +--- + +### Summary + +**Critical:** {COUNT} | **Moderate:** {COUNT} | **Minor:** {COUNT} + +[BINARY_FILES_NOTE if any] + +--- + +_Review generated by Raven's Verdict. LLM-produced analysis - findings may be incorrect or lack context. Verify before acting._ +``` + + + + +### 3.1 Preview + +Display the complete transformed review to the user. + +``` +โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +PREVIEW - This will be posted to PR #{PR_NUMBER} +โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• + +[FULL REVIEW CONTENT] + +โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• +``` + +### 3.2 Confirm + +Ask user for explicit confirmation: + +> **Ready to post this review to PR #{PR_NUMBER}?** +> +> **[y] Yes** - Post as comment +> **[n] No** - Abort, do not post +> **[e] Edit** - Let me modify before posting +> **[s] Save only** - Save locally, don't post + +### 3.3 Post or Save + +**Write review to a temp file, then post:** + +1. Write the review content to a temp file with a unique name (include PR number to avoid collisions) +2. Post using `gh pr comment {PR_NUMBER} [--repo {REPO}] --body-file {path}` +3. Delete the temp file after successful post + +Do NOT use heredocs or `echo` - Markdown code blocks will break shell parsing. Use your file writing tool instead. + +**If auth fails or post fails:** + +1. Display error prominently: + + ``` + โš ๏ธ FAILED TO POST REVIEW + Error: {ERROR_MESSAGE} + ``` + +2. Keep the temp file and tell the user where it is, so they can post manually with: + `gh pr comment {PR_NUMBER} [--repo {REPO}] --body-file {path}` + +**If save only (s):** + +Keep the temp file and inform user of location. + + + + +- The "cynical asshole" phase is internal only - never posted +- Tone transform MUST happen before any external output +- When in doubt, ask the user - never assume +- If you're unsure about severity, err toward higher severity +- If you're unsure about confidence, be honest and use Medium or Low + diff --git a/tools/migrate-custom-module-paths.js b/tools/migrate-custom-module-paths.js new file mode 100755 index 00000000..ad82e981 --- /dev/null +++ b/tools/migrate-custom-module-paths.js @@ -0,0 +1,124 @@ +/** + * Migration script to convert relative paths to absolute paths in custom module manifests + * This should be run once to update existing installations + */ + +const fs = require('fs-extra'); +const path = require('node:path'); +const yaml = require('yaml'); +const chalk = require('chalk'); + +/** + * Find BMAD directory in project + */ +function findBmadDir(projectDir = process.cwd()) { + const possibleNames = ['bmad', '.bmad']; + + for (const name of possibleNames) { + const bmadDir = path.join(projectDir, name); + if (fs.existsSync(bmadDir)) { + return bmadDir; + } + } + + return null; +} + +/** + * Update manifest to use absolute paths + */ +async function updateManifest(manifestPath, projectRoot) { + console.log(chalk.cyan(`\nUpdating manifest: ${manifestPath}`)); + + const content = await fs.readFile(manifestPath, 'utf8'); + const manifest = yaml.parse(content); + + if (!manifest.customModules || manifest.customModules.length === 0) { + console.log(chalk.dim(' No custom modules found')); + return false; + } + + let updated = false; + + for (const customModule of manifest.customModules) { + if (customModule.relativePath && !customModule.sourcePath) { + // Convert relative path to absolute + const absolutePath = path.resolve(projectRoot, customModule.relativePath); + customModule.sourcePath = absolutePath; + + // Remove the old relativePath + delete customModule.relativePath; + + console.log(chalk.green(` โœ“ Updated ${customModule.id}: ${customModule.relativePath} โ†’ ${absolutePath}`)); + updated = true; + } else if (customModule.sourcePath && !path.isAbsolute(customModule.sourcePath)) { + // Source path exists but is not absolute + const absolutePath = path.resolve(customModule.sourcePath); + customModule.sourcePath = absolutePath; + + console.log(chalk.green(` โœ“ Updated ${customModule.id}: ${customModule.sourcePath} โ†’ ${absolutePath}`)); + updated = true; + } + } + + if (updated) { + // Write back the updated manifest + const yamlStr = yaml.dump(manifest, { + indent: 2, + lineWidth: -1, + noRefs: true, + sortKeys: false, + }); + + await fs.writeFile(manifestPath, yamlStr); + console.log(chalk.green(' Manifest updated successfully')); + } else { + console.log(chalk.dim(' All paths already absolute')); + } + + return updated; +} + +/** + * Main migration function + */ +async function migrate(directory) { + const projectRoot = path.resolve(directory || process.cwd()); + const bmadDir = findBmadDir(projectRoot); + + if (!bmadDir) { + console.error(chalk.red('โœ— No BMAD installation found in directory')); + process.exit(1); + } + + console.log(chalk.blue.bold('๐Ÿ”„ BMAD Custom Module Path Migration')); + console.log(chalk.dim(`Project: ${projectRoot}`)); + console.log(chalk.dim(`BMAD Directory: ${bmadDir}`)); + + const manifestPath = path.join(bmadDir, '_cfg', 'manifest.yaml'); + + if (!fs.existsSync(manifestPath)) { + console.error(chalk.red('โœ— No manifest.yaml found')); + process.exit(1); + } + + const updated = await updateManifest(manifestPath, projectRoot); + + if (updated) { + console.log(chalk.green.bold('\nโœจ Migration completed successfully!')); + console.log(chalk.dim('Custom modules now use absolute source paths.')); + } else { + console.log(chalk.yellow('\nโš  No migration needed - paths already absolute')); + } +} + +// Run migration if called directly +if (require.main === module) { + const directory = process.argv[2]; + migrate(directory).catch((error) => { + console.error(chalk.red('\nโœ— Migration failed:'), error.message); + process.exit(1); + }); +} + +module.exports = { migrate }; diff --git a/tools/schema/agent.js b/tools/schema/agent.js index 99438f6a..cafff7c0 100644 --- a/tools/schema/agent.js +++ b/tools/schema/agent.js @@ -75,27 +75,41 @@ function agentSchema(options = {}) { } // Handle multi format with triggers array (new format) else if (item.triggers && Array.isArray(item.triggers)) { - for (const triggerGroup of item.triggers) { - for (const triggerKey of Object.keys(triggerGroup)) { - if (!TRIGGER_PATTERN.test(triggerKey)) { + for (const [triggerIndex, triggerItem] of item.triggers.entries()) { + let triggerName = null; + + // Extract trigger name from all three formats + if (triggerItem.trigger) { + // Format 1: Simple flat format with trigger field + triggerName = triggerItem.trigger; + } else { + // Format 2a or 2b: Object-key format + const keys = Object.keys(triggerItem); + if (keys.length === 1 && keys[0] !== 'trigger') { + triggerName = keys[0]; + } + } + + if (triggerName) { + if (!TRIGGER_PATTERN.test(triggerName)) { ctx.addIssue({ code: 'custom', - path: ['agent', 'menu', index, 'triggers'], - message: `agent.menu[].triggers key must be kebab-case (lowercase words separated by hyphen) - got "${triggerKey}"`, + path: ['agent', 'menu', index, 'triggers', triggerIndex], + message: `agent.menu[].triggers[] must be kebab-case (lowercase words separated by hyphen) - got "${triggerName}"`, }); return; } - if (seenTriggers.has(triggerKey)) { + if (seenTriggers.has(triggerName)) { ctx.addIssue({ code: 'custom', - path: ['agent', 'menu', index, 'triggers'], - message: `agent.menu[].triggers key duplicates "${triggerKey}" within the same agent`, + path: ['agent', 'menu', index, 'triggers', triggerIndex], + message: `agent.menu[].triggers[] duplicates "${triggerName}" within the same agent`, }); return; } - seenTriggers.add(triggerKey); + seenTriggers.add(triggerName); } } } @@ -250,102 +264,148 @@ function buildMenuItemSchema() { .object({ multi: createNonEmptyString('agent.menu[].multi'), triggers: z - .array(z.object({}).passthrough()) - .refine( - (triggers) => { - // Each item in triggers array should be an object with exactly one key - for (const trigger of triggers) { - const keys = Object.keys(trigger); - if (keys.length !== 1) { - return false; - } + .array( + z.union([ + // Format 1: Simple flat format (has trigger field) + z + .object({ + trigger: z.string(), + input: createNonEmptyString('agent.menu[].triggers[].input'), + route: createNonEmptyString('agent.menu[].triggers[].route').optional(), + action: createNonEmptyString('agent.menu[].triggers[].action').optional(), + data: z.string().optional(), + type: z.enum(['exec', 'action', 'workflow']).optional(), + }) + .strict() + .refine((data) => data.trigger, { message: 'Must have trigger field' }) + .superRefine((value, ctx) => { + // Must have either route or action (or both) + if (!value.route && !value.action) { + ctx.addIssue({ + code: 'custom', + message: 'agent.menu[].triggers[] must have either route or action (or both)', + }); + } + }), + // Format 2a: Object with array format (like bmad-builder.agent.yaml) + z + .object({}) + .passthrough() + .refine( + (value) => { + const keys = Object.keys(value); + if (keys.length !== 1) return false; + const triggerItems = value[keys[0]]; + return Array.isArray(triggerItems); + }, + { message: 'Must be object with single key pointing to array' }, + ) + .superRefine((value, ctx) => { + const triggerName = Object.keys(value)[0]; + const triggerItems = value[triggerName]; - const execArray = trigger[keys[0]]; - if (!Array.isArray(execArray)) { - return false; - } + if (!Array.isArray(triggerItems)) { + ctx.addIssue({ + code: 'custom', + message: `Trigger "${triggerName}" must be an array of items`, + }); + return; + } - // Check required fields - const hasInput = execArray.some((item) => 'input' in item); - const hasRouteOrAction = execArray.some((item) => 'route' in item || 'action' in item); + // Check required fields in the array + const hasInput = triggerItems.some((item) => 'input' in item); + const hasRouteOrAction = triggerItems.some((item) => 'route' in item || 'action' in item); - if (!hasInput) { - return false; - } + if (!hasInput) { + ctx.addIssue({ + code: 'custom', + message: `Trigger "${triggerName}" must have an input field`, + }); + } - // If not TODO, must have route or action - const isTodo = execArray.some((item) => item.route === 'TODO' || item.action === 'TODO'); - if (!isTodo && !hasRouteOrAction) { - return false; - } - } - return true; - }, - { - message: 'agent.menu[].triggers must be an array of trigger objects with input and either route/action or TODO', - }, + if (!hasRouteOrAction) { + ctx.addIssue({ + code: 'custom', + message: `Trigger "${triggerName}" must have a route or action field`, + }); + } + }), + // Format 2b: Object with direct fields (like analyst.agent.yaml) + z + .object({}) + .passthrough() + .refine( + (value) => { + const keys = Object.keys(value); + if (keys.length !== 1) return false; + const triggerFields = value[keys[0]]; + return !Array.isArray(triggerFields) && typeof triggerFields === 'object'; + }, + { message: 'Must be object with single key pointing to object' }, + ) + .superRefine((value, ctx) => { + const triggerName = Object.keys(value)[0]; + const triggerFields = value[triggerName]; + + // Check required fields + if (!triggerFields.input || typeof triggerFields.input !== 'string') { + ctx.addIssue({ + code: 'custom', + message: `Trigger "${triggerName}" must have an input field`, + }); + } + + if (!triggerFields.route && !triggerFields.action) { + ctx.addIssue({ + code: 'custom', + message: `Trigger "${triggerName}" must have a route or action field`, + }); + } + }), + ]), ) - .transform((triggers) => { - // Validate and clean up the triggers - for (const trigger of triggers) { - const keys = Object.keys(trigger); - if (keys.length !== 1) { - throw new Error('Each trigger object must have exactly one key'); - } - - const execArray = trigger[keys[0]]; - if (!Array.isArray(execArray)) { - throw new TypeError(`Trigger "${keys[0]}" must be an array`); - } - - // Validate each item in the exec array - for (const item of execArray) { - if ('input' in item && typeof item.input !== 'string') { - throw new Error('Input must be a string'); - } - if ('route' in item && typeof item.route !== 'string' && item.route !== 'TODO') { - throw new Error('Route must be a string or TODO'); - } - if ('type' in item && !['exec', 'action', 'workflow', 'TODO'].includes(item.type)) { - throw new Error('Type must be one of: exec, action, workflow, TODO'); - } - } - } - return triggers; - }), + .min(1, { message: 'agent.menu[].triggers must have at least one trigger' }), discussion: z.boolean().optional(), }) .strict() .superRefine((value, ctx) => { - // Extract all trigger keys for validation - const triggerKeys = []; - for (const triggerGroup of value.triggers) { - for (const key of Object.keys(triggerGroup)) { - triggerKeys.push(key); + // Check for duplicate trigger names + const seenTriggers = new Set(); + for (const [index, triggerItem] of value.triggers.entries()) { + let triggerName = null; - // Validate trigger key format - if (!TRIGGER_PATTERN.test(key)) { + // Extract trigger name from either format + if (triggerItem.trigger) { + // Format 1 + triggerName = triggerItem.trigger; + } else { + // Format 2 + const keys = Object.keys(triggerItem); + if (keys.length === 1) { + triggerName = keys[0]; + } + } + + if (triggerName) { + if (seenTriggers.has(triggerName)) { ctx.addIssue({ code: 'custom', - path: ['agent', 'menu', 'triggers'], - message: `Trigger key "${key}" must be kebab-case (lowercase words separated by hyphen)`, + path: ['agent', 'menu', 'triggers', index], + message: `Trigger name "${triggerName}" is duplicated`, + }); + } + seenTriggers.add(triggerName); + + // Validate trigger name format + if (!TRIGGER_PATTERN.test(triggerName)) { + ctx.addIssue({ + code: 'custom', + path: ['agent', 'menu', 'triggers', index], + message: `Trigger name "${triggerName}" must be kebab-case (lowercase words separated by hyphen)`, }); } } } - - // Check for duplicates - const seenTriggers = new Set(); - for (const triggerKey of triggerKeys) { - if (seenTriggers.has(triggerKey)) { - ctx.addIssue({ - code: 'custom', - path: ['agent', 'menu', 'triggers'], - message: `Trigger key "${triggerKey}" is duplicated`, - }); - } - seenTriggers.add(triggerKey); - } }); return z.union([legacyMenuItemSchema, multiMenuItemSchema]); diff --git a/tools/validate-svg-changes.sh b/tools/validate-svg-changes.sh new file mode 100755 index 00000000..07c68375 --- /dev/null +++ b/tools/validate-svg-changes.sh @@ -0,0 +1,356 @@ +#!/bin/bash +# +# Visual SVG Validation Script +# +# Compares old vs new SVG files using browser-accurate rendering (Playwright) +# and pixel-level comparison (ImageMagick), then generates a prompt for AI analysis. +# +# Usage: ./tools/validate-svg-changes.sh +# + +set -e + +SVG_FILE="${1:-src/modules/bmm/docs/images/workflow-method-greenfield.svg}" +TMP_DIR="/tmp/svg-validation-$$" + +echo "๐ŸŽจ Visual SVG Validation" +echo "" + +# Check if file exists +if [ ! -f "$SVG_FILE" ]; then + echo "โŒ Error: SVG file not found: $SVG_FILE" + exit 1 +fi + +# Check for ImageMagick +if ! command -v magick &> /dev/null; then + echo "โŒ ImageMagick not found" + echo "" + echo "Install with:" + echo " brew install imagemagick" + echo "" + exit 1 +fi + +echo "โœ“ ImageMagick found" + +# Check for Node.js +if ! command -v node &> /dev/null; then + echo "โŒ Node.js not found" + exit 1 +fi + +echo "โœ“ Node.js found ($(node -v))" + +# Check for Playwright (local install) +if [ ! -d "node_modules/playwright" ]; then + echo "" + echo "๐Ÿ“ฆ Playwright not found locally" + echo "Installing Playwright (local to this project, no package.json changes)..." + echo "" + npm install --no-save playwright + echo "" + echo "โœ“ Playwright installed" +else + echo "โœ“ Playwright found" +fi + +echo "" +echo "๐Ÿ”„ Rendering SVGs to PNG..." +echo "" + +# Create temp directory +mkdir -p "$TMP_DIR" + +# Extract old SVG from git +git show HEAD:"$SVG_FILE" > "$TMP_DIR/old.svg" 2>/dev/null || { + echo "โŒ Could not extract old SVG from git HEAD" + echo " Make sure you have uncommitted changes to compare" + exit 1 +} + +# Copy new SVG +cp "$SVG_FILE" "$TMP_DIR/new.svg" + +# Create Node.js renderer script in project directory (so it can find node_modules) +cat > "tools/render-svg-temp.js" << 'EOJS' +const { chromium } = require('playwright'); +const fs = require('fs'); + +async function renderSVG(svgPath, pngPath) { + const browser = await chromium.launch({ headless: true }); + const page = await browser.newPage(); + + const svgContent = fs.readFileSync(svgPath, 'utf8'); + const widthMatch = svgContent.match(/width="([^"]+)"/); + const heightMatch = svgContent.match(/height="([^"]+)"/); + const width = Math.ceil(parseFloat(widthMatch[1])); + const height = Math.ceil(parseFloat(heightMatch[1])); + + const html = ` + + + + + + ${svgContent} + + `; + + await page.setContent(html); + await page.setViewportSize({ width, height }); + await page.waitForTimeout(1000); + await page.screenshot({ path: pngPath, fullPage: true }); + await browser.close(); + + console.log(`โœ“ Rendered ${pngPath}`); +} + +(async () => { + await renderSVG(process.argv[2], process.argv[3]); + await renderSVG(process.argv[4], process.argv[5]); +})(); +EOJS + +# Render both SVGs (run from project dir so node_modules is accessible) +node tools/render-svg-temp.js \ + "$TMP_DIR/old.svg" "$TMP_DIR/old.png" \ + "$TMP_DIR/new.svg" "$TMP_DIR/new.png" + +# Clean up temp script +rm tools/render-svg-temp.js + +echo "" +echo "๐Ÿ” Comparing pixels..." +echo "" + +# Compare using ImageMagick +DIFF_OUTPUT=$(magick compare -metric AE "$TMP_DIR/old.png" "$TMP_DIR/new.png" "$TMP_DIR/diff.png" 2>&1 || true) +DIFF_PIXELS=$(echo "$DIFF_OUTPUT" | awk '{print $1}') + +# Get image dimensions +DIMENSIONS=$(magick identify -format "%wx%h" "$TMP_DIR/old.png") +WIDTH=$(echo "$DIMENSIONS" | cut -d'x' -f1) +HEIGHT=$(echo "$DIMENSIONS" | cut -d'x' -f2) +TOTAL_PIXELS=$((WIDTH * HEIGHT)) + +# Calculate percentage +DIFF_PERCENT=$(echo "scale=4; $DIFF_PIXELS / $TOTAL_PIXELS * 100" | bc) + +echo "๐Ÿ“Š Results:" +echo " Dimensions: ${WIDTH} ร— ${HEIGHT}" +echo " Total pixels: $(printf "%'d" $TOTAL_PIXELS)" +echo " Different pixels: $(printf "%'d" $DIFF_PIXELS)" +echo " Difference: ${DIFF_PERCENT}%" +echo "" + +if (( $(echo "$DIFF_PERCENT < 0.01" | bc -l) )); then + echo "โœ… ESSENTIALLY IDENTICAL (< 0.01% difference)" + VERDICT="essentially identical" +elif (( $(echo "$DIFF_PERCENT < 0.1" | bc -l) )); then + echo "โš ๏ธ MINOR DIFFERENCES (< 0.1%)" + VERDICT="minor differences detected" +else + echo "โŒ SIGNIFICANT DIFFERENCES (โ‰ฅ 0.1%)" + VERDICT="significant differences detected" +fi + +echo "" +echo "๐Ÿ“ Output files:" +echo " Old render: $TMP_DIR/old.png" +echo " New render: $TMP_DIR/new.png" +echo " Diff image: $TMP_DIR/diff.png" +echo "" + +# Generate HTML comparison page +cat > "$TMP_DIR/comparison.html" << 'EOHTML' + + + + SVG Comparison + + + +
+

๐ŸŽจ SVG Visual Comparison

+

File: FILENAME_PLACEHOLDER

+
+
+
Dimensions
+
DIMENSIONS_PLACEHOLDER
+
+
+
Different Pixels
+
DIFF_PIXELS_PLACEHOLDER
+
+
+
Difference
+
DIFF_PERCENT_PLACEHOLDER%
+
+
+
Verdict
+
VERDICT_PLACEHOLDER
+
+
+
+ +
+
+

๐Ÿ“„ Old (HEAD)

+
+ Old SVG +
+
+ +
+

๐Ÿ“ New (Working)

+
+ New SVG +
+
+ +
+

๐Ÿ” Diff (Red = Changes)

+
+ Diff +
+
+
+ + +EOHTML + +# Determine verdict class for styling +if (( $(echo "$DIFF_PERCENT < 0.01" | bc -l) )); then + VERDICT_CLASS="good" +elif (( $(echo "$DIFF_PERCENT < 0.1" | bc -l) )); then + VERDICT_CLASS="warning" +else + VERDICT_CLASS="bad" +fi + +# Replace placeholders in HTML +sed -i '' "s|FILENAME_PLACEHOLDER|$SVG_FILE|g" "$TMP_DIR/comparison.html" +sed -i '' "s|DIMENSIONS_PLACEHOLDER|${WIDTH} ร— ${HEIGHT}|g" "$TMP_DIR/comparison.html" +sed -i '' "s|DIFF_PIXELS_PLACEHOLDER|$(printf "%'d" $DIFF_PIXELS) / $(printf "%'d" $TOTAL_PIXELS)|g" "$TMP_DIR/comparison.html" +sed -i '' "s|DIFF_PERCENT_PLACEHOLDER|$DIFF_PERCENT|g" "$TMP_DIR/comparison.html" +sed -i '' "s|VERDICT_PLACEHOLDER|$VERDICT|g" "$TMP_DIR/comparison.html" +sed -i '' "s|VERDICT_CLASS_PLACEHOLDER|$VERDICT_CLASS|g" "$TMP_DIR/comparison.html" + +echo "โœ“ Generated comparison page: $TMP_DIR/comparison.html" +echo "" +echo "๐ŸŒ Opening comparison in browser..." +open "$TMP_DIR/comparison.html" +echo "" + +echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" +echo "" +echo "๐Ÿค– AI VISUAL ANALYSIS PROMPT" +echo "" +echo "Copy and paste this into Gemini/Claude with the diff image attached:" +echo "" +echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" +cat << PROMPT + +I've made changes to an Excalidraw diagram SVG file. Please analyze the visual differences between the old and new versions. + +**Automated Analysis:** +- Dimensions: ${WIDTH} ร— ${HEIGHT} pixels +- Different pixels: $(printf "%'d" $DIFF_PIXELS) out of $(printf "%'d" $TOTAL_PIXELS) +- Difference: ${DIFF_PERCENT}% +- Verdict: ${VERDICT} + +**Attached Image:** +The attached image shows the pixel-level diff (red = differences). + +**Questions:** +1. Are the differences purely anti-aliasing/rendering artifacts, or are there actual content changes? +2. If there are content changes, what specifically changed? +3. Do the changes align with the intent to remove zombie Excalidraw elements (elements marked as deleted but left in the JSON)? +4. Is this safe to commit? + +**Context:** +- File: $SVG_FILE +- Changes: Removed 191 lines of zombie JSON from Excalidraw source +- Expected: Visual output should be identical (zombie elements were already marked as deleted) + +PROMPT +echo "โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”" +echo "" +echo "๐Ÿ“Ž Attach this file to your AI prompt:" +echo " $TMP_DIR/diff.png" +echo "" +echo "๐Ÿ’ก To open the diff image:" +echo " open $TMP_DIR/diff.png" +echo ""