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

package/docs/index.md

@@ -0,0 +1,143 @@
+# 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](./modules/bmm/quick-start)     | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) |
+| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)    | [Quick Start Guide](./modules/bmm/quick-start)              |
+| **Brownfield project** | [Brownfield Guide](./modules/bmm/brownfield-guide) | [Quick Start Guide](./modules/bmm/quick-start)              |
+
+---
+
+## 📋 Core Documentation
+
+### Project-Level Docs (Root)
+
+- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions
+- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes
+
+### Installation & Setup
+
+- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
+- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
+- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing
+
+---
+
+## 🏗️ Module Documentation
+
+### BMad Method (BMM) - Software & Game Development
+
+The flagship module for agile AI-driven development.
+
+- **[BMM Module README](./modules/bmm/)** - Module overview, agents, and complete documentation index
+- **[BMM Documentation](./modules/bmm/)** - All BMM-specific guides and references:
+  - [Quick Start Guide](./modules/bmm/quick-start) - Step-by-step guide to building your first project
+  - [Quick Spec Flow](./modules/bmm/quick-spec-flow) - Rapid Level 0-1 development
+  - [Scale Adaptive System](./modules/bmm/scale-adaptive-system) - Understanding the 5-level system
+  - [Brownfield Guide](./modules/bmm/brownfield-guide) - Working with existing codebases
+- **[BMM Workflows Guide](./modules/bmm/index#-workflow-guides)** - **ESSENTIAL READING**
+- **[Test Architect Guide](./modules/bmm/test-architecture)** - Testing strategy and quality assurance
+
+### BMad Builder (BMB) - Create Custom Solutions
+
+Build your own agents, workflows, and modules.
+
+- **[BMB Module Overview](./modules/bmb/index)** - Module overview and capabilities
+- **[Agent Creation Guide](./modules/bmb/agents/index)** - Design custom agents
+
+### Creative Intelligence Suite (CIS) - Innovation & Creativity
+
+AI-powered creative thinking and brainstorming.
+
+- **[CIS Module README](./modules/cis/)** - 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)
+- [Rovo Dev](./ide-info/rovo-dev.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
+
+### Custom Agents, Workflow and Modules
+
+- **[Custom Content Installation](./custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer!
+- [Agent Customization Guide](./agent-customization-guide.md) - Customize agent behavior and responses
+
+---
+
+## 🎓 Recommended Reading Paths
+
+### Path 1: Brand New to BMad (Software Project)
+
+1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
+2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
+3. [BMM Module README](./modules/bmm/) - Understand agents
+4. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
+5. [Your IDE guide](./ide-info/) - Optimize your workflow
+
+### Path 2: Game Development Project
+
+1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
+2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
+3. [BMM Module README](./modules/bmm/) - Game agents are included
+4. [BMGD Workflows Guide](./modules/bmgd/workflows-guide) - Game-specific 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](./modules/bmm/quick-start) - Reorient yourself
+3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Learn new v6 workflows
+
+### Path 4: Working with Existing Codebase (Brownfield)
+
+1. [Brownfield Guide](./modules/bmm/brownfield-guide) - Approach for legacy code
+2. [Quick Start Guide](./modules/bmm/quick-start) - Follow the process
+3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
+
+### Path 5: Building Custom Solutions
+
+1. [BMB Module Overview](./modules/bmb/index) - Understand capabilities
+2. [Agent Creation Guide](./modules/bmb/agents/index) - Create agents
+3. [BMB Workflows Guide](./modules/bmb/workflows/) - Understand workflow structure
+
+### Path 6: Contributing to BMad
+
+1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines
+2. Relevant module README - Understand the area you're contributing to

package/docs/v4-to-v6-upgrade.md

@@ -10,14 +10,14 @@ BMad v6 represents a complete ground-up rewrite with significant architectural c
 
 When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
 
-- **Legacy folders**: Any folders starting with `.bmad`, `bmad` (lowercase), or `Bmad`
+- **Legacy folders**: Any folders starting with `_bmad`, `bmad` (lowercase), or `Bmad`
 - **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
 
 ### What Happens During Detection
 
-1. **Automatic Backup of v4 Modules**: All `.bmad-*` folders are moved to `v4-backup/` in your project root
+1. **Automatic Backup of v4 Modules**: All `_bmad-*` folders are moved to `v4-backup/` in your project root
    - If a backup already exists, a timestamp is added to avoid conflicts
-   - Example: `.bmad-core` → `v4-backup/.bmad-core`
+   - Example: `_bmad-core` → `v4-backup/_bmad-core`
    - Your project files and data are NOT affected
 
 2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
@@ -34,12 +34,12 @@ When you run `npm run install:bmad` on a project with v4 installed, the installe
 
 | v4 Module                     | v6 Status                                        |
 | ----------------------------- | ------------------------------------------------ |
-| `.bmad-2d-phaser-game-dev`    | Integrated into BMM                              |
-| `.bmad-2d-unity-game-dev`     | Integrated into BMM                              |
-| `.bmad-godot-game-dev`        | Integrated into BMM                              |
-| `.bmad-*-game-dev` (any)      | Integrated into BMM                              |
-| `.bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
-| `.bmad-creative-writing`      | Not adapted - New module releasing soon          |
+| `_bmad-2d-phaser-game-dev`    | Integrated into BMM                              |
+| `_bmad-2d-unity-game-dev`     | Integrated into BMM                              |
+| `_bmad-godot-game-dev`        | Integrated into BMM                              |
+| `_bmad-*-game-dev` (any)      | Integrated into BMM                              |
+| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
+| `_bmad-creative-writing`      | Not adapted - New module releasing soon          |
 
 **Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
 
@@ -53,30 +53,30 @@ When you run `npm run install:bmad` on a project with v4 installed, the installe
 
 ```
 your-project/
-├── .bmad-core/           # Was actually the BMad Method
-├── .bmad-game-dev/       # Separate expansion packs
-├── .bmad-creative-writing/
-└── .bmad-infrastructure-devops/
+├── _bmad-core/           # Was actually the BMad Method
+├── _bmad-game-dev/       # Separate expansion packs
+├── _bmad-creative-writing/
+└── _bmad-infrastructure-devops/
 ```
 
 **v6 Unified Structure:**
 
 ```
 your-project/
-└── bmad/                 # Single installation folder
+└── _bmad/       # Single installation folder, default _bmad
     ├── core/            # Real core framework (applies to all modules)
     ├── bmm/             # BMad Method (software/game dev)
     ├── bmb/             # BMad Builder (create agents/workflows)
     ├── cis/             # Creative Intelligence Suite
-    └── _cfg/            # Your customizations
+    └── _config/            # Your customizations
         └── agents/      # Agent customization files
 ```
 
 ### Key Concept Changes
 
-- **v4 `.bmad-core`**: Was actually the BMad Method
-- **v6 `bmad/core/`**: Is the real universal core framework
-- **v6 `bmad/bmm/`**: Is the BMad Method module
+- **v4 `_bmad-core`**: Was actually the BMad Method
+- **v6 `_bmad/core/`**: Is the real universal core framework
+- **v6 `_bmad/bmm/`**: Is the BMad Method module
 - **Module identification**: All modules now have a `config.yaml` file
 
 ---
@@ -93,7 +93,7 @@ After running the v6 installer:
    - This tells v6 you've already completed planning and solutioning phases
 3. **Document paths**: Keep your existing paths during installation
    - Default PRD/Architecture location: `docs/`
-   - Default stories location: `docs/stories/`
+   - Default stories location: `docs/sprint-artifacts/`
    - **Accept these defaults** if you're already using them in v4
 
 > **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
@@ -110,15 +110,15 @@ After running the v6 installer:
 
 ### v4 Agent Customization
 
-In v4, you may have modified agent files directly in `.bmad-*` folders.
+In v4, you may have modified agent files directly in `_bmad-*` folders.
 
 ### v6 Agent Customization
 
-**All customizations** now go in `bmad/_cfg/agents/` using customize files:
+**All customizations** now go in `_bmad/_config/agents/` using customize files:
 
 **Example: Renaming an agent and changing communication style**
 
-File: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+File: `_bmad/_config/agents/bmm-pm.customize.yaml`
 
 ```yaml
 # Customize the PM agent
@@ -133,8 +133,8 @@ persona:
 
 **How it works:**
 
-- Base agent: `bmad/bmm/agents/pm.md`
-- Customization: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+- Base agent: `_bmad/bmm/agents/pm.md`
+- Customization: `_bmad/_config/agents/bmm-pm.customize.yaml`
 - Result: Agent uses your custom name and style, but updates don't overwrite your changes
 
 ---
@@ -176,7 +176,7 @@ npx bmad-method install
 
 The installer will:
 
-1. Detect v4 installation and offer to backup `.bmad-*` folders
+1. Detect v4 installation and offer to backup `_bmad-*` folders
 2. Prompt for recommended cleanup (you can skip)
 3. Let you select modules (recommend: BMM for software and or game development)
 4. Configure core settings (name, language, etc.)
@@ -188,7 +188,7 @@ The installer will:
 If you're using:
 
 - `docs/` for PRD and architecture
-- `docs/stories/` for story files
+- `docs/sprint-artifacts/` for story files
 
 **Accept these defaults** during installation.
 
@@ -196,23 +196,25 @@ If you're using:
 
 After installation:
 
-```bash
-# Start the analyst and tell the analyst after it loads - claude code instructions:
-claude # wait for claude to launch in terminal
-- `/analyst` # wait for analyst greeting and menu
-- `*workflow-init` # v6 now supports much better natural language fuzzy matching - so you could also say `workflow init` or possibly `please init the workflow`
-```
+1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
+   - [Claude Code](./ide-info/claude-code.md)
+   - [Cursor](./ide-info/cursor.md)
+   - [VS Code/Windsurf](./ide-info/) - Check your IDE folder
+
+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, its most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
+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.
 
 ---
 
 ## Post-Migration Checklist
 
 - [ ] v4 folders backed up to `v4-backup/`
-- [ ] v6 installed to `bmad/` folder
+- [ ] v6 installed to `_bmad/` folder
 - [ ] `workflow-init` run with correct project level selected
-- [ ] Agent customizations migrated to `bmad/_cfg/agents/` if needed
+- [ ] Agent customizations migrated to `_bmad/_config/agents/` if needed
 - [ ] IDE integration working (test by listing agents)
 - [ ] For active development: `sprint-planning` workflow executed
 
@@ -222,4 +224,4 @@ Since you are migrating an existing project from v4, its most likely **Level 3 o
 
 - **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
 - **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
-- **Docs**: Check `bmad/docs/` in your installation for IDE-specific instructions
+- **Docs**: Check `_bmad/docs/` in your installation for IDE-specific instructions

package/docs/web-bundles-gemini-gpt-guide.md

@@ -0,0 +1,21 @@
+# Using BMad Web Bundles in Gemini Gems & Custom GPTs
+
+## IMPORTANT NOTE
+
+The Web Bundling Feature is being rebuilt from the ground up, current bundles for v6 may be incomplete or missing functionality and are not optimized. This will be rectified very soon, with a more expansive guide.
+
+## What Are Web bundles
+
+Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file.
+
+## What Are Web Bundles?
+
+Web bundles are standalone XML files containing:
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- No external files required
+
+**Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally.

package/eslint.config.mjs

@@ -16,6 +16,26 @@ export default [
       'test/template-test-generator/**/*.md',
       'test/fixtures/**',
       'test/fixtures/**/*.yaml',
+      '_bmad/**',
+      '_bmad*/**',
+      // Docusaurus build artifacts
+      '.docusaurus/**',
+      'build/**',
+      'website/**',
+      // Gitignored patterns
+      'z*/**', // z-samples, z1, z2, etc.
+      '.claude/**',
+      '.codex/**',
+      '.github/chatmodes/**',
+      '.agent/**',
+      '.agentvibes/**',
+      '.kiro/**',
+      '.roo/**',
+      'test-project-install/**',
+      'sample-project/**',
+      'tools/template-test-generator/test-scenarios/**',
+      'src/modules/*/sub-modules/**',
+      '.bundler-temp/**',
     ],
   },
 
