bmad-fh 6.0.0-alpha.23

package/docs/_STYLE_GUIDE.md

@@ -0,0 +1,367 @@
+---
+title: "Documentation Style Guide"
+---
+
+This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow.
+
+## Project-Specific Rules
+
+| Rule | Specification |
+|------|---------------|
+| No horizontal rules (`---`) | Fragments reading flow |
+| No `####` headers | Use bold text or admonitions instead |
+| No "Related" or "Next:" sections | Sidebar handles navigation |
+| No deeply nested lists | Break into sections instead |
+| No code blocks for non-code | Use admonitions for dialogue examples |
+| No bold paragraphs for callouts | Use admonitions instead |
+| 1-2 admonitions per section max | Tutorials allow 3-4 per major section |
+| Table cells / list items | 1-2 sentences max |
+| Header budget | 8-12 `##` per doc; 2-3 `###` per section |
+
+## Admonitions (Starlight Syntax)
+
+```md
+:::tip[Title]
+Shortcuts, best practices
+:::
+
+:::note[Title]
+Context, definitions, examples, prerequisites
+:::
+
+:::caution[Title]
+Caveats, potential issues
+:::
+
+:::danger[Title]
+Critical warnings only — data loss, security issues
+:::
+```
+
+### Standard Uses
+
+| Admonition | Use For |
+|------------|---------|
+| `:::note[Prerequisites]` | Dependencies before starting |
+| `:::tip[Quick Path]` | TL;DR summary at document top |
+| `:::caution[Important]` | Critical caveats |
+| `:::note[Example]` | Command/response examples |
+
+## Standard Table Formats
+
+**Phases:**
+
+```md
+| Phase | Name | What Happens |
+|-------|------|--------------|
+| 1 | Analysis | Brainstorm, research *(optional)* |
+| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
+```
+
+**Commands:**
+
+```md
+| Command | Agent | Purpose |
+|---------|-------|---------|
+| `*workflow-init` | Analyst | Initialize a new project |
+| `*prd` | PM | Create Product Requirements Document |
+```
+
+## Folder Structure Blocks
+
+Show in "What You've Accomplished" sections:
+
+````md
+```
+your-project/
+├── _bmad/                         # BMad configuration
+├── _bmad-output/
+│   ├── PRD.md                     # Your requirements document
+│   └── bmm-workflow-status.yaml   # Progress tracking
+└── ...
+```
+````
+
+## Tutorial Structure
+
+```text
+1. Title + Hook (1-2 sentences describing outcome)
+2. Version/Module Notice (info or warning admonition) (optional)
+3. What You'll Learn (bullet list of outcomes)
+4. Prerequisites (info admonition)
+5. Quick Path (tip admonition - TL;DR summary)
+6. Understanding [Topic] (context before steps - tables for phases/agents)
+7. Installation (optional)
+8. Step 1: [First Major Task]
+9. Step 2: [Second Major Task]
+10. Step 3: [Third Major Task]
+11. What You've Accomplished (summary + folder structure)
+12. Quick Reference (commands table)
+13. Common Questions (FAQ format)
+14. Getting Help (community links)
+15. Key Takeaways (tip admonition)
+```
+
+### Tutorial Checklist
+
+- [ ] Hook describes outcome in 1-2 sentences
+- [ ] "What You'll Learn" section present
+- [ ] Prerequisites in admonition
+- [ ] Quick Path TL;DR admonition at top
+- [ ] Tables for phases, commands, agents
+- [ ] "What You've Accomplished" section present
+- [ ] Quick Reference table present
+- [ ] Common Questions section present
+- [ ] Getting Help section present
+- [ ] Key Takeaways admonition at end
+
+## How-To Structure
+
+```text
+1. Title + Hook (one sentence: "Use the `X` workflow to...")
+2. When to Use This (bullet list of scenarios)
+3. When to Skip This (optional)
+4. Prerequisites (note admonition)
+5. Steps (numbered ### subsections)
+6. What You Get (output/artifacts produced)
+7. Example (optional)
+8. Tips (optional)
+9. Next Steps (optional)
+```
+
+### How-To Checklist
+
+- [ ] Hook starts with "Use the `X` workflow to..."
+- [ ] "When to Use This" has 3-5 bullet points
+- [ ] Prerequisites listed
+- [ ] Steps are numbered `###` subsections with action verbs
+- [ ] "What You Get" describes output artifacts
+
+## Explanation Structure
+
+### Types
+
+| Type | Example |
+|------|---------|
+| **Index/Landing** | `core-concepts/index.md` |
+| **Concept** | `what-are-agents.md` |
+| **Feature** | `quick-flow.md` |
+| **Philosophy** | `why-solutioning-matters.md` |
+| **FAQ** | `brownfield-faq.md` |
+
+### General Template
+
+```text
+1. Title + Hook (1-2 sentences)
+2. Overview/Definition (what it is, why it matters)
+3. Key Concepts (### subsections)
+4. Comparison Table (optional)
+5. When to Use / When Not to Use (optional)
+6. Diagram (optional - mermaid, 1 per doc max)
+7. Next Steps (optional)
+```
+
+### Index/Landing Pages
+
+```text
+1. Title + Hook (one sentence)
+2. Content Table (links with descriptions)
+3. Getting Started (numbered list)
+4. Choose Your Path (optional - decision tree)
+```
+
+### Concept Explainers
+
+```text
+1. Title + Hook (what it is)
+2. Types/Categories (### subsections) (optional)
+3. Key Differences Table
+4. Components/Parts
+5. Which Should You Use?
+6. Creating/Customizing (pointer to how-to guides)
+```
+
+### Feature Explainers
+
+```text
+1. Title + Hook (what it does)
+2. Quick Facts (optional - "Perfect for:", "Time to:")
+3. When to Use / When Not to Use
+4. How It Works (mermaid diagram optional)
+5. Key Benefits
+6. Comparison Table (optional)
+7. When to Graduate/Upgrade (optional)
+```
+
+### Philosophy/Rationale Documents
+
+```text
+1. Title + Hook (the principle)
+2. The Problem
+3. The Solution
+4. Key Principles (### subsections)
+5. Benefits
+6. When This Applies
+```
+
+### Explanation Checklist
+
+- [ ] Hook states what document explains
+- [ ] Content in scannable `##` sections
+- [ ] Comparison tables for 3+ options
+- [ ] Diagrams have clear labels
+- [ ] Links to how-to guides for procedural questions
+- [ ] 2-3 admonitions max per document
+
+## Reference Structure
+
+### Types
+
+| Type | Example |
+|------|---------|
+| **Index/Landing** | `workflows/index.md` |
+| **Catalog** | `agents/index.md` |
+| **Deep-Dive** | `document-project.md` |
+| **Configuration** | `core-tasks.md` |
+| **Glossary** | `glossary/index.md` |
+| **Comprehensive** | `bmgd-workflows.md` |
+
+### Reference Index Pages
+
+```text
+1. Title + Hook (one sentence)
+2. Content Sections (## for each category)
+   - Bullet list with links and descriptions
+```
+
+### Catalog Reference
+
+```text
+1. Title + Hook
+2. Items (## for each item)
+   - Brief description (one sentence)
+   - **Commands:** or **Key Info:** as flat list
+3. Universal/Shared (## section) (optional)
+```
+
+### Item Deep-Dive Reference
+
+```text
+1. Title + Hook (one sentence purpose)
+2. Quick Facts (optional note admonition)
+   - Module, Command, Input, Output as list
+3. Purpose/Overview (## section)
+4. How to Invoke (code block)
+5. Key Sections (## for each aspect)
+   - Use ### for sub-options
+6. Notes/Caveats (tip or caution admonition)
+```
+
+### Configuration Reference
+
+```text
+1. Title + Hook
+2. Table of Contents (jump links if 4+ items)
+3. Items (## for each config/task)
+   - **Bold summary** — one sentence
+   - **Use it when:** bullet list
+   - **How it works:** numbered steps (3-5 max)
+   - **Output:** expected result (optional)
+```
+
+### Comprehensive Reference Guide
+
+```text
+1. Title + Hook
+2. Overview (## section)
+   - Diagram or table showing organization
+3. Major Sections (## for each phase/category)
+   - Items (### for each item)
+   - Standardized fields: Command, Agent, Input, Output, Description
+4. Next Steps (optional)
+```
+
+### Reference Checklist
+
+- [ ] Hook states what document references
+- [ ] Structure matches reference type
+- [ ] Items use consistent structure throughout
+- [ ] Tables for structured/comparative data
+- [ ] Links to explanation docs for conceptual depth
+- [ ] 1-2 admonitions max
+
+## Glossary Structure
+
+Starlight generates right-side "On this page" navigation from headers:
+
+- Categories as `##` headers — appear in right nav
+- Terms in tables — compact rows, not individual headers
+- No inline TOC — right sidebar handles navigation
+
+### Table Format
+
+```md
+## Category Name
+
+| Term | Definition |
+|------|------------|
+| **Agent** | Specialized AI persona with specific expertise that guides users through workflows. |
+| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |
+```
+
+### Definition Rules
+
+| Do | Don't |
+|----|-------|
+| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
+| Keep to 1-2 sentences | Write multi-paragraph explanations |
+| Bold term name in cell | Use plain text for terms |
+
+### Context Markers
+
+Add italic context at definition start for limited-scope terms:
+
+- `*Quick Flow only.*`
+- `*BMad Method/Enterprise.*`
+- `*Phase N.*`
+- `*BMGD.*`
+- `*Brownfield.*`
+
+### Glossary Checklist
+
+- [ ] Terms in tables, not individual headers
+- [ ] Terms alphabetized within categories
+- [ ] Definitions 1-2 sentences
+- [ ] Context markers italicized
+- [ ] Term names bolded in cells
+- [ ] No "A [term] is..." definitions
+
+## FAQ Sections
+
+```md
+## Questions
+
+- [Do I always need architecture?](#do-i-always-need-architecture)
+- [Can I change my plan later?](#can-i-change-my-plan-later)
+
+### Do I always need architecture?
+
+Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
+
+### Can I change my plan later?
+
+Yes. The SM agent has a `correct-course` workflow for handling scope changes.
+
+**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
+```
+
+## Validation Commands
+
+Before submitting documentation changes:
+
+```bash
+npm run docs:fix-links            # Preview link format fixes
+npm run docs:fix-links -- --write # Apply fixes
+npm run docs:validate-links       # Check links exist
+npm run docs:build                # Verify no build errors
+```

