@devo-bmad-custom/agent-orchestration 1.0.0

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

@@ -0,0 +1,158 @@
+---
+name: 'step-01-mode-detection'
+description: 'Determine execution mode (tech-spec vs direct), handle escalation, set state variables'
+
+nextStepFile_modeA: './step-03-execute.md'
+nextStepFile_modeB: './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: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/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: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/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: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/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: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/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: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md`"
+- Mode B (direct, [E] selected): "**NEXT:** Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md`"
+- Escalation ([P] or [W]): "**EXITING Quick Dev.** Follow the directed workflow."
+
+---
+

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

@@ -0,0 +1,122 @@
+---
+name: "step-02-context-gathering"
+description: "Quick context gathering for direct mode - identify files, patterns, dependencies"
+
+nextStepFile: "./step-03-execute.md"
+---
+
+# Step 2: Context Gathering (Direct Mode)
+
+**Goal:** Quickly gather context for direct instructions - files, patterns, dependencies.
+
+**Note:** This step only runs for Mode B (direct instructions). If `{execution_mode}` is "tech-spec", this step was skipped.
+
+---
+
+## AVAILABLE STATE
+
+From step-01:
+
+- `{baseline_commit}` - Git HEAD at workflow start
+- `{execution_mode}` - Should be "direct"
+- `{project_context}` - Loaded if exists
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. Identify Files to Modify
+
+Based on user's direct instructions and confirmed documents:
+
+- **Review UX Design Document** — Search for `{planning_artifacts}/*ux*.md`. If found, read it to understand design intent, UI patterns, and interaction requirements.
+- Search for relevant implementation files using glob/grep
+- Identify the specific files that need changes
+- Note file locations and purposes
+
+### 2. Find Relevant Patterns
+
+Examine the identified files and their surroundings:
+
+- Code style and conventions used
+- Existing patterns for similar functionality
+- Import/export patterns
+- Error handling approaches
+- Test patterns (if tests exist nearby)
+
+### 3. Note Dependencies
+
+Identify:
+
+- External libraries used
+- Internal module dependencies
+- Configuration files that may need updates
+- Related files that might be affected
+
+### 4. Create Mental Plan
+
+Synthesize gathered context into:
+
+- List of tasks to complete
+- Acceptance criteria (inferred from user request)
+- Order of operations
+- Files to touch
+
+---
+
+## PRESENT PLAN AND PROCEED
+
+Display to user:
+
+```
+**Context Gathered:**
+
+**Files to modify:**
+- {list files}
+
+**Patterns identified:**
+- {key patterns}
+
+**Plan:**
+1. {task 1}
+2. {task 2}
+...
+
+**Inferred AC:**
+- {acceptance criteria}
+
+✅ Context mapped — moving to execution now.
+If you want to adjust the plan before I start, say so. Otherwise I'm proceeding.
+```
+
+> 💡 **Agile note — why we do this:** Context gathering is a time-boxed spike, not a planning ceremony. The goal is to identify the right files and patterns so execution is surgical. We don't need approval to start — just clarity on what we're changing.
+
+#### Auto-Proceed Rules:
+
+- **Proceed immediately** to Step 3 unless the user requests adjustments
+- If user says "adjust" or "wait" or similar: incorporate feedback, re-present summary, then proceed
+- If user asks questions: answer them, then proceed
+- **No y/n gate** — silence means go
+
+---
+
+## NEXT STEP DIRECTIVE
+
+**After presenting the plan, read fully and follow:** `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md`
+
+---
+
+## SUCCESS METRICS
+
+- Files to modify identified
+- Relevant patterns documented
+- Dependencies noted
+- Mental plan created with tasks and AC
+- Proceeding to execution without unnecessary confirmation
+
+## FAILURE MODES
+
+- Executing this step when Mode A (tech-spec)
+- Proceeding without identifying files to modify
+- Blocking on user confirmation when no adjustment is needed
+- Missing obvious patterns in existing code

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

