Merge branch 'main' into rebrand-acronym

* fix(installer): remove double-escaping of quotes in CSV manifest pipeline

cleanForCSV() pre-escaped " to "" before storing in memory, then
escapeCsv() escaped again at CSV write time. After csv-parse round-trip
(which only un-escapes once), descriptions retained doubled quotes
instead of originals, corrupting generated output files.

Fix: remove the redundant quote escaping from cleanForCSV() since
escapeCsv() already handles CSV quoting correctly at write time.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(installer): use single quotes for description in Gemini workflow templates

Replace triple-quoted """{{description}}""" with single-quoted '{{description}}'
to avoid TOML escaping issues in Gemini workflow templates.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/bmad-os-audit-file-refs/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-audit-file-refs
+description: Audit BMAD source files for file-reference convention violations using parallel Haiku subagents. Use when users requests an "audit file references" for a skill, workflow or task.
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-changelog-social/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: bmad-os-changelog-social
-description: Generate social media announcements for Discord, Twitter, and LinkedIn from the latest changelog entry. Use when user asks to create release announcements, social posts, or share changelog updates. Reads CHANGELOG.md in current working directory. Reference examples/ for tone and format.
-disable-model-invocation: true
+description: Generate social media announcements for Discord, Twitter, and LinkedIn from the latest changelog entry. Use when user asks to 'create release announcement' or 'create social posts' or share changelog updates.
 ---
 
 # Changelog Social

.claude/skills/bmad-os-diataxis-style-fix/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: bmad-os-diataxis-style-fix
-description: Fixes documentation to comply with Diataxis framework and BMad Method style guide rules
-disable-model-invocation: true
+description: Fixes documentation to comply with Diataxis framework and BMad Method style guide rules. Use when user asks to check or fix style of files under the docs folder.
 ---
 
 Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-draft-changelog/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: bmad-os-draft-changelog
-description: Analyzes changes since last release and updates CHANGELOG.md ONLY. Does NOT trigger releases.
-disable-model-invocation: true
+description: "Analyzes changes since last release and updates CHANGELOG.md ONLY. Use when users requests 'update the changelog' or 'prepare changelog release notes'"
 ---
 
 Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-gh-triage/README.md

@@ -1,14 +0,0 @@
-# gh-triage
-
-Fetches all GitHub issues via gh CLI and uses AI agents to deeply analyze, cluster, and prioritize issues.
-
-## Usage
-
-Run from within any BMad Method repository to triage issues.
-
-## What It Does
-
-1. Fetches all open issues via `gh issue list`
-2. Splits issues into batches
-3. Launches parallel agents to analyze each batch
-4. Generates comprehensive triage report to `_bmad-output/triage-reports/`

.claude/skills/bmad-os-gh-triage/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: bmad-os-gh-triage
-description: Fetch all GitHub issues via gh CLI and use AI agents to deeply analyze, cluster, and prioritize issues
-license: MIT
-disable-model-invocation: true
-metadata:
-  author: bmad-code-org
-  version: "3.0.0"
-compatibility: Requires gh CLI, git repository, and BMad Method with Task tool support
+description: Analyze all github issues. Use when the user says 'triage the github issues' or 'analyze open github issues'.
 ---
 
 Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-release-module/README.md

@@ -1,24 +0,0 @@
-# release-module
-
-Automates the complete release process for npm modules.
-
-## Usage
-
-Run from project root or pass project path:
-```
-bmad-utility-skills:release-module
-```
-
-## Prerequisite
-
-First run `draft-changelog` to analyze changes and create a draft changelog.
-
-## What It Does
-
-1. Gets and confirms changelog entry
-2. Confirms version bump type (patch/minor/major)
-3. Updates CHANGELOG.md
-4. Bumps version with `npm version`
-5. Pushes git tag
-6. Publishes to npm
-7. Creates GitHub release

.claude/skills/bmad-os-release-module/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: bmad-os-release-module
-description: Automates the complete release process for npm modules - version bump, changelog, git tag, npm publish, GitHub release
-disable-model-invocation: true
+description: Perform requested version bump, git tag, npm publish, GitHub release. Use when user requests 'perform a release' only.
 ---
 
 Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-review-pr/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-os-review-pr
