mdan-cli 2.5.0 → 2.5.2

package/docs/how-to/established-projects.md

@@ -0,0 +1,117 @@
+---
+title: "Established Projects"
+description: How to use BMad Method on existing codebases
+sidebar:
+  order: 6
+---
+
+Use BMad Method effectively when working on existing projects and legacy codebases.
+
+This guide covers the essential workflow for onboarding to existing projects with BMad Method.
+
+:::note[Prerequisites]
+- BMad Method installed (`npx bmad-method install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code or Cursor)
+:::
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+
+- `docs/`
+- `_bmad-output/planning-artifacts/`
+- `_bmad-output/implementation-artifacts/`
+
+## Step 2: Create Project Context
+
+:::tip[Recommended for Existing Projects]
+Generate `project-context.md` to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
+:::
+
+Run the generate project context workflow:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your codebase to identify:
+- Technology stack and versions
+- Code organization patterns
+- Naming conventions
+- Testing approaches
+- Framework-specific patterns
+
+You can review and refine the generated file, or create it manually at `_bmad-output/project-context.md` if you prefer.
+
+[Learn more about project context](../explanation/project-context.md)
+
+## Step 3: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- Intent and business rationale
+- Business rules
+- Architecture
+- Any other relevant project information
+
+For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
+
+## Step 3: Get Help
+
+### BMad-Help: Your Starting Point
+
+**Run `/bmad-help` anytime you're unsure what to do next.** This intelligent guide:
+
+- Inspects your project to see what's already been done
+- Shows options based on your installed modules
+- Understands natural language queries
+
+```
+/bmad-help I have an existing Rails app, where should I start?
+/bmad-help What's the difference between quick-flow and full method?
+/bmad-help Show me what workflows are available
+```
+
+BMad-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly what to do next.
+
+### Choosing Your Approach
+
+You have two primary options depending on the scope of changes:
+
+| Scope                          | Recommended Approach                                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad Method is likely overkill. |
+| **Major changes or additions** | Start with the BMad Method, applying as much or as little rigor as needed.                                                    |
+
+### During PRD Creation
+
+When creating a brief or jumping directly into the PRD, ensure the agent:
+
+- Finds and analyzes your existing project documentation
+- Reads the proper context about your current system
+
+You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
+
+### UX Considerations
+
+UX work is optional. The decision depends not on whether your project has a UX, but on:
+
+- Whether you will be working on UX changes
+- Whether significant new UX designs or patterns are needed
+
+If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
+
+### Architecture Considerations
+
+When doing architecture, ensure the architect:
+
+- Uses the proper documented files
+- Scans the existing codebase
+
+Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
+
+## More Information
+
+- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
+- **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects

package/docs/how-to/get-answers-about-bmad.md

@@ -0,0 +1,134 @@
+---
+title: "How to Get Answers About BMad"
+description: Use an LLM to quickly answer your own BMad questions
+sidebar:
+  order: 4
+---
+
+## Start Here: BMad-Help
+
+**The fastest way to get answers about BMad is `/bmad-help`.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
+
+BMad-Help is more than a lookup tool — it:
+- **Inspects your project** to see what's already been completed
+- **Understands natural language** — ask questions in plain English
+- **Varies based on your installed modules** — shows relevant options
+- **Auto-runs after workflows** — tells you exactly what to do next
+- **Recommends the first required task** — no guessing where to start
+
+### How to Use BMad-Help
+
+Run it with just the slash command:
+
+```
+/bmad-help
+```
+
+Or combine it with a natural language query:
+
+```
+/bmad-help I have a SaaS idea and know all the features. Where do I start?
+/bmad-help What are my options for UX design?
+/bmad-help I'm stuck on the PRD workflow
+/bmad-help Show me what's been done so far
+```
+
+BMad-Help responds with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+---
+
+## When to Use This Guide
+
+Use this section when:
+- You want to understand BMad's architecture or internals
+- You need answers outside of what BMad-Help provides
+- You're researching BMad before installing
+- You want to explore the source code directly
+
+## Steps
+
+### 1. Choose Your Source
+
+| Source               | Best For                                  | Examples                     |
+| -------------------- | ----------------------------------------- | ---------------------------- |
+| **`_bmad` folder**   | How BMad works—agents, workflows, prompts | "What does the PM agent do?" |
+| **Full GitHub repo** | History, installer, architecture          | "What changed in v6?"        |
+| **`llms-full.txt`**  | Quick overview from docs                  | "Explain BMad's four phases" |
+
+The `_bmad` folder is created when you install BMad. If you don't have it yet, clone the repo instead.
+
+### 2. Point Your AI at the Source
+
+**If your AI can read files (Claude Code, Cursor, etc.):**
+
+- **BMad installed:** Point at the `_bmad` folder and ask directly
+- **Want deeper context:** Clone the [full repo](https://github.com/bmad-code-org/BMAD-METHOD)
+
+**If you use ChatGPT or Claude.ai:**
+
+Fetch `llms-full.txt` into your session:
+
+```text
+https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+
+### 3. Ask Your Question
+
+:::note[Example]
+**Q:** "Tell me the fastest way to build something with BMad"
+
+**A:** Use Quick Flow: Run `quick-spec` to write a technical specification, then `quick-dev` to implement it—skipping the full planning phases.
+:::
+
+## What You Get
+
+Direct answers about BMad—how agents work, what workflows do, why things are structured the way they are—without waiting for someone else to respond.
+
+## Tips
+
+- **Verify surprising answers** — LLMs occasionally get things wrong. Check the source file or ask on Discord.
+- **Be specific** — "What does step 3 of the PRD workflow do?" beats "How does PRD work?"
+
+## Still Stuck?
+
+Tried the LLM approach and still need help? You now have a much better question to ask.
+
+| Channel                   | Use For                                     |
+| ------------------------- | ------------------------------------------- |
+| `#bmad-method-help`       | Quick questions (real-time chat)            |
+| `help-requests` forum     | Detailed questions (searchable, persistent) |
+| `#suggestions-feedback`   | Ideas and feature requests                  |
+| `#report-bugs-and-issues` | Bug reports                                 |
+
+**Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
+
+**GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) (for clear bugs)
+
+*You!*
+        *Stuck*
+             *in the queue—*
+                      *waiting*
+                              *for who?*
+
+*The source*
+        *is there,*
+                *plain to see!*
+
+*Point*
+     *your machine.*
+              *Set it free.*
+
+*It reads.*
+        *It speaks.*
+                *Ask away—*
+
+*Why wait*
+        *for tomorrow*
+                *when you have*
+                        *today?*
+
+*—Claude*

