bmad-method 6.0.0-alpha.9 → 6.0.2

package/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md

@@ -0,0 +1,146 @@
+---
+name: 'step-06-resolve-findings'
+description: 'Handle review findings interactively, apply fixes, update tech-spec with final status'
+---
+
+# Step 6: Resolve Findings
+
+**Goal:** Handle adversarial review findings interactively, apply fixes, finalize tech-spec.
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+- `{baseline_commit}` - Git HEAD at workflow start
+- `{execution_mode}` - "tech-spec" or "direct"
+- `{tech_spec_path}` - Tech-spec file (if Mode A)
+- Findings table from step-05
+
+---
+
+## RESOLUTION OPTIONS
+
+Present: "How would you like to handle these findings?"
+
+Display:
+
+**[W] Walk through** - Discuss each finding individually
+**[F] Fix automatically** - Automatically fix issues classified as "real"
+**[S] Skip** - Acknowledge and proceed to commit
+
+### Menu Handling Logic:
+
+- IF W: Execute WALK THROUGH section below
+- IF F: Execute FIX AUTOMATICALLY section below
+- IF S: Execute SKIP section below
+
+### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed when user makes a selection
+
+---
+
+## WALK THROUGH [W]
+
+For each finding in order:
+
+1. Present the finding with context
+2. Ask: **fix now / skip / discuss**
+3. If fix: Apply the fix immediately
+4. If skip: Note as acknowledged, continue
+5. If discuss: Provide more context, re-ask
+6. Move to next finding
+
+After all findings processed, summarize what was fixed/skipped.
+
+---
+
+## FIX AUTOMATICALLY [F]
+
+1. Filter findings to only those classified as "real"
+2. Apply fixes for each real finding
+3. Report what was fixed:
+
+```
+**Auto-fix Applied:**
+- F1: {description of fix}
+- F3: {description of fix}
+...
+
+Skipped (noise/uncertain): F2, F4
+```
+
+---
+
+## SKIP [S]
+
+1. Acknowledge all findings were reviewed
+2. Note that user chose to proceed without fixes
+3. Continue to completion
+
+---
+
+## UPDATE TECH-SPEC (Mode A only)
+
+If `{execution_mode}` is "tech-spec":
+
+1. Load `{tech_spec_path}`
+2. Update status to "Completed"
+3. Add review notes:
+   ```
+   ## Review Notes
+   - Adversarial review completed
+   - Findings: {count} total, {fixed} fixed, {skipped} skipped
+   - Resolution approach: {walk-through/auto-fix/skip}
+   ```
+4. Save changes
+
+---
+
+## COMPLETION OUTPUT
+
+```
+**Review complete. Ready to commit.**
+
+**Implementation Summary:**
+- {what was implemented}
+- Files modified: {count}
+- Tests: {status}
+- Review findings: {X} addressed, {Y} skipped
+
+{Explain what was implemented based on user_skill_level}
+```
+
+---
+
+## WORKFLOW COMPLETE
+
+This is the final step. The Quick Dev workflow is now complete.
+
+User can:
+
+- Commit changes
+- Run additional tests
+- Start new Quick Dev session
+
+---
+
+## SUCCESS METRICS
+
+- User presented with resolution options
+- Chosen approach executed correctly
+- Fixes applied cleanly (if applicable)
+- Tech-spec updated with final status (Mode A)
+- Completion summary provided
+- User understands what was implemented
+
+## FAILURE MODES
+
+- Not presenting resolution options
+- Auto-fixing "noise" or "uncertain" findings
+- Not updating tech-spec after resolution (Mode A)
+- No completion summary
+- Leaving user unclear on next steps

package/src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -0,0 +1,50 @@
+---
+name: quick-dev
+description: "Implement a Quick Tech Spec for small changes or features. Use when the user provides a quick tech spec and says 'implement this quick spec' or 'proceed with implementation of [quick tech spec]'"
+---
+
+# Quick Dev Workflow
+
+**Goal:** Execute implementation tasks efficiently, either from a tech-spec or direct user instructions.
+
+**Your Role:** You are an elite full-stack developer executing tasks autonomously. Follow patterns, ship code, run tests. Every response moves the project forward.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for focused execution:
+
+- Each step loads fresh to combat "lost in the middle"
+- State persists via variables: `{baseline_commit}`, `{execution_mode}`, `{tech_spec_path}`
+- Sequential progression through implementation phases
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `user_name`, `communication_language`, `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev`
+- `project_context` = `**/project-context.md` (load if exists)
+
+### Related Workflows
+
+- `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md`
+- `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md`
+- `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
+
+---
+
+## EXECUTION
+
+Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md` to begin the workflow.

package/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md

@@ -0,0 +1,189 @@
+---
+name: 'step-01-understand'
+description: 'Analyze the requirement delta between current state and what user wants to build'
+
+templateFile: '../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.
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## 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]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2)
+    - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3)
+    - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/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 `{implementation_artifacts}` 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
+
+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:**
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"
+
+b) **HALT and wait for user selection.**
+
+#### Menu Handling Logic:
+
+- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After A or P execution, return to this 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.

package/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md

@@ -0,0 +1,143 @@
+---
+name: 'step-02-investigate'
+description: 'Map technical constraints and anchor points within the codebase'
+
+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).
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## 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: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"
+
+**HALT and wait for user selection.**
+
+#### Menu Handling Logic:
+
+- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
+- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After A or P execution, return to this 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.

package/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md

@@ -0,0 +1,126 @@
+---
+name: 'step-03-generate'
+description: 'Build the implementation plan based on the technical mapping of constraints'
+
+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.
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## 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) **Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (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.