Compare commits
21 Commits
eb587ff337
...
6ffac88631
| Author | SHA1 | Date |
|---|---|---|
Tolga Karatas
|
6ffac88631 | |
Brian Madison
|
1782e97731 | |
|
Brian Madison
|
9247146397 | |
|
Brian Madison
|
c8481c21c3 | |
|
Tolga Karatas
|
8bb2615561 | |
|
Tolga Karatas
|
d97b9b9cf9 | |
|
Tolga Karatas
|
3aebb87ab8 | |
|
Tolga Karatas
|
5c924b3af1 | |
|
Tolga Karatas
|
66bae0ece4 | |
|
Tolga Karatas
|
e8f76504af | |
|
Tolga Karatas
|
e0b1b7cd9d | |
|
Tolga Karatas
|
2159182fdf | |
|
Tolga Karatas
|
bb1b470080 | |
|
Tolga Karatas
|
834b417460 | |
|
Tolga Karatas
|
d50b7c13dc | |
|
Tolga Karatas
|
a351874068 | |
|
Tolga Karatas
|
f7fd90297e | |
|
Tolga Karatas
|
b75f3fbefd | |
|
Tolga Karatas
|
c892eaa00c | |
|
Tolga Karatas
|
124b7164bd | |
|
Tolga Karatas
|
378f96cd43 |
|
|
@ -42,7 +42,7 @@ _bmad/_config/agents/
|
|||
Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
|
||||
|
||||
| Section | Behavior | Purpose |
|
||||
| ------------------- | ------------ | ---------------------------------------------- |
|
||||
| ------------------ | -------- | ----------------------------------------------- |
|
||||
| `agent.metadata` | Replaces | Override the agent's display name |
|
||||
| `persona` | Replaces | Set role, identity, style, and principles |
|
||||
| `memories` | Appends | Add persistent context the agent always recalls |
|
||||
|
|
@ -96,7 +96,7 @@ Add custom entries to the agent's display menu. Each item needs a `trigger`, a t
|
|||
```yaml
|
||||
menu:
|
||||
- trigger: my-workflow
|
||||
workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
|
||||
workflow: 'my-custom/workflows/my-workflow.yaml'
|
||||
description: My custom workflow
|
||||
- trigger: deploy
|
||||
action: '#deploy-prompt'
|
||||
|
|
@ -137,7 +137,7 @@ npx bmad-method install
|
|||
The installer detects the existing installation and offers these options:
|
||||
|
||||
| Option | What It Does |
|
||||
| --------------------- | ------------------------------------------------------------------- |
|
||||
| ---------------------------- | ------------------------------------------------------------------- |
|
||||
| **Quick Update** | Updates all modules to the latest version and recompiles all agents |
|
||||
| **Recompile Agents** | Applies customizations only, without updating module files |
|
||||
| **Modify BMad Installation** | Full installation flow for adding or removing modules |
|
||||
|
|
|
|||
|
|
@ -59,9 +59,21 @@ For complex projects, consider using the `document-project` workflow. It offers
|
|||
|
||||
## Step 3: Get Help
|
||||
|
||||
Get help to know what to do next based on your unique needs
|
||||
### BMad-Help: Your Starting Point
|
||||
|
||||
Run `bmad-help` to get guidance when you are not sure what to do next.
|
||||
**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
|
||||
|
||||
|
|
|
|||
|
|
@ -5,17 +5,48 @@ sidebar:
|
|||
order: 4
|
||||
---
|
||||
|
||||
If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
|
||||
## Start Here: BMad-Help
|
||||
|
||||
## When to Use This
|
||||
**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.
|
||||
|
||||
- You have a question about how BMad works or what to do next with BMad
|
||||
- You want to understand a specific agent or workflow
|
||||
- You need quick answers without waiting for Discord
|
||||
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
|
||||
|
||||
:::note[Prerequisites]
|
||||
An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad installed in your project or access to the GitHub repo.
|
||||
:::
|
||||
### 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
|
||||
|
||||
|
|
|
|||
|
|
@ -79,7 +79,18 @@ your-project/
|
|||
|
||||
## Verify Installation
|
||||
|
||||
Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,11 @@ If you're comfortable working with AI coding assistants like Claude, Cursor, or
|
|||
The fastest way to understand BMad is to try it.
|
||||
|
||||
- **[Get Started with BMad](./tutorials/getting-started.md)** — Install and understand how BMad works
|
||||
- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management.
|
||||
- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management
|
||||
|
||||
:::tip[Just Want to Dive In?]
|
||||
Install BMad and run `/bmad-help` — it will guide you through everything based on your project and installed modules.
|
||||
:::
|
||||
|
||||
## How to Use These Docs
|
||||
|
||||
|
|
|
|||
|
|
@ -103,9 +103,29 @@ See [Workflow Map](./workflow-map.md) for the complete workflow reference organi
|
|||
|
||||
Tasks and tools are standalone operations that do not require an agent or workflow context.
|
||||
|
||||
#### BMad-Help: Your Intelligent Guide
|
||||
|
||||
**`/bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that:
|
||||
|
||||
- **Inspects your project** to see what's already been done
|
||||
- **Understands natural language queries** — ask questions in plain English
|
||||
- **Varies by installed modules** — shows options based on what you have
|
||||
- **Auto-invokes after workflows** — every workflow ends with clear next steps
|
||||
- **Recommends the first required task** — no guessing where to start
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
/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
|
||||
```
|
||||
|
||||
#### Other Tasks and Tools
|
||||
|
||||
| Example command | Purpose |
|
||||
| --- | --- |
|
||||
| `/bmad-help` | Context-aware guidance and next-step recommendations |
|
||||
| `/bmad-shard-doc` | Split a large markdown file into smaller sections |
|
||||
| `/bmad-index-docs` | Index project documentation |
|
||||
| `/bmad-editorial-review-prose` | Review document prose quality |
|
||||
|
|
|
|||
|
|
@ -24,54 +24,52 @@ Final important note: Every workflow below can be run directly with your tool of
|
|||
Explore the problem space and validate ideas before committing to planning.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ---------------------- | -------------------------------------------------------------------------- | ------------------------- |
|
||||
| `brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
|
||||
| `research` | Validate market, technical, or domain assumptions | Research findings |
|
||||
| `create-product-brief` | Capture strategic vision | `product-brief.md` |
|
||||
| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
|
||||
| `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
|
||||
| `bmad-bmm-research` | Validate market, technical, or domain assumptions | Research findings |
|
||||
| `bmad-bmm-create-product-brief` | Capture strategic vision | `product-brief.md` |
|
||||
|
||||
## Phase 2: Planning
|
||||
|
||||
Define what to build and for whom.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ------------------ | ---------------------------------------- | ------------ |
|
||||
| `create-prd` | Define requirements (FRs/NFRs) | `PRD.md` |
|
||||
| `create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
|
||||
| --------------------------- | ---------------------------------------- | ------------ |
|
||||
| `bmad-bmm-create-prd` | Define requirements (FRs/NFRs) | `PRD.md` |
|
||||
| `bmad-bmm-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
|
||||
|
||||
## Phase 3: Solutioning
|
||||
|
||||
Decide how to build it and break work into stories.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| -------------------------------- | ------------------------------------------ | --------------------------- |
|
||||
| `create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs |
|
||||
| `create-epics-and-stories` | Break requirements into implementable work | Epic files with stories |
|
||||
| `check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision |
|
||||
| ----------------------------------------- | ------------------------------------------ | --------------------------- |
|
||||
| `bmad-bmm-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs |
|
||||
| `bmad-bmm-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories |
|
||||
| `bmad-bmm-check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision |
|
||||
|
||||
## Phase 4: Implementation
|
||||
|
||||
Build it, one story at a time.
|
||||
Build it, one story at a time. Coming soon, full phase 4 automation!
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ----------------- | -------------------------------------- | ----------------------------- |
|
||||
| `sprint-planning` | Initialize tracking (once per project) | `sprint-status.yaml` |
|
||||
| `create-story` | Prepare next story for implementation | `story-[slug].md` |
|
||||
| `dev-story` | Implement the story | Working code + tests |
|
||||
| `automate` (QA) | Generate tests for existing features | Test suite |
|
||||
| `code-review` | Validate implementation quality | Approved or changes requested |
|
||||
| `correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing |
|
||||
| `retrospective` | Review after epic completion | Lessons learned |
|
||||
|
||||
**Quinn (QA Agent):** Built-in QA agent for test automation. Trigger with `QA` or `bmad-bmm-qa-automate`. Generates standard API and E2E tests using your project's test framework. Beginner-friendly, no configuration needed. For advanced test strategy, install [Test Architect (TEA)](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) module.
|
||||
| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- |
|
||||
| `bmad-bmm-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle) | `sprint-status.yaml` |
|
||||
| `bmad-bmm-create-story` | Prepare next story for implementation | `story-[slug].md` |
|
||||
| `bmad-bmm-dev-story` | Implement the story | Working code + tests |
|
||||
| `bmad-bmm-code-review` | Validate implementation quality | Approved or changes requested |
|
||||
| `bmad-bmm-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing |
|
||||
| `bmad-bmm-automate` | Generate tests for existing features - Use after a full epic is complete | End to End UI Focused Test suite |
|
||||
| `bmad-bmm-retrospective` | Review after epic completion | Lessons learned |
|
||||
|
||||
## Quick Flow (Parallel Track)
|
||||
|
||||
Skip phases 1-3 for small, well-understood work.
|
||||
|
||||
| Workflow | Purpose | Produces |
|
||||
| ------------ | ------------------------------------------ | --------------------------------------------- |
|
||||
| `quick-spec` | Define an ad-hoc change | `tech-spec.md` (story file for small changes) |
|
||||
| `quick-dev` | Implement from spec or direct instructions | Working code + tests |
|
||||
| --------------------- | ------------------------------------------ | --------------------------------------------- |
|
||||
| `bmad-bmm-quick-spec` | Define an ad-hoc change | `tech-spec.md` (story file for small changes) |
|
||||
| `bmad-bmm-quick-dev` | Implement from spec or direct instructions | Working code + tests |
|
||||
|
||||
## Context Management
|
||||
|
||||
|
|
@ -80,43 +78,12 @@ Each document becomes context for the next phase. The PRD tells the architect wh
|
|||
### Project Context
|
||||
|
||||
:::tip[Recommended]
|
||||
Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows.
|
||||
Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows. This optional file can be generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats important to keep aligned with current conventions.
|
||||
:::
|
||||
|
||||
**When to create it:**
|
||||
|
||||
| Scenario | Approach |
|
||||
|----------|----------|
|
||||
| Before architecture (manual) | Document technical preferences you want the architect to respect |
|
||||
| After architecture | Generate it to capture decisions made during solutioning |
|
||||
| Existing projects | Run `generate-project-context` to discover established patterns |
|
||||
| Quick Flow | Create before `quick-dev` to ensure consistent implementation |
|
||||
|
||||
**How to create it:**
|
||||
|
||||
- **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules
|
||||
- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase
|
||||
|
||||
**What workflows load it:**
|
||||
|
||||
| Workflow | Purpose |
|
||||
|----------|---------|
|
||||
| `create-architecture` | Respects technical preferences when designing |
|
||||
| `create-story` | Informs story creation with project patterns |
|
||||
| `dev-story` | Guides implementation decisions |
|
||||
| `code-review` | Validates against project standards |
|
||||
| `quick-dev` | Applies patterns when implementing |
|
||||
|
||||
[**Learn more about project-context.md**](../explanation/project-context.md)
|
||||
|
||||
### Additional Context by Workflow
|
||||
|
||||
Beyond `project-context.md`, each workflow loads specific documents:
|
||||
|
||||
| Workflow | Also Loads |
|
||||
|----------|------------|
|
||||
| `create-story` | epics, PRD, architecture, UX |
|
||||
| `dev-story` | story file |
|
||||
| `code-review` | architecture, story file |
|
||||
| `quick-spec` | planning docs (if exist) |
|
||||
| `quick-dev` | tech-spec |
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ Build software faster using AI-powered workflows with specialized agents that gu
|
|||
## What You'll Learn
|
||||
|
||||
- Install and initialize BMad Method for a new project
|
||||
- Use **BMad-Help** — your intelligent guide that knows what to do next
|
||||
- Choose the right planning track for your project size
|
||||
- Progress through phases from requirements to working code
|
||||
- Use agents and workflows effectively
|
||||
|
|
@ -19,11 +20,46 @@ Build software faster using AI-powered workflows with specialized agents that gu
|
|||
- **A project idea** — Even a simple one works for learning
|
||||
:::
|
||||
|
||||
:::tip[Quick Path]
|
||||
:::tip[The Easiest Path]
|
||||
**Install** → `npx bmad-method install`
|
||||
**Plan** → PM creates PRD, Architect creates architecture
|
||||
**Build** → SM manages sprints, DEV implements stories
|
||||
**Fresh chats** for each workflow to avoid context issues.
|
||||
**Ask** → `/bmad-help what should I do first?`
|
||||
**Build** → Let BMad-Help guide you workflow by workflow
|
||||
:::
|
||||
|
||||
## Meet BMad-Help: Your Intelligent Guide
|
||||
|
||||
**BMad-Help is the fastest way to get started with BMad.** You don't need to memorize workflows or phases — just ask, and BMad-Help will:
|
||||
|
||||
- **Inspect your project** to see what's already been done
|
||||
- **Show your options** based on which modules you have installed
|
||||
- **Recommend what's next** — including the first required task
|
||||
- **Answer questions** like "I have a SaaS idea, where do I start?"
|
||||
|
||||
### How to Use BMad-Help
|
||||
|
||||
Run it in your AI IDE with just the slash command:
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
```
|
||||
|
||||
Or combine it with a question for context-aware guidance:
|
||||
|
||||
```
|
||||
/bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
|
||||
```
|
||||
|
||||
BMad-Help will respond with:
|
||||
- What's recommended for your situation
|
||||
- What the first required task is
|
||||
- What the rest of the process looks like
|
||||
|
||||
### It Powers Workflows Too
|
||||
|
||||
BMad-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
|
||||
|
||||
:::tip[Start Here]
|
||||
After installing BMad, run `/bmad-help` immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
|
||||
:::
|
||||
|
||||
## Understanding BMad
|
||||
|
|
@ -65,7 +101,15 @@ The installer creates two folders:
|
|||
- `_bmad/` — agents, workflows, tasks, and configuration
|
||||
- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
|
||||
|
||||
Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
|
||||
:::tip[Your Next Step]
|
||||
Open your AI IDE in the project folder and run:
|
||||
|
||||
```
|
||||
/bmad-help
|
||||
```
|
||||
|
||||
BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
|
||||
:::
|
||||
|
||||
:::note[How to Load Agents and Run Workflows]
|
||||
Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent).
|
||||
|
|
@ -176,8 +220,8 @@ your-project/
|
|||
## Quick Reference
|
||||
|
||||
| Workflow | Command | Agent | Purpose |
|
||||
| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
|
||||
| `help` | `/bmad-help` | Any | Get guidance on what to do next |
|
||||
| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- |
|
||||
| **`help`** ⭐ | `/bmad-help` | Any | **Your intelligent guide — ask anything!** |
|
||||
| `prd` | `/bmad-bmm-create-prd` | PM | Create Product Requirements Document |
|
||||
| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | Create architecture document |
|
||||
| `generate-project-context` | `/bmad-bmm-generate-project-context` | Analyst | Create project context file |
|
||||
|
|
@ -204,16 +248,26 @@ Not strictly. Once you learn the flow, you can run workflows directly using the
|
|||
|
||||
## Getting Help
|
||||
|
||||
:::tip[First Stop: BMad-Help]
|
||||
**Run `/bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
|
||||
- "What should I do after installing?"
|
||||
- "I'm stuck on workflow X"
|
||||
- "What are my options for Y?"
|
||||
- "Show me what's been done so far"
|
||||
|
||||
BMad-Help inspects your project, detects what you've completed, and tells you exactly what to do next.
|
||||
:::
|
||||
|
||||
- **During workflows** — Agents guide you with questions and explanations
|
||||
- **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
|
||||
- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
:::tip[Remember These]
|
||||
- **Start with `/bmad-help`** — Your intelligent guide that knows your project and options
|
||||
- **Always use fresh chats** — Start a new chat for each workflow
|
||||
- **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
|
||||
- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps
|
||||
- **BMad-Help runs automatically** — Every workflow ends with guidance on what's next
|
||||
:::
|
||||
|
||||
Ready to start? Install BMad and let the agents guide you through your first project.
|
||||
Ready to start? Install BMad, run `/bmad-help`, and let your intelligent guide lead the way.
|
||||
|
|
|
|||
|
|
@ -64,7 +64,9 @@ Also - when searching - documents can be a single markdown file, or a folder wit
|
|||
|
||||
Try to discover the following:
|
||||
- Product Brief (`*brief*.md`)
|
||||
- Research Documents (`*prd*.md`)
|
||||
- PRD (`*prd*.md`) - PRIMARY input: contains FRs and NFRs the UX must address
|
||||
- Architecture Document (`*architecture*.md`) - Contains technical constraints that affect UX decisions (API limits, platform requirements, performance budgets)
|
||||
- StRS (`*strs*.md`) - Enterprise track: contains user profiles and operational scenarios
|
||||
- Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.)
|
||||
- Project Context (`**/project-context.md`)
|
||||
|
||||
|
|
@ -98,8 +100,10 @@ Report what was found:
|
|||
|
||||
**Documents Found:**
|
||||
|
||||
- PRD: {number of PRD files loaded or "None found"}
|
||||
- PRD: {number of PRD files loaded or "None found"} ← Key: FRs define what UX must address
|
||||
- Product brief: {number of brief files loaded or "None found"}
|
||||
- Architecture: {found or "None found"} ← Key: Technical constraints that affect UX
|
||||
- StRS: {found or "None found"} ← Enterprise: User profiles and scenarios
|
||||
- Other context: {number of other files loaded or "None found"}
|
||||
|
||||
**Files loaded:** {list of specific file names or "No additional documents found"}
|
||||
|
|
|
|||
|
|
@ -227,7 +227,7 @@ Show the generated responsive and accessibility content and present choices:
|
|||
|
||||
- Append the final content to `{planning_artifacts}/ux-design-specification.md`
|
||||
- Update frontmatter: append step to end of stepsCompleted array
|
||||
- Load `./step-14-complete.md`
|
||||
- Load `./step-13b-requirements-validation.md`
|
||||
|
||||
## APPEND TO DOCUMENT:
|
||||
|
||||
|
|
@ -259,6 +259,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 `./step-14-complete.md` to finalize the UX design workflow.
|
||||
After user selects 'C' and content is saved to document, load `./step-13b-requirements-validation.md` to finalize the UX design workflow.
|
||||
|
||||
Remember: Do NOT proceed to step-14 until user explicitly selects 'C' from the A/P/C menu and content is saved!
|
||||
|
|
|
|||
|
|
@ -0,0 +1,176 @@
|
|||
# Step 13b: Requirements Validation & Handoff Checklist
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
- 🎯 This step validates UX design completeness against PRD requirements
|
||||
- 📋 YOU ARE A VALIDATION FACILITATOR for this step
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Load PRD and validate requirements coverage
|
||||
- 🎯 Load Architecture document and check constraint alignment
|
||||
- ⚠️ Present findings with A/P/C menu
|
||||
- 💾 ONLY save when user chooses C (Continue)
|
||||
- 📖 Update output file frontmatter, adding this step to stepsCompleted
|
||||
- 🚫 FORBIDDEN to load next step until C is selected
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Complete UX design specification from all previous steps is available
|
||||
- PRD (if loaded at init) contains FRs/NFRs that UX must address
|
||||
- Architecture (if loaded at init) contains technical constraints
|
||||
- Focus on validating coverage and creating handoff artifacts
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Validate that the UX design addresses PRD requirements, respects architecture constraints, and prepare handoff artifacts for downstream workflows (Architecture, Epics & Stories).
|
||||
|
||||
## VALIDATION & HANDOFF SEQUENCE:
|
||||
|
||||
### 1. Requirements Coverage Validation
|
||||
|
||||
If PRD was loaded during initialization:
|
||||
|
||||
**Extract PRD Functional Requirements:**
|
||||
- Load the PRD and find all FRs
|
||||
- For each FR, determine if the UX design addresses it
|
||||
|
||||
**Create Coverage Matrix:**
|
||||
- Map each FR to UX design elements (user journeys, components, patterns)
|
||||
- Identify FRs NOT addressed by UX design
|
||||
- For unaddressed FRs, determine if they are:
|
||||
- Non-UI FRs (backend-only, no UX needed) → Mark as N/A
|
||||
- Missing from UX design → Flag as GAP
|
||||
|
||||
**Present to user:**
|
||||
"I've validated your UX design against the PRD requirements:
|
||||
|
||||
**FR Coverage:**
|
||||
|
||||
| FR | Description | UX Element | Status |
|
||||
|----|-------------|-----------|--------|
|
||||
| FR1 | [desc] | [journey/component/pattern] | ✅ Covered |
|
||||
| FR5 | [desc] | - | ⚠️ Gap (UI feature) |
|
||||
| FR8 | [desc] | N/A | ➖ Backend only |
|
||||
|
||||
**Coverage: [X]% of UI-relevant FRs addressed**
|
||||
**Gaps found: [count]**"
|
||||
|
||||
If PRD was NOT loaded:
|
||||
- Note that requirements validation could not be performed
|
||||
- Recommend running this check later when PRD is available
|
||||
|
||||
### 2. Architecture Constraint Alignment
|
||||
|
||||
If Architecture document was loaded:
|
||||
|
||||
**Check for conflicts:**
|
||||
- API constraints vs. UX interaction patterns (e.g., real-time updates vs. REST-only API)
|
||||
- Platform constraints vs. responsive strategy
|
||||
- Performance budgets vs. animation/interaction complexity
|
||||
- Data model constraints vs. information architecture
|
||||
|
||||
**Present any conflicts found:**
|
||||
- Conflict description
|
||||
- UX design assumption
|
||||
- Architecture constraint
|
||||
- Suggested resolution
|
||||
|
||||
If Architecture was NOT loaded:
|
||||
- Note that constraint validation could not be performed
|
||||
|
||||
### 3. Downstream Handoff Checklist
|
||||
|
||||
Create handoff information for downstream workflows:
|
||||
|
||||
**For Architecture Workflow (Winston):**
|
||||
- [ ] UX interaction patterns that require specific API design
|
||||
- [ ] Real-time requirements identified in UX (WebSocket, SSE, polling)
|
||||
- [ ] Data requirements from form designs and user flows
|
||||
- [ ] Performance requirements from animation/interaction specs
|
||||
|
||||
**For Epics & Stories Workflow (John):**
|
||||
- [ ] User journey → FR mapping (which journeys implement which FRs)
|
||||
- [ ] Component complexity estimates (simple, moderate, complex)
|
||||
- [ ] Design dependencies between components
|
||||
- [ ] Phasing recommendations (what can be MVP vs. later)
|
||||
|
||||
**Design Decision Rationale:**
|
||||
- Key design decisions and WHY they were made
|
||||
- Alternatives considered and rejected (with reasons)
|
||||
- Assumptions made during design
|
||||
|
||||
### 4. Generate Validation & Handoff Content
|
||||
|
||||
Append to the document:
|
||||
|
||||
```markdown
|
||||
## Requirements Validation
|
||||
|
||||
### FR Coverage Matrix
|
||||
|
||||
[Table mapping FRs to UX elements]
|
||||
|
||||
### Architecture Constraint Alignment
|
||||
|
||||
[Any conflicts found and resolutions, or "No architecture document loaded"]
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Architecture Handoff
|
||||
|
||||
[UX constraints and requirements for architecture decisions]
|
||||
|
||||
### Epics & Stories Handoff
|
||||
|
||||
[User journey → FR mapping, complexity estimates, phasing recommendations]
|
||||
|
||||
### Design Decision Rationale
|
||||
|
||||
[Key decisions with reasoning for downstream teams]
|
||||
```
|
||||
|
||||
### 5. Present MENU OPTIONS
|
||||
|
||||
Present the validation findings and handoff checklist, then display menu:
|
||||
- Show coverage matrix highlights
|
||||
- Show any architecture conflicts
|
||||
- Show handoff readiness
|
||||
|
||||
Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Complete Workflow (Step 14)"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF A: Read fully and follow Advanced Elicitation, process, ask acceptance, update or keep, redisplay
|
||||
- IF P: Read fully and follow Party Mode, process, ask acceptance, update or keep, redisplay
|
||||
- IF C: Append to output document, update frontmatter, then read fully and follow: `./step-14-complete.md`
|
||||
- IF Any other: help user respond, then redisplay menu
|
||||
|
||||
## APPEND TO DOCUMENT:
|
||||
|
||||
When user selects 'C', append the content directly to the document.
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
✅ PRD FR coverage validated (if PRD available)
|
||||
✅ Architecture constraints checked (if architecture available)
|
||||
✅ FR → UX element mapping created
|
||||
✅ Gaps identified with clear categorization
|
||||
✅ Handoff checklist prepared for Architecture and Epics workflows
|
||||
✅ Design decision rationale documented
|
||||
✅ A/P/C menu presented and handled correctly
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
❌ Not loading PRD for validation when it was discovered at init
|
||||
❌ Claiming full coverage without systematic check
|
||||
❌ Not creating handoff artifacts for downstream workflows
|
||||
❌ Not documenting design decision rationale
|
||||
❌ Marking non-UI FRs as gaps (they should be N/A)
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After user selects 'C' and content is saved, load `./step-14-complete.md` to complete the workflow.
|
||||
|
||||
Remember: Do NOT proceed to step-14 until user explicitly selects 'C'!
|
||||
|
|
@ -8,6 +8,12 @@
|
|||
- [ ] Tests cover happy path
|
||||
- [ ] Tests cover 1-2 critical error cases
|
||||
|
||||
## Requirements Traceability (All Tracks)
|
||||
|
||||
- [ ] Each acceptance criterion has at least one test
|
||||
- [ ] Each FR has at least one test scenario defined
|
||||
- [ ] Test descriptions reference the FR or acceptance criterion they verify
|
||||
|
||||
## Test Quality
|
||||
|
||||
- [ ] All generated tests run successfully
|
||||
|
|
|
|||
|
|
@ -0,0 +1,122 @@
|
|||
# Per-Requirement Quality Checklist (ISO 29148)
|
||||
|
||||
Apply this checklist to EVERY individual requirement in StRS, SyRS, and PRD/SRS documents. Each requirement must satisfy all 9 quality criteria.
|
||||
|
||||
## The 9 Quality Criteria
|
||||
|
||||
### 1. Necessary
|
||||
|
||||
- [ ] The requirement traces to a real stakeholder need or business objective
|
||||
- [ ] Removing this requirement would leave a stakeholder need unmet
|
||||
- [ ] The requirement is not gold-plating (adding unnecessary complexity)
|
||||
|
||||
**Test:** "If we remove this requirement, would a stakeholder's need go unmet?"
|
||||
|
||||
### 2. Implementation-Free
|
||||
|
||||
- [ ] The requirement states WHAT is needed, not HOW to build it
|
||||
- [ ] No technology choices are embedded (unless it IS a design constraint)
|
||||
- [ ] No UI/UX specifics are included (unless it IS an interface requirement)
|
||||
- [ ] The requirement could be implemented in multiple different ways
|
||||
|
||||
**Test:** "Could an architect choose from 3+ different implementation approaches?"
|
||||
|
||||
### 3. Unambiguous
|
||||
|
||||
- [ ] The requirement has only ONE possible interpretation
|
||||
- [ ] No vague adjectives (good, fast, easy, user-friendly, intuitive, robust)
|
||||
- [ ] Measurable criteria are used where applicable
|
||||
- [ ] Terms are defined in the glossary or are industry-standard
|
||||
|
||||
**Test:** "Would 5 different engineers interpret this the same way?"
|
||||
|
||||
### 4. Consistent
|
||||
|
||||
- [ ] The requirement does NOT contradict any other requirement
|
||||
- [ ] Terminology is consistent with the rest of the document
|
||||
- [ ] Scope aligns with the product vision and boundaries
|
||||
- [ ] No conflicting quality attribute targets (e.g., maximum security AND minimal latency)
|
||||
|
||||
**Test:** "Does this requirement peacefully coexist with all other requirements?"
|
||||
|
||||
### 5. Complete
|
||||
|
||||
- [ ] The requirement contains enough detail to design and test against
|
||||
- [ ] All conditions and constraints are specified
|
||||
- [ ] Edge cases and boundary conditions are addressed (or explicitly deferred)
|
||||
- [ ] No TBD, TBC, or placeholder values remain
|
||||
|
||||
**Test:** "Could a developer implement this without asking clarifying questions?"
|
||||
|
||||
### 6. Singular
|
||||
|
||||
- [ ] The requirement expresses exactly ONE capability or constraint
|
||||
- [ ] No compound requirements joined by "and" or "or" (split if needed)
|
||||
- [ ] The requirement can be independently verified
|
||||
- [ ] The requirement can be independently prioritized
|
||||
|
||||
**Test:** "Can I assign a single pass/fail verdict to this requirement?"
|
||||
|
||||
### 7. Feasible
|
||||
|
||||
- [ ] The requirement is technically achievable with known technology
|
||||
- [ ] The requirement is achievable within the project's constraints (budget, timeline, team)
|
||||
- [ ] No physical impossibilities or contradictions with laws of physics/math
|
||||
- [ ] Required third-party capabilities or services are available
|
||||
|
||||
**Test:** "Can the team actually build this within the project constraints?"
|
||||
|
||||
### 8. Traceable
|
||||
|
||||
- [ ] The requirement has a unique identifier (ID)
|
||||
- [ ] The requirement's source is documented (stakeholder, regulation, business objective)
|
||||
- [ ] The requirement can be linked to downstream artifacts (design, code, tests)
|
||||
- [ ] The requirement can be linked to upstream sources (StRS, business needs)
|
||||
|
||||
**Test:** "Can I follow this requirement from origin to implementation to test?"
|
||||
|
||||
### 9. Verifiable
|
||||
|
||||
- [ ] There exists a method to prove the requirement is satisfied
|
||||
- [ ] The verification method is identified (Test, Analysis, Demonstration, Inspection)
|
||||
- [ ] Acceptance criteria are clear and objective
|
||||
- [ ] The verification can be performed within project constraints
|
||||
|
||||
**Test:** "Can I write a test or create a verification procedure for this?"
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
| # | Criterion | Key Question | Red Flags |
|
||||
|---|-----------|-------------|-----------|
|
||||
| 1 | Necessary | Would removing it leave a need unmet? | Gold-plating, nice-to-have disguised as must-have |
|
||||
| 2 | Implementation-Free | Can it be built 3+ ways? | Technology names, UI specifics, algorithm choices |
|
||||
| 3 | Unambiguous | Would 5 engineers agree? | "Good", "fast", "easy", "user-friendly", "robust" |
|
||||
| 4 | Consistent | Does it conflict with others? | Contradicting metrics, overlapping scope |
|
||||
| 5 | Complete | Can dev build without questions? | TBD, TBC, "details to follow", missing conditions |
|
||||
| 6 | Singular | Can I give one pass/fail? | "and", "or" joining two capabilities |
|
||||
| 7 | Feasible | Can the team actually build it? | Unrealistic targets, unavailable technology |
|
||||
| 8 | Traceable | Can I follow origin → test? | Missing ID, no source reference |
|
||||
| 9 | Verifiable | Can I test/prove it? | Subjective criteria, unmeasurable quality |
|
||||
|
||||
## Usage
|
||||
|
||||
**When to Apply:**
|
||||
- During PRD/SRS creation (Step 9: FR synthesis, Step 10: NFR synthesis)
|
||||
- During PRD validation (validation workflow)
|
||||
- During StRS and SyRS review steps
|
||||
- During change management (new or modified requirements)
|
||||
|
||||
**How to Apply:**
|
||||
1. Select a requirement
|
||||
2. Walk through all 9 criteria
|
||||
3. Mark any failures
|
||||
4. Fix failures before proceeding or flag for review
|
||||
5. A requirement that fails ANY criterion needs attention
|
||||
|
||||
**Scoring:**
|
||||
- 9/9: Requirement is high quality
|
||||
- 7-8/9: Minor issues, address if time permits
|
||||
- 5-6/9: Significant issues, must address before approval
|
||||
- <5/9: Requirement needs rewrite
|
||||
|
|
@ -9,6 +9,7 @@ description: Get unstuck by showing what workflow steps come next or answering q
|
|||
|
||||
- **Empty `phase` = anytime** — Universal tools work regardless of workflow state
|
||||
- **Numbered phases indicate sequence** — Phases like `1-discover` → `2-define` → `3-build` → `4-ship` flow in order (naming varies by module)
|
||||
- **Phase with no Required Steps** - If an entire phase has no required, true items, the entire phase is optional. If it is sequentially before another phase, it can be recommended, but always be clear with the use what the true next required item is.
|
||||
- **Stay in module** — Guide through the active module's workflow based on phase+sequence ordering
|
||||
- **Descriptions contain routing** — Read for alternate paths (e.g., "back to previous if fixes needed")
|
||||
- **`required=true` blocks progress** — Required workflows must complete before proceeding to later phases
|
||||
|
|
@ -52,7 +53,7 @@ Determine what was just completed:
|
|||
|
||||
## EXECUTION
|
||||
|
||||
1. **Load catalog** — Load `{project-root}/_bmad/_config/bmad-help.csv`
|
||||
1. **Load catalog** — Load `_bmad/_config/bmad-help.csv`
|
||||
|
||||
2. **Resolve output locations and config** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. Also extract `communication_language` and `project_knowledge` from each scanned module's config.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,6 +32,16 @@ modules:
|
|||
type: bmad-org
|
||||
npmPackage: bmad-game-dev-studio
|
||||
|
||||
bmad-method-audit-standards-enterprise:
|
||||
url: https://github.com/bmad-code-org/bmad-method-audit-standards-enterprise
|
||||
module-definition: src/module.yaml
|
||||
code: audit
|
||||
name: "Audit Standards Enterprise"
|
||||
description: "Standards Auditor for compliance, security auditing, traceability, and multi-standard governance"
|
||||
defaultSelected: false
|
||||
type: bmad-org
|
||||
npmPackage: bmad-method-audit-standards-enterprise
|
||||
|
||||
bmad-method-test-architecture-enterprise:
|
||||
url: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise
|
||||
module-definition: src/module.yaml
|
||||
|
|
|
|||
Loading…
Reference in New Issue