bmad-method 6.0.0-alpha.13 → 6.0.0-alpha.14

package/docs/custom-agent-installation.md

@@ -1,125 +1,68 @@
 # Custom Agent Installation
 
-Install and personalize BMAD agents in your project.
+BMAD agents and workflows are now installed through the main CLI installer using a `custom.yaml` configuration file or by having an installer file.
 
 ## Quick Start
 
-```bash
-# From your project directory with BMAD installed
-npx bmad-method agent-install
-```
+Create a `custom.yaml` file in the root of your agent/workflow folder:
 
-Or if you have bmad-cli installed globally:
-
-```bash
-bmad agent-install
+```yaml
+code: my-custom-agent
+name: 'My Custom Agent'
+default_selected: true
 ```
 
-## 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
+Then run the BMAD installer from your project directory:
 
 ```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
+npx bmad-method install
 ```
 
-## Installing from Custom Locations
-
-Use the `-s` / `--source` option to install agents from any location:
+Or if you have bmad-cli installed globally:
 
 ```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
+bmad install
 ```
 
-This is useful when:
+## Installation Methods
 
-- 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
+### Method 1: Stand-alone Folder with custom.yaml
 
-## Example Session
+Place your agent or workflow in a folder with a `custom.yaml` file at the root:
 
 ```
-🔧 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
+my-agent/
+├── custom.yaml      # Required configuration file
+├── my-agent.agent.yaml
+└── sidecar/         # Optional
+    └── instructions.md
+```
 
-   Persona: Fred
-   File: fred-commit-poet.md
+### Method 2: Installer File
 
-📝 Agent Configuration
+For more complex installations, include an `installer.js` or `installer.yaml` file in your agent/workflow folder:
 
-   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
+```
+my-workflow/
+├── workflow.md
+└── installer.yaml   # Custom installation logic
+```
 
-   How enthusiastic should the agent be?
-     1. Moderate - Professional with personality
-   * 2. High - Genuinely excited
-     3. EXTREME - Full theatrical drama
-   Choice (default: 2): 3
+## What It Does
 
-   Include emojis in commit messages? [Y/n]: y
+1. **Discovers** available agents and workflows from folders with `custom.yaml`
+2. **Installs** to your project's `.bmad/custom/` directory
+3. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
+4. **Registers** the agent/workflow in the BMAD system
 
-✨ Agent installed successfully!
-   Name: fred-commit-poet
-   Location: /project/.bmad/custom/agents/fred-commit-poet
-   Compiled: fred-commit-poet.md
+## Example custom.yaml
 
-   ✓ 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
+```yaml
+code: my-custom-agent
+name: 'My Custom Agent'
+default_selected: true
 ```
 
-## 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.**
@@ -130,8 +73,9 @@ The BMAD source includes example agents you can install. **You must copy them to
 
 ```bash
 # From your project root
+mkdir -p .bmad/custom/agents/my-agent
 cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \
-   .bmad/custom/agents/
+   .bmad/custom/agents/my-agent/
 ```
 
 **For expert agents** (folder with sidecar files):
@@ -142,19 +86,29 @@ cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memor
    .bmad/custom/agents/
 ```
 
-### Step 2: Install and Personalize
+### Step 2: Create custom.yaml
+
+```bash
+# In the agent folder, create custom.yaml
+cat > .bmad/custom/agents/my-agent/custom.yaml << EOF
+code: my-agent
+name: "My Custom Agent"
+default_selected: true
+EOF
+```
+
+### Step 3: Install
 
 ```bash
-npx bmad-method agent-install
-# or: bmad agent-install (if BMAD installed locally)
+npx bmad-method install
+# or: bmad 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
+1. Find the agent with its `custom.yaml`
+2. Install it to the appropriate location
+3. Create IDE commands for immediate use
 
 ### Available Reference Agents
 
@@ -180,4 +134,4 @@ src/modules/bmb/reference/agents/
 
 ## 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/`.
+Use the BMB agent builder to craft your agents. Once ready to use, place your `.agent.yaml` files or folders with `custom.yaml` in `.bmad/custom/agents/` or `.bmad/custom/workflows/`.

package/docs/document-sharding-guide.md

@@ -190,7 +190,7 @@ Workflows load only needed sections:
 
 - Needs ALL epics to build complete status
 
-**epic-tech-context, create-story, story-context, code-review** (Selective):
+**create-story, code-review** (Selective):
 
 ```
 Working on Epic 3, Story 2:

package/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/**',
     ],
   },
 

package/example-custom-content/README.md

@@ -0,0 +1,4 @@
+# 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.

package/{custom/src → 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
@@ -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:)

package/{custom/src → 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..._

package/{custom/src → example-custom-content}/agents/toolsmith/toolsmith.agent.yaml

@@ -5,41 +5,42 @@ agent:
     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:
 

package/example-custom-content/custom.yaml

@@ -0,0 +1,3 @@
+code: bmad-custom
+name: "BMAD-Custom: Sample Stand Alone Custom Agents and Workflows"
+default_selected: true

package/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/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/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.