agent create workflow overhaul to use data files efficiently. updated and created separate user guides for the create agent workflow along with general concept docs of what an agent and workflow are in regards to0 bmad generally.

Author: Brian Madison

docs/bmad-core-concepts/agents.md

@@ -0,0 +1,93 @@
+# Agents
+
+Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
+
+## Agent Types
+
+BMAD has two primary agent types, designed for different use cases:
+
+### Simple Agents
+
+**Self-contained, focused, ready to use.**
+
+Simple agents are complete in a single file. They excel at well-defined tasks and require minimal setup.
+
+**Best for:**
+- Single-purpose assistants (code review, documentation, commit messages)
+- Quick deployment
+- Projects that don't require persistent memory
+- Getting started fast
+
+**Example:** A commit message agent that reads your git diff and generates conventional commits.
+
+### Expert Agents
+
+**Powerful, memory-equipped, domain specialists.**
+
+Expert agents have a **sidecar** - a companion folder containing additional instructions, workflows, and memory files. They remember context across sessions and handle complex, multi-step tasks.
+
+**Best for:**
+- Domain specialists (security architect, game designer, product manager)
+- Tasks requiring persistent memory
+- Complex workflows with multiple stages
+- Projects that grow over time
+
+**Example:** A game architect that remembers your design decisions, maintains consistency across sprints, and coordinates with other specialists.
+
+## Key Differences
+
+| Feature          | Simple         | Expert                     |
+| ---------------- | -------------- | -------------------------- |
+| **Files**        | Single file    | Agent + sidecar folder     |
+| **Memory**       | Session only   | Persistent across sessions |
+| **Capabilities** | Focused scope  | Multi-domain, extensible   |
+| **Setup**        | Zero config    | Sidecar initialization     |
+| **Best Use**     | Specific tasks | Ongoing projects           |
+
+## Agent Components
+
+All agents share these building blocks:
+
+### Persona
+- **Role** - What the agent does (expertise domain)
+- **Identity** - Who the agent is (personality, character)
+- **Communication Style** - How the agent speaks (tone, voice)
+- **Principles** - Why the agent acts (values, decision framework)
+
+### Capabilities
+- Skills, tools, and knowledge the agent can apply
+- Mapped to specific menu commands
+
+### Menu
+- Interactive command list
+- Triggers, descriptions, and handlers
+- Auto-includes help and exit options
+
+### Critical Actions (optional)
+- Instructions that execute before the agent starts
+- Enable autonomous behaviors (e.g., "check git status before changes")
+
+## Which Should You Use?
+
+**Choose Simple when:**
+- You need a task done quickly and reliably
+- The scope is well-defined and won't change much
+- You don't need the agent to remember things between sessions
+
+**Choose Expert when:**
+- You're building something complex over time
+- The agent needs to maintain context (project history, decisions)
+- You want the agent to coordinate workflows or other agents
+- Domain expertise requires specialized knowledge bases
+
+## Creating Custom Agents
+
+BMAD provides the **BMAD Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](../modules/bmb-bmad-builder/agent-creation-guide.md) for step-by-step instructions.
+
+## Customizing Existing Agents
+
+You can modify any agent's behavior without editing core files. See [BMAD Customization](./bmad-customization/) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained.
+
+---
+
+**Next:** Learn about [Workflows](./workflows.md) to see how agents accomplish complex tasks.

…stomization/agent-customization-guide.md …re-concepts/bmad-customization/agents.mddocs/bmad-customization/agent-customization-guide.md renamed to docs/bmad-core-concepts/bmad-customization/agents.md docs/bmad-customization/agent-customization-guide.md renamed to docs/bmad-core-concepts/bmad-customization/agents.md

@@ -203,6 +203,8 @@ memories:
 
 ## Next Steps
 
-- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
-- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
-- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference
+- **[Learn about Agents](../agents.md)** - Understand Simple vs Expert agents
+- **[Agent Creation Guide](../../modules/bmb-bmad-builder/agent-creation-guide.md)** - Build completely custom agents
+- **[BMM Complete Documentation](../../modules/bmm-bmad-method/index)** - Full BMad Method reference
+
+[← Back to Customization](./index.md)

docs/bmad-core-concepts/bmad-customization/index.md

@@ -0,0 +1,26 @@
+# BMAD Customization
+
+Personalize agents and workflows to match your needs.
+
+## Guides
+
+| Guide | Description |
+|-------|-------------|
+| **[Agent Customization](./agents.md)** | Modify agent behavior without editing core files |
+| **[Workflow Customization](./workflows.md)** | Customize and optimize workflows |
+
+## Overview
+
+BMAD provides two main customization approaches:
+
+### Agent Customization
+Modify any agent's persona, name, capabilities, or menu items using `.customize.yaml` files in `_bmad/_config/agents/`. Your customizations persist through updates.
+
+### Workflow Customization
+Replace or extend workflow steps to create tailored processes. (Coming soon)
+
+---
+
+**Next:** Read the [Agent Customization Guide](./agents.md) to start personalizing your agents.
+
+[← Back to Core Concepts](../index.md)

docs/bmad-core-concepts/bmad-customization/workflows.md

@@ -0,0 +1,30 @@
+# Workflow Customization Guide
+
+Customize and optimize workflows with step replacement and hooks.
+
+## Status
+
+> **Coming Soon:** Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
+
+## What to Expect
+
+Workflow customization will allow you to:
+
+- **Replace Steps** - Swap out specific workflow steps with custom implementations
+- **Add Hooks** - Inject custom behavior before/after workflow steps
+- **Extend Workflows** - Create new workflows based on existing ones
+- **Override Behavior** - Customize workflow logic for your project's needs
+
+## For Now
+
+While workflow customization is in development, you can:
+
+- **Create Custom Workflows** - Use the BMAD Builder to create entirely new workflows
+- **Customize Agents** - Modify agent behavior using [Agent Customization](./agents.md)
+- **Provide Feedback** - Share your workflow customization needs with the community
+
+---
+
+**In the meantime:** Learn how to [create custom workflows](../../modules/bmb-bmad-builder/index) from scratch.
+
+[← Back to Customization](./index.md)

docs/bmad-core-concepts/index.md

@@ -0,0 +1,37 @@
+# BMAD Core Concepts
+
+Understanding the fundamental building blocks of the BMAD Method.
+
+## The Essentials
+
+| Concept | Description | Guide |
+|---------|-------------|-------|
+| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](./agents.md) |
+| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](./workflows.md) |
+| **Modules** | Packaged collections of agents and workflows | [Modules Guide](./modules.md) |
+
+## Getting Started
+
+### New to BMAD?
+Start here to understand what BMAD is and how it works:
+
+1. **[Agents Guide](./agents.md)** - Learn about Simple and Expert agents
+2. **[Workflows Guide](./workflows.md)** - Understand how workflows orchestrate tasks
+3. **[Modules Guide](./modules.md)** - See how modules organize functionality
+
+### Installing BMAD
+
+- **[Installation Guide](./installing/)** - Set up BMAD in your project
+- **[Upgrading from v4](./installing/upgrading.md)** - Migrate from earlier versions
+
+### Configuration
+
+- **[BMAD Customization](./bmad-customization/)** - Personalize agents and workflows
+
+### Advanced
+
+- **[Web Bundles](./web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
+
+---
+
+**Next:** Read the [Agents Guide](./agents.md) to understand the core building block of BMAD.

docs/installing-bmad.md …s/bmad-core-concepts/installing/index.mddocs/installing-bmad.md renamed to docs/bmad-core-concepts/installing/index.md docs/installing-bmad.md renamed to docs/bmad-core-concepts/installing/index.md

@@ -1,5 +1,13 @@
 # Installation
 
+Get BMAD up and running in your project.
+
+## Upgrading?
+
+If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md).
+
+---
+
 ## Quick Install
 
 ```bash
@@ -52,8 +60,9 @@ your-project/
 
 ## Next Steps
 
-1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
-2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
+1. **Read the [Quick Start Guide](../../modules/bmm-bmad-method/quick-start)** to build your first feature
+2. **Explore [Workflows](../../modules/bmm-bmad-method/index#-workflow-guides)** to understand the methodology
+3. **Learn about [Agents](../agents.md)** to understand BMAD's core building blocks
 
 ## Troubleshooting
 

docs/v4-to-v6-upgrade.md …ad-core-concepts/installing/upgrading.mddocs/v4-to-v6-upgrade.md renamed to docs/bmad-core-concepts/installing/upgrading.md docs/v4-to-v6-upgrade.md renamed to docs/bmad-core-concepts/installing/upgrading.md

@@ -120,7 +120,7 @@ persona:
     - Always upbeat and adventurous
 ```
 
