BMAD-METHOD/docs/_STYLE_GUIDE.md

title

title
Documentation Style Guide

This project adheres to the Google Developer Documentation Style Guide and uses Diataxis 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)

:::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:

| Phase | Name     | What Happens                                 |
| ----- | -------- | -------------------------------------------- |
| 1     | Analysis | Brainstorm, research *(optional)*            |
| 2     | Planning | Requirements — PRD or tech-spec *(required)* |

Commands:

| Command      | Agent   | Purpose                              |
| ------------ | ------- | ------------------------------------ |
| `brainstorm` | Analyst | Brainstorm a new project             |
| `prd`        | PM      | Create Product Requirements Document |

Folder Structure Blocks

Show in "What You've Accomplished" sections:

```
your-project/
├── _bmad/                         # BMad configuration
├── _bmad-output/
│   ├── PRD.md                     # Your requirements document
│   └── bmm-workflow-status.yaml   # Progress tracking
└── ...
```

Tutorial Structure

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

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

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

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

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

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

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

1. Title + Hook (one sentence)
2. Content Sections (## for each category)
   - Bullet list with links and descriptions

Catalog Reference

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

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

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

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

## 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

## 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:

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