@@ -61,9 +81,9 @@ export default [
     },
   },
 
-  // CLI/CommonJS scripts under tools/** and test/**
+  // CLI scripts under tools/** and test/**
   {
-    files: ['tools/**/*.js', 'test/**/*.js'],
+    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
     rules: {
       // Allow CommonJS patterns for Node CLI scripts
       'unicorn/prefer-module': 'off',
@@ -90,6 +110,7 @@ export default [
       'no-useless-catch': 'off',
       'unicorn/prefer-number-properties': 'off',
       'no-unreachable': 'off',
+      'unicorn/text-encoding-identifier-case': 'off',
     },
   },
 

package/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.20",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -25,23 +25,27 @@
   },
   "scripts": {
     "bmad:install": "node tools/cli/bmad-cli.js install",
-    "bmad:status": "node tools/cli/bmad-cli.js status",
     "bundle": "node tools/cli/bundlers/bundle-web.js all",
+    "docs:build": "node tools/build-docs.js",
+    "docs:dev": "npm run docs:build && npm run docs:serve",
+    "docs:serve": "docusaurus start --config website/docusaurus.config.js --host localhost",
     "flatten": "node tools/flattener/main.js",
-    "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,md,yaml}\"",
-    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",
+    "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "install:bmad": "node tools/cli/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
     "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
-    "test": "node test/test-agent-schema.js",
-    "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js",
-    "validate:bundles": "node tools/validate-bundles.js",
+    "test": "npm run test:schemas && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+    "test:install": "node test/test-installation-components.js",
+    "test:schemas": "node test/test-agent-schema.js",
     "validate:schemas": "node tools/validate-agent-schema.js"
   },
   "lint-staged": {
@@ -53,8 +57,11 @@
       "eslint --fix",
       "npm run format:fix"
     ],
