From c57ada4d9c4b3042ed8b0b6ad39c14ed64cfed6f Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sat, 22 Nov 2025 16:16:12 -0600
Subject: [PATCH] feat: improve agent creation workflow and documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## BMB Agent Workflow Improvements
- Always create folders for agents (even simple ones)
- Add compact info-and-installation-guide.md (20 lines max)
- Include installation guide with every created agent
- Update workflow to use standalone_output_folder structure

## Documentation Updates
- Clarify --defaults makes installation non-interactive
- Update all parameter documentation for clarity
- Fix npm package references (bmad-method only)

## New Agent Structure
Every agent now gets:
  agent-folder/
  ├── agent-name.agent.yaml    # Source YAML
  └── info-and-installation-guide.md  # Quick install guide + description

## Quick Install Commands (added to guide)
- Interactive: npx bmad-method agent-install --source ./agent.yaml
- Non-interactive: npx bmad-method agent-install --source ./agent.yaml --defaults

This makes agent installation much more user-friendly and consistent.
---
 docs/custom-agent-installation.md               |  2 +-
 .../create-agent/info-and-installation-guide.md | 17 +++++++++++++++++
 .../create-agent/installation-guide.md          |  2 +-
 .../bmb/workflows/create-agent/workflow.yaml    |  7 +++++--
 4 files changed, 24 insertions(+), 4 deletions(-)
 create mode 100644 src/modules/bmb/workflows/create-agent/info-and-installation-guide.md

diff --git a/docs/custom-agent-installation.md b/docs/custom-agent-installation.md
index 01bedcf4..15098094 100644
--- a/docs/custom-agent-installation.md
+++ b/docs/custom-agent-installation.md
@@ -46,7 +46,7 @@ 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 (skip all prompts)
+# Install with defaults (non-interactive)
 bmad agent-install -s path/to/my-agent -d
 
 # Install to a specific destination project
diff --git a/src/modules/bmb/workflows/create-agent/info-and-installation-guide.md b/src/modules/bmb/workflows/create-agent/info-and-installation-guide.md
new file mode 100644
index 00000000..304bbb98
--- /dev/null
+++ b/src/modules/bmb/workflows/create-agent/info-and-installation-guide.md
@@ -0,0 +1,17 @@
+# {agent_name} Agent
+
+## Installation
+
+```bash
+# Quick install (interactive)
+npx bmad-method agent-install --source ./{agent_filename}.agent.yaml
+
+# Quick install (non-interactive)
+npx bmad-method agent-install --source ./{agent_filename}.agent.yaml --defaults
+```
+
+## About This Agent
+
+{agent_description}
+
+_Generated with BMAD Builder workflow_
diff --git a/src/modules/bmb/workflows/create-agent/installation-guide.md b/src/modules/bmb/workflows/create-agent/installation-guide.md
index b9ab6c01..f210254b 100644
--- a/src/modules/bmb/workflows/create-agent/installation-guide.md
+++ b/src/modules/bmb/workflows/create-agent/installation-guide.md
@@ -56,7 +56,7 @@ npx bmad-method agent-install    # Works anywhere without cloning
 # Install specific agent file
 npx bmad-method agent-install --source ./my-agent.agent.yaml
 
-# Use default configuration (no prompts)
+# Use default configuration (non-interactive, no prompts)
 npx bmad-method agent-install --defaults
 
 # Install to specific destination
diff --git a/src/modules/bmb/workflows/create-agent/workflow.yaml b/src/modules/bmb/workflows/create-agent/workflow.yaml
index 5710ac05..e989710c 100644
--- a/src/modules/bmb/workflows/create-agent/workflow.yaml
+++ b/src/modules/bmb/workflows/create-agent/workflow.yaml
@@ -31,9 +31,11 @@ validation: "{installed_path}/agent-validation-checklist.md"
 
 # Output configuration - YAML agents compiled to .md at install time
 # Module agents: Save to {bmad_folder}/{{target_module}}/agents/
-# Standalone agents: Save to custom_agent_location/
+# Standalone agents: Always create folders with agent + guide
 module_output_file: "{project-root}/{bmad_folder}/{{target_module}}/agents/{{agent_filename}}.agent.yaml"
-standalone_output_file: "{custom_agent_location}/{{agent_filename}}.agent.yaml"
+standalone_output_folder: "{custom_agent_location}/{{agent_filename}}"
+standalone_output_file: "{standalone_output_folder}/{{agent_filename}}.agent.yaml"
+standalone_info_guide: "{standalone_output_folder}/info-and-installation-guide.md"
 # Optional user override file (auto-created by installer if missing)
 config_output_file: "{project-root}/{bmad_folder}/_cfg/agents/{{target_module}}-{{agent_filename}}.customize.yaml"
 
@@ -46,6 +48,7 @@ web_bundle:
   web_bundle_files:
     - "{bmad_folder}/bmb/workflows/create-agent/instructions.md"
     - "{bmad_folder}/bmb/workflows/create-agent/checklist.md"
+    - "{bmad_folder}/bmb/workflows/create-agent/info-and-installation-guide.md"
     - "{bmad_folder}/bmb/docs/agent-compilation.md"
     - "{bmad_folder}/bmb/docs/understanding-agent-types.md"
     - "{bmad_folder}/bmb/docs/simple-agent-architecture.md"