From 208f27dcdb18f6bb5ff7892500eeafa87e682227 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Fri, 26 Dec 2025 17:43:59 -0800 Subject: [PATCH 1/6] refactor: convert create-tech-spec to sharded workflow with orient-first pattern (#1185) * refactor: convert create-tech-spec to sharded workflow with orient-first pattern * docs: reposition deep exploration isolation guideline within universal code investigation section * docs: Update terminology from 'Requirement Delta' to 'Problem Statement' in step-02-investigate.md context. * Update src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../bmm/agents/quick-flow-solo-dev.agent.yaml | 2 +- .../create-tech-spec/instructions.md | 115 ----------- .../steps/step-01-understand.md | 188 ++++++++++++++++++ .../steps/step-02-investigate.md | 143 +++++++++++++ .../steps/step-03-generate.md | 127 ++++++++++++ .../create-tech-spec/steps/step-04-review.md | 172 ++++++++++++++++ .../create-tech-spec/tech-spec-template.md | 74 +++++++ .../create-tech-spec/workflow.md | 78 ++++++++ .../create-tech-spec/workflow.yaml | 28 --- .../steps/step-05-adversarial-review.md | 2 +- 10 files changed, 784 insertions(+), 145 deletions(-) delete mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md create mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md delete mode 100644 src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml diff --git a/src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml b/src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml index d052b45f..27bd0147 100644 --- a/src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml +++ b/src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml @@ -19,7 +19,7 @@ agent: menu: - trigger: TS or fuzzy match on tech-spec - workflow: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml" + exec: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md" description: "[TS] Architect a technical spec with implementation-ready stories (Required first step)" - trigger: QD or fuzzy match on quick-dev diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.md deleted file mode 100644 index 64fccf29..00000000 --- a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.md +++ /dev/null @@ -1,115 +0,0 @@ -# Create Tech-Spec - Spec Engineering for AI Development - - - -Communicate in {communication_language}, tailored to {user_skill_level} -Generate documents in {document_output_language} -Conversational spec engineering - ask questions, investigate code, produce complete spec -Spec must contain ALL context a fresh dev agent needs to implement it - - - Load and execute {advanced_elicitation}, then return to current step - Load and execute {party_mode_workflow}, then return to current step - Load and execute {quick_dev_workflow} with the tech-spec file - - - - -Greet {user_name} and ask them to describe what they want to build or change. - -Ask clarifying questions: problem, who's affected, scope, constraints, existing code? - -Check for existing context in {output_folder} and {implementation_artifacts} - - -[a] Advanced Elicitation [c] Continue [p] Party Mode - - - - - - -If brownfield: get file paths, read code, identify patterns/conventions/dependencies - -Document: tech stack, code patterns, files to modify, test patterns - - -[a] Advanced Elicitation [c] Continue [p] Party Mode - - - - - - -Create tech-spec using this structure: - -```markdown -# Tech-Spec: {title} - -**Created:** {date} -**Status:** Ready for Development - -## Overview - -### Problem Statement - -### Solution - -### Scope (In/Out) - -## Context for Development - -### Codebase Patterns - -### Files to Reference - -### Technical Decisions - -## Implementation Plan - -### Tasks - -- [ ] Task 1: Description -- [ ] Task 2: Description - -### Acceptance Criteria - -- [ ] AC 1: Given/When/Then -- [ ] AC 2: ... - -## Additional Context - -### Dependencies - -### Testing Strategy - -### Notes -``` - - - -Save to {implementation_artifacts}/tech-spec-{slug}.md - - - - - -Present spec to {user_name}, ask if it captures intent, make changes as needed - -**Tech-Spec Complete!** - -Saved to: {implementation_artifacts}/tech-spec-{slug}.md - -[a] Advanced Elicitation - refine further -[b] Begin Development (not recommended - fresh context better) -[d] Done - exit -[p] Party Mode - get feedback - -**Recommended:** Run `dev-spec {implementation_artifacts}/tech-spec-{slug}.md` in fresh context. - - -Choice (a/b/d/p): - - - - diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md new file mode 100644 index 00000000..c26a390b --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md @@ -0,0 +1,188 @@ +--- +name: 'step-01-understand' +description: 'Analyze the requirement delta between current state and what user wants to build' + +workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec' +nextStepFile: '{workflow_path}/steps/step-02-investigate.md' +skipToStepFile: '{workflow_path}/steps/step-03-generate.md' +templateFile: '{workflow_path}/tech-spec-template.md' +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +--- + +# Step 1: Analyze Requirement Delta + +**Progress: Step 1 of 4** - Next: Deep Investigation + +## RULES: + +- MUST NOT skip steps. +- MUST NOT optimize sequence. +- MUST follow exact instructions. +- MUST NOT look ahead to future steps. + +## CONTEXT: + +- Variables from `workflow.md` are available in memory. +- Focus: Define the technical requirement delta and scope. +- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2. +- Objective: Establish a verifiable delta between current state and target state. + +## SEQUENCE OF INSTRUCTIONS + +### 0. Check for Work in Progress + +a) **Before anything else, check if `{wipFile}` exists:** + +b) **IF WIP FILE EXISTS:** + +1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted` +2. Calculate progress: `lastStep = max(stepsCompleted)` +3. Present to user: + +``` +Hey {user_name}! Found a tech-spec in progress: + +**{title}** - Step {lastStep} of 4 complete + +Is this what you're here to continue? + +[y] Yes, pick up where I left off +[n] No, archive it and start something new +``` + +4. **HALT and wait for user selection.** + +a) **Menu Handling:** + +- **[y] Continue existing:** + - Jump directly to the appropriate step based on `stepsCompleted`: + - `[1]` → Load `{nextStepFile}` (Step 2) + - `[1, 2]` → Load `{skipToStepFile}` (Step 3) + - `[1, 2, 3]` → Load `{workflow_path}/steps/step-04-review.md` (Step 4) +- **[n] Archive and start fresh:** + - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md` + +### 1. Greet and Ask for Initial Request + +a) **Greet the user briefly:** + +"Hey {user_name}! What are we building today?" + +b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look. + +### 2. Quick Orient Scan + +a) **Before asking detailed questions, do a rapid scan to understand the landscape:** + +b) **Check for existing context docs:** + +- Check `{output_folder}` for planning documents (PRD, architecture, epics) +- Check for `**/project-context.md` - if it exists, skim for patterns and conventions +- Check for any existing stories or specs related to user's request + +c) **If user mentioned specific code/features, do a quick scan:** + +- Search for relevant files/classes/functions they mentioned +- Skim the structure (don't deep-dive yet - that's Step 2) +- Note: tech stack, obvious patterns, file locations + +d) **Build mental model:** + +- What's the likely landscape for this feature? +- What's the likely scope based on what you found? +- What questions do you NOW have, informed by the code? + +**This scan should take < 30 seconds. Just enough to ask smart questions.** + +### 3. Ask Informed Questions + +a) **Now ask clarifying questions - but make them INFORMED by what you found:** + +Instead of generic questions like "What's the scope?", ask specific ones like: +- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?" +- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?" +- "The epics doc mentions X - is this related?" + +**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation. + +b) **If no existing code is found:** + +- Ask about intended architecture, patterns, constraints +- Ask what similar systems they'd like to emulate + +### 4. Capture Core Understanding + +a) **From the conversation, extract and confirm:** + +- **Title**: A clear, concise name for this work +- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces) +- **Problem Statement**: What problem are we solving? +- **Solution**: High-level approach (1-2 sentences) +- **In Scope**: What's included +- **Out of Scope**: What's explicitly NOT included + +b) **Ask the user to confirm the captured understanding before proceeding.** + +### 5. Initialize WIP File + +a) **Create the tech-spec WIP file:** + +1. Copy template from `{templateFile}` +2. Write to `{wipFile}` +3. Update frontmatter with captured values: + ```yaml + --- + title: '{title}' + slug: '{slug}' + created: '{date}' + status: 'in-progress' + stepsCompleted: [1] + tech_stack: [] + files_to_modify: [] + code_patterns: [] + test_patterns: [] + --- + ``` +4. Fill in Overview section with Problem Statement, Solution, and Scope +5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery. +6. Write the file + +b) **Report to user:** + +"Created: `{wipFile}` + +**Captured:** + +- Title: {title} +- Problem: {problem_statement_summary} +- Scope: {scope_summary}" + +### 6. Present Checkpoint Menu + +a) **Display menu:** + +``` +[a] Advanced Elicitation - dig deeper into requirements +[c] Continue - proceed to next step +[p] Party Mode - bring in other experts +``` + +b) **HALT and wait for user selection.** + +#### Menu Handling: + +- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu +- **[c]**: Load and execute `{nextStepFile}` (Map Technical Constraints) +- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu + +--- + +## REQUIRED OUTPUTS: + +- MUST initialize WIP file with captured metadata. + +## VERIFICATION CHECKLIST: + +- [ ] WIP check performed FIRST before any greeting. +- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`. +- [ ] User selected [c] to continue. diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md new file mode 100644 index 00000000..a431050c --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md @@ -0,0 +1,143 @@ +--- +name: 'step-02-investigate' +description: 'Map technical constraints and anchor points within the codebase' + +workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec' +nextStepFile: '{workflow_path}/steps/step-03-generate.md' +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +--- + +# Step 2: Map Technical Constraints & Anchor Points + +**Progress: Step 2 of 4** - Next: Generate Plan + +## RULES: + +- MUST NOT skip steps. +- MUST NOT optimize sequence. +- MUST follow exact instructions. +- MUST NOT generate the full spec yet (that's Step 3). + +## CONTEXT: + +- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined. +- Focus: Map the problem statement to specific anchor points in the codebase. +- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified. +- Objective: Provide the implementation-ready ground truth for the plan. + +## SEQUENCE OF INSTRUCTIONS + +### 1. Load Current State + +**Read `{wipFile}` and extract:** + +- Problem statement and scope from Overview section +- Any context gathered in Step 1 + +### 2. Execute Investigation Path + +**Universal Code Investigation:** + +_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._ + +a) **Build on Step 1's Quick Scan** + +Review what was found in Step 1's orient scan. Then ask: + +"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?" + +b) **Read and Analyze Code** + +For each file/directory provided: + +- Read the complete file(s) +- Identify patterns, conventions, coding style +- Note dependencies and imports +- Find related test files + +**If NO relevant code is found (Clean Slate):** + +- Identify the target directory where the feature should live. +- Scan parent directories for architectural context. +- Identify standard project utilities or boilerplate that SHOULD be used. +- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist. + + +c) **Document Technical Context** + +Capture and confirm with user: + +- **Tech Stack**: Languages, frameworks, libraries +- **Code Patterns**: Architecture patterns, naming conventions, file structure +- **Files to Modify/Create**: Specific files that will need changes or new files to be created +- **Test Patterns**: How tests are structured, test frameworks used + +d) **Look for project-context.md** + +If `**/project-context.md` exists and wasn't loaded in Step 1: + +- Load it now +- Extract patterns and conventions +- Note any rules that must be followed + +### 3. Update WIP File + +**Update `{wipFile}` frontmatter:** + +```yaml +--- +# ... existing frontmatter ... +stepsCompleted: [1, 2] +tech_stack: ['{captured_tech_stack}'] +files_to_modify: ['{captured_files}'] +code_patterns: ['{captured_patterns}'] +test_patterns: ['{captured_test_patterns}'] +--- +``` + +**Update the Context for Development section:** + +Fill in: + +- Codebase Patterns (from investigation) +- Files to Reference table (files reviewed) +- Technical Decisions (any decisions made during investigation) + +**Report to user:** + +"**Context Gathered:** + +- Tech Stack: {tech_stack_summary} +- Files to Modify: {files_count} files identified +- Patterns: {patterns_summary} +- Tests: {test_patterns_summary}" + +### 4. Present Checkpoint Menu + +**Display menu:** + +``` +[a] Advanced Elicitation - explore more context +[c] Continue - proceed to Generate Spec +[p] Party Mode - bring in other experts +``` + +**HALT and wait for user selection.** + +#### Menu Handling: + +- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu +- **[c]**: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then load and execute `{nextStepFile}` +- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu + +--- + +## REQUIRED OUTPUTS: + +- MUST document technical context (stack, patterns, files identified). +- MUST update `{wipFile}` with functional context. + +## VERIFICATION CHECKLIST: + +- [ ] Technical mapping performed and documented. +- [ ] `stepsCompleted: [1, 2]` set in frontmatter. diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md new file mode 100644 index 00000000..5fbe87d0 --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md @@ -0,0 +1,127 @@ +--- +name: 'step-03-generate' +description: 'Build the implementation plan based on the technical mapping of constraints' + +workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec' +nextStepFile: '{workflow_path}/steps/step-04-review.md' +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +--- + +# Step 3: Generate Implementation Plan + +**Progress: Step 3 of 4** - Next: Review & Finalize + +## RULES: + +- MUST NOT skip steps. +- MUST NOT optimize sequence. +- MUST follow exact instructions. +- MUST NOT implement anything - just document. + +## CONTEXT: + +- Requires `{wipFile}` with defined "Overview" and "Context for Development" sections. +- Focus: Create the implementation sequence that addresses the requirement delta using the captured technical context. +- Output: Implementation-ready tasks with specific files and instructions. +- Target: Meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`. + +## SEQUENCE OF INSTRUCTIONS + +### 1. Load Current State + +**Read `{wipFile}` completely and extract:** + +- All frontmatter values +- Overview section (Problem, Solution, Scope) +- Context for Development section (Patterns, Files, Decisions) + +### 2. Generate Implementation Plan + +Generate specific implementation tasks: + +a) **Task Breakdown** + +- Each task should be a discrete, completable unit of work +- Tasks should be ordered logically (dependencies first) +- Include the specific files to modify in each task +- Be explicit about what changes to make + +b) **Task Format** + +```markdown +- [ ] Task N: Clear action description + - File: `path/to/file.ext` + - Action: Specific change to make + - Notes: Any implementation details +``` + +### 3. Generate Acceptance Criteria + +**Create testable acceptance criteria:** + +Each AC should follow Given/When/Then format: + +```markdown +- [ ] AC N: Given [precondition], when [action], then [expected result] +``` + +**Ensure ACs cover:** + +- Happy path functionality +- Error handling +- Edge cases (if relevant) +- Integration points (if relevant) + +### 4. Complete Additional Context + +**Fill in remaining sections:** + +a) **Dependencies** + +- External libraries or services needed +- Other tasks or features this depends on +- API or data dependencies + +b) **Testing Strategy** + +- Unit tests needed +- Integration tests needed +- Manual testing steps + +c) **Notes** + +- High-risk items from pre-mortem analysis +- Known limitations +- Future considerations (out of scope but worth noting) + +### 5. Write Complete Spec + +a) **Update `{wipFile}` with all generated content:** + +- Ensure all template sections are filled in +- No placeholder text remaining +- All frontmatter values current +- Update status to 'review' (NOT 'ready-for-dev' - that happens after user review in Step 4) + +b) **Update frontmatter:** + +```yaml +--- +# ... existing values ... +status: 'review' +stepsCompleted: [1, 2, 3] +--- +``` + +c) **Load and execute `{nextStepFile}` (Step 4)** + +## REQUIRED OUTPUTS: + +- Tasks MUST be specific, actionable, ordered logically, with files to modify. +- ACs MUST be testable, using Given/When/Then format. +- Status MUST be updated to 'review'. + +## VERIFICATION CHECKLIST: + +- [ ] `stepsCompleted: [1, 2, 3]` set in frontmatter. +- [ ] Spec meets the **READY FOR DEVELOPMENT** standard. diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md new file mode 100644 index 00000000..c8c41f69 --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md @@ -0,0 +1,172 @@ +--- +name: 'step-04-review' +description: 'Review and finalize the tech-spec' + +workflow_path: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec' +wipFile: '{implementation_artifacts}/tech-spec-wip.md' +--- + +# Step 4: Review & Finalize + +**Progress: Step 4 of 4** - Final Step + +## RULES: + +- MUST NOT skip steps. +- MUST NOT optimize sequence. +- MUST follow exact instructions. + +## CONTEXT: + +- Requires `{wipFile}` from Step 3. +- MUST present COMPLETE spec content. Iterate until user is satisfied. +- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`. + +## SEQUENCE OF INSTRUCTIONS + +### 1. Load and Present Complete Spec + +**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.** + +**Present to user:** + +"Here's your complete tech-spec. Please review:" + +[Display the complete spec content - all sections] + +"**Quick Summary:** + +- {task_count} tasks to implement +- {ac_count} acceptance criteria to verify +- {files_count} files to modify + +Does this capture your intent? Any changes needed?" + +### 2. Handle Review Feedback + +a) **If user requests changes:** + +- Make the requested edits to `{wipFile}` +- Re-present the affected sections +- Ask if there are more changes +- Loop until user is satisfied + +b) **If the spec does NOT meet the "Ready for Development" standard:** + +- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs). +- Propose specific improvements to reach the standard. +- Make the edits once the user agrees. + +c) **If user has questions:** + +- Answer questions about the spec +- Clarify any confusing sections +- Make clarifying edits if needed + +### 3. Finalize the Spec + +**When user confirms the spec is good AND it meets the "Ready for Development" standard:** + +a) Update `{wipFile}` frontmatter: + + ```yaml + --- + # ... existing values ... + status: 'ready-for-dev' + stepsCompleted: [1, 2, 3, 4] + --- + ``` + +b) **Rename WIP file to final filename:** + - Using the `slug` extracted in Section 1 + - Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md` + - Store this as `finalFile` for use in menus below + +### 4. Present Final Menu + +a) **Display completion message and menu:** + +``` +**Tech-Spec Complete!** + +Saved to: {finalFile} + +--- + +**Next Steps:** + +[a] Advanced Elicitation - refine further +[r] Adversarial Review - critique of the spec (highly recommended) +[b] Begin Development - start implementing now (not recommended) +[d] Done - exit workflow +[p] Party Mode - get expert feedback before dev + +--- + +Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results. + +Copy this prompt to start dev: + +\`\`\` +quick-dev {finalFile} +\`\`\` + +This ensures the dev agent has clean context focused solely on implementation. +``` + +b) **HALT and wait for user selection.** + +#### Menu Handling: + +- **[a]**: Load and execute `{advanced_elicitation}`, then return here and redisplay menu +- **[b]**: Load and execute `{quick_dev_workflow}` with the final spec file (warn: fresh context is better) +- **[d]**: Exit workflow - display final confirmation and path to spec +- **[p]**: Load and execute `{party_mode_exec}`, then return here and redisplay menu +- **[r]**: Execute Adversarial Review: + 1. **Invoke Adversarial Review Task**: + > With `{finalFile}` constructed, invoke the review task. If possible, use information asymmetry: run this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`. + Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml + > **Platform fallback:** If task invocation not available, load the task file and execute its instructions inline, passing `{finalFile}` as the content. + > The task should: review `{finalFile}` and return a list of findings. + + 2. **Process Findings**: + > Capture the findings from the task output. + > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance. + > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided). + > DO NOT exclude findings based on severity or validity unless explicitly asked to do so. + > Order findings by severity. + > Number the ordered findings (F1, F2, F3, etc.). + > If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description + + 3. Return here and redisplay menu. + +### 5. Exit Workflow + +**When user selects [d]:** + +"**All done!** Your tech-spec is ready at: + +`{finalFile}` + +When you're ready to implement, run: + +``` +quick-dev {finalFile} +``` + +Ship it!" + +--- + +## REQUIRED OUTPUTS: + +- MUST update status to 'ready-for-dev'. +- MUST rename file to `tech-spec-{slug}.md`. +- MUST provide clear next-step guidance and recommend fresh context for dev. + +## VERIFICATION CHECKLIST: + +- [ ] Complete spec presented for review. +- [ ] Requested changes implemented. +- [ ] Spec verified against **READY FOR DEVELOPMENT** standard. +- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed. diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md new file mode 100644 index 00000000..8d201149 --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md @@ -0,0 +1,74 @@ +--- +title: '{title}' +slug: '{slug}' +created: '{date}' +status: 'in-progress' +stepsCompleted: [] +tech_stack: [] +files_to_modify: [] +code_patterns: [] +test_patterns: [] +--- + +# Tech-Spec: {title} + +**Created:** {date} + +## Overview + +### Problem Statement + +{problem_statement} + +### Solution + +{solution} + +### Scope + +**In Scope:** +{in_scope} + +**Out of Scope:** +{out_of_scope} + +## Context for Development + +### Codebase Patterns + +{codebase_patterns} + +### Files to Reference + +| File | Purpose | +| ---- | ------- | + +{files_table} + +### Technical Decisions + +{technical_decisions} + +## Implementation Plan + +### Tasks + +{tasks} + +### Acceptance Criteria + +{acceptance_criteria} + +## Additional Context + +### Dependencies + +{dependencies} + +### Testing Strategy + +{testing_strategy} + +### Notes + +{notes} diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md new file mode 100644 index 00000000..90194b87 --- /dev/null +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md @@ -0,0 +1,78 @@ +--- +name: create-tech-spec +description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec. +main_config: '{project-root}/_bmad/bmm/config.yaml' +web_bundle: true + +# Checkpoint handler paths +advanced_elicitation: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml' +party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md' +quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md' +--- + +# Create Tech-Spec Workflow + +**Goal:** Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation. + +**READY FOR DEVELOPMENT STANDARD:** + +A specification is considered "Ready for Development" ONLY if it meets the following: + +- **Actionable**: Every task has a clear file path and specific action. +- **Logical**: Tasks are ordered by dependency (lowest level first). +- **Testable**: All ACs follow Given/When/Then and cover happy path and edge cases. +- **Complete**: All investigation results from Step 2 are inlined; no placeholders or "TBD". +- **Self-Contained**: A fresh agent can implement the feature without reading the workflow history. + +--- + +**Your Role:** You are an elite developer and spec engineer. You ask sharp questions, investigate existing code thoroughly, and produce specs that contain ALL context a fresh dev agent needs to implement the feature. No handoffs, no missing context - just complete, actionable specs. + +--- + +## WORKFLOW ARCHITECTURE + +This uses **step-file architecture** for disciplined execution: + +### Core Principles + +- **Micro-file Design**: Each step is a self-contained instruction file that must be followed exactly +- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed +- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization +- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array +- **Append-Only Building**: Build the tech-spec by updating content as directed + +### Step Processing Rules + +1. **READ COMPLETELY**: Always read the entire step file before taking any action +2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate +3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection +4. **CHECK CONTINUATION**: Only proceed to next step when user selects [c] (Continue) +5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step +6. **LOAD NEXT**: When directed, load and read entire next step file, then execute + +### Critical Rules (NO EXCEPTIONS) + +- **NEVER** load multiple step files simultaneously +- **ALWAYS** read entire step file before execution +- **NEVER** skip steps or optimize the sequence +- **ALWAYS** update frontmatter of output file when completing a step +- **ALWAYS** follow the exact instructions in the step file +- **ALWAYS** halt at menus and wait for user input +- **NEVER** create mental todo lists from future steps + +--- + +## INITIALIZATION SEQUENCE + +### 1. Configuration Loading + +Load and read full config from `{main_config}` and resolve: + +- `project_name`, `output_folder`, `implementation_artifacts`, `user_name` +- `communication_language`, `document_output_language`, `user_skill_level` +- `date` as system-generated current datetime + +### 2. First Step Execution + +Load, read the full file, and then execute `steps/step-01-understand.md` to begin the workflow. diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml deleted file mode 100644 index cf2b2815..00000000 --- a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# Quick-Flow: Create Tech-Spec -name: create-tech-spec -description: "Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec." -author: "BMad" - -# Config -config_source: "{project-root}/_bmad/bmm/config.yaml" -implementation_artifacts: "{config_source}:implementation_artifacts" -planning_artifacts: "{config_source}:planning_artifacts" -project_knowledge: "{config_source}:project_knowledge" -output_folder: "{implementation_artifacts}" -user_name: "{config_source}:user_name" -communication_language: "{config_source}:communication_language" -document_output_language: "{config_source}:document_output_language" -user_skill_level: "{config_source}:user_skill_level" -date: system-generated - -# Workflow components -installed_path: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec" -instructions: "{installed_path}/instructions.md" - -# Related workflows -quick_dev_workflow: "{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml" -party_mode_exec: "{project-root}/_bmad/core/workflows/party-mode/workflow.md" -advanced_elicitation: "{project-root}/_bmad/core/tasks/advanced-elicitation.xml" - -standalone: true -web_bundle: false diff --git a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md index fd349801..2a366dbd 100644 --- a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md +++ b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md @@ -79,7 +79,7 @@ Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undec DO NOT exclude findings based on severity or validity unless explicitly asked to do so. Order findings by severity. Number the ordered findings (F1, F2, F3, etc.). -If WriteTodos or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the todo; otherwise present findings as a table with columns: ID, Severity, Validity, Description +If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description --- From aba9d11c886ea12e7dffdfd9f4e49e1eca3c08f9 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 27 Dec 2025 10:40:23 +0800 Subject: [PATCH 2/6] quick flow updates to aid discovery and implementation --- .../create-tech-spec/steps/step-01-understand.md | 2 +- .../workflows/bmad-quick-flow/create-tech-spec/workflow.md | 2 +- .../bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md | 2 +- .../bmm/workflows/bmad-quick-flow/quick-dev/workflow.md | 2 +- tools/cli/lib/agent/compiler.js | 4 ---- 5 files changed, 4 insertions(+), 8 deletions(-) diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md index c26a390b..4964abd4 100644 --- a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md @@ -76,7 +76,7 @@ a) **Before asking detailed questions, do a rapid scan to understand the landsca b) **Check for existing context docs:** -- Check `{output_folder}` for planning documents (PRD, architecture, epics) +- Check `{output_folder}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research) - Check for `**/project-context.md` - if it exists, skim for patterns and conventions - Check for any existing stories or specs related to user's request diff --git a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md index 90194b87..ca28929c 100644 --- a/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md +++ b/src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md @@ -69,7 +69,7 @@ This uses **step-file architecture** for disciplined execution: Load and read full config from `{main_config}` and resolve: -- `project_name`, `output_folder`, `implementation_artifacts`, `user_name` +- `project_name`, `output_folder`, `planning_artifacts`, `implementation_artifacts`, `user_name` - `communication_language`, `document_output_language`, `user_skill_level` - `date` as system-generated current datetime diff --git a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md index d6e79845..2f8d2623 100644 --- a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md +++ b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md @@ -40,7 +40,7 @@ First, check if the project uses Git version control: ### 2. Load Project Context -Check if `{project_context}` exists (`**/project-context.md`). If found, load it - this is foundational reference for ALL implementation decisions. +Check if `{project_context}` exists (`**/project-context.md`). If found, load it as a foundational reference for ALL implementation decisions. ### 3. Parse User Input diff --git a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md index 1f0468ba..33c4b060 100644 --- a/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md +++ b/src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md @@ -28,7 +28,7 @@ This uses **step-file architecture** for focused execution: Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve: - `user_name`, `communication_language`, `user_skill_level` -- `output_folder`, `sprint_artifacts` +- `output_folder`, `planning_artifacts`, `implementation_artifacts` - `date` as system-generated current datetime ### Paths diff --git a/tools/cli/lib/agent/compiler.js b/tools/cli/lib/agent/compiler.js index 9f4b6bfe..cf8704be 100644 --- a/tools/cli/lib/agent/compiler.js +++ b/tools/cli/lib/agent/compiler.js @@ -142,11 +142,7 @@ function buildMenuXml(menuItems) { } // Handle legacy format menu items else if (item.trigger) { - // For legacy items, keep using cmd with * format let trigger = item.trigger || ''; - if (!trigger.startsWith('*')) { - trigger = '*' + trigger; - } const attrs = [`cmd="${trigger}"`]; From 949cf64d3b2442bc36a879188e26235886f5216a Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 27 Dec 2025 10:59:44 +0800 Subject: [PATCH 3/6] workflow status, init and phase 4 items aligned with planning_artifacts and implementation_artifacts for discovery and output --- .../code-review/workflow.yaml | 21 ++++++++--------- .../create-story/workflow.yaml | 23 ++++++++++--------- .../retrospective/instructions.md | 6 ++--- .../retrospective/workflow.yaml | 21 +++++++++-------- .../workflow-status/init/instructions.md | 12 +++++----- .../workflow-status/init/workflow.yaml | 3 ++- .../workflows/workflow-status/instructions.md | 8 +++---- 7 files changed, 47 insertions(+), 47 deletions(-) diff --git a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml index db51becc..9e66b932 100644 --- a/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/code-review/workflow.yaml @@ -10,9 +10,10 @@ communication_language: "{config_source}:communication_language" user_skill_level: "{config_source}:user_skill_level" document_output_language: "{config_source}:document_output_language" date: system-generated +planning_artifacts: "{config_source}:planning_artifacts" implementation_artifacts: "{config_source}:implementation_artifacts" output_folder: "{implementation_artifacts}" -sprint_status: "{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" +sprint_status: "{implementation_artifacts}/sprint-status.yaml" # Workflow components installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/code-review" @@ -31,24 +32,20 @@ variables: input_file_patterns: architecture: description: "System architecture for review context" - whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/*.md" + whole: "{planning_artifacts}/*architecture*.md" + sharded: "{planning_artifacts}/*architecture*/*.md" load_strategy: "FULL_LOAD" ux_design: description: "UX design specification (if UI review)" - whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/*.md" + whole: "{planning_artifacts}/*ux*.md" + sharded: "{planning_artifacts}/*ux*/*.md" load_strategy: "FULL_LOAD" epics: description: "Epic containing story being reviewed" - whole: "{output_folder}/*epic*.md" - sharded_index: "{output_folder}/*epic*/index.md" - sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + whole: "{planning_artifacts}/*epic*.md" + sharded_index: "{planning_artifacts}/*epic*/index.md" + sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" load_strategy: "SELECTIVE_LOAD" - document_project: - description: "Brownfield project documentation (optional)" - sharded: "{output_folder}/index.md" - load_strategy: "INDEX_GUIDED" standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index f4470a6a..e79a7f97 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -7,6 +7,7 @@ config_source: "{project-root}/_bmad/bmm/config.yaml" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" date: system-generated +planning_artifacts: "{config_source}:planning_artifacts" implementation_artifacts: "{config_source}:implementation_artifacts" output_folder: "{implementation_artifacts}" story_dir: "{implementation_artifacts}" @@ -20,10 +21,10 @@ validation: "{installed_path}/checklist.md" # Variables and inputs variables: sprint_status: "{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" # Primary source for story tracking - epics_file: "{output_folder}/epics.md" # Enhanced epics+stories with BDD and source hints - prd_file: "{output_folder}/PRD.md" # Fallback for requirements (if not in epics file) + epics_file: "{planning_artifacts}/epics.md" # Enhanced epics+stories with BDD and source hints + prd_file: "{planning_artifacts}/prd.md" # Fallback for requirements (if not in epics file) architecture_file: "{planning_artifacts}/architecture.md" # Fallback for constraints (if not in epics file) - ux_file: "{output_folder}/ux.md" # Fallback for UX requirements (if not in epics file) + ux_file: "{planning_artifacts}/*ux*.md" # Fallback for UX requirements (if not in epics file) story_title: "" # Will be elicited if not derivable # Project context @@ -36,23 +37,23 @@ default_output_file: "{story_dir}/{{story_key}}.md" input_file_patterns: prd: description: "PRD (fallback - epics file should have most content)" - whole: "{output_folder}/*prd*.md" - sharded: "{output_folder}/*prd*/*.md" + whole: "{planning_artifacts}/*prd*.md" + sharded: "{planning_artifacts}/*prd*/*.md" load_strategy: "SELECTIVE_LOAD" # Only load if needed architecture: description: "Architecture (fallback - epics file should have relevant sections)" - whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/*.md" + whole: "{planning_artifacts}/*architecture*.md" + sharded: "{planning_artifacts}/*architecture*/*.md" load_strategy: "SELECTIVE_LOAD" # Only load if needed ux: description: "UX design (fallback - epics file should have relevant sections)" - whole: "{output_folder}/*ux*.md" - sharded: "{output_folder}/*ux*/*.md" + whole: "{planning_artifacts}/*ux*.md" + sharded: "{planning_artifacts}/*ux*/*.md" load_strategy: "SELECTIVE_LOAD" # Only load if needed epics: description: "Enhanced epics+stories file with BDD and source hints" - whole: "{output_folder}/*epic*.md" - sharded: "{output_folder}/*epic*/*.md" + whole: "{planning_artifacts}/*epic*.md" + sharded: "{planning_artifacts}/*epic*/*.md" load_strategy: "SELECTIVE_LOAD" # Only load needed epic standalone: true diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md index 70b1ae80..01750312 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md +++ b/src/modules/bmm/workflows/4-implementation/retrospective/instructions.md @@ -365,16 +365,16 @@ Alice (Product Owner): "Good thinking - helps us connect what we learned to what Attempt to load next epic using selective loading strategy: **Try sharded first (more specific):** -Check if file exists: {output_folder}/epic\*/epic-{{next_epic_num}}.md +Check if file exists: {planning_artifacts}/epic\*/epic-{{next_epic_num}}.md - Load {output_folder}/*epic*/epic-{{next_epic_num}}.md + Load {planning_artifacts}/*epic*/epic-{{next_epic_num}}.md Set {{next_epic_source}} = "sharded" **Fallback to whole document:** -Check if file exists: {output_folder}/epic\*.md +Check if file exists: {planning_artifacts}/epic\*.md Load entire epics document diff --git a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml index 9be242e7..80d934b2 100644 --- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml @@ -4,12 +4,13 @@ description: "Run after epic completion to review overall success, extract lesso author: "BMad" config_source: "{project-root}/_bmad/bmm/config.yaml" -output_folder: "{config_source}:output_folder" +output_folder: "{config_source}:implementation_artifacts}" user_name: "{config_source}:user_name" communication_language: "{config_source}:communication_language" user_skill_level: "{config_source}:user_skill_level" document_output_language: "{config_source}:document_output_language" date: system-generated +planning_artifacts: "{config_source}:planning_artifacts" implementation_artifacts: "{config_source}:implementation_artifacts" installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/retrospective" @@ -25,9 +26,9 @@ required_inputs: input_file_patterns: epics: description: "The completed epic for retrospective" - whole: "{output_folder}/*epic*.md" - sharded_index: "{output_folder}/*epic*/index.md" - sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md" + whole: "{planning_artifacts}/*epic*.md" + sharded_index: "{planning_artifacts}/*epic*/index.md" + sharded_single: "{planning_artifacts}/*epic*/epic-{{epic_num}}.md" load_strategy: "SELECTIVE_LOAD" previous_retrospective: description: "Previous epic's retrospective (optional)" @@ -35,21 +36,21 @@ input_file_patterns: load_strategy: "SELECTIVE_LOAD" architecture: description: "System architecture for context" - whole: "{output_folder}/*architecture*.md" - sharded: "{output_folder}/*architecture*/*.md" + whole: "{planning_artifacts}/*architecture*.md" + sharded: "{planning_artifacts}/*architecture*/*.md" load_strategy: "FULL_LOAD" prd: description: "Product requirements for context" - whole: "{output_folder}/*prd*.md" - sharded: "{output_folder}/*prd*/*.md" + whole: "{planning_artifacts}/*prd*.md" + sharded: "{planning_artifacts}/*prd*/*.md" load_strategy: "FULL_LOAD" document_project: description: "Brownfield project documentation (optional)" - sharded: "{output_folder}/*.md" + sharded: "{planning_artifacts}/*.md" load_strategy: "INDEX_GUIDED" # Required files -sprint_status_file: "{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml" +sprint_status_file: "{implementation_artifacts}/sprint-status.yaml" story_directory: "{implementation_artifacts}" retrospectives_folder: "{implementation_artifacts}" diff --git a/src/modules/bmm/workflows/workflow-status/init/instructions.md b/src/modules/bmm/workflows/workflow-status/init/instructions.md index 51c1b6de..eeee90d9 100644 --- a/src/modules/bmm/workflows/workflow-status/init/instructions.md +++ b/src/modules/bmm/workflows/workflow-status/init/instructions.md @@ -15,8 +15,8 @@ - BMM artifacts: PRD, epics, architecture, UX, brief, research, brainstorm - Implementation: stories, sprint-status, workflow-status - Codebase: source directories, package files, git repo -- Check both {output_folder} and {implementation_artifacts} locations - +- Check both {planning_artifacts} and {implementation_artifacts} locations + Categorize into one of these states: @@ -25,7 +25,7 @@ - ACTIVE: Has stories or sprint status - LEGACY: Has code but no BMM artifacts - UNCLEAR: Mixed state needs clarification - + What's your project called? {{#if project_name}}(Config shows: {{project_name}}){{/if}} Store project_name @@ -68,7 +68,7 @@ Choice [1-4] Archive existing work? (y/n) - Move artifacts to {output_folder}/archive/ + Move artifacts to {planning_artifacts}/archive/ Ready for fresh start! Continue to step 3 @@ -323,10 +323,10 @@ Choice: Generate YAML from template with all variables - Save to {output_folder}/bmm-workflow-status.yaml + Save to {planning_artifacts}/bmm-workflow-status.yaml Identify next workflow and agent -✅ **Created:** {output_folder}/bmm-workflow-status.yaml +✅ **Created:** {planning_artifacts}/bmm-workflow-status.yaml **Next:** {{next_workflow_name}} **Agent:** {{next_agent}} diff --git a/src/modules/bmm/workflows/workflow-status/init/workflow.yaml b/src/modules/bmm/workflows/workflow-status/init/workflow.yaml index 63fe168c..5e1c7618 100644 --- a/src/modules/bmm/workflows/workflow-status/init/workflow.yaml +++ b/src/modules/bmm/workflows/workflow-status/init/workflow.yaml @@ -7,6 +7,7 @@ author: "BMad" config_source: "{project-root}/_bmad/bmm/config.yaml" output_folder: "{config_source}:output_folder" implementation_artifacts: "{config_source}:implementation_artifacts" +planning_artifacts: "{config_source}:planning_artifacts" user_name: "{config_source}:user_name" project_name: "{config_source}:project_name" communication_language: "{config_source}:communication_language" @@ -23,7 +24,7 @@ template: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow-status-te path_files: "{project-root}/_bmad/bmm/workflows/workflow-status/paths/" # Output configuration -default_output_file: "{output_folder}/bmm-workflow-status.yaml" +default_output_file: "{planning_artifacts}/bmm-workflow-status.yaml" standalone: true web_bundle: false diff --git a/src/modules/bmm/workflows/workflow-status/instructions.md b/src/modules/bmm/workflows/workflow-status/instructions.md index 9c5b7723..5f816aa6 100644 --- a/src/modules/bmm/workflows/workflow-status/instructions.md +++ b/src/modules/bmm/workflows/workflow-status/instructions.md @@ -34,7 +34,7 @@ -Search {output_folder}/ for file: bmm-workflow-status.yaml +Search {planning_artifacts}/ for file: bmm-workflow-status.yaml No workflow status found. @@ -343,11 +343,11 @@ Your choice: Get {{workflow_id}} parameter (required) - Get {{output_file}} parameter (required - path to created file) + Get {{default_output_file}} parameter (required - path to created file) ONLY write the file path as the status value - no other text, notes, or metadata Update workflow status in YAML: - - In workflow_status section, update: {{workflow_id}}: {{output_file}} + - In workflow_status section, update: {{workflow_id}}: {{default_output_file}} Find {{workflow_id}} in loaded path YAML Determine next workflow from path sequence @@ -359,7 +359,7 @@ Your choice: next_workflow = {{determined next workflow}} next_agent = {{determined next agent from path file}} completed_workflow = {{workflow_id}} - output_file = {{output_file}} + default_output_file = {{default_output_file}} From d4a94df29a13ff1c7397370ff112046798e567b0 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 27 Dec 2025 18:29:35 +0800 Subject: [PATCH 4/6] doc cleanup round 1 --- .vscode/settings.json | 1 + docs/agent-customization-guide.md | 2 +- docs/custom-content-installation.md | 12 +- docs/custom-content.md | 9 +- docs/document-sharding-guide.md | 350 +-------- docs/getting-started/installation.md | 46 +- docs/ide-info/auggie.md | 31 - docs/ide-info/claude-code.md | 25 - docs/ide-info/cline.md | 31 - docs/ide-info/codex.md | 21 - docs/ide-info/crush.md | 30 - docs/ide-info/cursor.md | 25 - docs/ide-info/gemini.md | 25 - docs/ide-info/github-copilot.md | 26 - docs/ide-info/iflow.md | 33 - docs/ide-info/index.md | 24 - docs/ide-info/kilo.md | 24 - docs/ide-info/opencode.md | 24 - docs/ide-info/qwen.md | 25 - docs/ide-info/roo.md | 27 - docs/ide-info/rovo-dev.md | 22 - docs/ide-info/trae.md | 25 - docs/ide-info/windsurf.md | 22 - docs/index.md | 42 +- docs/v4-to-v6-upgrade.md | 153 +--- docs/web-bundles-gemini-gpt-guide.md | 6 +- ...low-vendoring-customization-inheritance.md | 42 ++ .../toolsmith-sidecar/knowledge/docs.md | 5 - src/modules/bmgd/docs/glossary.md | 1 - src/modules/bmgd/docs/index.md | 5 - src/modules/bmm/README.md | 4 - src/modules/bmm/docs/brownfield-guide.md | 1 - .../docs/enterprise-agentic-development.md | 686 ------------------ src/modules/bmm/docs/faq.md | 2 - src/modules/bmm/docs/index.md | 62 +- src/modules/bmm/docs/party-mode.md | 120 +-- src/modules/bmm/docs/quick-spec-flow.md | 24 +- src/modules/bmm/docs/quick-start.md | 7 +- src/modules/bmm/docs/scale-adaptive-system.md | 618 ---------------- src/modules/bmm/docs/test-architecture.md | 42 +- src/modules/bmm/docs/troubleshooting.md | 660 +---------------- .../docs/workflow-architecture-reference.md | 366 ---------- .../workflow-document-project-reference.md | 422 +---------- src/modules/bmm/docs/workflows-analysis.md | 75 +- src/modules/bmm/docs/workflows-planning.md | 378 +--------- tools/cli/installers/install-messages.yaml | 22 +- tools/cli/installers/lib/core/detector.js | 20 - website/sidebars.js | 20 +- website/src/pages/downloads.md | 15 - 49 files changed, 202 insertions(+), 4456 deletions(-) delete mode 100644 docs/ide-info/auggie.md delete mode 100644 docs/ide-info/claude-code.md delete mode 100644 docs/ide-info/cline.md delete mode 100644 docs/ide-info/codex.md delete mode 100644 docs/ide-info/crush.md delete mode 100644 docs/ide-info/cursor.md delete mode 100644 docs/ide-info/gemini.md delete mode 100644 docs/ide-info/github-copilot.md delete mode 100644 docs/ide-info/iflow.md delete mode 100644 docs/ide-info/index.md delete mode 100644 docs/ide-info/kilo.md delete mode 100644 docs/ide-info/opencode.md delete mode 100644 docs/ide-info/qwen.md delete mode 100644 docs/ide-info/roo.md delete mode 100644 docs/ide-info/rovo-dev.md delete mode 100644 docs/ide-info/trae.md delete mode 100644 docs/ide-info/windsurf.md create mode 100644 docs/workflow-vendoring-customization-inheritance.md delete mode 100644 src/modules/bmm/docs/enterprise-agentic-development.md delete mode 100644 src/modules/bmm/docs/scale-adaptive-system.md delete mode 100644 src/modules/bmm/docs/workflow-architecture-reference.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 1f500542..8a85c1f3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -57,6 +57,7 @@ "tileset", "tmpl", "Trae", + "Unsharded", "VNET", "webskip" ], diff --git a/docs/agent-customization-guide.md b/docs/agent-customization-guide.md index 724f5d26..350a609a 100644 --- a/docs/agent-customization-guide.md +++ b/docs/agent-customization-guide.md @@ -81,7 +81,7 @@ Add your own workflows to the agent's menu: ```yaml menu: - trigger: my-workflow - workflow: '{project-root}/custom/my-workflow.yaml' + workflow: '{project-root}/my-custom/workflows/my-workflow.yaml' description: My custom workflow - trigger: deploy action: '#deploy-prompt' diff --git a/docs/custom-content-installation.md b/docs/custom-content-installation.md index 6658233e..3c280d0c 100644 --- a/docs/custom-content-installation.md +++ b/docs/custom-content-installation.md @@ -26,10 +26,8 @@ To create an installable custom module: - Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite) - The folder name serves as the module code -2. **Required Files** - - Include a `module.yaml` file in the root folder - - This file drives the installation process when used by the BMAD installer - - Reference existing modules or the BMad Builder for configuration examples +2. **Required File** + - Include a `module.yaml` file in the root folder (this drives questions for the final generated config.yaml at install target) 3. **Folder Organization** Follow these conventions for optimal compatibility: @@ -56,8 +54,10 @@ For standalone content that isn't part of a cohesive module collection, follow t 1. **Module Configuration** - Create a folder with a `module.yaml` file (similar to custom modules) - - Add the property `unitary: true` to the module.yaml - - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other + - Add the property `unitary: true` in the module.yaml + - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other + - Any content you add to this folder should still be nested under workflows and agents - but the key with stand alone content is they do not rely on each other. + - Agents do not reference other workflows even if stored in a unitary:true module. But unitary Agents can have their own workflows in their sidecar, or reference workflows as requirements from other modules - with a process known as workflow vendoring. Keep in mind, this will require that the workflow referenced from the other module would need to be available for the end user to install, so its recommended to only vendor workflows from the core module, or official bmm modules (See [Workflow Vendoring, Customization, and Inheritance](workflow-vendoring-customization-inheritance.md)). 2. **Folder Structure** Organize content in specific named folders: diff --git a/docs/custom-content.md b/docs/custom-content.md index 69f9e171..b54e8572 100644 --- a/docs/custom-content.md +++ b/docs/custom-content.md @@ -1,6 +1,6 @@ # Custom Content -BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine. +BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agents provides workflows and expertise to plan and build any custom content you can imagine. This flexibility transforms the platform beyond its current capabilities, enabling: @@ -21,7 +21,7 @@ This flexibility transforms the platform beyond its current capabilities, enabli - [Custom Global Modules](#custom-global-modules) - [Custom Agents](#custom-agents) - [BMad Tiny Agents](#bmad-tiny-agents) - - [Simple vs Expert Agents](#simple-vs-expert-agents) + - [Simple and Expert Agents](#simple-and-expert-agents) - [Custom Workflows](#custom-workflows) ## Custom Stand Alone Modules @@ -57,7 +57,7 @@ Similar to Custom Stand Alone Modules, but designed to add functionality that ap Examples include: -- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module +- The current TTS (Text-to-Speech) functionality for Claude, which will soon be converted to a global module - The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities - Installation and update tools that work with any BMAD method configuration @@ -81,7 +81,7 @@ Personal agents designed for highly specific needs that may not be suitable for These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository. -### Simple vs Expert Agents +### Simple and Expert Agents The distinction between simple and expert agents lies in their structure: @@ -89,7 +89,6 @@ The distinction between simple and expert agents lies in their structure: - Single file containing all prompts and configuration - Self-contained and straightforward -- has metadata type: simple **Expert Agent:** diff --git a/docs/document-sharding-guide.md b/docs/document-sharding-guide.md index a0399375..4480042a 100644 --- a/docs/document-sharding-guide.md +++ b/docs/document-sharding-guide.md @@ -4,13 +4,21 @@ Comprehensive guide to BMad Method's document sharding system for managing large ## Table of Contents -- [What is Document Sharding?](#what-is-document-sharding) -- [When to Use Sharding](#when-to-use-sharding) -- [How Sharding Works](#how-sharding-works) -- [Using the Shard-Doc Tool](#using-the-shard-doc-tool) -- [Workflow Support](#workflow-support) -- [Best Practices](#best-practices) -- [Examples](#examples) +- [Document Sharding Guide](#document-sharding-guide) + - [Table of Contents](#table-of-contents) + - [What is Document Sharding?](#what-is-document-sharding) + - [Architecture](#architecture) + - [When to Use Sharding](#when-to-use-sharding) + - [Ideal Candidates](#ideal-candidates) + - [How Sharding Works](#how-sharding-works) + - [Sharding Process](#sharding-process) + - [Workflow Discovery](#workflow-discovery) + - [Using the Shard-Doc Tool](#using-the-shard-doc-tool) + - [CLI Command](#cli-command) + - [Interactive Process](#interactive-process) + - [What Gets Created](#what-gets-created) + - [Workflow Support](#workflow-support) + - [Universal Support](#universal-support) ## What is Document Sharding? @@ -49,27 +57,6 @@ docs/ - Epic files with 4+ epics (especially for Phase 4) - UX design specs covering multiple subsystems -**Token Thresholds:** - -- **Consider sharding**: Documents > 20k tokens -- **Strongly recommended**: Documents > 40k tokens -- **Critical for efficiency**: Documents > 60k tokens - -### When NOT to Shard - -**Small Projects:** - -- Single epic projects -- Level 0-1 projects (tech-spec only) -- Documents under 10k tokens -- Quick prototypes - -**Frequently Updated Docs:** - -- Active work-in-progress documents -- Documents updated daily -- Documents where whole-file context is essential - ## How Sharding Works ### Sharding Process @@ -85,36 +72,14 @@ BMad workflows use a **dual discovery system**: 1. **Try whole document first** - Look for `document-name.md` 2. **Check for sharded version** - Look for `document-name/index.md` -3. **Priority rule** - Whole document takes precedence if both exist - -### Loading Strategies - -**Full Load (Phase 1-3 workflows):** - -``` -If sharded: - - Read index.md - - Read ALL section files - - Treat as single combined document -``` - -**Selective Load (Phase 4 workflows):** - -``` -If sharded epics and working on Epic 3: - - Read epics/index.md - - Load ONLY epics/epic-3.md - - Skip all other epic files - - 90%+ token savings! -``` +3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead. ## Using the Shard-Doc Tool ### CLI Command ```bash -# Activate bmad-master or analyst agent, then: -/shard-doc +/bmad:core:tools:shard-doc ``` ### Interactive Process @@ -166,284 +131,3 @@ Agent: Sharding PRD.md... - ✅ Sharded documents - ✅ Automatic detection - ✅ Transparent to user - -### Workflow-Specific Patterns - -#### Phase 1-3 (Full Load) - -Workflows load entire sharded documents: - -- `product-brief` - Research, brainstorming docs -- `prd` - Product brief, research -- `gdd` - Game brief, research -- `create-ux-design` - PRD, brief, architecture (if available) -- `tech-spec` - Brief, research -- `architecture` - PRD, UX design (if available) -- `create-epics-and-stories` - PRD, architecture -- `implementation-readiness` - All planning docs - -#### Phase 4 (Selective Load) - -Workflows load only needed sections: - -**sprint-planning** (Full Load): - -- Needs ALL epics to build complete status - -**create-story, code-review** (Selective): - -``` -Working on Epic 3, Story 2: - ✓ Load epics/epic-3.md only - ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc. - -Result: 90%+ token reduction for 10-epic projects! -``` - -### Input File Patterns - -Workflows use standardized patterns: - -```yaml -input_file_patterns: - prd: - whole: '{output_folder}/*prd*.md' - sharded: '{output_folder}/*prd*/index.md' - - epics: - whole: '{output_folder}/*epic*.md' - sharded_index: '{output_folder}/*epic*/index.md' - sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' -``` - -## Best Practices - -### Sharding Strategy - -**Do:** - -- ✅ Shard after planning phase complete -- ✅ Keep level 2 headings well-organized -- ✅ Use descriptive section names -- ✅ Shard before Phase 4 implementation -- ✅ Keep original file as backup initially - -**Don't:** - -- ❌ Shard work-in-progress documents -- ❌ Shard small documents (<20k tokens) -- ❌ Mix sharded and whole versions -- ❌ Manually edit index.md structure - -### Naming Conventions - -**Good Section Names:** - -```markdown -## Epic 1: User Authentication - -## Technical Requirements - -## System Architecture - -## UX Design Principles -``` - -**Poor Section Names:** - -```markdown -## Section 1 - -## Part A - -## Details - -## More Info -``` - -### File Management - -**When to Re-shard:** - -- Significant structural changes to document -- Adding/removing major sections -- After major refactoring - -**Updating Sharded Docs:** - -1. Edit individual section files directly -2. OR edit original, delete sharded folder, re-shard -3. Don't manually edit index.md - -## Examples - -### Example 1: Large PRD - -**Scenario:** 15-epic project, PRD is 45k tokens - -**Before Sharding:** - -``` -Every workflow loads entire 45k token PRD -Architecture workflow: 45k tokens -UX design workflow: 45k tokens -``` - -**After Sharding:** - -```bash -/shard-doc -Source: docs/PRD.md -Destination: docs/prd/ - -Created: - prd/index.md - prd/overview.md (3k tokens) - prd/functional-requirements.md (8k tokens) - prd/non-functional-requirements.md (6k tokens) - prd/user-personas.md (4k tokens) - ...additional FR/NFR sections -``` - -**Result:** - -``` -Architecture workflow: Can load specific sections needed -UX design workflow: Can load specific sections needed -Significant token reduction for large requirement docs! -``` - -### Example 2: Sharding Epics File - -**Scenario:** 8 epics with detailed stories, 35k tokens total - -```bash -/shard-doc -Source: docs/bmm-epics.md -Destination: docs/epics/ - -Created: - epics/index.md - epics/epic-1.md - epics/epic-2.md - ... - epics/epic-8.md -``` - -**Efficiency Gain:** - -``` -Working on Epic 5 stories: - Old: Load all 8 epics (35k tokens) - New: Load epic-5.md only (4k tokens) - Savings: 88% reduction -``` - -### Example 3: Architecture Document - -**Scenario:** Multi-layer system architecture, 28k tokens - -```bash -/shard-doc -Source: docs/architecture.md -Destination: docs/architecture/ - -Created: - architecture/index.md - architecture/system-overview.md - architecture/frontend-architecture.md - architecture/backend-services.md - architecture/data-layer.md - architecture/infrastructure.md - architecture/security-architecture.md -``` - -**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc. - -## Custom Workflow Integration - -### For Workflow Builders - -When creating custom workflows that load large documents: - -**1. Add input_file_patterns to workflow.yaml:** - -```yaml -input_file_patterns: - your_document: - whole: '{output_folder}/*your-doc*.md' - sharded: '{output_folder}/*your-doc*/index.md' -``` - -**2. Add discovery instructions to instructions.md:** - -```markdown -## Document Discovery - -1. Search for whole document: _your-doc_.md -2. Check for sharded version: _your-doc_/index.md -3. If sharded: Read index + ALL sections (or specific sections if selective load) -4. Priority: Whole document first -``` - -**3. Choose loading strategy:** - -- **Full Load**: Read all sections when sharded -- **Selective Load**: Read only relevant sections (requires section identification logic) - -### Pattern Templates - -**Full Load Pattern:** - -```xml -Search for document: {output_folder}/*doc-name*.md -If not found, check for sharded: {output_folder}/*doc-name*/index.md -Read index.md to understand structure -Read ALL section files listed in index -Combine content as single document -``` - -**Selective Load Pattern (with section ID):** - -```xml -Determine section needed (e.g., epic_num = 3) -Check for sharded version: {output_folder}/*doc-name*/index.md -Read ONLY the specific section file needed -Skip all other section files -``` - -## Troubleshooting - -### Common Issues - -**Both whole and sharded exist:** - -- Workflows will use whole document (priority rule) -- Delete or archive the one you don't want - -**Index.md out of sync:** - -- Delete sharded folder -- Re-run shard-doc on original - -**Workflow can't find document:** - -- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.) -- Verify index.md exists in sharded folder -- Check output_folder path in config - -**Sections too granular:** - -- Combine sections in original document -- Use fewer level 2 headings -- Re-shard - -## Related Documentation - -- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation -- [BMM Workflows Guide](./modules/bmm/index.md#-workflow-guides) - Workflow overview -- [Workflow Creation Guide](./modules/bmb/workflows/index) - Custom workflow patterns - ---- - -**Document sharding is optional but powerful** - use it when efficiency matters for large projects! diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index f481ab96..06d3a72b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -5,7 +5,7 @@ Get BMAD Method running in your project in under 2 minutes. ## Quick Install ```bash -npx bmad-method@alpha install +npx bmad-method install ``` This interactive installer will: @@ -16,19 +16,23 @@ This interactive installer will: ## Requirements -- **Node.js** 18+ (for the installer) +- **Node.js** 20+ (for the installer) - **Git** (recommended for version control) -- An **AI-powered IDE** or access to Claude/ChatGPT/Gemini +- An **AI-powered Agent and/or IDE** or access to Claude/ChatGPT/Gemini ## Module Options During installation, you'll choose which modules to install: -| Module | Description | Best For | -| -------- | ---------------- | ---------------------------------------- | -| **BMM** | BMAD Method Core | Software development projects | -| **BMGD** | Game Development | Game projects with specialized workflows | -| **BMB** | Builder | Creating custom agents and workflows | +| Module | Description | Best For | +| -------- | -------------------- | ----------------------------------------------------- | +| **BMM** | BMAD Method Core | Software development projects | +| **BMGD** | Game Development | Game projects with specialized workflows | +| **CIS** | Creative Intel Suite | Creativity Unlocking Suite, not software dev specific | +| **BMB** | Builder | Creating custom agents and workflows | + +You will also be asked if you would like to install custom content (agents, workflows or modules) you have created with the BMB, or shared from others in the community. + ## Post-Installation @@ -39,38 +43,26 @@ your-project/ ├── _bmad/ # BMAD configuration and agents │ ├── bmm/ # Method module (if installed) │ ├── bmgd/ # Game dev module (if installed) -│ └── config.yaml # Your project configuration +│ ├── core/ # Always installed, includes party mode, advanced elicitation, and other core generic utils +│ ├── {others}/ # etc... +├── _bmad-output/ # BMAD default output folder - configurable during install ├── .claude/ # IDE-specific setup (varies by IDE) -└── ... your code +└── ... your code # maybe nothing else yet if a fresh new folder ``` ## Next Steps 1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature -2. **Check your [IDE Guide](../ide-info/index.md)** for IDE-specific tips -3. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology - -## Alternative: Web Bundles - -Don't want to install? Use BMAD agents directly in: - -- **Claude Projects** - Upload the web bundle -- **ChatGPT** - Use custom GPT bundles -- **Gemini** - Import agent prompts - -See the [Web Bundles Guide](../web-bundles-gemini-gpt-guide.md) for details. +2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology ## Troubleshooting ### Common Issues **"Command not found: npx"** -: Install Node.js 18+ from [nodejs.org](https://nodejs.org) +: Install Node.js 20+ from [nodejs.org](https://nodejs.org) **"Permission denied"** : Run with appropriate permissions or check your npm configuration -**IDE not detected** -: The installer will prompt you to select your IDE manually - -For more help, see [Troubleshooting](../modules/bmm/troubleshooting.md) or join our [Discord](https://discord.gg/bmad). +For more help, join our [Discord](https://discord.gg/bmad). diff --git a/docs/ide-info/auggie.md b/docs/ide-info/auggie.md deleted file mode 100644 index eaca87eb..00000000 --- a/docs/ide-info/auggie.md +++ /dev/null @@ -1,31 +0,0 @@ -# BMAD Method - Auggie CLI Instructions - -## Activating Agents - -BMAD agents can be installed in multiple locations based on your setup. - -### Common Locations - -- User Home: `~/.augment/commands/` -- Project: `.augment/commands/` -- Custom paths you selected - -### How to Use - -1. **Type Trigger**: Use `@{agent-name}` in your prompt -2. **Activate**: Agent persona activates -3. **Tasks**: Use `@task-{task-name}` for tasks - -### Examples - -``` -@dev - Activate development agent -@architect - Activate architect agent -@task-setup - Execute setup task -``` - -### Notes - -- Agents can be in multiple locations -- Check your installation paths -- Activation syntax same across all locations diff --git a/docs/ide-info/claude-code.md b/docs/ide-info/claude-code.md deleted file mode 100644 index 74981b6e..00000000 --- a/docs/ide-info/claude-code.md +++ /dev/null @@ -1,25 +0,0 @@ -# BMAD Method - Claude Code Instructions - -## Activating Agents - -BMAD agents are installed as slash commands in `.claude/commands/bmad/`. - -### How to Use - -1. **Type Slash Command**: Start with `/` to see available commands -2. **Select Agent**: Type `/bmad-{agent-name}` (e.g., `/bmad-dev`) -3. **Execute**: Press Enter to activate that agent persona - -### Examples - -``` -/bmad:bmm:agents:dev - Activate development agent -/bmad:bmm:agents:architect - Activate architect agent -/bmad:bmm:workflows:dev-story - Execute dev-story workflow -``` - -### Notes - -- Commands are autocompleted when you type `/` -- Agent remains active for the conversation -- Start a new conversation to switch agents diff --git a/docs/ide-info/cline.md b/docs/ide-info/cline.md deleted file mode 100644 index e6487c9d..00000000 --- a/docs/ide-info/cline.md +++ /dev/null @@ -1,31 +0,0 @@ -# BMAD Method - Cline Instructions - -## Activating Agents - -BMAD agents are installed as **toggleable rules** in `.clinerules/` directory. - -### Important: Rules are OFF by default - -- Rules are NOT automatically loaded to avoid context pollution -- You must manually enable the agent you want to use - -### How to Use - -1. **Open Rules Panel**: Click the rules icon below the chat input -2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`) -3. **Activate in Chat**: Type `@{agent-name}` to activate that persona -4. **Disable When Done**: Toggle OFF to free up context - -### Best Practices - -- Only enable 1-2 agents at a time to preserve context -- Disable agents when switching tasks -- Rules are numbered (01-, 02-) for organization, not priority - -### Example - -``` -Toggle ON: 01-core-dev.md -In chat: "@dev help me refactor this code" -When done: Toggle OFF the rule -``` diff --git a/docs/ide-info/codex.md b/docs/ide-info/codex.md deleted file mode 100644 index 5e1c05d4..00000000 --- a/docs/ide-info/codex.md +++ /dev/null @@ -1,21 +0,0 @@ -# BMAD Method - Codex Instructions - -## Activating Agents - -BMAD agents, tasks and workflows are installed as custom prompts in -`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it -defaults to `$HOME/.codex/`. - -### Examples - -``` -/bmad-bmm-agents-dev - Activate development agent -/bmad-bmm-agents-architect - Activate architect agent -/bmad-bmm-workflows-dev-story - Execute dev-story workflow -``` - -### Notes - -Prompts are autocompleted when you type / -Agent remains active for the conversation -Start a new conversation to switch agents diff --git a/docs/ide-info/crush.md b/docs/ide-info/crush.md deleted file mode 100644 index 3526a87a..00000000 --- a/docs/ide-info/crush.md +++ /dev/null @@ -1,30 +0,0 @@ -# BMAD Method - Crush Instructions - -## Activating Agents - -BMAD agents are installed as commands in `.crush/commands/bmad/`. - -### How to Use - -1. **Open Command Palette**: Use Crush command interface -2. **Navigate**: Browse to `_bmad/{module}/agents/` -3. **Select Agent**: Choose the agent command -4. **Execute**: Run to activate agent persona - -### Command Structure - -``` -.crush/commands/bmad/ -├── agents/ # All agents -├── tasks/ # All tasks -├── core/ # Core module -│ ├── agents/ -│ └── tasks/ -└── {module}/ # Other modules -``` - -### Notes - -- Commands organized by module -- Can browse hierarchically -- Agent activates for session diff --git a/docs/ide-info/cursor.md b/docs/ide-info/cursor.md deleted file mode 100644 index 9b65f675..00000000 --- a/docs/ide-info/cursor.md +++ /dev/null @@ -1,25 +0,0 @@ -# BMAD Method - Cursor Instructions - -## Activating Agents - -BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules. - -### How to Use - -1. **Reference in Chat**: Use `@_bmad/{module}/agents/{agent-name}` -2. **Include Entire Module**: Use `@_bmad/{module}` -3. **Reference Index**: Use `@_bmad/index` for all available agents - -### Examples - -``` -@_bmad/core/agents/dev - Activate dev agent -@_bmad/bmm/agents/architect - Activate architect agent -@_bmad/core - Include all core agents/tasks -``` - -### Notes - -- Rules are Manual type - only loaded when explicitly referenced -- No automatic context pollution -- Can combine multiple agents: `@_bmad/core/agents/dev @_bmad/core/agents/test` diff --git a/docs/ide-info/gemini.md b/docs/ide-info/gemini.md deleted file mode 100644 index c102a30c..00000000 --- a/docs/ide-info/gemini.md +++ /dev/null @@ -1,25 +0,0 @@ -# BMAD Method - Gemini CLI Instructions - -## Activating Agents - -BMAD agents are concatenated in `.gemini/bmad-method/GEMINI.md`. - -### How to Use - -1. **Type Trigger**: Use `*{agent-name}` in your prompt -2. **Activate**: Agent persona activates from the concatenated file -3. **Continue**: Agent remains active for conversation - -### Examples - -``` -*dev - Activate development agent -*architect - Activate architect agent -*test - Activate test agent -``` - -### Notes - -- All agents loaded from single GEMINI.md file -- Triggers with asterisk: `*{agent-name}` -- Context includes all agents (may be large) diff --git a/docs/ide-info/github-copilot.md b/docs/ide-info/github-copilot.md deleted file mode 100644 index 7fd2e69a..00000000 --- a/docs/ide-info/github-copilot.md +++ /dev/null @@ -1,26 +0,0 @@ -# BMAD Method - GitHub Copilot Instructions - -## Activating Agents - -BMAD agents are installed as chat modes in `.github/chatmodes/`. - -### How to Use - -1. **Open Chat View**: Click Copilot icon in VS Code sidebar -2. **Select Mode**: Click mode selector (top of chat) -3. **Choose Agent**: Select the BMAD agent from dropdown -4. **Chat**: Agent is now active for this session - -### VS Code Settings - -Configured in `.vscode/settings.json`: - -- Max requests per session -- Auto-fix enabled -- MCP discovery enabled - -### Notes - -- Modes persist for the chat session -- Switch modes anytime via dropdown -- Multiple agents available in mode selector diff --git a/docs/ide-info/iflow.md b/docs/ide-info/iflow.md deleted file mode 100644 index 52ad248d..00000000 --- a/docs/ide-info/iflow.md +++ /dev/null @@ -1,33 +0,0 @@ -# BMAD Method - iFlow CLI Instructions - -## Activating Agents - -BMAD agents are installed as commands in `.iflow/commands/bmad/`. - -### How to Use - -1. **Access Commands**: Use iFlow command interface -2. **Navigate**: Browse to `_bmad/agents/` or `_bmad/tasks/` -3. **Select**: Choose the agent or task command -4. **Execute**: Run to activate - -### Command Structure - -``` -.iflow/commands/bmad/ -├── agents/ # Agent commands -└── tasks/ # Task commands -``` - -### Examples - -``` -/_bmad/agents/core-dev - Activate dev agent -/_bmad/tasks/core-setup - Execute setup task -``` - -### Notes - -- Commands organized by type (agents/tasks) -- Agent activates for session -- Similar to Crush command structure diff --git a/docs/ide-info/index.md b/docs/ide-info/index.md deleted file mode 100644 index 1ddee660..00000000 --- a/docs/ide-info/index.md +++ /dev/null @@ -1,24 +0,0 @@ -# IDE Guides - -BMAD Method works with any AI-powered development environment. Choose your IDE below for specific setup instructions and tips. - -## All Supported IDEs - -| IDE | Type | BMAD Support | -| ----------------------------------- | ----------------- | --------------------- | -| [Claude Code](claude-code.md) | CLI/Terminal | Native slash commands | -| [Cursor](cursor.md) | Desktop Editor | Full agent support | -| [VS Code / Windsurf](windsurf.md) | Desktop Editor | Extension-based | -| [Cline](cline.md) | VS Code Extension | Full support | -| [GitHub Copilot](github-copilot.md) | Extension | Workspace agents | -| [Augment](auggie.md) | Extension | Agent loading | -| [Codex](codex.md) | CLI | Prompt injection | -| [Gemini](gemini.md) | Web/API | Web bundles | -| [Roo](roo.md) | VS Code Extension | Mode support | -| [Kilo](kilo.md) | Extension | Basic support | -| [OpenCode](opencode.md) | Open Source | Full support | -| [Qwen](qwen.md) | Web/API | Web bundles | -| [Trae](trae.md) | Extension | Basic support | -| [Crush](crush.md) | Desktop | Agent support | -| [iFlow](iflow.md) | Extension | Prompt loading | -| [Rovo Dev](rovo-dev.md) | Atlassian | Integration | diff --git a/docs/ide-info/kilo.md b/docs/ide-info/kilo.md deleted file mode 100644 index ff420ded..00000000 --- a/docs/ide-info/kilo.md +++ /dev/null @@ -1,24 +0,0 @@ -# BMAD Method - KiloCode Instructions - -## Activating Agents - -BMAD agents are installed as custom modes in `.kilocodemodes`. - -### How to Use - -1. **Open Project**: Modes auto-load when project opens -2. **Select Mode**: Use mode selector in KiloCode interface -3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode -4. **Activate**: Mode is now active - -### Mode Format - -- Mode name: `bmad-{module}-{agent}` -- Display: `{icon} {title}` -- Example: `bmad-core-dev` shows as `🤖 Dev` - -### Notes - -- Modes persist until changed -- Similar to Roo Code mode system -- Icon shows in mode selector diff --git a/docs/ide-info/opencode.md b/docs/ide-info/opencode.md deleted file mode 100644 index 0612a15d..00000000 --- a/docs/ide-info/opencode.md +++ /dev/null @@ -1,24 +0,0 @@ -# BMAD Method - OpenCode Instructions - -## Activating Agents - -BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_name}` and workflow commands in `.opencode/command/BMAD/{module_name}`. - -### How to Use - -1. **Switch Agents**: Press **Tab** to cycle through primary agents or select using the `/agents` -2. **Activate Agent**: Once the Agent is selected say `hello` or any prompt to activate that agent persona -3. **Execute Commands**: Type `/bmad` to see and execute bmad workflow commands (commands allow for fuzzy matching) - -### Examples - -``` -/agents - to see a list of agents and switch between them -/_bmad/bmm/workflows/workflow-init - Activate the workflow-init command -``` - -### Notes - -- Press **Tab** to switch between primary agents (Analyst, Architect, Dev, etc.) -- Commands are autocompleted when you type `/` and allow for fuzzy matching -- Workflow commands execute in current agent context, make sure you have the right agent activated before running a command diff --git a/docs/ide-info/qwen.md b/docs/ide-info/qwen.md deleted file mode 100644 index f8b7de38..00000000 --- a/docs/ide-info/qwen.md +++ /dev/null @@ -1,25 +0,0 @@ -# BMAD Method - Qwen Code Instructions - -## Activating Agents - -BMAD agents are concatenated in `.qwen/bmad-method/QWEN.md`. - -### How to Use - -1. **Type Trigger**: Use `*{agent-name}` in your prompt -2. **Activate**: Agent persona activates from the concatenated file -3. **Continue**: Agent remains active for conversation - -### Examples - -``` -*dev - Activate development agent -*architect - Activate architect agent -*test - Activate test agent -``` - -### Notes - -- All agents loaded from single QWEN.md file -- Triggers with asterisk: `*{agent-name}` -- Similar to Gemini CLI setup diff --git a/docs/ide-info/roo.md b/docs/ide-info/roo.md deleted file mode 100644 index da30d248..00000000 --- a/docs/ide-info/roo.md +++ /dev/null @@ -1,27 +0,0 @@ -# BMAD Method - Roo Code Instructions - -## Activating Agents - -BMAD agents are installed as custom modes in `.roomodes`. - -### How to Use - -1. **Open Project**: Modes auto-load when project opens -2. **Select Mode**: Use mode selector in Roo interface -3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode -4. **Activate**: Mode is now active with configured permissions - -### Permission Levels - -Modes are configured with file edit permissions: - -- Development files only -- Configuration files only -- Documentation files only -- All files (if configured) - -### Notes - -- Modes persist until changed -- Each mode has specific file access rights -- Icon shows in mode selector for easy identification diff --git a/docs/ide-info/rovo-dev.md b/docs/ide-info/rovo-dev.md deleted file mode 100644 index 9da1e27e..00000000 --- a/docs/ide-info/rovo-dev.md +++ /dev/null @@ -1,22 +0,0 @@ -# BMAD Method - Rovo Dev Instructions - -## Activating Agents - -BMAD agents are installed as subagents in `.rovodev/subagents/`. - -### How to Use - -1. **Open Project**: Subagents auto-load when project opens -2. **Invoke Agent**: Type `@` and select agent (e.g., `@bmad-bmm-dev`, `@bmad-bmm-architect`) -3. **Reference Files**: Check `.rovodev/workflows/` and `.rovodev/references/` - -### Directory Structure - -- `.rovodev/subagents/` - BMAD agents -- `.rovodev/workflows/` - Workflow guides -- `.rovodev/references/` - Tasks and tools - -### Notes - -- Agents are automatically discovered by Rovo Dev -- Subagents use YAML frontmatter for configuration diff --git a/docs/ide-info/trae.md b/docs/ide-info/trae.md deleted file mode 100644 index ed00043b..00000000 --- a/docs/ide-info/trae.md +++ /dev/null @@ -1,25 +0,0 @@ -# BMAD Method - Trae Instructions - -## Activating Agents - -BMAD agents are installed as rules in `.trae/rules/`. - -### How to Use - -1. **Type Trigger**: Use `@{agent-name}` in your prompt -2. **Activate**: Agent persona activates automatically -3. **Continue**: Agent remains active for conversation - -### Examples - -``` -@dev - Activate development agent -@architect - Activate architect agent -@task-setup - Execute setup task -``` - -### Notes - -- Rules auto-load from `.trae/rules/` directory -- Multiple agents can be referenced: `@dev and @test` -- Agent follows YAML configuration in rule file diff --git a/docs/ide-info/windsurf.md b/docs/ide-info/windsurf.md deleted file mode 100644 index 97fc010c..00000000 --- a/docs/ide-info/windsurf.md +++ /dev/null @@ -1,22 +0,0 @@ -# BMAD Method - Windsurf Instructions - -## Activating Agents - -BMAD agents are installed as workflows in `.windsurf/workflows/`. - -### How to Use - -1. **Open Workflows**: Access via Windsurf menu or command palette -2. **Select Workflow**: Choose the agent/task workflow -3. **Execute**: Run to activate that agent persona - -### Workflow Types - -- **Agent workflows**: `{module}-{agent}.md` (auto_execution_mode: 3) -- **Task workflows**: `task-{module}-{task}.md` (auto_execution_mode: 2) - -### Notes - -- Agents run with higher autonomy (mode 3) -- Tasks run with guided execution (mode 2) -- Workflows persist for the session diff --git a/docs/index.md b/docs/index.md index 3bd13681..6e81e1fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,12 @@ # BMad Documentation Index -Complete map of all BMad Method v6 documentation with recommended reading paths. - ---- - ## 🎯 Getting Started (Start Here!) **New users:** Start with one of these based on your situation: | Your Situation | Start Here | Then Read | | ---------------------- | -------------------------------------------------- | ----------------------------------------------------------- | -| **Brand new to BMad** | [Quick Start Guide](./modules/bmm/quick-start) | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) | +| **Brand new to BMad** | [Quick Start Guide](bmm/quick-start) | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) | | **Upgrading from v4** | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) | [Quick Start Guide](./modules/bmm/quick-start) | | **Brownfield project** | [Brownfield Guide](./modules/bmm/brownfield-guide) | [Quick Start Guide](./modules/bmm/quick-start) | @@ -28,7 +24,7 @@ Complete map of all BMad Method v6 documentation with recommended reading paths. - **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users - **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings -- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing +- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - (temporarily non-functional) Maintainer guide for bundle auto-publishing --- @@ -60,38 +56,6 @@ AI-powered creative thinking and brainstorming. - **[CIS Module README](./modules/cis/)** - Module overview and workflows ---- - -## 🖥️ IDE-Specific Guides - -Instructions for loading agents and running workflows in your development environment. - -**Popular IDEs:** - -- [Claude Code](./ide-info/claude-code.md) -- [Cursor](./ide-info/cursor.md) -- [VS Code](./ide-info/windsurf.md) - -**Other Supported IDEs:** - -- [Augment](./ide-info/auggie.md) -- [Cline](./ide-info/cline.md) -- [Codex](./ide-info/codex.md) -- [Crush](./ide-info/crush.md) -- [Gemini](./ide-info/gemini.md) -- [GitHub Copilot](./ide-info/github-copilot.md) -- [IFlow](./ide-info/iflow.md) -- [Kilo](./ide-info/kilo.md) -- [OpenCode](./ide-info/opencode.md) -- [Qwen](./ide-info/qwen.md) -- [Roo](./ide-info/roo.md) -- [Rovo Dev](./ide-info/rovo-dev.md) -- [Trae](./ide-info/trae.md) - -**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions. - ---- - ## 🔧 Advanced Topics ### Custom Agents, Workflow and Modules @@ -109,7 +73,6 @@ Instructions for loading agents and running workflows in your development enviro 2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on 3. [BMM Module README](./modules/bmm/) - Understand agents 4. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology -5. [Your IDE guide](./ide-info/) - Optimize your workflow ### Path 2: Game Development Project @@ -117,7 +80,6 @@ Instructions for loading agents and running workflows in your development enviro 2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on 3. [BMM Module README](./modules/bmm/) - Game agents are included 4. [BMGD Workflows Guide](./modules/bmgd/workflows-guide) - Game-specific workflows -5. [Your IDE guide](./ide-info/) - Optimize your workflow ### Path 3: Upgrading from v4 diff --git a/docs/v4-to-v6-upgrade.md b/docs/v4-to-v6-upgrade.md index 788d570a..ba1e0dae 100644 --- a/docs/v4-to-v6-upgrade.md +++ b/docs/v4-to-v6-upgrade.md @@ -8,42 +8,36 @@ BMad v6 represents a complete ground-up rewrite with significant architectural c ## Automatic V4 Detection -When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects: +When you run `npm run install:bmad` on a project, the installer automatically detects: -- **Legacy folders**: Any folders starting with `_bmad`, `bmad` (lowercase), or `Bmad` +- **Legacy folders**: Any folders starting with `bmad-core` or `bmad-core` - **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.) ### What Happens During Detection -1. **Automatic Backup of v4 Modules**: All `_bmad-*` folders are moved to `v4-backup/` in your project root +1. **Automatic Backup of v4 Modules**: All `.bmad-core` folders are moved to `v4-backup/` in your project root - If a backup already exists, a timestamp is added to avoid conflicts - - Example: `_bmad-core` → `v4-backup/_bmad-core` + - Example: `.bmad-core` → `v4-backup/_bmad-core` - Your project files and data are NOT affected 2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed - - Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc. - - These old commands would still reference v4 folder structure if left in place - - The installer provides copy/paste terminal commands for your platform - - You can proceed without cleanup, but removing them prevents confusion with old v4 commands - ---- + - Located in IDE config folders, for example claude: `.claude/commands/BMad/agents`, `.claude/commands/BMad/tasks`, etc. + - NOTE: if the upgrade and install of v6 finished, the new commands will be under `.claude/commands/bmad//agents|workflows` + - Note 2: If you accidentally delete the wrong/new bmad commands - you can easily restore them by rerunning the installer, and choose quick update option, and all will be reapplied properly. ## Module Migration ### Deprecated Modules -| v4 Module | v6 Status | -| ----------------------------- | ------------------------------------------------ | -| `_bmad-2d-phaser-game-dev` | Integrated into BMM | -| `_bmad-2d-unity-game-dev` | Integrated into BMM | -| `_bmad-godot-game-dev` | Integrated into BMM | -| `_bmad-*-game-dev` (any) | Integrated into BMM | -| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM | -| `_bmad-creative-writing` | Not adapted - New module releasing soon | +| v4 Module | v6 Status | +| ----------------------------- | ---------------------------------------------- | +| `_bmad-2d-phaser-game-dev` | Integrated into new BMGD Module | +| `_bmad-2d-unity-game-dev` | Integrated into new BMGD Module | +| `_bmad-godot-game-dev` | Integrated into new BMGD Module | +| `_bmad-*-game-dev` (any) | Integrated into new BMGD Module | +| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming soon | +| `_bmad-creative-writing` | Not adapted - New v6 module coming soon | -**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine. - ---- ## Architecture Changes @@ -64,12 +58,13 @@ your-project/ ``` your-project/ └── _bmad/ # Single installation folder, default _bmad + └── _config/ # Your customizations + | └── agents/ # Agent customization files ├── core/ # Real core framework (applies to all modules) ├── bmm/ # BMad Method (software/game dev) ├── bmb/ # BMad Builder (create agents/workflows) ├── cis/ # Creative Intelligence Suite - └── _config/ # Your customizations - └── agents/ # Agent customization files + ``` ### Key Concept Changes @@ -77,34 +72,28 @@ your-project/ - **v4 `_bmad-core`**: Was actually the BMad Method - **v6 `_bmad/core/`**: Is the real universal core framework - **v6 `_bmad/bmm/`**: Is the BMad Method module -- **Module identification**: All modules now have a `config.yaml` file - ---- +- **Module identification**: All modules now have a `config.yaml` file once installed at the root of the modules installed folder ## Project Progress Migration -### If You've Completed Planning Phase (PRD/Architecture) with the BMad Method: +### If You've Completed Some or all Planning Phases (Brief/PRD/UX/Architecture) with the BMad Method: -After running the v6 installer: +After running the v6 installer, if you kept the paths the same as the installation suggested, you will need to move a few files, or run the installer again. It is recommended to stick with these defaults as it will be easier to adapt if things change in the future. -1. **Run `workflow-init`** workflow to set up the guided workflow system -2. **Specify your project level** when prompted: - - If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4** - - This tells v6 you've already completed planning and solutioning phases -3. **Document paths**: Keep your existing paths during installation - - Default PRD/Architecture location: `docs/` - - Default stories location: `docs/sprint-artifacts/` - - **Accept these defaults** if you're already using them in v4 +If you have any planning artifacts, put them in a folder called _bmad-output/planning-artifacts at the root of your project, ensuring that: +PRD has PRD in the file name or folder name if sharded. +Similar for 'brief', 'architecture', 'ux-design'. -> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files. +If you have other long term docs that will not be as ephemeral as these project docs, you can put them in the /docs folder, ideally with a index.md file. + +HIGHLY RECOMMENDED NOTE: If you are only partway through planning, its highly recommended to restart and do the PRD, UX and ARCHITECTURE steps. You could even use your existing documents as inputs letting the agent know you want to redo them with the new workflows. These optimized v6 progressive discovery workflows that also will utilize web search at key moments, while offering better advanced elicitation and part mode in the IDE will produce superior results. And then once all are complete, an epics with stories is generated after the architecture step now - ensuring it uses input from all planing documents. ### If You're Mid-Development (Stories Created/Implemented) 1. Complete the v6 installation as above -2. Run `workflow-init` and specify Level 3 or 4 -3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4) - ---- +2. Ensure you have a file called epics.md or epics/epic*.md - these need to be located under the _bmad-output/planning-artifacts folder. +3. Run the scrum masters `sprint-planning` workflow to generate the implementation tracking plan in _bmad-output/implementation-artifacts. +4. Inform the SM after the output is complete which epics and stories were completed already and should be parked properly in the file. ## Agent Customization Migration @@ -131,13 +120,15 @@ persona: - Always upbeat and adventurous ``` +There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](agent-customization-guide.md) + +CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations. + **How it works:** - Base agent: `_bmad/bmm/agents/pm.md` - Customization: `_bmad/_config/agents/bmm-pm.customize.yaml` -- Result: Agent uses your custom name and style, but updates don't overwrite your changes - ---- +- Rebuild all agents -> Result: Agent uses your custom name and style ## Document Compatibility @@ -151,77 +142,3 @@ persona: - ✅ Mixed approaches All workflow files are scanned automatically. No manual configuration needed. - ---- - -## Installation Steps - -### 1. Clone Repository - -```bash -git clone https://github.com/bmad-code-org/BMAD-METHOD -cd BMAD-METHOD -npm install -``` - -### 2. Run Installer on Your v4 Project - -```bash -npx bmad-method install -``` - -**Enter the full path to your v4 project** when prompted. - -### 3. Follow Interactive Prompts - -The installer will: - -1. Detect v4 installation and offer to backup `_bmad-*` folders -2. Prompt for recommended cleanup (you can skip) -3. Let you select modules (recommend: BMM for software and or game development) -4. Configure core settings (name, language, etc.) -5. Configure module-specific options -6. Configure IDE integrations - -### 4. Accept Default Paths - -If you're using: - -- `docs/` for PRD and architecture -- `docs/sprint-artifacts/` for story files - -**Accept these defaults** during installation. - -### 5. Initialize Workflow - -After installation: - -1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents: - - [Claude Code](./ide-info/claude-code.md) - - [Cursor](./ide-info/cursor.md) - - [VS Code/Windsurf](./ide-info/) - Check your IDE folder - -2. **Wait for the agent's menu** to appear - -3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow" - -Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4. - ---- - -## Post-Migration Checklist - -- [ ] v4 folders backed up to `v4-backup/` -- [ ] v6 installed to `_bmad/` folder -- [ ] `workflow-init` run with correct project level selected -- [ ] Agent customizations migrated to `_bmad/_config/agents/` if needed -- [ ] IDE integration working (test by listing agents) -- [ ] For active development: `sprint-planning` workflow executed - ---- - -## Getting Help - -- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj) -- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues) -- **Docs**: Check `_bmad/docs/` in your installation for IDE-specific instructions diff --git a/docs/web-bundles-gemini-gpt-guide.md b/docs/web-bundles-gemini-gpt-guide.md index 0dd3bb85..2fdd1e6c 100644 --- a/docs/web-bundles-gemini-gpt-guide.md +++ b/docs/web-bundles-gemini-gpt-guide.md @@ -2,15 +2,15 @@ ## IMPORTANT NOTE -The Web Bundling Feature is being rebuilt from the ground up, current bundles for v6 may be incomplete or missing functionality and are not optimized. This will be rectified very soon, with a more expansive guide. +The Web Bundling Feature is being rebuilt from the ground up, current bundles found for v6 may be incomplete or missing functionality and are not optimized. ## What Are Web bundles -Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file. +Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload. ## What Are Web Bundles? -Web bundles are standalone XML files containing: +Web bundles are standalone files containing: - Complete agent persona and instructions - All workflows and dependencies diff --git a/docs/workflow-vendoring-customization-inheritance.md b/docs/workflow-vendoring-customization-inheritance.md new file mode 100644 index 00000000..c661b2a4 --- /dev/null +++ b/docs/workflow-vendoring-customization-inheritance.md @@ -0,0 +1,42 @@ +# Workflow Vendoring, Customization, and Inheritance (Official Support Consing Soon) + +Vendoring and Inheritance of workflows are 2 ways of sharing or reutilizing workflows - but with some key distinctions and use cases. + +## 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//workflows/4-production/dev-story/workflow.md" + exec: "{project-root}/_bmad//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 (Official Support 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 (Official Support 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. diff --git a/samples/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md b/samples/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md index 26d13df6..83988ac3 100644 --- a/samples/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md +++ b/samples/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md @@ -25,10 +25,6 @@ - @/docs/installers-bundlers/ - Tooling-specific documentation directory - @/tools/cli/README.md - CLI usage documentation (comprehensive) -### IDE-Specific Documentation - -- @/docs/ide-info/ - IDE-specific setup guides (15+ files) - ### Module Documentation Each module may have its own docs: @@ -73,7 +69,6 @@ Follow Keep a Changelog format: When code changes, check these docs: - CLI changes → tools/cli/README.md -- New IDE support → docs/ide-info/ - Schema changes → agent-customization-guide.md - Bundle changes → web-bundles-gemini-gpt-guide.md - Installer changes → installers-bundlers/ diff --git a/src/modules/bmgd/docs/glossary.md b/src/modules/bmgd/docs/glossary.md index f4765038..92de3676 100644 --- a/src/modules/bmgd/docs/glossary.md +++ b/src/modules/bmgd/docs/glossary.md @@ -291,4 +291,3 @@ Phase 4 workflows inherit from BMM base and add BMGD-specific overrides. - **[Quick Start Guide](./quick-start.md)** - Get started with BMGD - **[Game Types Guide](./game-types-guide.md)** - Game genre reference -- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions diff --git a/src/modules/bmgd/docs/index.md b/src/modules/bmgd/docs/index.md index 06ddba4b..510cf899 100644 --- a/src/modules/bmgd/docs/index.md +++ b/src/modules/bmgd/docs/index.md @@ -50,7 +50,6 @@ Understanding how BMGD works: Essential reference materials: - **[Glossary](./glossary.md)** - Key game development terminology -- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions --- @@ -148,7 +147,6 @@ BMGD Documentation ├── quick-flow-guide.md # Rapid prototyping and development ├── game-types-guide.md # Game type templates ├── glossary.md # Terminology -└── troubleshooting.md # Common issues ``` --- @@ -164,9 +162,6 @@ BMGD Documentation ### Related Documentation - **[BMM Documentation](../../bmm/docs/index.md)** - Core BMad Method documentation -- **[IDE Guides](../../ide-info/)** - Configure your development environment - ---- ## Tips for Using This Documentation diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md index 0992fdd0..e33f481b 100644 --- a/src/modules/bmm/README.md +++ b/src/modules/bmm/README.md @@ -111,10 +111,6 @@ Use party mode to engage all 19+ agents (from BMM, CIS, BMB, custom modules) in - **[Brownfield Guide](./docs/brownfield-guide.md)** - Working with existing codebases - **[Quick Spec Flow](./docs/quick-spec-flow.md)** - Fast-track for Level 0-1 projects - **[Enterprise Agentic Development](./docs/enterprise-agentic-development.md)** - Team collaboration patterns -- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions -- **[IDE Setup Guides](../../../docs/ide-info/)** - Configure Claude Code, Cursor, Windsurf, etc. - ---- ## 🤝 Community diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md index b75d506b..80403416 100644 --- a/src/modules/bmm/docs/brownfield-guide.md +++ b/src/modules/bmm/docs/brownfield-guide.md @@ -725,7 +725,6 @@ flowchart TD - **[Quick Start Guide](./quick-start.md)** - Getting started with BMM - **[Glossary](./glossary.md)** - Key terminology - **[FAQ](./faq.md)** - Common questions -- **[Troubleshooting](./troubleshooting.md)** - Problem resolution - **[Workflow Documentation](./index.md#-workflow-guides)** - Complete workflow reference --- diff --git a/src/modules/bmm/docs/enterprise-agentic-development.md b/src/modules/bmm/docs/enterprise-agentic-development.md deleted file mode 100644 index f12a3ec1..00000000 --- a/src/modules/bmm/docs/enterprise-agentic-development.md +++ /dev/null @@ -1,686 +0,0 @@ -# Enterprise Agentic Development with BMad Method - -**The paradigm shift: From team-based story parallelism to individual epic ownership** - -**Reading Time:** ~18 minutes - ---- - -## Table of Contents - -- [The Paradigm Shift](#the-paradigm-shift) -- [The Evolving Role of Product Managers and UX Designers](#the-evolving-role-of-product-managers-and-ux-designers) -- [How BMad Method Enables PM/UX Technical Evolution](#how-bmad-method-enables-pmux-technical-evolution) -- [Team Collaboration Patterns](#team-collaboration-patterns) -- [Work Distribution Strategies](#work-distribution-strategies) -- [Enterprise Configuration with Git Submodules](#enterprise-configuration-with-git-submodules) -- [Best Practices](#best-practices) -- [Common Scenarios](#common-scenarios) - ---- - -## The Paradigm Shift - -### Traditional Agile: Team-Based Story Parallelism - -- **Epic duration:** 4-12 weeks across multiple sprints -- **Story duration:** 2-5 days per developer -- **Team size:** 5-9 developers working on same epic -- **Parallelization:** Multiple devs on stories within single epic -- **Coordination:** Constant - daily standups, merge conflicts, integration overhead - -**Example:** Payment Processing Epic - -- Sprint 1-2: Backend API (Dev A) -- Sprint 1-2: Frontend UI (Dev B) -- Sprint 2-3: Testing (Dev C) -- **Result:** 6-8 weeks, 3 developers, high coordination - -### Agentic Development: Individual Epic Ownership - -- **Epic duration:** Hours to days (not weeks) -- **Story duration:** 30 min to 4 hours with AI agent -- **Team size:** 1 developer + AI agents completes full epics -- **Parallelization:** Developers work on separate epics -- **Coordination:** Minimal - epic boundaries, async updates - -**Same Example:** Payment Processing Epic - -- Day 1 AM: Backend API stories (1 dev + agent, 3-4 stories) -- Day 1 PM: Frontend UI stories (same dev + agent, 2-3 stories) -- Day 2: Testing & deployment (same dev + agent, 2 stories) -- **Result:** 1-2 days, 1 developer, minimal coordination - -### The Core Difference - -**What changed:** AI agents collapse story duration from days to hours, making **epic-level ownership** practical. - -**Impact:** Single developer with BMad Method can deliver in 1 day what previously required full team and multiple sprints. - ---- - -## The Evolving Role of Product Managers and UX Designers - -### The Future is Now - -Product Managers and UX Designers are undergoing **the most significant transformation since the creation of these disciplines**. The emergence of AI agents is creating a new breed of technical product leaders who translate vision directly into working code. - -### From Spec Writers to Code Orchestrators - -**Traditional PM/UX (Pre-2025):** - -- Write PRDs, hand off to engineering -- Wait weeks/months for implementation -- Limited validation capabilities -- Non-technical role, heavy on process - -**Emerging PM/UX (2025+):** - -- Write AI-optimized PRDs that **feed agentic pipelines directly** -- Generate working prototypes in 10-15 minutes -- Review pull requests from AI agents -- Technical fluency is **table stakes**, not optional -- Orchestrate cloud-based AI agent teams - -### Industry Research (November 2025) - -- **56% of product professionals** cite AI/ML as top focus -- **AI agents automating** customer discovery, PRD creation, status reporting -- **PRD-to-Code automation** enables PMs to build and deploy apps in 10-15 minutes -- **By 2026**: Roles converging into "Full-Stack Product Lead" (PM + Design + Engineering) -- **Very high salaries** for AI agent PMs who orchestrate autonomous dev systems - -### Required Skills for Modern PMs/UX - -1. **AI Prompt Engineering** - Writing PRDs AI agents can execute autonomously -2. **Coding Literacy** - Understanding code structure, APIs, data flows (not production coding) -3. **Agentic Workflow Design** - Orchestrating multi-agent systems (planning → design → dev) -4. **Technical Architecture** - Reasoning frameworks, memory systems, tool integration -5. **Data Literacy** - Interpreting model outputs, spotting trends, identifying gaps -6. **Code Review** - Evaluating AI-generated PRs for correctness and vision alignment - -### What Remains Human - -**AI Can't Replace:** - -- Product vision (market dynamics, customer pain, strategic positioning) -- Empathy (deep user research, emotional intelligence, stakeholder management) -- Creativity (novel problem-solving, disruptive thinking) -- Judgment (prioritization decisions, trade-off analysis) -- Ethics (responsible AI use, privacy, accessibility) - -**What Changes:** - -- PMs/UX spend **more time on human elements** (AI handles routine execution) -- Barrier between "thinking" and "building" collapses -- Product leaders become **builder-thinkers**, not just spec writers - -### The Convergence - -- **PMs learning to code** with GitHub Copilot, Cursor, v0 -- **UX designers generating code** with UXPin Merge, Figma-to-code tools -- **Developers becoming orchestrators** reviewing AI output vs writing from scratch - -**The Bottom Line:** By 2026, successful PMs/UX will fluently operate in both vision and execution. **BMad Method provides the structured framework to make this transition.** - ---- - -## How BMad Method Enables PM/UX Technical Evolution - -BMad Method is specifically designed to position PMs and UX designers for this future. - -### 1. AI-Executable PRD Generation - -**PM Workflow:** - -```bash -bmad pm *create-prd -``` - -**BMad produces:** - -- Structured, machine-readable requirements -- Functional Requirements (FRs) with testable acceptance criteria -- Non-Functional Requirements (NFRs) with measurable targets -- Technical context for AI agents - -**Why it matters:** Traditional PRDs are human-readable prose. BMad PRDs are **AI-executable requirement specifications**. - -**PM Value:** Clear requirements that feed into architecture decisions, then into story breakdown. No ambiguity. - -### 2. Human-in-the-Loop Architecture - -**Architect/PM Workflow:** - -```bash -bmad architect *create-architecture -``` - -**BMad produces:** - -- System architecture aligned with PRD's FRs/NFRs -- Architecture Decision Records (ADRs) -- FR/NFR-specific technical guidance -- Integration patterns and standards - -**Why it matters:** PMs can **understand and validate** technical decisions. Architecture is conversational, not template-driven. - -**PM Value:** Technical fluency built through guided architecture process. PMs learn while creating. - -### 3. Automated Epic/Story Breakdown (AFTER Architecture) - -**PM Workflow:** - -```bash -bmad pm *create-epics-and-stories -``` - -**V6 Improvement:** Epics and stories are now created AFTER architecture for better quality. The workflow uses both PRD (FRs/NFRs) and Architecture to create technically-informed stories. - -**BMad produces:** - -- Epic files with clear objectives -- Story files with acceptance criteria, context, technical guidance -- Priority assignments (P0-P3) -- Dependency mapping informed by architectural decisions - -**Why it matters:** Stories become **work packages for cloud AI agents**. Each story is self-contained with full context AND aligned with architecture. - -**PM Value:** No more "story refinement sessions" with engineering. Stories are technically grounded from the start. - -### 4. Cloud Agentic Pipeline (Emerging Pattern) - -**Current State (2025):** - -``` -PM writes BMad PRD (FRs/NFRs) - ↓ -Architect creates architecture (technical decisions) - ↓ -create-epics-and-stories generates story queue (informed by architecture) - ↓ -Stories loaded by human developers + BMad agents - ↓ -Developers create PRs - ↓ -PM/Team reviews PRs - ↓ -Merge and deploy -``` - -**Near Future (2026):** - -``` -PM writes BMad PRD (FRs/NFRs) - ↓ -Architecture auto-generated with PM approval - ↓ -create-epics-and-stories generates story queue (informed by architecture) - ↓ -Stories automatically fed to cloud AI agent pool - ↓ -AI agents implement stories in parallel - ↓ -AI agents create pull requests - ↓ -PM/UX/Senior Devs review PRs - ↓ -Approved PRs auto-merge - ↓ -Continuous deployment to production -``` - -**Time Savings:** - -- **Traditional:** PM writes spec → 2-4 weeks engineering → review → deploy (6-8 weeks) -- **BMad Agentic:** PM writes PRD → AI agents implement → review PRs → deploy (2-5 days) - -### 5. UX Design Integration - -**UX Designer Workflow:** - -```bash -bmad ux *create-ux-design -``` - -**BMad produces:** - -- Component-based design system -- Interaction patterns aligned with tech stack -- Accessibility guidelines -- Responsive design specifications - -**Why it matters:** Design specs become **implementation-ready** for AI agents. No "lost in translation" between design and dev. - -**UX Value:** Designs validated through working prototypes, not static mocks. Technical understanding built through BMad workflows. - -### 6. PM Technical Skills Development - -**BMad teaches PMs technical skills through:** - -- **Conversational workflows** - No pre-requisite knowledge, learn by doing -- **Architecture facilitation** - Understand system design through guided questions -- **Story context assembly** - See how code patterns inform implementation -- **Code review workflows** - Learn to evaluate code quality, patterns, standards - -**Example:** PM runs `create-architecture` workflow: - -- BMad asks about scale, performance, integrations -- PM answers business questions -- BMad explains technical implications -- PM learns architecture concepts while making decisions - -**Result:** PMs gain **working technical knowledge** without formal CS education. - -### 7. Organizational Leverage - -**Traditional Model:** - -- 1 PM → supports 5-9 developers → delivers 1-2 features/quarter - -**BMad Agentic Model:** - -- 1 PM → writes BMad PRD → 20-50 AI agents execute stories in parallel → delivers 5-10 features/quarter - -**Leverage multiplier:** 5-10× with same PM headcount. - -### 8. Quality Consistency - -**BMad ensures:** - -- AI agents follow architectural patterns consistently -- Code standards applied uniformly -- PRD traceability throughout implementation (via acceptance criteria) -- No "telephone game" between PM, design, and dev - -**PM Value:** What gets built **matches what was specified**, drastically reducing rework. - -### 9. Rapid Prototyping for Validation - -**PM Workflow (with BMad + Cursor/v0):** - -1. Use BMad to generate PRD structure and requirements -2. Extract key user flow from PRD -3. Feed to Cursor/v0 with BMad context -4. Working prototype in 10-15 minutes -5. Validate with users **before** committing to full development - -**Traditional:** Months of development to validate idea -**BMad Agentic:** Hours of development to validate idea - -### 10. Career Path Evolution - -**BMad positions PMs for emerging roles:** - -- **AI Agent Product Manager** - Orchestrate autonomous development systems -- **Full-Stack Product Lead** - Oversee product, design, engineering with AI leverage -- **Technical Product Strategist** - Bridge business vision and technical execution - -**Hiring advantage:** PMs using BMad demonstrate: - -- Technical fluency (can read architecture, validate tech decisions) -- AI-native workflows (structured requirements, agentic orchestration) -- Results (ship 5-10× faster than peers) - ---- - -## Team Collaboration Patterns - -### Old Pattern: Story Parallelism - -**Traditional Agile:** - -``` -Epic: User Dashboard (8 weeks) -├─ Story 1: Backend API (Dev A, Sprint 1-2) -├─ Story 2: Frontend Layout (Dev B, Sprint 1-2) -├─ Story 3: Data Viz (Dev C, Sprint 2-3) -└─ Story 4: Integration Testing (Team, Sprint 3-4) - -Challenge: Coordination overhead, merge conflicts, integration issues -``` - -### New Pattern: Epic Ownership - -**Agentic Development:** - -``` -Project: Analytics Platform (2-3 weeks) - -Developer A: -└─ Epic 1: User Dashboard (3 days, 12 stories sequentially with AI) - -Developer B: -└─ Epic 2: Admin Panel (4 days, 15 stories sequentially with AI) - -Developer C: -└─ Epic 3: Reporting Engine (5 days, 18 stories sequentially with AI) - -Benefit: Minimal coordination, epic-level ownership, clear boundaries -``` - ---- - -## Work Distribution Strategies - -### Strategy 1: Epic-Based (Recommended) - -**Best for:** 2-10 developers - -**Approach:** Each developer owns complete epics, works sequentially through stories - -**Example:** - -```yaml -epics: - - id: epic-1 - title: Payment Processing - owner: alice - stories: 8 - estimate: 2 days - - - id: epic-2 - title: User Dashboard - owner: bob - stories: 12 - estimate: 3 days -``` - -**Benefits:** Clear ownership, minimal conflicts, epic cohesion, reduced coordination - -### Strategy 2: Layer-Based - -**Best for:** Full-stack apps, specialized teams - -**Example:** - -``` -Frontend Dev: Epic 1 (Product Catalog UI), Epic 3 (Cart UI) -Backend Dev: Epic 2 (Product API), Epic 4 (Cart Service) -``` - -**Benefits:** Developers in expertise area, true parallel work, clear API contracts - -**Requirements:** Strong architecture phase, clear API contracts upfront - -### Strategy 3: Feature-Based - -**Best for:** Large teams (10+ developers) - -**Example:** - -``` -Team A (2 devs): Payments feature (4 epics) -Team B (2 devs): User Management feature (3 epics) -Team C (2 devs): Analytics feature (3 epics) -``` - -**Benefits:** Feature team autonomy, domain expertise, scalable to large orgs - ---- - -## Enterprise Configuration with Git Submodules - -### The Challenge - -**Problem:** Teams customize BMad (agents, workflows, configs) but don't want personal tooling in main repo. - -**Anti-pattern:** Adding `_bmad/` to `.gitignore` breaks IDE tools, submodule management. - -### The Solution: Git Submodules - -**Benefits:** - -- BMad exists in project but tracked separately -- Each developer controls their own BMad version/config -- Optional team config sharing via submodule repo -- IDE tools maintain proper context - -### Setup (New Projects) - -**1. Create optional team config repo:** - -```bash -git init bmm-config -cd bmm-config -npx bmad-method install -# Customize for team standards -git commit -m "Team BMM config" -git push origin main -``` - -**2. Add submodule to project:** - -```bash -cd /path/to/your-project -git submodule add https://github.com/your-org/bmm-config.git bmad -git commit -m "Add BMM as submodule" -``` - -**3. Team members initialize:** - -```bash -git clone https://github.com/your-org/your-project.git -cd your-project -git submodule update --init --recursive -# Make personal customizations in _bmad/ -``` - -### Daily Workflow - -**Work in main project:** - -```bash -cd /path/to/your-project -# BMad available at ./_bmad/, load agents normally -``` - -**Update personal config:** - -```bash -cd bmad -# Make changes, commit locally, don't push unless sharing -``` - -**Update to latest team config:** - -```bash -cd bmad -git pull origin main -``` - -### Configuration Strategies - -**Option 1: Fully Personal** - No submodule, each dev installs independently, use `.gitignore` - -**Option 2: Team Baseline + Personal** - Submodule has team standards, devs add personal customizations locally - -**Option 3: Full Team Sharing** - All configs in submodule, team collaborates on improvements - ---- - -## Best Practices - -### 1. Epic Ownership - -- **Do:** Assign entire epic to one developer (context → implementation → retro) -- **Don't:** Split epics across multiple developers (coordination overhead, context loss) - -### 2. Dependency Management - -- **Do:** Identify epic dependencies in planning, document API contracts, complete prerequisites first -- **Don't:** Start dependent epic before prerequisite ready, change API contracts without coordination - -### 3. Communication Cadence - -**Traditional:** Daily standups essential -**Agentic:** Lighter coordination - -**Recommended:** - -- Daily async updates ("Epic 1, 60% complete, no blockers") -- Twice-weekly 15min sync -- Epic completion demos -- Sprint retro after all epics complete - -### 4. Branch Strategy - -```bash -feature/epic-1-payment-processing (Alice) -feature/epic-2-user-dashboard (Bob) -feature/epic-3-admin-panel (Carol) - -# PR and merge when epic complete -``` - -### 5. Testing Strategy - -- **Story-level:** Unit tests (DoD requirement, written by agent during dev-story) -- **Epic-level:** Integration tests across stories -- **Project-level:** E2E tests after multiple epics complete - -### 6. Documentation Updates - -- **Real-time:** `sprint-status.yaml` updated by workflows -- **Epic completion:** Update architecture docs, API docs, README if changed -- **Sprint completion:** Incorporate retrospective insights - -### 7. Metrics (Different from Traditional) - -**Traditional:** Story points per sprint, burndown charts -**Agentic:** Epics per week, stories per day, time to epic completion - -**Example velocity:** - -- Junior dev + AI: 1-2 epics/week (8-15 stories) -- Mid-level dev + AI: 2-3 epics/week (15-25 stories) -- Senior dev + AI: 3-5 epics/week (25-40 stories) - ---- - -## Common Scenarios - -### Scenario 1: Startup (2 Developers) - -**Project:** SaaS MVP (Level 3) - -**Distribution:** - -``` -Developer A: -├─ Epic 1: Authentication (3 days) -├─ Epic 3: Payment Integration (2 days) -└─ Epic 5: Admin Dashboard (3 days) - -Developer B: -├─ Epic 2: Core Product Features (4 days) -├─ Epic 4: Analytics (3 days) -└─ Epic 6: Notifications (2 days) - -Total: ~2 weeks -Traditional estimate: 3-4 months -``` - -**BMM Setup:** Direct installation, both use Claude Code, minimal customization - -### Scenario 2: Mid-Size Team (8 Developers) - -**Project:** Enterprise Platform (Level 4) - -**Distribution (Layer-Based):** - -``` -Backend (2 devs): 6 API epics -Frontend (2 devs): 6 UI epics -Full-stack (2 devs): 4 integration epics -DevOps (1 dev): 3 infrastructure epics -QA (1 dev): 1 E2E testing epic - -Total: ~3 weeks -Traditional estimate: 9-12 months -``` - -**BMM Setup:** Git submodule, team config repo, mix of Claude Code/Cursor users - -### Scenario 3: Large Enterprise (50+ Developers) - -**Project:** Multi-Product Platform - -**Organization:** - -- 5 product teams (8-10 devs each) -- 1 platform team (10 devs - shared services) -- 1 infrastructure team (5 devs) - -**Distribution (Feature-Based):** - -``` -Product Team A: Payments (10 epics, 2 weeks) -Product Team B: User Mgmt (12 epics, 2 weeks) -Product Team C: Analytics (8 epics, 1.5 weeks) -Product Team D: Admin Tools (10 epics, 2 weeks) -Product Team E: Mobile (15 epics, 3 weeks) - -Platform Team: Shared Services (continuous) -Infrastructure Team: DevOps (continuous) - -Total: 3-4 months -Traditional estimate: 2-3 years -``` - -**BMM Setup:** Each team has own submodule config, org-wide base config, variety of IDE tools - ---- - -## Summary - -### Key Transformation - -**Work Unit Changed:** - -- **Old:** Story = unit of work assignment -- **New:** Epic = unit of work assignment - -**Why:** AI agents collapse story duration (days → hours), making epic ownership practical. - -### Velocity Impact - -- **Traditional:** Months for epic delivery, heavy coordination -- **Agentic:** Days for epic delivery, minimal coordination -- **Result:** 10-50× productivity gains - -### PM/UX Evolution - -**BMad Method enables:** - -- PMs to write AI-executable PRDs -- UX designers to validate through working prototypes -- Technical fluency without CS degrees -- Orchestration of cloud AI agent teams -- Career evolution to Full-Stack Product Lead - -### Enterprise Adoption - -**Git submodules:** Best practice for BMM management across teams -**Team flexibility:** Mix of tools (Claude Code, Cursor, Windsurf) with shared BMM foundation -**Scalable patterns:** Epic-based, layer-based, feature-based distribution strategies - -### The Future (2026) - -PMs write BMad PRDs → Stories auto-fed to cloud AI agents → Parallel implementation → Human review of PRs → Continuous deployment - -**The future isn't AI replacing PMs—it's AI-augmented PMs becoming 10× more powerful.** - ---- - -## Related Documentation - -- [FAQ](./faq.md) - Common questions -- [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained -- [Quick Start Guide](./quick-start.md) - Getting started -- [Workflow Documentation](./index.md#-workflow-guides) - Complete workflow reference -- [Agents Guide](./agents-guide.md) - Understanding BMad agents - ---- - -_BMad Method fundamentally changes how PMs work, how teams structure work, and how products get built. Understanding these patterns is essential for enterprise success in the age of AI agents._ diff --git a/src/modules/bmm/docs/faq.md b/src/modules/bmm/docs/faq.md index f9d9365d..628d265e 100644 --- a/src/modules/bmm/docs/faq.md +++ b/src/modules/bmm/docs/faq.md @@ -354,8 +354,6 @@ Use them together for best results. **Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality. -See [IDE Setup Guides](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for configuration specifics. - ### Q: Can I customize agents? **A:** Yes! Agents are installed as markdown files with XML-style content (optimized for LLMs, readable by any model). Create customization files in `_bmad/_config/agents/[agent-name].customize.yaml` to override default behaviors while keeping core functionality intact. See agent documentation for customization options. diff --git a/src/modules/bmm/docs/index.md b/src/modules/bmm/docs/index.md index 5e0dd290..6541317d 100644 --- a/src/modules/bmm/docs/index.md +++ b/src/modules/bmm/docs/index.md @@ -22,26 +22,23 @@ Complete guides for the BMad Method Module (BMM) - AI-powered agile development ## 📖 Core Concepts -Understanding how BMM adapts to your needs: +The BMad Method is meant to be adapted and customized to your specific needs. In this realm there is no one size fits all - your needs are unique, and BMad Method is meant to support this (and if it does not, can be further customized or extended with new modules). -- **[Scale Adaptive System](./scale-adaptive-system.md)** - How BMM adapts to project size and complexity - - Three planning tracks (Quick Flow, BMad Method, Enterprise Method) - - Automatic track recommendation - - Documentation requirements per track - - Planning workflow routing +First know there is the full BMad Method Process and then there is a Quick Flow for those quicker smaller efforts. + +- **[Full Adaptive BMad Method](#-workflow-guides)** - Full planning and scope support through extensive development and testing. + - Broken down into 4 phases, all of which are comprised of both required and optional phases + - Phases 1-3 are all about progressive idea development through planning and preparations to build your project. + - Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planing completed + - All 4 phases have optional steps in them, depending on how rigorous you want to go with planning, research ideation, validation, testing and traceability. + - While there is a lot here, know that even this can be distilled down to a simple PRD, Epic and Story list and then jump into the dev cycle. But if that is all you want, you might be better off with the BMad Quick Flow described next - **[BMAD Quick Flow](./bmad-quick-flow.md)** - Fast-track development workflow - 3-step process: spec → dev → optional review - Perfect for bug fixes and small features - Rapid prototyping with production quality - - Hours to implementation, not days - - Barry (Quick Flow Solo Dev) agent owned - -- **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)** - Elite solo developer for rapid development - - Barry is an elite developer who thrives on autonomous execution - - Lives and breathes the BMAD Quick Flow workflow - - Takes projects from concept to deployment with ruthless efficiency - - No handoffs, no delays - just pure focused development + - Implementation in minutes, not days + - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)** ## 🤖 Agents and Collaboration @@ -78,7 +75,6 @@ Essential reference materials: - **[Glossary](./glossary.md)** - Key terminology and concepts - **[FAQ](./faq.md)** - Frequently asked questions across all topics -- **[Enterprise Agentic Development](./enterprise-agentic-development.md)** - Team collaboration strategies ## 🎯 Choose Your Path @@ -86,19 +82,14 @@ Essential reference materials: **Build something new (greenfield)** → Start with [Quick Start Guide](./quick-start.md) -→ Then review [Scale Adaptive System](./scale-adaptive-system.md) to understand tracks **Fix a bug or add small feature** -→ Go to [BMAD Quick Flow](./bmad-quick-flow.md) for rapid development -→ Or use [Quick Flow Solo Dev](./quick-flow-solo-dev.md) directly +→ User the [Quick Flow Solo Dev](./quick-flow-solo-dev.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](./quick-spec-flow.md) process **Work with existing codebase (brownfield)** → Read [Brownfield Development Guide](./brownfield-guide.md) → Pay special attention to documentation requirements for brownfield projects -**Understand planning tracks and methodology** -→ See [Scale Adaptive System](./scale-adaptive-system.md) - ## 📋 Workflow Guides Comprehensive documentation for all BMM workflows organized by phase: @@ -127,35 +118,6 @@ Comprehensive documentation for all BMM workflows organized by phase: - **[Testing & QA Workflows](./test-architecture.md)** - Comprehensive quality assurance (1,420 lines) - Test strategy, automation, quality gates - TEA agent and test healing - - BMad-integrated vs standalone modes - -**Total: 34 workflows documented across all phases** - -### Advanced Workflow References - -For detailed technical documentation on specific complex workflows: - -- **[Document Project Workflow Reference](./workflow-document-project-reference.md)** - Technical deep-dive (445 lines) - - v1.2.0 context-safe architecture - - Scan levels, resumability, write-as-you-go - - Multi-part project detection - - Deep-dive mode for targeted analysis - -- **[Architecture Workflow Reference](./workflow-architecture-reference.md)** - Decision architecture guide (320 lines) - - Starter template intelligence - - Novel pattern design - - Implementation patterns for agent consistency - - Adaptive facilitation approach - -## 🏗️ Module Structure - -Understanding BMM components: - -- **[BMM Module README](../README.md)** - Overview of module structure - - Agent roster and roles - - Workflow organization - - Teams and collaboration - - Best practices ## 🌐 External Resources diff --git a/src/modules/bmm/docs/party-mode.md b/src/modules/bmm/docs/party-mode.md index 287e5022..801decd9 100644 --- a/src/modules/bmm/docs/party-mode.md +++ b/src/modules/bmm/docs/party-mode.md @@ -2,13 +2,11 @@ **Get all your AI agents in one conversation** ---- - ## What is Party Mode? Ever wanted to gather your entire AI team in one room and see what happens? That's party mode. -Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and suddenly you've got **all your AI agents** in one conversation. PM, Architect, DEV, UX Designer, the CIS creative agents - everyone shows up. +Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent or at key workflow junctions when asked), and suddenly you've got **all your AI agents** in one conversation. PM, Architect, DEV, UX Designer and more that you can choose from. **Why it's useful:** @@ -19,8 +17,6 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and su - **Sprint retrospectives** - Party mode powers the retrospective workflow - **Sprint planning** - Multi-agent collaboration for planning sessions -**Future use:** Advanced elicitation workflows will leverage party mode for sophisticated requirement gathering. - --- ## How It Works @@ -46,6 +42,10 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and su # OR from any agent context *party-mode +# Super Hack + +/bmad:core:workflows:party-mode and include also in the party Santa Clause and Einstein + # During party Ask questions, respond to agents, direct the conversation @@ -103,116 +103,6 @@ _(Ideas cross-pollinate and evolve)_ _(Multiple perspectives reveal the right answer)_ ---- - -## When NOT to Use Party Mode - -**Skip party mode for:** - -- Simple implementation questions → Use DEV agent -- Document review → Use Technical Writer -- Workflow status checks → Use any agent + `*workflow-status` -- Single-domain questions → Use specialist agent - -**Use party mode for:** - -- Multi-perspective decisions -- Creative collaboration -- Post-mortems and retrospectives -- Sprint planning sessions -- Complex problem-solving - ---- - -## Agent Customization - -Party mode uses agents from `_bmad/[module]/agents/*.md` - these already include any customizations you applied during install. - -**To customize agents for party mode:** - -1. Create customization file: `_bmad/_config/agents/bmm-pm.customize.yaml` -2. Run `npx bmad-method install` to rebuild agents -3. Customizations now active in party mode - -Example customization: - -```yaml -agent: - persona: - principles: - - 'HIPAA compliance is non-negotiable' - - 'Patient safety over feature velocity' -``` - -See [Agents Guide](./agents-guide.md#agent-customization) for details. - ---- - -## BMM Workflows That Use Party Mode - -**Current:** - -- `epic-retrospective` - Post-epic team retrospective powered by party mode -- Sprint planning discussions (informal party mode usage) - -**Future:** - -- Advanced elicitation workflows will officially integrate party mode -- Multi-agent requirement validation -- Collaborative technical reviews - ---- - -## Available Agents - -Party mode can include **19+ agents** from all installed modules: - -**BMM (12 agents):** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Technical Writer, Game Designer, Game Developer, Game Architect - -**CIS (5 agents):** Brainstorming Coach, Creative Problem Solver, Design Thinking Coach, Innovation Strategist, Storyteller - -**BMB (1 agent):** BMad Builder - -**Core (1 agent):** BMad Master (orchestrator) - -**Custom:** Any agents you've created - ---- - -## Tips - -**Get better results:** - -- Be specific with your topic/question -- Provide context (project type, constraints, goals) -- Direct specific agents when you want their expertise -- Make decisions - party mode informs, you decide -- Time box discussions (15-30 minutes is usually plenty) - -**Examples of good opening questions:** - -- "We need to decide between REST and GraphQL for our mobile API. Project is a B2B SaaS with 50 enterprise clients." -- "Our last sprint failed spectacularly. Let's discuss what went wrong with authentication implementation." -- "Brainstorm: how can we make our game's tutorial feel rewarding instead of tedious?" - ---- - -## Troubleshooting - -**Same agents responding every time?** -Vary your questions or explicitly request other perspectives: "Game Designer, your thoughts?" - -**Discussion going in circles?** -BMad Master will summarize and redirect, or you can make a decision and move on. - -**Too many agents talking?** -Make your topic more specific - BMad Master picks 2-3 agents based on relevance. - -**Agents not using customizations?** -Make sure you ran `npx bmad-method install` after creating customization files. - ---- - ## Related Documentation - [Agents Guide](./agents-guide.md) - Complete agent reference diff --git a/src/modules/bmm/docs/quick-spec-flow.md b/src/modules/bmm/docs/quick-spec-flow.md index 96af1993..fb1d3f73 100644 --- a/src/modules/bmm/docs/quick-spec-flow.md +++ b/src/modules/bmm/docs/quick-spec-flow.md @@ -371,8 +371,6 @@ Checks: **Total time:** 1-3 hours (mostly implementation) ---- - ## Integration with Phase 4 Workflows Quick Spec Flow works seamlessly with all Phase 4 implementation workflows: @@ -395,8 +393,6 @@ Quick Spec Flow works seamlessly with all Phase 4 implementation workflows: - ✅ Uses tech-spec.md as comprehensive context - ✅ Implements following detected conventions ---- - ## Comparison: Quick Spec vs Full BMM | Aspect | Quick Flow Track | BMad Method/Enterprise Tracks | @@ -411,7 +407,6 @@ Quick Spec Flow works seamlessly with all Phase 4 implementation workflows: | **Brownfield** | Auto-analyzes and conforms | Manual documentation required | | **Conventions** | Auto-detects and confirms | Document in PRD/Architecture | ---- ## When to Graduate from Quick Flow to BMad Method @@ -426,8 +421,6 @@ Start with Quick Flow, but switch to BMad Method when: 💡 **Tip:** You can always run `workflow-init` later to transition from Quick Flow to BMad Method! ---- - ## Quick Spec Flow - Key Benefits ### 🚀 **Speed** @@ -465,8 +458,6 @@ Start with Quick Flow, but switch to BMad Method when: - No scope creep - Fast iteration ---- - ## Getting Started ### Prerequisites @@ -478,12 +469,12 @@ Start with Quick Flow, but switch to BMad Method when: ```bash # For a quick bug fix or small change: -# 1. Load PM agent +# 1. Load Quick Dev Solo agent # 2. Say: "I want to [describe your change]" -# 3. PM will ask if you want to run tech-spec +# 3. Agent will ask if you want to run tech-spec # 4. Answer questions about your change # 5. Get tech-spec + story -# 6. Load DEV agent and implement! +# 6. Reload a fresh context with the solo agent and implement! # For a small feature with multiple stories: # Same as above, but get epic + 2-3 stories @@ -492,14 +483,7 @@ Start with Quick Flow, but switch to BMad Method when: ### No workflow-init Required! -Quick Spec Flow is **fully standalone**: - -- Detects if it's a single change or multi-story feature -- Asks for greenfield vs brownfield -- Works without status file tracking -- Perfect for rapid prototyping - ---- +Quick Spec Flow is **fully standalone** ## FAQ diff --git a/src/modules/bmm/docs/quick-start.md b/src/modules/bmm/docs/quick-start.md index d32c1d7f..f5f73785 100644 --- a/src/modules/bmm/docs/quick-start.md +++ b/src/modules/bmm/docs/quick-start.md @@ -43,10 +43,7 @@ The interactive installer will guide you through setup and create a `_bmad/` fol ### Step 1: Initialize Your Workflow -1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for how to activate agents: - - [Claude Code](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/ide-info/claude-code.md) - - [VS Code/Cursor/Windsurf](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) - Check your IDE folder - - Other IDEs also supported +1. **Load the Analyst agent** in your IDE - Generally this is done by typing `/` - if you are unsure, you can just start with /bmad and see all that is available, sorted by agents and workflows. 2. **Wait for the agent's menu** to appear 3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number @@ -113,7 +110,7 @@ The next TRULY REQUIRED step is: When an agent tells you to run a workflow (like `prd`): -1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for your IDE's specific instructions +1. **Start a new chat** with the specified agent 2. **Wait for the menu** to appear 3. **Tell the agent** to run it using any of these formats: - Type the shorthand: `*prd` diff --git a/src/modules/bmm/docs/scale-adaptive-system.md b/src/modules/bmm/docs/scale-adaptive-system.md deleted file mode 100644 index 09b66048..00000000 --- a/src/modules/bmm/docs/scale-adaptive-system.md +++ /dev/null @@ -1,618 +0,0 @@ -# BMad Method Scale Adaptive System - -**Automatically adapts workflows to project complexity - from quick fixes to enterprise systems** - ---- - -## Overview - -The **Scale Adaptive System** intelligently routes projects to the right planning methodology based on complexity, not arbitrary story counts. - -### The Problem - -Traditional methodologies apply the same process to every project: - -- Bug fix requires full design docs -- Enterprise system built with minimal planning -- One-size-fits-none approach - -### The Solution - -BMad Method adapts to three distinct planning tracks: - -- **Quick Flow**: Tech-spec only, implement immediately -- **BMad Method**: PRD + Architecture, structured approach -- **Enterprise Method**: Full planning with security/devops/test - -**Result**: Right planning depth for every project. - ---- - -## Quick Reference - -### Three Tracks at a Glance - -| Track | Planning Depth | Best For | -| --------------------- | --------------------- | ------------------------------------------ | -| **Quick Flow** | Tech-spec only | Simple features, bug fixes, clear scope | -| **BMad Method** | PRD + Arch + UX | Products, platforms, complex features | -| **Enterprise Method** | Method + Test/Sec/Ops | Enterprise needs, compliance, multi-tenant | - -### Decision Tree - -```mermaid -flowchart TD - START{Describe your project} - - START -->|Bug fix, simple feature| Q1{Scope crystal clear?} - START -->|Product, platform, complex| M[BMad Method
PRD + Architecture] - START -->|Enterprise, compliance| E[Enterprise Method
Extended Planning] - - Q1 -->|Yes| QF[Quick Flow
Tech-spec only] - Q1 -->|Uncertain| M - - style QF fill:#bfb,stroke:#333,stroke-width:2px,color:#000 - style M fill:#bbf,stroke:#333,stroke-width:2px,color:#000 - style E fill:#f9f,stroke:#333,stroke-width:2px,color:#000 -``` - -### Quick Keywords - -- **Quick Flow**: fix, bug, simple, add, clear scope -- **BMad Method**: product, platform, dashboard, complex, multiple features -- **Enterprise Method**: enterprise, multi-tenant, compliance, security, audit - ---- - -## How Track Selection Works - -When you run `workflow-init`, it guides you through an educational choice: - -### 1. Description Analysis - -Analyzes your project description for complexity indicators and suggests an appropriate track. - -### 2. Educational Presentation - -Shows all three tracks with: - -- Time investment -- Planning approach -- Benefits and trade-offs -- AI agent support level -- Concrete examples - -### 3. Honest Recommendation - -Provides tailored recommendation based on: - -- Complexity keywords -- Greenfield vs brownfield -- User's description - -### 4. User Choice - -You choose the track that fits your situation. The system guides but never forces. - -**Example:** - -``` -workflow-init: "Based on 'Add user dashboard with analytics', I recommend BMad Method. - This involves multiple features and system design. The PRD + Architecture - gives AI agents complete context for better code generation." - -You: "Actually, this is simpler than it sounds. Quick Flow." - -workflow-init: "Got it! Using Quick Flow with tech-spec." -``` - ---- - -## The Three Tracks - -### Track 1: Quick Flow - -**Definition**: Fast implementation with tech-spec planning. - -**Time**: Hours to 1 day of planning - -**Planning Docs**: - -- Tech-spec.md (implementation-focused) -- Story files (1-15 typically, auto-detects epic structure) - -**Workflow Path**: - -``` -(Brownfield: document-project first if needed) -↓ -Tech-Spec → Implement -``` - -**Use For**: - -- Bug fixes -- Simple features -- Enhancements with clear scope -- Quick additions - -**Story Count**: Typically 1-15 stories (guidance, not rule) - -**Example**: "Fix authentication token expiration bug" - -**AI Agent Support**: Basic - minimal context provided - -**Trade-off**: Less planning = higher rework risk if complexity emerges - ---- - -### Track 2: BMad Method (RECOMMENDED) - -**Definition**: Full product + system design planning. - -**Time**: 1-3 days of planning - -**Planning Docs**: - -- PRD.md (functional and non-functional requirements) -- Architecture.md (system design) -- UX Design (if UI components) -- Epics and Stories (created after architecture) - -**Workflow Path**: - -``` -(Brownfield: document-project first if needed) -↓ -(Optional: Analysis phase - brainstorm, research, product brief) -↓ -PRD → (Optional UX) → Architecture → Create Epics and Stories → Implementation Readiness Check → Implement -``` - -**Complete Workflow Visualization**: - -![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg) - -_Detailed flowchart showing all phases, workflows, agents (color-coded), and decision points for the BMad Method track. Each colored box represents a different agent role._ - -**Use For**: - -**Greenfield**: - -- Products -- Platforms -- Multi-feature initiatives - -**Brownfield**: - -- Complex additions (new UIs + APIs) -- Major refactors -- New modules - -**Story Count**: Typically 10-50+ stories (guidance, not rule) - -**Examples**: - -- "User dashboard with analytics and preferences" -- "Add real-time collaboration to existing document editor" -- "Payment integration system" - -**AI Agent Support**: Exceptional - complete context for coding partnership - -**Why Architecture for Brownfield?** - -Your brownfield documentation might be huge. Architecture workflow distills massive codebase context into a focused solution design specific to YOUR project. This keeps AI agents focused without getting lost in existing code. - -**Benefits**: - -- Complete AI agent context -- Prevents architectural drift -- Fewer surprises during implementation -- Better code quality -- Faster overall delivery (planning pays off) - ---- - -### Track 3: Enterprise Method - -**Definition**: Extended planning with security, devops, and test strategy. - -**Time**: 3-7 days of planning - -**Planning Docs**: - -- All BMad Method docs PLUS: -- Security Architecture -- DevOps Strategy -- Test Strategy -- Compliance documentation - -**Workflow Path**: - -``` -(Brownfield: document-project nearly mandatory) -↓ -Analysis (recommended/required) → PRD → UX → Architecture -↓ -Create Epics and Stories -↓ -Security Architecture → DevOps Strategy → Test Strategy -↓ -Implementation Readiness Check → Implement -``` - -**Use For**: - -- Enterprise requirements -- Multi-tenant systems -- Compliance needs (HIPAA, SOC2, etc.) -- Mission-critical systems -- Security-sensitive applications - -**Story Count**: Typically 30+ stories (but defined by enterprise needs, not count) - -**Examples**: - -- "Multi-tenant SaaS platform" -- "HIPAA-compliant patient portal" -- "Add SOC2 audit logging to enterprise app" - -**AI Agent Support**: Elite - comprehensive enterprise planning - -**Critical for Enterprise**: - -- Security architecture and threat modeling -- DevOps pipeline planning -- Comprehensive test strategy -- Risk assessment -- Compliance mapping - ---- - -## Planning Documents by Track - -### Quick Flow Documents - -**Created**: Upfront in Planning Phase - -**Tech-Spec**: - -- Problem statement and solution -- Source tree changes -- Technical implementation details -- Detected stack and conventions (brownfield) -- UX/UI considerations (if user-facing) -- Testing strategy - -**Serves as**: Complete planning document (replaces PRD + Architecture) - ---- - -### BMad Method Documents - -**Created**: Upfront in Planning and Solutioning Phases - -**PRD (Product Requirements Document)**: - -- Product vision and goals -- Functional requirements (FRs) -- Non-functional requirements (NFRs) -- Success criteria -- User experience considerations -- Business context - -**Note**: Epics and stories are created AFTER architecture in the create-epics-and-stories workflow - -**Architecture Document**: - -- System components and responsibilities -- Data models and schemas -- Integration patterns -- Security architecture -- Performance considerations -- Deployment architecture - -**For Brownfield**: Acts as focused "solution design" that distills existing codebase into integration plan - ---- - -### Enterprise Method Documents - -**Created**: Extended planning across multiple phases - -Includes all BMad Method documents PLUS: - -**Security Architecture**: - -- Threat modeling -- Authentication/authorization design -- Data protection strategy -- Audit requirements - -**DevOps Strategy**: - -- CI/CD pipeline design -- Infrastructure architecture -- Monitoring and alerting -- Disaster recovery - -**Test Strategy**: - -- Test approach and coverage -- Automation strategy -- Quality gates -- Performance testing - ---- - -## Workflow Comparison - -| Track | Analysis | Planning | Architecture | Security/Ops | Typical Stories | -| --------------- | ----------- | --------- | ------------ | ------------ | --------------- | -| **Quick Flow** | Optional | Tech-spec | None | None | 1-15 | -| **BMad Method** | Recommended | PRD + UX | Required | None | 10-50+ | -| **Enterprise** | Required | PRD + UX | Required | Required | 30+ | - -**Note**: Story counts are GUIDANCE based on typical usage, NOT definitions of tracks. - ---- - -## Brownfield Projects - -### Critical First Step - -For ALL brownfield projects: Run `document-project` BEFORE planning workflows. - -### Why document-project is Critical - -**Quick Flow** uses it for: - -- Auto-detecting existing patterns -- Understanding codebase structure -- Confirming conventions - -**BMad Method** uses it for: - -- Architecture inputs (existing structure) -- Integration design -- Pattern consistency - -**Enterprise Method** uses it for: - -- Security analysis -- Integration architecture -- Risk assessment - -### Brownfield Workflow Pattern - -```mermaid -flowchart TD - START([Brownfield Project]) - CHECK{Has docs/
index.md?} - - START --> CHECK - CHECK -->|No| DOC[document-project workflow
10-30 min] - CHECK -->|Yes| TRACK[Choose Track] - - DOC --> TRACK - TRACK -->|Quick| QF[Tech-Spec] - TRACK -->|Method| M[PRD + Arch] - TRACK -->|Enterprise| E[PRD + Arch + Sec/Ops] - - style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000 - style TRACK fill:#bfb,stroke:#333,stroke-width:2px,color:#000 -``` - ---- - -## Common Scenarios - -### Scenario 1: Bug Fix (Quick Flow) - -**Input**: "Fix email validation bug in login form" - -**Detection**: Keywords "fix", "bug" - -**Track**: Quick Flow - -**Workflow**: - -1. (Optional) Brief analysis -2. Tech-spec with single story -3. Implement immediately - -**Time**: 2-4 hours total - ---- - -### Scenario 2: Small Feature (Quick Flow) - -**Input**: "Add OAuth social login (Google, GitHub, Facebook)" - -**Detection**: Keywords "add", "feature", clear scope - -**Track**: Quick Flow - -**Workflow**: - -1. (Optional) Research OAuth providers -2. Tech-spec with 3 stories -3. Implement story-by-story - -**Time**: 1-3 days - ---- - -### Scenario 3: Customer Portal (BMad Method) - -**Input**: "Build customer portal with dashboard, tickets, billing" - -**Detection**: Keywords "portal", "dashboard", multiple features - -**Track**: BMad Method - -**Workflow**: - -1. (Recommended) Product Brief -2. PRD (FRs/NFRs) -3. (If UI) UX Design -4. Architecture (system design) -5. Create Epics and Stories -6. Implementation Readiness Check -7. Implement with sprint planning - -**Time**: 1-2 weeks - ---- - -### Scenario 4: E-commerce Platform (BMad Method) - -**Input**: "Build e-commerce platform with products, cart, checkout, admin, analytics" - -**Detection**: Keywords "platform", multiple subsystems - -**Track**: BMad Method - -**Workflow**: - -1. Research + Product Brief -2. Comprehensive PRD (FRs/NFRs) -3. UX Design (recommended) -4. System Architecture (required) -5. Create Epics and Stories -6. Implementation Readiness Check -7. Implement with phased approach - -**Time**: 3-6 weeks - ---- - -### Scenario 5: Brownfield Addition (BMad Method) - -**Input**: "Add search functionality to existing product catalog" - -**Detection**: Brownfield + moderate complexity - -**Track**: BMad Method (not Quick Flow) - -**Critical First Step**: - -1. **Run document-project** to analyze existing codebase - -**Then Workflow**: - -2. PRD for search feature (FRs/NFRs) -3. Architecture (integration design - highly recommended) -4. Create Epics and Stories -5. Implementation Readiness Check -6. Implement following existing patterns - -**Time**: 1-2 weeks - -**Why Method not Quick Flow?**: Integration with existing catalog system benefits from architecture planning to ensure consistency. - ---- - -### Scenario 6: Multi-tenant Platform (Enterprise Method) - -**Input**: "Add multi-tenancy to existing single-tenant SaaS platform" - -**Detection**: Keywords "multi-tenant", enterprise scale - -**Track**: Enterprise Method - -**Workflow**: - -1. Document-project (mandatory) -2. Research (compliance, security) -3. PRD (multi-tenancy requirements - FRs/NFRs) -4. Architecture (tenant isolation design) -5. Create Epics and Stories -6. Security Architecture (data isolation, auth) -7. DevOps Strategy (tenant provisioning, monitoring) -8. Test Strategy (tenant isolation testing) -9. Implementation Readiness Check -10. Phased implementation - -**Time**: 3-6 months - ---- - -## Best Practices - -### 1. Document-Project First for Brownfield - -Always run `document-project` before starting brownfield planning. AI agents need existing codebase context. - -### 2. Trust the Recommendation - -If `workflow-init` suggests BMad Method, there's probably complexity you haven't considered. Review carefully before overriding. - -### 3. Start Smaller if Uncertain - -Uncertain between Quick Flow and Method? Start with Quick Flow. You can create PRD later if needed. - -### 4. Don't Skip Implementation Readiness Check - -For BMad Method and Enterprise, implementation readiness checks prevent costly mistakes. Invest the time. - -### 5. Architecture is Optional but Recommended for Brownfield - -Brownfield BMad Method makes architecture optional, but it's highly recommended. It distills complex codebase into focused solution design. - -### 6. Discovery Phase Based on Need - -Brainstorming and research are offered regardless of track. Use them when you need to think through the problem space. - -### 7. Product Brief for Greenfield Method - -Product Brief is only offered for greenfield BMad Method and Enterprise. It's optional but helps with strategic thinking. - ---- - -## Key Differences from Legacy System - -### Old System (Levels 0-4) - -- Arbitrary story count thresholds -- Level 2 vs Level 3 based on story count -- Confusing overlap zones (5-10 stories, 12-40 stories) -- Tech-spec and PRD shown as conflicting options - -### New System (3 Tracks) - -- Methodology-based distinction (not story counts) -- Story counts as guidance, not definitions -- Clear track purposes: - - Quick Flow = Implementation-focused - - BMad Method = Product + system design - - Enterprise = Extended with security/ops -- Mutually exclusive paths chosen upfront -- Educational decision-making - ---- - -## Migration from Old System - -If you have existing projects using the old level system: - -- **Level 0-1** → Quick Flow -- **Level 2-3** → BMad Method -- **Level 4** → Enterprise Method - -Run `workflow-init` on existing projects to migrate to new tracking system. It detects existing planning artifacts and creates appropriate workflow tracking. - ---- - -## Related Documentation - -- **[Quick Start Guide](./quick-start.md)** - Get started with BMM -- **[Quick Spec Flow](./quick-spec-flow.md)** - Details on Quick Flow track -- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows -- **[Glossary](./glossary.md)** - Complete terminology -- **[FAQ](./faq.md)** - Common questions -- **[Workflows Guide](./index.md#-workflow-guides)** - Complete workflow reference - ---- - -_Scale Adaptive System - Right planning depth for every project._ diff --git a/src/modules/bmm/docs/test-architecture.md b/src/modules/bmm/docs/test-architecture.md index eb44a0c8..e64282d3 100644 --- a/src/modules/bmm/docs/test-architecture.md +++ b/src/modules/bmm/docs/test-architecture.md @@ -1,7 +1,3 @@ ---- -last-redoc-date: 2025-11-05 ---- - # Test Architect (TEA) Agent Guide ## Overview @@ -259,17 +255,17 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks* - 🔄 Phase 4: `*test-design` - Focus on regression hotspots and brownfield risks - 🔄 Phase 4: Story Review - May include `*nfr-assess` if not done earlier -| Workflow Stage | Test Architect | Dev / Team | Outputs | -| ---------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| **Documentation**: Prerequisite ➕ | - | Analyst `*document-project` (if undocumented) | Comprehensive project documentation | -| **Phase 1**: Discovery | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` | -| **Phase 2**: Planning | Run ➕ `*trace` (baseline coverage) | PM `*prd` (creates PRD with FRs/NFRs) | PRD with FRs/NFRs, ➕ coverage baseline | -| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline | -| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories | -| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (regression hotspots) | Review epic scope and brownfield risks | `test-design-epic-N.md` with brownfield risk assessment and mitigation | -| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation | -| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report | -| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, share release notes | Quality audit, Gate YAML + release summary | +| Workflow Stage | Test Architect | Dev / Team | Outputs | +| --------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| **Documentation**: Prerequisite ➕ | - | Analyst `*document-project` (if undocumented) | Comprehensive project documentation | +| **Phase 1**: Discovery | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` | +| **Phase 2**: Planning | Run ➕ `*trace` (baseline coverage) | PM `*prd` (creates PRD with FRs/NFRs) | PRD with FRs/NFRs, ➕ coverage baseline | +| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline | +| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories | +| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (regression hotspots) | Review epic scope and brownfield risks | `test-design-epic-N.md` with brownfield risk assessment and mitigation | +| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation | +| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report | +| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, share release notes | Quality audit, Gate YAML + release summary |
Execution Notes @@ -309,15 +305,15 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks* - 🔄 Phase 4: `*test-design` - Enterprise focus (compliance, security architecture alignment) - 📦 Release Gate - Archive artifacts and compliance evidence for audits -| Workflow Stage | Test Architect | Dev / Team | Outputs | -| -------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| **Phase 1**: Discovery | - | Analyst ➕ `*research`, `*product-brief` | Domain research, compliance analysis, product brief | -| **Phase 2**: Planning | Run ➕ `*nfr-assess` | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design` | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation | -| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline | -| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint plan with all epics | +| Workflow Stage | Test Architect | Dev / Team | Outputs | +| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| **Phase 1**: Discovery | - | Analyst ➕ `*research`, `*product-brief` | Domain research, compliance analysis, product brief | +| **Phase 2**: Planning | Run ➕ `*nfr-assess` | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design` | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation | +| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline | +| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint plan with all epics | | **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (compliance focus) | Review epic scope and compliance requirements | `test-design-epic-N.md` with security/performance/compliance focus | -| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices | -| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | Quality audit, updated assessments, gate YAML, 📦 audit trail | +| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices | +| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | Quality audit, updated assessments, gate YAML, 📦 audit trail |
Execution Notes diff --git a/src/modules/bmm/docs/troubleshooting.md b/src/modules/bmm/docs/troubleshooting.md index 35ba5ce8..99ce15a8 100644 --- a/src/modules/bmm/docs/troubleshooting.md +++ b/src/modules/bmm/docs/troubleshooting.md @@ -1,661 +1,3 @@ # BMM Troubleshooting Guide -Common issues and solutions for the BMad Method Module. - ---- - -## Quick Diagnosis - -**Use this flowchart to find your issue:** - -```mermaid -flowchart TD - START{What's the problem?} - - START -->|Can't get started| SETUP[Setup & Installation Issues] - START -->|Wrong level detected| LEVEL[Level Detection Problems] - START -->|Workflow not working| WORKFLOW[Workflow Issues] - START -->|Agent lacks context| CONTEXT[Context & Documentation Issues] - START -->|Implementation problems| IMPL[Implementation Issues] - START -->|Files/paths wrong| FILES[File & Path Issues] - - style START fill:#ffb,stroke:#333,stroke-width:2px - style SETUP fill:#bfb,stroke:#333,stroke-width:2px - style LEVEL fill:#bbf,stroke:#333,stroke-width:2px - style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px - style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px -``` - ---- - -## Table of Contents - -- [Setup and Installation Issues](#setup-and-installation-issues) -- [Level Detection Problems](#level-detection-problems) -- [Workflow Issues](#workflow-issues) -- [Context and Documentation Issues](#context-and-documentation-issues) -- [Implementation Issues](#implementation-issues) -- [File and Path Issues](#file-and-path-issues) -- [Agent Behavior Issues](#agent-behavior-issues) -- [Integration Issues (Brownfield)](#integration-issues-brownfield) - ---- - -## Setup and Installation Issues - -### Problem: BMM not found after installation - -**Symptoms:** - -- `bmad` command not recognized -- Agent files not accessible -- Workflows don't load - -**Solution:** - -```bash -# Check if BMM is installed -ls bmad/ - -# If not present, run installer -npx bmad-method@alpha install - -# For fresh install -npx bmad-method@alpha install --skip-version-prompt -``` - -### Problem: Agents don't have menu - -**Symptoms:** - -- Load agent file but no menu appears -- Agent doesn't respond to commands - -**Solution:** - -1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md` -2. Wait a few seconds for agent to initialize -3. Try asking "show menu" or "help" -4. Check IDE supports Markdown rendering with context -5. For Claude Code: Ensure agent file is open in chat context - -### Problem: Workflows not found - -**Symptoms:** - -- Agent says workflow doesn't exist -- Menu shows workflow but won't run - -**Solution:** - -1. Check workflow exists: `ls bmad/bmm/workflows/` -2. Verify agent has access to workflow (check agent's workflow list) -3. Try using menu number instead of workflow name -4. Restart chat with agent in fresh session - ---- - -## Level Detection Problems - -### Problem: workflow-init suggests wrong level - -**Symptoms:** - -- Detects Level 3 but you only need Level 1 -- Suggests Level 1 but project is actually Level 2 -- Can't figure out appropriate level - -**Solution:** - -1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level -2. **Be specific in description** - Use level keywords when describing: - - "fix bug" → Level 0 - - "add small feature" → Level 1 - - "build dashboard" → Level 2 -3. **Manual override** - You can always switch levels later if needed - -**Example:** - -``` -workflow-init: "Level 3 project?" -You: "No, this is just adding OAuth login - Level 1" -workflow-init: "Got it, creating Level 1 workflow" -``` - -### Problem: Project level unclear - -**Symptoms:** - -- Between Level 1 and Level 2 -- Not sure if architecture needed -- Story count uncertain - -**Solution:** -**When in doubt, start smaller:** - -- Choose Level 1 instead of Level 2 -- You can always run `create-prd` later if needed -- Level 1 is faster, less overhead -- Easy to upgrade, hard to downgrade - -**Decision criteria:** - -- Single epic with related stories? → Level 1 -- Multiple independent epics? → Level 2 -- Need product-level planning? → Level 2 -- Just need technical plan? → Level 1 - -### Problem: Old planning docs influencing level detection - -**Symptoms:** - -- Old Level 3 PRD in folder -- Working on new Level 0 bug fix -- workflow-init suggests Level 3 - -**Solution:** -workflow-init asks: "Is this work in progress or previous effort?" - -- Answer: "Previous effort" -- Then describe your NEW work clearly -- System will detect level based on NEW work, not old artifacts - ---- - -## Workflow Issues - -### Problem: Workflow fails or hangs - -**Symptoms:** - -- Workflow starts but doesn't complete -- Agent stops responding mid-workflow -- Progress stalls - -**Solution:** - -1. **Check context limits** - Start fresh chat for complex workflows -2. **Verify prerequisites**: - - Phase 2 needs Phase 1 complete (if used) - - Phase 3 needs Phase 2 complete - - Phase 4 needs Phase 3 complete (if Level 3-4) -3. **Restart workflow** - Load agent in new chat and restart -4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid - -### Problem: Agent says "workflow not found" - -**Symptoms:** - -- Request workflow by name -- Agent doesn't recognize it -- Menu doesn't show workflow - -**Solution:** - -1. Check spelling/format - Use exact workflow name or menu shortcut (`*prd` not `*PRD`) -2. Verify agent has workflow: - - PM agent: prd, tech-spec - - Architect agent: create-architecture, validate-architecture - - SM agent: sprint-planning, create-story -3. Try menu number instead of name -4. Check you're using correct agent for workflow - -### Problem: Sprint-planning workflow fails - -**Symptoms:** - -- Can't create sprint-status.yaml -- Epics not extracted from files -- Status file empty or incorrect - -**Solution:** - -1. **Verify epic files exist**: - - Level 1: tech-spec with epic - - Level 2-4: epics.md or sharded epic files -2. **Check file format**: - - Epic files should be valid Markdown - - Epic headers should be clear (## Epic Name) -3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first -4. **Check file paths** - Epic files should be in correct output folder - ---- - -## Context and Documentation Issues - -### Problem: AI agents lack codebase understanding (Brownfield) - -**Symptoms:** - -- Suggestions don't align with existing patterns -- Ignores available components -- Proposes approaches that conflict with architecture -- Doesn't reference existing code - -**Solution:** - -1. **Run document-project** - Critical for brownfield projects - ``` - Load Analyst agent → run document-project - Choose scan level: Deep (recommended for PRD prep) - ``` -2. **Verify docs/index.md exists** - This is master entry point for AI agents -3. **Check documentation completeness**: - - Review generated docs/index.md - - Ensure key systems are documented -4. **Run deep-dive on specific areas** if needed - -### Problem: Have documentation but agents can't find it - -**Symptoms:** - -- README.md, ARCHITECTURE.md exist -- AI agents still ask questions answered in docs -- No docs/index.md file - -**Solution:** -**Option 1: Quick fix (2-5min)** -Run `index-docs` task: - -- Located at `bmad/core/tasks/index-docs.xml` -- Scans existing docs and generates index.md -- Lightweight, just creates navigation - -**Option 2: Comprehensive (10-30min)** -Run document-project workflow: - -- Discovers existing docs in Step 2 -- Generates NEW AI-friendly documentation from codebase -- Creates index.md linking to BOTH existing and new docs - -**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently. - -### Problem: document-project takes too long - -**Symptoms:** - -- Exhaustive scan running for hours -- Impatient to start planning - -**Solution:** -**Choose appropriate scan level:** - -- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview -- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects** -- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding - -For most brownfield projects, **Deep scan is sufficient**. - ---- - -## Implementation Issues - -### Problem: Existing tests breaking (Brownfield) - -**Symptoms:** - -- Regression test failures -- Previously working functionality broken -- Integration tests failing - -**Solution:** - -1. **Review changes against existing patterns**: - - Check if new code follows existing conventions - - Verify API contracts unchanged (unless intentionally versioned) -2. **Run test-review workflow** (TEA agent): - - Analyzes test coverage - - Identifies regression risks - - Suggests fixes -3. **Add regression testing to DoD**: - - All existing tests must pass - - Add integration tests for new code -4. **Consider feature flags** for gradual rollout - -### Problem: Story takes much longer than estimated - -**Symptoms:** - -- Story estimated 4 hours, took 12 hours -- Acceptance criteria harder than expected -- Hidden complexity discovered - -**Solution:** -**This is normal!** Estimates are estimates. To handle: - -1. **Continue until DoD met** - Don't compromise quality -2. **Document learnings in retrospective**: - - What caused the overrun? - - What should we watch for next time? -3. **Consider splitting story** if it's truly two stories -4. **Adjust future estimates** based on this data - -**Don't stress about estimate accuracy** - use them for learning, not judgment. - -### Problem: Integration points unclear - -**Symptoms:** - -- Not sure how to connect new code to existing -- Unsure which files to modify -- Multiple possible integration approaches - -**Solution:** - -1. **For brownfield**: - - Ensure document-project captured existing architecture - - Review architecture docs before implementing -2. **Check story file** - Should document integration points -3. **In tech-spec/architecture** - Explicitly document: - - Which existing modules to modify - - What APIs/services to integrate with - - Data flow between new and existing code -4. **Run integration-planning workflow** (Level 3-4): - - Architect agent creates integration strategy - -### Problem: Inconsistent patterns being introduced - -**Symptoms:** - -- New code style doesn't match existing -- Different architectural approach -- Not following team conventions - -**Solution:** - -1. **Check convention detection** (Quick Spec Flow): - - Should detect existing patterns - - Asks for confirmation before proceeding -2. **Review documentation** - Ensure document-project captured patterns -3. **Use comprehensive story files** - Include pattern guidance in story -4. **Add to code-review checklist**: - - Pattern adherence - - Convention consistency - - Style matching -5. **Run retrospective** to identify pattern deviations early - ---- - -## File and Path Issues - -### Problem: Output files in wrong location - -**Symptoms:** - -- PRD created in wrong folder -- Story files not where expected -- Documentation scattered - -**Solution:** -Check `bmad/bmm/config.yaml` for configured paths: - -```yaml -output_folder: '{project-root}/docs' -dev_story_location: '{project-root}/docs/stories' -``` - -Default locations: - -- Planning docs (PRD, epics, architecture): `{output_folder}/` -- Stories: `{dev_story_location}/` -- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml` - -To change locations, edit config.yaml then re-run workflows. - -### Problem: Can't find status file - -**Symptoms:** - -- workflow-status says no status file -- Can't track progress -- Lost place in workflow - -**Solution:** - -1. **Check default location**: `docs/bmm-workflow-status.md` -2. **If missing, reinitialize**: - ``` - Load Analyst agent → run workflow-init - ``` -3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD -4. **Search for it**: - ```bash - find . -name "bmm-workflow-status.md" - find . -name "sprint-status.yaml" - ``` - -### Problem: Sprint-status.yaml not updating - -**Symptoms:** - -- Workflows complete but status unchanged -- Stories stuck in old status -- Epic status not progressing - -**Solution:** - -1. **Manual update required** - Most status changes are manual: - ```yaml - stories: - - id: epic-1-story-1 - status: done # Change this manually - ``` -2. **Some workflows auto-update**: - - sprint-planning creates file - - create-story changes story to "ready-for-dev" - - dev-story may auto-update (check workflow) -3. **Re-run sprint-planning** to resync if needed - ---- - -## Agent Behavior Issues - -### Problem: Agent provides vague or generic responses - -**Symptoms:** - -- "Use appropriate framework" -- "Follow best practices" -- Generic advice without specifics - -**Solution:** - -1. **Provide more context** - Be specific in your description: - - "Add OAuth using passport.js to Express server" - - Not: "Add authentication" -2. **For brownfield**: - - Ensure document-project was run - - Agent needs codebase context for specific advice -3. **Reference existing docs**: - - "Based on the existing auth system in UserService..." -4. **Start fresh chat** - Context overload can cause generic responses - -### Problem: Agent hallucinating or making up information - -**Symptoms:** - -- References files that don't exist -- Suggests APIs that aren't in your stack -- Creates imaginary requirements - -**Solution:** - -1. **Use fresh chat** - Context overflow main cause of hallucinations -2. **Provide concrete constraints**: - - "We use Express 4.18.2, not Next.js" - - "Our database is PostgreSQL, not MongoDB" -3. **For brownfield**: - - Document-project provides factual grounding - - Agent sees actual code, not assumptions -4. **Correct immediately**: - - "No, we don't have UserService, we have AuthenticationModule" - -### Problem: Agent won't follow instructions - -**Symptoms:** - -- Ignores specific requests -- Does something different than asked -- Doesn't respect constraints - -**Solution:** - -1. **Be more explicit** - Agents respond to clear, specific instructions: - - "Use EXACTLY these three steps..." - - "Do NOT include database migrations in this story" -2. **Check agent capabilities** - Agent might not have access to requested workflow -3. **Try different phrasing** - Rephrase request to be more direct -4. **Use menu system** - Numbers are clearer than text commands - ---- - -## Integration Issues (Brownfield) - -### Problem: New code conflicts with existing architecture - -**Symptoms:** - -- Integration approach doesn't fit existing structure -- Would require major refactoring -- Conflicts with established patterns - -**Solution:** - -1. **Check if document-project was run** - Agents need architecture context -2. **Review existing architecture docs**: - - Read docs/architecture.md (from document-project) - - Understand current system design -3. **For Level 3-4**: - - Run validate-architecture workflow before planning - - Use integration-planning workflow -4. **Explicitly document integration strategy** in architecture: - - How new components fit existing structure - - What modifications needed to existing code - - Migration path if changing patterns - -### Problem: Breaking changes to existing APIs - -**Symptoms:** - -- Changing API breaks consumers -- Downstream services affected -- Need backward compatibility - -**Solution:** - -1. **Identify all API consumers** (document-project should show this) -2. **Plan versioning strategy**: - - API v1 (existing) + v2 (new) - - Deprecation timeline -3. **Use feature flags** for gradual rollout -4. **Document migration guide** for API consumers -5. **Add to testing strategy**: - - Existing consumers still work (v1) - - New functionality works (v2) - -### Problem: Data migration required - -**Symptoms:** - -- Schema changes needed -- Existing data needs transformation -- Risk of data loss - -**Solution:** - -1. **Create explicit migration strategy** in architecture: - - Forward migration (old → new schema) - - Rollback plan (new → old schema) - - Data validation approach -2. **Test migrations thoroughly**: - - On copy of production data - - Measure performance impact -3. **Plan rollout**: - - Staging environment first - - Gradual production rollout - - Monitoring for issues -4. **Document in tech-spec/architecture**: - - Migration scripts - - Rollback procedures - - Expected downtime - ---- - -## Still Stuck? - -### Getting More Help - -If your issue isn't covered here: - -1. **Check other documentation**: - - [FAQ](./faq.md) - Common questions - - [Glossary](./glossary.md) - Terminology - - [Quick Start](./quick-start.md) - Basic usage - - [Brownfield Guide](./brownfield-guide.md) - Existing codebases - - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels - -2. **Community support**: - - [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues - - Active community, fast responses - - Share your specific situation - -3. **Report bugs**: - - [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) - - Include version, steps to reproduce, expected vs actual behavior - -4. **Video tutorials**: - - [YouTube Channel](https://www.youtube.com/@BMadCode) - - Visual walkthroughs of common workflows - ---- - -## Common Error Messages - -### "No workflow status file found" - -**Cause:** Haven't run workflow-init yet -**Fix:** Load Analyst agent → run workflow-init - -### "Epic file not found" - -**Cause:** PRD/epics not created, or wrong path -**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths - -### "Story not in sprint-status.yaml" - -**Cause:** Sprint-planning not run, or story file not created -**Fix:** Run sprint-planning workflow, verify story files exist - -### "Documentation insufficient for brownfield" - -**Cause:** No docs/index.md or document-project not run -**Fix:** Run document-project workflow with Deep scan - -### "Level detection failed" - -**Cause:** Ambiguous project description -**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.) - -### "Context generation failed" - -**Cause:** Missing prerequisites (story file or docs) -**Fix:** Verify story file exists, docs present - ---- - -## Prevention Tips - -**Avoid common issues before they happen:** - -1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later -2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow -3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present -4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow -5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade -6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift -7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic -8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4) - ---- - -**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide! +Common issues and solutions for the BMad Method Module will be listed here as needed. \ No newline at end of file diff --git a/src/modules/bmm/docs/workflow-architecture-reference.md b/src/modules/bmm/docs/workflow-architecture-reference.md deleted file mode 100644 index 0acd0d30..00000000 --- a/src/modules/bmm/docs/workflow-architecture-reference.md +++ /dev/null @@ -1,366 +0,0 @@ -# Decision Architecture Workflow - Technical Reference - -**Module:** BMM (BMAD Method Module) -**Type:** Solutioning Workflow - ---- - -## Overview - -The Decision Architecture workflow is a complete reimagining of how architectural decisions are made in the BMAD Method. Instead of template-driven documentation, this workflow facilitates an intelligent conversation that produces a **decision-focused architecture document** optimized for preventing AI agent conflicts during implementation. - ---- - -## Core Philosophy - -**The Problem**: When multiple AI agents implement different parts of a system, they make conflicting technical decisions leading to incompatible implementations. - -**The Solution**: A "consistency contract" that documents all critical technical decisions upfront, ensuring every agent follows the same patterns and uses the same technologies. - ---- - -## Key Features - -### 1. Starter Template Intelligence ⭐ NEW - -- Discovers relevant starter templates (create-next-app, create-t3-app, etc.) -- Considers UX requirements when selecting templates (animations, accessibility, etc.) -- Searches for current CLI options and defaults -- Documents decisions made BY the starter template -- Makes remaining architectural decisions around the starter foundation -- First implementation story becomes "initialize with starter command" - -### 2. Adaptive Facilitation - -- Adjusts conversation style based on user skill level (beginner/intermediate/expert) -- Experts get rapid, technical discussions -- Beginners receive education and protection from complexity -- Everyone produces the same high-quality output - -### 3. Dynamic Version Verification - -- NEVER trusts hardcoded version numbers -- Uses WebSearch to find current stable versions -- Verifies versions during the conversation -- Documents only verified, current versions - -### 4. Intelligent Discovery - -- No rigid project type templates -- Analyzes PRD to identify which decisions matter for THIS project -- Uses knowledge base of decisions and patterns -- Scales to infinite project types - -### 5. Collaborative Decision Making - -- Facilitates discussion for each critical decision -- Presents options with trade-offs -- Integrates advanced elicitation for innovative approaches -- Ensures decisions are coherent and compatible - -### 6. Consistent Output - -- Structured decision collection during conversation -- Strict document generation from collected decisions -- Validated against hard requirements -- Optimized for AI agent consumption - ---- - -## Workflow Structure - -``` -Step 0: Validate workflow and extract project configuration -Step 0.5: Validate workflow sequencing -Step 1: Load PRD (with FRs/NFRs) and understand project context -Step 2: Discover and evaluate starter templates ⭐ NEW -Step 3: Adapt facilitation style and identify remaining decisions -Step 4: Facilitate collaborative decision making (with version verification) -Step 5: Address cross-cutting concerns -Step 6: Define project structure and boundaries -Step 7: Design novel architectural patterns (when needed) ⭐ NEW -Step 8: Define implementation patterns to prevent agent conflicts -Step 9: Validate architectural coherence -Step 10: Generate decision architecture document (with initialization commands) -Step 11: Validate document completeness -Step 12: Final review and update workflow status -``` - ---- - -## Files in This Workflow - -- **workflow.yaml** - Configuration and metadata -- **instructions.md** - The adaptive facilitation flow -- **decision-catalog.yaml** - Knowledge base of all architectural decisions -- **architecture-patterns.yaml** - Common patterns identified from requirements -- **pattern-categories.csv** - Pattern principles that teach LLM what needs defining -- **checklist.md** - Validation requirements for the output document -- **architecture-template.md** - Strict format for the final document - ---- - -## How It's Different from Old architecture - -| Aspect | Old Workflow | New Workflow | -| -------------------- | -------------------------------------------- | ----------------------------------------------- | -| **Approach** | Template-driven | Conversation-driven | -| **Project Types** | 11 rigid types with 22+ files | Infinite flexibility with intelligent discovery | -| **User Interaction** | Output sections with "Continue?" | Collaborative decision facilitation | -| **Skill Adaptation** | One-size-fits-all | Adapts to beginner/intermediate/expert | -| **Decision Making** | Late in process (Step 5) | Upfront and central focus | -| **Output** | Multiple documents including faux tech-specs | Single decision-focused architecture | -| **Time** | Confusing and slow | 30-90 minutes depending on skill level | -| **Elicitation** | Never used | Integrated at decision points | - ---- - -## Expected Inputs - -- **PRD** (Product Requirements Document) with: - - Functional Requirements - - Non-Functional Requirements - - Performance and compliance needs - -- **UX Spec** (Optional but valuable) with: - - Interface designs and interaction patterns - - Accessibility requirements (WCAG levels) - - Animation and transition needs - - Platform-specific UI requirements - - Performance expectations for interactions - ---- - -## Output Document - -A single `architecture.md` file containing: - -- Executive summary (2-3 sentences) -- Project initialization command (if using starter template) -- Decision summary table with verified versions and epic mapping -- Complete project structure -- Integration specifications -- Consistency rules for AI agents - ---- - -## How Novel Pattern Design Works - -Step 7 handles unique or complex patterns that need to be INVENTED: - -### 1. Detection - -The workflow analyzes the PRD for concepts that don't have standard solutions: - -- Novel interaction patterns (e.g., "swipe to match" when Tinder doesn't exist) -- Complex multi-epic workflows (e.g., "viral invitation system") -- Unique data relationships (e.g., "social graph" before Facebook) -- New paradigms (e.g., "ephemeral messages" before Snapchat) - -### 2. Design Collaboration - -Instead of just picking technologies, the workflow helps DESIGN the solution: - -- Identifies the core problem to solve -- Explores different approaches with the user -- Documents how components interact -- Creates sequence diagrams for complex flows -- Uses elicitation to find innovative solutions - -### 3. Documentation - -Novel patterns become part of the architecture with: - -- Pattern name and purpose -- Component interactions -- Data flow diagrams -- Which epics/stories are affected -- Implementation guidance for agents - -### 4. Example - -``` -PRD: "Users can create 'circles' of friends with overlapping membership" -↓ -Workflow detects: This is a novel social structure pattern -↓ -Designs with user: Circle membership model, permission cascading, UI patterns -↓ -Documents: "Circle Pattern" with component design and data flow -↓ -All agents understand how to implement circle-related features consistently -``` - ---- - -## How Implementation Patterns Work - -Step 8 prevents agent conflicts by defining patterns for consistency: - -### 1. The Core Principle - -> "Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture" - -The LLM asks: "What could an agent encounter where they'd have to guess?" - -### 2. Pattern Categories (principles, not prescriptions) - -- **Naming**: How things are named (APIs, database fields, files) -- **Structure**: How things are organized (folders, modules, layers) -- **Format**: How data is formatted (JSON structures, responses) -- **Communication**: How components talk (events, messages, protocols) -- **Lifecycle**: How states change (workflows, transitions) -- **Location**: Where things go (URLs, paths, storage) -- **Consistency**: Cross-cutting concerns (dates, errors, logs) - -### 3. LLM Intelligence - -- Uses the principle to identify patterns beyond the 7 categories -- Figures out what specific patterns matter for chosen tech -- Only asks about patterns that could cause conflicts -- Skips obvious patterns that the tech choice determines - -### 4. Example - -``` -Tech chosen: REST API + PostgreSQL + React -↓ -LLM identifies needs: -- REST: URL structure, response format, status codes -- PostgreSQL: table naming, column naming, FK patterns -- React: component structure, state management, test location -↓ -Facilitates each with user -↓ -Documents as Implementation Patterns in architecture -``` - ---- - -## How Starter Templates Work - -When the workflow detects a project type that has a starter template: - -1. **Discovery**: Searches for relevant starter templates based on PRD -2. **Investigation**: Looks up current CLI options and defaults -3. **Presentation**: Shows user what the starter provides -4. **Integration**: Documents starter decisions as "PROVIDED BY STARTER" -5. **Continuation**: Only asks about decisions NOT made by starter -6. **Documentation**: Includes exact initialization command in architecture - -### Example Flow - -``` -PRD says: "Next.js web application with authentication" -↓ -Workflow finds: create-next-app and create-t3-app -↓ -User chooses: create-t3-app (includes auth setup) -↓ -Starter provides: Next.js, TypeScript, tRPC, Prisma, NextAuth, Tailwind -↓ -Workflow only asks about: Database choice, deployment target, additional services -↓ -First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma" -``` - ---- - -## Usage - -```bash -# In your BMAD-enabled project -workflow architecture -``` - -The AI agent will: - -1. Load your PRD (with FRs/NFRs) -2. Identify critical decisions needed -3. Facilitate discussion on each decision -4. Generate a comprehensive architecture document -5. Validate completeness - ---- - -## Design Principles - -1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates -2. **Intelligence over Templates** - Use AI understanding rather than rigid structures -3. **Decisions over Details** - Focus on what prevents agent conflicts, not implementation minutiae -4. **Adaptation over Uniformity** - Meet users where they are while ensuring quality output -5. **Collaboration over Output** - The conversation matters as much as the document - ---- - -## For Developers - -This workflow assumes: - -- Single developer + AI agents (not teams) -- Speed matters (decisions in minutes, not days) -- AI agents need clear constraints to prevent conflicts -- The architecture document is for agents, not humans - ---- - -## Migration from architecture - -Projects using the old `architecture` workflow should: - -1. Complete any in-progress architecture work -2. Use `architecture` for new projects -3. The old workflow remains available but is deprecated - ---- - -## Version History - -**1.3.2** - UX specification integration and fuzzy file matching - -- Added UX spec as optional input with fuzzy file matching -- Updated workflow.yaml with input file references -- Starter template selection now considers UX requirements -- Added UX alignment validation to checklist -- Instructions use variable references for flexible file names - -**1.3.1** - Workflow refinement and standardization - -- Added workflow status checking at start (Steps 0 and 0.5) -- Added workflow status updating at end (Step 12) -- Reorganized step numbering for clarity (removed fractional steps) -- Enhanced with intent-based approach throughout -- Improved cohesiveness across all workflow components - -**1.3.0** - Novel pattern design for unique architectures - -- Added novel pattern design (now Step 7, formerly Step 5.3) -- Detects novel concepts in PRD that need architectural invention -- Facilitates design collaboration with sequence diagrams -- Uses elicitation for innovative approaches -- Documents custom patterns for multi-epic consistency - -**1.2.0** - Implementation patterns for agent consistency - -- Added implementation patterns (now Step 8, formerly Step 5.5) -- Created principle-based pattern-categories.csv (7 principles, not 118 prescriptions) -- Core principle: "What could agents decide differently?" -- LLM uses principle to identify patterns beyond the categories -- Prevents agent conflicts through intelligent pattern discovery - -**1.1.0** - Enhanced with starter template discovery and version verification - -- Added intelligent starter template detection and integration (now Step 2) -- Added dynamic version verification via web search -- Starter decisions are documented as "PROVIDED BY STARTER" -- First implementation story uses starter initialization command - -**1.0.0** - Initial release replacing architecture workflow - ---- - -**Related Documentation:** - -- [Solutioning Workflows](./workflows-solutioning.md) -- [Planning Workflows](./workflows-planning.md) -- [Scale Adaptive System](./scale-adaptive-system.md) diff --git a/src/modules/bmm/docs/workflow-document-project-reference.md b/src/modules/bmm/docs/workflow-document-project-reference.md index ad1e5a02..c835607f 100644 --- a/src/modules/bmm/docs/workflow-document-project-reference.md +++ b/src/modules/bmm/docs/workflow-document-project-reference.md @@ -1,54 +1,23 @@ # Document Project Workflow - Technical Reference **Module:** BMM (BMAD Method Module) -**Type:** Action Workflow (Documentation Generator) - ---- ## Purpose Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development. Generates a master index and multiple documentation files tailored to project structure and type. -**NEW in v1.2.0:** Context-safe architecture with scan levels, resumability, and write-as-you-go pattern to prevent context exhaustion. - ---- - -## Key Features - -- **Multi-Project Type Support**: Handles web, backend, mobile, CLI, game, embedded, data, infra, library, desktop, and extension projects -- **Multi-Part Detection**: Automatically detects and documents projects with separate client/server or multiple services -- **Three Scan Levels** (NEW v1.2.0): Quick (2-5 min), Deep (10-30 min), Exhaustive (30-120 min) -- **Resumability** (NEW v1.2.0): Interrupt and resume workflows without losing progress -- **Write-as-you-go** (NEW v1.2.0): Documents written immediately to prevent context exhaustion -- **Intelligent Batching** (NEW v1.2.0): Subfolder-based processing for deep/exhaustive scans -- **Data-Driven Analysis**: Uses CSV-based project type detection and documentation requirements -- **Comprehensive Scanning**: Analyzes APIs, data models, UI components, configuration, security patterns, and more -- **Architecture Matching**: Matches projects to 170+ architecture templates from the solutioning registry -- **Brownfield PRD Ready**: Generates documentation specifically designed for AI agents planning new features - ---- - ## How to Invoke - -```bash -workflow document-project -``` - -Or from BMAD CLI: - ```bash /bmad:bmm:workflows:document-project ``` - --- -## Scan Levels (NEW in v1.2.0) +## Scan Levels Choose the right scan depth for your needs: ### 1. Quick Scan (Default) -**Duration:** 2-5 minutes **What it does:** Pattern-based analysis without reading source files **Reads:** Config files, package manifests, directory structure, README **Use when:** @@ -61,7 +30,6 @@ Choose the right scan depth for your needs: ### 2. Deep Scan -**Duration:** 10-30 minutes **What it does:** Reads files in critical directories based on project type **Reads:** Files in critical paths defined by documentation requirements **Use when:** @@ -74,7 +42,6 @@ Choose the right scan depth for your needs: ### 3. Exhaustive Scan -**Duration:** 30-120 minutes **What it does:** Reads ALL source files in project **Reads:** Every source file (excludes node_modules, dist, build, .git) **Use when:** @@ -88,7 +55,7 @@ Choose the right scan depth for your needs: --- -## Resumability (NEW in v1.2.0) +## Resumability The workflow can be interrupted and resumed without losing progress: @@ -98,392 +65,7 @@ The workflow can be interrupted and resumed without losing progress: - **Step-by-Step:** Resume from exact step where interrupted - **Archiving:** Old state files automatically archived -**Example Resume Flow:** - -``` -> workflow document-project - -I found an in-progress workflow state from 2025-10-11 14:32:15. - -Current Progress: -- Mode: initial_scan -- Scan Level: deep -- Completed Steps: 5/12 -- Last Step: step_5 - -Would you like to: -1. Resume from where we left off - Continue from step 6 -2. Start fresh - Archive old state and begin new scan -3. Cancel - Exit without changes - -Your choice [1/2/3]: -``` - ---- - -## What It Does - -### Step-by-Step Process - -1. **Detects Project Structure** - Identifies if project is single-part or multi-part (client/server/etc.) -2. **Classifies Project Type** - Matches against 12 project types (web, backend, mobile, etc.) -3. **Discovers Documentation** - Finds existing README, CONTRIBUTING, ARCHITECTURE files -4. **Analyzes Tech Stack** - Parses package files, identifies frameworks, versions, dependencies -5. **Conditional Scanning** - Performs targeted analysis based on project type requirements: - - API routes and endpoints - - Database models and schemas - - State management patterns - - UI component libraries - - Configuration and security - - CI/CD and deployment configs -6. **Generates Source Tree** - Creates annotated directory structure with critical paths -7. **Extracts Dev Instructions** - Documents setup, build, run, and test commands -8. **Creates Architecture Docs** - Generates detailed architecture using matched templates -9. **Builds Master Index** - Creates comprehensive index.md as primary AI retrieval source -10. **Validates Output** - Runs 140+ point checklist to ensure completeness - -### Output Files - -**Single-Part Projects:** - -- `index.md` - Master index -- `project-overview.md` - Executive summary -- `architecture.md` - Detailed architecture -- `source-tree-analysis.md` - Annotated directory tree -- `component-inventory.md` - Component catalog (if applicable) -- `development-guide.md` - Local dev instructions -- `api-contracts.md` - API documentation (if applicable) -- `data-models.md` - Database schema (if applicable) -- `deployment-guide.md` - Deployment process (optional) -- `contribution-guide.md` - Contributing guidelines (optional) -- `project-scan-report.json` - State file for resumability (NEW v1.2.0) - -**Multi-Part Projects (e.g., client + server):** - -- `index.md` - Master index with part navigation -- `project-overview.md` - Multi-part summary -- `architecture-{part_id}.md` - Per-part architecture docs -- `source-tree-analysis.md` - Full tree with part annotations -- `component-inventory-{part_id}.md` - Per-part components -- `development-guide-{part_id}.md` - Per-part dev guides -- `integration-architecture.md` - How parts communicate -- `project-parts.json` - Machine-readable metadata -- `project-scan-report.json` - State file for resumability (NEW v1.2.0) -- Additional conditional files per part (API, data models, etc.) - ---- - -## Data Files - -The workflow uses a single comprehensive CSV file: - -**documentation-requirements.csv** - Complete project analysis guide - -- Location: `/_bmad/bmm/workflows/document-project/documentation-requirements.csv` -- 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded) -- 24 columns combining: - - **Detection columns**: `project_type_id`, `key_file_patterns` (identifies project type from codebase) - - **Requirement columns**: `requires_api_scan`, `requires_data_models`, `requires_ui_components`, etc. - - **Pattern columns**: `critical_directories`, `test_file_patterns`, `config_patterns`, etc. -- Self-contained: All project detection AND scanning requirements in one file -- Architecture patterns inferred from tech stack (no external registry needed) - ---- - -## Use Cases - -### Primary Use Case: Brownfield PRD Creation - -After running this workflow, use the generated `index.md` as input to brownfield PRD workflows: - -``` -User: "I want to add a new dashboard feature" -PRD Workflow: Loads docs/index.md -→ Understands existing architecture -→ Identifies reusable components -→ Plans integration with existing APIs -→ Creates contextual PRD with FRs and NFRs -Architecture Workflow: Creates architecture design -Create-Epics-and-Stories Workflow: Breaks down into epics and stories -``` - -### Other Use Cases - -- **Onboarding New Developers** - Comprehensive project documentation -- **Architecture Review** - Structured analysis of existing system -- **Technical Debt Assessment** - Identify patterns and anti-patterns -- **Migration Planning** - Understand current state before refactoring - ---- - -## Requirements - -### Recommended Inputs (Optional) - -- Project root directory (defaults to current directory) -- README.md or similar docs (auto-discovered if present) -- User guidance on key areas to focus (workflow will ask) - -### Tools Used - -- File system scanning (Glob, Read, Grep) -- Code analysis -- Git repository analysis (optional) - ---- - -## Configuration - -### Default Output Location - -Files are saved to: `{output_folder}` (from config.yaml) - -Default: `/docs/` folder in project root - -### Customization - -- Modify `documentation-requirements.csv` to adjust scanning patterns for project types -- Add new project types to `project-types.csv` -- Add new architecture templates to `registry.csv` - ---- - -## Example: Multi-Part Web App - -**Input:** - -``` -my-app/ -├── client/ # React frontend -├── server/ # Express backend -└── README.md -``` - -**Detection Result:** - -- Repository Type: Monorepo -- Part 1: client (web/React) -- Part 2: server (backend/Express) - -**Output (10+ files):** - -``` -docs/ -├── index.md -├── project-overview.md -├── architecture-client.md -├── architecture-server.md -├── source-tree-analysis.md -├── component-inventory-client.md -├── development-guide-client.md -├── development-guide-server.md -├── api-contracts-server.md -├── data-models-server.md -├── integration-architecture.md -└── project-parts.json -``` - ---- - -## Example: Simple CLI Tool - -**Input:** - -``` -hello-cli/ -├── main.go -├── go.mod -└── README.md -``` - -**Detection Result:** - -- Repository Type: Monolith -- Part 1: main (cli/Go) - -**Output (4 files):** - -``` -docs/ -├── index.md -├── project-overview.md -├── architecture.md -└── source-tree-analysis.md -``` - ---- - -## Deep-Dive Mode - -### What is Deep-Dive Mode? - -When you run the workflow on a project that already has documentation, you'll be offered a choice: - -1. **Rescan entire project** - Update all documentation with latest changes -2. **Deep-dive into specific area** - Generate EXHAUSTIVE documentation for a particular feature/module/folder -3. **Cancel** - Keep existing documentation - -Deep-dive mode performs **comprehensive, file-by-file analysis** of a specific area, reading EVERY file completely and documenting: - -- All exports with complete signatures -- All imports and dependencies -- Dependency graphs and data flow -- Code patterns and implementations -- Testing coverage and strategies -- Integration points -- Reuse opportunities - -### When to Use Deep-Dive Mode - -- **Before implementing a feature** - Deep-dive the area you'll be modifying -- **During architecture review** - Deep-dive complex modules -- **For code understanding** - Deep-dive unfamiliar parts of codebase -- **When creating PRDs** - Deep-dive areas affected by new features - -### Deep-Dive Process - -1. Workflow detects existing `index.md` -2. Offers deep-dive option -3. Suggests areas based on project structure: - - API route groups - - Feature modules - - UI component areas - - Services/business logic -4. You select area or specify custom path -5. Workflow reads EVERY file in that area -6. Generates `deep-dive-{area-name}.md` with complete analysis -7. Updates `index.md` with link to deep-dive doc -8. Offers to deep-dive another area or finish - -### Deep-Dive Output Example - -**docs/deep-dive-dashboard-feature.md:** - -- Complete file inventory (47 files analyzed) -- Every export with signatures -- Dependency graph -- Data flow analysis -- Integration points -- Testing coverage -- Related code references -- Implementation guidance -- ~3,000 LOC documented in detail - -### Incremental Deep-Diving - -You can deep-dive multiple areas over time: - -- First run: Scan entire project → generates index.md -- Second run: Deep-dive dashboard feature -- Third run: Deep-dive API layer -- Fourth run: Deep-dive authentication system - -All deep-dive docs are linked from the master index. - ---- - -## Validation - -The workflow includes a comprehensive 160+ point checklist covering: - -- Project detection accuracy -- Technology stack completeness -- Codebase scanning thoroughness -- Architecture documentation quality -- Multi-part handling (if applicable) -- Brownfield PRD readiness -- Deep-dive completeness (if applicable) - ---- - -## Next Steps After Completion - -1. **Review** `docs/index.md` - Your master documentation index -2. **Validate** - Check generated docs for accuracy -3. **Use for PRD** - Point brownfield PRD workflow to index.md -4. **Maintain** - Re-run workflow when architecture changes significantly - ---- - -## File Structure - -``` -document-project/ -├── workflow.yaml # Workflow configuration -├── instructions.md # Step-by-step workflow logic -├── checklist.md # Validation criteria -├── documentation-requirements.csv # Project type scanning patterns -├── templates/ # Output templates -│ ├── index-template.md -│ ├── project-overview-template.md -│ └── source-tree-template.md -└── README.md # This file -``` - ---- - -## Troubleshooting - -**Issue: Project type not detected correctly** - -- Solution: Workflow will ask for confirmation; manually select correct type - -**Issue: Missing critical information** - -- Solution: Provide additional context when prompted; re-run specific analysis steps - -**Issue: Multi-part detection missed a part** - -- Solution: When asked to confirm parts, specify the missing part and its path - -**Issue: Architecture template doesn't match well** - -- Solution: Check registry.csv; may need to add new template or adjust matching criteria - ---- - -## Architecture Improvements in v1.2.0 - -### Context-Safe Design - -The workflow now uses a write-as-you-go architecture: - -- Documents written immediately to disk (not accumulated in memory) -- Detailed findings purged after writing (only summaries kept) -- State tracking enables resumption from any step -- Batching strategy prevents context exhaustion on large projects - -### Batching Strategy - -For deep/exhaustive scans: - -- Process ONE subfolder at a time -- Read files → Extract info → Write output → Validate → Purge context -- Primary concern is file SIZE (not count) -- Track batches in state file for resumability - -### State File Format - -Optimized JSON (no pretty-printing): - -```json -{ - "workflow_version": "1.2.0", - "timestamps": {...}, - "mode": "initial_scan", - "scan_level": "deep", - "completed_steps": [...], - "current_step": "step_6", - "findings": {"summary": "only"}, - "outputs_generated": [...], - "resume_instructions": "..." -} -``` - ---- - **Related Documentation:** - [Brownfield Development Guide](./brownfield-guide.md) - [Implementation Workflows](./workflows-implementation.md) -- [Scale Adaptive System](./scale-adaptive-system.md) diff --git a/src/modules/bmm/docs/workflows-analysis.md b/src/modules/bmm/docs/workflows-analysis.md index 8eed43be..9dd5a359 100644 --- a/src/modules/bmm/docs/workflows-analysis.md +++ b/src/modules/bmm/docs/workflows-analysis.md @@ -19,7 +19,6 @@ Phase 1 Analysis consists of three categories of optional workflows: ### Discovery & Ideation (Optional) - **brainstorm-project** - Multi-track solution exploration for software projects -- **brainstorm-game** - Game concept generation (coming soon) ### Research & Validation (Optional) @@ -54,19 +53,10 @@ These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` w **When to Use:** -- Unclear technical approach with business objectives -- Multiple solution paths need evaluation -- Hidden assumptions need discovery -- Innovation beyond obvious solutions - -**Key Outputs:** - -- Architecture proposals with trade-off analysis -- Value framework (prioritized features) -- Risk analysis (dependencies, challenges) -- Strategic recommendation with rationale - -**Example:** "We need a customer dashboard" → Options: Monolith SSR (faster), Microservices SPA (scalable), Hybrid (balanced) with recommendation. +- Very vague or seed kernal of an idea that needs exploration +- Consider alternatives or enhancements to an idea +- See your idea from different angles and viewpoints +- No idea what you want to build, but want to find some inspiration --- @@ -111,11 +101,6 @@ These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` w - Transitioning from exploration to strategy - Need executive-level product documentation -**Modes:** - -- **Interactive Mode** (Recommended): Step-by-step collaborative development with probing questions -- **YOLO Mode**: AI generates complete draft from context, then iterative refinement - **Key Outputs:** - Executive summary @@ -179,32 +164,6 @@ Analysis outputs feed directly into Planning: Planning workflows automatically load these documents if they exist in the output folder. ---- - -## Best Practices - -### 1. Don't Over-Invest in Analysis - -Analysis is optional. If requirements are clear, skip to Phase 2 (Planning). - -### 2. Iterate Between Workflows - -Common pattern: brainstorm → research (validate) → brief (synthesize) - -### 3. Document Assumptions - -Analysis surfaces and validates assumptions. Document them explicitly for planning to challenge. - -### 4. Keep It Strategic - -Focus on "what" and "why", not "how". Leave implementation for Planning and Solutioning. - -### 5. Involve Stakeholders - -Use analysis workflows to align stakeholders before committing to detailed planning. - ---- - ## Common Patterns ### Greenfield Software (Full Analysis) @@ -238,29 +197,3 @@ Use analysis workflows to align stakeholders before committing to detailed plann - [Phase 4: Implementation Workflows](./workflows-implementation.md) - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project complexity - [Agents Guide](./agents-guide.md) - Complete agent reference - ---- - -## Troubleshooting - -**Q: Do I need to run all analysis workflows?** -A: No! Analysis is entirely optional. Use only workflows that help you think through your problem. - -**Q: Which workflow should I start with?** -A: If unsure, start with `research` (market type) to validate viability, then move to `product-brief`. - -**Q: Can I skip straight to Planning?** -A: Yes! If you know what you're building and why, skip Phase 1 entirely and start with Phase 2 (prd/tech-spec). - -**Q: How long should Analysis take?** -A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning. - -**Q: What if I discover problems during Analysis?** -A: That's the point! Analysis helps you fail fast and pivot before heavy planning investment. - -**Q: Should brownfield projects do Analysis?** -A: Usually no. Start with `document-project` (Documentation prerequisite), then skip to Planning (Phase 2). - ---- - -_Phase 1 Analysis - Optional strategic thinking before commitment._ diff --git a/src/modules/bmm/docs/workflows-planning.md b/src/modules/bmm/docs/workflows-planning.md index 3ce91599..b826ae44 100644 --- a/src/modules/bmm/docs/workflows-planning.md +++ b/src/modules/bmm/docs/workflows-planning.md @@ -1,183 +1,14 @@ # BMM Planning Workflows (Phase 2) -## Overview - -Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity. - -**Key principle:** One unified entry point (`workflow-init`) intelligently routes to the appropriate planning methodology - from quick tech-specs to comprehensive PRDs. - -**When to use:** All projects require planning. The system adapts depth automatically based on complexity. - ---- - ## Phase 2 Planning Workflow Overview -Phase 2 Planning uses a scale-adaptive system with three tracks: - -### Quick Flow (Simple Planning) - -- Entry: `workflow-init` routes based on project complexity -- Workflow: `tech-spec` -- Output: Technical document with story/epic structure -- Story count: 1-15 (typical) -- Next: Phase 4 (Implementation) - skips Phase 3 - -### BMad Method (Recommended) - -- Entry: `workflow-init` routes based on project complexity -- Workflows: `prd` → (optional) `create-ux-design` -- Output: PRD with FRs/NFRs -- Story count: 10-50+ (typical) -- Next: Phase 3 (Solutioning) → Phase 4 - -### Enterprise Method - -- Planning: Same as BMad Method (`prd` workflow) -- Solutioning: Extended Phase 3 workflows (Architecture + Security + DevOps) -- Story count: 30+ (typical) -- Next: Phase 4 - -The `correct-course` workflow can be used anytime for significant requirement changes. - ---- ## Quick Reference -| Workflow | Agent | Track | Purpose | Typical Stories | -| -------------------- | ----------- | ----------------------- | ----------------------------------------------- | --------------- | -| **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A | -| **tech-spec** | PM | Quick Flow | Technical document → Story or Epic+Stories | 1-15 | -| **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+ | -| **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) | N/A | -| **correct-course** | PM/SM | All | Mid-stream requirement changes | N/A | - -**Note:** Story counts are guidance. V6 improvement: Epic+Stories are created AFTER architecture for better quality. - ---- - -## Scale-Adaptive Planning System - -BMM uses three distinct planning tracks that adapt to project complexity: - -### Track 1: Quick Flow - -**Best For:** Bug fixes, simple features, clear scope, enhancements - -**Planning:** Tech-spec only → Implementation - -**Time:** Hours to 1 day - -**Story Count:** Typically 1-15 (guidance) - -**Documents:** tech-spec.md + story files - -**Example:** "Fix authentication bug", "Add OAuth social login" - ---- - -### Track 2: BMad Method (RECOMMENDED) - -**Best For:** Products, platforms, complex features, multiple epics - -**Planning:** PRD + Architecture → Implementation - -**Time:** 1-3 days - -**Story Count:** Typically 10-50+ (guidance) - -**Documents:** PRD.md (FRs/NFRs) + architecture.md + epics.md + epic files - -**Greenfield:** Product Brief (optional) → PRD (FRs/NFRs) → UX (optional) → Architecture → Epics+Stories → Implementation - -**Brownfield:** document-project → PRD (FRs/NFRs) → Architecture (recommended) → Epics+Stories → Implementation - -**Example:** "Customer dashboard", "E-commerce platform", "Add search to existing app" - -**Why Architecture for Brownfield?** Distills massive codebase context into focused solution design for your specific project. - ---- - -### Track 3: Enterprise Method - -**Best For:** Enterprise requirements, multi-tenant, compliance, security-sensitive - -**Planning (Phase 2):** Uses BMad Method planning (PRD with FRs/NFRs) - -**Solutioning (Phase 3):** Extended workflows (Architecture + Security + DevOps + SecOps as optional additions) → Epics+Stories - -**Time:** 3-7 days total (1-3 days planning + 2-4 days extended solutioning) - -**Story Count:** Typically 30+ (but defined by enterprise needs) - -**Documents Phase 2:** PRD.md (FRs/NFRs) - -**Documents Phase 3:** architecture.md + epics.md + epic files + security-architecture.md (optional) + devops-strategy.md (optional) + secops-strategy.md (optional) - -**Example:** "Multi-tenant SaaS", "HIPAA-compliant portal", "Add SOC2 audit logging" - ---- - -## How Track Selection Works - -`workflow-init` guides you through educational choice: - -1. **Description Analysis** - Analyzes project description for complexity -2. **Educational Presentation** - Shows all three tracks with trade-offs -3. **Recommendation** - Suggests track based on keywords and context -4. **User Choice** - You select the track that fits - -The system guides but never forces. You can override recommendations. - ---- - -## Workflow Descriptions - -### workflow-init (Entry Point) - -**Purpose:** Single unified entry point for all planning. Discovers project needs and intelligently routes to appropriate track. - -**Agent:** PM (orchestrates others as needed) - -**Always Use:** This is your planning starting point. Don't call prd/tech-spec directly unless skipping discovery. - -**Process:** - -1. Discovery (understand context, assess complexity, identify concerns) -2. Routing Decision (determine track, explain rationale, confirm) -3. Execute Target Workflow (invoke planning workflow, pass context) -4. Handoff (document decisions, recommend next phase) - ---- - -### tech-spec (Quick Flow) - -**Purpose:** Lightweight technical specification for simple changes (Quick Flow track). Produces technical document and story or epic+stories structure. - -**Agent:** PM - -**When to Use:** - -- Bug fixes -- Single API endpoint additions -- Configuration changes -- Small UI component additions -- Isolated validation rules - -**Key Outputs:** - -- **tech-spec.md** - Technical document containing: - - Problem statement and solution - - Source tree changes - - Implementation details - - Testing strategy - - Acceptance criteria -- **Story file(s)** - Single story OR epic+stories structure (1-15 stories typically) - -**Skip To Phase:** 4 (Implementation) - no Phase 3 architecture needed - -**Example:** "Fix null pointer when user has no profile image" → Single file change, null check, unit test, no DB migration. - ---- +| Workflow | Agent | Track | Purpose | +| -------------------- | ----------- | ----------------------- | ------------------------------------- | +| **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs | +| **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) | ### prd (Product Requirements Document) @@ -245,207 +76,14 @@ The system guides but never forces. You can override recommendations. **Example:** Dashboard redesign → Card-based layout with split-pane toggle, 5 card components, 12 color tokens, responsive grid, 3 epics (Layout, Visualization, Accessibility). ---- - -### correct-course - -**Purpose:** Handle significant requirement changes during implementation (all tracks). - -**Agent:** PM, Architect, or SM - -**When to Use:** - -- Priorities change mid-project -- New requirements emerge -- Scope adjustments needed -- Technical blockers require replanning - -**Process:** - -1. Analyze impact of change -2. Propose solutions (continue, pivot, pause) -3. Update affected documents (PRD, epics, stories) -4. Re-route for implementation - -**Integration:** Updates planning artifacts, may trigger architecture review - ---- - -## Decision Guide - -### Which Planning Workflow? - -**Use `workflow-init` (Recommended):** Let the system discover needs and route appropriately. - -**Direct Selection (Advanced):** - -- **Bug fix or single change** → `tech-spec` (Quick Flow) -- **Software product** → `prd` (BMad Method) -- **UX innovation project** → `create-ux-design` + `prd` (BMad Method) -- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method - ---- - -## Integration with Phase 3 (Solutioning) - -Planning outputs feed into Solutioning: - -| Planning Output | Solutioning Input | Track Decision | -| --------------- | ---------------------------------- | ---------------------------- | -| tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) | -| PRD.md | **architecture** (Level 3-4) | BMad Method (recommended) | -| ux-spec.md | **architecture** (frontend design) | BMad Method | -| Enterprise docs | **architecture** + security/ops | Enterprise Method (required) | - -**Key Decision Points:** - -- **Quick Flow:** Skip Phase 3 entirely → Phase 4 (Implementation) -- **BMad Method:** Optional Phase 3 (simple), Required Phase 3 (complex) -- **Enterprise:** Required Phase 3 (architecture + extended planning) - -See: [workflows-solutioning.md](./workflows-solutioning.md) - ---- - ## Best Practices -### 1. Always Start with workflow-init +### 1. Do Product Brief from Phase 1 to kickstart the PRD for better results -Let the entry point guide you. It prevents over-planning simple features or under-planning complex initiatives. - -### 2. Trust the Recommendation - -If `workflow-init` suggests BMad Method, there's likely complexity you haven't considered. Review carefully before overriding. - -### 3. Iterate on Requirements - -Planning documents are living. Refine PRDs as you learn during Solutioning and Implementation. - -### 4. Involve Stakeholders Early - -Review PRDs with stakeholders before Solutioning. Catch misalignment early. - -### 5. Focus on "What" Not "How" +### 2. Focus on "What" Not "How" Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning). -### 6. Document-Project First for Brownfield +### 3. Document-Project First for Brownfield -Always run `document-project` before planning brownfield projects. AI agents need existing codebase context. - ---- - -## Common Patterns - -### Greenfield Software (BMad Method) - -``` -1. (Optional) Analysis: product-brief, research -2. workflow-init → routes to prd -3. PM: prd workflow -4. (Optional) UX Designer: create-ux-design workflow -5. → Phase 3: architecture -``` - -### Brownfield Software (BMad Method) - -``` -1. Technical Writer or Analyst: document-project -2. workflow-init → routes to prd -3. PM: prd workflow -4. → Phase 3: architecture (recommended for focused solution design) -``` - -### Bug Fix (Quick Flow) - -``` -1. workflow-init → routes to tech-spec -2. PM: tech-spec workflow -3. → Phase 4: Implementation (skip Phase 3) -``` - -### Enterprise Project (Enterprise Method) - -``` -1. (Recommended) Analysis: research (compliance, security) -2. workflow-init → routes to Enterprise Method -3. PM: prd workflow -4. (Optional) UX Designer: ux workflow -5. PM: create-epics-and-stories -6. → Phase 3: architecture + security + devops + test strategy -``` - ---- - -## Common Anti-Patterns - -### ❌ Skipping Planning - -"We'll just start coding and figure it out." -**Result:** Scope creep, rework, missed requirements - -### ❌ Over-Planning Simple Changes - -"Let me write a 20-page PRD for this button color change." -**Result:** Wasted time, analysis paralysis - -### ❌ Planning Without Discovery - -"I already know what I want, skip the questions." -**Result:** Solving wrong problem, missing opportunities - -### ❌ Treating PRD as Immutable - -"The PRD is locked, no changes allowed." -**Result:** Ignoring new information, rigid planning - -### ✅ Correct Approach - -- Use scale-adaptive planning (right depth for complexity) -- Involve stakeholders in review -- Iterate as you learn -- Keep planning docs living and updated -- Use `correct-course` for significant changes - ---- - -## Related Documentation - -- [Phase 1: Analysis Workflows](./workflows-analysis.md) - Optional discovery phase -- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - Next phase -- [Phase 4: Implementation Workflows](./workflows-implementation.md) -- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding the three tracks -- [Quick Spec Flow](./quick-spec-flow.md) - Quick Flow track details -- [Agents Guide](./agents-guide.md) - Complete agent reference - ---- - -## Troubleshooting - -**Q: Which workflow should I run first?** -A: Run `workflow-init`. It analyzes your project and routes to the right planning workflow. - -**Q: Do I always need a PRD?** -A: No. Simple changes use `tech-spec` (Quick Flow). Only BMad Method and Enterprise tracks create PRDs. - -**Q: Can I skip Phase 3 (Solutioning)?** -A: Yes for Quick Flow. Optional for BMad Method (simple projects). Required for BMad Method (complex projects) and Enterprise. - -**Q: How do I know which track to choose?** -A: Use `workflow-init` - it recommends based on your description. Story counts are guidance, not definitions. - -**Q: What if requirements change mid-project?** -A: Run `correct-course` workflow. It analyzes impact and updates planning artifacts. - -**Q: Do brownfield projects need architecture?** -A: Recommended! Architecture distills massive codebase into focused solution design for your specific project. - -**Q: When do I run create-epics-and-stories?** -A: In Phase 3 (Solutioning), after architecture is complete. - -**Q: Should I use product-brief before PRD?** -A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context. - ---- - -_Phase 2 Planning - Scale-adaptive requirements for every project._ +Always run `document-project` before planning brownfield projects. AI agents need existing codebase context and will make a large quality difference. If you are adding a small addition to an existing project, you might want to consider instead after using document-project to use the quick flow solo dev process instead. diff --git a/tools/cli/installers/install-messages.yaml b/tools/cli/installers/install-messages.yaml index 1de5c070..c2fe7fd7 100644 --- a/tools/cli/installers/install-messages.yaml +++ b/tools/cli/installers/install-messages.yaml @@ -6,11 +6,13 @@ startMessage: | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - 🎉🎉 Happy Holidays and New Year 🍾🍾 + If you are looking for Version 4 of BMad Method, please note that you can + still install it by using the command `npx bmad-method@latest install`, until v6 reaches beta. - IMPORTANT Changes with Version Alpha.20 - PLEASE READ THIS if upgrading from earlier Alpha Versions: + IMPORTANT Changes with Version Alpha.22 - PLEASE READ THIS if upgrading from earlier Alpha Versions: - 1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs` is meant for long-term artifacts, which you can always decide to move content to. + 1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs` + is meant for long-term artifacts, which you can always decide to move content to. 2. If utilizing the BMad Method Module (BMM) please be aware of the following important recent changes: @@ -21,8 +23,8 @@ startMessage: | IT IS STRONGLY SUGGESTED to align with these folder conventions instead of dumping all to docs/ - if you are upgrading from a prior version where all output was going to docs or docs/sprint-artifacts, it is suggested to reset configs to these new values. - If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts, and if you had brainstorming - content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts. + If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts, + and if you had brainstorming content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts. Read the latest updates before continuing: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md @@ -35,8 +37,11 @@ endMessage: | ✨ BMAD IS READY TO USE! - ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of being migrated to the improved workflow progressive disclosure system. - Along with this, the full conversion to the new path locations for content being searched may possibly be incomplete. If you run a workflow that relies on finding input documents automatically, and you notice they are not being found / looking in the wrong location, either: + ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of + being migrated to the improved workflow progressive disclosure system. + Along with this, the full conversion to the new path locations for content being searched + may possibly be incomplete. If you run a workflow that relies on finding input documents + automatically, and you notice they are not being found / looking in the wrong location, either: 1. Manually specify the correct input location when prompted 2. Open an issue on GitHub so we can address the problem quickly if you think its a bug. 3. Ensure your content is in the new locations for best results: @@ -47,6 +52,7 @@ endMessage: | Thank you for helping test the early release version of the new BMad Core and BMad Method! Stable Beta coming soon - please read the full README.md and linked documentation to get started. - And again, here is the Change Log with all the details of recent updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md + And again, here is the Change Log with all the details of recent updates: + https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md ════════════════════════════════════════════════════════════════════════════════ diff --git a/tools/cli/installers/lib/core/detector.js b/tools/cli/installers/lib/core/detector.js index 1fe76104..a50c56e4 100644 --- a/tools/cli/installers/lib/core/detector.js +++ b/tools/cli/installers/lib/core/detector.js @@ -210,26 +210,6 @@ class Detector { * @returns {{ hasLegacyV4: boolean, offenders: string[] }} */ async detectLegacyV4(projectDir) { - // Helper: check existence of a nested path with case-sensitive segment matching - const existsCaseSensitive = async (baseDir, segments) => { - let dir = baseDir; - for (let i = 0; i < segments.length; i++) { - const seg = segments[i]; - let entries; - try { - entries = await fs.readdir(dir, { withFileTypes: true }); - } catch { - return false; - } - const hit = entries.find((e) => e.name === seg); - if (!hit) return false; - // Parents must be directories; the last segment may be a file or directory - if (i < segments.length - 1 && !hit.isDirectory()) return false; - dir = path.join(dir, hit.name); - } - return true; - }; - // Helper: check if a directory is a V6+ installation const isV6Installation = async (dirPath) => { const manifestPath = path.join(dirPath, '_config', 'manifest.yaml'); diff --git a/website/sidebars.js b/website/sidebars.js index 3175f711..827fa131 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -11,25 +11,7 @@ const sidebars = { type: 'category', label: 'IDE Guides', collapsed: true, - items: [ - 'ide-info/index', - 'ide-info/claude-code', - 'ide-info/cursor', - 'ide-info/windsurf', - 'ide-info/cline', - 'ide-info/github-copilot', - 'ide-info/auggie', - 'ide-info/codex', - 'ide-info/crush', - 'ide-info/gemini', - 'ide-info/iflow', - 'ide-info/kilo', - 'ide-info/opencode', - 'ide-info/qwen', - 'ide-info/roo', - 'ide-info/rovo-dev', - 'ide-info/trae', - ], + items: [], }, 'v4-to-v6-upgrade', ], diff --git a/website/src/pages/downloads.md b/website/src/pages/downloads.md index cef3a41b..d7e134d2 100644 --- a/website/src/pages/downloads.md +++ b/website/src/pages/downloads.md @@ -33,15 +33,6 @@ docs = requests.get("https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt") # Include in your system prompt or context ``` -## Source Bundles - -Download the complete source code for offline development or contribution. - -| Bundle | Contents | -| --------------------------------------------------- | ------------------------------------------- | -| **[bmad-sources.zip](/downloads/bmad-sources.zip)** | Complete `/src/` directory with all modules | -| **[bmad-prompts.zip](/downloads/bmad-prompts.zip)** | Agent prompts and workflows from `/_bmad/` | - ## Installation Options ### NPM (Recommended) @@ -50,12 +41,6 @@ Download the complete source code for offline development or contribution. npx bmad-method@alpha install ``` -### Manual Installation - -1. Download `bmad-prompts.zip` -2. Extract to your project root -3. Configure your IDE per the [IDE Guides](/docs/ide-info/) - ## Version Information - **Current Version:** See [CHANGELOG](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md) From 2a8a4388a9bfd755299002a6619295179134325c Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 27 Dec 2025 20:31:12 +0800 Subject: [PATCH 5/6] v4 detection cleanup --- .../workflows/document-project/checklist.md | 4 +- tools/cli/installers/lib/core/detector.js | 100 +-------------- tools/cli/installers/lib/core/installer.js | 121 +++++++----------- 3 files changed, 52 insertions(+), 173 deletions(-) diff --git a/src/modules/bmm/workflows/document-project/checklist.md b/src/modules/bmm/workflows/document-project/checklist.md index 636312b4..7b67d1e5 100644 --- a/src/modules/bmm/workflows/document-project/checklist.md +++ b/src/modules/bmm/workflows/document-project/checklist.md @@ -1,6 +1,6 @@ # Document Project Workflow - Validation Checklist -## Scan Level and Resumability (v1.2.0) +## Scan Level and Resumability - [ ] Scan level selection offered (quick/deep/exhaustive) for initial_scan and full_rescan modes - [ ] Deep-dive mode automatically uses exhaustive scan (no choice given) @@ -223,7 +223,7 @@ All items in the following sections must be checked: -- ✓ Scan Level and Resumability (v1.2.0) +- ✓ Scan Level and Resumability - ✓ Write-as-you-go Architecture - ✓ Batching Strategy (if deep/exhaustive scan) - ✓ Project Detection and Classification diff --git a/tools/cli/installers/lib/core/detector.js b/tools/cli/installers/lib/core/detector.js index a50c56e4..9bb73658 100644 --- a/tools/cli/installers/lib/core/detector.js +++ b/tools/cli/installers/lib/core/detector.js @@ -203,107 +203,17 @@ class Detector { } /** - * Detect legacy BMAD v4 footprints (case-sensitive path checks) - * V4 used _bmad-method as default folder name - * V6+ uses configurable folder names and ALWAYS has _config/manifest.yaml with installation.version + * Detect legacy BMAD v4 .bmad-method folder * @param {string} projectDir - Project directory to check * @returns {{ hasLegacyV4: boolean, offenders: string[] }} */ async detectLegacyV4(projectDir) { - // Helper: check if a directory is a V6+ installation - const isV6Installation = async (dirPath) => { - const manifestPath = path.join(dirPath, '_config', 'manifest.yaml'); - if (!(await fs.pathExists(manifestPath))) { - return false; - } - try { - const yaml = require('yaml'); - const manifestContent = await fs.readFile(manifestPath, 'utf8'); - const manifest = yaml.parse(manifestContent); - // V6+ manifest has installation.version - return manifest && manifest.installation && manifest.installation.version; - } catch { - return false; - } - }; - const offenders = []; - // Strategy: - // 1. First scan for ANY V6+ installation (_config/manifest.yaml) - // 2. If V6+ found → don't flag anything (user is already on V6+) - // 3. If NO V6+ found → flag folders with "bmad" in name as potential V4 legacy - - let hasV6Installation = false; - const potentialV4Folders = []; - - try { - const entries = await fs.readdir(projectDir, { withFileTypes: true }); - - for (const entry of entries) { - if (entry.isDirectory()) { - const name = entry.name; - const fullPath = path.join(projectDir, entry.name); - - // Check if directory is empty (skip empty leftover folders) - const dirContents = await fs.readdir(fullPath); - if (dirContents.length === 0) { - continue; // Skip empty folders - } - - // Check if it's a V6+ installation by looking for _config/manifest.yaml - // This works for ANY folder name (not just bmad-prefixed) - const isV6 = await isV6Installation(fullPath); - - if (isV6) { - // Found a V6+ installation - user is already on V6+ - hasV6Installation = true; - // Don't break - continue scanning to be thorough - } else { - // Not V6+, check if this is the exact V4 folder name "bmad-method" - if (name === 'bmad-method') { - // This is the V4 default folder - flag it as legacy - potentialV4Folders.push(fullPath); - } - } - } - } - } catch { - // Ignore errors reading directory - } - - // Only flag V4 folders if NO V6+ installation was found - if (!hasV6Installation && potentialV4Folders.length > 0) { - offenders.push(...potentialV4Folders); - } - - // Check inside various IDE command folders for legacy bmad folders - // V4 used folders like 'bmad-method' or custom names in IDE commands - // V6+ uses 'bmad' in IDE commands (hardcoded in IDE handlers) - // Legacy V4 IDE command folders won't have a corresponding V6+ installation - const ideConfigFolders = ['.opencode', '.claude', '.crush', '.continue', '.cursor', '.windsurf', '.cline', '.roo-cline']; - - for (const ideFolder of ideConfigFolders) { - const commandsDirName = ideFolder === '.opencode' ? 'command' : 'commands'; - const commandsPath = path.join(projectDir, ideFolder, commandsDirName); - if (await fs.pathExists(commandsPath)) { - try { - const commandEntries = await fs.readdir(commandsPath, { withFileTypes: true }); - for (const entry of commandEntries) { - if (entry.isDirectory()) { - const name = entry.name; - // V4 used 'bmad-method' or similar in IDE commands folders - // V6+ uses 'bmad' (hardcoded) - // So anything that's NOT 'bmad' but starts with bmad/Bmad is likely V4 - if ((name.startsWith('bmad') || name.startsWith('Bmad') || name === 'BMad') && name !== 'bmad') { - offenders.push(path.join(commandsPath, entry.name)); - } - } - } - } catch { - // Ignore errors reading commands directory - } - } + // Check for .bmad-method folder + const bmadMethodPath = path.join(projectDir, '.bmad-method'); + if (await fs.pathExists(bmadMethodPath)) { + offenders.push(bmadMethodPath); } return { hasLegacyV4: offenders.length > 0, offenders }; diff --git a/tools/cli/installers/lib/core/installer.js b/tools/cli/installers/lib/core/installer.js index bc85d2f2..816dbbbc 100644 --- a/tools/cli/installers/lib/core/installer.js +++ b/tools/cli/installers/lib/core/installer.js @@ -2152,90 +2152,59 @@ class Installer { } /** - * Handle legacy BMAD v4 migration with automatic backup - * @param {string} projectDir - Project directory - * @param {Object} legacyV4 - Legacy V4 detection result with offenders array + * Handle legacy BMAD v4 detection with simple warning + * @param {string} _projectDir - Project directory (unused in simplified version) + * @param {Object} _legacyV4 - Legacy V4 detection result (unused in simplified version) */ - async handleLegacyV4Migration(projectDir, legacyV4) { - console.log(chalk.yellow.bold('\n⚠️ Legacy BMAD v4 detected')); - console.log(chalk.dim('The installer found legacy artefacts in your project.\n')); - - // Separate _bmad* folders (auto-backup) from other offending paths (manual cleanup) - const bmadFolders = legacyV4.offenders.filter((p) => { - const name = path.basename(p); - return name.startsWith('_bmad'); // Only dot-prefixed folders get auto-backed up - }); - const otherOffenders = legacyV4.offenders.filter((p) => { - const name = path.basename(p); - return !name.startsWith('_bmad'); // Everything else is manual cleanup - }); - + async handleLegacyV4Migration(_projectDir, _legacyV4) { const inquirer = require('inquirer').default || require('inquirer'); - // Show warning for other offending paths FIRST - if (otherOffenders.length > 0) { - console.log(chalk.yellow('⚠️ Recommended cleanup:')); - console.log(chalk.dim('It is recommended to remove the following items before proceeding:\n')); - for (const p of otherOffenders) console.log(chalk.dim(` - ${p}`)); + console.log(''); + console.log(chalk.yellow.bold('⚠️ Legacy BMAD v4 detected')); + console.log(chalk.yellow('─'.repeat(80))); + console.log(chalk.yellow('Found .bmad-method folder from BMAD v4 installation.')); + console.log(''); - console.log(chalk.cyan('\nCleanup commands you can copy/paste:')); - console.log(chalk.dim('macOS/Linux:')); - for (const p of otherOffenders) console.log(chalk.dim(` rm -rf '${p}'`)); - console.log(chalk.dim('Windows:')); - for (const p of otherOffenders) console.log(chalk.dim(` rmdir /S /Q "${p}"`)); + console.log(chalk.dim('Before continuing with installation, we recommend:')); + console.log(chalk.dim(' 1. Remove the .bmad-method folder, OR')); + console.log(chalk.dim(' 2. Back it up by renaming it to another name (e.g., bmad-method-backup)')); + console.log(''); - const { cleanedUp } = await inquirer.prompt([ - { - type: 'confirm', - name: 'cleanedUp', - message: 'Have you completed the recommended cleanup? (You can proceed without it, but it is recommended)', - default: false, - }, - ]); + console.log(chalk.dim('If your v4 installation set up rules or commands, you should remove those as well.')); + console.log(''); - if (cleanedUp) { - console.log(chalk.green('✓ Cleanup acknowledged\n')); - } else { - console.log(chalk.yellow('⚠️ Proceeding without recommended cleanup\n')); - } + const { proceed } = await inquirer.prompt([ + { + type: 'list', + name: 'proceed', + message: 'What would you like to do?', + choices: [ + { + name: 'Exit and clean up manually (recommended)', + value: 'exit', + short: 'Exit installation', + }, + { + name: 'Continue with installation anyway', + value: 'continue', + short: 'Continue', + }, + ], + default: 'exit', + }, + ]); + + if (proceed === 'exit') { + console.log(''); + console.log(chalk.cyan('Please remove the .bmad-method folder and any v4 rules/commands,')); + console.log(chalk.cyan('then run the installer again.')); + console.log(''); + process.exit(0); } - // Handle _bmad* folders with automatic backup - if (bmadFolders.length > 0) { - console.log(chalk.cyan('The following legacy folders will be moved to v4-backup:')); - for (const p of bmadFolders) console.log(chalk.dim(` - ${p}`)); - - const { proceed } = await inquirer.prompt([ - { - type: 'confirm', - name: 'proceed', - message: 'Proceed with backing up legacy v4 folders?', - default: true, - }, - ]); - - if (proceed) { - const backupDir = path.join(projectDir, 'v4-backup'); - await fs.ensureDir(backupDir); - - for (const folder of bmadFolders) { - const folderName = path.basename(folder); - const backupPath = path.join(backupDir, folderName); - - // If backup already exists, add timestamp - let finalBackupPath = backupPath; - if (await fs.pathExists(backupPath)) { - const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').split('T')[0]; - finalBackupPath = path.join(backupDir, `${folderName}-${timestamp}`); - } - - await fs.move(folder, finalBackupPath, { overwrite: false }); - console.log(chalk.green(`✓ Moved ${folderName} to ${path.relative(projectDir, finalBackupPath)}`)); - } - } else { - throw new Error('Installation cancelled by user'); - } - } + console.log(''); + console.log(chalk.yellow('⚠️ Proceeding with installation despite legacy v4 folder')); + console.log(''); } /** From ea421adbf9ead6d0738157fa3b1ea190294bd29c Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sat, 27 Dec 2025 21:35:39 +0800 Subject: [PATCH 6/6] create and edit workflow minor fixes --- .../create-agent/steps/step-01-brainstorm.md | 2 +- .../templates/agent-plan.template.md | 2 + .../templates/expert-agent.template.md | 44 ++++++------------- .../templates/simple-agent.template.md | 34 ++++---------- .../create-workflow/steps/step-06-design.md | 4 +- .../create-workflow/steps/step-07-build.md | 16 ++++++- .../edit-workflow/steps/step-01-analyze.md | 9 ++-- .../bmb/workflows/edit-workflow/workflow.md | 2 +- 8 files changed, 47 insertions(+), 66 deletions(-) diff --git a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md b/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md index 909876a6..1ae2d6e7 100644 --- a/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md +++ b/src/modules/bmb/workflows/create-agent/steps/step-01-brainstorm.md @@ -90,7 +90,7 @@ Wait for clear user response (yes/no or y/n). - Load brainstorming workflow: `{brainstormWorkflow}` - Pass context data: `{brainstormContext}` -- Execute brainstorming session scoped specifically to brainstorming a new agent. +- Execute brainstorming session scoped specifically utilizing the brainstormContext to guide the scope and outcome - Capture all brainstorming output for next step - Return to this step after brainstorming completes diff --git a/src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md b/src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md index 8888bb7c..92b2d862 100644 --- a/src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md +++ b/src/modules/bmb/workflows/create-agent/templates/agent-plan.template.md @@ -1,3 +1,5 @@ --- stepsCompleted: [] --- + +# Agent Design and Build Plan diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md index 069512cc..02fa2e5c 100644 --- a/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md +++ b/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md @@ -28,28 +28,22 @@ Domain-specific agents with persistent memory, sidecar files, and restricted acc ```yaml agent: metadata: + id: _bmad/agents/{agent-name}/{agent-name}.md name: 'Persona Name' title: 'Agent Title' icon: 'emoji' - type: 'expert' + module: stand-alone # or module name persona: - role: 'Domain Expert with specialized capability' + role: | + First-person description of primary function (1-2 sentences) identity: | - Background and expertise in first-person voice. - {{#if user_preference}} - Customization based on install_config. - {{/if}} + Background, experience, specializations in first-person (2-3 sentences) communication_style: | - {{#if tone_style == "gentle"}} - Gentle and supportive communication... - {{/if}} - {{#if tone_style == "direct"}} - Direct and efficient communication... - {{/if}} - I reference past conversations naturally. + 1-2 short sentence describe how the agent speaks and communicates + principles: - Core belief about the domain @@ -89,29 +83,17 @@ agent: Reference stored information naturally. menu: - - trigger: action1 + - trigger: MF or fuzzy match on main function action: '#main-function' - description: 'Primary agent function' + description: '[MF] Main agent function' - - trigger: remember + - trigger: SM or fuzzy match on save-memory action: 'Update ./{agent-name}-sidecar/memories.md with session insights' - description: 'Save what we discussed today' + description: '[SM] Save memory what we discussed today' - - trigger: insight + - trigger: RI or fuzzy match on record-insight action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md' - description: 'Record a significant insight' - - - multi: "[DF] Do Foo or start [CH] Chat with expert" - triggers: - - do-foo - - input: [DF] or fuzzy match on do foo - - action: '#main-action' - - data: what is being discussed or suggested with the command, along with custom party custom agents if specified - - type: action - - expert-chat: - - input: [CH] or fuzzy match validate agent - - action: agent responds as expert based on its persona to converse - - type: action + description: '[RI] Record a significant insight' install_config: compile_time_only: true diff --git a/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md index e68a3c56..0a7108a4 100644 --- a/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md +++ b/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md @@ -18,7 +18,7 @@ agent: name: 'Persona Name' title: 'Agent Title' icon: 'emoji' - type: simple + module: stand-alone # or module name persona: role: | @@ -26,17 +26,9 @@ agent: identity: | Background, experience, specializations in first-person (2-5 sentences) - {{#if custom_variable}} - Conditional identity text based on install_config - {{/if}} communication_style: | - {{#if style_choice == "professional"}} - Professional and systematic approach... - {{/if}} - {{#if style_choice == "casual"}} - Friendly and approachable tone... - {{/if}} + 1-2 short sentence describe how the agent speaks and communicates principles: - Core belief or methodology @@ -58,26 +50,18 @@ agent: 3. Final step - - id: another-action + - id: foo-bar content: | Another reusable prompt template menu: - - trigger: inline - action: 'Direct inline prompt text' - description: 'Execute inline action' + - trigger: FB or fuzzy match on foo-bar + action: '#foo-bar' + description: '[FB] Foo Bar inline action' - - multi: "[DF] Do Foo or start [CH] Chat with expert" - triggers: - - do-foo - - input: [DF] or fuzzy match on do foo - - action: '#main-action' - - data: what is being discussed or suggested with the command, along with custom party custom agents if specified - - type: action - - expert-chat: - - input: [CH] or fuzzy match validate agent - - action: agent responds as expert based on its persona to converse - - type: action + - trigger: IA or fuzzy match on main-action + action: '#main-action' + description: '[IA] Execute inline action' install_config: compile_time_only: true diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md b/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md index e2a61532..90ae8b31 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-06-design.md @@ -96,9 +96,9 @@ Read: {project-root}/_bmad/bmb/docs/workflows/templates/step-1b-template.md This shows the continuation step pattern for workflows that might take multiple sessions. -Based on the approved plan, collaboratively design: +Based on the approved plan, collaboratively design the info to answer the following for the build plan: -- How many major steps does this workflow need? (Recommend 3-7) +- How many major steps does this workflow need? - What is the goal of each step? - Which steps are optional vs required? - Should any steps repeat or loop? diff --git a/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md b/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md index 9dab2ab7..85a844b8 100644 --- a/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md +++ b/src/modules/bmb/workflows/create-workflow/steps/step-07-build.md @@ -72,7 +72,7 @@ To generate all the workflow files (workflow.md, step files, templates, and supp - When building continuable step-01-init.md files, use template `{project-root}/_bmad/bmb/docs/workflows/templates/step-01-init-continuable-template.md` - When building continuation steps, use template `{project-root}/_bmad/bmb/docs/workflows/templates/step-1b-template.md` - When building the main workflow.md file, you must follow template `{project-root}/_bmad/bmb/docs/workflows/templates/workflow-template.md` -- Example step files from {project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition/workflow.md for patterns +- Example step files from {project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition/workflow.md for patterns - this is an idealized workflow so all files can give good insight into format and structure to be followed ## FILE GENERATION SEQUENCE: @@ -182,6 +182,20 @@ For document workflows: - Include all variables from design - Ensure variable naming consistency +Remember that the output format design we aligned on chose one of the following - and what it means practically when creating the workflow steps: +1. **Strict Template** - Must follow exact format with specific fields + 1. This is similar to the example where there are multiple template fragements that are specific with all fields to be in the final output. + 2. generally there will be 1 fragment to a step to complete in the overall template. +2. **Structured** - Required sections but flexible within each + 1. Usually there will just be one template file - and in this mode it lists out all the section headings (generally level 2 sections in the md) with a handlebars style placeholder for each section. + 2. Step files responsible for a specific section will upon user Continue of that step ensure output is written to the templates proper section +3. **Semi-structured** - Core sections plus optional additions + 1. Similar to the prior 2, but not all sections or content are listed in the template, some steps might offer various paths or options to go to different steps (or variance within a step) that can determine what sections end up in the final document +4. **Free-form** - Content-driven with minimal structure + 1. These are the easiest and most flexible. The single template usually only has the front matter fence with a stepsCompleted array and maybe some other fields, and outside of the front matter just the level 1 doc title + 2. With free form, any step that could produce content just appends to the end of the document, so its progressively build in the order of ste[s completed. + 3. Its good to have in this type of workflow a final polish output doc type step that cohesively can update the doc built up in this progressive manner, improving flow, reducing duplication, and ensure all information is aligned and where it belongs. + ### 6. Generate Supporting Files Based on design requirements: diff --git a/src/modules/bmb/workflows/edit-workflow/steps/step-01-analyze.md b/src/modules/bmb/workflows/edit-workflow/steps/step-01-analyze.md index 6fc65102..2dda91d6 100644 --- a/src/modules/bmb/workflows/edit-workflow/steps/step-01-analyze.md +++ b/src/modules/bmb/workflows/edit-workflow/steps/step-01-analyze.md @@ -127,7 +127,7 @@ Based on what the user wants to edit: #### Compliance Analysis -Load reference documentation as needed: +Load reference documentation to understand what ideal workflow files sound be when doing the review: - `{project-root}/_bmad/bmb/docs/workflows/architecture.md` - `{project-root}/_bmad/bmb/docs/workflows/templates/step-template.md` @@ -135,10 +135,9 @@ Load reference documentation as needed: Check against best practices: -- Step file size and structure -- Menu handling implementation -- Frontmatter variable usage -- Path reference consistency +- Step file size and structure (each step file 80-250 lines) +- Menu handling implementation (every menu item has a handler, and continue will only proceed after writes to output if applicable have completed) +- Frontmatter variable usage - no unused variables in the specific step front matter, and all files referenced in the file are done through a variable in the front matter ### 5. Present Analysis Findings diff --git a/src/modules/bmb/workflows/edit-workflow/workflow.md b/src/modules/bmb/workflows/edit-workflow/workflow.md index 1daaca4d..9eabd3e1 100644 --- a/src/modules/bmb/workflows/edit-workflow/workflow.md +++ b/src/modules/bmb/workflows/edit-workflow/workflow.md @@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution: Load and read full config from {project-root}/_bmad/bmb/config.yaml and resolve: -- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language` +- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder` ### 2. First Step EXECUTION