bmad-method 6.0.0-alpha.20 → 6.0.0-alpha.22

package/.vscode/settings.json

@@ -57,6 +57,7 @@
     "tileset",
     "tmpl",
     "Trae",
+    "Unsharded",
     "VNET",
     "webskip"
   ],

package/CHANGELOG.md

@@ -1,5 +1,255 @@
 # Changelog
 
+## [6.0.0-alpha.22]
+
+**Release: December 31, 2025**
+
+### 🌟 Key Highlights
+
+1. **Unified Agent Workflow**: Create, Edit, and Validate workflows consolidated into single powerful agent workflow with separate step paths
+2. **Agent Knowledge System**: Comprehensive data file architecture with persona properties, validation patterns, and crafting principles
+3. **Deep Language Integration**: All sharded progressive workflows now support language choice at every step
+4. **Core Module Documentation**: Extensive docs for core workflows (brainstorming, party mode, advanced elicitation)
+5. **BMAD Core Concepts**: New documentation structure explaining agents, workflows, modules, and installation
+6. **Tech Spec Sharded**: create-tech-spec workflow converted to sharded format with orient-first pattern
+
+### 🤖 Unified Agent Workflow (Major Feature)
+
+**Consolidated Architecture:**
+
+- **Single Workflow, Three Paths**: Create, Edit, and Validate operations unified under `src/modules/bmb/workflows/agent/`
+- **steps-c/**: Create path with 9 comprehensive steps for building new agents
+- **steps-e/**: Edit path with 10 steps for modifying existing agents
+- **steps-v/**: Validate path for standalone agent validation review
+- **data/**: Centralized knowledge base for all agent-building intel
+
+### 📚 Agent Knowledge System
+
+**Data File Architecture:**
+
+Located in `src/modules/bmb/workflows/agent/data/`:
+
+- **agent-metadata.md** (208 lines) - Complete metadata field reference
+- **agent-menu-patterns.md** (233 lines) - Menu design patterns and best practices
+- **agent-compilation.md** (273 lines) - Compilation process documentation
+- **persona-properties.md** (266 lines) - Persona crafting properties and examples
+- **principles-crafting.md** (292 lines) - Core principles for agent design
+- **critical-actions.md** (120 lines) - Critical action patterns
+- **expert-agent-architecture.md** (236 lines) - Expert agent structure
+- **expert-agent-validation.md** (173 lines) - Expert-specific validation
+- **module-agent-validation.md** (124 lines) - Module-specific validation
+- **simple-agent-architecture.md** (204 lines) - Simple agent structure
+- **simple-agent-validation.md** (132 lines) - Simple agent validation
+- **understanding-agent-types.md** (222 lines) - Agent type comparison
+- **brainstorm-context.md** - Brainstorming guidance
+- **communication-presets.csv** - Communication style presets
+
+**Reference Examples:**
+
+- **reference/module-examples/architect.agent.yaml** - Module agent example
+- **reference/simple-examples/commit-poet.agent.yaml** - Simple agent example
+- **journal-keeper/** - Complete sidecar pattern example
+
+**Templates:**
+
+- **templates/simple-agent.template.md** - Simple agent template
+- **templates/expert-agent-template/expert-agent.template.md** - Expert agent template
+- **templates/expert-agent-sidecar/** - Sidecar templates (instructions, memories)
+
+### 🌍 Deep Language Integration
+
+**Progressive Workflow Language Support:**
+
+- **Every Step Biased**: All sharded progressive workflow steps now include language preference context
+- **260+ Files Updated**: Comprehensive language integration across:
+  - Core workflows (brainstorming, party mode, advanced elicitation)
+  - BMB workflows (create-agent, create-module, create-workflow, edit-workflow, etc.)
+  - BMGD workflows (game-brief, gdd, narrative, game-architecture, etc.)
+  - BMM workflows (research, create-ux-design, prd, create-architecture, etc.)
+- **Tested Languages**: Verified working with Spanish and Pirate Speak
+- **Natural Conversations**: AI agents respond in configured language throughout workflow
+
+### 📖 Core Module Documentation
+
+**New Core Documentation Structure:**
+
+`docs/modules/core/`:
+
+- **index.md** - Core module overview
+- **core-workflows.md** - Core workflow documentation
+- **core-tasks.md** - Core task reference
+- **brainstorming.md** (100 lines) - Brainstorming workflow guide
+- **party-mode.md** (50 lines) - Party mode guide
+- **advanced-elicitation.md** (105 lines) - Advanced elicitation techniques
+- **document-sharding-guide.md** (133 lines) - Sharded workflow format guide
+- **global-core-config.md** - Global core configuration reference
+
+**Advanced Elicitation Moved:**
+
+- **From**: `docs/` root
+- **To**: `src/core/workflows/advanced-elicitation/`
+- **Status**: Now a proper core workflow with methods.csv
+
+### 📚 BMAD Core Concepts Documentation
+
+**New Documentation Structure:**
+
+`docs/bmad-core-concepts/`:
+
+- **index.md** - Core concepts introduction
+- **agents.md** (93 lines) - Understanding agents in BMAD
+- **workflows.md** (89 lines) - Understanding workflows in BMAD
+- **modules.md** (76 lines) - Understanding modules (BMM, BMGD, CIS, BMB, Core)
+- **installing/index.md** (77 lines) - Installation guide
+- **installing/upgrading.md** (144 lines) - Upgrading guide
+- **bmad-customization/index.md** - Customization overview
+- **bmad-customization/agents.md** - Agent customization guide
+- **bmad-customization/workflows.md** (30 lines) - Workflow customization guide
+- **web-bundles/index.md** (34 lines) - Web bundle distribution guide
+
+**Documentation Cleanup:**
+
+- **Removed v4-to-v6-upgrade.md** - Outdated upgrade guide
+- **Removed document-sharding-guide.md** from docs root (moved to core)
+- **Removed web-bundles-gemini-gpt-guide.md** - Consolidated into web-bundles/index.md
+- **Removed getting-started/installation.md** - Migrated to bmad-core-concepts
+- **Removed all ide-info/*.md files** - Consolidated into web-bundles documentation
+
+### 🔧 Create-Tech-Spec Sharded Conversion
+
+**Monolithic to Sharded:**
+
+- **From**: Single `workflow.yaml` with `instructions.md`
+- **To**: Sharded `workflow.md` with individual step files
+- **Pattern**: Orient-first approach (understand before investigating)
+
+### 🔨 Additional Improvements
+
+**Workflow Status Path Fixes:**
+
+- **Corrected Discovery Paths**: workflow-status workflows now properly use planning_artifacts and implementation_artifacts
+- **Updated All Path Files**: enterprise-brownfield, enterprise-greenfield, method-brownfield, method-greenfield
+
+**Documentation Updates:**
+
+- **BMB Agent Creation Guide**: Comprehensive 166-line guide for agent creation
+- **Workflow Vendoring Doc**: New 42-line guide on workflow customization and inheritance
+- **Document Project Reference**: Moved from BMM docs to shared location
+- **Workflows Planning Guide**: New 89-line guide for planning workflows
+
+**BMB Documentation Streamlining:**
+
+- **Removed Redundant Docs**: Eliminated duplicate documentation in `src/modules/bmb/docs/`
+- **Step File Rules**: New 469-line comprehensive guide for step file creation
+- **Agent Docs Moved**: Agent architecture and validation docs moved to workflow data/
+
+**Windows Inquirer Fix:**
+
+- **Another Default Addition**: Additional inquirer default value setting for better Windows multiselection support
+
+**Code Quality:**
+
+- **Removed Old BMM README**: Consolidated module documentation
+- **Removed BMM Troubleshooting**: 661-line doc moved to shared location
+- **Removed Enterprise Agentic Development**: 686-line doc consolidated
+- **Removed Scale Adaptive System**: 618-line doc consolidated
+
+---
+
+## [6.0.0-alpha.21]
+
+**Release: December 27, 2025**
+
+### 🌟 Key Highlights
+
+1. **Consistent Menu System**: All agents now use standardized 2-letter menu codes (e.g., "rd" for research, "ca" for create-architecture)
+2. **Planning Artifacts Architecture**: Phase 1-3 workflows now properly segregate planning artifacts from documentation
+3. **Windows Installer Fixed Again**: Updated inquirer to resolve multiselection tool issues
+4. **Auto-Injected Features**: Chat and party mode automatically injected into all agents
+5. **Validation System**: All agents now pass comprehensive new validation checks
+
+### 🎯 Consistent Menu System (Major Feature)
+
+**Standardized 2-Letter Codes:**
+
+- **Compound Menu Triggers**: All agents now use consistent 2-letter compound trigger format (e.g., `bmm-rd`, `bmm-ca`)
+- **Improved UX**: Shorter, more memorable command shortcuts across all modules
+- **Module Prefixing**: Menu items properly scoped by module prefix (bmm-, bmgd-, cis-, bmb-)
+- **Universal Pattern**: All 22 agents updated to follow the same menu structure
+
+**Agent Updates:**
+
+- **BMM Module**: 9 agents with standardized menus (pm, analyst, architect, dev, ux-designer, tech-writer, sm, tea, quick-flow-solo-dev)
+- **BMGD Module**: 6 agents with standardized menus (game-architect, game-designer, game-dev, game-qa, game-scrum-master, game-solo-dev)
+- **CIS Module**: 6 agents with standardized menus (innovation-strategist, design-thinking-coach, creative-problem-solver, brainstorming-coach, presentation-master, storyteller)
+- **BMB Module**: 3 agents with standardized menus (bmad-builder, agent-builder, module-builder, workflow-builder)
+- **Core Module**: BMAD Master agent updated with consistent menu patterns
+
+### 📁 Planning Artifacts Architecture
+
+**Content Segregation Implementation:**
+
+- **Phase 1-3 Workflows**: All planning workflows now use `planning_artifacts` folder (default changed from `docs`)
+- **Proper Input Discovery**: Workflows follow consistent input discovery patterns from planning artifacts
+- **Output Management**: Planning artifacts properly separated from long-term documentation
+- **Affected Workflows**:
+  - Product Brief: Updated discovery and output to planning artifacts
+  - PRD: Fixed discovery and output to planning artifacts
+  - UX Design: Updated all steps for proper artifact handling
+  - Architecture: Updated discovery and output flow
+  - Game Architecture: Updated for planning artifacts
+  - Story Creation: Updated workflow output paths
+
+**File Organization:**
+
+- **Planning Artifacts**: Ephemeral planning documents (prd.md, product-brief.md, ux-design.md, architecture.md)
+- **Documentation**: Long-term project documentation (separate from planning)
+- **Module Configuration**: BMM and BMGD modules updated with proper default paths
+
+### 🪟 Windows Installer Fixes
+
+**Inquirer Multiselection Fix:**
+
+- **Updated Inquirer Version**: Resolved tool multiselection issues that were causing Windows installer failures
+- **Better Compatibility**: Improved handling of checkbox and multi-select prompts on Windows(?)
+
+### 🤖 Agent System Improvements
+
+**Auto-Injected Features:**
+
+- **Chat Mode**: Automatically injected into all agents during compilation
+- **Party Mode**: Automatically injected into all agents during compilation
+- **Reduced Manual Configuration**: No need to manually add these features to agent definitions
+- **Consistent Behavior**: All agents now have uniform access to chat and party mode capabilities
+
+**Agent Normalization:**
+
+- **All Agents Validated**: All 22 agents pass comprehensive validation checks
+- **Schema Enforcement**: Proper compound trigger validation implemented
+- **Metadata Cleanup**: Removed obsolete and inconsistent metadata patterns
+- **Test Fixtures Updated**: Validation test fixtures aligned with new requirements
+
+### 🔧 Bug Fixes & Cleanup
+
+**Docusaurus Merge Recovery:**
+
+- **Restored Agent Files**: Fixed agent files accidentally modified in Docusaurus merge (PR #1191)
+- **Reference Cleanup**: Removed obsolete agent reference examples (journal-keeper, security-engineer, trend-analyst)
+- **Test Fixture Updates**: Aligned test fixtures with current validation requirements
+
+**Code Quality:**
+
+- **Schema Improvements**: Enhanced agent schema validation with better error messages
+- **Removed Redundancy**: Cleaned up duplicate and obsolete agent definitions
+- **Installer Cleanup**: Removed unused configuration code from BMM installer
+
+**Planning Artifacts Path:**
+- Default: `planning_artifacts/` (configurable in module.yaml)
+- Previous: `docs/`
+- Benefit: Clear separation between planning work and permanent documentation
+
+---
+
 ## [6.0.0-alpha.20]
 
 **Release: December 23, 2025**

package/README.md

@@ -24,9 +24,8 @@ The completely revamped **BMAD V6 installer** now includes built-in support for
 
 **📚 Learn More:**
 
-- [**Custom Content Overview**](./docs/custom-content.md) - Discover all supported content types
-- [**Installation Guide**](./docs/custom-content-installation.md) - Learn to create and install custom content
-- [**Detail Content Docs**](./src/modules/bmb/docs/index.md) - Reference details for agents, modules, workflows and the bmad builder
+- [**Custom Content Overview**](docs/modules/bmb-bmad-builder/custom-content.md) - Discover all supported content types
+- [**Installation Guide**](docs/modules/bmb-bmad-builder/custom-content-installation.md) - Learn to create and install custom content
 - [**2 Very simple Custom Modules of questionable quality**](./samples/sample-custom-modules/README.md) - if you want to download and try to install a custom shared module, get an idea of how to bundle and share your own, or create your own personal agents, workflows and modules.
 
 </div>
@@ -68,7 +67,7 @@ With **BMad Builder**, you can architect both simple agents and vastly complex d
 ## 📊 See It In Action
 
 <p align="center">
-  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
+  <img src="./docs/modules/bmm-bmad-method/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
 </p>
 
 <p align="center">
@@ -80,13 +79,18 @@ With **BMad Builder**, you can architect both simple agents and vastly complex d
 ### 1. Install BMad Method
 
 ```bash
-# Install v6 Alpha (recommended)
+# Install v6 RECOMMENDED
 npx bmad-method@alpha install
+```
 
-# Or stable v4 for production
+```bash
+# Install v4 Legacy (not recommended if starting fresh)
 npx bmad-method install
+# OR
+npx bmad-method@latest install
 ```
 
+
 ### 2. Initialize Your Project
 
 Load any agent in your IDE and run:
@@ -101,8 +105,8 @@ This analyzes your project and recommends the right workflow track.
 
 BMad Method adapts to your needs with three intelligent tracks:
 
-| Track              | Use For                   | Planning                | Time to Start |
-| ------------------ | ------------------------- | ----------------------- | ------------- |
+| Track             | Use For                   | Planning                | Time to Start |
+| ----------------- | ------------------------- | ----------------------- | ------------- |
 | **⚡ Quick Flow**  | Bug fixes, small features | Tech spec only          | < 5 minutes   |
 | **📋 BMad Method** | Products, platforms       | PRD + Architecture + UX | < 15 minutes  |
 | **🏢 Enterprise**  | Compliance, scale         | Full governance suite   | < 30 minutes  |
@@ -124,35 +128,35 @@ Each phase has specialized workflows and agents working together to deliver exce
 
 **12 Specialized Agents** working in concert:
 
-| Development | Architecture   | Product       | Leadership     |
-| ----------- | -------------- | ------------- | -------------- |
-| Developer   | Architect      | PM            | Scrum Master   |
-| UX Designer | Test Architect | Analyst       | BMad Master    |
-| Tech Writer | Game Architect | Game Designer | Game Developer |
+| Development | Architecture   | Product     | Leadership   |
+| ----------- | -------------- | ----------- | ------------ |
+| Developer   | Architect      | PM          | Scrum Master |
+| UX Designer | Test Architect | Analyst     | BMad Master  |
+|             |                | Tech Writer |              |
 
-**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
+**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready web app fixture-based utilities.
 
 Each agent brings deep expertise and can be customized to match your team's style.
 
 ## 📦 What's Included
 
-### Core Modules
+### Official Modules
 
 - **BMad Method (BMM)** - Complete agile development framework
   - 12 specialized agents
   - 34 workflows across 4 phases
-  - Scale-adaptive planning
-  - [→ Documentation Hub](./src/modules/bmm/docs/index.md)
+  - Stand Along Quick Spec Flow for a streamlined simple implementation process
+  - [→ Documentation Hub](./docs/modules/bmm-bmad-method/index.md)
 
 - **BMad Builder (BMB)** - Create custom agents and workflows
   - Build anything from simple agents to complex modules
   - Create domain-specific solutions (legal, medical, finance, education)
-  - [→ Builder Guide](./src/modules/bmb/docs/index.md)
+  - [→ Builder Guide](./docs/modules/bmb-bmad-builder/index.md)
 
 - **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
   - Brainstorming, design thinking, storytelling
   - 5 creative facilitation workflows
-  - [→ Creative Workflows](./src/modules/cis/docs/index.md)
+  - [→ Creative Workflows](./docs/modules/cis-creative-intelligence-suite/index.md)
 
 ### Key Features
 
@@ -166,14 +170,14 @@ Each agent brings deep expertise and can be customized to match your team's styl
 
 ### Quick Links
 
-- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
-- **[Complete BMM Documentation](./src/modules/bmm/docs/index.md)** - All guides and references
-- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
+- **[Quick Start Guide](./docs/modules/bmm-bmad-method/quick-start.md)** - 15-minute introduction
+- **[Complete BMM Documentation](./docs/modules/bmm-bmad-method/index.md)** - All guides and references
+- **[Agent Customization](docs/bmad-customization/agent-customization-guide.md)** - Personalize your agents
 - **[All Documentation](./docs/index.md)** - Complete documentation index
 
 ### For v4 Users
 
-- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4/docs)**
 - **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
 
 ## 💬 Community & Support
@@ -181,24 +185,12 @@ Each agent brings deep expertise and can be customized to match your team's styl
 - **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
 - **[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
+- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles (Currently not functioning, reworking soon)
 - **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines
 
 ## 🛠️ Development
 
-For contributors working on the BMad codebase:
-
-```bash
-# Run all quality checks
-npm test
-
-# Development commands
-npm run lint:fix      # Fix code style
-npm run format:fix    # Auto-format code
-npm run bundle        # Build web bundles
-```
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
+If you would like to contribute, first check the [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
 
 ## What's New in v6
 

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

package/docs/{agent-customization-guide.md → bmad-core-concepts/bmad-customization/agents.md}

@@ -81,7 +81,7 @@ Add your own workflows to the agent's menu:
 ```yaml
 menu:
   - trigger: my-workflow
-    workflow: '{project-root}/custom/my-workflow.yaml'
+    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
     description: My custom workflow
   - trigger: deploy
     action: '#deploy-prompt'
@@ -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)

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

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

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