doc: standardize quick-flow menu patterns to newer format (bmad-code-org#1388)

Update quick-spec and quick-dev workflow menus to match established standards:
- Uppercase all menu option letters ([A], [P], [C], [T], [E], [W], etc.)
- Add "Menu Handling Logic:" sections with IF/THEN structure
- Add "EXECUTION RULES:" sections with halt/wait behavior
- Add chat handling for checkpoint menus (A/P/C)
- Remove code blocks from Display patterns, use standard format
- Add header for adversarial review process block

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>

Author: 3 people

src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md

@@ -52,7 +52,7 @@ Analyze the user's input to determine mode:
 - Load the spec, extract tasks/context/AC
 - Set `{execution_mode}` = "tech-spec"
 - Set `{tech_spec_path}` = provided path
-- **NEXT:** Load `step-03-execute.md`
+- **NEXT:** Read fully and follow: `step-03-execute.md`
 
 **Mode B: Direct Instructions**
 
@@ -88,53 +88,73 @@ Use holistic judgment, not mechanical keyword matching.
 
 ### No Escalation (simple request)
 
-Present choice:
+Display: "**Select:** [T] Plan first (tech-spec) [E] Execute directly"
 
-```
-**[t] Plan first** - Create tech-spec then implement
-**[e] Execute directly** - Start now
-```
+#### Menu Handling Logic:
 
-- **[t]:** Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[e]:** Ask for any additional guidance, then **NEXT:** Load `step-02-context-gathering.md`
+- IF T: Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.**
+- IF E: Ask for any additional guidance, then **NEXT:** Read fully and follow: `step-02-context-gathering.md`
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed when user makes a selection
+
+---
 
 ### Escalation Triggered - Level 0-2
 
-```
-This looks like a focused feature with multiple components.
+Present: "This looks like a focused feature with multiple components."
+
+Display:
+
+**[T] Create tech-spec first** (recommended)
+**[W] Seems bigger than quick-dev** - Recommend the Full BMad Flow PRD Process
+**[E] Execute directly**
+
+#### Menu Handling Logic:
 
-**[t] Create tech-spec first** (recommended)
-**[w] Seems bigger than quick-dev** - Recommend the Full BMad Flow PRD Process
-**[e] Execute directly**
-```
+- IF T: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
+- IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
+- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `step-02-context-gathering.md`
 
-- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[w]:** Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
-- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed when user makes a selection
+
+---
 
 ### Escalation Triggered - Level 3+
 
-```
-This sounds like platform/system work.
+Present: "This sounds like platform/system work."
+
+Display:
+
+**[W] Start BMad Method** (recommended)
+**[T] Create tech-spec** (lighter planning)
+**[E] Execute directly** - feeling lucky
+
+#### Menu Handling Logic:
+
+- IF T: Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
+- IF W: Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
+- IF E: Ask for guidance, then **NEXT:** Read fully and follow: `step-02-context-gathering.md`
 
-**[w] Start BMad Method** (recommended)
-**[t] Create tech-spec** (lighter planning)
-**[e] Execute directly** - feeling lucky
-```
+#### EXECUTION RULES:
 
-- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[w]:** Direct user to run the PRD workflow instead. **EXIT Quick Dev.**
-- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed when user makes a selection
 
 ---
 
 ## NEXT STEP DIRECTIVE
 
 **CRITICAL:** When this step completes, explicitly state which step to load:
 
-- Mode A (tech-spec): "**NEXT:** Loading `step-03-execute.md`"
-- Mode B (direct, [e] selected): "**NEXT:** Loading `step-02-context-gathering.md`"
-- Escalation ([t] or [w]): "**EXITING Quick Dev.** Follow the directed workflow."
+- Mode A (tech-spec): "**NEXT:** read fully and follow: `step-03-execute.md`"
+- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `step-02-context-gathering.md`"
+- Escalation ([T] or [W]): "**EXITING Quick Dev.** Follow the directed workflow."
 
 ---
 

src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md

@@ -99,7 +99,7 @@ Ready to execute? (y/n/adjust)
 
 **CRITICAL:** When user confirms ready, explicitly state:
 
-- **y:** "**NEXT:** Loading `step-03-execute.md`"
+- **y:** "**NEXT:** Read fully and follow: `step-03-execute.md`"
 - **n/adjust:** Continue gathering context, then re-present plan
 
 ---

src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md

@@ -91,7 +91,7 @@ For each task:
 
 ## NEXT STEP
 
-When ALL tasks are complete (or halted on blocker), load `step-04-self-check.md`.
+When ALL tasks are complete (or halted on blocker), read fully and follow: `step-04-self-check.md`.
 
 ---
 

src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md

@@ -85,7 +85,7 @@ If TodoWrite or similar tool is available, turn each finding into a TODO, includ
 
 ## NEXT STEP
 
-With findings in hand, load `step-06-resolve-findings.md` for user to choose resolution approach.
+With findings in hand, read fully and follow: `step-06-resolve-findings.md` for user to choose resolution approach.
 
 ---
 

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

@@ -25,15 +25,24 @@ From previous steps:
 
 ## RESOLUTION OPTIONS
 
-Present choice to user:
+Present: "How would you like to handle these findings?"
 
-```
-How would you like to handle these findings?
+Display:
 
 **[1] Walk through** - Discuss each finding individually
 **[2] Auto-fix** - Automatically fix issues classified as "real"
 **[3] Skip** - Acknowledge and proceed to commit
-```
+
+### Menu Handling Logic:
+
+- IF 1: Execute OPTION 1 (Walk Through) below
+- IF 2: Execute OPTION 2 (Auto-fix) below
+- IF 3: Execute OPTION 3 (Skip) below
+
+### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed when user makes a selection
 
 ---
 

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

@@ -47,20 +47,20 @@ Hey {user_name}! Found a tech-spec in progress:
 
 Is this what you're here to continue?
 
-[y] Yes, pick up where I left off
-[n] No, archive it and start something new
+[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:**
+- **[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 `./step-04-review.md` (Step 4)
-- **[n] Archive and start fresh:**
+- **[N] Archive and start fresh:**
   - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`
 
 ### 1. Greet and Ask for Initial Request
@@ -162,19 +162,22 @@ b) **Report to user:**
 
 a) **Display menu:**
 
-```
-[a] Advanced Elicitation - dig deeper into requirements
-[c] Continue - proceed to next step
-[p] Party Mode - bring in other experts
-```
+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:
+#### 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: `{nextStepFile}`
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
 
-- **[a]**: Read fully and follow: `{advanced_elicitation}`, then return here and redisplay menu
-- **[c]**: Read fully and follow: `{nextStepFile}` (Map Technical Constraints)
-- **[p]**: Read fully and follow: `{party_mode_exec}`, then return here and redisplay menu
+- 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
 
 ---
 
@@ -186,4 +189,4 @@ b) **HALT and wait for user selection.**
 
 - [ ] WIP check performed FIRST before any greeting.
 - [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
-- [ ] User selected [c] to continue.
+- [ ] User selected [C] to continue.

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

@@ -115,21 +115,22 @@ Fill in:
 
 ### 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
-```
+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:
+#### 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: `{nextStepFile}`
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
 
-- **[a]**: Read fully and follow: `{advanced_elicitation}`, then return here and redisplay menu
-- **[c]**: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{nextStepFile}`
-- **[p]**: Read fully and follow: `{party_mode_exec}`, then return here and redisplay menu
+- 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
 
 ---
 

src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md

@@ -43,23 +43,24 @@ wipFile: '{implementation_artifacts}/tech-spec-wip.md'
 
 **Present review menu:**
 
-```
-[y] Approve - finalize the spec
-[c] Changes - request modifications
-[q] Questions - ask about any section
-[a] Advanced Elicitation - dig deeper before approving
-[p] Party Mode - get expert feedback before approving
-```
+Display: "**Select:** [Y] Approve [C] Changes [Q] Questions [A] Advanced Elicitation [P] Party Mode"
 
 **HALT and wait for user selection.**
 
-#### Menu Handling:
+#### Menu Handling Logic:
+
+- IF Y: Proceed to Section 3 (Finalize the Spec)
+- IF C: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
+- IF Q: Answer questions, then redisplay this menu
+- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
 
-- **[y]**: Proceed to Section 3 (Finalize the Spec)
-- **[c]**: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
-- **[q]**: Answer questions, then redisplay this menu
-- **[a]**: Read fully and follow: `{advanced_elicitation}`, then return here and redisplay menu
-- **[p]**: Read fully and follow: `{party_mode_exec}`, then return here and redisplay menu
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to finalize when user selects 'Y'
+- After other menu items execution, return to this menu
 
 ### 2. Handle Review Feedback
 
@@ -114,11 +115,11 @@ 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
+[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
 
 ---
 
@@ -135,14 +136,23 @@ This ensures the dev agent has clean context focused solely on implementation.
 
 b) **HALT and wait for user selection.**
 
-#### Menu Handling:
+#### Menu Handling Logic:
+
+- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF B: Load and execute `{quick_dev_workflow}` with the final spec file (warn: fresh context is better)
+- IF D: Exit workflow - display final confirmation and path to spec
+- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
+- IF R: Execute Adversarial Review (see below)
+- IF Any other comments or queries: respond helpfully then redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- After A, P, or R execution, return to this menu
+
+#### Adversarial Review [R] Process:
 
-- **[a]**: Read fully and follow: `{advanced_elicitation}`, then return here and redisplay menu
-- **[b]**: Read fully and follow: `{quick_dev_workflow}` with the final spec file (warn: fresh context is better)
-- **[d]**: Exit workflow - display final confirmation and path to spec
-- **[p]**: Read fully and follow: `{party_mode_exec}`, then return here and redisplay menu
-- **[r]**: Execute Adversarial Review:
-    1. **Invoke Adversarial Review Task**:
+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}`.
        <invoke-task>Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml</invoke-task>
        > **Platform fallback:** If task invocation not available, load the task file and follow its instructions inline, passing `{finalFile}` as the content.
@@ -161,7 +171,7 @@ b) **HALT and wait for user selection.**
 
 ### 5. Exit Workflow
 
-**When user selects [d]:**
+**When user selects [D]:**
 
 "**All done!** Your tech-spec is ready at:
 

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -47,7 +47,7 @@ This uses **step-file architecture** for disciplined execution:
 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)
+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, read fully and follow the next step file