From 5042a895de6e9f14b922147ea4e80dcf5a1ca8ec Mon Sep 17 00:00:00 2001 From: Dicky Moore Date: Thu, 5 Feb 2026 12:01:57 +0000 Subject: [PATCH] Make workflow references platform-agnostic --- docs/tutorials/getting-started.md | 76 +++++++++++++++---------------- src/core/tasks/help.md | 55 +++++++--------------- 2 files changed, 52 insertions(+), 79 deletions(-) diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index 54a9b240d..1ba4780dd 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -65,11 +65,7 @@ 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. - -:::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). -::: +Open your AI IDE in the project folder. Run the `help` workflow (`bmad-help` on most platforms) to see what to do next — it detects what you've completed and recommends the next step. :::caution[Fresh Chats] Always start a fresh chat for each workflow. This prevents context limitations from causing issues. @@ -82,29 +78,29 @@ Work through phases 1-3. **Use fresh chats for each workflow.** ### Phase 1: Analysis (Optional) All workflows in this phase are optional: -- **brainstorming** (`/bmad-brainstorming`) — Guided ideation -- **research** (`/bmad-bmm-research`) — Market and technical research -- **create-product-brief** (`/bmad-bmm-create-product-brief`) — Recommended foundation document +- **brainstorming** — Guided ideation +- **research** — Market and technical research +- **create-product-brief** — Recommended foundation document ### Phase 2: Planning (Required) **For BMad Method and Enterprise tracks:** -1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run the `prd` workflow (`/bmad-bmm-create-prd`) +1. Load the **PM agent** in a new chat +2. Run the `prd` workflow 3. Output: `PRD.md` **For Quick Flow track:** -- Use the `quick-spec` workflow (`/bmad-bmm-quick-spec`) instead of PRD, then skip to implementation +- Use the `quick-spec` workflow instead of PRD, then skip to implementation :::note[UX Design (Optional)] -If your project has a user interface, load the **UX-Designer agent** (`/bmad-agent-bmm-ux-designer`) and run the UX design workflow (`/bmad-bmm-create-ux-design`) after creating your PRD. +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 (BMad Method/Enterprise) **Create Architecture** -1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `create-architecture` (`/bmad-bmm-create-architecture`) +1. Load the **Architect agent** in a new chat +2. Run `create-architecture` 3. Output: Architecture document with technical decisions **Create Epics and Stories** @@ -113,13 +109,13 @@ If your project has a user interface, load the **UX-Designer agent** (`/bmad-age Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down. ::: -1. Load the **PM agent** (`/bmad-agent-bmm-pm`) in a new chat -2. Run `create-epics-and-stories` (`/bmad-bmm-create-epics-and-stories`) +1. Load the **PM agent** in a new chat +2. Run `create-epics-and-stories` 3. The workflow uses both PRD and Architecture to create technically-informed stories **Implementation Readiness Check** *(Highly Recommended)* -1. Load the **Architect agent** (`/bmad-agent-bmm-architect`) in a new chat -2. Run `check-implementation-readiness` (`/bmad-bmm-check-implementation-readiness`) +1. Load the **Architect agent** in a new chat +2. Run `check-implementation-readiness` 3. Validates cohesion across all planning documents ## Step 2: Build Your Project @@ -128,19 +124,19 @@ Once planning is complete, move to implementation. **Each workflow should run in ### Initialize Sprint Planning -Load the **SM agent** (`/bmad-agent-bmm-sm`) and run `sprint-planning` (`/bmad-bmm-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories. +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 | Command | Purpose | -| ---- | ----- | -------------- | -------------------------- | ---------------------------------- | -| 1 | SM | `create-story` | `/bmad-bmm-create-story` | Create story file from epic | -| 2 | DEV | `dev-story` | `/bmad-bmm-dev-story` | Implement the story | -| 3 | DEV | `code-review` | `/bmad-bmm-code-review` | Quality validation *(recommended)* | +| 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** (`/bmad-agent-bmm-sm`) and run `retrospective` (`/bmad-bmm-retrospective`). +After completing all stories in an epic, load the **SM agent** and run `retrospective`. ## What You've Accomplished @@ -166,17 +162,17 @@ your-project/ ## Quick Reference -| Workflow | Command | Agent | Purpose | -| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ | -| `help` | `/bmad-help` | Any | Get guidance on what to do next | -| `prd` | `/bmad-bmm-create-prd` | PM | Create Product Requirements Document | -| `create-architecture` | `/bmad-bmm-create-architecture` | Architect | Create architecture document | -| `create-epics-and-stories` | `/bmad-bmm-create-epics-and-stories` | PM | Break down PRD into epics | -| `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion | -| `sprint-planning` | `/bmad-bmm-sprint-planning` | SM | Initialize sprint tracking | -| `create-story` | `/bmad-bmm-create-story` | SM | Create a story file | -| `dev-story` | `/bmad-bmm-dev-story` | DEV | Implement a story | -| `code-review` | `/bmad-bmm-code-review` | DEV | Review implemented code | +| Workflow | Agent | Purpose | +| -------------------------------- | --------- | ------------------------------------ | +| `help` | Any | Get guidance on what to do next | +| `prd` | PM | Create Product Requirements Document | +| `create-architecture` | Architect | Create architecture document | +| `create-epics-and-stories` | PM | Break down PRD into epics | +| `check-implementation-readiness` | Architect | Validate planning cohesion | +| `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 @@ -184,10 +180,10 @@ your-project/ Only for BMad Method and Enterprise tracks. Quick Flow skips from tech-spec to implementation. **Can I change my plan later?** -Yes. The SM agent has a `correct-course` workflow (`/bmad-bmm-correct-course`) for handling scope changes. +Yes. The SM agent has a `correct-course` workflow for handling scope changes. **What if I want to brainstorm first?** -Load the Analyst agent (`/bmad-agent-bmm-analyst`) and run `brainstorming` (`/bmad-brainstorming`) before starting your PRD. +Load the Analyst agent and run `brainstorming` before starting your PRD. **Do I need to follow a strict order?** Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above. @@ -196,14 +192,14 @@ Not strictly. Once you learn the flow, you can run workflows directly using the - **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 +- **Stuck?** — Run `help` to see what to do next ## Key Takeaways :::tip[Remember These] - **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 +- **Use `help` when stuck** — It detects your progress and suggests next steps ::: Ready to start? Install BMad and let the agents guide you through your first project. diff --git a/src/core/tasks/help.md b/src/core/tasks/help.md index c3c3fab11..e797d4fdc 100644 --- a/src/core/tasks/help.md +++ b/src/core/tasks/help.md @@ -1,11 +1,12 @@ --- name: help description: Get unstuck by showing what workflow steps come next or answering questions about what to do +standalone: true --- # Task: BMAD Help -## ROUTING RULES +## KEY RULES - **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) @@ -14,26 +15,6 @@ description: Get unstuck by showing what workflow steps come next or answering q - **`required=true` blocks progress** — Required workflows must complete before proceeding to later phases - **Artifacts reveal completion** — Search resolved output paths for `outputs` patterns, fuzzy-match found files to workflow rows -## DISPLAY RULES - -### Command-Based Workflows -When `command` field has a value: -- Show the command prefixed with `/` (e.g., `/bmad-bmm-create-prd`) - -### Agent-Based Workflows -When `command` field is empty: -- User loads agent first via `/agent-command` -- Then invokes by referencing the `code` field or describing the `name` field -- Do NOT show a slash command — show the code value and agent load instruction instead - -Example presentation for empty command: -``` -Explain Concept (EC) -Load: /tech-writer, then ask to "EC about [topic]" -Agent: Tech Writer -Description: Create clear technical explanations with examples... -``` - ## MODULE DETECTION - **Empty `module` column** → universal tools (work across all modules) @@ -44,42 +25,38 @@ Detect the active module from conversation context, recent workflows, or user qu ## INPUT ANALYSIS Determine what was just completed: -- Explicit completion stated by user -- Workflow completed in current conversation -- Artifacts found matching `outputs` patterns -- If `index.md` exists, read it for additional context +- Did someone state they completed something? Proceed as if that was the input. +- Was a workflow just completed in this conversation? Proceed as if that was the input. +- Search resolved artifact locations for files; fuzzy-match to workflow `outputs` patterns. +- If an `index.md` exists, read it for additional context. - If still unclear, ask: "What workflow did you most recently complete?" ## EXECUTION 1. **Load catalog** — Load `{project-root}/_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. +2. **Resolve output locations** — 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. -3. **Ground in project knowledge** — If `project_knowledge` resolves to an existing path, read available documentation files (architecture docs, project overview, tech stack references) for grounding context. Use discovered project facts when composing any project-specific output. Never fabricate project-specific details — if documentation is unavailable, state so. +3. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. -4. **Detect active module** — Use MODULE DETECTION above +4. **Detect active module** — Use MODULE DETECTION above to determine which module the user is working in. -5. **Analyze input** — Task may provide a workflow name/code, conversational phrase, or nothing. Infer what was just completed using INPUT ANALYSIS above. +5. **Present recommendations** — Show next steps based on completed workflows, phase/sequence ordering (KEY RULES), and artifact detection. Format per the following -6. **Present recommendations** — Show next steps based on: - - Completed workflows detected - - Phase/sequence ordering (ROUTING RULES) - - Artifact presence +## RECOMMENDED OUTPUT FORMAT **Optional items first** — List optional workflows until a required step is reached **Required items next** — List the next required workflow - - For each item, apply DISPLAY RULES above and include: + For each item show: - Workflow **name** - - **Command** OR **Code + Agent load instruction** (per DISPLAY RULES) + - **Command** (use the catalog command name; present it in your platform's command format, e.g., `bmad-example-build-prototype`) - **Agent** title and display name from the CSV (e.g., "🎨 Alex (Designer)") - Brief **description** -7. **Additional guidance to convey**: - - Present all output in `{communication_language}` + ### Additional response output guidance to convey: - Run each workflow in a **fresh context window** + - Load the agent using the platform's command format for `agent-command`, or run the workflow command directly - For **validation workflows**: recommend using a different high-quality LLM if available - For conversational requests: match the user's tone while presenting clearly -8. Return to the calling process after presenting recommendations. +6. Return to the calling process after presenting recommendations.