@@ -0,0 +1,93 @@
+---
+name: 'step-03-execute'
+description: 'Execute implementation - iterate through tasks, write code, run tests'
+
+nextStepFile: './step-04-self-check.md'
+---
+
+# Step 3: Execute Implementation
+
+**Goal:** Implement all tasks, write tests, follow patterns, handle errors.
+
+**Critical:** Continue through ALL tasks without stopping for milestones.
+
+---
+
+## 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)
+- `{project_context}` - Project patterns (if exists)
+
+From context:
+
+- Mode A: Tasks and AC extracted from tech-spec
+- Mode B: Tasks and AC from step-02 mental plan
+
+---
+
+## EXECUTION LOOP
+
+For each task:
+
+### 1. Load Context
+
+- Read files relevant to this task
+- Review patterns from project-context or observed code
+- Understand dependencies
+
+### 2. Implement
+
+- Write code following existing patterns
+- Handle errors appropriately
+- Follow conventions observed in codebase
+- Add appropriate comments where non-obvious
+
+### 3. Test
+
+- Write tests if appropriate for the change
+- Run existing tests to catch regressions
+- Verify the specific AC for this task
+
+### 4. Mark Complete
+
+- Check off task: `- [x] Task N`
+- Continue to next task immediately
+
+---
+
+## HALT CONDITIONS
+
+**HALT and request guidance if:**
+
+- 3 consecutive failures on same task
+- Tests fail and fix is not obvious
+- Blocking dependency discovered
+- Ambiguity that requires user decision
+
+**Do NOT halt for:**
+
+- Minor issues that can be noted and continued
+- Warnings that don't block functionality
+- Style preferences (follow existing patterns)
+
+---
+
+## CONTINUOUS EXECUTION
+
+**Critical:** Do not stop between tasks for approval.
+
+- Execute all tasks in sequence
+- Only halt for blocking issues
+- Tests failing = fix before continuing
+- Track all completed work for self-check
+
+---
+
+## NEXT STEP
+
+When ALL tasks are complete (or halted on blocker), read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md`.
+

package/src/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md

@@ -0,0 +1,93 @@
+---
+name: 'step-04-self-check'
+description: 'Self-audit implementation against tasks, tests, AC, and patterns'
+
+nextStepFile: './step-05-adversarial-review.md'
+---
+
+# Step 4: Self-Check
+
+**Goal:** Audit completed work against tasks, tests, AC, and patterns before external review.
+
+---
+
+## 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)
+- `{project_context}` - Project patterns (if exists)
+
+---
+
+## SELF-CHECK AUDIT
+
+### 1. Tasks Complete
+
+Verify all tasks are marked complete:
+
+- [ ] All tasks from tech-spec or mental plan marked `[x]`
+- [ ] No tasks skipped without documented reason
+- [ ] Any blocked tasks have clear explanation
+
+### 2. Tests Passing
+
+Verify test status:
+
+- [ ] All existing tests still pass
+- [ ] New tests written for new functionality
+- [ ] No test warnings or skipped tests without reason
+
+### 3. Acceptance Criteria Satisfied
+
+For each AC:
+
+- [ ] AC is demonstrably met
+- [ ] Can explain how implementation satisfies AC
+- [ ] Edge cases considered
+
+### 4. Patterns Followed
+
+Verify code quality:
+
+- [ ] Follows existing code patterns in codebase
+- [ ] Follows project-context rules (if exists)
+- [ ] Error handling consistent with codebase
+- [ ] No obvious code smells introduced
+
+---
+
+## UPDATE TECH-SPEC (Mode A only)
+
+If `{execution_mode}` is "tech-spec":
+
+1. Load `{tech_spec_path}`
+2. Mark all tasks as `[x]` complete
+3. Update status to "Implementation Complete"
+4. Save changes
+
+---
+
+## IMPLEMENTATION SUMMARY
+
+Present summary to transition to review:
+
+```
+**Implementation Complete!**
+
+**Summary:** {what was implemented}
+**Files Modified:** {list of files}
+**Tests:** {test summary - passed/added/etc}
+**AC Status:** {all satisfied / issues noted}
+
+Proceeding to adversarial code review...
+```
+
+---
+
+## NEXT STEP
+
+Proceed immediately to `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md`.
+

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

@@ -0,0 +1,87 @@
+---
+name: 'step-05-adversarial-review'
+description: 'Construct diff and invoke adversarial review task'
+
+nextStepFile: './step-06-resolve-findings.md'
+---
+
+# Step 5: Adversarial Code Review
+
+**Goal:** Construct diff of all changes, invoke adversarial review task, present findings.
+
+---
+
+## AVAILABLE STATE
+
+From previous steps:
+
+- `{baseline_commit}` - Git HEAD at workflow start (CRITICAL for diff)
+- `{execution_mode}` - "tech-spec" or "direct"
+- `{tech_spec_path}` - Tech-spec file (if Mode A)
+
+---
+
+### 1. Construct Diff
+
+Build complete diff of all changes since workflow started.
+
+### If `{baseline_commit}` is a Git commit hash:
+
+**Tracked File Changes:**
+
+```bash
+git diff {baseline_commit}
+```
+
+**New Untracked Files:**
+Only include untracked files that YOU created during this workflow (steps 2-4).
+Do not include pre-existing untracked files.
+For each new file created, include its full content as a "new file" addition.
+
+### If `{baseline_commit}` is "NO_GIT":
+
+Use best-effort diff construction:
+
+- List all files you modified during steps 2-4
+- For each file, show the changes you made (before/after if you recall, or just current state)
+- Include any new files you created with their full content
+- Note: This is less precise than Git diff but still enables meaningful review
+
+### Capture as {diff_output}
+
+Merge all changes into `{diff_output}`.
+
+**Note:** Do NOT `git add` anything - this is read-only inspection.
+
+---
+
+### 2. Invoke Adversarial Review
+
+With `{diff_output}` constructed, load and follow the review task. If possible, use information asymmetry: load this step, and only it, in a separate subagent or process with read access to the project, but no context except the `{diff_output}`.
+
+```xml
+<invoke-task>Review {diff_output} 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 `{diff_output}` as the content.
+
+The task should: review `{diff_output}` and return a list of findings.
+
+---
+
+### 3. 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
+
+---
+
+## NEXT STEP
+
+With findings in hand, read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md` for user to choose resolution approach.
+

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
+
+> 💡 **Agile note — why we do this:** Adversarial review exists to catch what forward-looking implementation misses. Real findings are fixed before commit — this is the quality gate that keeps tech debt from compounding.
+
+**Default behavior: Auto-fix all findings classified as "real", then proceed.**
+
+Execute FIX AUTOMATICALLY section below immediately. Present the fix summary to the user.
+
+After fixing, display options for any remaining findings:
+
+**[W] Walk through** - Discuss remaining/skipped findings individually
+**[S] Skip** - Acknowledge remaining findings and proceed to commit
+
+> Only halt if the user invokes [W] or [S] in response to the summary. Silence means proceed.
+
+### EXECUTION RULES:
+
+- **Auto-fix "real" findings immediately** — do not ask permission
+- Only halt after presenting fix summary if user wants to walk through or skip remaining
+- "Noise" and "uncertain" findings are reported but not auto-fixed
+
+---
+
+## 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