Interactive workflow guide, README Quick Start overhaul, and /bmad-help callouts (#1396)

forcetrainer · claude · web-flow · commit 999ece33a90c · 2026-01-24T12:16:20.000-06:00
* Add interactive workflow guide page

Replace confusing static SVG workflow diagram with an interactive
guide at /workflow-guide. Users select their track (Quick Flow,
BMad Method, Enterprise) and see relevant phases, agents, commands,
and outputs. Update link validator to recognize custom page routes.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Add visual dev loop indicator to workflow guide

Wrap create-story, dev-story, and code-review in a dashed border
group with a "Repeat for each story" label to clearly communicate
the iterative development cycle in Phase 4.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Simplify workflow guide to vertical slash command flow

Replace expandable phase cards with a clean vertical flow showing
slash commands as the primary element, with down arrows between
steps, agent badges, required/optional status, and concise
descriptions. Add prominent /bmad-help callout and note that
agent loading is optional.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Simplify README Quick Start with numbered command flows

Replace wordy paragraphs and track table with two clear numbered
paths (Quick Flow: 3 commands, BMad Method: 6 steps) and a
prominent /bmad-help callout as the primary guidance mechanism.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Add Party Mode to README, /bmad-help to getting-started

Add Party Mode bullet to Why BMad section, note about agent-based
usage as an alternative to direct workflows, and a /bmad-help
mention in the getting-started tutorial after installation.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Add link to getting-started tutorial in README Quick Start

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Add workflow guide link to docs index New Here section

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Update README tagline and format modules table

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Fix workflow-guide links to use relative paths

The /workflow-guide absolute path breaks with non-root base paths.
Use relative paths since workflow-guide is a custom Astro page
outside the docs collection. Docs-to-docs links keep the /docs/
pattern which the rehype plugin handles.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

* Revert workflow-guide links to absolute paths

Use /workflow-guide to match the /docs/ convention used throughout.
Works correctly on the production site where base path is /.

Co-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
-**Build More, Architect Dreams** — An AI-driven agile development framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
+**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
 
 **100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay.
 
@@ -16,6 +16,7 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 - **Scale-Adaptive**: Automatically adjusts planning depth based on project complexity (Level 0-4)
 - **Structured Workflows**: Grounded in agile best practices across analysis, planning, architecture, and implementation
 - **Specialized Agents**: 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
+- **Party Mode**: Bring multiple agent personas into one session to plan, troubleshoot, or discuss your project collaboratively
 - **Complete Lifecycle**: From brainstorming to deployment, with just-in-time documentation
 
 ## Quick Start
@@ -26,34 +27,43 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 npx bmad-method@alpha install
 ```
 
-Follow the installer prompts to configure your project.
+Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
 
-Once you have installed BMad to a folder, launch your tool of choice from where you installed BMad. (We really like Claude Code and Cursor - but there are any that work great with BMad!)
+> **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask it questions like `/bmad-help How should I build a web app for XYZ?`
 
-Then its simple as running the command: `/bmad-help` if you do not know what to do. Depending on which modules you have installed, you will have different choices.
+The workflows below show the fastest path to working code. You can also load agents directly for a more structured process, extensive planning, or to learn about agile development practices — the agents guide you with menus, explanations, and elicitation at each step.
 
-To make the help more applicable you can even run the `/bmad-help What do you suggest I do to get started building a brand new web application for XYZ`.
+### Simple Path (Quick Flow)
 
-The results from BMad Help will be able to suggest and constantly guide you on what to do next - along with the workflows upon completion also making suggestions on what to do next.
+Bug fixes, small features, clear scope — 3 commands:
 
-This analyzes your project and recommends a track:
+1. `/quick-spec` — analyzes your codebase and produces a tech-spec with stories
+2. `/dev-story` — implements each story
+3. `/code-review` — validates quality
 
-| Track           | Best For                  | Time to First Story Coding |
-| --------------- | ------------------------- | -------------------------- |
-| **Quick Flow**  | Bug fixes, small features | ~10-30 minutes             |
-| **BMad Method** | Products and platforms    | ~30 minutes - 2 hours      |
-| **Enterprise**  | Compliance-heavy systems  | ~1-3 hours                 |
+### Full Planning Path (BMad Method)
+
+Products, platforms, complex features — structured planning then build:
+
+1. `/product-brief` — define problem, users, and MVP scope
+2. `/create-prd` — full requirements with personas, metrics, and risks
+3. `/create-architecture` — technical decisions and system design
+4. `/create-epics-and-stories` — break work into prioritized stories
+5. `/sprint-planning` — initialize sprint tracking
+6. **Repeat per story:** `/create-story` → `/dev-story` → `/code-review`
+
+Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/getting-started-bmadv6/).
 
 ## Modules
 
 BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time.
 
-| Module | GitHub | NPM | Purpose |
-|--------|--------|-----|---------|
-| **BMad Method (BMM)** | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) | [bmad-method](https://www.npmjs.com/package/bmad-method) | Core framework with 34+ workflows across 4 development phases |
-| **BMad Builder (BMB)** | [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) | [bmad-builder](https://www.npmjs.com/package/bmad-builder) | Create custom BMad agents, workflows, and domain-specific modules |
-| **Game Dev Studio (BMGD)** | [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | [bmad-game-dev-studio](https://www.npmjs.com/package/bmad-game-dev-studio) | Game development workflows for Unity, Unreal, and Godot |
-| **Creative Intelligence Suite (CIS)** | [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | [bmad-creative-intelligence-suite](https://www.npmjs.com/package/bmad-creative-intelligence-suite) | Innovation, brainstorming, design thinking, and problem-solving |
+| Module                                | GitHub                                                                                                                            | NPM                                                                                                | Purpose                                                           |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **BMad Method (BMM)**                 | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)                                                         | [bmad-method](https://www.npmjs.com/package/bmad-method)                                           | Core framework with 34+ workflows across 4 development phases     |
+| **BMad Builder (BMB)**                | [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)                                                       | [bmad-builder](https://www.npmjs.com/package/bmad-builder)                                         | Create custom BMad agents, workflows, and domain-specific modules |
+| **Game Dev Studio (BMGD)**            | [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)                         | [bmad-game-dev-studio](https://www.npmjs.com/package/bmad-game-dev-studio)                         | Game development workflows for Unity, Unreal, and Godot           |
+| **Creative Intelligence Suite (CIS)** | [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | [bmad-creative-intelligence-suite](https://www.npmjs.com/package/bmad-creative-intelligence-suite) | Innovation, brainstorming, design thinking, and problem-solving   |
 
 ## Documentation
 
diff --git a/docs/index.md b/docs/index.md
@@ -13,6 +13,7 @@ If you're comfortable working with AI coding assistants like Claude, Cursor, or
 The fastest way to understand BMad is to try it. Choose a tutorial to walk through your first project in about 10 minutes.
 
 - **[Get Started with BMad](/docs/tutorials/getting-started/getting-started-bmadv6.md)** — Latest features, still in active development
+- **[Workflow Guide](/workflow-guide)** — A simple visual overview of the various BMad tracks that get you going quickly.
 
 :::tip[Already familiar with AI-assisted development?]
 Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](/docs/explanation/core-concepts/what-are-agents.md) to understand how BMad organizes its AI personas.
diff --git a/docs/tutorials/getting-started/getting-started-bmadv6.md b/docs/tutorials/getting-started/getting-started-bmadv6.md
@@ -42,9 +42,7 @@ BMad helps you build software through guided workflows with specialized AI agent
 | 3     | Solutioning    | Design architecture *(BMad Method/Enterprise only)* |
 | 4     | Implementation | Build epic by epic, story by story                  |
 
-![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg)
-
-*Complete visual flowchart showing all phases, workflows, and agents for the standard greenfield track.*
+**[Open the Interactive Workflow Guide](/workflow-guide)** to explore phases, agents, and outputs for your chosen track.
 
 Based on your project's complexity, BMad offers three planning tracks:
 
@@ -86,6 +84,8 @@ your-project/
 Having issues? See [Install BMad](/docs/how-to/installation/install-bmad.md) for common solutions.
 :::
 
+Open your AI IDE in the project folder. From here, you can run `/bmad-help` anytime to see what to do next — or ask it a question like `/bmad-help How should I build a web app for XYZ?`
+
 ## Step 1: Initialize Your Project
 
 Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
diff --git a/tools/validate-doc-links.js b/tools/validate-doc-links.js
@@ -27,6 +27,9 @@ const LINK_REGEX = /\[([^\]]*)\]\((\/[^)]+)\)/g;
 // File extensions that are static assets, not markdown docs
 const STATIC_ASSET_EXTENSIONS = ['.zip', '.txt', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
 
+// Custom Astro page routes (not part of the docs content collection)
+const CUSTOM_PAGE_ROUTES = new Set(['/workflow-guide']);
+
 // Regex to extract headings for anchor validation
 const HEADING_PATTERN = /^#{1,6}\s+(.+)$/gm;
 
@@ -210,6 +213,11 @@ function processFile(filePath) {
       continue;
     }
 
+    // Skip custom Astro page routes
+    if (CUSTOM_PAGE_ROUTES.has(linkPath)) {
+      continue;
+    }
+
     // Validate the link target exists
     const targetFile = resolveLink(linkPath);
 
diff --git a/website/src/components/WorkflowGuide.astro b/website/src/components/WorkflowGuide.astro
diff --git a/website/src/pages/workflow-guide.astro b/website/src/pages/workflow-guide.astro
