6.0.0-alpha.3

README.md

@@ -7,254 +7,202 @@
 
 > **🚨 ALPHA VERSION DOCUMENTATION**
 >
-> This README documents **BMad v6 (Alpha)** - currently under active development.
+> - **Install v6 Alpha:** `npx bmad-method@alpha install`
->
+> - **Install stable v4:** `npx bmad-method install`
-> **To install v6 Alpha:** `npx bmad-method@alpha install`
+> - **[View v4 documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
->
-> **Looking for stable v4 documentation?** [View v4 README](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)
->
-> **Want the stable version?** `npx bmad-method install` (installs v4.x)
 
-## The Universal Human-AI Collaboration Platform
+## Universal Human-AI Collaboration Platform
 
-BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMad-CORE guides you through reflective workflows that bring out your best ideas and the AI's full capabilities.
+BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.
 
-**🎯 Human Amplification, Not Replacement** • **🎨 Works in Any Domain** • **⚡ Powered by Specialized Agents**
+**🎯 Human Amplification** • **🎨 Domain Agnostic** • **⚡ Agent-Powered**
 
----
+## Table of Contents
 
-## 🔄 Upgrading from v4?
+- [Quick Start](#quick-start)
-
+- [What is BMad-CORE?](#what-is-bmad-core)
-**[→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Complete migration instructions for existing v4 users
+- [Modules](#modules)
-
+  - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development)
----
+  - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions)
-
+  - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity)
-## What is BMad-CORE?
+- [Installation](#installation)
-
+- [Key Features](#key-features)
-BMad-CORE is the **universal foundation** that powers all BMad modules. It provides:
+- [Documentation](#documentation)
-
+- [Community & Support](#community--support)
-- **Agent orchestration framework** for specialized AI personas
-- **Workflow execution engine** for guided processes
-- **Modular architecture** allowing domain-specific extensions
-- **IDE integrations** across multiple development environments
-- **Update-safe customization system** for all agents and workflows
-
-### Core v6 Framework Enhancements
-
-**All modules benefit from these new core capabilities:**
-
-- **🎨 Full Agent Customization** - Modify any agent's name, role, personality, and behavior via `bmad/_cfg/agents/` customize files that survive all updates
-- **🌐 Multi-Language Support** - Choose your language for both agent communication and documentation output independently
-- **👤 User Personalization** - Agents address you by name and adapt to your technical level and preferences
-- **🔄 Update-Safe Configuration** - Your customizations persist through framework and module updates
-- **⚙️ Flexible Settings** - Configure communication style, technical depth, output formats, and more per module or globally
-
-### The C.O.R.E. Philosophy
-
-- **C**ollaboration: Human-AI partnership where both contribute unique strengths
-- **O**ptimized: Refined processes for maximum effectiveness
-- **R**eflection: Guided thinking that unlocks better solutions
-- **E**ngine: Powerful framework orchestrating specialized agents and workflows
-
-Instead of giving you answers, BMad-CORE helps you **discover better solutions** through strategic questioning, expert guidance, and structured thinking.
-
----
-
-## The BMad Method - Agile AI-Driven Development
-
-**The flagship module for software and game development excellence.**
-
-The BMad Method (BMM) is a complete AI-driven agile development framework that revolutionizes how you build software and games. Whether you're fixing a bug, building a feature, or architecting an enterprise system, BMM adapts to your needs.
-
-### What's New in v6?
-
-**🎯 Revolutionary Scale-Adaptive Workflows**
-
-- **Levels 0-4**: Automatically adjusts from quick fixes to enterprise-scale projects
-- **Greenfield & Brownfield**: Full support for new projects and existing codebases
-- **Smart Context Engine**: New optimized brownfield documentation engine that understands your existing code
-
-**🏗️ Project-Adaptive Architecture**
-
-- Architecture documents that adapt to YOUR project type (web, mobile, embedded, game, etc.)
-- No more "one-size-fits-all" templates
-- Specialized sections based on what you're actually building
-- Game development fully integrated with engine-specific guidance (Unity, Phaser, Godot, Unreal, and more)
-
-**⚡ From Simple to Complex - All in One System**
-
-- **Level 0-1**: Quick fixes and small features with minimal overhead
-- **Level 2**: Feature development with lightweight planning
-- **Level 3-4**: Full enterprise workflows with comprehensive documentation
-- Seamless workflow progression as complexity grows
-
-**💬 Highly Interactive & Guided**
-
-- Interactive workflows that ask the right questions
-- Agents guide you through discovery rather than giving generic answers
-- Context-aware recommendations based on your project state
-- Real-time validation and course correction
-
-**📋 Four-Phase Methodology**
-
-1. **Analysis** (Optional) - Brainstorming, research, product briefs
-2. **Planning** (Required) - Scale-adaptive PRD/GDD generation
-3. **Solutioning** (Level 3-4) - Adaptive architecture and tech specs
-4. **Implementation** (Iterative) - Story creation, context gathering, development, review
-
-### Specialized Agents
-
-- **PM** - Product planning and requirements
-- **Analyst** - Research and business analysis
-- **Architect** - Technical architecture and design
-- **Scrum Master** - Sprint planning and story management
-- **Developer** - Implementation with senior dev review
-- **Game Development** (Optional) - Game Designer, Game Developer, Game Architect
-- **And more** - UX, Test Architect, and other specialized roles
-
-### Documentation
-
-- **[📚 Complete BMM Documentation](./src/modules/bmm/README.md)** - Full module reference
-- **[📖 BMM Workflows Guide](./src/modules/bmm/workflows/README.md)** - Essential reading for using BMM
-
----
-
-## Additional Beta Modules
-
-### **[BMad Builder (BMB)](./src/modules/bmb/README.md)** - Create Custom Solutions
-
-Build your own agents, workflows, and modules using the BMad-CORE framework.
-
-- **Agent Creation**: Design specialized agents with custom roles and behaviors
-- **Workflow Design**: Build structured multi-step processes
-- **Module Development**: Package complete solutions for any domain
-- **Three Agent Types**: Full module, hybrid, and standalone agents
-
-**[📚 Complete BMB Documentation](./src/modules/bmb/README.md)** | **[🎯 Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
-
----
-
-### **[Creative Intelligence Suite (CIS)](./src/modules/cis/readme.md)** - Innovation & Creativity
-
-Transform creative and strategic thinking through AI-powered facilitation across five specialized domains.
-
-- **5 Interactive Workflows**: Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
-- **150+ Creative Techniques**: Proven frameworks and methodologies
-- **5 Specialized Agents**: Each with unique personas and facilitation styles
-- **Shared Resource**: Powers creative workflows in other modules (e.g., BMM brainstorming)
-
-**[📚 Complete CIS Documentation](./src/modules/cis/readme.md)** | **[📖 CIS Workflows](./src/modules/cis/workflows/README.md)**
-
----
 
 ## Quick Start
 
-### Prerequisites
+- **New to v6?** [→ BMad Method V6 Quick Start Guide](./docs/BMad-Method-V6-Quick-Start.md)
+- **Upgrading?** [→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)
 
-- **Node.js v20+** ([Download](https://nodejs.org))
+## What is BMad-CORE?
 
-### Installation
+Foundation framework powering all BMad modules:
 
-Install BMad to your project using npx:
+- **Agent Orchestration** - Specialized AI personas with unique capabilities
+- **Workflow Engine** - Guided multi-step processes
+- **Modular Architecture** - Domain-specific extensions
+- **IDE Integration** - Works across development environments
+- **Update-Safe Customization** - Persistent configuration through updates
+
+### v6 Core Enhancements
+
+- **🎨 Agent Customization** - Modify names, roles, personalities via `bmad/_cfg/agents/`
+- **🌐 Multi-Language** - Independent language settings for communication and output
+- **👤 Personalization** - Agents adapt to your name, technical level, preferences
+- **🔄 Persistent Config** - Customizations survive all updates
+- **⚙️ Flexible Settings** - Module or global configuration options
+
+### C.O.R.E. Philosophy
+
+- **C**ollaboration: Human-AI partnership leveraging unique strengths
+- **O**ptimized: Refined processes for maximum effectiveness
+- **R**eflection: Guided thinking unlocking better solutions
+- **E**ngine: Framework orchestrating specialized agents and workflows
+
+BMad-CORE helps you **discover better solutions** through strategic questioning and structured thinking.
+
+## Modules
+
+### BMad Method (BMM) - Agile AI Development
+
+AI-driven agile framework revolutionizing software and game development. Adapts from bug fixes to enterprise systems.
+
+#### v6 Highlights
+
+**🎯 Scale-Adaptive Workflows (Levels 0-4)**
+
+- Automatically adjusts complexity from quick fixes to enterprise projects
+- Greenfield & brownfield support with smart context engine
+
+**🏗️ Project-Adaptive Architecture**
+
+- Documents adapt to project type (web, mobile, embedded, game)
+- Engine-specific game development (Unity, Phaser, Godot, Unreal)
+
+**📋 Four-Phase Methodology**
+
+1. **Analysis** - Brainstorming, research, briefs
+2. **Planning** - Scale-adaptive PRD/GDD
+3. **Solutioning** - Architecture and tech specs
+4. **Implementation** - Stories, development, review
+
+**Specialized Agents**: PM, Analyst, Architect, Scrum Master, Developer, Game Designer/Developer/Architect, UX, Test Architect
+
+**Documentation**: [📚 BMM Module](./src/modules/bmm/README.md) | [📖 Workflows Guide](./src/modules/bmm/workflows/README.md)
+
+### BMad Builder (BMB) - Create Custom Solutions
+
+Build custom agents, workflows, and modules using BMad-CORE framework.
+
+- **Agent Creation** - Custom roles and behaviors
+- **Workflow Design** - Structured multi-step processes
+- **Module Development** - Complete domain solutions
+- **Three Agent Types** - Full module, hybrid, standalone
+
+**Documentation**:
+
+- [📚 BMB Module](./src/modules/bmb/README.md) - Complete module reference
+- [🎯 Create Agent](./src/modules/bmb/workflows/create-agent/README.md) - Agent builder workflow
+- [📋 Create Workflow](./src/modules/bmb/workflows/create-workflow/README.md) - Workflow designer
+- [📦 Create Module](./src/modules/bmb/workflows/create-module/README.md) - Module scaffolding
+
+### Creative Intelligence Suite (CIS) - Innovation & Creativity
+
+AI-powered creative facilitation across five domains.
+
+- **5 Interactive Workflows** - Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
+- **150+ Creative Techniques** - Proven frameworks and methodologies
+- **5 Specialized Agents** - Unique personas and facilitation styles
+- **Shared Resource** - Powers creative workflows in other modules
+
+**Documentation**: [📚 CIS Module](./src/modules/cis/README.md) | [📖 CIS Workflows](./src/modules/cis/workflows/README.md)
+
+## Installation
+
+**Prerequisites**: Node.js v20+ ([Download](https://nodejs.org))
 
 ```bash
-# Install v6 Alpha (this version)
+# Install v6 Alpha
 npx bmad-method@alpha install
 
-# Install stable v4 (production-ready)
+# Install stable v4
 npx bmad-method install
 ```
 
-The interactive installer will guide you through:
+Interactive installer guides you through:
 
-1. **Project location** - Where to install BMad
+1. **Project location** - Installation directory
-2. **Module selection** - Choose which modules you need (BMM, BMB, CIS)
+2. **Module selection** - BMM, BMB, CIS
-3. **Configuration** - Set your name, language preferences, and module options
+3. **Configuration** - Name, language, game dev options
-   - **Game Development (Optional)**: When installing BMM, you can optionally include game development agents and workflow!
+4. **IDE integration** - Environment setup
-4. **IDE integration** - Configure your development environment
 
-### What Gets Installed
+### Project Structure
-
-All modules install to a single `bmad/` folder in your project:
 
 ```
 your-project/
 └── bmad/
-    ├── core/         # Core framework (always installed)
+    ├── core/         # Core framework
-    ├── bmm/          # BMad Method (if selected)
+    ├── bmm/          # BMad Method
-    ├── bmb/          # BMad Builder (if selected)
+    ├── bmb/          # BMad Builder
-    ├── cis/          # Creative Intelligence Suite (shared resources)
+    ├── cis/          # Creative Intelligence
     └── _cfg/         # Your customizations
-        └── agents/   # Agent customization files
+        └── agents/   # Agent configs
 ```
 
-### Getting Started with BMM
+### Getting Started
 
-After installation, activate the Analyst agent in your IDE and run:
+After installation, activate Analyst agent and run:
 
-```bash
+```
 /workflow-init
 ```
 
-Or run it directly as a command (command syntax varies by IDE - use slash commands in Claude Code, OpenCode, etc.).
+This initializes the workflow system and helps choose your starting point.
-
-This sets up the guided workflow system and helps you choose the right starting point for your project based on its complexity.
-
----
 
 ## Key Features
 
 ### 🎨 Update-Safe Customization
 
-- **Agent Customization**: Modify agents via `bmad/_cfg/agents/` customize files
+- Agent modification via `bmad/_cfg/agents/`
-- **Persistent Settings**: Your customizations survive updates
+- Persistent settings through updates
-- **Multi-Language Support**: Agents communicate in your preferred language
+- Multi-language support
-- **Flexible Configuration**: Adjust agent names, roles, communication styles, and more
+- Flexible configuration
 
 ### 🚀 Intelligent Installation
 
-The installer automatically:
+- Auto-detects v4 installations
-
-- Detects and migrates v4 installations
 - Configures IDE integrations
-- Resolves module dependencies
+- Resolves dependencies
-- Sets up agent customization templates
+- Creates unified manifests
-- Creates unified agent manifests
 
 ### 📁 Unified Architecture
 
-Everything in one place - no more scattered configuration folders. Clean, organized, maintainable.
+Single `bmad/` folder - clean, organized, maintainable.
 
----
+## Documentation
 
-## Additional Documentation
+- **[📚 Documentation Index](./docs/index.md)** - Complete documentation map
-
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions
-- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions for v4 users
+- **[CLI Tool Guide](./tools/cli/README.md)** - Installer reference
-- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and bundler reference
+- **[Contributing Guide](./CONTRIBUTING.md)** - Contribution guidelines
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to BMad
-
----
 
 ## Community & Support
 
-- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share ideas, and collaborate
+- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Community help
-- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs and request features
+- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Bug reports
-- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials and updates
+- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials
-- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Get notified of updates
+- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Updates
-
----
 
 ## Contributing
 
-We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
-
----
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) for details.
+MIT License - See [LICENSE](LICENSE)
 
-**Trademark Notice**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
+**Trademark**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
 
 ---
 

docs/BMad-Method-V6-Quick-Start.md

@@ -0,0 +1,341 @@
+# BMad Method V6 Quick Start Guide
+
+Get started with BMad Method v6 for your new greenfield project. This guide walks you through building software from scratch using AI-powered workflows.
+
+## TL;DR - The Quick Path
+
+1. **Install**: `npx bmad-method@alpha install`
+2. **Initialize**: Load Analyst agent → Run "workflow-init"
+3. **Plan**: Load PM agent → Run "prd" (or "tech-spec" for small projects)
+4. **Architect**: Load Architect agent → Run "create-architecture" (10+ stories only)
+5. **Build**: Load SM agent → Run workflows for each story → Load DEV agent → Implement
+6. **Always use fresh chats** for each workflow to avoid hallucinations
+
+---
+
+## What is BMad Method?
+
+BMad Method (BMM) helps you build software through guided workflows with specialized AI agents. The process follows four phases:
+
+1. **Phase 1: Analysis** (Optional) - Brainstorming, Research, Product Brief
+2. **Phase 2: Planning** (Required) - Create your requirements (tech-spec or PRD)
+3. **Phase 3: Architecture** (Conditional) - Design the architecture for complex projects (10+ stories)
+4. **Phase 4: Implementation** (Required) - Build your software Epic by Epic, Story by Story
+
+## Installation
+
+```bash
+# Install v6 Alpha to your project
+npx bmad-method@alpha install
+```
+
+The interactive installer will guide you through setup and create a `bmad/` folder with all agents and workflows.
+
+---
+
+## Getting Started
+
+### Step 1: Initialize Your Workflow
+
+1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](../docs/ide-info/) for how to activate agents:
+   - [Claude Code](../docs/ide-info/claude-code.md)
+   - [VS Code/Cursor/Windsurf](../docs/ide-info/) - Check your IDE folder
+   - Other IDEs also supported
+2. **Wait for the agent's menu** to appear
+3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
+
+#### What happens during workflow-init?
+
+Workflows are interactive processes in V6 that replaced tasks and templates from prior versions. There are many types of workflows, and you can even create your own with the BMad Builder module. For the BMad Method, you'll be interacting with expert-designed workflows crafted to work with you to get the best out of both you and the LLM.
+
+During workflow-init, you'll describe:
+
+- Your project and its goals
+- Whether there's an existing codebase or this is a new project
+- The general size and complexity (you can adjust this later)
+
+#### Project Scale Levels
+
+Based on your description, the workflow will suggest a level and let you choose from:
+
+**Greenfield Project Levels:**
+
+- **Level 0** - Single atomic change (1 story) - bug fixes, typos, minor updates, single file changes
+- **Level 1** - Small feature (1-10 stories) - simple additions, isolated features, one module
+- **Level 2** - Medium feature set (5-15 stories) - dashboards, multiple related features, several modules
+- **Level 3** - Complex integration (12-40 stories) - platform features, major integrations, architectural changes
+- **Level 4** - Enterprise expansion (40+ stories) - multi-tenant, ecosystem changes, system-wide initiatives
+
+#### What gets created?
+
+Once you confirm your level, the `bmm-workflow-status.md` file will be created in your project's docs folder (assuming default install location). This file tracks your progress through all phases.
+
+**Important notes:**
+
+- Every level has different paths through the phases
+- Story counts can still change based on overall complexity as you work
+- For this guide, we'll assume a Level 2 project
+- This workflow will guide you through Phase 1 (optional), Phase 2 (required), and Phase 3 (required for Level 2+ complexity)
+
+### Step 2: Work Through Phases 1-3
+
+After workflow-init completes, you'll work through the planning phases. **Important: Use fresh chats for each workflow to avoid context limitations.**
+
+#### Checking Your Status
+
+If you're unsure what to do next:
+
+1. Load any agent in a new chat
+2. Ask for "workflow-status"
+3. The agent will tell you the next recommended or required workflow
+
+**Example response:**
+
+```
+Phase 1 (Analysis) is entirely optional. All workflows are optional or recommended:
+  - brainstorm-project - optional
+  - research - optional
+  - product-brief - RECOMMENDED (but not required)
+
+The next TRULY REQUIRED step is:
+  - PRD (Product Requirements Document) in Phase 2 - Planning
+  - Agent: pm
+  - Command: /bmad:bmm:workflows:prd
+```
+
+#### How to Run Workflows in Phases 1-3
+
+When an agent tells you to run a workflow (like `/bmad:bmm:workflows:prd`):
+
+1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](../docs/ide-info/) for your IDE's specific instructions
+2. **Wait for the menu** to appear
+3. **Tell the agent** to run it using any of these formats:
+   - Type the shorthand: `*prd`
+   - Say it naturally: "Let's create a new PRD"
+   - Select the menu number for "create-prd"
+
+The agents in V6 are very good with fuzzy menu matching!
+
+#### Quick Reference: Agent → Document Mapping
+
+For v4 users or those who prefer to skip workflow-status guidance:
+
+- **Analyst** → Brainstorming, Product Brief
+- **PM** → PRD (10+ stories) OR tech-spec (1-10 stories)
+- **UX-Designer** → UX Design Document (if UI-heavy)
+- **Architect** → Architecture (10+ stories)
+
+#### Phase 2: Planning - Creating the PRD
+
+**For Level 2+ projects (10+ stories):**
+
+1. Load the **PM agent** in a new chat
+2. Tell it to run the PRD workflow
+3. Once complete, you'll have two files:
+   - **PRD.md** - Your Product Requirements Document
+   - **Epics.md** - High-level epics with stories
+
+**For smaller projects (Levels 0-1):**
+
+- Use **tech-spec** instead of PRD (no architecture needed)
+
+#### Phase 2 (Optional): UX Design
+
+If your project has a user interface:
+
+1. Load the **UX-Designer agent** in a new chat
+2. Tell it to run the UX design workflow
+3. After completion, run validations to ensure the Epics file stays updated
+
+#### Phase 3: Architecture
+
+**For Level 2+ projects only:**
+
+1. Load the **Architect agent** in a new chat
+2. Tell it to run the create-architecture workflow
+3. After completion, run validations to ensure the Epics file stays updated
+
+#### Phase 3: Solutioning Gate Check (Highly Recommended)
+
+Once architecture is complete:
+
+1. Load the **Architect agent** in a new chat
+2. Tell it to run "solutioning-gate-check"
+3. This validates cohesion across all your planning documents (PRD, UX, Architecture, Epics)
+4. This was called the "PO Master Checklist" in v4
+
+**Why run this?** It ensures all your planning assets align properly before you start building.
+
+#### Context Management Tips
+
+- **Use 200k+ context models** for best results (Claude Sonnet 4.5, GPT-4, etc.)
+- **Fresh chat for each workflow** - Brainstorming, Briefs, Research, and PRD generation are all context-intensive
+- **No document sharding needed** - Unlike v4, you don't need to split documents
+- **Web Bundles coming soon** - Will help save LLM tokens for users with limited plans
+
+### Step 3: Start Building (Phase 4 - Implementation)
+
+Once planning and architecture are complete, you'll move to Phase 4. **Important: Each workflow below should be run in a fresh chat to avoid context limitations and hallucinations.**
+
+#### 3.1 Initialize Sprint Planning
+
+1. **Start a new chat** with the **SM (Scrum Master) agent**
+2. Wait for the menu to appear
+3. Tell the agent: "Run sprint-planning"
+4. This creates your `sprint-status.yaml` file that tracks all epics and stories
+
+#### 3.2 Create Epic Context (Optional but Recommended)
+
+1. **Start a new chat** with the **SM agent**
+2. Wait for the menu
+3. Tell the agent: "Run epic-tech-context"
+4. This creates technical context for the current epic before drafting stories
+
+#### 3.3 Draft Your First Story
+
+1. **Start a new chat** with the **SM agent**
+2. Wait for the menu
+3. Tell the agent: "Run create-story"
+4. This drafts the story file from the epic
+
+#### 3.4 Add Story Context (Optional but Recommended)
+
+1. **Start a new chat** with the **SM agent**
+2. Wait for the menu
+3. Tell the agent: "Run story-context"
+4. This creates implementation-specific technical context for the story
+
+#### 3.5 Implement the Story
+
+1. **Start a new chat** with the **DEV agent**
+2. Wait for the menu
+3. Tell the agent: "Run dev-story"
+4. The DEV agent will implement the story and update the sprint status
+
+#### 3.6 Review the Code (Optional but Recommended)
+
+1. **Start a new chat** with the **DEV agent**
+2. Wait for the menu
+3. Tell the agent: "Run code-review"
+4. The DEV agent performs quality validation (this was called QA in v4)
+
+### Step 4: Keep Going
+
+For each subsequent story, repeat the cycle using **fresh chats** for each workflow:
+
+1. **New chat** → SM agent → "Run create-story"
+2. **New chat** → SM agent → "Run story-context"
+3. **New chat** → DEV agent → "Run dev-story"
+4. **New chat** → DEV agent → "Run code-review" (optional but recommended)
+
+After completing all stories in an epic:
+
+1. **Start a new chat** with the **SM agent**
+2. Tell the agent: "Run retrospective"
+
+**Why fresh chats?** Context-intensive workflows can cause hallucinations if you keep issuing commands in the same chat. Starting fresh ensures the agent has maximum context capacity for each workflow.
+
+---
+
+## Understanding the Agents
+
+Each agent is a specialized AI persona:
+
+- **Analyst** - Initializes workflows and tracks progress
+- **PM** - Creates requirements and specifications
+- **UX-Designer** - If your project has a front end - this designer will help produce artifacts, come up with mock updates, and design a great look and feel with you giving it guidance.
+- **Architect** - Designs system architecture
+- **SM (Scrum Master)** - Manages sprints and creates stories
+- **DEV** - Implements code and reviews work
+
+## How Workflows Work
+
+1. **Load an agent** - Open the agent file in your IDE to activate it
+2. **Wait for the menu** - The agent will present its available workflows
+3. **Tell the agent what to run** - Say "Run [workflow-name]"
+4. **Follow the prompts** - The agent guides you through each step
+
+The agent creates documents, asks questions, and helps you make decisions throughout the process.
+
+## Project Tracking Files
+
+BMad creates two files to track your progress:
+
+**1. bmm-workflow-status.md**
+
+- Shows which phase you're in and what's next
+- Created by workflow-init
+- Updated automatically as you progress through phases
+
+**2. sprint-status.yaml** (Phase 4 only)
+
+- Tracks all your epics and stories during implementation
+- Critical for SM and DEV agents to know what to work on next
+- Created by sprint-planning workflow
+- Updated automatically as stories progress
+
+**You don't need to edit these manually** - agents update them as you work.
+
+---
+
+## The Complete Flow Visualized
+
+```
+Phase 1 (Optional)          Phase 2 (Required)         Phase 3 (Conditional)        Phase 4 (Required)
+┌─────────────────┐        ┌─────────────────┐        ┌─────────────────┐         ┌──────────────────┐
+│ Analysis        │        │ Planning        │        │ Architecture    │         │ Implementation   │
+│                 │        │                 │        │                 │         │                  │
+│ • Brainstorm    │        │ Level 0-1:      │        │ Level 2+:       │         │ Per Epic:        │
+│ • Research      │───────▶│  • tech-spec    │───────▶│  • architecture │────────▶│  • epic context  │
+│ • Brief         │        │                 │        │  • gate-check   │         │                  │
+│                 │        │ Level 2+:       │        │                 │         │ Per Story:       │
+│ (Analyst)       │        │  • PRD          │        │ (Architect)     │         │  • create-story  │
+│                 │        │  • UX (opt)     │        │                 │         │  • story-context │
+│                 │        │                 │        │                 │         │  • dev-story     │
+│                 │        │ (PM, UX)        │        │                 │         │  • code-review   │
+│                 │        │                 │        │                 │         │                  │
+│                 │        │                 │        │                 │         │ (SM, DEV)        │
+└─────────────────┘        └─────────────────┘        └─────────────────┘         └──────────────────┘
+```
+
+## Common Questions
+
+**Q: Do I always need architecture?**
+A: Only for larger projects (10+ stories). Small projects can skip straight from tech-spec to implementation.
+
+**Q: Can I change my plan later?**
+A: Yes! The SM agent has a "correct-course" workflow for handling scope changes.
+
+**Q: What if I want to brainstorm first?**
+A: Load the Analyst agent and tell it to "Run brainstorm-project" before running workflow-init.
+
+**Q: Why do I need fresh chats for each workflow?**
+A: Context-intensive workflows can cause hallucinations if run in sequence. Fresh chats ensure maximum context capacity.
+
+**Q: Can I skip workflow-init and workflow-status?**
+A: Yes, once you learn the flow. Use the Quick Reference in Step 2 to go directly to the workflows you need.
+
+## Getting Help
+
+- **During workflows**: Agents guide you with questions and explanations
+- **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
+- **Complete guide**: [BMM Workflows README](../src/modules/bmm/workflows/README.md)
+- **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
+
+---
+
+## Key Takeaways
+
+✅ **Always use fresh chats** - Load agents in new chats for each workflow to avoid context issues
+✅ **Let workflow-status guide you** - Load any agent and ask for status when unsure what's next
+✅ **Level matters** - Small projects (0-1) use tech-spec, larger projects (2+) need PRD and architecture
+✅ **Tracking is automatic** - The status files update themselves, no manual editing needed
+✅ **Agents are flexible** - Use menu numbers, shortcuts (\*prd), or natural language
+
+**Ready to start building?** Install BMad, load the Analyst, run workflow-init, and let the agents guide you!
+
+---
+
+**Version**: v6-alpha
+**Last Updated**: 2025-01
+**For detailed documentation**: [Complete BMM Workflows Guide](../src/modules/bmm/workflows/README.md)

docs/index.md

@@ -0,0 +1,229 @@
+# BMad Documentation Index
+
+Complete map of all BMad Method v6 documentation with recommended reading paths.
+
+---
+
+## 🎯 Getting Started (Start Here!)
+
+**New users:** Start with one of these based on your situation:
+
+| Your Situation         | Start Here                                           | Then Read                                                     |
+| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
+| **Brand new to BMad**  | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) | [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) |
+| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)      | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md)          |
+| **Brownfield project** | [Brownfield Guide](./bmad-brownfield-guide.md)       | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md)          |
+
+---
+
+## 📋 Core Documentation
+
+### Project-Level Docs (Root)
+
+- **[README.md](../README.md)** - Main project overview, feature summary, and module introductions
+- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[CHANGELOG.md](../CHANGELOG.md)** - Version history and breaking changes
+- **[CLAUDE.md](../CLAUDE.md)** - Claude Code specific guidelines for this project
+
+### Installation & Setup
+
+- **[BMad Method V6 Quick Start](./BMad-Method-V6-Quick-Start.md)** - Step-by-step guide to building your first project with BMM
+- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
+- **[Brownfield Guide](./bmad-brownfield-guide.md)** - Guidance for working with existing codebases
+
+---
+
+## 🏗️ Module Documentation
+
+### BMad Method (BMM) - Software & Game Development
+
+The flagship module for agile AI-driven development.
+
+- **[BMM Module README](../src/modules/bmm/README.md)** - Module overview, agents, and structure
+- **[BMM Workflows Guide](../src/modules/bmm/workflows/README.md)** - **ESSENTIAL READING** - Complete v6 workflow system explanation
+  - Phase 1: Analysis (optional)
+  - Phase 2: Planning (required, scale-adaptive)
+  - Phase 3: Solutioning (complex projects)
+  - Phase 4: Implementation (iterative)
+- **[Test Architect Guide](../src/modules/bmm/testarch/README.md)** - Testing strategy and quality assurance
+
+### BMad Builder (BMB) - Create Custom Solutions
+
+Build your own agents, workflows, and modules.
+
+- **[BMB Module README](../src/modules/bmb/README.md)** - Module overview and capabilities
+- **[Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md)** - Design custom agents
+
+### Creative Intelligence Suite (CIS) - Innovation & Creativity
+
+AI-powered creative thinking and brainstorming.
+
+- **[CIS Module README](../src/modules/cis/README.md)** - Module overview and workflows
+
+---
+
+## 🖥️ IDE-Specific Guides
+
+Instructions for loading agents and running workflows in your development environment.
+
+**Popular IDEs:**
+
+- [Claude Code](./ide-info/claude-code.md)
+- [Cursor](./ide-info/cursor.md)
+- [VS Code](./ide-info/windsurf.md)
+
+**Other Supported IDEs:**
+
+- [Augment](./ide-info/auggie.md)
+- [Cline](./ide-info/cline.md)
+- [Codex](./ide-info/codex.md)
+- [Crush](./ide-info/crush.md)
+- [Gemini](./ide-info/gemini.md)
+- [GitHub Copilot](./ide-info/github-copilot.md)
+- [IFlow](./ide-info/iflow.md)
+- [Kilo](./ide-info/kilo.md)
+- [OpenCode](./ide-info/opencode.md)
+- [Qwen](./ide-info/qwen.md)
+- [Roo](./ide-info/roo.md)
+- [Trae](./ide-info/trae.md)
+
+**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions.
+
+---
+
+## 🔧 Advanced Topics
+
+### Installation & Bundling
+
+- [IDE Injections Reference](./installers-bundlers/ide-injections.md) - How agents are installed to IDEs
+- [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
+- [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles
+
+---
+
+## 📊 Documentation Map
+
+```
+docs/
+├── index.md (this file)
+├── BMad-Method-V6-Quick-Start.md
+├── v4-to-v6-upgrade.md
+├── bmad-brownfield-guide.md
+├── ide-info/
+│   ├── claude-code.md
+│   ├── cursor.md
+│   ├── windsurf.md
+│   └── [14+ other IDEs]
+└── installers-bundlers/
+    ├── ide-injections.md
+    ├── installers-modules-platforms-reference.md
+    └── web-bundler-usage.md
+
+src/
+├── modules/
+│   ├── bmm/
+│   │   ├── README.md
+│   │   ├── workflows/README.md (ESSENTIAL)
+│   │   └── testarch/README.md
+│   ├── bmb/
+│   │   ├── README.md
+│   │   └── workflows/create-agent/README.md
+│   └── cis/
+│       └── README.md
+```
+
+---
+
+## 🎓 Recommended Reading Paths
+
+### Path 1: Brand New to BMad (Software Project)
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Understand agents
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 2: Game Development Project
+
+1. [README.md](../README.md) - Understand the vision
+2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Get hands-on
+3. [BMM Module README](../src/modules/bmm/README.md) - Game agents are included
+4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Game workflows
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 3: Upgrading from v4
+
+1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
+2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Reorient yourself
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Learn new v6 workflows
+
+### Path 4: Working with Existing Codebase (Brownfield)
+
+1. [Brownfield Guide](./bmad-brownfield-guide.md) - Approach for legacy code
+2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Follow the process
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
+
+### Path 5: Building Custom Solutions
+
+1. [BMB Module README](../src/modules/bmb/README.md) - Understand capabilities
+2. [Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md) - Create agents
+3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Understand workflow structure
+
+### Path 6: Contributing to BMad
+
+1. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+2. Relevant module README - Understand the area you're contributing to
+3. [Code Style section in CONTRIBUTING.md](../CONTRIBUTING.md#code-style) - Follow standards
+
+---
+
+## 🔍 Quick Reference
+
+**What is each module for?**
+
+- **BMM** - AI-driven software and game development
+- **BMB** - Create custom agents and workflows
+- **CIS** - Creative thinking and brainstorming
+
+**How do I load an agent?**
+→ See [ide-info](./ide-info/) folder for your IDE
+
+**I'm stuck, what's next?**
+→ Check the [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) or run `workflow-status`
+
+**I want to contribute**
+→ Start with [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+## 📚 Important Concepts
+
+### Fresh Chats
+
+Each workflow should run in a fresh chat with the specified agent to avoid context limitations. This is emphasized throughout the docs because it's critical to successful workflows.
+
+### Scale Levels
+
+BMM adapts to project complexity (Levels 0-4). Documentation is scale-adaptive - you only need what's relevant to your project size.
+
+### Update-Safe Customization
+
+All agent customizations go in `bmad/_cfg/agents/` and survive updates. See your IDE guide and module README for details.
+
+---
+
+## 🆘 Getting Help
+
+- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
+  - #general-dev - Technical questions
+  - #bugs-issues - Bug reports
+- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- **YouTube**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
+
+---
+
+**Version**: v6-alpha
+**Last Updated**: 2025-10-30
+
+---

docs/v4-to-v6-upgrade.md

@@ -196,14 +196,16 @@ If you're using:
 
 After installation:
 
-```bash
+1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
-# Start the analyst and tell the analyst after it loads - claude code instructions:
+   - [Claude Code](./ide-info/claude-code.md)
-claude # wait for claude to launch in terminal
+   - [Cursor](./ide-info/cursor.md)
-- `/analyst` # wait for analyst greeting and menu
+   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
-- `*workflow-init` # v6 now supports much better natural language fuzzy matching - so you could also say `workflow init` or possibly `please init the workflow`
-```
 
-Since you are migrating an existing project from v4, its most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
+2. **Wait for the agent's menu** to appear
+
+3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
+
+Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
 
 ---
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-alpha.2",
+  "version": "6.0.0-alpha.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-alpha.2",
+      "version": "6.0.0-alpha.3",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.6.1",
@@ -27,7 +27,8 @@
         "xml2js": "^0.6.2"
       },
       "bin": {
-        "bmad": "tools/cli/bmad-cli.js"
+        "bmad": "tools/bmad-npx-wrapper.js",
+        "bmad-method": "tools/bmad-npx-wrapper.js"
       },
       "devDependencies": {
         "@eslint/js": "^9.33.0",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.2",
+  "version": "6.0.0-alpha.3",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

src/modules/bmb/README.md

@@ -1,132 +1,194 @@
 # BMB - BMad Builder Module
 
-The BMB (BMad Builder Module) provides specialized tools and workflows for creating, customizing, and extending BMad Method components, including custom agents, workflows, and integrations.
+Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
+
+## Table of Contents
+
+- [Module Structure](#module-structure)
+- [Core Workflows](#core-workflows)
+- [Agent Types](#agent-types)
+- [Quick Start](#quick-start)
+- [Best Practices](#best-practices)
 
 ## Module Structure
 
-### 🤖 `/agents`
+### 🤖 Agents
 
-Builder-specific agents that help create and customize BMad Method components:
+**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
 
-- Agent creation and configuration specialists
+### 📋 Workflows
-- Workflow designers
-- Integration builders
 
-### 📋 `/workflows`
+Comprehensive suite for building and maintaining BMad components.
 
-Specialized workflows for building and extending BMad Method capabilities:
+## Core Workflows
 
-#### Core Builder Workflows
+### Creation Workflows
 
-- `create-agent` - Design and implement custom agents
+**[create-agent](./workflows/create-agent/README.md)** - Build BMad agents
-- `create-workflow` - Build new workflow definitions
-- `create-team` - Configure agent teams
-- `bundle-agent` - Package agents for distribution
-- `create-method` - Design custom development methodologies
 
-#### Integration Workflows
+- Interactive persona development
+- Command structure design
+- YAML source compilation to .md
 
-- `integrate-tool` - Connect external tools and services
+**[create-workflow](./workflows/create-workflow/README.md)** - Design workflows
-- `create-adapter` - Build API adapters
-- `setup-environment` - Configure development environments
 
-## Key Features
+- Structured multi-step processes
+- Configuration validation
+- Web bundle support
 
-### Agent Builder
+**[create-module](./workflows/create-module/README.md)** - Build complete modules
 
-Create custom agents with:
+- Full module infrastructure
+- Agent and workflow integration
+- Installation automation
 
-- Role-specific instructions
+**[module-brief](./workflows/module-brief/README.md)** - Strategic planning
-- Tool configurations
-- Behavior patterns
-- Integration points
 
-### Workflow Designer
+- Module blueprint creation
+- Vision and architecture
+- Comprehensive analysis
 
-Design workflows that:
+### Editing Workflows
 
-- Orchestrate multiple agents
+**[edit-agent](./workflows/edit-agent/README.md)** - Modify existing agents
-- Define process flows
-- Handle different project scales
-- Integrate with existing systems
 
-### Team Configuration
+- Persona refinement
+- Command updates
+- Best practice compliance
 
-Build teams that:
+**[edit-workflow](./workflows/edit-workflow/README.md)** - Update workflows
 
-- Combine complementary agent skills
+- Structure maintenance
-- Coordinate on complex tasks
+- Configuration updates
-- Share context effectively
+- Documentation sync
-- Deliver cohesive results
+
+**[edit-module](./workflows/edit-module/README.md)** - Module enhancement
+
+- Component modifications
+- Dependency management
+- Version control
+
+### Maintenance Workflows
+
+**[convert-legacy](./workflows/convert-legacy/README.md)** - Migration tool
+
+- v4 to v6 conversion
+- Structure compliance
+- Convention updates
+
+**[audit-workflow](./workflows/audit-workflow/README.md)** - Quality validation
+
+- Structure verification
+- Config standards check
+- Bloat detection
+- Web bundle completeness
+
+**[redoc](./workflows/redoc/README.md)** - Auto-documentation
+
+- Reverse-tree approach
+- Technical writer quality
+- Convention compliance
+
+## Agent Types
+
+BMB creates three agent architectures:
+
+### Full Module Agent
+
+- Complete persona and role definition
+- Command structure with fuzzy matching
+- Workflow integration
+- Module-specific capabilities
+
+### Hybrid Agent
+
+- Shared core capabilities
+- Module-specific extensions
+- Cross-module compatibility
+
+### Standalone Agent
+
+- Independent operation
+- Minimal dependencies
+- Specialized single purpose
 
 ## Quick Start
 
-```bash
+1. **Load BMad Builder agent** in your IDE
-# Create a new custom agent
+2. **Choose creation type:**
-bmad bmb create-agent
+   ```
+   *create-agent     # New agent
+   *create-workflow  # New workflow
+   *create-module    # Complete module
+   ```
+3. **Follow interactive prompts**
 
-# Design a new workflow
+### Example: Creating an Agent
-bmad bmb create-workflow
 
-# Bundle an agent for sharing
+```
-bmad bmb bundle-agent
+User: I need a code review agent
+Builder: *create-agent
 
-# Create a custom team configuration
+[Interactive session begins]
-bmad bmb create-team
+- Brainstorming phase (optional)
+- Persona development
+- Command structure
+- Integration points
 ```
 
 ## Use Cases
 
-### Custom Agent Development
+### Custom Development Teams
 
 Build specialized agents for:
 
-- Domain-specific expertise
+- Domain expertise (legal, medical, finance)
-- Company-specific processes
+- Company processes
 - Tool integrations
 - Automation tasks
 
-### Workflow Customization
+### Workflow Extensions
 
 Create workflows for:
 
-- Unique development processes
 - Compliance requirements
 - Quality gates
 - Deployment pipelines
-
-### Team Orchestration
-
-Configure teams for:
-
-- Large-scale projects
-- Cross-functional collaboration
-- Specialized domains
 - Custom methodologies
 
-## Integration with BMM
+### Complete Solutions
 
-BMB works alongside BMM to:
+Package modules for:
 
-- Extend core BMM capabilities
+- Industry verticals
-- Create custom implementations
+- Technology stacks
-- Build domain-specific solutions
+- Business processes
-- Integrate with existing tools
+- Educational frameworks
 
 ## Best Practices
 
-1. **Start with existing patterns** - Study BMM agents and workflows before creating new ones
+1. **Study existing patterns** - Review BMM/CIS implementations
-2. **Keep it modular** - Build reusable components
+2. **Follow conventions** - Use established structures
-3. **Document thoroughly** - Clear documentation helps others use your creations
+3. **Document thoroughly** - Clear instructions essential
-4. **Test extensively** - Validate agents and workflows before production use
+4. **Test iteratively** - Validate during creation
-5. **Share and collaborate** - Contribute useful components back to the community
+5. **Consider reusability** - Build modular components
+
+## Integration
+
+BMB components integrate with:
+
+- **BMad Core** - Framework foundation
+- **BMM** - Extend development capabilities
+- **CIS** - Leverage creative workflows
+- **Custom Modules** - Your domain solutions
 
 ## Related Documentation
 
-- [BMM Module](../bmm/README.md) - Core method implementation
+- **[Agent Creation Guide](./workflows/create-agent/README.md)** - Detailed instructions
-- [Agent Creation Guide](./workflows/create-agent/README.md) - Detailed agent building instructions
+- **[Module Structure](./workflows/create-module/module-structure.md)** - Architecture patterns
-- [Workflow Design Patterns](./workflows/README.md) - Best practices for workflow creation
+- **[BMM Module](../bmm/README.md)** - Reference implementation
+- **[Core Framework](../../core/README.md)** - Foundation concepts
 
 ---
 
-BMB empowers you to extend and customize the BMad Method to fit your specific needs while maintaining the power and consistency of the core framework.
+BMB empowers you to extend BMad Method for your specific needs while maintaining framework consistency and power.

src/modules/bmb/workflows/create-agent/README.md

@@ -1,320 +1,203 @@
-# Build Agent
+# Create Agent Workflow
 
-## Overview
+Interactive agent builder creating BMad Core compliant agents as YAML source files that compile to .md during installation.
 
-The Build Agent workflow is an interactive agent builder that guides you through creating BMAD Core compliant agents as YAML source files that compile to final `.md` during install. It supports three agent types: Simple (self-contained), Expert (with sidecar resources), and Module (full-featured with workflows).
+## Table of Contents
 
-## Key Features
+- [Quick Start](#quick-start)
+- [Agent Types](#agent-types)
+- [Workflow Phases](#workflow-phases)
+- [Output Structure](#output-structure)
+- [Installation](#installation)
+- [Examples](#examples)
 
-- **Optional Brainstorming**: Creative ideation session before agent building to explore concepts and personalities
+## Quick Start
-- **Three Agent Types**: Simple, Expert, and Module agents with appropriate structures
-- **Persona Development**: Guided creation of role, identity, communication style, and principles
-- **Command Builder**: Interactive command definition with workflow/task/action patterns
-- **Validation Built-In**: Ensures YAML structure and BMAD Core compliance
-- **Customize Support**: Optional `customize.yaml` for persona/menu overrides and critical actions
-- **Sidecar Resources**: Setup for Expert agents with domain-specific data
-
-## Usage
-
-### Basic Invocation
 
 ```bash
+# Direct workflow
 workflow create-agent
-```
 
-### Through BMad Builder Agent
+# Via BMad Builder
-
-```
 *create-agent
 ```
 
-### With Brainstorming Session
+## Agent Types
 
-The workflow includes an optional brainstorming phase (Step -1) that helps you explore agent concepts, personalities, and capabilities before building. This is particularly useful when you have a vague idea and want to develop it into a concrete agent concept.
+### Simple Agent
 
-### What You'll Be Asked
+- Self-contained functionality
+- Basic command structure
+- No external resources
 
-0. **Optional brainstorming** (vague idea → refined concept)
+### Expert Agent
-1. Agent type (Simple, Expert, or Module)
-2. Basic identity (name, title, icon, filename)
-3. Module assignment (for Module agents)
-4. Sidecar resources (for Expert agents)
-5. Persona elements (role, identity, style, principles)
-6. Commands and their implementations
-7. Critical actions (optional)
-8. Activation rules (optional, rarely needed)
 
-## Workflow Structure
+- Sidecar resources for domain knowledge
+- Extended capabilities
+- Knowledge base integration
 
-### Files Included
+### Module Agent
 
-```
+- Full-featured with workflows
-create-agent/
+- Module-specific commands
-├── workflow.yaml                  # Configuration
+- Integrated with module structure
-├── instructions.md                # Step-by-step guide
-├── checklist.md                   # Validation criteria
-├── README.md                      # This file
-├── agent-types.md                 # Agent type documentation
-├── agent-architecture.md          # Architecture patterns
-├── agent-command-patterns.md      # Command patterns reference
-└── communication-styles.md        # Style examples
-```
 
-## Workflow Process
+## Workflow Phases
 
-### Phase 0: Optional Brainstorming (Step -1)
+### Phase 0: Optional Brainstorming
 
-- Creative ideation session using diverse brainstorming techniques
+- Creative ideation session
-- Explore agent concepts, personalities, and capabilities
+- Explore concepts and personalities
-- Generate character ideas, expertise areas, and command concepts
+- Generate command ideas
-- Output feeds directly into agent identity and persona development
+- Output feeds into persona development
 
-### Phase 1: Agent Setup (Steps 0-2)
+### Phase 1: Agent Setup
 
-- Load agent building documentation and patterns
+1. Choose agent type (Simple/Expert/Module)
-- Choose agent type (Simple/Expert/Module)
+2. Define identity (name, title, icon, filename)
-- Define basic identity (name, title, icon, filename) - informed by brainstorming if completed
+3. Assign to module (if Module agent)
-- Assign to module (for Module agents)
 
-### Phase 2: Persona Development (Steps 2-3)
+### Phase 2: Persona Development
 
-- Define role and responsibilities - leveraging brainstorming insights if available
+- Define role and responsibilities
-- Craft unique identity and backstory
+- Craft unique identity/backstory
-- Select communication style - can use brainstormed personality concepts
+- Select communication style
 - Establish guiding principles
 - Add critical actions (optional)
 
-### Phase 3: Command Building (Step 4)
+### Phase 3: Command Building
 
-- Add *help and *exit commands (required)
+- Add required commands (*help, *exit)
-- Define workflow commands (most common)
+- Define workflow commands
-- Add task commands (for single operations)
+- Add task commands
-- Create action commands (inline logic)
+- Create action commands
-- Configure command attributes
+- Configure attributes
 
-### Phase 4: Finalization (Steps 5-10)
+### Phase 4: Finalization
 
-- Confirm activation behavior (mostly automatic)
+- Generate .agent.yaml file
-- Generate `.agent.yaml` file
+- Create customize file (optional)
-- Optionally create a customize file for overrides
+- Setup sidecar resources (Expert agents)
-- Setup sidecar resources (for Expert agents)
+- Validate and compile
-- Validate YAML and compile to `.md`
 - Provide usage instructions
 
-## Output
+## Output Structure
 
 ### Generated Files
 
-#### For Standalone Agents (not part of a module)
+**Standalone Agents:**
 
-- **YAML Source**: `{custom_agent_location}/{{agent_filename}}.agent.yaml` (default: `bmad/agents/`)
+- Source: `bmad/agents/{filename}.agent.yaml`
-- **Installation Location**: `{project-root}/bmad/agents/{{agent_filename}}.md`
+- Compiled: `bmad/agents/{filename}.md`
-- **Compilation**: Run the BMAD Method installer and select "Compile Agents (Quick rebuild of all agent .md files)"
 
-#### For Module Agents
+**Module Agents:**
 
-- **YAML Source**: `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml`
+- Source: `src/modules/{module}/agents/{filename}.agent.yaml`
-- **Installation Location**: `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
+- Compiled: `bmad/{module}/agents/{filename}.md`
-- **Compilation**: Automatic during module installation
 
-### YAML Agent Structure (simplified)
+### YAML Structure
 
 ```yaml
 agent:
   metadata:
-    id: bmad/{{module}}/agents/{{agent_filename}}.md
+    id: bmad/{module}/agents/{filename}.md
-    name: { { agent_name } }
+    name: Agent Name
-    title: { { agent_title } }
+    title: Agent Title
-    icon: { { agent_icon } }
+    icon: 🤖
-    module: { { module } }
+    module: module-name
   persona:
     role: '...'
     identity: '...'
     communication_style: '...'
     principles: ['...', '...']
   menu:
-    - trigger: example
+    - trigger: command-name
-      workflow: '{project-root}/path/to/workflow.yaml'
+      workflow: path/to/workflow.yaml
-      description: Do the thing
+      description: Command description
 ```
 
 ### Optional Customize File
 
-If created, generates at:
+Location: `bmad/_cfg/agents/{module}-{filename}.customize.yaml`
-`{project-root}/bmad/_cfg/agents/{{module}}-{{agent_filename}}.customize.yaml`
 
-## Installation and Compilation
+Allows persona and menu overrides that persist through updates.
 
-### Agent Installation Locations
+## Installation
 
-Agents are installed to different locations based on their type:
+### Compilation Methods
 
-1. **Standalone Agents** (not part of a module)
+**Quick Rebuild:**
-   - Source: Created in your custom agent location (default: `bmad/agents/`)
-   - Installed to: `{project-root}/bmad/agents/`
-   - Compilation: Run BMAD Method installer and select "Compile Agents"
-
-2. **Module Agents** (part of BMM, BMB, or custom modules)
-   - Source: Created in `src/modules/{module}/agents/`
-   - Installed to: `{project-root}/bmad/{module}/agents/`
-   - Compilation: Automatic during module installation
-
-### Compilation Process
-
-The installer compiles YAML agent definitions to Markdown:
 
 ```bash
-# For standalone agents
+bmad compile-agents
-npm run build:agents
-
-# For all BMad components (includes agents)
-npm run install:bmad
-
-# Using the installer menu
-npm run installer
-# Then select: Compile Agents
 ```
 
-### Build Commands
+**During Module Install:**
+Automatic compilation when installing modules
 
-Additional build commands for agent management:
+**Manual Compilation:**
 
 ```bash
-# Build specific agent types
+node tools/cli/bmad-cli.js compile-agents
-npx bmad-method build:agents        # Build standalone agents
-npx bmad-method build:modules        # Build module agents (with modules)
-
-# Full rebuild
-npx bmad-method build:all           # Rebuild everything
 ```
 
-## Requirements
+## Examples
 
-- BMAD Core v6 project structure
+### Creating a Code Review Agent
-- Module to host the agent (for Module agents)
-- Understanding of agent purpose and commands
-- Workflows/tasks to reference in commands (or mark as "todo")
 
-## Brainstorming Integration
+```
+User: I need a code review agent
+Builder: Let's brainstorm first...
 
-The optional brainstorming phase (Step -1) provides a seamless path from vague idea to concrete agent concept:
+[Brainstorming generates ideas for strict vs friendly reviewer]
 
-### When to Use Brainstorming
+Builder: Now let's build your agent:
+- Type: Simple
+- Name: Code Reviewer
+- Role: Senior developer conducting thorough reviews
+- Style: Professional but approachable
+- Commands:
+  - *review-pr: Review pull request
+  - *review-file: Review single file
+  - *review-standards: Check coding standards
+```
 
-- **Vague concept**: "I want an agent that helps with data stuff"
+### Creating a Domain Expert
-- **Creative exploration**: Want to discover unique personality and approach
-- **Team building**: Creating agents for a module with specific roles
-- **Character development**: Need to flesh out agent personality and voice
 
-### Brainstorming Flow
+```
+Type: Expert
+Name: Legal Advisor
+Sidecar: legal-knowledge/
+Commands:
+  - *contract-review
+  - *compliance-check
+  - *risk-assessment
+```
 
-1. **Step -1**: Optional brainstorming session
+## Workflow Files
-   - Uses CIS brainstorming workflow with agent-specific context
-   - Explores identity, personality, expertise, and command concepts
-   - Generates detailed character and capability ideas
 
-2. **Steps 0-2**: Agent setup informed by brainstorming
+```
-   - Brainstorming output guides agent type selection
+create-agent/
-   - Character concepts inform basic identity choices
+├── workflow.yaml              # Configuration
-   - Personality insights shape persona development
+├── instructions.md            # Step guide
-
+├── checklist.md              # Validation
-3. **Seamless transition**: Vague idea → brainstormed concept → built agent
+├── README.md                 # This file
-
+├── agent-types.md            # Type details
-### Key Principle
+├── agent-architecture.md     # Patterns
-
+├── agent-command-patterns.md # Commands
-Users can go from **vague idea → brainstormed concept → built agent** in one continuous flow, with brainstorming output directly feeding into agent development.
+└── communication-styles.md   # Styles
+```
 
 ## Best Practices
 
-### Before Starting
+1. **Use brainstorming** for complex agents
+2. **Start simple** - Add commands incrementally
+3. **Test commands** before finalizing
+4. **Document thoroughly** in descriptions
+5. **Follow naming conventions** consistently
 
-1. Review example agents in `/bmad/bmm/agents/` for patterns
+## Related Documentation
-2. Consider using brainstorming if you have a vague concept to develop
-3. Have a clear vision of the agent's role and personality (or use brainstorming to develop it)
-4. List the commands/capabilities the agent will need
-5. Identify any workflows or tasks the agent will invoke
 
-### During Execution
+- [Agent Types](./agent-types.md)
-
+- [Command Patterns](./agent-command-patterns.md)
-1. **Agent Names**: Use memorable names that reflect personality
+- [Communication Styles](./communication-styles.md)
-2. **Icons**: Choose an emoji that represents the agent's role
+- [BMB Module](../../README.md)
-3. **Persona**: Make it distinct and consistent with communication style
-4. **Commands**: Use kebab-case, start custom commands with letter (not \*)
-5. **Workflows**: Reference existing workflows or mark as "todo" to implement later
-
-### After Completion
-
-1. **Compile the agent**:
-   - For standalone agents: Run `npm run build:agents` or use the installer menu
-   - For module agents: Automatic during module installation
-2. **Test the agent**: Use the compiled `.md` agent in your IDE
-3. **Implement placeholders**: Complete any "todo" workflows referenced
-4. **Refine as needed**: Use customize file for persona adjustments
-5. **Evolve over time**: Add new commands as requirements emerge
-
-## Agent Types
-
-### Simple Agent
-
-- **Best For**: Self-contained utilities, simple assistants
-- **Characteristics**: Embedded logic, no external dependencies
-- **Example**: Calculator agent, random picker, simple formatter
-
-### Expert Agent
-
-- **Best For**: Domain-specific agents with data/memory
-- **Characteristics**: Sidecar folders, domain restrictions, memory files
-- **Example**: Diary keeper, project journal, personal knowledge base
-
-### Module Agent
-
-- **Best For**: Full-featured agents with workflows
-- **Characteristics**: Part of module, commands invoke workflows
-- **Example**: Product manager, architect, research assistant
-
-## Troubleshooting
-
-### Issue: Agent won't load
-
-- **Solution**: Validate XML structure is correct
-- **Check**: Ensure all required tags present (persona, cmds)
-
-### Issue: Commands don't work
-
-- **Solution**: Verify workflow paths are correct or marked "todo"
-- **Check**: Test workflow invocation separately first
-
-### Issue: Persona feels generic
-
-- **Solution**: Review communication styles guide
-- **Check**: Make identity unique and specific to role
-
-## Customization
-
-To modify agent building process:
-
-1. Edit `instructions.md` to change steps
-2. Update `agent-types.md` to add new agent patterns
-3. Modify `agent-command-patterns.md` for new command types
-4. Edit `communication-styles.md` to add personality examples
-
-## Version History
-
-- **v6.0.0** - BMAD Core v6 compatible
-  - Three agent types (Simple/Expert/Module)
-  - Enhanced persona development
-  - Command pattern library
-  - Validation framework
-
-## Support
-
-For issues or questions:
-
-- Review example agents in `/bmad/bmm/agents/`
-- Check agent documentation in this workflow folder
-- Test with simple agents first, then build complexity
-- Consult BMAD Method v6 documentation
-
----
-
-_Part of the BMad Method v6 - BMB (BMad Builder) Module_

src/modules/bmb/workflows/create-agent/instructions.md

@@ -20,8 +20,6 @@
   <check if="user answered no">
     <action>Proceed directly to Step 0</action>
   </check>
-
-<template-output>brainstorming_results</template-output>
 </step>
 
 <step n="0" goal="Load technical documentation">
@@ -103,9 +101,24 @@
 7. Wise Sage/Yoda - Cryptic wisdom, inverted syntax
 8. Game Show Host - Enthusiastic, game show tropes
 
-**Professional Presets:** 9. Analytical Expert - Systematic, data-driven, hierarchical 10. Supportive Mentor - Patient guidance, celebrates wins 11. Direct Consultant - Straight to the point, efficient 12. Collaborative Partner - Team-oriented, inclusive
+**Professional Presets:**
 
-**Quirky Presets:** 13. Cooking Show Chef - Recipe metaphors, culinary terms 14. Sports Commentator - Play-by-play, excitement 15. Nature Documentarian - Wildlife documentary style 16. Time Traveler - Temporal references, timeline talk 17. Conspiracy Theorist - Everything is connected 18. Zen Master - Philosophical, paradoxical 19. Star Trek Captain - Space exploration protocols 20. Soap Opera Drama - Dramatic reveals, gasps 21. Reality TV Contestant - Confessionals, drama
+9. Analytical Expert - Systematic, data-driven, hierarchical
+10. Supportive Mentor - Patient guidance, celebrates wins
+11. Direct Consultant - Straight to the point, efficient
+12. Collaborative Partner - Team-oriented, inclusive
+
+**Quirky Presets:**
+
+13. Cooking Show Chef - Recipe metaphors, culinary terms
+14. Sports Commentator - Play-by-play, excitement
+15. Nature Documentarian - Wildlife documentary style
+16. Time Traveler - Temporal references, timeline talk
+17. Conspiracy Theorist - Everything is connected
+18. Zen Master - Philosophical, paradoxical
+19. Star Trek Captain - Space exploration protocols
+20. Soap Opera Drama - Dramatic reveals, gasps
+21. Reality TV Contestant - Confessionals, drama
 
 <action>If user wants to see more examples or create custom styles, show relevant sections from {communication_styles} guide and help them craft their unique style</action>
 

src/modules/bmb/workflows/create-module/README.md

@@ -1,220 +1,229 @@
-# Build Module Workflow
+# Create Module Workflow
 
-## Overview
+Interactive scaffolding system creating complete BMad modules with agents, workflows, tasks, and installation infrastructure.
 
-The Build Module workflow is an interactive scaffolding system that creates complete BMAD modules with agents, workflows, tasks, and installation infrastructure. It serves as the primary tool for building new modules in the BMAD ecosystem, guiding users through the entire module creation process from concept to deployment-ready structure.
+## Table of Contents
 
-## Key Features
+- [Quick Start](#quick-start)
+- [Workflow Phases](#workflow-phases)
+- [Output Structure](#output-structure)
+- [Module Components](#module-components)
+- [Best Practices](#best-practices)
 
-- **Interactive Module Planning** - Collaborative session to define module concept, scope, and architecture
+## Quick Start
-- **Intelligent Scaffolding** - Automatic creation of proper directory structures and configuration files
-- **Component Integration** - Seamless integration with create-agent and create-workflow workflows
-- **Installation Infrastructure** - Complete installer setup with configuration templates
-- **Module Brief Integration** - Can use existing module briefs as blueprints for accelerated development
-- **Validation and Documentation** - Built-in validation checks and comprehensive README generation
-
-## Usage
-
-### Basic Invocation
 
 ```bash
+# Basic invocation
 workflow create-module
+
+# With module brief input
+workflow create-module --input module-brief-{name}-{date}.md
+
+# Via BMad Builder
+*create-module
 ```
 
-### With Module Brief Input
+## Workflow Phases
 
-```bash
+### Phase 1: Concept Definition
-# If you have a module brief from the module-brief workflow
-workflow create-module --input module-brief-my-module-2024-09-26.md
-```
 
-### Configuration
+- Define module purpose and audience
+- Establish module code (kebab-case) and name
+- Choose category (Domain, Creative, Technical, Business, Personal)
+- Plan component architecture
 
-The workflow loads critical variables from the BMB configuration:
+**Module Brief Integration:**
 
-- **custom_module_location**: Where custom modules are created (default: `bmad/`)
+- Auto-detects existing briefs
-- **user_name**: Module author information
+- Uses as pre-populated blueprint
-- **date**: Automatic timestamp for versioning
+- Accelerates planning phase
 
-## Workflow Structure
+### Phase 2: Architecture Planning
 
-### Files Included
+- Create directory hierarchy
+- Setup configuration system
+- Define installer structure
+- Establish component folders
+
+### Phase 3: Component Creation
+
+- Optional first agent creation
+- Optional first workflow creation
+- Component placeholder generation
+- Integration validation
+
+### Phase 4: Installation Setup
+
+- Create install-config.yaml
+- Configure deployment questions
+- Setup installer logic
+- Post-install messaging
+
+### Phase 5: Documentation
+
+- Generate comprehensive README
+- Create development roadmap
+- Provide quick commands
+- Document next steps
+
+## Output Structure
+
+### Generated Directory
 
 ```
-create-module/
+bmad/{module-code}/
-├── workflow.yaml           # Configuration and metadata
+├── agents/              # Agent definitions
-├── instructions.md         # Step-by-step execution guide
+├── workflows/           # Workflow processes
-├── checklist.md           # Validation criteria
+├── tasks/              # Reusable tasks
-├── module-structure.md    # Module architecture guide
+├── templates/          # Document templates
-├── installer-templates/   # Installation templates
+├── data/               # Module data files
+├── _module-installer/  # Installation logic
 │   ├── install-config.yaml
 │   └── installer.js
-└── README.md             # This file
+├── README.md           # Module documentation
+├── TODO.md            # Development roadmap
+└── config.yaml        # Runtime configuration
 ```
 
-## Workflow Process
+### Configuration Files
 
-### Phase 1: Concept Definition (Steps 1-2)
+**install-config.yaml** - Installation questions
 
-**Module Vision and Identity**
+```yaml
+questions:
+  - id: user_name
+    prompt: 'Your name?'
+    default: 'User'
+  - id: output_folder
+    prompt: 'Output location?'
+    default: './output'
+```
 
-- Define module concept, purpose, and target audience
+**config.yaml** - Generated from user answers during install
-- Establish module code (kebab-case) and friendly name
-- Choose module category (Domain-Specific, Creative, Technical, Business, Personal)
-- Plan component architecture with agent and workflow specifications
 
-**Module Brief Integration**
+```yaml
+user_name: 'John Doe'
+output_folder: './my-output'
+```
 
-- Automatically detects existing module briefs in output folder
+## Module Components
-- Can load and use briefs as pre-populated blueprints
-- Accelerates planning when comprehensive brief exists
 
-### Phase 2: Architecture Planning (Steps 3-4)
+### Agents
 
-**Directory Structure Creation**
+- Full module agents with workflows
+- Expert agents with sidecars
+- Simple utility agents
 
-- Creates complete module directory hierarchy
+### Workflows
-- Sets up agent, workflow, task, template, and data folders
-- Establishes installer directory with proper configuration
 
-**Module Configuration**
+- Multi-step guided processes
+- Configuration-driven
+- Web bundle support
 
-- Defines configuration questions in install-config.yaml (config.yaml generated during installation)
+### Tasks
-- Configures component counts and references
-- Sets up output and data folder specifications
 
-### Phase 3: Component Creation (Steps 5-6)
+- Reusable operations
+- Agent-agnostic
+- Modular components
 
-**Interactive Component Building**
+### Templates
 
-- Optional creation of first agent using create-agent workflow
+- Document structures
-- Optional creation of first workflow using create-workflow workflow
+- Output formats
-- Creates placeholders for components to be built later
+- Report templates
-
-**Workflow Integration**
-
-- Seamlessly invokes sub-workflows for component creation
-- Ensures proper file placement and structure
-- Maintains module consistency across components
-
-### Phase 4: Installation and Documentation (Steps 7-9)
-
-**Installer Infrastructure**
-
-- Creates install-config.yaml with configuration questions for deployment
-- Sets up optional installer.js for complex installation logic
-- Configures post-install messaging and instructions
-
-**Comprehensive Documentation**
-
-- Generates detailed README.md with usage examples
-- Creates development roadmap for remaining components
-- Provides quick commands for continued development
-
-### Phase 5: Validation and Finalization (Step 10)
-
-**Quality Assurance**
-
-- Validates directory structure and configuration files
-- Checks component references and path consistency
-- Ensures installer configuration is deployment-ready
-- Provides comprehensive module summary and next steps
-
-## Output
-
-### Generated Files
-
-- **Module Directory**: Complete module structure at `{project-root}/bmad/{module_code}/`
-- **Configuration Files**:
-  - Source: install-config.yaml (configuration questions)
-  - Target: config.yaml (generated from user answers during installation)
-- **Documentation**: README.md, TODO.md development roadmap
-- **Component Placeholders**: Structured folders for agents, workflows, and tasks
-
-### Output Structure
-
-The workflow creates a complete module ready for development:
-
-1. **Module Identity** - Name, code, version, and metadata
-2. **Directory Structure** - Proper BMAD module hierarchy
-3. **Configuration System** - Runtime and installation configs
-4. **Component Framework** - Ready-to-use agent and workflow scaffolding
-5. **Installation Infrastructure** - Deployment-ready installer
-6. **Documentation Suite** - README, roadmap, and development guides
-
-## Requirements
-
-- **Module Brief** (optional but recommended) - Use module-brief workflow first for best results
-- **BMAD Core Configuration** - Properly configured BMB config.yaml
-- **Build Tools Access** - create-agent and create-workflow workflows must be available
 
 ## Best Practices
 
-### Before Starting
+### Planning
 
-1. **Create a Module Brief** - Run module-brief workflow for comprehensive planning
+1. **Use module-brief workflow first** - Creates comprehensive blueprint
-2. **Review Existing Modules** - Study similar modules in `/bmad/` for patterns and inspiration
+2. **Define clear scope** - Avoid feature creep
-3. **Define Clear Scope** - Have a concrete vision of what the module will accomplish
+3. **Plan component interactions** - Map agent/workflow relationships
 
-### During Execution
+### Structure
 
-1. **Use Module Briefs** - Load existing briefs when prompted for accelerated development
+1. **Follow conventions** - Use established patterns
-2. **Start Simple** - Create one core agent and workflow, then expand iteratively
+2. **Keep components focused** - Single responsibility
-3. **Leverage Sub-workflows** - Use create-agent and create-workflow for quality components
+3. **Document thoroughly** - Clear README and inline docs
-4. **Validate Early** - Review generated structure before proceeding to next phases
 
-### After Completion
+### Development
 
-1. **Follow the Roadmap** - Use generated TODO.md for systematic development
+1. **Start with core agent** - Build primary functionality first
-2. **Test Installation** - Validate installer with `bmad install {module_code}`
+2. **Create key workflows** - Essential processes before edge cases
-3. **Iterate Components** - Use quick commands to add agents and workflows
+3. **Test incrementally** - Validate as you build
-4. **Document Progress** - Update README.md as the module evolves
 
-## Troubleshooting
+### Installation
 
-### Common Issues
+1. **Minimal config questions** - Only essential settings
+2. **Smart defaults** - Sensible out-of-box experience
+3. **Clear post-install** - Guide users to first steps
 
-**Issue**: Module already exists at target location
+## Integration Points
 
-- **Solution**: Choose a different module code or remove existing module
+### With Other Workflows
-- **Check**: Verify output folder permissions and available space
 
-**Issue**: Sub-workflow invocation fails
+- **module-brief** - Strategic planning input
+- **create-agent** - Agent component creation
+- **create-workflow** - Workflow building
+- **redoc** - Documentation maintenance
 
-- **Solution**: Ensure create-agent and create-workflow workflows are available
+### With BMad Core
-- **Check**: Validate workflow paths in config.yaml
 
-**Issue**: Installation configuration invalid
+- Uses core framework capabilities
+- Integrates with module system
+- Follows BMad conventions
 
-- **Solution**: Review install-config.yaml syntax and paths
+## Examples
-- **Check**: Ensure all referenced paths use {project-root} variables correctly
 
-## Customization
+### Domain-Specific Module
 
-To customize this workflow:
+```
+Category: Domain-Specific
+Code: legal-advisor
+Components:
+- Contract Review Agent
+- Compliance Workflow
+- Legal Templates
+```
 
-1. **Modify Instructions** - Update instructions.md to adjust scaffolding steps
+### Creative Module
-2. **Extend Templates** - Add new installer templates in installer-templates/
-3. **Update Validation** - Enhance checklist.md with additional quality checks
-4. **Add Components** - Integrate additional sub-workflows for specialized components
 
-## Version History
+```
+Category: Creative
+Code: story-builder
+Components:
+- Narrative Agent
+- Plot Workflow
+- Character Templates
+```
 
-- **v1.0.0** - Initial release
+### Technical Module
-  - Interactive module scaffolding
-  - Component integration with create-agent and create-workflow
-  - Complete installation infrastructure
-  - Module brief integration support
 
-## Support
+```
+Category: Technical
+Code: api-tester
+Components:
+- Test Runner Agent
+- API Validation Workflow
+- Test Report Templates
+```
 
-For issues or questions:
+## Workflow Files
 
-- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
+```
-- Study module structure patterns at `module-structure.md`
+create-module/
-- Validate output using `checklist.md`
+├── workflow.yaml          # Configuration
-- Consult existing modules in `/bmad/` for examples
+├── instructions.md        # Step guide
+├── checklist.md          # Validation
+├── module-structure.md   # Architecture
+├── installer-templates/  # Install files
+└── README.md            # This file
+```
 
----
+## Related Documentation
 
-_Part of the BMad Method v6 - BMB (Builder) Module_
+- [Module Structure](./module-structure.md)
+- [Module Brief Workflow](../module-brief/README.md)
+- [Create Agent](../create-agent/README.md)
+- [Create Workflow](../create-workflow/README.md)
+- [BMB Module](../../README.md)

src/modules/bmb/workflows/create-workflow/instructions.md

@@ -108,7 +108,8 @@ Most workflows should be `standalone: true` to give users direct access.
 1. **Yes (Recommended)** - Users can run it directly (standalone: true)
 2. **No** - Only called by other workflows/agents (standalone: false)
 
-Most workflows choose option 1:</ask>
+Most workflows choose option 1:
+</ask>
 
 <action>Store {{standalone_setting}} as true or false based on response</action>
 
@@ -150,7 +151,8 @@ The architecture workflow is an excellent example of intent-based with prescript
 2. **Prescriptive** - Structured, consistent, controlled interactions
 3. **Mixed/Balanced** - I'll help you decide step-by-step
 
-What feels right for your workflow's purpose?</ask>
+What feels right for your workflow's purpose?
+</ask>
 
 <action>Store {{instruction_style}} preference</action>
 
@@ -185,11 +187,12 @@ Beyond style, consider **how interactive** this workflow should be:
 
 <ask>What interactivity level suits this workflow?
 
-1. **High** - Highly collaborative, user actively involved throughout
+1. **High** - Highly collaborative, user actively involved throughout (Recommended)
-2. **Medium** - Guided with key decision points (most common)
+2. **Medium** - Guided with key decision points
-3. **Low** - Autonomous with final review
+3. **Low** - Mostly autonomous with final review
 
-Select the level that matches your workflow's purpose:</ask>
+Select the level that matches your workflow's purpose:
+</ask>
 
 <action>Store {{interactivity_level}} preference</action>
 
@@ -487,6 +490,7 @@ Generate the template.md file following guide conventions:
    # Document Title
 
    **Date:** {{date}}
+
    **Author:** {{user_name}}
    ```
 
@@ -575,7 +579,9 @@ Review the created workflow:
 4. Validate YAML syntax
 5. Confirm all placeholders are replaced
 
-**Standard Config Validation:** 6. Verify workflow.yaml contains standard config block:
+**Standard Config Validation:**
+
+6. Verify workflow.yaml contains standard config block:
 
 - config_source defined
 - output_folder, user_name, communication_language pulled from config
@@ -584,7 +590,9 @@ Review the created workflow:
 7. Check instructions use config variables where appropriate
 8. Verify template includes config variables in metadata (if document workflow)
 
-**YAML/Instruction/Template Alignment:** 9. Cross-check all workflow.yaml variables against instruction usage:
+**YAML/Instruction/Template Alignment:**
+
+9. Cross-check all workflow.yaml variables against instruction usage:
 
 - Are all yaml variables referenced in instructions.md OR template.md?
 - Are there hardcoded values that should be variables?

src/modules/bmm/README.md

@@ -1,141 +1,144 @@
 # BMM - BMad Method Module
 
-The BMM (BMad Method Module) is the core orchestration system for the BMad Method, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
+Core orchestration system for AI-driven agile development, providing comprehensive lifecycle management through specialized agents and workflows.
 
-## 📚 Essential Reading
+## Table of Contents
 
-**Before using BMM, you MUST read the [BMM v6 Workflows Guide](./workflows/README.md).** This document explains the revolutionary v6a workflow system and how all components work together.
+- [Essential Reading](#essential-reading)
+- [Module Structure](#module-structure)
+- [Quick Start](#quick-start)
+- [Key Concepts](#key-concepts)
+- [Scale Levels](#scale-levels)
+- [Story Lifecycle](#story-lifecycle)
+- [Best Practices](#best-practices)
+
+## Essential Reading
+
+**[📖 BMM v6 Workflows Guide](./workflows/README.md)** - Required reading before using BMM. Explains the revolutionary workflow system and component integration.
 
 ## Module Structure
 
-### 🤖 `/agents`
+### 🤖 Agents
 
-Specialized AI agents for different development roles:
+**Core Development Roles:**
 
-- **PM** (Product Manager) - Product planning and requirements
+- **PM** - Product Manager for planning and requirements
 - **Analyst** - Business analysis and research
 - **Architect** - Technical architecture and design
-- **SM** (Scrum Master) - Sprint and story management
+- **SM** - Scrum Master for sprint and story management
-- **DEV** (Developer) - Code implementation
+- **DEV** - Developer for implementation
-- **TEA** (Test Architect) - Test Architect
+- **TEA** - Test Architect for quality assurance
 - **UX** - User experience design
-- And more specialized roles
 
-**Game Development Agents** (Optional):
+**Game Development** (Optional):
-During installation, you can optionally include game development specialists:
 
-- **Game Designer** - Creative vision and game design documents (GDD)
+- **Game Designer** - Creative vision and GDD creation
 - **Game Developer** - Game-specific implementation
-- **Game Architect** - Game systems and technical infrastructure
+- **Game Architect** - Game systems and infrastructure
 
-These agents come with specialized workflows (`brainstorm-game`, `game-brief`, `gdd`) and are only installed if you select "Include Game Planning Agents and Workflows" during BMM installation.
+### 📋 Workflows
 
-### 📋 `/workflows`
+Four-phase methodology adapting to project complexity:
 
-The heart of BMM - structured workflows for the four development phases:
+**1. Analysis** (Optional)
 
-1. **Analysis Phase** (Optional)
 - `brainstorm-project` - Project ideation
 - `research` - Market/technical research
 - `product-brief` - Product strategy
 
-2. **Planning Phase** (Required)
+**2. Planning** (Required)
-   - `prd` - Scale-adaptive project planning
-   - Routes to appropriate documentation based on project complexity
 
-3. **Solutioning Phase** (Level 3-4 projects)
+- `prd` - Scale-adaptive planning
-   - `3-solutioning` - Architecture design
+- Routes to appropriate documentation level
-   - `tech-spec` - Epic-specific technical specifications
 
-4. **Implementation Phase** (Iterative)
+**3. Solutioning** (Level 3-4)
-   - `create-story` - Story drafting (SM agent)
-   - `story-ready` - Approve story for development (SM agent)
-   - `story-context` - Expertise injection (SM agent)
-   - `dev-story` - Implementation (DEV agent)
-   - `story-done` - Mark story done (DEV agent)
-   - `code-review` - Quality validation (DEV/SR agent)
-   - `correct-course` - Issue resolution
-   - `retrospective` - Continuous improvement
 
-### 👥 `/teams`
+- `architecture` - System design
+- `tech-spec` - Epic technical specifications
 
-Pre-configured agent teams for different project types and phases. Teams coordinate multiple agents working together on complex tasks.
+**4. Implementation** (Iterative)
 
-### 📝 `/tasks`
+- `create-story` - Draft stories
+- `story-context` - Inject expertise
+- `dev-story` - Implement
+- `code-review` - Validate quality
 
-Reusable task definitions that agents execute within workflows. These are the atomic units of work that compose into larger workflows.
+### 👥 Teams
 
-### 🔧 `/sub-modules`
+Pre-configured agent groups for coordinated complex tasks.
 
-Extension modules that add specialized capabilities to BMM.
+### 📝 Tasks
 
-### 🏗️ `/testarch`
+Atomic work units composing into larger workflows.
 
-Test architecture and quality assurance components. The **[Test Architect (TEA) Guide](./testarch/README.md)** provides comprehensive testing strategy across 9 workflows: framework setup, CI/CD, test design, ATDD, automation, traceability, NFR assessment, quality gates, and test review.
+### 🏗️ Test Architecture
+
+**[TEA Guide](./testarch/README.md)** - Comprehensive testing strategy across 9 specialized workflows.
 
 ## Quick Start
 
-```bash
+1. **Load PM agent** in your IDE
-# Load the PM agent - either via slash command or drag and drop or @ the agent file.
+2. **Wait for menu** to appear
-# Once loaded, the agent should greet you and offer a menu of options. You can enter:
+3. **Run workflow:**
-`*prd`
    ```
+   *prd
+   ```
+
+**IDE Instructions:**
+
+- [Claude Code](../../docs/ide-info/claude-code.md)
+- [Cursor](../../docs/ide-info/cursor.md)
+- [VS Code](../../docs/ide-info/windsurf.md)
+- [Others](../../docs/ide-info/)
 
 ## Key Concepts
 
 ### Scale Levels
 
-BMM automatically adapts to project complexity:
+BMM automatically adapts complexity:
 
-- **Level 0**: Single atomic change
+| Level | Stories       | Documentation     |
-- **Level 1**: 1-10 stories, minimal documentation
+| ----- | ------------- | ----------------- |
-- **Level 2**: 5-15 stories, focused PRD
+| 0     | Single change | Minimal           |
-- **Level 3**: 12-40 stories, full architecture
+| 1     | 1-10          | Light PRD         |
-- **Level 4**: 40+ stories, enterprise scale
+| 2     | 5-15          | Focused PRD       |
+| 3     | 12-40         | Full architecture |
+| 4     | 40+           | Enterprise scale  |
 
-### Just-In-Time Design
+### Story Lifecycle
 
-Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
+Four-state machine tracked in status file:
-
-### Story State Machine
-
-Stories flow through a 4-state lifecycle tracked in the status file:
 
 ```
 BACKLOG → TODO → IN PROGRESS → DONE
 ```
 
-- **BACKLOG**: Ordered list of stories to be drafted (populated at phase transition)
+- **BACKLOG** - Ordered stories to draft
-- **TODO**: Single story ready for SM to draft (or drafted, awaiting approval)
+- **TODO** - Ready for SM drafting
-- **IN PROGRESS**: Single story approved for DEV to implement
+- **IN PROGRESS** - Approved for DEV
-- **DONE**: Completed stories with dates and points
+- **DONE** - Completed with metrics
 
-Agents never search for "next story" - they always read the exact story from the status file. Simple workflows (`story-ready`, `story-done`) advance the queue automatically.
+### Just-In-Time Design
+
+Technical specifications created per epic during implementation, enabling learning and adaptation.
 
 ### Context Injection
 
-Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.
+Dynamic technical guidance generated for each story, providing exact expertise when needed.
-
-## Integration with BMad Core
-
-BMM integrates seamlessly with the BMad Core framework, leveraging:
-
-- The agent execution engine
-- Workflow orchestration
-- Task management
-- Team coordination
-
-## Related Documentation
-
-- [BMM Workflows Guide](./workflows/README.md) - **Start here!**
-- [Test Architect (TEA) Guide](./testarch/README.md) - Quality assurance and testing strategy
 
 ## Best Practices
 
-1. **Always start with the workflows** - Let workflows guide your process
+1. **Start with workflows** - Let process guide you
-2. **Respect the scale** - Don't over-document small projects
+2. **Respect scale** - Don't over-document small projects
-3. **Trust the process** - The methodology has been carefully designed
+3. **Trust the process** - Methodology carefully designed
+4. **Use status file** - Single source of truth for stories
+
+## Related Documentation
+
+- **[Workflows Guide](./workflows/README.md)** - Complete workflow reference
+- **[Test Architect Guide](./testarch/README.md)** - Testing strategy
+- **[IDE Setup](../../docs/ide-info/)** - Environment configuration
 
 ---
 
-For detailed information about the complete BMad Method workflow system, see the [BMM Workflows README](./workflows/README.md).
+For complete BMad Method workflow system details, see the [BMM Workflows README](./workflows/README.md).

src/modules/bmm/workflows/1-analysis/brainstorm-game/instructions.md

@@ -5,20 +5,20 @@
 
 <workflow>
 
-  <step n="1" goal="Validate workflow readiness">
+  <step n="1" goal="Validate workflow readiness" tag="workflow-status">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-      <param>mode: validate</param>
-      <param>calling_workflow: brainstorm-game</param>
-    </invoke-workflow>
 
-    <check if="status_exists == false">
+    <check if="status file not found">
-      <output>{{suggestion}}</output>
+      <output>No workflow status file found. Game brainstorming is optional - you can continue without status tracking.</output>
-      <output>Note: Game brainstorming is optional. Continuing without progress tracking.</output>
       <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="status_exists == true">
+    <check if="status file found">
-      <action>Store {{status_file_path}} for later updates</action>
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+      <action>Parse workflow_status section</action>
+      <action>Check status of "brainstorm-game" workflow</action>
+      <action>Get project_level from YAML metadata</action>
+      <action>Find first non-completed workflow (next expected workflow)</action>
 
       <check if="project_type != 'game'">
         <output>Note: This is a {{project_type}} project. Game brainstorming is designed for game projects.</output>
@@ -28,12 +28,27 @@
         </check>
       </check>
 
-      <check if="warning != ''">
+      <check if="brainstorm-game status is file path (already completed)">
-        <output>{{warning}}</output>
+        <output>⚠️ Game brainstorming session already completed: {{brainstorm-game status}}</output>
-        <output>Note: Game brainstorming can be valuable at any project stage.</output>
+        <ask>Re-running will create a new session. Continue? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Use workflow-status to see your next step.</output>
+          <action>Exit workflow</action>
         </check>
       </check>
 
+      <check if="brainstorm-game is not the next expected workflow (latter items are completed already in the list)">
+        <output>⚠️ Next expected workflow: {{next_workflow}}. Game brainstorming is out of sequence.</output>
+        <ask>Continue with game brainstorming anyway? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Run {{next_workflow}} instead.</output>
+          <action>Exit workflow</action>
+        </check>
+      </check>
+
+      <action>Set standalone_mode = false</action>
+    </check>
+
   </step>
 
   <step n="2" goal="Load game brainstorming context and techniques">
@@ -66,17 +81,16 @@
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status and complete">
+  <step n="4" goal="Update status and complete" tag="workflow-status">
     <check if="standalone_mode != true">
-      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-        <param>mode: update</param>
+      <action>Find workflow_status key "brainstorm-game"</action>
-        <param>action: complete_workflow</param>
+      <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-        <param>workflow_name: brainstorm-game</param>
+      <action>Update workflow_status["brainstorm-game"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
-      </invoke-workflow>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-      <check if="success == true">
+      <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-        <output>Status updated! Next: {{next_workflow}}</output>
+      <action>Determine next agent from path file based on next workflow</action>
-      </check>
     </check>
 
     <output>**✅ Game Brainstorming Session Complete, {user_name}!**
@@ -88,16 +102,21 @@
 {{#if standalone_mode != true}}
 **Status Updated:**
 
-- Progress tracking updated
+- Progress tracking updated: brainstorm-game marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** You can run other analysis workflows (research, game-brief) before proceeding
 
 Check status anytime with: `workflow-status`
 {{else}}
-**Next Steps:**
 Since no workflow is in progress:
 
 - Refer to the BMM workflow guide if unsure what to do next

src/modules/bmm/workflows/1-analysis/brainstorm-project/README.md

@@ -1,29 +1,113 @@
----
-last-redoc-date: 2025-10-01
----
-
 # Project Brainstorming Workflow
 
-This workflow facilitates structured ideation for non-game software projects through systematic exploration of problem spaces, architectures, and implementation strategies. Unlike traditional requirement gathering, it employs creative techniques to uncover non-obvious approaches and identify innovative solutions that address core business needs while considering technical constraints and organizational capabilities.
+Structured ideation for software projects exploring problem spaces, architectures, and innovative solutions beyond traditional requirements gathering.
 
-The workflow operates through a project-specific context framework that captures business objectives, technical environment, stakeholder needs, and organizational constraints. It generates multiple solution vectors through parallel ideation tracks: architectural approaches, user experience paradigms, integration patterns, and value delivery mechanisms. Each track produces concrete proposals that are evaluated against feasibility, impact, and alignment with strategic objectives.
+## Table of Contents
 
-Critical differentiators include its focus on solution innovation rather than requirement enumeration, emphasis on technical-business alignment from inception, and structured approach to surfacing hidden assumptions. The workflow produces actionable outputs that directly feed into Product Brief development, ensuring that creative exploration translates into concrete planning artifacts.
+- [Purpose](#purpose)
+- [Usage](#usage)
+- [Process](#process)
+- [Inputs & Outputs](#inputs--outputs)
+- [Integration](#integration)
+
+## Purpose
+
+Generate multiple solution approaches for software projects through:
+
+- Parallel ideation tracks (architecture, UX, integration, value delivery)
+- Technical-business alignment from inception
+- Hidden assumption discovery
+- Innovation beyond obvious solutions
 
 ## Usage
 
 ```bash
-bmad bmm 1-analysis brainstorm-project
+# Run brainstorming session
+bmad bmm *brainstorm-project
+
+# Or via Analyst agent
+*brainstorm-project
 ```
 
-## Inputs
+## Process
 
-- **Project Context Document**: Business objectives, technical environment, stakeholder landscape, organizational constraints, success criteria, and known pain points
+### 1. Context Capture
-- **Problem Statement** (optional): Core business challenge or opportunity driving the project
 
-## Outputs
+- Business objectives and constraints
+- Technical environment
+- Stakeholder needs
+- Success criteria
 
-- **Architecture Proposals**: Multiple technical approaches with trade-off analysis and feasibility assessments
+### 2. Parallel Ideation
-- **Value Delivery Framework**: Prioritized feature concepts aligned with business objectives and user needs
+
-- **Risk and Opportunity Analysis**: Identified technical dependencies, integration challenges, and innovation opportunities
+- **Architecture Track**: Technical approaches with trade-offs
-- **Strategic Recommendation**: Synthesized direction with rationale and implementation considerations
+- **UX Track**: Interface paradigms and user journeys
+- **Integration Track**: System connection patterns
+- **Value Track**: Feature prioritization and delivery
+
+### 3. Solution Synthesis
+
+- Evaluate feasibility and impact
+- Align with strategic objectives
+- Surface hidden assumptions
+- Generate recommendations
+
+## Inputs & Outputs
+
+### Inputs
+
+| Input             | Type     | Purpose                                       |
+| ----------------- | -------- | --------------------------------------------- |
+| Project Context   | Document | Business objectives, environment, constraints |
+| Problem Statement | Optional | Core challenge or opportunity                 |
+
+### Outputs
+
+| Output                   | Content                                     |
+| ------------------------ | ------------------------------------------- |
+| Architecture Proposals   | Multiple approaches with trade-off analysis |
+| Value Framework          | Prioritized features aligned to objectives  |
+| Risk Analysis            | Dependencies, challenges, opportunities     |
+| Strategic Recommendation | Synthesized direction with rationale        |
+
+## Integration
+
+### Workflow Chain
+
+1. **brainstorm-project** ← Current step
+2. research (optional deep dive)
+3. product-brief (strategic document)
+4. Phase 2 planning (PRD/tech-spec)
+
+### Feed Into
+
+- Product Brief development
+- Architecture decisions
+- PRD requirements
+- Epic prioritization
+
+## Best Practices
+
+1. **Prepare context** - Gather business and technical background
+2. **Think broadly** - Explore non-obvious approaches
+3. **Document assumptions** - Capture implicit beliefs
+4. **Consider constraints** - Technical, organizational, resource
+5. **Focus on value** - Align to business objectives
+
+## Configuration
+
+```yaml
+# bmad/bmm/config.yaml
+output_folder: ./output
+project_name: Your Project
+```
+
+## Related Workflows
+
+- [Research](../research/README.md) - Deep investigation
+- [Product Brief](../product-brief/README.md) - Strategic planning
+- [PRD](../../2-plan-workflows/prd/README.md) - Requirements document
+
+---
+
+Part of BMad Method v6 - Phase 1 Analysis workflows

src/modules/bmm/workflows/1-analysis/brainstorm-project/instructions.md

@@ -8,26 +8,41 @@
 
 <workflow>
 
-  <step n="1" goal="Validate workflow readiness">
+  <step n="1" goal="Validate workflow readiness" tag="workflow-status">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-      <param>mode: validate</param>
-      <param>calling_workflow: brainstorm-project</param>
-    </invoke-workflow>
 
-    <check if="status_exists == false">
+    <check if="status file not found">
-      <output>{{suggestion}}</output>
+      <output>No workflow status file found. Brainstorming is optional - you can continue without status tracking.</output>
-      <output>Note: Brainstorming is optional. Continuing without progress tracking.</output>
       <action>Set standalone_mode = true</action>
     </check>
 
-    <check if="status_exists == true">
+    <check if="status file found">
-      <action>Store {{status_file_path}} for later updates</action>
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+      <action>Parse workflow_status section</action>
+      <action>Check status of "brainstorm-project" workflow</action>
+      <action>Get project_level from YAML metadata</action>
+      <action>Find first non-completed workflow (next expected workflow)</action>
 
-      <check if="warning != ''">
+      <check if="brainstorm-project status is file path (already completed)">
-        <output>{{warning}}</output>
+        <output>⚠️ Brainstorming session already completed: {{brainstorm-project status}}</output>
-        <output>Note: Brainstorming can be valuable at any project stage.</output>
+        <ask>Re-running will create a new session. Continue? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Use workflow-status to see your next step.</output>
+          <action>Exit workflow</action>
         </check>
       </check>
+
+      <check if="brainstorm-project is not the next expected workflow (anything after brainstorm-project is completed already)">
+        <output>⚠️ Next expected workflow: {{next_workflow}}. Brainstorming is out of sequence.</output>
+        <ask>Continue with brainstorming anyway? (y/n)</ask>
+        <check if="n">
+          <output>Exiting. Run {{next_workflow}} instead.</output>
+          <action>Exit workflow</action>
+        </check>
+      </check>
+
+      <action>Set standalone_mode = false</action>
+    </check>
   </step>
 
   <step n="2" goal="Load project brainstorming context">
@@ -51,36 +66,40 @@
     </invoke-workflow>
   </step>
 
-  <step n="4" goal="Update status and complete">
+  <step n="4" goal="Update status and complete" tag="workflow-status">
     <check if="standalone_mode != true">
-      <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+      <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-        <param>mode: update</param>
+      <action>Find workflow_status key "brainstorm-project"</action>
-        <param>action: complete_workflow</param>
+      <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-        <param>workflow_name: brainstorm-project</param>
+      <action>Update workflow_status["brainstorm-project"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
-      </invoke-workflow>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-      <check if="success == true">
+      <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-        <output>Status updated! Next: {{next_workflow}}</output>
+      <action>Determine next agent from path file based on next workflow</action>
-      </check>
     </check>
 
     <output>**✅ Brainstorming Session Complete, {user_name}!**
 
 **Session Results:**
+
 - Brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
 
 {{#if standalone_mode != true}}
 **Status Updated:**
+
 - Progress tracking updated
 
 **Next Steps:**
+
 - **Next required:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** You can run other analysis workflows (research, product-brief) before proceeding
 
 Check status anytime with: `workflow-status`
 {{else}}
 **Next Steps:**
+
 Since no workflow is in progress:
+
 - Refer to the BMM workflow guide if unsure what to do next
 - Or run `workflow-init` to create a workflow path and get guided next steps
 {{/if}}

src/modules/bmm/workflows/1-analysis/game-brief/instructions.md

@@ -9,20 +9,20 @@
 
 <workflow>
 
-<step n="0" goal="Validate workflow readiness">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-  <param>mode: validate</param>
-  <param>calling_workflow: game-brief</param>
-</invoke-workflow>
 
-<check if="status_exists == false">
+<check if="status file not found">
-  <output>{{suggestion}}</output>
+  <output>No workflow status file found. Game brief is optional - you can continue without status tracking.</output>
-  <output>Note: Game brief is optional. Continuing without progress tracking.</output>
   <action>Set standalone_mode = true</action>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "game-brief" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_type != 'game'">
     <output>Note: This is a {{project_type}} project. Game brief is designed for game projects.</output>
@@ -32,11 +32,26 @@
     </check>
   </check>
 
-  <check if="warning != ''">
+  <check if="game-brief status is file path (already completed)">
-    <output>{{warning}}</output>
+    <output>⚠️ Game Brief already completed: {{game-brief status}}</output>
-    <output>Note: Game brief can provide valuable vision clarity at any stage.</output>
+    <ask>Re-running will overwrite the existing brief. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
     </check>
   </check>
+
+  <check if="game-brief is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Game Brief is out of sequence.</output>
+    <ask>Continue with Game Brief anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
 </step>
 
 <step n="1" goal="Initialize game brief session">
@@ -309,17 +324,16 @@ This brief will serve as the primary input for creating the Game Design Document
 <template-output>executive_brief</template-output>
 </step>
 
-<step n="16" goal="Update status and complete">
+<step n="16" goal="Update status and complete" tag="workflow-status">
 <check if="standalone_mode != true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-    <param>mode: update</param>
+  <action>Find workflow_status key "game-brief"</action>
-    <param>action: complete_workflow</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-    <param>workflow_name: game-brief</param>
+  <action>Update workflow_status["game-brief"] = "{output_folder}/bmm-game-brief-{{game_name}}-{{date}}.md"</action>
-  </invoke-workflow>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-    <output>Status updated! Next: {{next_workflow}}</output>
+<action>Determine next agent from path file based on next workflow</action>
-  </check>
 </check>
 
 <output>**✅ Game Brief Complete, {user_name}!**
@@ -331,17 +345,17 @@ This brief will serve as the primary input for creating the Game Design Document
 {{#if standalone_mode != true}}
 **Status Updated:**
 
-- Progress tracking updated
+- Progress tracking updated: game-brief marked complete
+- Next workflow: {{next_workflow}}
   {{else}}
-  Note: Running in standalone mode (no status file).
+  **Note:** Running in standalone mode (no progress tracking)
-  To track progress across workflows, run `workflow-init` first.
   {{/if}}
 
 **Next Steps:**
 
 {{#if standalone_mode != true}}
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Consider creating a prototype of core mechanic or validating assumptions with target players before proceeding
 
 Check status anytime with: `workflow-status`

src/modules/bmm/workflows/1-analysis/product-brief/instructions.md

@@ -9,34 +9,45 @@
 
 <workflow>
 
-<step n="0" goal="Validate workflow readiness">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-  <param>mode: validate</param>
-  <param>calling_workflow: product-brief</param>
-</invoke-workflow>
 
-<check if="status_exists == false">
+<check if="status file not found">
-  <output>{{suggestion}}</output>
+  <output>No workflow status file found. Product Brief is optional - you can continue without status tracking.</output>
-  <output>Note: Product Brief is optional. You can continue without status tracking.</output>
   <action>Set standalone_mode = true</action>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "product-brief" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 2">
     <output>Note: Product Brief is most valuable for Level 2+ projects. Your project is Level {{project_level}}.</output>
     <output>You may want to skip directly to technical planning instead.</output>
   </check>
 
-  <check if="warning != ''">
+  <check if="product-brief status is file path (already completed)">
-    <output>{{warning}}</output>
+    <output>⚠️ Product Brief already completed: {{product-brief status}}</output>
-    <ask>Continue with Product Brief anyway? (y/n)</ask>
+    <ask>Re-running will overwrite the existing brief. Continue? (y/n)</ask>
     <check if="n">
-      <output>Exiting. {{suggestion}}</output>
+      <output>Exiting. Use workflow-status to see your next step.</output>
       <action>Exit workflow</action>
     </check>
   </check>
+
+  <check if="product-brief is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Product Brief is out of sequence.</output>
+    <ask>Continue with Product Brief anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 </step>
 
@@ -61,6 +72,7 @@
 <ask>How would you like to work through the brief?
 
 **1. Interactive Mode** - We'll work through each section together, discussing and refining as we go
+
 **2. YOLO Mode** - I'll generate a complete draft based on our conversation so far, then we'll refine it together
 
 Which approach works best for you?</ask>
@@ -273,17 +285,16 @@ This brief will serve as the primary input for creating the Product Requirements
 <template-output>executive_brief</template-output>
 </step>
 
-<step n="16" goal="Update status file on completion">
+<step n="16" goal="Update status file on completion" tag="workflow-status">
 <check if="standalone_mode != true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-    <param>mode: update</param>
+  <action>Find workflow_status key "product-brief"</action>
-    <param>action: complete_workflow</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-    <param>workflow_name: product-brief</param>
+  <action>Update workflow_status["product-brief"] = "{output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md"</action>
-  </invoke-workflow>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-    <output>Status updated! Next: {{next_workflow}}</output>
+<action>Determine next agent from path file based on next workflow</action>
-  </check>
 </check>
 
 <output>**✅ Product Brief Complete, {user_name}!**
@@ -295,8 +306,8 @@ This brief will serve as the primary input for creating the Product Requirements
 {{#if standalone_mode != true}}
 **Status Updated:**
 
-- Progress tracking updated
+- Progress tracking updated: product-brief marked complete
-- Current workflow marked complete
+- Next workflow: {{next_workflow}}
   {{else}}
   **Note:** Running in standalone mode (no progress tracking)
   {{/if}}
@@ -305,7 +316,7 @@ This brief will serve as the primary input for creating the Product Requirements
 
 {{#if standalone_mode != true}}
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Gather additional stakeholder input or run research workflows before proceeding
 
 Check status anytime with: `workflow-status`

src/modules/bmm/workflows/1-analysis/research/instructions-deep-prompt.md

@@ -374,60 +374,50 @@ Select option (1-4):</ask>
 
 </step>
 
-<step n="FINAL" goal="Update status file on completion">
+<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
+<check if="standalone_mode != true">
-<action>Find the most recent file (by date in filename)</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-deep-prompt-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="status file exists">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Determine next agent from path file based on next workflow</action>
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: research</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated! Next: {{next_workflow}}</output>
 </check>
 
 <output>**✅ Deep Research Prompt Generated**
 
 **Research Prompt:**
 
-- Structured research prompt generated and saved
+- Structured research prompt generated and saved to {output_folder}/bmm-research-deep-prompt-{{date}}.md
 - Ready to execute with ChatGPT, Claude, Gemini, or Grok
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: research (deep-prompt) ✓
+- Progress tracking updated: research marked complete
-- Progress: {{new_progress_percentage}}%
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Execute the research prompt with AI platform, gather findings, or run additional research workflows
 
 Check status anytime with: `workflow-status`
-</output>
+{{else}}
-</check>
-
-<check if="status file not found">
-  <output>**✅ Deep Research Prompt Generated**
-
-**Research Prompt:**
-
-- Structured research prompt generated and saved
-
-Note: Running in standalone mode (no status file).
-
-**Next Steps:**
-
 Since no workflow is in progress:
 
 - Execute the research prompt with AI platform and gather findings
 - Refer to the BMM workflow guide if unsure what to do next
 - Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
   </output>
-  </check>
   </step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/research/instructions-market.md

@@ -554,60 +554,49 @@ Create compelling executive summary with:
 
 </step>
 
-<step n="14" goal="Update status file on completion">
+<step n="14" goal="Update status file on completion" tag="workflow-status">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
+<check if="standalone_mode != true">
-<action>Find the most recent file (by date in filename)</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-{{research_mode}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="status file exists">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Determine next agent from path file based on next workflow</action>
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: research</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated! Next: {{next_workflow}}</output>
-  </check>
 </check>
 
 <output>**✅ Research Complete ({{research_mode}} mode)**
 
 **Research Report:**
 
-- Research report generated and saved
+- Research report generated and saved to {output_folder}/bmm-research-{{research_mode}}-{{date}}.md
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: research ({{research_mode}}) ✓
+- Progress tracking updated: research marked complete
-- Progress: {{new_progress_percentage}}%
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Review findings with stakeholders, or run additional analysis workflows (product-brief, game-brief, etc.)
 
 Check status anytime with: `workflow-status`
-</output>
+{{else}}
-</check>
-
-<check if="status file not found">
-  <output>**✅ Research Complete ({{research_mode}} mode)**
-
-**Research Report:**
-
-- Research report generated and saved
-
-Note: Running in standalone mode (no status file).
-
-**Next Steps:**
-
 Since no workflow is in progress:
 
 - Review research findings
 - Refer to the BMM workflow guide if unsure what to do next
 - Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
   </output>
-  </check>
   </step>
 
 </workflow>

src/modules/bmm/workflows/1-analysis/research/instructions-router.md

@@ -10,27 +10,43 @@
 
 <critical>This is a ROUTER that directs to specialized research instruction sets</critical>
 
-<step n="1" goal="Validate workflow readiness">
+<step n="1" goal="Validate workflow readiness" tag="workflow-status">
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-  <param>mode: validate</param>
-  <param>calling_workflow: research</param>
-</invoke-workflow>
 
-<check if="status_exists == false">
+<check if="status file not found">
-  <output>{{suggestion}}</output>
+  <output>No workflow status file found. Research is optional - you can continue without status tracking.</output>
-  <output>Note: Research is optional. Continuing without progress tracking.</output>
   <action>Set standalone_mode = true</action>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for status updates in sub-workflows</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <action>Pass status_file_path to loaded instruction set</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "research" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+  <action>Pass status context to loaded instruction set for final update</action>
 
-  <check if="warning != ''">
+  <check if="research status is file path (already completed)">
-    <output>{{warning}}</output>
+    <output>⚠️ Research already completed: {{research status}}</output>
-    <output>Note: Research can provide valuable insights at any project stage.</output>
+    <ask>Re-running will create a new research report. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
     </check>
   </check>
+
+  <check if="research is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Research is out of sequence.</output>
+    <output>Note: Research can provide valuable insights at any project stage.</output>
+    <ask>Continue with Research anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
 </step>
 
 <step n="2" goal="Welcome and Research Type Selection">

src/modules/bmm/workflows/1-analysis/research/instructions-technical.md

@@ -442,60 +442,49 @@ Select option (1-5):</ask>
 
 </step>
 
-<step n="FINAL" goal="Update status file on completion">
+<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
+<check if="standalone_mode != true">
-<action>Find the most recent file (by date in filename)</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-technical-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="status file exists">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<action>Determine next agent from path file based on next workflow</action>
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: research</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated! Next: {{next_workflow}}</output>
-  </check>
 </check>
 
 <output>**✅ Technical Research Complete**
 
 **Research Report:**
 
-- Technical research report generated and saved
+- Technical research report generated and saved to {output_folder}/bmm-research-technical-{{date}}.md
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: research (technical) ✓
+- Progress tracking updated: research marked complete
-- Progress: {{new_progress_percentage}}%
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Review findings with architecture team, or run additional analysis workflows
 
 Check status anytime with: `workflow-status`
-</output>
+{{else}}
-</check>
-
-<check if="status file not found">
-  <output>**✅ Technical Research Complete**
-
-**Research Report:**
-
-- Technical research report generated and saved
-
-Note: Running in standalone mode (no status file).
-
-**Next Steps:**
-
 Since no workflow is in progress:
 
 - Review technical research findings
 - Refer to the BMM workflow guide if unsure what to do next
 - Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
   </output>
-  </check>
   </step>
 
 </workflow>

src/modules/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md

@@ -12,28 +12,42 @@
 
 <critical>DOCUMENT OUTPUT: Professional, specific, actionable UX design decisions WITH RATIONALE. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="status file not found">
-  <param>mode: data</param>
+  <output>No workflow status file found. Create UX Design can run standalone or as part of BMM planning workflow.</output>
-  <param>data_request: project_config</param>
+  <output>For standalone use, we'll gather requirements as we go. For integrated use, run `workflow-init` first for better context.</output>
-</invoke-workflow>
+  <action>Set standalone_mode = true</action>
-
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
-
-Create UX Design can run standalone or as part of the BMM planning workflow.
-
-For standalone use, we'll gather requirements as we go.
-For integrated use, run `workflow-init` first for better context.
-</output>
-<action>Set mode: standalone</action>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "create-design" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="create-design status is file path (already completed)">
+    <output>⚠️ UX Design already completed: {{create-design status}}</output>
+    <ask>Re-running will overwrite the existing UX design. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="create-design is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. UX Design is out of sequence.</output>
+    <ask>Continue with UX Design anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 <action>Store {{project_level}} for scoping decisions</action>
-  <action>Set mode: integrated</action>
 </check>
 </step>
 
@@ -1116,12 +1130,16 @@ Based on your deployment intent: {{recommendation}}
 
 <action>Save final document to {default_output_file}</action>
 
-  <check if="tracking_mode == true">
+  <check if="standalone_mode != true">
-    <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-      <param>mode: update</param>
+    <action>Find workflow_status key "create-design"</action>
-      <param>action: complete_workflow</param>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-      <param>workflow_name: create-ux-design</param>
+    <action>Update workflow_status["create-design"] = "{default_output_file}"</action>
-    </invoke-workflow>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+    <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+    <action>Determine next agent from path file based on next workflow</action>
+
   </check>
 
 <ask>🎨 **One more thing!** Want to see your design come to life?

src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md

@@ -67,21 +67,29 @@ Use: `prd`
 </check>
 </step>
 
-<step n="0.5" goal="Validate workflow sequencing">
+<step n="0.5" goal="Validate workflow sequencing" tag="workflow-status">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="standalone_mode != true">
-  <param>mode: validate</param>
+  <action>Check status of "gdd" workflow in loaded status file</action>
-  <param>calling_workflow: gdd</param>
-</invoke-workflow>
 
-<check if="warning != ''">
+  <check if="gdd status is file path (already completed)">
-  <output>{{warning}}</output>
+    <output>⚠️ GDD already completed: {{gdd status}}</output>
+    <ask>Re-running will overwrite the existing GDD. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="gdd is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. GDD is out of sequence.</output>
     <ask>Continue with GDD anyway? (y/n)</ask>
     <check if="n">
-    <output>{{suggestion}}</output>
+      <output>Exiting. Run {{next_workflow}} instead.</output>
       <action>Exit workflow</action>
     </check>
   </check>
+</check>
 </step>
 
 <step n="1" goal="Load context and determine game type">
@@ -328,18 +336,23 @@ For each {{placeholder}} in the fragment, elicit and capture that information.
 
 </step>
 
-<step n="15" goal="Update status and populate story sequence">
+<step n="15" goal="Update status and populate story sequence" tag="workflow-status">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="standalone_mode != true">
-  <param>mode: update</param>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <param>action: complete_workflow</param>
+  <action>Find workflow_status key "gdd"</action>
-  <param>workflow_name: gdd</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-  <param>populate_stories_from: {epics_output_file}</param>
+  <action>Update workflow_status["gdd"] = "{output_folder}/bmm-gdd-{{game_name}}-{{date}}.md"</action>
-</invoke-workflow>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="success == true">
+<action>Parse {epics_output_file} to extract all stories</action>
-  <output>Status updated! Next: {{next_workflow}} ({{next_agent}} agent)</output>
+<action>Populate story_sequence section in status file with story IDs</action>
-  <output>Loaded {{total_stories}} stories from epics.</output>
+<action>Set each story status to "not-started"</action>
+<output>Loaded {{total_stories}} stories from epics into story sequence.</output>
+
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+<output>Next workflow: {{next_workflow}} ({{next_agent}} agent)</output>
 </check>
 
 </step>

src/modules/bmm/workflows/2-plan-workflows/narrative/instructions-narrative.md

@@ -10,20 +10,40 @@
 <critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
 <critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</critical>
 
-<step n="0" goal="Check for workflow status">
+<step n="0" goal="Check for workflow status" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="status file not found">
-  <param>mode: init-check</param>
+  <output>No workflow status file found. Narrative workflow is optional - you can continue without status tracking.</output>
-</invoke-workflow>
+  <action>Set standalone_mode = true</action>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set tracking_mode = true</action>
 </check>
 
-<check if="status_exists == false">
+<check if="status file found">
-  <action>Set tracking_mode = false</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <output>Note: Running without workflow tracking. Run `workflow-init` to enable progress tracking.</output>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "narrative" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
+
+  <check if="narrative status is file path (already completed)">
+    <output>⚠️ Narrative Design Document already completed: {{narrative status}}</output>
+    <ask>Re-running will overwrite the existing narrative document. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+  <check if="narrative is not the next expected workflow (latter items are completed already in the list)">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Narrative is out of sequence.</output>
+    <ask>Continue with Narrative Design anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
 </check>
 </step>
 
@@ -539,19 +559,50 @@ Which would you like?</ask>
 
 </step>
 
-<step n="17" goal="Update status if tracking enabled">
+<step n="17" goal="Update status if tracking enabled" tag="workflow-status">
 
-<check if="tracking_mode == true">
+<check if="standalone_mode != true">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-    <param>mode: update</param>
+  <action>Find workflow_status key "narrative"</action>
-    <param>action: complete_workflow</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-    <param>workflow_name: narrative</param>
+  <action>Update workflow_status["narrative"] = "{output_folder}/bmm-narrative-{{game_name}}-{{date}}.md"</action>
-  </invoke-workflow>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-    <output>✅ Status updated! Next: {{next_workflow}}</output>
+<action>Determine next agent from path file based on next workflow</action>
-  </check>
 </check>
+
+<output>**✅ Narrative Design Complete, {user_name}!**
+
+**Narrative Document:**
+
+- Narrative design saved to {output_folder}/bmm-narrative-{{game_name}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: narrative marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review narrative with writing team or stakeholders
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review narrative design with team
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
   </step>
 
 </workflow>

src/modules/bmm/workflows/2-plan-workflows/prd/instructions.md

@@ -12,26 +12,12 @@
 
 <workflow>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="status file not found">
-  <param>mode: data</param>
+  <output>No workflow status file found. PRD workflow can run standalone or as part of BMM workflow path.</output>
-  <param>data_request: project_config</param>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-</invoke-workflow>
-
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
-
-The PRD workflow can run standalone or as part of the BMM workflow path.
-
-**Recommended:** Run `workflow-init` first for:
-
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
-
-**Or continue standalone** without progress tracking.
-</output>
   <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
   <check if="continue">
     <action>Set standalone_mode = true</action>
@@ -41,8 +27,12 @@ The PRD workflow can run standalone or as part of the BMM workflow path.
   </check>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "prd" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 2">
     <output>**Incorrect Workflow for Level {{project_level}}**
@@ -54,33 +44,26 @@ PRD is for Level 2-4 projects. Level 0-1 should use tech-spec directly.
 <action>Exit and redirect to tech-spec</action>
 </check>
 
-  <check if="project_type == game">
+  <check if="prd status is file path (already completed)">
-    <output>**Incorrect Workflow for Game Projects**
+    <output>⚠️ PRD already completed: {{prd status}}</output>
-
+    <ask>Re-running will overwrite the existing PRD. Continue? (y/n)</ask>
-Game projects should use GDD workflow instead of PRD.
-
-**Correct workflow:** `gdd` (PM agent)
-</output>
-<action>Exit and redirect to gdd</action>
-</check>
-</check>
-</step>
-
-<step n="0.5" goal="Validate workflow sequencing">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: validate</param>
-  <param>calling_workflow: prd</param>
-</invoke-workflow>
-
-<check if="warning != ''">
-  <output>{{warning}}</output>
-  <ask>Continue with PRD anyway? (y/n)</ask>
     <check if="n">
-    <output>{{suggestion}}</output>
+      <output>Exiting. Use workflow-status to see your next step.</output>
       <action>Exit workflow</action>
     </check>
   </check>
+
+  <check if="prd is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. PRD is out of sequence.</output>
+    <ask>Continue with PRD anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
 </step>
 
 <step n="1" goal="Initialize PRD context">
@@ -409,18 +392,17 @@ For each epic from the epic list, expand with full story details:
 
 </step>
 
-<step n="10" goal="Update status and complete">
+<step n="10" goal="Update status and complete" tag="workflow-status">
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="standalone_mode != true">
-  <param>mode: update</param>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <param>action: complete_workflow</param>
+  <action>Find workflow_status key "prd"</action>
-  <param>workflow_name: prd</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-  <param>populate_stories_from: {epics_output_file}</param>
+  <action>Update workflow_status["prd"] = "{default_output_file}"</action>
-</invoke-workflow>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="success == true">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-  <output>Status updated! Next: {{next_workflow}} ({{next_agent}} agent)</output>
+<action>Determine next agent from path file based on next workflow</action>
-  <output>Loaded {{total_stories}} stories from epics.</output>
 </check>
 
 <output>**✅ PRD Workflow Complete, {user_name}!**

src/modules/bmm/workflows/2-plan-workflows/tech-spec/instructions.md

@@ -13,26 +13,12 @@
 
 <critical>DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="status file not found">
-  <param>mode: data</param>
+  <output>No workflow status file found. Tech-spec workflow can run standalone or as part of BMM workflow path.</output>
-  <param>data_request: project_config</param>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-</invoke-workflow>
-
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
-
-The tech-spec workflow can run standalone or as part of the BMM workflow path.
-
-**Recommended:** Run `workflow-init` first for:
-
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
-
-**Or continue standalone** without progress tracking.
-</output>
   <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
   <check if="continue">
     <action>Set standalone_mode = true</action>
@@ -42,8 +28,12 @@ The tech-spec workflow can run standalone or as part of the BMM workflow path.
   </check>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "tech-spec" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level >= 2">
     <output>**Incorrect Workflow for Level {{project_level}}**
@@ -55,33 +45,26 @@ Tech-spec is for Level 0-1 projects. Level 2-4 should use PRD workflow.
 <action>Exit and redirect to prd</action>
 </check>
 
-  <check if="project_type == game">
+  <check if="tech-spec status is file path (already completed)">
-    <output>**Incorrect Workflow for Game Projects**
+    <output>⚠️ Tech-spec already completed: {{tech-spec status}}</output>
-
+    <ask>Re-running will overwrite the existing tech-spec. Continue? (y/n)</ask>
-Game projects should use GDD workflow instead of tech-spec.
-
-**Correct workflow:** `gdd` (PM agent)
-</output>
-<action>Exit and redirect to gdd</action>
-</check>
-</check>
-</step>
-
-<step n="0.5" goal="Validate workflow sequencing">
-
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-  <param>mode: validate</param>
-  <param>calling_workflow: tech-spec</param>
-</invoke-workflow>
-
-<check if="warning != ''">
-  <output>{{warning}}</output>
-  <ask>Continue with tech-spec anyway? (y/n)</ask>
     <check if="n">
-    <output>{{suggestion}}</output>
+      <output>Exiting. Use workflow-status to see your next step.</output>
       <action>Exit workflow</action>
     </check>
   </check>
+
+  <check if="tech-spec is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Tech-spec is out of sequence.</output>
+    <ask>Continue with tech-spec anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
 </step>
 
 <step n="1" goal="Confirm project scope and update tracking">
@@ -232,21 +215,22 @@ Run cohesion validation? (y/n)</ask>
 
 ## Next Steps
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="standalone_mode != true">
-  <param>mode: update</param>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <param>action: complete_workflow</param>
+  <action>Find workflow_status key "tech-spec"</action>
-  <param>workflow_name: tech-spec</param>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-</invoke-workflow>
+  <action>Update workflow_status["tech-spec"] = "{output_folder}/bmm-tech-spec-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="success == true">
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-  <output>Status updated!</output>
+<action>Determine next agent from path file based on next workflow</action>
 </check>
 
 <output>**✅ Tech-Spec Complete, {user_name}!**
 
 **Deliverables Created:**
-<check if="project_level == 0">
 
+<check if="project_level == 0">
 - ✅ tech-spec.md - Technical specification
 - ✅ user-story.md - Single user story
 </check>

src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

@@ -10,26 +10,12 @@
 <critical>Generate all documents in {document_output_language}</critical>
 <critical>This workflow replaces architecture with a conversation-driven approach</critical>
 
-<step n="0" goal="Validate workflow and extract project configuration">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+<check if="status file not found">
-  <param>mode: data</param>
+  <output>No workflow status file found. Decision Architecture can run standalone or as part of BMM workflow path.</output>
-  <param>data_request: project_config</param>
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-</invoke-workflow>
-
-<check if="status_exists == false">
-  <output>**Note: No Workflow Status File Found**
-
-The Decision Architecture workflow can run standalone or as part of the BMM workflow path.
-
-**Recommended:** Run `workflow-init` first for:
-
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
-
-**Or continue standalone** without progress tracking.
-</output>
   <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
   <check if="continue">
     <action>Set standalone_mode = true</action>
@@ -39,8 +25,12 @@ The Decision Architecture workflow can run standalone or as part of the BMM work
   </check>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "create-architecture" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
   <check if="project_level < 3">
     <output>**Note: Level {{project_level}} Project**
@@ -50,25 +40,28 @@ Decision Architecture is typically for Level 3-4 projects, but can be used for a
 For Level {{project_level}}, we'll keep the architecture appropriately scoped.
 </output>
 </check>
-</check>
-</step>
 
-<step n="0.5" goal="Validate workflow sequencing">
+  <check if="create-architecture status is file path (already completed)">
-
+    <output>⚠️ Architecture already completed: {{create-architecture status}}</output>
-<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+    <ask>Re-running will overwrite the existing architecture. Continue? (y/n)</ask>
-  <param>mode: validate</param>
-  <param>calling_workflow: architecture</param>
-</invoke-workflow>
-
-<check if="warning != ''">
-  <output>{{warning}}</output>
-  <ask>Continue with Decision Architecture anyway? (y/n)</ask>
     <check if="n">
-    <output>{{suggestion}}</output>
+      <output>Exiting. Use workflow-status to see your next step.</output>
       <action>Exit workflow</action>
     </check>
   </check>
 
+  <check if="create-architecture is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Architecture is out of sequence.</output>
+    <ask>Continue with Architecture anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
+
 <action>Check for existing PRD and epics files using fuzzy matching</action>
 
 <action>Fuzzy match PRD file: {prd_file}</action>
@@ -663,20 +656,20 @@ Enforcement: "All agents MUST follow this pattern"
 
 <action>Save document to {output_folder}/architecture.md</action>
 
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
+  <check if="standalone_mode != true">
-    <param>mode: update</param>
+    <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-    <param>action: complete_workflow</param>
+    <action>Find workflow_status key "create-architecture"</action>
-    <param>workflow_name: architecture</param>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-  </invoke-workflow>
+    <action>Update workflow_status["create-architecture"] = "{output_folder}/bmm-architecture-{{date}}.md"</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-  <check if="success == true">
+    <action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
-    <output>✅ Decision Architecture workflow complete!
+    <action>Determine next agent from path file based on next workflow</action>
-
-Status updated.
-</output>
 
   </check>
 
+<output>✅ Decision Architecture workflow complete!</output>
+
 <output>**Deliverables Created:**
 
 - ✅ architecture.md - Complete architectural decisions document

src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md

@@ -6,25 +6,12 @@
 
 <workflow>
 
-<step n="0" goal="Initialize and understand project context">
+<step n="0" goal="Validate workflow readiness" tag="workflow-status">
-<invoke-workflow path="{workflow_status_workflow}">
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
 
-<check if="status_exists == false">
+<check if="status file not found">
-  <output>**Note: No Workflow Status File Found**
+  <output>No workflow status file found. Implementation Ready Check can run standalone or as part of BMM workflow path.</output>
-
+  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-The Implementation Ready Check can run standalone or as part of the BMM workflow path.
-
-**Recommended:** Run `workflow-init` first for:
-
-- Project context tracking
-- Workflow sequencing guidance
-- Progress monitoring across workflows
-
-**Or continue standalone** without progress tracking.
-</output>
   <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
   <check if="continue">
     <action>Set standalone_mode = true</action>
@@ -34,19 +21,38 @@ The Implementation Ready Check can run standalone or as part of the BMM workflow
   </check>
 </check>
 
-<check if="status_exists == true">
+<check if="status file found">
-  <action>Store {{status_file_path}} for later updates</action>
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
-  <action>Store {{project_level}}, {{active_path}}, and {{workflow_phase}} for validation context</action>
+  <action>Parse workflow_status section</action>
+  <action>Check status of "solutioning-gate-check" workflow</action>
+  <action>Get project_level from YAML metadata</action>
+  <action>Find first non-completed workflow (next expected workflow)</action>
 
-<action>Based on the project_level, understand what artifacts should exist:
+<action>Based on the project_level, understand what artifacts should exist: - Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning) - Level 2: PRD, tech spec, epics/stories (no separate architecture doc) - Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
-
-- Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning)
-- Level 2: PRD, tech spec, epics/stories (no separate architecture doc)
-- Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
 </action>
 
-<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
+  <check if="solutioning-gate-check status is file path (already completed)">
+    <output>⚠️ Gate check already completed: {{solutioning-gate-check status}}</output>
+    <ask>Re-running will create a new validation report. Continue? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Use workflow-status to see your next step.</output>
+      <action>Exit workflow</action>
     </check>
+  </check>
+
+  <check if="solutioning-gate-check is not the next expected workflow">
+    <output>⚠️ Next expected workflow: {{next_workflow}}. Gate check is out of sequence.</output>
+    <ask>Continue with gate check anyway? (y/n)</ask>
+    <check if="n">
+      <output>Exiting. Run {{next_workflow}} instead.</output>
+      <action>Exit workflow</action>
+    </check>
+  </check>
+
+<action>Set standalone_mode = false</action>
+</check>
+
+<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
 
 <template-output>project_context</template-output>
 </step>
@@ -249,23 +255,48 @@ The Implementation Ready Check can run standalone or as part of the BMM workflow
 <template-output>readiness_assessment</template-output>
 </step>
 
-<step n="7" goal="Workflow status update offer" optional="true">
+<step n="7" goal="Update status and complete" tag="workflow-status">
-<ask>The readiness assessment is complete. Would you like to update the workflow status to proceed to the next phase? [yes/no]
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "solutioning-gate-check"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["solutioning-gate-check"] = "{output_folder}/bmm-readiness-assessment-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-Note: This will advance the project workflow to the next phase in your current path.</ask>
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+</check>
 
-<action if="user_response == 'yes'">
+<output>**✅ Implementation Ready Check Complete!**
-Determine the next workflow phase based on current status:
-- If Level 0-1: Advance to implementation phase
-- If Level 2-4 in solutioning: Advance to Phase 4 (Implementation)
-- Update the workflow status configuration accordingly
-- Confirm the update with the user
-</action>
 
-<action if="user_response == 'no'">
+**Assessment Report:**
-Acknowledge that the workflow status remains unchanged.
+
-Remind user they can manually update when ready.
+- Readiness assessment saved to: {output_folder}/bmm-readiness-assessment-{{date}}.md
-</action>
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: solutioning-gate-check marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- Review the assessment report and address any critical issues before proceeding
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
 
 <template-output>status_update_result</template-output>
 </step>

src/modules/bmm/workflows/4-implementation/create-story/README.md

@@ -1,129 +1,146 @@
----
-last-redoc-date: 2025-10-01
----
-
 # Create Story Workflow
 
-The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
+Just-in-time story generation creating one story at a time based on epic backlog state. Run by Scrum Master (SM) agent to ensure planned stories align with approved epics.
 
-This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
+## Table of Contents
 
-The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
+- [Usage](#usage)
+- [Key Features](#key-features)
+- [Inputs & Outputs](#inputs--outputs)
+- [Workflow Behavior](#workflow-behavior)
+- [Integration](#integration)
 
 ## Usage
 
 ```bash
-# SM initiates story creation for the next piece of work
+# SM initiates next story creation
 bmad sm *create-story
 ```
 
-The SM runs this workflow when:
+**When to run:**
 
-- The current sprint has capacity for new work
+- Sprint has capacity for new work
-- The previous story status is "Done" or "Approved"
+- Previous story is Done/Approved
-- The team is ready for the next planned story in the epic
+- Team ready for next planned story
-- Story preparation is needed before development
-
-## Inputs
-
-**Required Context Files:**
-
-- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
-- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
-- **PRD.md**: Product requirements document (fallback for requirements)
-- **Architecture Documents**: Automatically discovered from docs/ and output folders:
-  - tech-stack.md, unified-project-structure.md, coding-standards.md
-  - testing-strategy.md, backend-architecture.md, frontend-architecture.md
-  - data-models.md, database-schema.md, rest-api-spec.md, external-apis.md
-
-**Workflow Variables:**
-
-- `story_dir`: From config `dev_story_location` - where stories are saved
-- `epic_num`: Current epic number (auto-detected from existing stories)
-- `story_num`: Next story number (incremented from last completed story)
-- `auto_run_context`: Default true - runs story-context workflow after creation
-- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
-
-## Outputs
-
-**Primary Deliverable:**
-
-- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
-  - User story statement (role, action, benefit)
-  - Acceptance criteria extracted from tech spec or epics.md
-  - Tasks and subtasks mapped to ACs
-  - Testing requirements per testing strategy
-  - Dev notes with source citations
-  - Status: "Draft" (requires approval before development)
-
-**Validation Safeguards:**
-
-- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
-  ```
-  "No planned next story found in epics.md for epic {epic_num}.
-  Please load either PM or SM agent and run *correct-course to add/modify epic stories."
-  ```
-- **Status Check**: Won't create new story if current story isn't Done/Approved
-- **Document Grounding**: All requirements traced to source documents (no invention)
 
 ## Key Features
 
-**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
+### Strict Planning Enforcement
 
-**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
+- **Only creates stories enumerated in epics.md**
+- Halts if story not found in epic plan
+- Prevents scope creep through validation
 
-**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
+### Intelligent Document Discovery
 
-**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
+- Auto-finds tech spec: `tech-spec-epic-{N}-*.md`
+- Discovers architecture docs across directories
+- Builds prioritized requirement sources
 
-**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
+### Source Document Grounding
 
-## Integration with v6 Flow
+- Every requirement traced to source
+- No invention of domain facts
+- Citations included in output
 
-The create-story workflow is step 1 in the v6 implementation cycle:
+### Non-Interactive Mode
 
-1. **SM: create-story** ← You are here
+- Default "#yolo" mode minimizes prompts
-2. SM: story-context (adds JIT technical expertise)
+- Smooth automated story preparation
-3. DEV: dev-story (implements with generated context)
+- Only prompts when critical
-4. DEV/SR: code-review (validates completion)
-5. If needed: correct-course (adjusts direction)
-6. After epic: retrospective (captures learnings)
 
-This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
+## Inputs & Outputs
 
-## Document Priority Order
+### Required Files
 
-The workflow uses this priority for extracting requirements:
+| File                     | Purpose                       | Priority |
+| ------------------------ | ----------------------------- | -------- |
+| epics.md                 | Story enumeration (MANDATORY) | Critical |
+| tech-spec-epic-{N}-\*.md | Epic technical spec           | High     |
+| PRD.md                   | Product requirements          | Medium   |
+| Architecture docs        | Technical constraints         | Low      |
 
-1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
+### Auto-Discovered Docs
-2. **epics_file**: Acceptance criteria and story breakdown
+
-3. **prd_file**: Business requirements and constraints
+- `tech-stack.md`, `unified-project-structure.md`
-4. **Architecture docs**: Constraints, patterns, and technical guidance
+- `testing-strategy.md`, `backend/frontend-architecture.md`
+- `data-models.md`, `database-schema.md`, `api-specs.md`
+
+### Output
+
+**Story Document:** `{story_dir}/story-{epic}.{story}.md`
+
+- User story statement (role, action, benefit)
+- Acceptance criteria from tech spec/epics
+- Tasks mapped to ACs
+- Testing requirements
+- Dev notes with sources
+- Status: "Draft"
 
 ## Workflow Behavior
 
-**Story Number Management:**
+### Story Number Management
 
-- Automatically detects next story number from existing files
+- Auto-detects next story number
-- Won't skip numbers or create duplicates
+- No duplicates or skipped numbers
-- Maintains epic.story numbering convention
+- Maintains epic.story convention
 
-**Update vs Create:**
+### Update vs Create
 
-- If latest story status != Done/Approved: Updates existing story
+- **If current story not Done:** Updates existing
-- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
+- **If current story Done:** Creates next (if planned)
 
-**Epic Advancement:**
+### Validation Safeguards
 
-- In non-interactive mode: Stays within current epic
+**No Story Found:**
-- Interactive mode: Can prompt for new epic number
+
+```
+"No planned next story found in epics.md for epic {N}.
+Run *correct-course to add/modify epic stories."
+```
+
+**Missing Config:**
+Ensure `dev_story_location` set in config.yaml
+
+## Integration
+
+### v6 Implementation Cycle
+
+1. **create-story** ← Current step (defines "what")
+2. story-context (adds technical "how")
+3. dev-story (implementation)
+4. code-review (validation)
+5. correct-course (if needed)
+6. retrospective (after epic)
+
+### Document Priority
+
+1. **tech_spec_file** - Epic-specific spec
+2. **epics_file** - Story breakdown
+3. **prd_file** - Business requirements
+4. **architecture_docs** - Technical guidance
+
+## Configuration
+
+```yaml
+# bmad/bmm/config.yaml
+dev_story_location: ./stories
+output_folder: ./output
+
+# workflow.yaml defaults
+non_interactive: true
+auto_run_context: true
+```
 
 ## Troubleshooting
 
-**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
+| Issue                   | Solution                                   |
+| ----------------------- | ------------------------------------------ |
+| "No planned next story" | Run `*correct-course` to add story to epic |
+| Missing story_dir       | Set `dev_story_location` in config         |
+| Tech spec not found     | Use naming: `tech-spec-epic-{N}-*.md`      |
+| No architecture docs    | Add docs to docs/ or output/ folder        |
 
-**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
+---
 
-**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
+For workflow details, see [instructions.md](./instructions.md) and [checklist.md](./checklist.md).
-
-**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.

src/modules/bmm/workflows/4-implementation/create-story/instructions.md

@@ -234,6 +234,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
     <output>**✅ Story Created Successfully, {user_name}!**
 
 **Story Details:**
+
 - Story ID: {{story_id}}
 - Story Key: {{story_key}}
 - File: {{story_file}}
@@ -242,6 +243,7 @@ You may need to run sprint-planning to refresh tracking, or manually set the sto
 **⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
 
 **Next Steps:**
+
 1. Review the drafted story in {{story_file}}
 2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
 3. Or run `story-ready` to manually mark the story ready without generating technical context

src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -178,12 +178,14 @@ You may need to run sprint-planning to refresh tracking.
     <output>✅ Story context generated successfully, {user_name}!
 
 **Story Details:**
+
 - Story: {{epic_id}}.{{story_id}} - {{story_title}}
 - Story Key: {{story_key}}
 - Context File: {default_output_file}
 - Status: drafted → ready-for-dev
 
 **Context Includes:**
+
 - Documentation artifacts and references
 - Existing code and interfaces
 - Dependencies and frameworks
@@ -191,6 +193,7 @@ You may need to run sprint-planning to refresh tracking.
 - Development constraints
 
 **Next Steps:**
+
 1. Review the context file: {default_output_file}
 2. Run `dev-story` to implement the story
 3. Generate context for more drafted stories if needed

src/modules/bmm/workflows/README.md

@@ -1,577 +1,215 @@
----
+# BMM Workflows - Complete v6 Guide
-last-redoc-date: 2025-10-12
----
 
-# BMM Workflows - The Complete v6 Flow
+Master guide for BMM's four-phase methodology that adapts to project scale (Level 0-4) and context (greenfield/brownfield).
 
-The BMM (BMAD Method Module) orchestrates software development through four distinct phases, each with specialized workflows that adapt to project scale (Level 0-4) and context (greenfield vs brownfield). This document serves as the master guide for understanding how these workflows interconnect to deliver the revolutionary v6 methodology.
+## Table of Contents
 
-## Core v6 Innovations
+- [Core Innovations](#core-innovations)
+- [Universal Entry Point](#universal-entry-point)
+- [Four Phases Overview](#four-phases-overview)
+- [Phase Details](#phase-details)
+  - [Documentation Prerequisite](#documentation-prerequisite)
+  - [Phase 1: Analysis](#phase-1-analysis)
+  - [Phase 2: Planning](#phase-2-planning)
+  - [Phase 3: Solutioning](#phase-3-solutioning)
+  - [Phase 4: Implementation](#phase-4-implementation)
+- [Scale Levels](#scale-levels)
+- [Greenfield vs Brownfield](#greenfield-vs-brownfield)
+- [Critical Rules](#critical-rules)
 
-**Scale-Adaptive Planning**: Projects automatically route through different workflows based on complexity (Level 0-4), ensuring appropriate documentation and process overhead.
+## Core Innovations
 
-**Just-In-Time Design**: Technical specifications are created one epic at a time during implementation, not all upfront, incorporating learnings as the project evolves.
+- **Scale-Adaptive Planning** - Automatic routing based on complexity (Level 0-4)
+- **Just-In-Time Design** - Tech specs created per epic during implementation
+- **Dynamic Expertise Injection** - Story-specific technical guidance
+- **Continuous Learning Loop** - Retrospectives improve each cycle
 
-**Dynamic Expertise Injection**: Story-context workflows provide targeted technical guidance per story, replacing static documentation with contextual expertise.
+## Universal Entry Point
 
-**Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last.
+**Always start with `workflow-status` or `workflow-init`**
 
-## The Four Phases (Plus Documentation Prerequisite)
+### workflow-status
+
+- Checks for existing workflow status file
+- Displays current phase and progress
+- Routes to appropriate next workflow
+- Shows Phase 4 implementation state
+
+### workflow-init
+
+- Creates initial bmm-workflow-status.md
+- Detects greenfield vs brownfield
+- Routes undocumented brownfield to document-project
+- Sets up workflow tracking
+
+## Four Phases Overview
 
 ```
-┌──────────────────────────────────────────────────────────────┐
+PREREQUISITE: document-project (brownfield without docs)
-│       PREREQUISITE: PROJECT DOCUMENTATION (Conditional)      │
-│        For brownfield projects without adequate docs         │
-│                     OR post-completion cleanup               │
-├──────────────────────────────────────────────────────────────┤
-│  document-project ──→ Comprehensive project documentation    │
-└────────────────────────────────────────────────────────┼─────┘
                     ↓
-┌──────────────────────────────────────────────────────────────┐
+PHASE 1: Analysis (optional)
-│                    PHASE 1: ANALYSIS                         │
+    brainstorm → research → brief
-│                      (Optional)                              │
-├──────────────────────────────────────────────────────────────┤
-│  brainstorm-game  ──┐                                        │
-│  brainstorm-project ├──→ research ──→ product-brief  ──┐     │
-│  game-brief ────────┘                          game-brief    │
-└────────────────────────────────────────────────────────┼─────┘
                     ↓
-┌──────────────────────────────────────────────────────────────┐
+PHASE 2: Planning (required, scale-adaptive)
-│                    PHASE 2: PLANNING                         │
+    Level 0-1: tech-spec only
-│              (Scale-Adaptive Router - by type)               │
+    Level 2-4: PRD + epics
-├──────────────────────────────────────────────────────────────┤
-│  SOFTWARE: prd/tech-spec    GAMES: gdd/narrative             │
-│      ├──→ Level 0: tech-spec only      ├──→ GDD (all levels) │
-│      ├──→ Level 1: tech-spec only      └──→ Narrative (opt)  │
-│      ├──→ Level 2: PRD + Epics ──────────────────────────┐   │
-│      └──→ Level 3-4: PRD + Epics ────────────────────────┼┐  │
-│  UX: create-ux-design (conditional)                      ││  │
-└──────────────────────────────────────────────────────────┼┼──┘
-                                                           ↓↓
-┌──────────────────────────────────────────────────────────────┐
-│                   PHASE 3: SOLUTIONING                       │
-│           (Software Levels 2-4 / Complex Games)              │
-├──────────────────────────────────────────────────────────────┤
-│  create-architecture ──→ architecture.md                     │
-│  validate-architecture (optional)                            │
-│  solutioning-gate-check (recommended/required)               │
-└────────────────────────────────────────────────────────────┬─┘
                     ↓
-┌──────────────────────────────────────────────────────────────┐
+PHASE 3: Solutioning (Level 2-4 only)
-│                  PHASE 4: IMPLEMENTATION                     │
+    architecture → validation → gate-check
-│                    (Sprint-Based Cycle)                      │
+                    ↓
-├──────────────────────────────────────────────────────────────┤
+PHASE 4: Implementation (iterative)
-│  sprint-planning ──→ sprint-status.yaml                      │
+    sprint-planning → epic-context → story cycle
-│       ↓                                                      │
-│  ┌─→ epic-tech-context (per epic)                            │
-│  │   ↓                                                       │
-│  │   create-story ──→ story-context ──→ dev-story ─┐         │
-│  │                                                 ↓         │
-│  │   retrospective ←── [epic done] ←─── code-review         │
-│  │                                                 ↓         │
-│  └──────────── correct-course ←──[if issues]───────┘         │
-└──────────────────────────────────────────────────────────────┘
 ```
 
-## Universal Entry Point: workflow-status
+## Phase Details
 
-**Before starting any workflow, check your status!**
+### Documentation Prerequisite
 
-The `workflow-status` workflow is the **universal entry point** for all BMM workflows, if you have not already set up your workflow, run `workflow-init`, but even if you just run the workflow-status and the file does not exist you should still be directed to run workflow-init.
+**When:** Brownfield projects without documentation OR post-completion cleanup
 
-**What it does:**
+| Workflow         | Purpose                       | Output             |
+| ---------------- | ----------------------------- | ------------------ |
+| document-project | Analyze and document codebase | Comprehensive docs |
 
-- ✅ Checks for existing workflow status file
+**Use Cases:**
-- ✅ Displays current phase, progress, and next action
-- ✅ Helps new users plan their workflow approach
-- ✅ Guides brownfield projects to documentation first
-- ✅ Routes to appropriate workflows based on context
 
-**No status file?** It will:
+1. **Pre-Phase 1**: Understand existing brownfield code
+2. **Post-Phase 4**: Create clean documentation replacing scattered artifacts
 
-1. Ask about project context (greenfield vs brownfield)
+### Phase 1: Analysis
-2. Generate your bmm-workflow-status.md file.
 
-**Status file exists?** It will:
+**Optional workflows for discovery and requirements gathering**
 
-1. Display current phase and progress
+| Workflow           | Agent         | Purpose               | Output                 |
-2. Show Phase 4 implementation state (BACKLOG/TODO/IN PROGRESS/DONE)
+| ------------------ | ------------- | --------------------- | ---------------------- |
-3. Recommend exact next action
+| brainstorm-project | Analyst       | Software ideation     | Architecture proposals |
-4. Offer to change workflow or display menu
+| brainstorm-game    | Game Designer | Game concept ideation | Concept proposals      |
+| research           | Analyst       | Multi-mode research   | Research artifacts     |
+| product-brief      | Analyst       | Strategic planning    | Product brief          |
+| game-brief         | Game Designer | Game foundation       | Game brief             |
 
-**All phase 1-3 workflows should check workflow-status on start of the workflow.**
+### Phase 2: Planning
 
----
+**Required phase with scale-adaptive routing**
 
-## Documentation Prerequisite (Brownfield Projects)
+| Workflow         | Agent         | Output         | Levels      |
+| ---------------- | ------------- | -------------- | ----------- |
+| prd              | PM            | PRD.md + epics | 2-4         |
+| tech-spec        | PM            | tech-spec.md   | 0-1         |
+| gdd              | Game Designer | GDD.md         | Games       |
+| create-ux-design | UX            | ux-design.md   | Conditional |
 
-**NOT a numbered phase** - this is a prerequisite workflow for brownfield projects without adequate documentation, OR a post-completion tool for creating clean source-of-truth documentation after Phases 1-4 are complete.
+### Phase 3: Solutioning
 
-### Purpose
+**Architecture phase for Level 2-4 projects**
 
-The `document-project` workflow serves TWO critical purposes:
+| Workflow               | Agent     | Purpose           | Output                 |
+| ---------------------- | --------- | ----------------- | ---------------------- |
+| create-architecture    | Architect | System design     | architecture.md + ADRs |
+| validate-architecture  | Architect | Design validation | Validation report      |
+| solutioning-gate-check | Architect | PRD/UX/arch check | Gate report            |
 
-1. **Pre-Phase 1 Prerequisite (Brownfield)**: Run BEFORE planning to understand existing codebases
+### Phase 4: Implementation
-2. **Post-Phase 4 Documentation (Any Project)**: Run AFTER completion to create superior documentation that replaces scattered PRD/architecture/story artifacts
 
-### Workflows
+**Sprint-based development cycle**
 
-| Workflow             | Agent   | Purpose                             | Output                              | When to Use                                                    |
+#### Sprint Status System
-| -------------------- | ------- | ----------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
-| **document-project** | Analyst | Analyze and document entire project | Comprehensive project documentation | Brownfield without docs OR post-completion cleanup (any scale) |
 
-### Use Cases
+**Epic Flow:** `backlog → contexted`
 
-**Use Case 1: Brownfield Prerequisite**
+**Story Flow:** `backlog → drafted → ready-for-dev → in-progress → review → done`
 
-```
+#### Implementation Workflows
-workflow-init detects undocumented brownfield
-    ↓
-document-project (generates index.md, architecture.md, etc.)
-    ↓
-Phase 1 (optional) → Phase 2 (planning with full context)
-```
-
-**Use Case 2: Post-Completion Documentation**
-
-```
-Phase 4 Implementation Complete
-    ↓
-document-project (scans final codebase)
-    ↓
-Produces clean, LLM-optimized docs > scattered phase artifacts
-```
-
-**Why it's superior**: Creates comprehensive, consistent documentation that both humans and LLMs can use to understand projects of any size or complexity - often better than manually-maintained PRDs, architecture docs, and story files.
-
----
-
-## Phase 1: Analysis (Optional)
-
-Optional workflows for project discovery and requirements gathering. Output feeds into Phase 2 planning.
-
-### Workflows
-
-| Workflow               | Agent         | Purpose                                     | Output                    | When to Use           |
-| ---------------------- | ------------- | ------------------------------------------- | ------------------------- | --------------------- |
-| **workflow-status**    | Analyst       | Universal entry point and status checker    | Status display + guidance | **Start here!**       |
-| **workflow-init**      | Analyst       | Generate an initial workflow status file    | Status display + guidance | **OR start here!**    |
-| **brainstorm-game**    | Game Designer | Game concept ideation using 5 methodologies | Concept proposals         | New game projects     |
-| **brainstorm-project** | Analyst       | Software solution exploration               | Architecture proposals    | New software projects |
-| **game-brief**         | Game Designer | Structured game design foundation           | Game brief document       | Before GDD creation   |
-| **product-brief**      | Analyst       | Strategic product planning culmination      | Product brief             | End of analysis phase |
-| **research**           | Analyst       | Multi-mode research (market/technical/deep) | Research artifacts        | When evidence needed  |
-
-### Flow
-
-```
-workflow-status (check) → Brainstorming → Research → Brief → Planning (Phase 2)
-```
-
-## Phase 2: Planning (Required)
-
-### Scale Levels
-
-| Level | Scope                    | Outputs                        | Next Phase                     |
-| ----- | ------------------------ | ------------------------------ | ------------------------------ |
-| **0** | Single atomic change     | tech-spec + 1 story            | → Implementation               |
-| **1** | 1-10 stories, 1 epic     | tech-spec + epic + 2-3 stories | → Implementation               |
-| **2** | 5-15 stories, 1-2 epics  | PRD + epics                    | → Solutioning → Implementation |
-| **3** | 12-40 stories, 2-5 epics | PRD + epics                    | → Solutioning → Implementation |
-| **4** | 40+ stories, 5+ epics    | PRD + epics                    | → Solutioning → Implementation |
-
-### Available Workflows
-
-| Workflow             | Agent       | Purpose                              | Output         | Levels      |
-| -------------------- | ----------- | ------------------------------------ | -------------- | ----------- |
-| **prd**              | PM          | Product Requirements Document        | PRD.md + epics | 2-4         |
-| **tech-spec**        | PM          | Technical specification              | tech-spec.md   | 0-1         |
-| **gdd**              | PM          | Game Design Document                 | GDD.md         | Games (all) |
-| **narrative**        | PM          | Game narrative design                | narrative.md   | Games (opt) |
-| **create-ux-design** | UX Designer | User experience and interface design | ux-design.md   | Conditional |
-
-### Key Outputs
-
-- **PRD.md**: Product Requirements Document (Levels 2-4)
-- **Epics.md**: Epic breakdown with stories (Levels 2-4)
-- **tech-spec.md**: Technical specification (Levels 0-1)
-- **story-{slug}.md**: Single user story (Level 0)
-- **story-{slug}-1.md, story-{slug}-2.md, story-{slug}-3.md**: User stories (Level 1)
-- **GDD.md**: Game Design Document (game projects)
-- **narrative.md**: Narrative design (game projects, optional)
-- **ux-design.md**: UX specification (conditional, UI-heavy projects)
-- **bmm-workflow-status.md**: Versioned workflow state tracking
-
-## Phase 3: Solutioning (Levels 2-4)
-
-Architecture and technical design phase for medium to complex projects.
-
-### Workflows
-
-| Workflow                   | Agent     | Purpose                          | Output                    | When        |
-| -------------------------- | --------- | -------------------------------- | ------------------------- | ----------- |
-| **create-architecture**    | Architect | Create system-wide architecture  | architecture.md with ADRs | Levels 2-4  |
-| **validate-architecture**  | Architect | Validate architecture design     | Validation report         | Optional    |
-| **solutioning-gate-check** | Architect | Validate PRD + UX + architecture | Gate check report         | Recommended |
-
-### Architecture Scope by Level
-
-- **Level 2**: Lightweight architecture document focusing on key technical decisions
-- **Level 3-4**: Comprehensive architecture with detailed ADRs, system diagrams, integration patterns
-
-## Phase 4: Implementation (Iterative)
-
-The core development cycle that transforms requirements into working software through sprint-based iteration.
-
-### Sprint Planning - The Phase 4 Entry Point
-
-Phase 4 begins with the **sprint-planning** workflow, which generates a `sprint-status.yaml` file that serves as the single source of truth for all implementation tracking.
-
-**What sprint-planning does:**
-
-1. Extracts all epics and stories from epic files
-2. Creates ordered status tracking for every work item
-3. Auto-detects existing story files and contexts
-4. Maintains status through the development lifecycle
-
-### The Sprint Status System
-
-Phase 4 uses a 6-state lifecycle tracked in `sprint-status.yaml`:
-
-**Epic Status Flow:**
-
-```
-backlog → contexted
-```
-
-**Story Status Flow:**
-
-```
-backlog → drafted → ready-for-dev → in-progress → review → done
-```
-
-**Retrospective Status:**
-
-```
-optional ↔ completed
-```
-
-#### Status Definitions
-
-**Epic Statuses:**
-
-- **backlog**: Epic exists in epic file but not yet contexted
-- **contexted**: Epic technical context created (prerequisite for drafting stories)
-
-**Story Statuses:**
-
-- **backlog**: Story only exists in epic file, not yet drafted
-- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
-- **ready-for-dev**: Draft approved + story context created
-- **in-progress**: Developer actively working on implementation
-- **review**: Under SM review (via code-review workflow)
-- **done**: Story completed and deployed
-
-**Retrospective Statuses:**
-
-- **optional**: Can be done but not required
-- **completed**: Retrospective has been completed
-
-### The Implementation Loop
-
-```
-Phase Transition (Phase 2 or 3 → Phase 4)
-  ↓
-┌─────────────────────────────────────────────────┐
-│  SM: sprint-planning                             │
-│  Creates: sprint-status.yaml with all epics/    │
-│           stories set to 'backlog'               │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  SM: epic-tech-context (for current epic)       │
-│  Creates: epic-N-context.md                      │
-│  Updates: Epic status to 'contexted'             │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  SM: create-story (drafts next backlog story)   │
-│  Creates: story-{key}.md                         │
-│  Updates: Story status to 'drafted'              │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  SM: story-context (creates implementation ctx)  │
-│  Creates: story-{key}-context.md                 │
-│  Updates: Story status to 'ready-for-dev'        │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  DEV: dev-story (implements story)               │
-│  Reads: story + context files                    │
-│  Updates: Story status to 'in-progress'          │
-│           then to 'review' when complete         │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  DEV: code-review (validates implementation)     │
-│  Reviews: Code changes against DoD               │
-│  Feedback: Iteration or approval                 │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-┌─────────────────────────────────────────────────┐
-│  DEV/SM: Updates story status to 'done'          │
-│  Manual update to sprint-status.yaml             │
-└───────────────────┬─────────────────────────────┘
-                    ↓
-            ┌───────┴────────┐
-            │  More stories?  │
-            └───────┬─────────┘
-                ┌───┴───┐
-                ↓       ↓
-          [Yes: Loop]  [No: Epic Complete]
-                         ↓
-                   ┌─────────────────┐
-                   │  SM: retrospective│
-                   │  Updates: epic-N- │
-                   │  retrospective to │
-                   │  'completed'      │
-                   └─────────────────┘
-```
-
-### Workflow Responsibilities
 
 | Workflow          | Agent | Purpose                 | Status Updates                              |
-| --------------------- | ----- | -------------------------------------- | ------------------------------------------- |
+| ----------------- | ----- | ----------------------- | ------------------------------------------- |
-| **sprint-planning**   | SM    | Initialize sprint status tracking      | Creates sprint-status.yaml                  |
+| sprint-planning   | SM    | Initialize tracking     | Creates sprint-status.yaml                  |
-| **epic-tech-context** | SM    | Create epic-specific technical context | Epic: backlog → contexted                   |
+| epic-tech-context | SM    | Epic technical context  | Epic: backlog → contexted                   |
-| **create-story**      | SM    | Draft individual story files           | Story: backlog → drafted                    |
+| create-story      | SM    | Draft story files       | Story: backlog → drafted                    |
-| **story-context**     | SM    | Generate implementation context/XML    | Story: drafted → ready-for-dev              |
+| story-context     | SM    | Implementation guidance | Story: drafted → ready-for-dev              |
-| **dev-story**         | DEV   | Implement story                        | Story: ready-for-dev → in-progress → review |
+| dev-story         | DEV   | Implement               | Story: ready-for-dev → in-progress → review |
-| **code-review**       | SM/SR | Quality validation and feedback        | (No automatic state change)                 |
+| code-review       | DEV   | Quality validation      | No auto update                              |
-| **retrospective**     | SM    | Capture epic learnings                 | Retrospective: optional → completed         |
+| retrospective     | SM    | Capture learnings       | Retrospective: optional → completed         |
-| **correct-course**    | SM    | Handle issues/scope changes            | (Adaptive based on situation)               |
+| correct-course    | SM    | Handle issues           | Adaptive                                    |
 
-### Key Guidelines
+#### Implementation Loop
-
-1. **Epic Context First**: Epics should be `contexted` before their stories can be `drafted`
-2. **Sequential by Default**: Stories are typically worked in order within an epic
-3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
-4. **Learning Transfer**: SM drafts next story after previous is `done` to incorporate learnings
-5. **Flexible Status Updates**: Agents and users can manually update sprint-status.yaml as needed
-
-## Greenfield vs Brownfield Paths
-
-### Greenfield Projects (New Code)
-
-**Path:** Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
-
-- **Level 0-1**: Skip Phase 3, go straight to implementation with tech-spec
-- **Level 2-4**: Full solutioning with architecture before implementation
-- Clean slate for architectural decisions
-- No existing patterns to constrain design
-
-### Brownfield Projects (Existing Code)
-
-**Path:** Documentation Prerequisite (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
-
-**Documentation Prerequisite (Conditional):**
 
 ```
-workflow-status/workflow-init
+sprint-planning (creates sprint-status.yaml)
-    ├─→ Check: Is existing codebase documented?
+    ↓
-    │   ├─→ YES: Proceed to Phase 1 or 2
+For each epic:
-    │   └─→ NO: REQUIRED - Run document-project workflow first
+    epic-tech-context
-    │       ├─→ Analyzes existing code
+        ↓
-    │       ├─→ Documents current architecture
+    For each story:
-    │       ├─→ Identifies technical debt
+        create-story → story-context → dev-story → code-review
-    │       ├─→ Creates comprehensive baseline documentation
+            ↓
-    │       └─→ Produces superior docs for LLM + human understanding
+        Mark done in sprint-status.yaml
-    └─→ Continue with scale-adaptive planning (Phases 1-4)
+    ↓
+    retrospective (epic complete)
 ```
 
-**Critical for Brownfield**:
+## Scale Levels
 
-- Must understand existing patterns before planning
+| Level | Scope         | Documentation         | Path            |
-- Integration points need documentation
+| ----- | ------------- | --------------------- | --------------- |
-- Technical debt must be visible in planning
+| 0     | Single change | tech-spec only        | Phase 2 → 4     |
-- Constraints from existing system affect scale decisions
+| 1     | 1-10 stories  | tech-spec only        | Phase 2 → 4     |
+| 2     | 5-15 stories  | PRD + architecture    | Phase 2 → 3 → 4 |
+| 3     | 12-40 stories | PRD + full arch       | Phase 2 → 3 → 4 |
+| 4     | 40+ stories   | PRD + enterprise arch | Phase 2 → 3 → 4 |
 
-**Post-Completion Option**: After Phase 4 completes, run `document-project` again to create clean source-of-truth documentation that supersedes scattered phase artifacts.
+## Greenfield vs Brownfield
 
-## Agent Participation by Phase
+### Greenfield (New Projects)
 
-| Phase/Step                         | Primary Agents         | Supporting Agents    | Key Workflows                               |
+```
-| ---------------------------------- | ---------------------- | -------------------- | ------------------------------------------- |
+Phase 1 (optional) → Phase 2 → Phase 3 (L2-4) → Phase 4
-| **Prerequisite: Documentation**    | Analyst                | -                    | document-project (conditional)              |
-| **Phase 1: Analysis**              | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
-| **Phase 2: Planning**              | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
-| **Phase 3: Solutioning**           | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
-| **Phase 4: Implementation**        | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
-| **Post-Completion: Documentation** | Analyst                | -                    | document-project (optional cleanup)         |
-
-## Key Files and Artifacts
-
-### Tracking Documents
-
-- **bmm-workflow-status.md**: Phase and workflow tracking (updated by workflow-status)
-  - Current phase and progress
-  - Workflow history
-  - Next recommended actions
-  - Project metadata and configuration
-
-- **sprint-status.yaml**: Implementation tracking (Phase 4 only)
-  - All epics, stories, and retrospectives
-  - Current status for each item (backlog → done)
-  - Single source of truth for Phase 4 progression
-  - Updated by agents as work progresses
-
-- **Epics.md**: Master epic/story definitions (source of truth for planning, Level 2-4)
-
-### Phase Outputs
-
-- **Documentation Prerequisite (if run)**:
-  - Comprehensive project documentation (index.md, architecture.md, source-tree-analysis.md, component-inventory.md, etc.)
-  - Superior to manually-maintained docs for LLM understanding
-
-- **Phase 1**:
-  - Product briefs, game briefs, research documents
-
-- **Phase 2**:
-  - Level 0: tech-spec.md + story-{slug}.md
-  - Level 1: tech-spec.md + epic breakdown + story-{slug}-N.md files
-  - Level 2-4: PRD.md + epics.md (+ optional ux-design.md, narrative.md)
-
-- **Phase 3**:
-  - architecture.md (with ADRs)
-  - Validation reports
-  - Gate check documentation
-
-- **Phase 4**:
-  - sprint-status.yaml (tracking file)
-  - epic-N-context.md files (per epic)
-  - story-{key}.md files (per story)
-  - story-{key}-context.md files (per story)
-  - Implemented code and tests
-
-## Best Practices
-
-### 1. Respect the Scale
-
-- Don't create PRDs for Level 0-1 changes (use tech-spec only)
-- Don't skip architecture for Level 2-4 projects
-- Let the workflow paths determine appropriate artifacts
-- Level 2 still requires Phase 3 solutioning (lighter than 3-4)
-
-### 2. Use Sprint Planning Effectively
-
-- Run sprint-planning at the start of Phase 4
-- Context epics before drafting their stories (epic-tech-context)
-- Update sprint-status.yaml as work progresses
-- Re-run sprint-planning to auto-detect new files/contexts
-
-### 3. Maintain Flow Integrity
-
-- Stories must be defined in Epics.md before sprint-planning
-- Complete epic context before story drafting
-- Create story context before implementation
-- Each phase completes before the next begins
-
-### 4. Document Brownfield First (Prerequisite)
-
-- Never plan without understanding existing code
-- Run document-project if codebase is undocumented (PREREQUISITE, not Phase 0)
-- Technical debt must be visible in planning
-- Integration points need documentation
-- Can also run post-Phase 4 for superior final documentation
-
-### 5. Learn Continuously
-
-- Run retrospectives after each epic
-- Incorporate learnings into next story drafts
-- Update workflows based on team feedback
-- Share patterns across teams
-
-## Common Pitfalls and Solutions
-
-| Pitfall                               | Solution                                              |
-| ------------------------------------- | ----------------------------------------------------- |
-| Skipping sprint-planning              | Always run at Phase 4 start - it creates status file  |
-| Creating stories without epic context | Run epic-tech-context before create-story             |
-| Skipping story-context generation     | Always run after create-story for better dev guidance |
-| Not updating sprint-status.yaml       | Update statuses as work progresses                    |
-| Thinking Level 2 skips Phase 3        | Level 2 DOES require architecture (just lighter)      |
-| Planning brownfield without docs      | Run document-project first if undocumented            |
-| Not running retrospectives            | Complete after every epic for learning transfer       |
-| Manually tracking stories elsewhere   | Use sprint-status.yaml as single source of truth      |
-
-## Quick Reference Commands
-
-```bash
-# Universal Entry Point (Start Here!)
-bmad analyst workflow-status  # Check status and get recommendations
-
-# Documentation Prerequisite (Brownfield without docs OR post-completion cleanup)
-bmad analyst document-project
-
-# Phase 1: Analysis (Optional)
-bmad analyst brainstorm-project    # Software ideation
-bmad game-designer brainstorm-game # Game ideation
-bmad analyst research              # Market/technical research
-bmad analyst product-brief         # Software brief
-bmad game-designer game-brief      # Game brief
-
-# Phase 2: Planning (Required)
-bmad pm prd                  # Level 2-4 software projects
-bmad pm tech-spec            # Level 0-1 software projects
-bmad pm gdd                  # Game projects (all levels)
-bmad pm narrative            # Game narrative (optional)
-bmad ux-designer create-ux-design  # UI-heavy projects
-
-# Phase 3: Solutioning (Levels 2-4)
-bmad architect create-architecture    # System architecture
-bmad architect validate-architecture  # Validation (optional)
-bmad architect solutioning-gate-check # Gate check
-
-# Phase 4: Implementation (Sprint-Based)
-bmad sm sprint-planning      # FIRST: Initialize sprint tracking
-bmad sm epic-tech-context    # Create epic context (per epic)
-bmad sm create-story         # Draft story file
-bmad sm story-context        # Create story context
-bmad dev dev-story           # Implement story
-bmad sm code-review         # Quality validation
-# (Update sprint-status.yaml to 'done' manually or via workflow)
-bmad sm retrospective        # After epic complete
-bmad sm correct-course       # If issues arise
 ```
 
-## Future Enhancements
+- Clean slate for design
+- No existing constraints
+- Direct to planning
 
-### Coming Soon
+### Brownfield (Existing Code)
 
-- **Automated status updates**: Workflows automatically update sprint-status.yaml
+```
-- **Workflow orchestration**: Automatic phase transitions and validation
+document-project (if needed) → Phase 1 (optional) → Phase 2 → Phase 3 (L2-4) → Phase 4
-- **Progress dashboards**: Real-time workflow status visualization
+```
-- **Team synchronization**: Multi-developer story coordination
 
-### Under Consideration
+- Must understand existing patterns
+- Documentation prerequisite if undocumented
+- Consider technical debt in planning
 
-- AI-assisted retrospectives with pattern detection
+## Critical Rules
-- Automated story sizing based on historical data
+
-- Predictive epic planning with risk assessment
+### Phase Transitions
-- Cross-project learning transfer
+
-- Enhanced brownfield analysis with architectural debt scoring
+1. **Check workflow-status** before any Phase 1-3 workflow
+2. **Document brownfield** before planning if undocumented
+3. **Complete planning** before solutioning
+4. **Complete architecture** (L2-4) before implementation
+
+### Implementation Rules
+
+1. **Epic context first** - Must context epic before drafting stories
+2. **Sequential by default** - Work stories in order within epic
+3. **Learning transfer** - Draft next story after previous done
+4. **Manual status updates** - Update sprint-status.yaml as needed
+
+### Story Management
+
+1. **Single source of truth** - sprint-status.yaml tracks everything
+2. **No story search** - Agents read exact story from status file
+3. **Context injection** - Each story gets specific technical guidance
+4. **Retrospective learning** - Capture improvements per epic
+
+### Best Practices
+
+1. **Trust the process** - Let workflows guide you
+2. **Respect scale** - Don't over-document small projects
+3. **Use status tracking** - Always know where you are
+4. **Iterate and learn** - Each epic improves the next
 
 ---
 
-**Version**: v6-alpha
+For specific workflow details, see individual workflow READMEs in their respective directories.
-**Last Updated**: 2025-10-26
-
-This document serves as the authoritative guide to BMM v6a workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.
-
-## Related Documentation
-
-- **Workflow Paths**: See `workflow-status/paths/` for detailed greenfield/brownfield routing by level
-- **Phase 2 Planning**: See `2-plan-workflows/README.md` for scale-adaptive planning details
-- **Phase 4 Sprint Planning**: See `4-implementation/sprint-planning/README.md` for sprint status system
-- **Individual Workflows**: Each workflow directory contains its own README with specific instructions

src/modules/bmm/workflows/workflow-status/README.md

@@ -19,7 +19,7 @@ The workflow status system provides:
 workflow-status/
 ├── workflow.yaml              # Main configuration
 ├── instructions.md            # Status checker (99 lines)
-├── workflow-status-template.md # Clean key-value template
+├── workflow-status-template.yaml # Clean YAML status template
 ├── project-levels.yaml        # Source of truth for scale definitions
 └── paths/                     # Modular workflow definitions
     ├── greenfield-level-0.yaml through level-4.yaml
@@ -61,25 +61,44 @@ workflow-init/
 
 ## Status File Format
 
-Simple key-value pairs for instant parsing:
+Clean YAML format with all workflows listed up front:
 
-```markdown
+```yaml
-PROJECT_NAME: MyProject
+# generated: 2025-10-29
-PROJECT_TYPE: software
+# project: MyProject
-PROJECT_LEVEL: 2
+# project_type: software
-FIELD_TYPE: greenfield
+# project_level: 2
-CURRENT_PHASE: 2-Planning
+# field_type: greenfield
-CURRENT_WORKFLOW: prd
+# workflow_path: greenfield-level-2.yaml
-NEXT_ACTION: Continue PRD
+
-NEXT_COMMAND: prd
+workflow_status:
-NEXT_AGENT: pm
+  # Phase 1: Analysis
+  brainstorm-project: optional
+  research: optional
+  product-brief: recommended
+
+  # Phase 2: Planning
+  prd: docs/prd.md
+  validate-prd: optional
+  create-design: conditional
+
+  # Phase 3: Solutioning
+  create-architecture: required
+  validate-architecture: optional
+  solutioning-gate-check: required
 ```
 
-Any agent can instantly grep what they need:
+**Status Values:**
 
-- Any: `grep 'NEXT_ACTION:' status.md`
+- `required` / `optional` / `recommended` / `conditional` - Not yet started
-- Any: `grep 'CURRENT_PHASE:' status.md`
+- `{file-path}` - Completed (e.g., `docs/prd.md`)
-- Any: `grep 'NEXT_COMMAND:' status.md`
+- `skipped` - Optional workflow that was skipped
+
+Any agent can instantly parse what they need:
+
+- Read YAML to see all workflows and their status
+- Check which workflows are completed vs pending
+- Auto-detect existing work by scanning for output files
 
 ## Project Levels
 
@@ -213,10 +232,10 @@ Other workflows read the status to coordinate:
 **Phase 4 (Implementation):**
 
 - workflow-status only tracks sprint-planning completion
-- After sprint-planning, all story/epic tracking happens in the sprint plan output file
+- After sprint-planning, all story/epic tracking happens in sprint-status.yaml
 - Phase 4 workflows do NOT read/write workflow-status (except sprint-planning for prerequisite verification)
 
-The status file is the single source of truth for Phases 1-3 and the hub that keeps all agents synchronized.
+The workflow-status.yaml file is the single source of truth for Phases 1-3, and sprint-status.yaml takes over for Phase 4 implementation tracking.
 
 ## Benefits
 

src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -261,36 +261,129 @@ Here's the complexity scale for reference:
 <template-output>workflow_path_file</template-output>
 </step>
 
-<step n="5" goal="Generate workflow summary">
+<step n="5" goal="Build workflow status YAML structure">
-<action>Build workflow from loaded path file</action>
+<action>Parse the loaded workflow path file and extract all workflows</action>
-<action>Display phases and workflows</action>
-<action>Set initial values for status file</action>
 
-<template-output>current_phase</template-output>
+<action>For each phase in the path file:
-<template-output>current_workflow</template-output>
+
-<template-output>current_agent</template-output>
+- Extract phase number and name
-<template-output>next_action</template-output>
+- Extract all workflows in that phase
-<template-output>next_command</template-output>
+- For each workflow, determine its status type:
-<template-output>next_agent</template-output>
+  - required: true → status = "required"
+  - recommended: true → status = "recommended"
+  - conditional: "if_has_ui" → status = "conditional"
+  - optional: true → status = "optional"
+  - Default if not specified → status = "required"
+    </action>
+
+<action>Build the workflow_items list in this format:
+
+For each phase:
+
+1. Add comment header: `  # Phase {n}: {Phase Name}`
+2. For each workflow in phase:
+   - Add entry: `  {workflow-id}: {status}`
+3. Add blank line between phases
+
+Example structure:
+
+```
+  # Phase 1: Analysis
+  brainstorm-project: optional
+  research: optional
+  product-brief: recommended
+
+  # Phase 2: Planning
+  prd: required
+  validate-prd: optional
+  create-design: conditional
+```
+
+</action>
+
+<action>Scan for existing workflow output files to auto-detect completion:
+
+For each workflow in the list, check common output locations:
+
+- {output_folder}/brainstorm-\*.md for brainstorm-project
+- {output_folder}/research-\*.md for research
+- {output_folder}/product-brief.md for product-brief
+- {output_folder}/prd.md for prd
+- {output_folder}/ux-design.md for create-design
+- {output_folder}/architecture.md for create-architecture
+- {output_folder}/tech-spec.md for tech-spec
+- {output_folder}/sprint-status.yaml for sprint-planning
+
+CRITICAL: If file exists, replace status with ONLY the file path - nothing else.
+Example: product-brief: docs/product-brief.md
+NOT: product-brief: "completed - docs/product-brief.md" or any other text.
+</action>
+
+<template-output>workflow_items</template-output>
 </step>
 
-<step n="6" goal="Create status file">
+<step n="6" goal="Create workflow status file">
-<action>Initialize all status values</action>
+<action>Set generated date to current date</action>
-<template-output>start_date</template-output>
+<template-output>generated</template-output>
-<template-output>last_updated</template-output>
+
-<template-output>phase_1_complete</template-output>
+<action>Prepare all template variables for workflow-status-template.yaml:
-<template-output>phase_2_complete</template-output>
+
-<template-output>phase_3_complete</template-output>
+- generated: {current_date}
-<template-output>phase_4_complete</template-output>
+- project_name: {project_name}
+- project_type: {project_type}
+- project_level: {project_level}
+- field_type: {field_type}
+- workflow_path_file: {workflow_path_file}
+- workflow_items: {workflow_items from step 5}
+  </action>
+
+<action>Display a preview of what will be created:
+
+Show the first workflow in each phase and total count:
+
+"Ready to create workflow status tracking:
+
+- Phase 1 ({phase_1_workflow_count} workflows): Starting with {first_workflow_phase_1}
+- Phase 2 ({phase_2_workflow_count} workflows): Starting with {first_workflow_phase_2}
+- Phase 3 ({phase_3_workflow_count} workflows): Starting with {first_workflow_phase_3}
+- Phase 4 (Implementation tracked separately in sprint-status.yaml)
+
+{{#if detected_completed_workflows}}
+Found existing work:
+{{#each detected_files}}
+
+- {{workflow_name}}: {{file_path}}
+  {{/each}}
+  {{/if}}"
+  </action>
 
 <ask>Ready to create your workflow status file? (y/n)</ask>
 
 <check if="answer == y">
-  <action>Save status file to {output_folder}/bmm-workflow-status.md</action>
+  <action>Generate YAML from workflow-status-template.yaml with all variables</action>
-  <output>✅ Status file created! Next up: {{next_agent}} agent, run `{{next_command}}`</output>
+  <action>Save status file to {output_folder}/bmm-workflow-status.yaml</action>
-  <check if="next_agent !== current_agent">
+
-    <output>It is strongly recommended to clear the context or start a new chat and load the next agent to execute the next command from that agents help menu, unless there is something else I can do for you first.</output>
+<action>Identify the first non-completed workflow in the list</action>
-  </check>
+<action>Look up that workflow's agent and command from the path file</action>
+
+<output>✅ Workflow status file created at {output_folder}/bmm-workflow-status.yaml
+
+**Next Steps:**
+
+{{#if detected_completed_workflows}}
+You have {{detected_count}} workflow(s) already completed. Great progress!
+{{/if}}
+
+**Next Workflow:** {{next_workflow_name}}
+
+**Agent:** {{next_agent}}
+
+**Command:** /bmad:bmm:workflows:{{next_workflow_id}}
+
+{{#if next_agent !== 'pm'}}
+It is recommended to start a new chat and load the {{next_agent}} agent before running the next workflow.
+{{/if}}
+</output>
 </check>
 </step>
 

src/modules/bmm/workflows/workflow-status/init/workflow.yaml

@@ -16,13 +16,13 @@ date: system-generated
 # Workflow components
 installed_path: "{project-root}/bmad/bmm/workflows/workflow-status/init"
 instructions: "{installed_path}/instructions.md"
-template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.md"
+template: "{project-root}/bmad/bmm/workflows/workflow-status/workflow-status-template.yaml"
 
 # Path data files
 path_files: "{project-root}/bmad/bmm/workflows/workflow-status/paths/"
 
 # Output configuration
-default_output_file: "{output_folder}/bmm-workflow-status.md"
+default_output_file: "{output_folder}/bmm-workflow-status.yaml"
 
 standalone: true
 web_bundle: false

src/modules/bmm/workflows/workflow-status/instructions.md

@@ -33,7 +33,7 @@
 </step>
 
 <step n="1" goal="Check for status file">
-<action>Search {output_folder}/ for file: bmm-workflow-status.md</action>
+<action>Search {output_folder}/ for file: bmm-workflow-status.yaml</action>
 
 <check if="no status file found">
   <output>No workflow status found. To get started:
@@ -50,51 +50,66 @@ This will guide you through project setup and create your workflow path.</output
 </step>
 
 <step n="2" goal="Read and parse status">
-<action>Read bmm-workflow-status.md</action>
+<action>Read bmm-workflow-status.yaml</action>
-<action>Extract key-value pairs from status file:</action>
+<action>Parse YAML file and extract metadata from comments and fields:</action>
 
-Parse these fields:
+Parse these fields from YAML comments and metadata:
 
-- PROJECT_NAME
+- project (from YAML field)
-- PROJECT_TYPE
+- project_type (from YAML field)
-- PROJECT_LEVEL
+- project_level (from YAML field)
-- FIELD_TYPE
+- field_type (from YAML field)
-- CURRENT_PHASE
+- workflow_path (from YAML field)
-- CURRENT_WORKFLOW
+
-- NEXT_ACTION
+<action>Parse workflow_status section:</action>
-- NEXT_COMMAND
+
-- NEXT_AGENT
+- Extract all workflow entries with their statuses
+- Identify completed workflows (status = file path)
+- Identify pending workflows (status = required/optional/recommended/conditional)
+- Identify skipped workflows (status = skipped)
+
+<action>Determine current state:</action>
+
+- Find first workflow with status != file path and != skipped
+- This is the NEXT workflow to work on
+- Look up agent and command from workflow path file
   </step>
 
 <step n="3" goal="Display current status and options">
-<action>Load workflow path file to check for optional steps</action>
+<action>Load workflow path file based on workflow_path field</action>
-<action>Check if current workflow is in progress or complete</action>
+<action>Identify current phase from next workflow to be done</action>
+<action>Build list of completed, pending, and optional workflows</action>
 
 <output>
 ## 📊 Current Status
 
-**Project:** {{PROJECT_NAME}} (Level {{PROJECT_LEVEL}} {{PROJECT_TYPE}})
+**Project:** {{project}} (Level {{project_level}} {{project_type}})
-**Phase:** {{CURRENT_PHASE}}
-**Current Workflow:** {{CURRENT_WORKFLOW}}
 
-## 🎯 Your Options
+**Path:** {{workflow_path}}
 
-{{#if CURRENT_WORKFLOW != "complete"}}
+**Progress:**
-**Continue in progress:**
 
-- {{CURRENT_WORKFLOW}} ({{CURRENT_AGENT}} agent)
+{{#each phases}}
-  {{/if}}
+{{phase_name}}:
+{{#each workflows_in_phase}}
 
-**Next required step:**
+- {{workflow_name}}: {{status_display}}
+  {{/each}}
+  {{/each}}
 
-- Command: `{{NEXT_COMMAND}}`
+## 🎯 Next Steps
-- Agent: {{NEXT_AGENT}}
+
+**Next Workflow:** {{next_workflow_name}}
+
+**Agent:** {{next_agent}}
+
+**Command:** /bmad:bmm:workflows:{{next_workflow_id}}
 
 {{#if optional_workflows_available}}
-**Optional workflows available:**
+**Optional Workflows Available:**
 {{#each optional_workflows}}
 
-- {{workflow_name}} ({{agent}})
+- {{workflow_name}} ({{agent}}) - {{status}}
   {{/each}}
   {{/if}}
   </output>
@@ -103,20 +118,69 @@ Parse these fields:
 <step n="4" goal="Offer actions">
 <ask>What would you like to do?
 
-{{#if CURRENT_WORKFLOW != "complete"}}
+1. **Start next workflow** - {{next_workflow_name}} ({{next_agent}} agent)
-
-1. **Continue current** - Resume {{CURRENT_WORKFLOW}}
-   {{/if}}
-2. **Next required** - {{NEXT_COMMAND}}
    {{#if optional_workflows_available}}
-3. **Optional workflow** - Choose from available options
+2. **Run optional workflow** - Choose from available options
    {{/if}}
-4. **View full status** - See complete status file
+3. **View full status YAML** - See complete status file
+4. **Update workflow status** - Mark a workflow as completed or skipped
 5. **Exit** - Return to agent
 
 Your choice:</ask>
 
 <action>Handle user selection based on available options</action>
+
+<check if="choice == 1">
+  <output>Ready to run {{next_workflow_name}}!
+
+**Command:** /bmad:bmm:workflows:{{next_workflow_id}}
+
+**Agent:** Load {{next_agent}} agent first
+
+{{#if next_agent !== current_agent}}
+Tip: Start a new chat and load the {{next_agent}} agent before running this workflow.
+{{/if}}
+</output>
+</check>
+
+<check if="choice == 2 AND optional_workflows_available">
+  <ask>Which optional workflow?
+{{#each optional_workflows numbered}}
+{{number}}. {{workflow_name}} ({{agent}})
+{{/each}}
+
+Your choice:</ask>
+<action>Display selected workflow command and agent</action>
+</check>
+
+<check if="choice == 3">
+  <action>Display complete bmm-workflow-status.yaml file contents</action>
+</check>
+
+<check if="choice == 4">
+  <ask>What would you like to update?
+
+1. Mark a workflow as **completed** (provide file path)
+2. Mark a workflow as **skipped**
+
+Your choice:</ask>
+
+  <check if="update_choice == 1">
+    <ask>Which workflow? (Enter workflow ID like 'prd' or 'create-architecture')</ask>
+    <ask>File path created? (e.g., docs/prd.md)</ask>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+    <action>Update workflow_status in YAML file: {{workflow_id}}: {{file_path}}</action>
+    <action>Save updated YAML file preserving ALL structure and comments</action>
+    <output>✅ Updated {{workflow_id}} to completed: {{file_path}}</output>
+  </check>
+
+  <check if="update_choice == 2">
+    <ask>Which workflow to skip? (Enter workflow ID)</ask>
+    <action>Update workflow_status in YAML file: {{workflow_id}}: skipped</action>
+    <action>Save updated YAML file</action>
+    <output>✅ Marked {{workflow_id}} as skipped</output>
+  </check>
+</check>
 </step>
 
 <!-- ============================================= -->
@@ -124,7 +188,7 @@ Your choice:</ask>
 <!-- ============================================= -->
 
 <step n="10" goal="Validate mode - Check if calling workflow should proceed">
-<action>Read {output_folder}/bmm-workflow-status.md if exists</action>
+<action>Read {output_folder}/bmm-workflow-status.yaml if exists</action>
 
 <check if="status file not found">
   <template-output>status_exists = false</template-output>
@@ -135,23 +199,16 @@ Your choice:</ask>
 </check>
 
 <check if="status file found">
-  <action>Parse status file fields</action>
+  <action>Parse YAML file to extract project metadata and workflow_status</action>
-  <action>Load workflow path file from WORKFLOW_PATH field</action>
+  <action>Load workflow path file from workflow_path field</action>
-  <action>Check if {{calling_workflow}} matches CURRENT_WORKFLOW or NEXT_COMMAND</action>
+  <action>Find first non-completed workflow in workflow_status (next workflow)</action>
+  <action>Check if {{calling_workflow}} matches next workflow or is in the workflow list</action>
 
 <template-output>status_exists = true</template-output>
-<template-output>current_phase = {{CURRENT_PHASE}}</template-output>
+<template-output>project_level = {{project_level}}</template-output>
-<template-output>current_workflow = {{CURRENT_WORKFLOW}}</template-output>
+<template-output>project_type = {{project_type}}</template-output>
-<template-output>next_workflow = {{NEXT_COMMAND}}</template-output>
+<template-output>field_type = {{field_type}}</template-output>
-<template-output>project_level = {{PROJECT_LEVEL}}</template-output>
+<template-output>next_workflow = {{next_workflow_id}}</template-output>
-<template-output>project_type = {{PROJECT_TYPE}}</template-output>
-<template-output>field_type = {{FIELD_TYPE}}</template-output>
-
-  <check if="calling_workflow == current_workflow">
-    <template-output>should_proceed = true</template-output>
-    <template-output>warning = ""</template-output>
-    <template-output>suggestion = "Resuming {{current_workflow}}"</template-output>
-  </check>
 
   <check if="calling_workflow == next_workflow">
     <template-output>should_proceed = true</template-output>
@@ -159,16 +216,22 @@ Your choice:</ask>
     <template-output>suggestion = "Proceeding with planned next step"</template-output>
   </check>
 
-  <check if="calling_workflow != current_workflow AND calling_workflow != next_workflow">
+  <check if="calling_workflow in workflow_status list">
-    <action>Check if calling_workflow is in optional workflows list</action>
+    <action>Check the status of calling_workflow in YAML</action>
 
-    <check if="is optional">
+    <check if="status is file path">
+      <template-output>should_proceed = true</template-output>
+      <template-output>warning = "⚠️ Workflow already completed: {{calling_workflow}}"</template-output>
+      <template-output>suggestion = "This workflow was already completed. Re-running will overwrite: {{status}}"</template-output>
+    </check>
+
+    <check if="status is optional/recommended">
       <template-output>should_proceed = true</template-output>
       <template-output>warning = "Running optional workflow {{calling_workflow}}"</template-output>
       <template-output>suggestion = "This is optional. Expected next: {{next_workflow}}"</template-output>
     </check>
 
-    <check if="not optional">
+    <check if="status is required but not next">
       <template-output>should_proceed = true</template-output>
       <template-output>warning = "⚠️ Out of sequence: Expected {{next_workflow}}, running {{calling_workflow}}"</template-output>
       <template-output>suggestion = "Consider running {{next_workflow}} instead, or continue if intentional"</template-output>
@@ -176,14 +239,20 @@ Your choice:</ask>
 
   </check>
 
-<template-output>status_file_path = {{path to bmm-workflow-status.md}}</template-output>
+  <check if="calling_workflow NOT in workflow_status list">
+    <template-output>should_proceed = true</template-output>
+    <template-output>warning = "⚠️ Unknown workflow: {{calling_workflow}} not in workflow path"</template-output>
+    <template-output>suggestion = "This workflow is not part of the defined path for this project"</template-output>
+  </check>
+
+<template-output>status_file_path = {{path to bmm-workflow-status.yaml}}</template-output>
 </check>
 
 <action>Return control to calling workflow with all template outputs</action>
 </step>
 
 <step n="20" goal="Data mode - Extract specific information">
-<action>Read {output_folder}/bmm-workflow-status.md if exists</action>
+<action>Read {output_folder}/bmm-workflow-status.yaml if exists</action>
 
 <check if="status file not found">
   <template-output>status_exists = false</template-output>
@@ -192,37 +261,46 @@ Your choice:</ask>
 </check>
 
 <check if="status file found">
-  <action>Parse status file completely</action>
+  <action>Parse YAML file completely</action>
   <template-output>status_exists = true</template-output>
 
   <check if="data_request == project_config">
-    <template-output>project_name = {{PROJECT_NAME}}</template-output>
+    <template-output>project_name = {{project}}</template-output>
-    <template-output>project_type = {{PROJECT_TYPE}}</template-output>
+    <template-output>project_type = {{project_type}}</template-output>
-    <template-output>project_level = {{PROJECT_LEVEL}}</template-output>
+    <template-output>project_level = {{project_level}}</template-output>
-    <template-output>field_type = {{FIELD_TYPE}}</template-output>
+    <template-output>field_type = {{field_type}}</template-output>
-    <template-output>workflow_path = {{WORKFLOW_PATH}}</template-output>
+    <template-output>workflow_path = {{workflow_path}}</template-output>
   </check>
 
-  <check if="data_request == phase_status">
+  <check if="data_request == workflow_status">
-    <template-output>current_phase = {{CURRENT_PHASE}}</template-output>
+    <action>Parse workflow_status section and return all workflow: status pairs</action>
-    <template-output>phase_1_complete = {{PHASE_1_COMPLETE}}</template-output>
+    <template-output>workflow_status = {{workflow_status_object}}</template-output>
-    <template-output>phase_2_complete = {{PHASE_2_COMPLETE}}</template-output>
+    <action>Calculate completion stats:</action>
-    <template-output>phase_3_complete = {{PHASE_3_COMPLETE}}</template-output>
+    <template-output>total_workflows = {{count all workflows}}</template-output>
-    <template-output>phase_4_complete = {{PHASE_4_COMPLETE}}</template-output>
+    <template-output>completed_workflows = {{count file path statuses}}</template-output>
+    <template-output>pending_workflows = {{count required/optional/etc}}</template-output>
+    <template-output>skipped_workflows = {{count skipped}}</template-output>
   </check>
 
   <check if="data_request == all">
     <action>Return all parsed fields as template outputs</action>
+    <template-output>project = {{project}}</template-output>
+    <template-output>project_type = {{project_type}}</template-output>
+    <template-output>project_level = {{project_level}}</template-output>
+    <template-output>field_type = {{field_type}}</template-output>
+    <template-output>workflow_path = {{workflow_path}}</template-output>
+    <template-output>workflow_status = {{workflow_status_object}}</template-output>
+    <template-output>generated = {{generated}}</template-output>
   </check>
 
-<template-output>status_file_path = {{path to bmm-workflow-status.md}}</template-output>
+<template-output>status_file_path = {{path to bmm-workflow-status.yaml}}</template-output>
 </check>
 
 <action>Return control to calling workflow with requested data</action>
 </step>
 
 <step n="30" goal="Init-check mode - Simple existence check">
-<action>Check if {output_folder}/bmm-workflow-status.md exists</action>
+<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
 
 <check if="exists">
   <template-output>status_exists = true</template-output>
@@ -238,7 +316,7 @@ Your choice:</ask>
 </step>
 
 <step n="40" goal="Update mode - Centralized status file updates">
-<action>Read {output_folder}/bmm-workflow-status.md</action>
+<action>Read {output_folder}/bmm-workflow-status.yaml</action>
 
 <check if="status file not found">
   <template-output>success = false</template-output>
@@ -247,64 +325,48 @@ Your choice:</ask>
 </check>
 
 <check if="status file found">
-  <action>Parse all current values from status file</action>
+  <action>Parse YAML file completely</action>
-  <action>Load workflow path file from WORKFLOW_PATH field</action>
+  <action>Load workflow path file from workflow_path field</action>
   <action>Check {{action}} parameter to determine update type</action>
 
   <!-- ============================================= -->
   <!-- ACTION: complete_workflow -->
   <!-- ============================================= -->
   <check if="action == complete_workflow">
-    <action>Get {{workflow_name}} parameter (required)</action>
+    <action>Get {{workflow_id}} parameter (required)</action>
+    <action>Get {{output_file}} parameter (required - path to created file)</action>
 
-    <action>Mark workflow complete:</action>
+    <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
-    - Update CURRENT_WORKFLOW to "{{workflow_name}} - Complete"
+    <action>Update workflow status in YAML:</action>
+    - In workflow_status section, update: {{workflow_id}}: {{output_file}}
 
-    <action>Find {{workflow_name}} in loaded path YAML</action>
+    <action>Find {{workflow_id}} in loaded path YAML</action>
     <action>Determine next workflow from path sequence</action>
+    <action>Find first workflow in workflow_status with status != file path and != skipped</action>
 
-    <action>Update Next Action fields:</action>
+    <action>Save updated YAML file preserving ALL structure and comments</action>
-    - NEXT_ACTION: Description from next workflow in path
-    - NEXT_COMMAND: Command for next workflow
-    - NEXT_AGENT: Agent for next workflow
-    - CURRENT_WORKFLOW: Set to next workflow name (or "Complete" if no more)
-    - CURRENT_AGENT: Set to next agent
-
-    <action>Check if phase complete:</action>
-    - If {{workflow_name}} is last required workflow in current phase
-    - Update PHASE_X_COMPLETE to true
-    - Update CURRENT_PHASE to next phase (if applicable)
-
-    <action>Update LAST_UPDATED to {{date}}</action>
-    <action>Save status file</action>
 
     <template-output>success = true</template-output>
     <template-output>next_workflow = {{determined next workflow}}</template-output>
-    <template-output>next_agent = {{determined next agent}}</template-output>
+    <template-output>next_agent = {{determined next agent from path file}}</template-output>
-    <template-output>phase_complete = {{true/false}}</template-output>
+    <template-output>completed_workflow = {{workflow_id}}</template-output>
+    <template-output>output_file = {{output_file}}</template-output>
 
   </check>
 
   <!-- ============================================= -->
-  <!-- ACTION: set_current_workflow (manual override) -->
+  <!-- ACTION: skip_workflow -->
   <!-- ============================================= -->
-  <check if="action == set_current_workflow">
+  <check if="action == skip_workflow">
-    <action>Get {{workflow_name}} parameter (required)</action>
+    <action>Get {{workflow_id}} parameter (required)</action>
-    <action>Get {{agent_name}} parameter (optional)</action>
 
-    <action>Update current workflow:</action>
+    <action>Update workflow status in YAML:</action>
-    - CURRENT_WORKFLOW: {{workflow_name}}
+    - In workflow_status section, update: {{workflow_id}}: skipped
-    - CURRENT_AGENT: {{agent_name or infer from path}}
 
-    <action>Find {{workflow_name}} in path to determine next:</action>
+    <action>Save updated YAML file</action>
-    - NEXT_ACTION: Next workflow description
-    - NEXT_COMMAND: Next workflow command
-    - NEXT_AGENT: Next workflow agent
-
-    <action>Update LAST_UPDATED to {{date}}</action>
-    <action>Save status file</action>
 
     <template-output>success = true</template-output>
+    <template-output>skipped_workflow = {{workflow_id}}</template-output>
 
   </check>
 
@@ -313,7 +375,7 @@ Your choice:</ask>
   <!-- ============================================= -->
   <check if="action not recognized">
     <template-output>success = false</template-output>
-    <template-output>error = "Unknown action: {{action}}. Valid actions: complete_workflow, set_current_workflow"</template-output>
+    <template-output>error = "Unknown action: {{action}}. Valid actions: complete_workflow, skip_workflow"</template-output>
   </check>
 
 </check>

src/modules/bmm/workflows/workflow-status/sample-level-3-workflow.yaml

@@ -0,0 +1,49 @@
+# Workflow Status Template
+# This tracks progress through phases 1-3 of the BMM methodology
+# Phase 4 (Implementation) is tracked separately in sprint-status.yaml
+
+# generated: 2025-10-29
+# project: Enterprise Customer Portal
+# project_type: software
+# project_level: 3
+# field_type: greenfield
+# workflow_path: greenfield-level-3.yaml
+
+# STATUS DEFINITIONS:
+# ==================
+# Initial Status (before completion):
+#   - required: Must be completed to progress
+#   - optional: Can be completed but not required
+#   - recommended: Strongly suggested but not required
+#   - conditional: Required only if certain conditions met (e.g., if_has_ui)
+#
+# Completion Status:
+#   - {file-path}: File created/found (e.g., "docs/product-brief.md")
+#   - skipped: Optional/conditional workflow that was skipped
+
+generated: 2025-10-29
+project: Enterprise Customer Portal
+project_type: software
+project_level: 3
+field_type: greenfield
+workflow_path: greenfield-level-3.yaml
+
+workflow_status:
+  # Phase 1: Analysis
+  brainstorm-project: docs/brainstorm-session-2025-10-15.md
+  research: docs/research-api-patterns.md
+  product-brief: docs/product-brief.md
+
+  # Phase 2: Planning
+  prd: docs/prd.md
+  validate-prd: skipped
+  create-design: docs/ux-design.md
+
+  # Phase 3: Solutioning
+  create-architecture: required
+  validate-architecture: optional
+  solutioning-gate-check: recommended
+
+  # Phase 4: Implementation
+  sprint-planning: required
+  # Note: Subsequent implementation workflows tracked in sprint-status.yaml

src/modules/bmm/workflows/workflow-status/workflow-status-template.md

@@ -1,30 +0,0 @@
-# BMM Workflow Status
-
-## Project Configuration
-
-PROJECT_NAME: {{project_name}}
-PROJECT_TYPE: {{project_type}}
-PROJECT_LEVEL: {{project_level}}
-FIELD_TYPE: {{field_type}}
-START_DATE: {{start_date}}
-WORKFLOW_PATH: {{workflow_path_file}}
-
-## Current State
-
-CURRENT_PHASE: {{current_phase}}
-CURRENT_WORKFLOW: {{current_workflow}}
-CURRENT_AGENT: {{current_agent}}
-PHASE_1_COMPLETE: {{phase_1_complete}}
-PHASE_2_COMPLETE: {{phase_2_complete}}
-PHASE_3_COMPLETE: {{phase_3_complete}}
-PHASE_4_COMPLETE: {{phase_4_complete}}
-
-## Next Action
-
-NEXT_ACTION: {{next_action}}
-NEXT_COMMAND: {{next_command}}
-NEXT_AGENT: {{next_agent}}
-
----
-
-_Last Updated: {{last_updated}}_

src/modules/bmm/workflows/workflow-status/workflow-status-template.yaml

@@ -0,0 +1,31 @@
+# Workflow Status Template
+# This tracks progress through phases 1-3 of the BMM methodology
+# Phase 4 (Implementation) is tracked separately in sprint-status.yaml
+
+# generated: {{generated}}
+# project: {{project_name}}
+# project_type: {{project_type}}
+# project_level: {{project_level}}
+# field_type: {{field_type}}
+# workflow_path: {{workflow_path_file}}
+
+# STATUS DEFINITIONS:
+# ==================
+# Initial Status (before completion):
+#   - required: Must be completed to progress
+#   - optional: Can be completed but not required
+#   - recommended: Strongly suggested but not required
+#   - conditional: Required only if certain conditions met (e.g., if_has_ui)
+#
+# Completion Status:
+#   - {file-path}: File created/found (e.g., "docs/product-brief.md")
+#   - skipped: Optional/conditional workflow that was skipped
+
+generated: "{{generated}}"
+project: "{{project_name}}"
+project_type: "{{project_type}}"
+project_level: "{{project_level}}"
+field_type: "{{field_type}}"
+workflow_path: "{{workflow_path_file}}"
+
+workflow_status: "{{workflow_items}}"

src/modules/bmm/workflows/workflow-status/workflow.yaml

@@ -1,6 +1,6 @@
 # Workflow Status - Master Router and Status Tracker
 name: workflow-status
-description: 'Lightweight status checker - answers "what should I do now?" for any agent. Reads simple key-value status file for instant parsing. Use workflow-init for new projects.'
+description: 'Lightweight status checker - answers "what should I do now?" for any agent. Reads YAML status file for workflow tracking. Use workflow-init for new projects.'
 author: "BMad"
 
 # Critical variables from config
@@ -17,13 +17,13 @@ installed_path: "{project-root}/bmad/bmm/workflows/workflow-status"
 instructions: "{installed_path}/instructions.md"
 
 # Template for status file creation (used by workflow-init)
-template: "{installed_path}/workflow-status-template.md"
+template: "{installed_path}/workflow-status-template.yaml"
 
 # Path definitions for project types
 path_files: "{installed_path}/paths/"
 
 # Output configuration - reads existing status
-default_output_file: "{output_folder}/bmm-workflow-status.md"
+default_output_file: "{output_folder}/bmm-workflow-status.yaml"
 
 standalone: true
 

src/modules/cis/readme.md

@@ -1,86 +1,153 @@
----
+# CIS - Creative Intelligence Suite
-last-redoc-date: 2025-09-28
----
 
-<!-- Powered by BMAD-CORE™ -->
+AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
-# Creative Intelligence System (CIS)
+## Table of Contents
 
-**Purpose:** Transform creative and strategic thinking through AI-powered facilitation across five specialized domains. The CIS module provides expert coaching for brainstorming, design thinking, problem-solving, innovation strategy, and storytelling.
+- [Core Capabilities](#core-capabilities)
+- [Specialized Agents](#specialized-agents)
+- [Interactive Workflows](#interactive-workflows)
+- [Quick Start](#quick-start)
+- [Key Differentiators](#key-differentiators)
+- [Configuration](#configuration)
 
-**Overview:** The Creative Intelligence System equips teams and individuals with structured creative methodologies delivered through distinctive agent personas. Each agent facilitates interactive workflows that guide users through proven techniques while adapting to context, energy levels, and goals. Unlike traditional creative tools, CIS agents act as master facilitators who ask questions to draw out insights rather than generating solutions directly.
+## Core Capabilities
 
-## Workflows
+CIS provides structured creative methodologies through distinctive agent personas who act as master facilitators, drawing out insights through strategic questioning rather than generating solutions directly.
+
+## Specialized Agents
+
+[View detailed agent descriptions →](./agents/README.md)
+
+- **Carson** - Brainstorming Specialist (energetic facilitator)
+- **Maya** - Design Thinking Maestro (jazz-like improviser)
+- **Dr. Quinn** - Problem Solver (detective-scientist hybrid)
+- **Victor** - Innovation Oracle (bold strategic precision)
+- **Sophia** - Master Storyteller (whimsical narrator)
+
+## Interactive Workflows
 
 [View all workflows →](./workflows/README.md)
 
-The module includes **5 interactive workflows** with over 150 creative techniques and frameworks:
+**5 Workflows** with **150+ Creative Techniques:**
 
-- **Brainstorming** - 36 creative techniques across 7 categories for ideation
+### Brainstorming
-- **Design Thinking** - Complete 5-phase human-centered design process
-- **Problem Solving** - Systematic root cause analysis and solution generation
-- **Innovation Strategy** - Business model innovation and disruption analysis
-- **Storytelling** - 25 story frameworks for compelling narratives
 
-## Agents
+36 techniques across 7 categories for ideation
 
-[View all agents →](./agents/README.md)
+- Divergent/convergent thinking
+- Lateral connections
+- Forced associations
 
-Five specialized agents with unique personas and communication styles:
+### Design Thinking
 
-- **Carson** - Elite Brainstorming Specialist (energetic facilitator)
+Complete 5-phase human-centered process
-- **Maya** - Design Thinking Maestro (jazz-like improviser)
-- **Dr. Quinn** - Master Problem Solver (detective-scientist hybrid)
-- **Victor** - Disruptive Innovation Oracle (bold strategic precision)
-- **Sophia** - Master Storyteller (flowery, whimsical narrator)
 
-## Configuration
+- Empathize → Define → Ideate → Prototype → Test
+- User journey mapping
+- Rapid iteration
 
-The module uses `/bmad/cis/config.yaml` for:
+### Problem Solving
 
-- `output_folder` - Where workflow results are saved
+Systematic root cause analysis
-- `user_name` - Session participant identification
-- `communication_language` - Facilitation language preference
 
-## Usage
+- 5 Whys, Fishbone diagrams
+- Solution generation
+- Impact assessment
+
+### Innovation Strategy
+
+Business model disruption
+
+- Blue Ocean Strategy
+- Jobs-to-be-Done
+- Disruptive innovation patterns
+
+### Storytelling
+
+25 narrative frameworks
+
+- Hero's Journey
+- Story circles
+- Compelling pitch structures
+
+## Quick Start
+
+### Direct Workflow
 
 ```bash
-# Direct workflow invocation
+# Start interactive session
 workflow brainstorming
-workflow design-thinking --data /path/to/context.md
 
-# Agent-facilitated sessions
+# With context document
+workflow design-thinking --data /path/to/context.md
+```
+
+### Agent-Facilitated
+
+```bash
+# Load agent
 agent cis/brainstorming-coach
+
+# Start workflow
 > *brainstorm
 ```
 
 ## Key Differentiators
 
-- **Facilitation Over Generation:** Agents guide users to discover their own insights through strategic questioning
+- **Facilitation Over Generation** - Guides discovery through questions
-- **Energy-Aware Sessions:** Built-in checkpoints monitor and adapt to user engagement levels
+- **Energy-Aware Sessions** - Adapts to engagement levels
-- **Context Integration:** All workflows accept optional context documents for domain-specific guidance
+- **Context Integration** - Domain-specific guidance support
-- **Persona-Driven Experience:** Each agent embodies a unique communication style matching their expertise
+- **Persona-Driven** - Unique communication styles
-- **Rich Method Libraries:** 150+ proven techniques and frameworks across creative disciplines
+- **Rich Method Libraries** - 150+ proven techniques
 
-## Installation
+## Configuration
 
-The CIS module installer (`_module-installer/`) configures the complete creative intelligence suite including all agents, workflows, and technique libraries.
+Edit `/bmad/cis/config.yaml`:
 
-## Module Architecture
+```yaml
+output_folder: ./creative-outputs
+user_name: Your Name
+communication_language: english
+```
+
+## Module Structure
 
 ```
 cis/
-├── agents/          # 5 specialized creative agents
+├── agents/              # 5 specialized facilitators
-├── workflows/       # 5 interactive workflows
+├── workflows/           # 5 interactive processes
 │   ├── brainstorming/
 │   ├── design-thinking/
 │   ├── innovation-strategy/
 │   ├── problem-solving/
 │   └── storytelling/
-├── tasks/           # Supporting task operations
+├── tasks/              # Supporting operations
-└── teams/           # Agent team configurations
+└── teams/              # Agent collaborations
 ```
 
+## Integration Points
+
+CIS workflows integrate with:
+
+- **BMM** - Powers project brainstorming
+- **BMB** - Creative module design
+- **Custom Modules** - Shared creative resource
+
+## Best Practices
+
+1. **Set clear objectives** before starting sessions
+2. **Provide context documents** for domain relevance
+3. **Trust the process** - Let facilitation guide you
+4. **Take breaks** when energy flags
+5. **Document insights** as they emerge
+
+## Related Documentation
+
+- **[Workflow Guide](./workflows/README.md)** - Detailed workflow instructions
+- **[Agent Personas](./agents/README.md)** - Full agent descriptions
+- **[BMM Integration](../bmm/README.md)** - Development workflow connection
+
 ---
 
-_Part of the BMAD Method v6.0 - Transform your creative potential with expert AI facilitation_
+Part of BMad Method v6.0 - Transform creative potential through expert AI facilitation.

src/modules/cis/workflows/README.md

@@ -1,67 +1,139 @@
----
-last-redoc-date: 2025-09-28
----
-
 # CIS Workflows
 
-The Creative Intelligence System includes five interactive workflows that facilitate different creative and strategic processes. Each workflow uses curated technique libraries and structured facilitation to guide users through proven methodologies.
+Five interactive workflows facilitating creative and strategic processes through curated technique libraries and structured facilitation.
 
-## Available Workflows
+## Table of Contents
+
+- [Workflow Overview](#workflow-overview)
+- [Common Features](#common-features)
+- [Usage](#usage)
+- [Configuration](#configuration)
+
+## Workflow Overview
 
 ### [Brainstorming](./brainstorming)
 
-Facilitates interactive ideation sessions using 36 creative techniques across 7 categories. AI acts as master facilitator using "Yes, and..." methodology. Supports user-selected, AI-recommended, random, or progressive technique flows.
+**Purpose:** Interactive ideation using 36 techniques across 7 categories
 
-**Key Feature:** Comprehensive technique library spanning collaborative, structured, creative, deep, theatrical, wild, and introspective approaches.
+**Approach:** Master facilitation with "Yes, and..." methodology
+
+**Techniques:** Collaborative, structured, creative, deep, theatrical, wild, introspective
+
+**Selection Modes:** User-selected, AI-recommended, random, or progressive
 
 ### [Design Thinking](./design-thinking)
 
-Guides human-centered design through the complete five-phase methodology: Empathize, Define, Ideate, Prototype, and Test. Emphasizes divergent thinking before convergent action with rapid prototyping focus.
+**Purpose:** Human-centered design through five phases
 
-**Key Feature:** Phase-specific method library and systematic user empathy development.
+**Process:** Empathize → Define → Ideate → Prototype → Test
+
+**Focus:** Divergent thinking before convergent action
+
+**Output:** User empathy insights and rapid prototypes
 
 ### [Innovation Strategy](./innovation-strategy)
 
-Identifies disruption opportunities and architects business model innovation. Analyzes markets, competitive dynamics, and value chains using frameworks like Jobs-to-be-Done and Blue Ocean Strategy.
+**Purpose:** Identify disruption opportunities and business model innovation
 
-**Key Feature:** Strategic focus on sustainable competitive advantage over feature innovation.
+**Frameworks:** Jobs-to-be-Done, Blue Ocean Strategy, Value Chain Analysis
+
+**Focus:** Sustainable competitive advantage over features
+
+**Output:** Strategic innovation roadmap
 
 ### [Problem Solving](./problem-solving)
 
-Applies systematic problem-solving methodologies combining TRIZ, Theory of Constraints, Systems Thinking, and Root Cause Analysis. Detective approach treats challenges as elegant puzzles.
+**Purpose:** Systematic challenge resolution
 
-**Key Feature:** Relentless root cause focus using framework-driven analysis.
+**Methods:** TRIZ, Theory of Constraints, Systems Thinking, Root Cause Analysis
+
+**Approach:** Detective-style puzzle solving
+
+**Output:** Root cause identification and solution strategies
 
 ### [Storytelling](./storytelling)
 
-Crafts compelling narratives using proven story frameworks (Hero's Journey, Three-Act Structure, Story Brand). Tailors emotional psychology and structure to platform and audience.
+**Purpose:** Craft compelling narratives
 
-**Key Feature:** Whimsical facilitation style that embodies master storytelling craft.
+**Frameworks:** Hero's Journey, Three-Act Structure, Story Brand (25 total)
 
-## Common Patterns
+**Customization:** Platform and audience-specific adaptation
 
-All CIS workflows share these characteristics:
+**Style:** Whimsical master storyteller facilitation
 
-- **Interactive Facilitation**: AI guides rather than generates, asking questions to draw out user insights
+## Common Features
-- **Technique Libraries**: CSV databases of methods, frameworks, and approaches
+
-- **Context Awareness**: Accept optional context documents via data attribute
+All workflows share:
-- **Structured Output**: Comprehensive reports capturing insights, decisions, and action plans
+
-- **Energy Monitoring**: Check-ins throughout to adapt pace and approach
+- **Interactive Facilitation** - AI guides through questions, not generation
+- **Technique Libraries** - CSV databases of proven methods
+- **Context Integration** - Optional document input for domain relevance
+- **Structured Output** - Comprehensive reports with insights and actions
+- **Energy Monitoring** - Adaptive pacing based on engagement
 
 ## Usage
 
-```bash
+### Basic Invocation
-# Basic invocation
-workflow [workflow-name]
 
-# With context document
+```bash
+workflow brainstorming
+workflow design-thinking
+workflow innovation-strategy
+workflow problem-solving
+workflow storytelling
+```
+
+### With Context
+
+```bash
 workflow [workflow-name] --data /path/to/context.md
 ```
 
+### Via Agent
+
+```bash
+agent cis/brainstorming-coach
+> *brainstorm
+```
+
 ## Configuration
 
-All workflows reference `/bmad/cis/config.yaml` for:
+Edit `/bmad/cis/config.yaml`:
 
-- `output_folder` - Where workflow results are saved
+| Setting                | Purpose                 | Default            |
-- `user_name` - Session participant identification
+| ---------------------- | ----------------------- | ------------------ |
-- `communication_language` - Facilitation language preference
+| output_folder          | Result storage location | ./creative-outputs |
+| user_name              | Session participant     | User               |
+| communication_language | Facilitation language   | english            |
+
+## Workflow Structure
+
+Each workflow contains:
+
+```
+workflow-name/
+├── workflow.yaml      # Configuration
+├── instructions.md    # Facilitation guide
+├── techniques.csv     # Method library
+└── README.md         # Documentation
+```
+
+## Best Practices
+
+1. **Prepare context** - Provide background documents for better results
+2. **Set clear objectives** - Define goals before starting
+3. **Trust the process** - Let facilitation guide discovery
+4. **Capture everything** - Document insights as they emerge
+5. **Take breaks** - Pause when energy drops
+
+## Integration
+
+CIS workflows integrate with:
+
+- **BMM** - Project brainstorming and ideation
+- **BMB** - Creative module design
+- **Custom Modules** - Shared creative resource
+
+---
+
+For detailed workflow instructions, see individual workflow directories.

src/modules/cis/workflows/storytelling/instructions.md

@@ -50,9 +50,17 @@ I can help craft your story using these proven narrative frameworks:
 3. **Customer Journey Story** - Before/after transformation narrative
 4. **Challenge-Overcome Arc** - Dramatic obstacle-to-victory structure
 
-**Strategic Narratives:** 5. **Brand Story** - Values, mission, and unique positioning 6. **Pitch Narrative** - Persuasive problem-to-solution structure 7. **Vision Narrative** - Future-focused aspirational story 8. **Origin Story** - Foundational narrative of how it began
+**Strategic Narratives:**
 
-**Specialized Narratives:** 9. **Data Storytelling** - Transform insights into compelling narrative 10. **Emotional Hooks** - Craft powerful opening and touchpoints
+5. **Brand Story** - Values, mission, and unique positioning
+6. **Pitch Narrative** - Persuasive problem-to-solution structure
+7. **Vision Narrative** - Future-focused aspirational story
+8. **Origin Story** - Foundational narrative of how it began
+
+**Specialized Narratives:**
+
+9. **Data Storytelling** - Transform insights into compelling narrative
+10. **Emotional Hooks** - Craft powerful opening and touchpoints
 
 Which framework best fits your purpose? (Enter 1-10, or ask for my recommendation)
 </ask>

tools/cli/installers/lib/core/manifest-generator.js

@@ -4,6 +4,9 @@ const yaml = require('js-yaml');
 const crypto = require('node:crypto');
 const { getSourcePath, getModulePath } = require('../../../lib/project-root');
 
+// Load package.json for version info
+const packageJson = require('../../../../../package.json');
+
 /**
  * Generates manifest files for installed workflows, agents, and tasks
  */
@@ -451,7 +454,7 @@ class ManifestGenerator {
 
     const manifest = {
       installation: {
-        version: '6.0.0-alpha.0',
+        version: packageJson.version,
         installDate: new Date().toISOString(),
         lastUpdated: new Date().toISOString(),
       },