package/docs/_archive/customize-workflows.md

@@ -0,0 +1,30 @@
+---
+title: "Workflow Customization Guide"
+---
+
+Customize and optimize workflows with step replacement and hooks.
+
+## Status
+
+:::note[Coming Soon]
+Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
+:::
+
+## What to Expect
+
+Workflow customization will allow you to:
+
+- **Replace Steps** - Swap out specific workflow steps with custom implementations
+- **Add Hooks** - Inject custom behavior before/after workflow steps
+- **Extend Workflows** - Create new workflows based on existing ones
+- **Override Behavior** - Customize workflow logic for your project's needs
+
+## For Now
+
+While workflow customization is in development, you can:
+
+- **Create Custom Workflows** - Use the BMad Builder to create entirely new workflows
+- **Customize Agents** - Modify agent behavior using [Agent Customization](/docs/how-to/customization/customize-agents.md)
+- **Provide Feedback** - Share your workflow customization needs with the community
+
+**In the meantime:** Learn how to [create custom workflows](/docs/explanation/bmad-builder/index.md) from scratch.

package/docs/_archive/getting-started-bmadv4.md

@@ -0,0 +1,247 @@
+---
+title: "Getting Started with BMad v4"
+description: Install BMad and create your first planning document
+---
+
+
+Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
+
+:::note[Stable Release]
+This tutorial covers BMad v4, the current stable release. For the latest features (with potential breaking changes), see the [BMad v6 Alpha tutorial](./getting-started-bmadv6.md).
+:::
+
+## What You'll Learn
+
+- Install and configure BMad for your IDE
+- Understand how BMad organizes work into phases and agents
+- Initialize a project and choose a planning track
+- Create your first requirements document
+
+:::note[Prerequisites]
+- **Node.js 20+** — Required for the installer
+- **Git** — Recommended for version control
+- **AI-powered IDE** — Claude Code, Cursor, Windsurf, or similar
+- **A project idea** — Even a simple one works for learning
+:::
+
+:::tip[Quick Path]
+**Install** → `npx bmad-method install`
+**Initialize** → Load Analyst agent, run `workflow-init`
+**Plan** → PM creates PRD, Architect creates architecture
+**Build** → SM manages sprints, DEV implements stories
+**Always use fresh chats** for each workflow to avoid context issues.
+:::
+
+## Understanding BMad
+
+BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases:
+
+| Phase | Name | What Happens |
+|-------|------|--------------|
+| 1 | Analysis | Brainstorm, research *(optional)* |
+| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
+| 3 | Solutioning | Architecture, design decisions *(varies by track)* |
+| 4 | Implementation | Build code story by story *(required)* |
+
+Based on your project's complexity, BMad offers three planning tracks:
+
+| Track | Best For | Documents Created |
+|-------|----------|-------------------|
+| **Quick Flow** | Bug fixes, simple features, clear scope | Tech-spec only |
+| **BMad Method** | Products, platforms, complex features | PRD + Architecture + UX |
+| **Enterprise** | Compliance, multi-tenant, enterprise needs | PRD + Architecture + Security + DevOps |
+
+## Installation
+
+Open a terminal in your project directory and run:
+
+```bash
+npx bmad-method install
+```
+
+The interactive installer guides you through setup:
+
+- **Choose Installation Location** — Select current directory (recommended), subdirectory, or custom path
+- **Select Your AI Tool** — Claude Code, Cursor, Windsurf, or other
+- **Choose Modules** — Select **BMM** (BMad Method) for this tutorial
+- **Accept Defaults** — Customize later in `_bmad/[module]/config.yaml`
+
+Verify your installation:
+
+```
+your-project/
+├── _bmad/
+│   ├── bmm/            # Method module
+│   │   ├── agents/     # Agent files
+│   │   ├── workflows/  # Workflow files
+│   │   └── config.yaml # Module config
+│   └── core/           # Core utilities
+├── _bmad-output/       # Generated artifacts (created later)
+└── .claude/            # IDE configuration (if using Claude Code)
+```
+
+:::tip[Troubleshooting]
+Having issues? See [Install BMad](../../how-to/installation/install-bmad.md) for common solutions.
+:::
+
+## Step 1: Initialize Your Project
+
+Load the **Analyst agent** in your IDE:
+- **Claude Code**: Type `/analyst` or load the agent file directly
+- **Cursor/Windsurf**: Open the agent file from `_bmad/bmm/agents/`
+
+Wait for the agent's menu to appear, then run:
+
+```
+Run workflow-init
+```
+
+Or use the shorthand: `*workflow-init`
+
+The workflow asks you to describe:
+- **Your project and goals** — What are you building? What problem does it solve?
+- **Existing codebase** — Is this new (greenfield) or existing code (brownfield)?
+- **Size and complexity** — Roughly how big is this? (adjustable later)
+
+Based on your description, the workflow suggests a planning track. For this tutorial, choose **BMad Method**.
+
+Once you confirm, the workflow creates `bmm-workflow-status.yaml` to track your progress.
+
+:::caution[Fresh Chats]
+Always start a fresh chat for each workflow. This prevents context limitations from causing issues.
+:::
+
+## Step 2: Create Your Plan
+
+With your project initialized, work through the planning phases.
+
+### Phase 1: Analysis (Optional)
+
+If you want to brainstorm or research first:
+- **brainstorm-project** — Guided ideation with the Analyst
+- **research** — Market and technical research
+- **product-brief** — Recommended foundation document
+
+### Phase 2: Planning (Required)
+
+**Start a fresh chat** and load the **PM agent**.
+
+```
+Run prd
+```
+
+Or use shortcuts: `*prd`, select "create-prd" from the menu, or say "Let's create a PRD".
+
+The PM agent guides you through:
+1. **Project overview** — Refine your project description
+2. **Goals and success metrics** — What does success look like?
+3. **User personas** — Who uses this product?
+4. **Functional requirements** — What must the system do?
+5. **Non-functional requirements** — Performance, security, scalability needs
+
+When complete, you'll have `PRD.md` in your `_bmad-output/` folder.
+
+:::note[UX Design (Optional)]
+If your project has a user interface, load the **UX-Designer agent** and run the UX design workflow after creating your PRD.
+:::
+
+### Phase 3: Solutioning (Required for BMad Method)
+
+**Start a fresh chat** and load the **Architect agent**.
+
+```
+Run create-architecture
+```
+
+The architect guides you through technical decisions: tech stack, database design, API patterns, and system structure.
+
+:::tip[Check Your Status]
+Unsure what's next? Load any agent and run `workflow-status`. It tells you the next recommended or required workflow.
+:::
+
+## Step 3: Build Your Project
+
+Once planning is complete, move to implementation.
+
+### Initialize Sprint Planning
+
+Load the **SM agent** and run `sprint-planning`. This creates `sprint-status.yaml` to track all epics and stories.
+
+### The Build Cycle
+
+For each story, repeat this cycle with fresh chats:
+
+| Step | Agent | Workflow | Purpose |
+|------|-------|----------|---------|
+| 1 | SM | `create-story` | Create story file from epic |
+| 2 | DEV | `dev-story` | Implement the story |
+| 3 | DEV | `code-review` | Quality validation *(recommended)* |
+
+After completing all stories in an epic, load the **SM agent** and run `retrospective`.
+
+## What You've Accomplished
+
+You've learned the foundation of building with BMad:
+
+- Installed BMad and configured it for your IDE
+- Initialized a project with your chosen planning track
+- Created planning documents (PRD, Architecture)
+- Understood the build cycle for implementation
+
+Your project now has:
+
+```
+your-project/
+├── _bmad/                         # BMad configuration
+├── _bmad-output/
+│   ├── PRD.md                     # Your requirements document
+│   ├── architecture.md            # Technical decisions
+│   └── bmm-workflow-status.yaml   # Progress tracking
+└── ...
+```
+
+## Quick Reference
+
+| Command | Agent | Purpose |
+|---------|-------|---------|
+| `*workflow-init` | Analyst | Initialize a new project |
+| `*workflow-status` | Any | Check progress and next steps |
+| `*prd` | PM | Create Product Requirements Document |
+| `*create-architecture` | Architect | Create architecture document |
+| `*sprint-planning` | SM | Initialize sprint tracking |
+| `*create-story` | SM | Create a story file |
+| `*dev-story` | DEV | Implement a story |
+| `*code-review` | DEV | Review implemented code |
+
+## Common Questions
+
+**Do I need to create a PRD for every project?**
+Only for BMad Method and Enterprise tracks. Quick Flow projects use a simpler tech-spec instead.
+
+**Can I skip Phase 1 (Analysis)?**
+Yes, Phase 1 is optional. If you already know what you're building, start with Phase 2 (Planning).
+
+**What if I want to brainstorm first?**
+Load the Analyst agent and run `*brainstorm-project` before `workflow-init`.
+
+**Why start fresh chats for each workflow?**
+Workflows are context-intensive. Reusing chats can cause the AI to hallucinate or lose track of details. Fresh chats ensure maximum context capacity.
+
+## Getting Help
+
+- **During workflows** — Agents guide you with questions and explanations
+- **Check status** — Run `workflow-status` with any agent
+- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
+- **Video tutorials** — [BMad Code YouTube](https://www.youtube.com/@BMadCode)
+
+## Key Takeaways
+
+:::tip[Remember These]
+- **Always use fresh chats** — Load agents in new chats for each workflow
+- **Let workflow-status guide you** — Ask any agent for status when unsure
+- **Track matters** — Quick Flow uses tech-spec; Method/Enterprise need PRD and architecture
+- **Tracking is automatic** — Status files update themselves
+- **Agents are flexible** — Use menu numbers, shortcuts (`*prd`), or natural language
+:::
+
+Ready to start? Install BMad, load the Analyst, run `workflow-init`, and let the agents guide you.

package/docs/_archive/vendor-workflows.md

@@ -0,0 +1,52 @@
+---
+title: "Workflow Vendoring, Customization, and Inheritance"
+---
+
+Use workflow vendoring and inheritance to share or reutilize workflows across modules.
+
+## Workflow Vendoring
+
+Workflow Vendoring allows an agent to have access to a workflow from another module, without having to install said module. At install time, the module workflow being vendored will be cloned and installed into the module that is receiving the vendored workflow the agent needs.
+
+### How to Vendor
+
+Lets assume you are building a module, and you do not want to recreate a workflow from the BMad Method, such as workflows/4-implementation/dev-story/workflow.md. Instead of copying all the context to your module, and having to maintain it over time as updates are made, you can instead use the exec-vendor menu item in your agent.
+
+From your modules agent definition, you would implement the menu item as follows in the agent:
+
+```yaml
+    - trigger: develop-story
+      exec-vendor: "{project-root}/_bmad/<source-module>/workflows/4-production/dev-story/workflow.md"
+      exec: "{project-root}/_bmad/<my-module>/workflows/dev-story/workflow.md"
+      description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
+```
+
+At install time, it will clone the workflow and all of its required assets, and the agent that gets built will have an exec to a path installed in its own module. The content gets added to the folder you specify in exec. While it does not have to exactly match the source path, you will want to ensure you are specifying the workflow.md to be in a new location (in other words in this example, dev-story would not already be the path of another custom module workflow that already exists.)
+
+## Workflow Inheritance
+
+:::note[Coming Soon]
+Official support for workflow inheritance is coming post beta.
+:::
+
+Workflow Inheritance is a different concept, that allows you to modify or extend existing workflow.
+
+Party Mode from the core is an example of a workflow that is designed with inheritance in mind - customization for specific party needs. While party mode itself is generic - there might be specific agent collaborations you want to create. Without having to reinvent the whole party mode concept, or copy and paste all of its content - you could inherit from party mode to extend it to be specific.
+
+Some possible examples could be:
+
+- Retrospective
+- Sprint Planning
+- Collaborative Brainstorming Sessions
+
+## Workflow Customization
+
+:::note[Coming Soon]
+Official support for workflow customization is coming post beta.
+:::
+
+Similar to Workflow Inheritance, Workflow Customization will soon be allowed for certain workflows that are meant to be user customized - similar in process to how agents are customized now.
+
+This will take the shape of workflows with optional hooks, configurable inputs, and the ability to replace whole at install time.
+
+For example, assume you are using the Create PRD workflow, which is comprised of 11 steps, and you want to always include specifics about your companies domain, technical landscape or something else. While project-context can be helpful with that, you can also through hooks and step overrides, have full replace steps, the key requirement being to ensure your step replace file is an exact file name match of an existing step, follows all conventions, and ends in a similar fashion to either hook back in to call the next existing step, or more custom steps that eventually hook back into the flow.