package/docs/how-to/install-bmad.md

@@ -0,0 +1,97 @@
+---
+title: "How to Install BMad"
+description: Step-by-step guide to installing BMad in your project
+sidebar:
+  order: 1
+---
+
+Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
+
+If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md).
+
+## When to Use This
+
+- Starting a new project with BMad
+- Adding BMad to an existing codebase
+- Update the existing BMad Installation
+
+:::note[Prerequisites]
+- **Node.js** 20+ (required for the installer)
+- **Git** (recommended)
+- **AI tool** (Claude Code, Cursor, or similar)
+:::
+
+## Steps
+
+### 1. Run the Installer
+
+```bash
+npx bmad-method install
+```
+
+:::tip[Bleeding edge]
+To install the latest from the main branch (may be unstable):
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+:::
+
+### 2. Choose Installation Location
+
+The installer will ask where to install BMad files:
+
+- Current directory (recommended for new projects if you created the directory yourself and ran from within the directory)
+- Custom path
+
+### 3. Select Your AI Tools
+
+Pick which AI tools you use:
+
+- Claude Code
+- Cursor
+- Others
+
+Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
+
+### 4. Choose Modules
+
+The installer shows available modules. Select whichever ones you need — most users just want **BMad Method** (the software development module).
+
+### 5. Follow the Prompts
+
+The installer guides you through the rest — custom content, settings, etc.
+
+## What You Get
+
+```text
+your-project/
+├── _bmad/
+│   ├── bmm/            # Your selected modules
+│   │   └── config.yaml # Module settings (if you ever need to change them)
+│   ├── core/           # Required core module
+│   └── ...
+├── _bmad-output/       # Generated artifacts
+├── .claude/            # Claude Code commands (if using Claude Code)
+└── .kiro/              # Kiro steering files (if using Kiro)
+```
+
+## Verify Installation
+
+Run `/bmad-help` to verify everything works and see what to do next.
+
+**BMad-Help is your intelligent guide** that will:
+- Confirm your installation is working
+- Show what's available based on your installed modules
+- Recommend your first step
+
+You can also ask it questions:
+```
+/bmad-help I just installed, what should I do first?
+/bmad-help What are my options for a SaaS project?
+```
+
+## Troubleshooting
+
+**Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
+
+**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](./get-answers-about-bmad.md) for how to point your AI at the right sources.