-There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](bmad-customization/agent-customization-guide.md)
+There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md)
 
 CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations.
 

docs/bmad-core-concepts/modules.md

@@ -0,0 +1,76 @@
+# Modules
+
+Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
+
+## What is a Module?
+
+A module is a self-contained package that includes:
+
+- **Agents** - Specialized AI assistants
+- **Workflows** - Step-by-step processes
+- **Configuration** - Module-specific settings
+- **Documentation** - Usage guides and reference
+
+## Official Modules
+
+### Core Module
+Always installed, provides shared functionality:
+- Global configuration
+- Core workflows (Party Mode, Advanced Elicitation, Brainstorming)
+- Common tasks (document indexing, sharding, review)
+
+### BMAD Method (BMM)
+Software and game development:
+- Project planning workflows
+- Implementation agents (Dev, PM, QA, Scrum Master)
+- Testing and architecture guidance
+
+### BMAD Builder (BMB)
+Create custom solutions:
+- Agent creation workflows
+- Workflow authoring tools
+- Module scaffolding
+
+### Creative Intelligence Suite (CIS)
+Innovation and creativity:
+- Creative thinking techniques
+- Innovation strategy workflows
+- Storytelling and ideation
+
+### BMAD Game Dev (BMGD)
+Game development specialization:
+- Game design workflows
+- Narrative development
+- Performance testing frameworks
+
+## Module Structure
+
+Installed modules follow this structure:
+
+```
+_bmad/
+├── core/           # Always present
+├── bmm/            # BMAD Method (if installed)
+├── bmb/            # BMAD Builder (if installed)
+├── cis/            # Creative Intelligence (if installed)
+└── bmgd/           # Game Dev (if installed)
+```
+
+## Custom Modules
+
+You can create your own modules containing:
+- Custom agents for your domain
+- Organizational workflows
+- Team-specific configurations
+
+Custom modules are installed the same way as official modules.
+
+## Installing Modules
+
+During BMAD installation, you choose which modules to install. You can also add or remove modules later by re-running the installer.
+
+See [Installation Guide](./installing/) for details.
+
+---
+
+**Next:** Read the [Installation Guide](./installing/) to set up BMAD with the modules you need.

docs/bmad-core-concepts/web-bundles/index.md

@@ -0,0 +1,34 @@
+# Web Bundles
+
+Use BMAD agents in Gemini Gems and Custom GPTs.
+
+## Status
+
+> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality.
+
+## What Are Web Bundles?
+
+Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
+
+### What's Included
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- No external files required
+
+### Use Cases
+
+**Perfect for:**
+- Uploading a single file to a Gemini GEM or Custom GPT
+- Using BMAD Method from the Web
+- Cost savings (generally lower cost than local usage)
+- Quick sharing of agent configurations
+
+**Trade-offs:**
+- Some quality reduction vs local usage
+- Less convenient than full local installation
+- Limited to agent capabilities (no workflow file access)
+
+[← Back to Core Concepts](../index.md)