refactor(bmm): convert quick-dev workflow to sharded format with adversarial review

[alexeyv]

Summary

• Convert monolithic instructions.md to 6 modular step files for better maintainability
• Add review-adversarial-general.xml core task for adversarial code reviews
• Replace workflow.yaml with workflow.md for cleaner step navigation
• Add non-Git fallback for adversarial reviews when git is unavailable

Test plan

• Run npm test to verify all validations pass
• Test quick-dev workflow with a tech-spec to verify step execution
• Test adversarial review invocation

🤖 Generated with Claude Code

[alexeyv]

@CodeRabbit review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

Introduces a new adversarial review task configuration and a comprehensive six-step Quick Dev workflow. The workflow guides users through mode detection, context gathering, execution, self-checking, adversarial code review, and findings resolution. Replaces prior workflow YAML configuration with new step-based markdown documentation structure.

Changes

Cohort / File(s)	Summary
New Task Definition src/core/tasks/review-adversarial-general.xml	New XML task configuration for adversarial code review with skeptical reviewer persona, mandatory severity classification, and halt conditions for zero findings.
Quick-Dev Workflow Core src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md	New workflow entry-point documentation defining initialization, state variables (baseline_commit, execution_mode, tech_spec_path), configuration loading, and step sequencing.
Workflow Configuration src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml	Deleted workflow YAML config; replaced by markdown-based step architecture and state management.
Legacy Documentation src/modules/bmm/workflows/bmad-quick-flow/quick-dev/checklist.md, src/modules/bmm/workflows/bmad-quick-flow/quick-dev/instructions.md	Deleted legacy checklist and instructions documentation; superseded by new step-file structure.
Workflow Steps src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md, step-02-context-gathering.md, step-03-execute.md, step-04-self-check.md, step-05-adversarial-review.md, step-06-resolve-findings.md	Six new sequential step definitions: mode detection (tech-spec vs. direct), context gathering, implementation execution, self-audit, adversarial review using new task, and interactive findings resolution.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(bmgd): comprehensive BMGD module upgrade #1151: Adds quick-flow adversarial-review step that directly invokes the _bmad/core/tasks/review-adversarial-general.xml task newly introduced in this PR.

Suggested reviewers

• bmadcode
• pbean
• muratkeremozcan

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main refactoring effort: converting the monolithic quick-dev workflow into a modular sharded format and adding adversarial review capability.
Description check	✅ Passed	The description is directly related to the changeset, outlining key transformations: conversion to step files, new adversarial review task, workflow.yaml to workflow.md migration, and Git fallback handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

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

65-84: Consider clarifying escalation level calculation.

The escalation threshold section defines triggers and reducers, but the handling section references specific levels (0-2 vs 3+) without explaining how to calculate the escalation level number. Consider adding a brief note on how signals translate to levels, e.g., "Each trigger adds +1, each reducer subtracts -1" or similar.

src/core/tasks/review-adversarial-general.xml (2)

31-33: Output format may not match step-05 expectations.

Step 5 (step-05-adversarial-review.md, lines 79-82) expects findings with severity (Critical, High, Medium, Low) and validity (real, noise, undecided) classifications. However, this task's step 3 only specifies "Output findings as a Markdown list" without requiring these structured fields.

Consider adding explicit output format requirements:

Suggested format specification

     <step n="3" title="Present Findings">
-      <action>Output findings as a Markdown list</action>
+      <action>Output findings as a numbered Markdown list</action>
+      <action>For each finding, include: severity (Critical/High/Medium/Low), validity assessment (real/noise/undecided), and description</action>
     </step>

---

26-29: Consider flexibility in finding count requirement.

The mandate to "Find at least ten issues" may be overly prescriptive for small diffs or well-written code, potentially leading to forced low-quality findings. Consider allowing fewer findings for minimal changes while maintaining the skeptical posture.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 021936e and 577b071.

📒 Files selected for processing (11)

• src/core/tasks/review-adversarial-general.xml
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/checklist.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/instructions.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml

💤 Files with no reviewable changes (3)

• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/instructions.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/checklist.md

🧰 Additional context used

📓 Path-based instructions (1)

**/*

⚙️ CodeRabbit configuration file

**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:

<code changes>

Files:

• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md
• src/core/tasks/review-adversarial-general.xml
• src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

🔇 Additional comments (8)

src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md (1)

1-113: LGTM!

The self-check step is well-structured with clear audit criteria, consistent state variable references, and proper Mode A/B handling. The progression to step-05-adversarial-review.md is correctly documented.

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

1-120: LGTM!

Step 2 correctly scopes itself to Mode B (direct instructions) with appropriate state variables. The user confirmation flow (y/n/adjust) and next step directive are well-defined.

src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md (1)

1-113: LGTM!

The execution step provides clear guidance for both modes, with well-defined halt conditions and continuous execution requirements. The state variable handling is consistent with previous steps.

src/modules/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md (1)

1-51: LGTM!

The workflow entry document provides a clear architectural overview, proper initialization sequence, and correctly references the step-file architecture. State variable definitions align with all step files.

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

1-140: LGTM!

Step 6 provides comprehensive resolution options with appropriate safeguards (auto-fix only applies to "real" findings). The tech-spec finalization and completion output are well-structured. Correctly defined as the final workflow step.

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

1-106: LGTM overall!

The adversarial review step is well-designed with proper Git/non-Git fallback handling, clear task invocation with platform fallback, and comprehensive findings processing. The zero-findings halt condition aligns with the task definition.

---

60-71: No action needed. The task path in step-05-adversarial-review.md is correct for post-installation usage. The file exists at src/core/tasks/review-adversarial-general.xml and is installed to {project-root}/_bmad/core/tasks/ as expected during the NPM installation process.

Likely an incorrect or invalid review comment.

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

1-156: LGTM!

Step 1 provides robust mode detection with proper state variable initialization, Git/non-Git handling, and comprehensive escalation framework. The dual next-step paths (Mode A → step-03, Mode B → step-02) are correctly defined.

[alexeyv]

Re: CodeRabbit finding on review-adversarial-general.xml lines 31-33 (output format)

This is by design. The separation of concerns is intentional:

1. Task (review-adversarial-general.xml) runs with information asymmetry—no workflow context, just the diff. It outputs raw findings as a plain list (descriptions only).

2. Step 5 receives the raw findings and—having full workflow context—evaluates severity/validity, orders by severity, then numbers them.

This ensures the adversarial review is truly independent (no bias from knowing intent), while classification benefits from understanding what the implementation was supposed to achieve.

Addressed in 4d5eb5f: clarified the task objective and output format to explicitly state "descriptions only", and reordered step-05 instructions to make the evaluate → order → number sequence clear.

[alexeyv]

Re: CodeRabbit finding on lines 26-29 (ten finding minimum)

Keeping as-is. This is a generic adversarial review task—it may operate on code, specs, docs, or any artifact. There is no reliable way to scale the requirement with "diff size" when there may not be a diff at all.

The design preference is to over-produce findings. False positives get classified as "noise" in step 5 and the user quickly sorts them out in step 6. Under-producing risks missing real issues, which is worse than a few extra items to dismiss.

[bmadcode]

thanks @alexeyv !