package/docs/how-to/non-interactive-installation.md

@@ -0,0 +1,171 @@
+---
+title: Non-Interactive Installation
+description: Install BMad using command-line flags for CI/CD pipelines and automated deployments
+sidebar:
+  order: 2
+---
+
+Use command-line flags to install BMad non-interactively. This is useful for:
+
+## When to Use This
+
+- Automated deployments and CI/CD pipelines
+- Scripted installations
+- Batch installations across multiple projects
+- Quick installations with known configurations
+
+:::note[Prerequisites]
+Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm).
+:::
+
+## Available Flags
+
+### Installation Options
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--directory <path>` | Installation directory | `--directory ~/projects/myapp` |
+| `--modules <modules>` | Comma-separated module IDs | `--modules bmm,bmb` |
+| `--tools <tools>` | Comma-separated tool/IDE IDs (use `none` to skip) | `--tools claude-code,cursor` or `--tools none` |
+| `--custom-content <paths>` | Comma-separated paths to custom modules | `--custom-content ~/my-module,~/another-module` |
+| `--action <type>` | Action for existing installations: `install` (default), `update`, `quick-update`, or `compile-agents` | `--action quick-update` |
+
+### Core Configuration
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--user-name <name>` | Name for agents to use | System username |
+| `--communication-language <lang>` | Agent communication language | English |
+| `--document-output-language <lang>` | Document output language | English |
+| `--output-folder <path>` | Output folder path | _bmad-output |
+
+### Other Options
+
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Accept all defaults and skip prompts |
+| `-d, --debug` | Enable debug output for manifest generation |
+
+## Module IDs
+
+Available module IDs for the `--modules` flag:
+
+- `bmm` — BMad Method Master
+- `bmb` — BMad Builder
+
+Check the [BMad registry](https://github.com/bmad-code-org) for available external modules.
+
+## Tool/IDE IDs
+
+Available tool IDs for the `--tools` flag:
+
+**Preferred:** `claude-code`, `cursor`
+
+Run `npx bmad-method install` interactively once to see the full current list of supported tools, or check the [platform codes configuration](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml).
+
+## Installation Modes
+
+| Mode | Description | Example |
+|------|-------------|---------|
+| Fully non-interactive | Provide all flags to skip all prompts | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
+| Semi-interactive | Provide some flags; BMad prompts for the rest | `npx bmad-method install --directory . --modules bmm` |
+| Defaults only | Accept all defaults with `-y` | `npx bmad-method install --yes` |
+| Without tools | Skip tool/IDE configuration | `npx bmad-method install --modules bmm --tools none` |
+
+## Examples
+
+### CI/CD Pipeline Installation
+
+```bash
+#!/bin/bash
+# install-bmad.sh
+
+npx bmad-method install \
+  --directory "${GITHUB_WORKSPACE}" \
+  --modules bmm \
+  --tools claude-code \
+  --user-name "CI Bot" \
+  --communication-language English \
+  --document-output-language English \
+  --output-folder _bmad-output \
+  --yes
+```
+
+### Update Existing Installation
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action update \
+  --modules bmm,bmb,custom-module
+```
+
+### Quick Update (Preserve Settings)
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --action quick-update
+```
+
+### Installation with Custom Content
+
+```bash
+npx bmad-method install \
+  --directory ~/projects/myapp \
+  --modules bmm \
+  --custom-content ~/my-custom-module,~/another-module \
+  --tools claude-code
+```
+
+## What You Get
+
+- A fully configured `_bmad/` directory in your project
+- Compiled agents and workflows for your selected modules and tools
+- A `_bmad-output/` folder for generated artifacts
+
+## Validation and Error Handling
+
+BMad validates all provided flags:
+
+- **Directory** — Must be a valid path with write permissions
+- **Modules** — Warns about invalid module IDs (but won't fail)
+- **Tools** — Warns about invalid tool IDs (but won't fail)
+- **Custom Content** — Each path must contain a valid `module.yaml` file
+- **Action** — Must be one of: `install`, `update`, `quick-update`, `compile-agents`
+
+Invalid values will either:
+1. Show an error and exit (for critical options like directory)
+2. Show a warning and skip (for optional items like custom content)
+3. Fall back to interactive prompts (for missing required values)
+
+:::tip[Best Practices]
+- Use absolute paths for `--directory` to avoid ambiguity
+- Test flags locally before using in CI/CD pipelines
+- Combine with `-y` for truly unattended installations
+- Use `--debug` if you encounter issues during installation
+:::
+
+## Troubleshooting
+
+### Installation fails with "Invalid directory"
+
+- The directory path must exist (or its parent must exist)
+- You need write permissions
+- The path must be absolute or correctly relative to the current directory
+
+### Module not found
+
+- Verify the module ID is correct
+- External modules must be available in the registry
+
+### Custom content path invalid
+
+Ensure each custom content path:
+- Points to a directory
+- Contains a `module.yaml` file in the root
+- Has a `code` field in the `module.yaml`
+
+:::note[Still stuck?]
+Run with `--debug` for detailed output, try interactive mode to isolate the issue, or report at <https://github.com/bmad-code-org/BMAD-METHOD/issues>.
+:::

package/docs/how-to/project-context.md

@@ -0,0 +1,136 @@
+---
+title: "Manage Project Context"
+description: Create and maintain project-context.md to guide AI agents
+sidebar:
+  order: 7
+---
+
+Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
+
+:::note[Prerequisites]
+- BMad Method installed
+- Understanding of your project's technology stack and conventions
+:::
+
+## When to Use This
+
+- You have strong technical preferences before starting architecture
+- You've completed architecture and want to capture decisions for implementation
+- You're working on an existing codebase with established patterns
+- You notice agents making inconsistent decisions across stories
+
+## Step 1: Choose Your Approach
+
+**Manual creation** — Best when you know exactly what rules you want to document
+
+**Generate after architecture** — Best for capturing decisions made during solutioning
+
+**Generate for existing projects** — Best for discovering patterns in existing codebases
+
+## Step 2: Create the File
+
+### Option A: Manual Creation
+
+Create the file at `_bmad-output/project-context.md`:
+
+```bash
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Add your technology stack and implementation rules:
+
+```markdown
+---
+project_name: 'MyProject'
+user_name: 'YourName'
+date: '2026-02-15'
+sections_completed: ['technology_stack', 'critical_rules']
+---
+
+# Project Context for AI Agents
+
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand
+- Testing: Vitest, Playwright
+- Styling: Tailwind CSS
+
+## Critical Implementation Rules
+
+**TypeScript:**
+- Strict mode enabled, no `any` types
+- Use `interface` for public APIs, `type` for unions
+
+**Code Organization:**
+- Components in `/src/components/` with co-located tests
+- API calls use `apiClient` singleton — never fetch directly
+
+**Testing:**
+- Unit tests focus on business logic
+- Integration tests use MSW for API mocking
+```
+
+### Option B: Generate After Architecture
+
+Run the workflow in a fresh chat:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Option C: Generate for Existing Projects
+
+For existing projects, run:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Step 3: Verify Content
+
+Review the generated file and ensure it captures:
+
+- Correct technology versions
+- Your actual conventions (not generic best practices)
+- Rules that prevent common mistakes
+- Framework-specific patterns
+
+Edit manually to add anything missing or remove inaccuracies.
+
+## What You Get
+
+A `project-context.md` file that:
+
+- Ensures all agents follow the same conventions
+- Prevents inconsistent decisions across stories
+- Captures architecture decisions for implementation
+- Serves as a reference for your project's patterns and rules
+
+## Tips
+
+:::tip[Focus on the Unobvious]
+Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
+:::
+
+:::tip[Keep It Lean]
+This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
+:::
+
+:::tip[Update as Needed]
+Edit manually when patterns change, or re-generate after significant architecture changes.
+:::
+
+:::tip[Works for All Project Types]
+Just as useful for Quick Flow as for full BMad Method projects.
+:::
+
+## Next Steps
+
+- [**Project Context Explanation**](../explanation/project-context.md) — Learn more about how it works
+- [**Workflow Map**](../reference/workflow-map.md) — See which workflows load project context