+description: Adversarial PR review tool (Raven's Verdict). Cynical deep review transformed into professional engineering findings. Use when user asks to 'review a PR' and provides a PR url or id.
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-review-pr/prompts/instructions.md

@@ -2,8 +2,7 @@
 
 A cynical adversarial review, transformed into cold engineering professionalism.
 
-<orientation>
-CRITICAL: Sandboxed Execution Rules
+## CRITICAL: Sandboxed Execution Rules
 
 Before proceeding, you MUST verify:
 
@@ -14,9 +13,6 @@ Before proceeding, you MUST verify:
 
 **If no explicit PR number/URL was provided, STOP immediately and ask:**
 "What PR number or URL should I review?"
-</orientation>
-
-<preflight-checks>
 
 ## Preflight Checks
 
@@ -97,9 +93,7 @@ gh pr diff {PR_NUMBER} [--repo {REPO}] --name-only | grep -E '\.(png|jpg|jpeg|gi
 
 Store list of binary files to skip. Note them in final output.
 
-</preflight-checks>
-
-<adversarial-review>
+## Adversarial Review
 
 ### 1.1 Run Cynical Review
 
@@ -130,9 +124,7 @@ Likely tag:
 - Add `[likely]` to findings with high confidence, e.g. with direct evidence
 - Sort findings by severity (Critical → Moderate → Minor), not by confidence
 
-</adversarial-review>
-
-<tone-transformation>
+## Tone Transformation
 
 **Transform the cynical output into cold engineering professionalism.**
 
@@ -177,9 +169,8 @@ Output format after transformation:
 _Review generated by Raven's Verdict. LLM-produced analysis - findings may be incorrect or lack context. Verify before acting._
 ```
 
-</tone-transformation>
+## Post Review
 
-<post-review>
 ### 3.1 Preview
 
 Display the complete transformed review to the user.
@@ -231,12 +222,10 @@ Do NOT use heredocs or `echo` - Markdown code blocks will break shell parsing. U
 
 Keep the temp file and inform user of location.
 
-</post-review>
+## Notes
 
-<notes>
 - The "cynical asshole" phase is internal only - never posted
 - Tone transform MUST happen before any external output
 - When in doubt, ask the user - never assume
 - If you're unsure about severity, err toward higher severity
 - If you're unsure about confidence, be honest and use Medium or Low
-</notes>

.gitignore

@@ -37,6 +37,7 @@ CLAUDE.local.md
 .serena/
 .claude/settings.local.json
 .junie/
+.agents/
 
 z*/
 

CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [6.0.3]
+
+### 🐛 Bug Fixes
+
+* Fix workflow descriptions to use proper quotes so they format better in skill conversion and don't break yaml front matter
+
+---
+
+## [6.0.2]
+
+### 🎁 Features
+
+* Add CodeBuddy platform support with installer configuration (#1483)
+* Add LLM audit prompt for file reference conventions - new audit tool using parallel subagents (#1720)
+* Migrate Codex installer from `.codex/prompts` to `.agents/skills` format to align with Codex CLI changes (#1729)
+* Convert review-pr and audit-file-refs tools to proper bmad-os skills with slash commands `/bmad-os-review-pr` and `/bmad-os-audit-file-refs` (#1732)
+
+### 🐛 Bug Fixes
+
+* Fix 24 broken step references in create-architecture workflow after directory rename (#1734)
+* Fix step file path references in check-implementation-readiness workflow (#1709, #1716)
+* Fix 3 broken file references and enable strict file reference validation in CI (#1717)
+* Fix Rovo Dev integration with custom installer that generates prompts.yml manifest (#1701)
+* Fix 104 relative step file references to use standardized `{project-root}/_bmad/` paths across 68 files (#1722)
+* Fix code fence imbalance in step-03-starter.md that caused rendering issues (#1724)
+* Remove Windsurf from recommended/preferred IDEs list (#1727)
+* Fix default Codex install location from global to project for better defaults (#1698)
+* Add npx cache workaround to Quick Start for stale beta versions (#1685)
+* Add language instructions to replace placeholder text in Research overview (#1703)
+* Ignore `.junie/` IDE integration folder in git and prettier configs (#1719)
+
+### ♻️ Refactoring
+
+* Update open source tool skills structure for future plugin migration
+* Standardize all workflow descriptions for skill generation with concise format and explicit trigger phrases
+* Remove `disable-model-invocation` flag from all IDE installer templates to enable workflow skill calls
+
+### 📚 Documentation
+
+* Elevate `bmad-help` as primary on-ramp across all documentation
+* Update workflow names with `bmad-bmm-` prefix and standardize table formatting
+* Clarify phase routing and catalog path in help task
+
+---
+
 ## [6.0.0]
 
 V6 Stable Release! The End of Beta!

README.md

@@ -22,6 +22,16 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 
 [Learn more at **docs.bmad-method.org**](http://docs.bmad-method.org)
 
+---
+
+## 🚀 What's Next for BMad?
+
+**V6 is here and we're just getting started!** The BMad Method is evolving rapidly with optimizations including Cross Platform Agent Team and Sub Agent inclusion, Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works.
+
+**[📍 Check out the complete Roadmap →](http://docs.bmad-method.org/roadmap/)**
+
+---
+
 ## Quick Start
 
 **Prerequisites**: [Node.js](https://nodejs.org) v20+

docs/index.md

@@ -7,6 +7,10 @@ The BMad Method (**B**uild **M**ore **A**rchitect **D**reams) is an AI-driven de
 
 If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
 
+:::note[🚀 V6 is Here and We're Just Getting Started!]
+Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works. **[Check out the Roadmap →](/roadmap/)**
+:::
+
 ## New Here? Start with a Tutorial
 
 The fastest way to understand BMad is to try it.

docs/roadmap.mdx

@@ -0,0 +1,136 @@
+---
+title: Roadmap
+description: What's next for BMad - Features, improvements, and community contributions
+---
+
+# The BMad Method: Public Roadmap
+
+The BMad Method, BMad Method Module (BMM), and BMad Builder (BMB) are evolving. Here's what we're working on and what's coming next.
+
+<div class="roadmap-container">
+
+  <h2 class="roadmap-section-title">In Progress</h2>
+
+  <div class="roadmap-future">
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🧩</span>
+      <h4>Universal Skills Architecture</h4>
+      <p>One skill, any platform. Write once, run everywhere.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🏗️</span>
+      <h4>BMad Builder v1</h4>
+      <p>Craft production-ready AI agents and workflows with evals, teams, and graceful degradation built in.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🧠</span>
+      <h4>Project Context System</h4>
+      <p>Your AI actually understands your project. Framework-aware context that evolves with your codebase.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">📦</span>
+      <h4>Centralized Skills</h4>
+      <p>Install once, use everywhere. Share skills across projects without the file clutter.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🔄</span>
+      <h4>Adaptive Skills</h4>
+      <p>Skills that know your tool. Optimized variants for Claude, Codex, Kimi, and OpenCode, plus many more.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">📝</span>
+      <h4>BMad Team Pros Blog</h4>
+      <p>Guides, articles and insights from the team. Launching soon.</p>
+    </div>
+  </div>
+
+  <h2 class="roadmap-section-title">Getting Started</h2>
+
+  <div class="roadmap-future">
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🏪</span>
+      <h4>Skill Marketplace</h4>
+      <p>Discover, install, and update community-built skills. One curl command away from superpowers.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🎨</span>
+      <h4>Workflow Customization</h4>
+      <p>Make it yours. Integrate Jira, Linear, custom outputs your workflow, your rules.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🚀</span>
+      <h4>Phase 1-3 Optimization</h4>
+      <p>Lightning-fast planning with sub-agent context gathering. YOLO mode meets guided excellence.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🌐</span>
+      <h4>Enterprise Ready</h4>
+      <p>SSO, audit logs, team workspaces. All the boring stuff that makes companies say yes.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">💎</span>
+      <h4>Community Modules Explosion</h4>
+      <p>Entertainment, security, therapy, roleplay and much more. Expand the BMad Method platform.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">⚡</span>
+      <h4>Dev Loop Automation</h4>
+      <p>Optional autopilot for development. Let AI handle the flow while keeping quality sky-high.</p>
+    </div>
+  </div>
+
+  <h2 class="roadmap-section-title">Community and Team</h2>
+
+  <div class="roadmap-future">
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🎙️</span>
+      <h4>The BMad Method Podcast</h4>
+      <p>Conversations about AI-native development. Launching March 1, 2026!</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🎓</span>
+      <h4>The BMad Method Master Class</h4>
+      <p>Go from user to expert. Deep dives into every phase, every workflow, every secret.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🏗️</span>
+      <h4>The BMad Builder Master Class</h4>
+      <p>Build your own agents. Advanced techniques for when you are ready to create, not just use.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">⚡</span>
+      <h4>BMad Prototype First</h4>
+      <p>Idea to working prototype in one session. Craft your dream app like a work of art.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🌴</span>
+      <h4>BMad BALM!</h4>
+      <p>Life management for the AI-native. Tasks, habits, goals your AI copilot for everything.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🖥️</span>
+      <h4>Official UI</h4>
+      <p>A beautiful interface for the entire BMad ecosystem. CLI power, GUI polish.</p>
+    </div>
+    <div class="roadmap-future-card">
+      <span class="roadmap-emoji">🔒</span>
+      <h4>BMad in a Box</h4>
+      <p>Self-hosted, air-gapped, enterprise-grade. Your AI assistant, your infrastructure, your control.</p>
+    </div>
+  </div>
+
+  <div style="text-align: center; margin-top: 3rem; padding: 2rem; background: var(--color-bg-card); border-radius: 12px; border: 1px solid var(--color-border);">
+    <h3 style="margin: 0 0 1rem;">Want to Contribute?</h3>
+    <p style="color: var(--slate-color-400); margin: 0;">
+      This is only a partial list of what's planned. The BMad Open Source team welcomes contributors!{" "}<br />
+      <a href="https://github.com/bmad-code-org/BMAD-METHOD" style="color: var(--color-in-progress);">Join us on GitHub</a> to help shape the future of AI-driven development.
+    </p>
+    <p style="color: var(--slate-color-400); margin: 1.5rem 0 0;">
+      Love what we're building? We appreciate both one-time and monthly{" "}<a href="https://buymeacoffee.com/bmad" style="color: var(--color-in-progress);">support</a>.
+    </p>
+    <p style="color: var(--slate-color-400); margin: 1rem 0 0;">
+      For corporate sponsorship, partnership inquiries, speaking engagements, training, or media enquiries:{" "}
+      <a href="mailto:contact@bmadcode.com" style="color: var(--color-in-progress);">contact@bmadcode.com</a>
+    </p>
+  </div>
+</div>

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.1",
+  "version": "6.0.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.1",
+      "version": "6.0.3",
       "license": "MIT",
       "dependencies": {
         "@clack/core": "^1.0.0",

package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.1",
-  "description": "Build More Architect Dreams — AI-driven agile development framework",
+  "version": "6.0.3",
+  "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
     "ai",

src/bmm/agents/qa.agent.yaml

@@ -29,7 +29,7 @@ agent:
 
   menu:
     - trigger: QA or fuzzy match on qa-automate
-      workflow: "{project-root}/_bmad/bmm/workflows/qa/automate/workflow.yaml"
+      workflow: "{project-root}/_bmad/bmm/workflows/qa-generate-e2e-tests/workflow.yaml"
       description: "[QA] Automate - Generate tests for existing features (simplified)"
 
   prompts:

src/bmm/module-help.csv

@@ -27,5 +27,5 @@ bmm,4-implementation,Validate Story,VS,35,_bmad/bmm/workflows/4-implementation/c
 bmm,4-implementation,Create Story,CS,30,_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml,bmad-bmm-create-story,true,sm,Create Mode,"Story cycle start: Prepare first found story in the sprint plan that is next, or if the command is run with a specific epic and story designation with context. Once complete, then VS then DS then CR then back to DS if needed or next CS or ER",implementation_artifacts,story,
 bmm,4-implementation,Dev Story,DS,40,_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml,bmad-bmm-dev-story,true,dev,Create Mode,"Story cycle: Execute story implementation tasks and tests then CR then back to DS if fixes needed",,,
 bmm,4-implementation,Code Review,CR,50,_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml,bmad-bmm-code-review,false,dev,Create Mode,"Story cycle: If issues back to DS if approved then next CS or ER if epic complete",,,
-bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa/automate/workflow.yaml,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite",
+bmm,4-implementation,QA Automation Test,QA,45,_bmad/bmm/workflows/qa-generate-e2e-tests/workflow.yaml,bmad-bmm-qa-automate,false,qa,Create Mode,"Generate automated API and E2E tests for implemented code using the project's existing test framework (detects existing well known in use test frameworks). Use after implementation to add test coverage. NOT for code review or story validation - use CR for that.",implementation_artifacts,"test suite",
 bmm,4-implementation,Retrospective,ER,60,_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml,bmad-bmm-retrospective,false,sm,Create Mode,"Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC",implementation_artifacts,retrospective,

src/bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md

@@ -128,7 +128,7 @@ Recap that the brief captures everything needed to guide subsequent product deve
 
 ### 5. Suggest next steps
 
-Product Brief complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Validate PRD`.
+Product Brief complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 ---
 

src/bmm/workflows/1-analysis/create-product-brief/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: create-product-brief
-description: Create comprehensive product briefs through collaborative step-by-step discovery as creative Business Analyst working with the user as peers.
+description: 'Create product brief through collaborative discovery. Use when the user says "lets create a product brief" or "help me create a project brief"'
 ---
 
 # Product Brief Workflow

src/bmm/workflows/1-analysis/research/workflow-domain-research.md

@@ -1,6 +1,6 @@
 ---
 name: domain-research
-description: Conduct domain research covering industry analysis, regulations, technology trends, and ecosystem dynamics using current web data and verified sources.
+description: 'Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]"'
 ---
 
 # Domain Research Workflow

src/bmm/workflows/1-analysis/research/workflow-market-research.md

@@ -1,6 +1,6 @@
 ---
 name: market-research
-description: Conduct market research covering market size, growth, competition, and customer insights using current web data and verified sources.
+description: 'Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".'
 ---
 
 # Market Research Workflow

src/bmm/workflows/1-analysis/research/workflow-technical-research.md

@@ -1,6 +1,6 @@
 ---
 name: technical-research
-description: Conduct technical research covering technology evaluation, architecture decisions, and implementation approaches using current web data and verified sources.
+description: 'Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".'
 ---
 
 # Technical Research Workflow

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-12-complete.md

@@ -87,7 +87,7 @@ Offer validation workflows to ensure PRD is ready for implementation:
 
 ### 4. Suggest Next Workflows
 
-PRD complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create PRD`.
+PRD complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 ### 5. Final Completion Confirmation
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-13-report-complete.md

@@ -197,7 +197,7 @@ Display:
 - **IF X (Exit):**
   - Display: "**Validation Report Saved:** {validationReportPath}"
   - Display: "**Summary:** {overall status} - {recommendation}"
-  - PRD Validation complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Validate PRD`.
+  - PRD Validation complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 - **IF Any other:** Help user, then redisplay menu
 

src/bmm/workflows/2-plan-workflows/create-prd/workflow-create-prd.md

@@ -1,6 +1,6 @@
 ---
 name: create-prd
-description: Create a comprehensive PRD (Product Requirements Document) through structured workflow facilitation
+description: 'Create a PRD from scratch. Use when the user says "lets create a product requirements document" or "I want to create a new PRD"'
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 nextStep: './steps-c/step-01-init.md'
 ---

src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md

@@ -1,6 +1,6 @@
 ---
 name: edit-prd
-description: Edit and improve an existing PRD - enhance clarity, completeness, and quality
+description: 'Edit an existing PRD. Use when the user says "edit this PRD".'
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 editWorkflow: './steps-e/step-e-01-discovery.md'
 ---

src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md

@@ -1,6 +1,6 @@
 ---
 name: validate-prd
-description: Validate an existing PRD against BMAD standards - comprehensive review for completeness, clarity, and quality
+description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"'
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 validateWorkflow: './steps-v/step-v-01-discovery.md'
 ---

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md

@@ -82,7 +82,7 @@ Update the main workflow status file:
 
 ### 3. Suggest Next Steps
 
-UX Design complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create UX`.
+UX Design complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 ### 5. Final Completion Confirmation
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-ux-design
-description: Work with a peer UX Design expert to plan your applications UX patterns, look and feel.
+description: 'Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
 ---
 
 # Create UX Design Workflow

src/bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md

@@ -109,7 +109,7 @@ The assessment found [number] issues requiring attention. Review the detailed re
 
 The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider.
 
-Implementation Readiness complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `implementation readiness`.
+Implementation Readiness complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 ---
 

src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: check-implementation-readiness
-description: 'Critical validation workflow that assesses PRD, Architecture, and Epics & Stories for completeness and alignment before implementation. Uses adversarial review approach to find gaps and issues.'
+description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
 ---
 
 # Implementation Readiness

src/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md

@@ -44,7 +44,7 @@ First, check if the output document already exists:
 
 If the document exists and has frontmatter with `stepsCompleted`:
 
-- **STOP here** and load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01b-continue.md` immediately
+- **STOP here** and load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md` immediately
 - Do not proceed with any initialization tasks
 - Let step-01b handle the continuation logic
 
@@ -148,6 +148,6 @@ Ready to begin architectural decision making. Do you have any other documents yo
 
 ## NEXT STEP:
 
-After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
+After user selects [C] to continue, only after ensuring all the template output has been created, then load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md` to analyze the project context and begin architectural decision making.
 
 Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md

@@ -85,7 +85,7 @@ Show the user their current progress:
 
 - Identify the next step based on `stepsCompleted`
 - Load the appropriate step file to continue
-- Example: If `stepsCompleted: [1, 2, 3]`, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
+- Example: If `stepsCompleted: [1, 2, 3]`, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
 
 #### If 'C' (Continue to next logical step):
 
@@ -103,7 +103,7 @@ Show the user their current progress:
 #### If 'X' (Start over):
 
 - Confirm: "This will delete all existing architectural decisions. Are you sure? (y/n)"
-- If confirmed: Delete existing document and read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md`
+- If confirmed: Delete existing document and read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md`
 - If not confirmed: Return to continuation menu
 
 ### 4. Navigate to Selected Step
@@ -162,12 +162,12 @@ After user makes choice:
 After user selects their continuation option, load the appropriate step file based on their choice. The step file will handle the detailed work from that point forward.
 
 Valid step files to load:
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-02-context.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md`
-- `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md`
+- `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md`
 
 Remember: The goal is smooth, transparent resumption that respects the work already done while giving the user control over how to proceed.

src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md

@@ -188,7 +188,7 @@ Show the generated content and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -219,6 +219,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-03-starter.md` to evaluate starter template options.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md` to evaluate starter template options.
 
 Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md

@@ -294,7 +294,7 @@ Show the generated content and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2, 3]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -324,6 +324,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-04-decisions.md` to begin making specific architectural decisions.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md` to begin making specific architectural decisions.
 
 Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md

@@ -282,7 +282,7 @@ Show the generated decisions content and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -313,6 +313,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-05-patterns.md` to define implementation patterns that ensure consistency across AI agents.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md` to define implementation patterns that ensure consistency across AI agents.
 
 Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md

@@ -323,7 +323,7 @@ Show the generated patterns content and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -354,6 +354,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-06-structure.md` to define the complete project structure.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md` to define the complete project structure.
 
 Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md

@@ -343,7 +343,7 @@ Show the generated project structure content and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -374,6 +374,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-07-validation.md` to validate architectural coherence and completeness.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md` to validate architectural coherence and completeness.
 
 Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md

@@ -323,7 +323,7 @@ Show the validation results and present choices:
 
 - Append the final content to `{planning_artifacts}/architecture.md`
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]`
-- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md`
+- Load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -354,6 +354,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-08-complete.md` to complete the workflow and provide implementation guidance.
+After user selects 'C' and content is saved to document, load `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md` to complete the workflow and provide implementation guidance.
 
 Remember: Do NOT proceed to step-08 until user explicitly selects 'C' from the A/P/C menu and content is saved!

src/bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md

@@ -41,7 +41,7 @@ completedAt: '{{current_date}}'
 
 ### 3. Next Steps Guidance
 
-Architecture complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create Architecture`.
+Architecture complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 Upon Completion of task output: offer to answer any questions about the Architecture Document.
 

src/bmm/workflows/3-solutioning/create-architecture/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: create-architecture
-description: Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts.
+description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
 ---
 
 # Architecture Workflow
@@ -44,6 +44,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ## EXECUTION
 
-Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/architecture/steps/step-01-init.md` to begin the workflow.
+Read fully and follow: `{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md` to begin the workflow.
 
 **Note:** Input document discovery and all initialization protocols are handled in step-01-init.md.

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md

@@ -144,6 +144,6 @@ If all validations pass:
 
 When C is selected, the workflow is complete and the epics.md is ready for development.
 
-Epics and Stories complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md` with argument `Create Epics and Stories`.
+Epics and Stories complete. Read fully and follow: `{project-root}/_bmad/core/tasks/help.md`
 
 Upon Completion of task output: offer to answer any questions about the Epics and Stories.

src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: create-epics-and-stories
-description: 'Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams.'
+description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"'
 ---
 
 # Create Epics and Stories

src/bmm/workflows/4-implementation/code-review/workflow.yaml

@@ -1,7 +1,6 @@
 # Review Story Workflow
 name: code-review
-description: "Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval."
-author: "BMad"
+description: 'Perform adversarial code review finding specific issues. Use when the user says "run code review" or "review this code"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"

src/bmm/workflows/4-implementation/correct-course/workflow.yaml

@@ -1,7 +1,6 @@
 # Correct Course - Sprint Change Management Workflow
 name: "correct-course"
-description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
-author: "BMad Method"
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
 
 config_source: "{project-root}/_bmad/bmm/config.yaml"
 user_name: "{config_source}:user_name"

src/bmm/workflows/4-implementation/create-story/workflow.yaml

@@ -1,6 +1,5 @@
 name: create-story
-description: "Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking"
-author: "BMad"
+description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"

src/bmm/workflows/4-implementation/dev-story/workflow.yaml

@@ -1,6 +1,5 @@
 name: dev-story
-description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
-author: "BMad"
+description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"

src/bmm/workflows/4-implementation/retrospective/workflow.yaml

@@ -1,7 +1,6 @@
 # Retrospective - Epic Completion Review Workflow
 name: "retrospective"
-description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic"
-author: "BMad"
+description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"'
 
 config_source: "{project-root}/_bmad/bmm/config.yaml"
 user_name: "{config_source}:user_name"

src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -1,5 +1,5 @@
 name: sprint-planning
-description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
+description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
 author: "BMad"
 
 # Critical variables from config

src/bmm/workflows/4-implementation/sprint-status/workflow.yaml

@@ -1,6 +1,6 @@
 # Sprint Status - Implementation Tracker
 name: sprint-status
-description: "Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow."
+description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"'
 author: "BMad"
 
 # Critical variables from config

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: quick-dev
-description: 'Flexible development - execute tech-specs OR direct instructions with optional planning.'
+description: 'Implement a Quick Tech Spec for small changes or features. Use when the user provides a quick tech spec and says "implement this quick spec" or "proceed with implementation of [quick tech spec]"'
 ---
 
 # Quick Dev Workflow

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: quick-spec
-description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.
+description: 'Very quick process to create implementation-ready quick specs for small changes or features. Use when the user says "create a quick spec" or "generate a quick tech spec"'
 main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 # Checkpoint handler paths

src/bmm/workflows/document-project/workflow.yaml

@@ -1,7 +1,7 @@
 # Document Project Workflow Configuration
 name: "document-project"
 version: "1.2.0"
-description: "Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development"
+description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
 author: "BMad"
 
 # Critical variables

src/bmm/workflows/generate-project-context/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: generate-project-context
-description: Creates a concise project-context.md file with critical rules and patterns that AI agents must follow when implementing code. Optimized for LLM context efficiency.
+description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
 ---
 
 # Generate Project Context Workflow

src/bmm/workflows/qa-generate-e2e-tests/workflow.yaml

@@ -1,7 +1,5 @@
-# Quinn QA workflow: Automate
-name: qa-automate
-description: "Generate tests quickly for existing features using standard test patterns"
-author: "BMad"
+name: qa-generate-e2e-tests
+description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/bmm/config.yaml"
@@ -12,7 +10,7 @@ document_output_language: "{config_source}:document_output_language"
 date: system-generated
 
 # Workflow components
-installed_path: "{project-root}/_bmad/bmm/workflows/qa/automate"
+installed_path: "{project-root}/_bmad/bmm/workflows/qa-generate-e2e-tests"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 template: false

src/core/tasks/editorial-review-prose.xml

@@ -1,6 +1,6 @@
 <task id="_bmad/core/tasks/editorial-review-prose.xml"
   name="Editorial Review - Prose"
-  description="Clinical copy-editor that reviews text for communication issues">
+  description="Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose">
 
   <objective>Review text for communication issues that impede comprehension and output suggested fixes in a three-column table</objective>
 

src/core/tasks/editorial-review-structure.xml

@@ -3,8 +3,7 @@
   but no context except the content to review -->
 <task id="_bmad/core/tasks/editorial-review-structure.xml"
   name="Editorial Review - Structure"
-  description="Structural editor that proposes cuts, reorganization,
-    and simplification while preserving comprehension">
+  description="Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure">
   <objective>Review document structure and propose substantive changes
     to improve clarity and flow-run this BEFORE copy editing</objective>
   <inputs>

src/core/tasks/help.md

@@ -1,6 +1,6 @@
 ---
 name: help
-description: Get unstuck by showing what workflow steps come next or answering questions about what to do
+description: "Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now"
 ---
 
 # Task: BMAD Help

src/core/tasks/index-docs.xml

@@ -1,5 +1,5 @@
 <task id="_bmad/core/tasks/index-docs" name="Index Docs"
-  description="Generates or updates an index.md of all documents in the specified directory">
+  description="Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder">
   <llm critical="true">
     <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
     <i>DO NOT skip steps or change the sequence</i>

src/core/tasks/review-adversarial-general.xml

@@ -1,7 +1,8 @@
 <!-- if possible, run this in a separate subagent or process with read access to the project, 
   but no context except the content to review -->
 
-<task id="_bmad/core/tasks/review-adversarial-general.xml" name="Adversarial Review (General)">
+<task id="_bmad/core/tasks/review-adversarial-general.xml" name="Adversarial Review (General)"
+  description="Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something">
   <objective>Cynically review content and produce findings</objective>
 
   <inputs>

src/core/tasks/shard-doc.xml

@@ -1,5 +1,5 @@
 <task id="_bmad/core/tasks/shard-doc" name="Shard Document"
-  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections">
+  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document">
   <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
 
   <llm critical="true">

src/core/workflows/advanced-elicitation/workflow.xml

@@ -1,4 +1,5 @@
 <task id="_bmad/core/workflows/advanced-elicitation/workflow.xml" name="Advanced Elicitation"
+  description="Push the LLM to reconsider refine and improve its recent output. Use when the user asks for advanced elicitation"
   methods="{project-root}/_bmad/core/workflows/advanced-elicitation/methods.csv"
   agent-party="{project-root}/_bmad/_config/agent-manifest.csv">
   <llm critical="true">

src/core/workflows/brainstorming/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says "help me brainstorm" or "help me ideate".'
 context_file: '' # Optional context file path for project-specific guidance
 ---
 

src/core/workflows/party-mode/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: party-mode
-description: Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests "party mode" only.'
 ---
 
 # Party Mode Workflow

test/test-installation-components.js

@@ -173,7 +173,7 @@ async function runTests() {
 
       assert(compiled.includes('QA Engineer'), 'QA agent compilation includes agent title');
 
-      assert(compiled.includes('qa/automate'), 'QA agent menu includes automate workflow');
+      assert(compiled.includes('qa-generate-e2e-tests'), 'QA agent menu includes automate workflow');
 
       // Cleanup
       await fs.remove(tempOutput);

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

@@ -24,16 +24,14 @@ class ManifestGenerator {
   }
 
   /**
-   * Clean text for CSV output by normalizing whitespace and escaping quotes
+   * Clean text for CSV output by normalizing whitespace.
+   * Note: Quote escaping is handled by escapeCsv() at write time.
    * @param {string} text - Text to clean
-   * @returns {string} Cleaned text safe for CSV
+   * @returns {string} Cleaned text
    */
   cleanForCSV(text) {
     if (!text) return '';
-    return text
-      .trim()
-      .replaceAll(/\s+/g, ' ') // Normalize all whitespace (including newlines) to single space
-      .replaceAll('"', '""'); // Escape quotes for CSV
+    return text.trim().replaceAll(/\s+/g, ' '); // Normalize all whitespace (including newlines) to single space
   }
 
   /**

tools/cli/installers/lib/ide/_config-driven.js

@@ -353,7 +353,6 @@ You must fully embody this agent's persona and follow all activation instruction
     return `---
 name: '{{name}}'
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 # {{name}}

tools/cli/installers/lib/ide/codex.js

@@ -1,6 +1,7 @@
 const path = require('node:path');
-const fs = require('fs-extra');
 const os = require('node:os');
+const fs = require('fs-extra');
+const yaml = require('yaml');
 const { BaseIdeSetup } = require('./_base-ide');
 const { WorkflowCommandGenerator } = require('./shared/workflow-command-generator');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
@@ -17,57 +18,6 @@ class CodexSetup extends BaseIdeSetup {
     super('codex', 'Codex', false);
   }
 
-  /**
-   * Collect configuration choices before installation
-   * @param {Object} options - Configuration options
-   * @returns {Object} Collected configuration
-   */
-  async collectConfiguration(options = {}) {
-    // Non-interactive mode: use default (project) - recommended for real work
-    if (options.skipPrompts) {
-      return { installLocation: options.codexLocation || 'project' };
-    }
-
-    let confirmed = false;
-    let installLocation = 'global';
-
-    while (!confirmed) {
-      installLocation = await prompts.select({
-        message: 'Where would you like to install Codex CLI prompts?',
-        choices: [
-          {
-            name: 'Global - Simple for single project ' + '(~/.codex/prompts, but references THIS project only)',
-            value: 'global',
-          },
-          {
-            name: `Project-specific - Recommended for real work (requires CODEX_HOME=<project-dir>${path.sep}.codex)`,
-            value: 'project',
-          },
-        ],
-        default: 'global',
-      });
-
-      // Show brief confirmation hint (detailed instructions available via verbose)
-      if (installLocation === 'project') {
-        await prompts.log.info('Prompts installed to: <project>/.codex/prompts (requires CODEX_HOME)');
-      } else {
-        await prompts.log.info('Prompts installed to: ~/.codex/prompts');
-      }
-
-      // Confirm the choice
-      confirmed = await prompts.confirm({
-        message: 'Proceed with this installation option?',
-        default: true,
-      });
-
-      if (!confirmed) {
-        await prompts.log.warn("Let's choose a different installation option.");
-      }
-    }
-
-    return { installLocation };
-  }
-
   /**
    * Setup Codex configuration
    * @param {string} projectDir - Project directory
@@ -80,20 +30,25 @@ class CodexSetup extends BaseIdeSetup {
     // Always use CLI mode
     const mode = 'cli';
 
-    // Get installation location from pre-collected config or default to global
-    const installLocation = options.preCollectedConfig?.installLocation || 'global';
-
     const { artifacts, counts } = await this.collectClaudeArtifacts(projectDir, bmadDir, options);
 
-    const destDir = this.getCodexPromptDir(projectDir, installLocation);
-    await fs.ensureDir(destDir);
-    await this.clearOldBmadFiles(destDir, options);
+    // Clean up old .codex/prompts locations (both global and project)
+    const oldGlobalDir = this.getOldCodexPromptDir(null, 'global');
+    await this.clearOldBmadFiles(oldGlobalDir, options);
+    const oldProjectDir = this.getOldCodexPromptDir(projectDir, 'project');
+    await this.clearOldBmadFiles(oldProjectDir, options);
 
-    // Collect artifacts and write using underscore format
+    // Install to .agents/skills
+    const destDir = this.getCodexSkillsDir(projectDir);
+    await fs.ensureDir(destDir);
+    await this.clearOldBmadSkills(destDir, options);
+
+    // Collect and write agent skills
     const agentGen = new AgentCommandGenerator(this.bmadFolderName);
     const { artifacts: agentArtifacts } = await agentGen.collectAgentArtifacts(bmadDir, options.selectedModules || []);
-    const agentCount = await agentGen.writeDashArtifacts(destDir, agentArtifacts);
+    const agentCount = await this.writeSkillArtifacts(destDir, agentArtifacts, 'agent-launcher');
 
+    // Collect and write task skills
     const tasks = await getTasksFromBmad(bmadDir, options.selectedModules || []);
     const taskArtifacts = [];
     for (const task of tasks) {
@@ -117,19 +72,23 @@ class CodexSetup extends BaseIdeSetup {
       });
     }
 
+    const ttGen = new TaskToolCommandGenerator(this.bmadFolderName);
+    const taskSkillArtifacts = taskArtifacts.map((artifact) => ({
+      ...artifact,
+      content: ttGen.generateCommandContent(artifact, artifact.type),
+    }));
+    const tasksWritten = await this.writeSkillArtifacts(destDir, taskSkillArtifacts, 'task');
+
+    // Collect and write workflow skills
     const workflowGenerator = new WorkflowCommandGenerator(this.bmadFolderName);
     const { artifacts: workflowArtifacts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir);
-    const workflowCount = await workflowGenerator.writeDashArtifacts(destDir, workflowArtifacts);
-
-    // Also write tasks using underscore format
-    const ttGen = new TaskToolCommandGenerator(this.bmadFolderName);
-    const tasksWritten = await ttGen.writeDashArtifacts(destDir, taskArtifacts);
+    const workflowCount = await this.writeSkillArtifacts(destDir, workflowArtifacts, 'workflow-command');
 
     const written = agentCount + workflowCount + tasksWritten;
 
     if (!options.silent) {
       await prompts.log.success(
-        `${this.name} configured: ${counts.agents} agents, ${counts.workflows} workflows, ${counts.tasks} tasks, ${written} files → ${destDir}`,
+        `${this.name} configured: ${counts.agents} agents, ${counts.workflows} workflows, ${counts.tasks} tasks, ${written} skills → ${destDir}`,
       );
     }
 
@@ -140,35 +99,18 @@ class CodexSetup extends BaseIdeSetup {
       counts,
       destination: destDir,
       written,
-      installLocation,
     };
   }
 
   /**
-   * Detect Codex installation by checking for BMAD prompt exports
+   * Detect Codex installation by checking for BMAD skills
    */
   async detect(projectDir) {
-    // Check both global and project-specific locations
-    const globalDir = this.getCodexPromptDir(null, 'global');
-    const projectDir_local = projectDir || process.cwd();
-    const projectSpecificDir = this.getCodexPromptDir(projectDir_local, 'project');
+    const dir = this.getCodexSkillsDir(projectDir || process.cwd());
 
-    // Check global location
-    if (await fs.pathExists(globalDir)) {
+    if (await fs.pathExists(dir)) {
       try {
-        const entries = await fs.readdir(globalDir);
-        if (entries && entries.some((entry) => entry && typeof entry === 'string' && entry.startsWith('bmad'))) {
-          return true;
-        }
-      } catch {
-        // Ignore errors
-      }
-    }
-
-    // Check project-specific location
-    if (await fs.pathExists(projectSpecificDir)) {
-      try {
-        const entries = await fs.readdir(projectSpecificDir);
+        const entries = await fs.readdir(dir);
         if (entries && entries.some((entry) => entry && typeof entry === 'string' && entry.startsWith('bmad'))) {
           return true;
         }
@@ -240,26 +182,138 @@ class CodexSetup extends BaseIdeSetup {
     };
   }
 
-  getCodexPromptDir(projectDir = null, location = 'global') {
+  getCodexSkillsDir(projectDir) {
+    if (!projectDir) {
+      throw new Error('projectDir is required for project-scoped skill installation');
+    }
+    return path.join(projectDir, '.agents', 'skills');
+  }
+
+  /**
+   * Get the old .codex/prompts directory for cleanup purposes
+   */
+  getOldCodexPromptDir(projectDir = null, location = 'global') {
     if (location === 'project' && projectDir) {
       return path.join(projectDir, '.codex', 'prompts');
     }
     return path.join(os.homedir(), '.codex', 'prompts');
   }
 
-  async flattenAndWriteArtifacts(artifacts, destDir) {
-    let written = 0;
+  /**
+   * Write artifacts as Agent Skills (agentskills.io format).
+   * Each artifact becomes a directory containing SKILL.md.
+   * @param {string} destDir - Base skills directory
+   * @param {Array} artifacts - Artifacts to write
+   * @param {string} artifactType - Type filter (e.g., 'agent-launcher', 'workflow-command', 'task')
+   * @returns {number} Number of skills written
+   */
+  async writeSkillArtifacts(destDir, artifacts, artifactType) {
+    let writtenCount = 0;
 
     for (const artifact of artifacts) {
-      const flattenedName = this.flattenFilename(artifact.relativePath);
-      const targetPath = path.join(destDir, flattenedName);
-      await fs.writeFile(targetPath, artifact.content);
-      written++;
+      // Filter by type if the artifact has a type field
+      if (artifact.type && artifact.type !== artifactType) {
+        continue;
+      }
+
+      // Get the dash-format name (e.g., bmad-bmm-create-prd.md) and remove .md
+      const flatName = toDashPath(artifact.relativePath);
+      const skillName = flatName.replace(/\.md$/, '');
+
+      // Create skill directory
+      const skillDir = path.join(destDir, skillName);
+      await fs.ensureDir(skillDir);
+
+      // Transform content: rewrite frontmatter for skills format
+      const skillContent = this.transformToSkillFormat(artifact.content, skillName);
+
+      // Write SKILL.md with platform-native line endings
+      const platformContent = skillContent.replaceAll('\n', os.EOL);
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), platformContent, 'utf8');
+      writtenCount++;
     }
 
-    return written;
+    return writtenCount;
   }
 
+  /**
+   * Transform artifact content from Codex prompt format to Agent Skills format.
+   * Removes disable-model-invocation, ensures name matches directory.
+   * @param {string} content - Original content with YAML frontmatter
+   * @param {string} skillName - Skill name (must match directory name)
+   * @returns {string} Transformed content
+   */
+  transformToSkillFormat(content, skillName) {
+    // Normalize line endings so body matches rebuilt frontmatter (both LF)
+    content = content.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+
+    // Parse frontmatter
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fmMatch) {
+      // No frontmatter -- wrap with minimal frontmatter
+      const fm = yaml.stringify({ name: skillName, description: skillName }).trimEnd();
+      return `---\n${fm}\n---\n\n${content}`;
+    }
+
+    const frontmatter = fmMatch[1];
+    const body = fmMatch[2];
+
+    // Parse frontmatter with yaml library to handle all quoting variants
+    let description;
+    try {
+      const parsed = yaml.parse(frontmatter);
+      description = parsed?.description || `${skillName} skill`;
+    } catch {
+      description = `${skillName} skill`;
+    }
+
+    // Build new frontmatter with only skills-spec fields, let yaml handle quoting
+    const newFrontmatter = yaml.stringify({ name: skillName, description }, { lineWidth: 0 }).trimEnd();
+    return `---\n${newFrontmatter}\n---\n${body}`;
+  }
+
+  /**
+   * Remove existing BMAD skill directories from the skills directory.
+   */
+  async clearOldBmadSkills(destDir, options = {}) {
+    if (!(await fs.pathExists(destDir))) {
+      return;
+    }
+
+    let entries;
+    try {
+      entries = await fs.readdir(destDir);
+    } catch (error) {
+      if (!options.silent) await prompts.log.warn(`Warning: Could not read directory ${destDir}: ${error.message}`);
+      return;
+    }
+
+    if (!entries || !Array.isArray(entries)) {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry || typeof entry !== 'string') {
+        continue;
+      }
+      if (!entry.startsWith('bmad')) {
+        continue;
+      }
+
+      const entryPath = path.join(destDir, entry);
+      try {
+        await fs.remove(entryPath);
+      } catch (error) {
+        if (!options.silent) {
+          await prompts.log.message(`  Skipping ${entry}: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Clean old BMAD files from legacy .codex/prompts directories.
+   */
   async clearOldBmadFiles(destDir, options = {}) {
     if (!(await fs.pathExists(destDir))) {
       return;
@@ -299,30 +353,11 @@ class CodexSetup extends BaseIdeSetup {
   }
 
   async readAndProcessWithProject(filePath, metadata, projectDir) {
-    const content = await fs.readFile(filePath, 'utf8');
+    const rawContent = await fs.readFile(filePath, 'utf8');
+    const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
     return super.processContent(content, metadata, projectDir);
   }
 
-  /**
-   * Get instructions for global installation
-   * @returns {string} Instructions text
-   */
-  getGlobalInstructions(destDir) {
-    const lines = [
-      'IMPORTANT: Codex Configuration',
-      '',
-      '/prompts installed globally to your HOME DIRECTORY.',
-      '',
-      'These prompts reference a specific _bmad path.',
-      "To use with other projects, you'd need to copy the _bmad dir.",
-      '',
-      'You can now use /commands in Codex CLI',
-      '  Example: /bmad_bmm_pm',
-      '  Type / to see all available commands',
-    ];
-    return lines.join('\n');
-  }
-
   /**
    * Get instructions for project-specific installation
    * @param {string} projectDir - Optional project directory
@@ -330,95 +365,74 @@ class CodexSetup extends BaseIdeSetup {
    * @returns {string} Instructions text
    */
   getProjectSpecificInstructions(projectDir = null, destDir = null) {
-    const isWindows = os.platform() === 'win32';
-
-    const commonLines = [
+    const lines = [
       'Project-Specific Codex Configuration',
       '',
-      `Prompts will be installed to: ${destDir || '<project>/.codex/prompts'}`,
-      '',
-      'REQUIRED: You must set CODEX_HOME to use these prompts',
+      `Skills installed to: ${destDir || '<project>/.agents/skills'}`,
       '',
+      'Codex automatically discovers skills in .agents/skills/ at and above the current directory and in your home directory.',
+      'No additional configuration is needed.',
     ];
 
-    const windowsLines = [
-      'Create a codex.cmd file in your project root:',
-      '',
-      '  @echo off',
-      '  set CODEX_HOME=%~dp0.codex',
-      '  codex %*',
-      '',
-      String.raw`Then run: .\codex instead of codex`,
-      '(The %~dp0 gets the directory of the .cmd file)',
-    ];
-
-    const unixLines = [
-      'Add this alias to your ~/.bashrc or ~/.zshrc:',
-      '',
-      '  alias codex=\'CODEX_HOME="$PWD/.codex" codex\'',
-      '',
-      'After adding, run: source ~/.bashrc  (or source ~/.zshrc)',
-      '(The $PWD uses your current working directory)',
-    ];
-    const closingLines = ['', 'This tells Codex CLI to use prompts from this project instead of ~/.codex'];
-
-    const lines = [...commonLines, ...(isWindows ? windowsLines : unixLines), ...closingLines];
-
     return lines.join('\n');
   }
 
   /**
-   * Cleanup Codex configuration
+   * Cleanup Codex configuration - cleans both new .agents/skills and old .codex/prompts
    */
   async cleanup(projectDir = null) {
-    // Clean both global and project-specific locations
-    const globalDir = this.getCodexPromptDir(null, 'global');
-    await this.clearOldBmadFiles(globalDir);
+    // Clean old .codex/prompts locations
+    const oldGlobalDir = this.getOldCodexPromptDir(null, 'global');
+    await this.clearOldBmadFiles(oldGlobalDir);
 
     if (projectDir) {
-      const projectSpecificDir = this.getCodexPromptDir(projectDir, 'project');
-      await this.clearOldBmadFiles(projectSpecificDir);
+      const oldProjectDir = this.getOldCodexPromptDir(projectDir, 'project');
+      await this.clearOldBmadFiles(oldProjectDir);
+
+      // Clean new .agents/skills location
+      const destDir = this.getCodexSkillsDir(projectDir);
+      await this.clearOldBmadSkills(destDir);
     }
   }
 
   /**
-   * Install a custom agent launcher for Codex
-   * @param {string} projectDir - Project directory (not used, Codex installs to home)
+   * Install a custom agent launcher for Codex as an Agent Skill
+   * @param {string} projectDir - Project directory
    * @param {string} agentName - Agent name (e.g., "fred-commit-poet")
    * @param {string} agentPath - Path to compiled agent (relative to project root)
    * @param {Object} metadata - Agent metadata
-   * @returns {Object|null} Info about created command
+   * @returns {Object|null} Info about created skill
    */
   async installCustomAgentLauncher(projectDir, agentName, agentPath, metadata) {
-    const destDir = this.getCodexPromptDir(projectDir, 'project');
-    await fs.ensureDir(destDir);
+    const destDir = this.getCodexSkillsDir(projectDir);
 
-    const launcherContent = `---
-name: '${agentName}'
-description: '${agentName} agent'
-disable-model-invocation: true
----
+    // Skill name from the dash name (without .md)
+    const skillName = customAgentDashName(agentName).replace(/\.md$/, '');
+    const skillDir = path.join(destDir, skillName);
+    await fs.ensureDir(skillDir);
 
-You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+    const description = metadata?.description || `${agentName} agent`;
+    const fm = yaml.stringify({ name: skillName, description }).trimEnd();
+    const skillContent =
+      `---\n${fm}\n---\n` +
+      "\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.\n" +
+      '\n<agent-activation CRITICAL="TRUE">\n' +
+      `1. LOAD the FULL agent file from @${agentPath}\n` +
+      '2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n' +
+      '3. FOLLOW every step in the <activation> section precisely\n' +
+      '4. DISPLAY the welcome/greeting as instructed\n' +
+      '5. PRESENT the numbered menu\n' +
+      '6. WAIT for user input before proceeding\n' +
+      '</agent-activation>\n';
 
-<agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from @${agentPath}
-2. READ its entire contents - this contains the complete agent persona, menu, and instructions
-3. FOLLOW every step in the <activation> section precisely
-4. DISPLAY the welcome/greeting as instructed
-5. PRESENT the numbered menu
-6. WAIT for user input before proceeding
-</agent-activation>
-`;
-
-    // Use underscore format: bmad_custom_fred-commit-poet.md
-    const fileName = customAgentDashName(agentName);
-    const launcherPath = path.join(destDir, fileName);
-    await fs.writeFile(launcherPath, launcherContent, 'utf8');
+    // Write with platform-native line endings
+    const platformContent = skillContent.replaceAll('\n', os.EOL);
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    await fs.writeFile(skillPath, platformContent, 'utf8');
 
     return {
-      path: path.relative(projectDir, launcherPath),
-      command: `/${fileName.replace('.md', '')}`,
+      path: path.relative(projectDir, skillPath),
+      command: `$${skillName}`,
     };
   }
 }

tools/cli/installers/lib/ide/github-copilot.js

@@ -166,7 +166,6 @@ class GitHubCopilotSetup extends BaseIdeSetup {
     return `---
 description: '${description.replaceAll("'", "''")}'
 tools: ${toolsStr}
-disable-model-invocation: true
 ---
 
 You must fully embody this agent's persona and follow all activation instructions exactly as specified.

tools/cli/installers/lib/ide/shared/task-tool-command-generator.js

@@ -176,7 +176,6 @@ class TaskToolCommandGenerator {
 
     return `---
 description: '${description.replaceAll("'", "''")}'
-disable-model-invocation: true
 ---
 
 # ${item.displayName || item.name}

tools/cli/installers/lib/ide/templates/agent-command-template.md

@@ -1,7 +1,6 @@
 ---
 name: '{{name}}'
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

tools/cli/installers/lib/ide/templates/combined/default-agent.md

@@ -1,7 +1,6 @@
 ---
 name: '{{name}}'
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md

@@ -1,7 +1,6 @@
 ---
 name: '{{name}}'
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

tools/cli/installers/lib/ide/templates/combined/default-workflow.md

@@ -1,7 +1,6 @@
 ---
 name: '{{name}}'
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!

tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml

@@ -1,4 +1,4 @@
-description = """{{description}}"""
+description = '{{description}}'
 prompt = """
 Execute the BMAD '{{name}}' workflow.
 

tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml

@@ -1,4 +1,4 @@
-description = """{{description}}"""
+description = '{{description}}'
 prompt = """
 Execute the BMAD '{{name}}' workflow.
 

tools/cli/installers/lib/ide/templates/workflow-command-template.md

@@ -1,6 +1,5 @@
 ---
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

tools/cli/installers/lib/ide/templates/workflow-commander.md

@@ -1,6 +1,5 @@
 ---
 description: '{{description}}'
-disable-model-invocation: true
 ---
 
 IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{{workflow_path}}, READ its entire contents and follow its directions exactly!

tools/maintainer/review-pr-README.md

@@ -1,55 +0,0 @@
-# Raven's Verdict - Deep PR Review Tool
-
-Adversarial code review for GitHub PRs. Works with any LLM agent.
-
-> **Status: Experimental.** We're still figuring out how to use this effectively. Expect the workflow to evolve.
-
-## How It Works
-
-Point your agent at `review-pr.md` and ask it to review a specific PR:
-
-> "Read tools/maintainer/review-pr.md and apply it to PR #123"
-
-The tool will:
-
-1. Check out the PR branch locally
-2. Run an adversarial review (find at least 5 issues)
-3. Transform findings into professional tone
-4. Preview the review and ask before posting
-
-See `review-pr.md` for full prompt structure, severity ratings, and sandboxing rules.
-
-## When to Use
-
-**Good candidates:**
-
-- PRs with meaningful logic changes
-- Refactors touching multiple files
-- New features or architectural changes
-
-**Skip it for:**
-
-- Trivial PRs (typo fixes, version bumps, single-line changes)
-- PRs you've already reviewed manually
-- PRs where you haven't agreed on the approach yet — fix the direction before the implementation
-
-## Workflow Tips
-
-**Always review before posting.** The preview step exists for a reason:
-
-- **[y] Yes** — Post as-is (only if you're confident)
-- **[e] Edit** — Modify findings before posting
-- **[s] Save only** — Write to file, don't post
-
-The save option is useful when you want to:
-
-- Hand-edit the review before posting
-- Use the findings as input for a second opinion ("Hey Claude, here's what Raven found — what do you think?")
-- Cherry-pick specific findings
-
-**Trust but verify.** LLM reviews can miss context or flag non-issues. Skim the findings before they hit the PR.
-
-## Prerequisites
-
-- `gh` CLI installed and authenticated (`gh auth status`)
-- Any LLM agent capable of running bash commands

tools/validate-doc-links.js

@@ -51,7 +51,7 @@ function getMarkdownFiles(dir) {
 
       if (entry.isDirectory()) {
         walk(fullPath);
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
         files.push(fullPath);
       }
     }
@@ -120,10 +120,13 @@ function resolveLink(siteRelativePath, sourceFile) {
     if (!resolved.startsWith(DOCS_ROOT + path.sep) && resolved !== DOCS_ROOT) return null;
     if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
     if (fs.existsSync(resolved + '.md')) return resolved + '.md';
-    // Directory: check for index.md
+    if (fs.existsSync(resolved + '.mdx')) return resolved + '.mdx';
+    // Directory: check for index.md or index.mdx
     if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
       const indexFile = path.join(resolved, 'index.md');
+      const indexMdxFile = path.join(resolved, 'index.mdx');
       if (fs.existsSync(indexFile)) return indexFile;
+      if (fs.existsSync(indexMdxFile)) return indexMdxFile;
     }
     return null;
   }
@@ -134,12 +137,17 @@ function resolveLink(siteRelativePath, sourceFile) {
   }
 
   if (checkPath.endsWith('/')) {
-    // Could be file.md or directory/index.md
-    const asFile = path.join(DOCS_ROOT, checkPath.slice(0, -1) + '.md');
+    // Could be file.md, file.mdx, or directory/index.md/mdx
+    const baseName = checkPath.slice(0, -1);
+    const asMd = path.join(DOCS_ROOT, baseName + '.md');
+    const asMdx = path.join(DOCS_ROOT, baseName + '.mdx');
     const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md');
+    const asIndexMdx = path.join(DOCS_ROOT, checkPath, 'index.mdx');
 
-    if (fs.existsSync(asFile)) return asFile;
+    if (fs.existsSync(asMd)) return asMd;
+    if (fs.existsSync(asMdx)) return asMdx;
     if (fs.existsSync(asIndex)) return asIndex;
+    if (fs.existsSync(asIndexMdx)) return asIndexMdx;
     return null;
   }
 
@@ -151,10 +159,16 @@ function resolveLink(siteRelativePath, sourceFile) {
   const withMd = direct + '.md';
   if (fs.existsSync(withMd)) return withMd;
 
-  // Directory without trailing slash: check for index.md
+  // Try with .mdx extension
+  const withMdx = direct + '.mdx';
+  if (fs.existsSync(withMdx)) return withMdx;
+
+  // Directory without trailing slash: check for index.md or index.mdx
   if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
     const indexFile = path.join(direct, 'index.md');
+    const indexMdxFile = path.join(direct, 'index.mdx');
     if (fs.existsSync(indexFile)) return indexFile;
+    if (fs.existsSync(indexMdxFile)) return indexMdxFile;
   }
 
   return null;

website/astro.config.mjs

@@ -90,6 +90,7 @@ export default defineConfig({
       // Sidebar configuration (Diataxis structure)
       sidebar: [
         { label: 'Welcome', slug: 'index' },
+        { label: 'Roadmap', slug: 'roadmap' },
         {
           label: 'Tutorials',
           collapsed: false,

website/src/rehype-markdown-links.js

@@ -101,11 +101,19 @@ export function findFirstDelimiter(str) {
 /** Walk up from a file path to find the content docs directory. */
 export function detectContentDir(filePath) {
   const segments = filePath.split(path.sep);
-  // Look for src/content/docs in the path
+  // Look for src/content/docs in the path (standard Astro)
   for (let i = segments.length - 1; i >= 2; i--) {
     if (segments[i - 2] === 'src' && segments[i - 1] === 'content' && segments[i] === 'docs') {
       return segments.slice(0, i + 1).join(path.sep);
     }
   }
+  // Also check for a standalone 'docs' directory (BMAD project structure)
+  // Path format: .../bmm/docs/file.mdx or .../bmm/website/...
+  for (let i = segments.length - 1; i >= 0; i--) {
+    if (segments[i] === 'docs') {
+      // Found docs directory - use its parent as the content root
+      return segments.slice(0, i + 1).join(path.sep);
+    }
+  }
   return null;
 }

website/src/styles/custom.css

@@ -507,3 +507,299 @@ blockquote {
     padding-right: 3rem;
   }
 }
+
+/* ============================================
+   ROADMAP STYLES
+   ============================================ */
+.roadmap-container {
+  --color-planned: #6366f1;
+  --color-in-progress: #10b981;
+  --color-exploring: #f59e0b;
+  --color-bg-card: rgba(255, 255, 255, 0.03);
+  --color-border: rgba(255, 255, 255, 0.1);
+}
+
+.dark .roadmap-container {
+  --color-bg-card: rgba(255, 255, 255, 0.03);
+  --color-border: rgba(255, 255, 255, 0.1);
+}
+
+.light .roadmap-container {
+  --color-bg-card: rgba(0, 0, 0, 0.02);
+  --color-border: rgba(0, 0, 0, 0.1);
+}
+
+.roadmap-legend {
+  display: flex;
+  gap: 1.5rem;
+  flex-wrap: wrap;
+  justify-content: center;
+  margin: 2rem 0;
+  padding: 1rem 1.5rem;
+  background: var(--color-bg-card);
+  border: 1px solid var(--color-border);
+  border-radius: 12px;
+}
+
+.legend-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9rem;
+}
+
+.legend-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+
+.legend-dot.planned { background: var(--color-planned); }
+.legend-dot.in-progress { background: var(--color-in-progress); }
+.legend-dot.exploring { background: var(--color-exploring); }
+
+.roadmap-timeline {
+  position: relative;
+  max-width: 1000px;
+  margin: 3rem auto;
+  padding: 0 1rem;
+}
+
+.roadmap-timeline::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  top: 0;
+  bottom: 0;
+  width: 3px;
+  background: linear-gradient(to bottom, var(--color-in-progress), var(--color-planned), var(--color-exploring));
+  transform: translateX(-50%);
+  border-radius: 3px;
+}
+
+.roadmap-item {
+  position: relative;
+  margin-bottom: 3rem;
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  gap: 2rem;
+  align-items: start;
+}
+
+.roadmap-item:nth-child(odd) .roadmap-card {
+  grid-column: 1;
+}
+
+.roadmap-item:nth-child(even) .roadmap-card {
+  grid-column: 3;
+}
+
+.roadmap-marker {
+  grid-column: 2;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  border: 4px solid var(--starlight-canvas-bg);
+  background: var(--color-in-progress);
+  position: relative;
+  z-index: 1;
+  box-shadow: 0 0 0 4px var(--color-border);
+}
+
+.roadmap-item.in-progress .roadmap-marker { background: var(--color-in-progress); }
+.roadmap-item.planned .roadmap-marker { background: var(--color-planned); }
+.roadmap-item.exploring .roadmap-marker { background: var(--color-exploring); }
+
+.roadmap-item:nth-child(odd) .roadmap-content {
+  grid-column: 1;
+  text-align: right;
+}
+
+.roadmap-item:nth-child(even) .roadmap-content {
+  grid-column: 3;
+  text-align: left;
+}
+
+.roadmap-card {
+  background: var(--color-bg-card);
+  border: 1px solid var(--color-border);
+  border-radius: 16px;
+  padding: 1.5rem;
+  transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease;
+}
+
+.roadmap-card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15);
+  border-color: var(--color-in-progress);
+}
+
+.roadmap-card.planned:hover { border-color: var(--color-planned); }
+.roadmap-card.exploring:hover { border-color: var(--color-exploring); }
+
+.roadmap-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 1rem;
+}
+
+.roadmap-item:nth-child(odd) .roadmap-header {
+  flex-direction: row-reverse;
+}
+
+.roadmap-badge {
+  padding: 0.25rem 0.75rem;
+  border-radius: 20px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.roadmap-badge.in-progress {
+  background: rgba(16, 185, 129, 0.15);
+  color: #10b981;
+}
+
+.roadmap-badge.planned {
+  background: rgba(99, 102, 241, 0.15);
+  color: #6366f1;
+}
+
+.roadmap-badge.exploring {
+  background: rgba(245, 158, 11, 0.15);
+  color: #f59e0b;
+}
+
+.roadmap-title {
+  font-size: 1.25rem;
+  font-weight: 700;
+  margin: 0;
+}
+
+.roadmap-description {
+  color: var(--slate-color-500);
+  margin-bottom: 1rem;
+  line-height: 1.6;
+}
+
+.roadmap-features {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.roadmap-features li {
+  padding: 0.5rem 0;
+  padding-left: 1.5rem;
+  position: relative;
+  font-size: 0.9rem;
+  color: var(--slate-color-400);
+}
+
+.roadmap-features li::before {
+  content: '→';
+  position: absolute;
+  left: 0;
+  color: var(--color-in-progress);
+}
+
+.roadmap-item.planned .roadmap-features li::before { color: var(--color-planned); }
+.roadmap-item.exploring .roadmap-features li::before { color: var(--color-exploring); }
+
+.roadmap-section-title {
+  text-align: center;
+  font-size: 1.5rem;
+  font-weight: 700;
+  margin: 3rem 0 2rem;
+  padding: 1rem;
+  background: linear-gradient(135deg, var(--color-in-progress), var(--color-planned));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.roadmap-future {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  align-items: stretch;
+  gap: 1.5rem;
+  margin-top: 3rem;
+  padding: 2rem;
+  background: var(--color-bg-card);
+  border: 1px solid var(--color-border);
+  border-radius: 16px;
+}
+
+.roadmap-future-card {
+  padding: 1.5rem;
+  border-radius: 12px;
+  background: linear-gradient(135deg, rgba(99, 102, 241, 0.1), rgba(245, 158, 11, 0.05));
+  border: 1px solid var(--color-border);
+  transition: transform 0.2s ease;
+  display: flex;
+  flex-direction: column;
+  min-height: 140px;
+}
+
+.roadmap-future-card h4 {
+  margin: 0 0 0.5rem 0;
+}
+
+.roadmap-future-card p {
+  margin: 0;
+}
+
+.roadmap-future-card:hover {
+  transform: scale(1.02);
+}
+
+.roadmap-future-card h4 {
+  margin: 0 0 0.5rem;
+  font-size: 1.1rem;
+  color: var(--color-planned);
+}
+
+.roadmap-future-card p {
+  margin: 0;
+  font-size: 0.9rem;
+  color: var(--slate-color-400);
+}
+
+.roadmap-emoji {
+  font-size: 1.5rem;
+  margin-bottom: 0.5rem;
+  display: block;
+}
+
+@media (max-width: 768px) {
+  .roadmap-timeline::before {
+    left: 20px;
+  }
+
+  .roadmap-item {
+    grid-template-columns: auto 1fr;
+    gap: 1rem;
+  }
+
+  .roadmap-item:nth-child(odd) .roadmap-card,
+  .roadmap-item:nth-child(even) .roadmap-card {
+    grid-column: 2;
+  }
+
+  .roadmap-item:nth-child(odd) .roadmap-content,
+  .roadmap-item:nth-child(even) .roadmap-content {
+    grid-column: 2;
+    text-align: left;
+  }
+
+  .roadmap-marker {
+    grid-column: 1;
+    grid-row: 1;
+  }
+
+  .roadmap-item:nth-child(odd) .roadmap-header {
+    flex-direction: row;
+  }
+}