-    "*.{json,md}": [
+    "*.json": [
       "npm run format:fix"
+    ],
+    "*.md": [
+      "markdownlint-cli2"
     ]
   },
   "dependencies": {
@@ -73,10 +80,14 @@
     "ora": "^5.4.1",
     "semver": "^7.6.3",
     "wrap-ansi": "^7.0.0",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "yaml": "^2.7.0"
   },
   "devDependencies": {
+    "@docusaurus/core": "^3.6.0",
+    "@docusaurus/preset-classic": "^3.6.0",
     "@eslint/js": "^9.33.0",
+    "archiver": "^7.0.1",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
@@ -86,8 +97,12 @@
     "husky": "^9.1.7",
     "jest": "^30.0.4",
     "lint-staged": "^16.1.1",
+    "markdownlint-cli2": "^0.19.1",
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.19",
+    "prism-react-renderer": "^2.4.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "yaml-eslint-parser": "^1.2.3",
     "yaml-lint": "^1.7.0",
     "zod": "^4.1.12"

package/samples/sample-custom-modules/README.md

@@ -0,0 +1,11 @@
+# Sample Custom Modules
+
+These are quickly put together examples of both a stand alone somewhat cohesive module that shows agents with workflows and that interact with the core features, and another custom module that is comprised with unrelated agents and workflows that are meant to be picked and chosen from - (but currently will all be installed as a module)
+
+To try these out, download either or both folders to your local machine, and run the normal bmad installer, and when asked about custom local content, say yes, and give the path to one of these two folders. You can even install both with other regular modules to the same project.
+
+Note - a project is just a folder with \_bmad in the folder - this can be a software project, but it can also be any type of folder on your local computer - such as a markdown notebook, a folder of other files, or just a folder you maintain with useful agents prompts and utilities for any purpose.
+
+Please remember - these are not optimal or very good examples in their utility or quality control - but they do demonstrate the basics of creating custom content and modules to be able to install for yourself or share with others. This is the groundwork for making very complex modules also such as the full bmad method.
+
+Additionally, tooling will come soon to allow for bundling these to make them usable and sharable with anyone ont he web!

package/samples/sample-custom-modules/sample-unitary-module/README.md

@@ -0,0 +1,8 @@
+# Example Custom Content module
+
+This is a demonstration of custom stand along agents and workflows. By having this content all in a folder with a module.yaml file,
+these items can be installed with the standard bmad installer custom local content menu item.
+
+This is how you could also create and share other custom agents and workflows not tied to a specific module.
+
+The main distinction with this colelction is module.yaml includes type: unitary

package/samples/sample-custom-modules/sample-unitary-module/agents/commit-poet/commit-poet.agent.yaml

@@ -0,0 +1,129 @@
+agent:
+  metadata:
+    id: "_bmad/agents/commit-poet/commit-poet.md"
+    name: "Inkwell Von Comitizen"
+    title: "Commit Message Artisan"
+    icon: "📜"
+    type: simple
+
+  persona:
+    role: |
+      I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
+
+    identity: |
+      I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. I analyze diffs, understand context, and produce messages that will still make sense months from now.
+
+    communication_style: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
+
+    principles:
+      - Every commit tells a story - the message should capture the "why"
+      - Future developers will read this - make their lives easier
+      - Brevity and clarity work together, not against each other
+      - Consistency in format helps teams move faster
+
+  prompts:
+    - id: write-commit
+      content: |
+        <instructions>
+        I'll craft a commit message for your changes. Show me:
+        - The diff or changed files, OR
+        - A description of what you changed and why
+
+        I'll analyze the changes and produce a message in conventional commit format.
+        </instructions>
+
+        <process>
+        1. Understand the scope and nature of changes
+        2. Identify the primary intent (feature, fix, refactor, etc.)
+        3. Determine appropriate scope/module
+        4. Craft subject line (imperative mood, concise)
+        5. Add body explaining "why" if non-obvious
+        6. Note breaking changes or closed issues
+        </process>
+
+        Show me your changes and I'll craft the message.
+
+    - id: analyze-changes
+      content: |
+        <instructions>
+        - Let me examine your changes before we commit to words.
+        - I'll provide analysis to inform the best commit message approach.
+        - Diff all uncommited changes and understand what is being done.
+        - Ask user for clarifications or the what and why that is critical to a good commit message.
+        </instructions>
+
+        <analysis_output>
+        - **Classification**: Type of change (feature, fix, refactor, etc.)
+        - **Scope**: Which parts of codebase affected
+        - **Complexity**: Simple tweak vs architectural shift
+        - **Key points**: What MUST be mentioned
+        - **Suggested style**: Which commit format fits best
+        </analysis_output>
+
+        Share your diff or describe your changes.
+
+    - id: improve-message
+      content: |
+        <instructions>
+        I'll elevate an existing commit message. Share:
+        1. Your current message
+        2. Optionally: the actual changes for context
+        </instructions>
+
+        <improvement_process>
+        - Identify what's already working well
+        - Check clarity, completeness, and tone
+        - Ensure subject line follows conventions
+        - Verify body explains the "why"
+        - Suggest specific improvements with reasoning
+        </improvement_process>
+
+    - id: batch-commits
+      content: |
+        <instructions>
+        For multiple related commits, I'll help create a coherent sequence. Share your set of changes.
+        </instructions>
+
+        <batch_approach>
+        - Analyze how changes relate to each other
+        - Suggest logical ordering (tells clearest story)
+        - Craft each message with consistent voice
+        - Ensure they read as chapters, not fragments
+        - Cross-reference where appropriate
+        </batch_approach>
+
+        <example>
+        Good sequence:
+        1. refactor(auth): extract token validation logic
+        2. feat(auth): add refresh token support
+        3. test(auth): add integration tests for token refresh
+        </example>
+
+  menu:
+    - trigger: write
+      action: "#write-commit"
+      description: "Craft a commit message for your changes"
+
+    - trigger: analyze
+      action: "#analyze-changes"
+      description: "Analyze changes before writing the message"
+
+    - trigger: improve
+      action: "#improve-message"
+      description: "Improve an existing commit message"
+
+    - trigger: batch
+      action: "#batch-commits"
+      description: "Create cohesive messages for multiple commits"
+
+    - trigger: conventional
+      action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
+      description: "Specifically use conventional commit format"
+
+    - trigger: story
+      action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
+      description: "Write commit as a narrative story"
+
+    - trigger: haiku
+      action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
+      description: "Compose a haiku commit message"