bmad-method 6.0.0-alpha.10 → 6.0.0-alpha.11

package/docs/custom-agent-installation.md

@@ -0,0 +1,169 @@
+# Custom Agent Installation
+
+Install and personalize BMAD agents in your project.
+
+## Quick Start
+
+```bash
+# From your project directory with BMAD installed
+npx bmad 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 <path>     Direct path to specific agent YAML file or folder
+  -d, --defaults        Use default values without prompting
+  -t, --target <path>   Target installation directory
+```
+
+## 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 agent-install
+# or: bmad agent-install
+```
+
+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
+
+Place your `.agent.yaml` files in `.bmad/custom/agents/`. Use the reference agents as templates.
+
+Key sections in an agent YAML:
+
+- `metadata`: name, title, icon, type
+- `persona`: role, identity, communication_style, principles
+- `prompts`: reusable prompt templates
+- `menu`: numbered menu items
+- `install_config`: personalization questions (optional, at end of file)
+
+See the reference agents for complete examples with install_config templates and XML-style semantic tags.

package/{v6-open-items.md → docs/v6-open-items.md}

@@ -13,5 +13,5 @@ Aside from stability and bug fixes found during the alpha period - the main focu
 - knowledge base for BMM
 - Module repository and submission process defined
 - MCP Injections based on installation selection
-- sub agent for opencode and claude code optimization
+- sub agent for open-code and claude code optimization
 - TDD Workflow Integration

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.10",
+  "version": "6.0.0-alpha.11",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -24,6 +24,7 @@
     "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",

package/src/core/resources/excalidraw/README.md

@@ -0,0 +1,160 @@
+# Core Excalidraw Resources
+
+Universal knowledge for creating Excalidraw diagrams. All agents that create Excalidraw files should reference these resources.
+
+## Purpose
+
+Provides the **HOW** (universal knowledge) while agents provide the **WHAT** (domain-specific application).
+
+**Core = "How to create Excalidraw elements"**
+
+- How to group shapes with text labels
+- How to calculate text width
+- How to create arrows with proper bindings
+- How to validate JSON syntax
+- Base structure and primitives
+
+**Agents = "What diagrams to create"**
+
+- Frame Expert (BMM): Technical flowcharts, architecture diagrams, wireframes
+- Presentation Master (CIS): Pitch decks, creative visuals, Rube Goldberg machines
+- Tech Writer (BMM): Documentation diagrams, concept explanations
+
+## Files in This Directory
+
+### excalidraw-helpers.md
+
+**Universal element creation patterns**
+
+- Text width calculation
+- Element grouping rules (shapes + labels)
+- Grid alignment
+- Arrow creation (straight, elbow)
+- Theme application
+- Validation checklist
+- Optimization rules
+
+**Agents reference this to:**
+
+- Create properly grouped shapes
+- Calculate text dimensions
+- Connect elements with arrows
+- Ensure valid structure
+
+### validate-json-instructions.md
+
+**Universal JSON validation process**
+
+- How to validate Excalidraw JSON
+- Common errors and fixes
+- Workflow integration
+- Error recovery
+
+**Agents reference this to:**
+
+- Validate files after creation
+- Fix syntax errors
+- Ensure files can be opened in Excalidraw
+
+### library-loader.md (Future)
+
+**How to load external .excalidrawlib files**
+
+- Programmatic library loading
+- Community library integration
+- Custom library management
+
+**Status:** To be developed when implementing external library support.
+
+## How Agents Use These Resources
+
+### Example: Frame Expert (Technical Diagrams)
+
+```yaml
+# workflows/diagrams/create-flowchart/workflow.yaml
+helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
+```
+
+**Domain-specific additions:**
+
+```yaml
+# workflows/diagrams/_shared/flowchart-templates.yaml
+flowchart:
+  start_node:
+    type: ellipse
+    width: 120
+    height: 60
+  process_box:
+    type: rectangle
+    width: 160
+    height: 80
+  decision_diamond:
+    type: diamond
+    width: 140
+    height: 100
+```
+
+### Example: Presentation Master (Creative Visuals)
+
+```yaml
+# workflows/create-visual-metaphor/workflow.yaml
+helpers: '{project-root}/{bmad_folder}/core/resources/excalidraw/excalidraw-helpers.md'
+json_validation: '{project-root}/{bmad_folder}/core/resources/excalidraw/validate-json-instructions.md'
+```
+
+**Domain-specific additions:**
+
+```yaml
+# workflows/_shared/creative-templates.yaml
+rube_goldberg:
+  whimsical_connector:
+    type: arrow
+    strokeStyle: dashed
+    roughness: 2
+  playful_box:
+    type: rectangle
+    roundness: 12
+```
+
+## What Doesn't Belong in Core
+
+**Domain-Specific Elements:**
+
+- Flowchart-specific templates (belongs in Frame Expert)
+- Pitch deck layouts (belongs in Presentation Master)
+- Documentation-specific styles (belongs in Tech Writer)
+
+**Agent Workflows:**
+
+- How to create a flowchart (Frame Expert workflow)
+- How to create a pitch deck (Presentation Master workflow)
+- Step-by-step diagram creation (agent-specific)
+
+**Theming:**
+
+- Currently in agent workflows
+- **Future:** Will be refactored to core as user-configurable themes
+
+## Architecture Principle
+
+**Single Source of Truth:**
+
+- Core holds universal knowledge
+- Agents reference core, don't duplicate
+- Updates to core benefit all agents
+- Agents specialize with domain knowledge
+
+**DRY (Don't Repeat Yourself):**
+
+- Element creation logic: ONCE in core
+- Text width calculation: ONCE in core
+- Validation process: ONCE in core
+- Arrow binding patterns: ONCE in core
+
+## Future Enhancements
+
+1. **External Library Loader** - Load .excalidrawlib files from libraries.excalidraw.com
+2. **Theme Management** - User-configurable color themes saved in core
+3. **Component Library** - Shared reusable components across agents
+4. **Layout Algorithms** - Auto-layout helpers for positioning elements

package/src/core/resources/excalidraw/library-loader.md

@@ -0,0 +1,50 @@
+# External Library Loader
+
+**Status:** Placeholder for future implementation
+
+## Purpose
+
+Load external .excalidrawlib files from https://libraries.excalidraw.com or custom sources.
+
+## Planned Capabilities
+
+- Load libraries by URL
+- Load libraries from local files
+- Merge multiple libraries
+- Filter library components
+- Cache loaded libraries
+
+## API Reference
+
+Will document how to use:
+
+- `importLibrary(url)` - Load library from URL
+- `loadSceneOrLibraryFromBlob()` - Load from file
+- `mergeLibraryItems()` - Combine libraries
+
+## Usage Example
+
+```yaml
+# Future workflow.yaml structure
+libraries:
+  - url: 'https://libraries.excalidraw.com/libraries/...'
+    filter: ['aws', 'cloud']
+  - path: '{project-root}/_data/custom-library.excalidrawlib'
+```
+
+## Implementation Notes
+
+This will be developed when agents need to leverage the extensive library ecosystem available at https://libraries.excalidraw.com.
+
+Hundreds of pre-built component libraries exist for:
+
+- AWS/Cloud icons
+- UI/UX components
+- Business diagrams
+- Mind map shapes
+- Floor plans
+- And much more...
+
+## User Configuration
+
+Future: Users will be able to configure favorite libraries in their BMAD config for automatic loading.