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

name	description	workflow_path	thisStepFile	nextStepFile_modeA	nextStepFile_modeB
step-01-mode-detection	Determine execution mode (tech-spec vs direct), handle escalation, set state variables	{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev	./step-01-mode-detection.md	./step-03-execute.md	./step-02-context-gathering.md

Step 1: Mode Detection

Goal: Determine execution mode, capture baseline, handle escalation if needed.

---

STATE VARIABLES (capture now, persist throughout)

These variables MUST be set in this step and available to all subsequent steps:

• {baseline_commit} - Git HEAD at workflow start (or "NO_GIT" if not a git repo)
• {execution_mode} - "tech-spec" or "direct"
• {tech_spec_path} - Path to tech-spec file (if Mode A)

---

EXECUTION SEQUENCE

1. Capture Baseline

First, check if the project uses Git version control:

If Git repo exists (.git directory present or git rev-parse --is-inside-work-tree succeeds):

• Run git rev-parse HEAD and store result as {baseline_commit}

If NOT a Git repo:

• Set {baseline_commit} = "NO_GIT"

2. Load Project Context

Check if {project_context} exists (**/project-context.md). If found, load it as a foundational reference for ALL implementation decisions.

3. Parse User Input

Analyze the user's input to determine mode:

Mode A: Tech-Spec

• User provided a path to a tech-spec file (e.g., quick-dev tech-spec-auth.md)
• Load the spec, extract tasks/context/AC
• Set {execution_mode} = "tech-spec"
• Set {tech_spec_path} = provided path
• NEXT: Read fully and follow: step-03-execute.md

Mode B: Direct Instructions

• User provided task description directly (e.g., refactor src/foo.ts...)
• Set {execution_mode} = "direct"
• NEXT: Evaluate escalation threshold, then proceed

---

ESCALATION THRESHOLD (Mode B only)

Evaluate user input with minimal token usage (no file loading):

Triggers escalation (if 2+ signals present):

• Multiple components mentioned (dashboard + api + database)
• System-level language (platform, integration, architecture)
• Uncertainty about approach ("how should I", "best way to")
• Multi-layer scope (UI + backend + data together)
• Extended timeframe ("this week", "over the next few days")

Reduces signal:

• Simplicity markers ("just", "quickly", "fix", "bug", "typo", "simple")
• Single file/component focus
• Confident, specific request

Use holistic judgment, not mechanical keyword matching.

---

ESCALATION HANDLING

No Escalation (simple request)

Display: "Select: [P] Plan first (tech-spec) [E] Execute directly"

Menu Handling Logic:

• IF P: 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

Present: "This looks like a focused feature with multiple components."

Display:

[P] Plan first (tech-spec) (recommended) [W] Seems bigger than quick-dev - Recommend the Full BMad Flow PRD Process [E] Execute directly

Menu Handling Logic:

• IF P: 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

EXECUTION RULES:

• ALWAYS halt and wait for user input after presenting menu
• ONLY proceed when user makes a selection

---

Escalation Triggered - Level 3+

Present: "This sounds like platform/system work."

Display:

[W] Start BMad Method (recommended) [P] Plan first (tech-spec) (lighter planning) [E] Execute directly - feeling lucky

Menu Handling Logic:

• IF P: 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

EXECUTION RULES:

• 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: read fully and follow: step-03-execute.md"
• Mode B (direct, [E] selected): "NEXT: Read fully and follow: step-02-context-gathering.md"
• Escalation ([P] or [W]): "EXITING Quick Dev. Follow the directed workflow."

---

SUCCESS METRICS

• {baseline_commit} captured and stored
• {execution_mode} determined ("tech-spec" or "direct")
• {tech_spec_path} set if Mode A
• Project context loaded if exists
• Escalation evaluated appropriately (Mode B)
• Explicit NEXT directive provided

FAILURE MODES

• Proceeding without capturing baseline commit
• Not setting execution_mode variable
• Loading step-02 when Mode A (tech-spec provided)
• Attempting to "return" after escalation instead of EXIT
• No explicit NEXT directive at step completion