<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>


<command-name>/output-style</command-name>
            <command-message>output-style</command-message>
            <command-args>tts-summary</command-args>


<local-command-stdout>Set output style to tts-summary</local-command-stdout>


<command-message>bmad-bmm-quick-dev2</command-message>
<command-name>/bmad-bmm-quick-dev2</command-name>


IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev2/workflow.md, READ its entire contents and follow its directions exactly!


The user wants me to load and follow the quick-dev2 workflow. Let me read the workflow file.


Error: File does not exist. Note: your current working directory is /Users/alex/src/bmad/quick-flow-redesign.


     1→---
     2→name: quick-dev2
     3→description: 'Unified quick flow - clarify intent, plan, implement, review, present.'
     4→main_config: '{project-root}/_bmad/bmm/config.yaml'
     5→
     6→# Related workflows
     7→advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
     8→party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
     9→
    10→# Review building block
    11→adversarial_review_task: '{project-root}/_bmad/core/tasks/review-adversarial-general.xml'
    12→---
    13→
    14→# Quick Dev 2 Workflow
    15→
    16→**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow.
    17→
    18→**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal.
    19→
    20→---
    21→
    22→## READY FOR DEVELOPMENT STANDARD
    23→
    24→A specification is "Ready for Development" when:
    25→
    26→- **Actionable**: Every task has a file path and specific action.
    27→- **Logical**: Tasks ordered by dependency.
    28→- **Testable**: All ACs use Given/When/Then.
    29→- **Complete**: No placeholders or TBDs.
    30→- **Self-Contained**: A fresh agent can implement from the spec alone.
    31→
    32→---
    33→
    34→## WORKFLOW ARCHITECTURE
    35→
    36→This uses **step-file architecture** for disciplined execution:
    37→
    38→- **Micro-file Design**: Each step is self-contained and followed exactly
    39→- **Just-In-Time Loading**: Only load the current step file
    40→- **Sequential Enforcement**: Complete steps in order, no skipping
    41→- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
    42→- **Append-Only Building**: Build artifacts incrementally
    43→
    44→### Step Processing Rules
    45→
    46→1. **READ COMPLETELY**: Read the entire step file before acting
    47→2. **FOLLOW SEQUENCE**: Execute sections in order
    48→3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
    49→4. **LOAD NEXT**: When directed, read fully and follow the next step file
    50→
    51→### Critical Rules (NO EXCEPTIONS)
    52→
    53→- **NEVER** load multiple step files simultaneously
    54→- **ALWAYS** read entire step file before execution
    55→- **NEVER** skip steps or optimize the sequence
    56→- **ALWAYS** follow the exact instructions in the step file
    57→- **ALWAYS** halt at checkpoints and wait for human input
    58→
    59→---
    60→
    61→## INITIALIZATION SEQUENCE
    62→
    63→### 1. Configuration Loading
    64→
    65→Load and read full config from `{main_config}` and resolve:
    66→
    67→- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
    68→- `communication_language`, `document_output_language`, `user_skill_level`
    69→- `date` as system-generated current datetime
    70→- `project_context` = `**/project-context.md` (load if exists)
    71→- CLAUDE.md / memory files (load if exist)
    72→
    73→YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
    74→
    75→### 2. Paths
    76→
    77→- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev2`
    78→- `templateFile` = `{installed_path}/tech-spec-template.md`
    79→- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
    80→- `tasksDir` = `{implementation_artifacts}/tasks`
    81→
    82→### 3. First Step Execution
    83→
    84→Read fully and follow: `{installed_path}/steps/step-01-clarify-and-route.md` to begin the workflow.
    85→

---
name: quick-dev2
description: 'Unified quick flow - clarify intent, plan, implement, review, present.'
main_config: '{project-root}/_bmad/bmm/config.yaml'

# Related workflows
advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'

# Review building block
adversarial_review_task: '{project-root}/_bmad/core/tasks/review-adversarial-general.xml'
---

# Quick Dev 2 Workflow

**Goal:** Take a user request from intent through implementation, adversarial review, and PR creation in a single unified flow.

**Your Role:** You are an elite developer. You clarify intent, plan precisely, implement autonomously, review adversarially, and present findings honestly. Minimum ceremony, maximum signal.

---

## READY FOR DEVELOPMENT STANDARD

A specification is "Ready for Development" when:

- **Actionable**: Every task has a file path and specific action.
- **Logical**: Tasks ordered by dependency.
- **Testable**: All ACs use Given/When/Then.
- **Complete**: No placeholders or TBDs.
- **Self-Contained**: A fresh agent can implement from the spec alone.

---

## WORKFLOW ARCHITECTURE

This uses **step-file architecture** for disciplined execution:

- **Micro-file Design**: Each step is self-contained and followed exactly
- **Just-In-Time Loading**: Only load the current step file
- **Sequential Enforcement**: Complete steps in order, no skipping
- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
- **Append-Only Building**: Build artifacts incrementally

### Step Processing Rules

1. **READ COMPLETELY**: Read the entire step file before acting
2. **FOLLOW SEQUENCE**: Execute sections in order
3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
4. **LOAD NEXT**: When directed, read fully and follow the next step file

### Critical Rules (NO EXCEPTIONS)

- **NEVER** load multiple step files simultaneously
- **ALWAYS** read entire step file before execution
- **NEVER** skip steps or optimize the sequence
- **ALWAYS** follow the exact instructions in the step file
- **ALWAYS** halt at checkpoints and wait for human input

---

## INITIALIZATION SEQUENCE

### 1. Configuration Loading

Load and read full config from `{main_config}` and resolve:

- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
- `communication_language`, `document_output_language`, `user_skill_level`
- `date` as system-generated current datetime
- `project_context` = `**/project-context.md` (load if exists)
- CLAUDE.md / memory files (load if exist)

YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.

### 2. Paths

- `installed_path` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev2`
- `templateFile` = `{installed_path}/tech-spec-template.md`
- `wipFile` = `{implementation_artifacts}/tech-spec-wip.md`
- `tasksDir` = `{implementation_artifacts}/tasks`

### 3. First Step Execution

Read fully and follow: `{installed_path}/steps/step-01-clarify-and-route.md` to begin the workflow.


Now I need to follow the initialization sequence:

1. Load config from `{main_config}` which is `{project-root}/_bmad/bmm/config.yaml`
2. Resolve variables
3. Set paths
4. Load step-01

Let me load the config first, and also check for project-context.md.


Now I'll follow the initialization sequence. Let me load the config and check for project context files.


<tool_use_error>Sibling tool call errored</tool_use_error>


/Users/alex/src/bmad/quick-flow-redesign/docs/explanation/project-context.md
/Users/alex/src/bmad/quick-flow-redesign/docs/how-to/project-context.md


<tool_use_error>Directory does not exist: /Users/alex/src/bmad/quick-flow-redesign/_bmad. Note: your current working directory is /Users/alex/src/bmad/quick-flow-redesign.</tool_use_error>

Error: Directory does not exist: /Users/alex/src/bmad/quick-flow-redesign/_bmad. Note: your current working directory is /Users/alex/src/bmad/quick-flow-redesign.


No files found


The config.yaml referenced in the workflow (`{project-root}/_bmad/bmm/config.yaml`) doesn't exist. The workflow is in `src/bmm/workflows/bmad-quick-flow/quick-dev2/`. Let me check if there's a config file somewhere else in the bmm directory structure.


Bash

List bmm directory contents


agents
data
module-help.csv
module.yaml
teams
workflows


     1→code: bmm
     2→name: "BMad Method Agile-AI Driven-Development"
     3→description: "AI-driven agile development framework"
     4→default_selected: true # This module will be selected by default for new installations
     5→
     6→# Variables from Core Config inserted:
     7→## user_name
     8→## communication_language
     9→## document_output_language
    10→## output_folder
    11→
    12→project_name:
    13→  prompt: "What is your project called?"
    14→  default: "{directory_name}"
    15→  result: "{value}"
    16→
    17→user_skill_level:
    18→  prompt:
    19→    - "What is your development experience level?"
    20→    - "This affects how agents explain concepts in chat."
    21→  default: "intermediate"
    22→  result: "{value}"
    23→  single-select:
    24→    - value: "beginner"
    25→      label: "Beginner - Explain things clearly"
    26→    - value: "intermediate"
    27→      label: "Intermediate - Balance detail with speed"
    28→    - value: "expert"
    29→      label: "Expert - Be direct and technical"
    30→
    31→planning_artifacts: # Phase 1-3 artifacts
    32→  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
    33→  default: "{output_folder}/planning-artifacts"
    34→  result: "{project-root}/{value}"
    35→
    36→implementation_artifacts: # Phase 4 artifacts and quick-dev flow output
    37→  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
    38→  default: "{output_folder}/implementation-artifacts"
    39→  result: "{project-root}/{value}"
    40→
    41→project_knowledge: # Artifacts from research, document-project output, other long lived accurate knowledge
    42→  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
    43→  default: "docs"
    44→  result: "{project-root}/{value}"
    45→
    46→# Directories to create during installation (declarative, no code execution)
    47→directories:
    48→  - "{planning_artifacts}"
    49→  - "{implementation_artifacts}"
    50→  - "{project_knowledge}"
    51→

code: bmm
name: "BMad Method Agile-AI Driven-Development"
description: "AI-driven agile development framework"
default_selected: true # This module will be selected by default for new installations

# Variables from Core Config inserted:
## user_name
## communication_language
## document_output_language
## output_folder

project_name:
  prompt: "What is your project called?"
  default: "{directory_name}"
  result: "{value}"

user_skill_level:
  prompt:
    - "What is your development experience level?"
    - "This affects how agents explain concepts in chat."
  default: "intermediate"
  result: "{value}"
  single-select:
    - value: "beginner"
      label: "Beginner - Explain things clearly"
    - value: "intermediate"
      label: "Intermediate - Balance detail with speed"
    - value: "expert"
      label: "Expert - Be direct and technical"

planning_artifacts: # Phase 1-3 artifacts
  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
  default: "{output_folder}/planning-artifacts"
  result: "{project-root}/{value}"

implementation_artifacts: # Phase 4 artifacts and quick-dev flow output
  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
  default: "{output_folder}/implementation-artifacts"
  result: "{project-root}/{value}"

project_knowledge: # Artifacts from research, document-project output, other long lived accurate knowledge
  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
  default: "docs"
  result: "{project-root}/{value}"

# Directories to create during installation (declarative, no code execution)
directories:
  - "{planning_artifacts}"
  - "{implementation_artifacts}"
  - "{project_knowledge}"


The config.yaml doesn't exist yet for this project because it's not installed - this is the source repo for the BMAD method itself. The workflow references `{project-root}/_bmad/bmm/config.yaml` which would exist in a project that has BMAD installed.

Since this is the source repo and we're working on the quick-flow-redesign branch, I think the user wants to test/use the quick-dev2 workflow. But the config doesn't exist. Let me check for any existing config or experiment artifacts.


     1→# Quick-Flow Redesign — Session State (Compaction)
     2→
     3→## What This Is
     4→
     5→This is a compacted session state for the quick-flow redesign brainstorming/planning session. Read this file to resume the session with full context.
     6→
     7→## Artifacts
     8→
     9→- **Intent doc:** `_bmad-output/planning-artifacts/quick-flow-redesign-intent.md` — the original vision statement, approved by human
    10→- **Plan (current):** `_bmad-output/planning-artifacts/quick-flow-redesign-plan.md` — the implementation plan, iteratively refined through this session
    11→- **Analysis of old flows:** `/tmp/bmad-quick-flow-logs/analysis.md` — turn-by-turn analysis of what went wrong with the old quick-spec + quick-dev sessions
    12→- **Oscillation research:** `/tmp/agent-loop-oscillation-research.md` — deep research on agent loop oscillation, divergence, and mitigations (13 academic papers, production reports from Devin/Cursor/Claude Code/Codex)
    13→
    14→## Core Design Decisions (Settled)
    15→
    16→These are not up for debate — they were explicitly decided by the human:
    17→
    18→1. **North star: minimize human turns.** Everything serves this goal.
    19→2. **Unified flow replaces both quick-spec and quick-dev.** One session, one context.
    20→3. **Exactly two human checkpoints** for plan-code-review route: end of plan, end of review. Non-negotiable.
    21→4. **Plan is source code, implementation is a build artifact.** If the agent drifted from the spec, the spec wasn't precise enough — that's a spec defect.
    22→5. **Push is strictly prohibited by default.** Hard ban unless overridden in sidecar config. Human copy-pastes push command.
    23→6. **All remote VC operations (push, PR) live in step 5 only.** Step 3 is local-only.
    24→7. **No parallel task execution.** Race conditions are a hard taboo. Sequential only.
    25→8. **Generic flow first.** Platform-agnostic. CC-native variant is future work.
    26→9. **Don't prescribe how to capture intent.** Define exit criteria, not process. LLM knows how to ask questions from training.
    27→10. **Skill argument is the primary expression of intent.** Don't assume you start from zero.
    28→11. **When routing is ambiguous between one-shot and spec, default to spec.** Writing a spec for something trivial is less costly than one-shotting something complex.
    29→12. **Adversarial code review in context-free subagent is non-negotiable** even for trivial one-shot changes.
    30→13. **Spec loop hard cap: default 5, overridable in sidecar.**
    31→14. **`_bmad-output/wip.md`** (all lowercase) — parking lot for deferred findings and guiding principle breadcrumbs. Append-only, never auto-loaded.
    32→15. **Quick-flow is zero-dependency** — works with no project context files. But bootstraps/backfills context over time so it never asks the same question twice.
    33→16. **Task sharding uses BMAD sharded workflow pattern.** Sequence file robust against crashes. Generic flow uses files; CC-native uses TaskCreate/TaskGet.
    34→17. **Lists in prompts are examples, not exhaustive.** LLMs treat lists as exhaustive — be careful.
    35→18. **Positive Preservation when discarding code.** Extract "what worked well" as KEEP instructions before re-deriving. Prevents loss of emergent cleverness across spec-loop iterations.
    36→19. **Golden Examples in spec template are frozen after checkpoint 1.** Same treatment as Problem/Solution/Scope/Non-Goals.
    37→
    38→## Classification System
    39→
    40→Four categories for review findings:
    41→- **Spec** — root cause traces to the spec (wrong, vague, or insufficiently precise to prevent drift). Fix the spec, re-derive code.
    42→- **Patch** — code quality issue unrelated to the spec. Fix the code.
    43→- **Defer** — not worth blocking. Park in wip.md.
    44→- **Reject** — not a real finding.
    45→
    46→**Key classification behaviors:**
    47→- Two-pass: scan ALL findings for spec-class first. If any found and under iteration limit, fix them all, re-derive, re-review. Do NOT classify remaining findings — they're moot.
    48→- Only classify into patch/defer/reject when no spec-class findings remain (or iteration limit hit).
    49→- Low-confidence findings (can't confidently classify) go to the human at checkpoint 2 as the primary action item. Usually 1-3 items.
    50→
    51→## Review Architecture
    52→
    53→**Three roles, separated by design:**
    54→1. **Intent/Rules Auditor (Layer 1)** — receives spec + code + project rules. No conversation context. Checks functional correctness and rule adherence. Skipped for one-shot route.
    55→2. **Adversarial Code Reviewer (Layer 2)** — receives only diff + source code. Information-asymmetric by design. Non-negotiable for all routes including one-shot.
    56→3. **Classifier** — the implementor agent classifying external findings. Must NOT review (anchoring bias). But well-equipped to classify because outside findings break through the anchor.
    57→
    58→**Additional layers** extensible via sidecar config (security, accessibility, etc.).
    59→
    60→**Findings merge** uses existing BMAD dedup-reorder-classify pattern before classification.
    61→
    62→## Oscillation Mitigations (In Progress)
    63→
    64→The spec-loop is the highest-risk point. Research confirmed:
    65→- LLMs naturally converge to 2-period attractor cycles
    66→- Self-correction without external feedback often degrades performance
    67→- 37.6% increase in security vulnerabilities after just 5 iterations
    68→- "Spec-rewriting is the hardest case" — no stable external anchor when agent can modify both spec and implementation
    69→
    70→**Current mitigations in the plan:**
    71→- Hard iteration cap (default 5)
    72→- Frozen original intent as immutable reference (discussed but NOT yet written into the plan)
    73→
    74→**Mitigation under discussion:**
    75→- **Guardrails ratchet** (from Ralph Wiggum Loop literature) — each spec amendment appends a constraint documenting what was changed and why. Creates monotonically increasing constraints preventing revisiting known-bad states. Concrete and implementable. NOT yet written into the plan.
    76→
    77→## Task List — Discussion Items
    78→
    79→Discussion items from adversarial review of the plan. Status as of compaction:
    80→
    81→**Completed (resolved):**
    82→- #1 Token/cost/time budgets — context window + iteration cap are the practical mitigations. No other way in generic flow.
    83→- #2 merge-base hardcodes "main" — actionable. Implementation task #26 created.
    84→- #3 Migration path for WIP files — out of scope.
    85→- #4 Dry-run flag — out of scope.
    86→- #5 .gitignore for _bmad-output — out of scope.
    87→- #6 Routing is stochastic — acceptable. Checkpoint catches bad routing. No change needed.
    88→- #7 "Don't prescribe intent capture" is dangerous — rejected. Exit criteria are the guardrail.
    89→- #8 Autonomy between checkpoints risks divergence — rejected. Quick-flow is for small tasks. Argues against north star.
    90→
    91→**Resolved (session 2 — team-based discussion):**
    92→- #9 Spec-loop oscillation — **ACCEPT.** Three mitigations written into Phase C: (1) frozen intent sections (Problem/Solution/Scope/Non-Goals read-only after checkpoint 1, intent-class findings escalate to human), (2) guardrails ratchet (spec change log prevents revisiting known-bad states), (3) hard iteration cap (unchanged). New classification cascade: intent-class > spec-class > patch-class.
    93→- #10 Sequence file crash-proofing — **SKIP.** Plan is adequate as-is.
    94→- #11 Prompt growth — **SKIP.** Non-issue for quick-flow's small task scope.
    95→- #12 Resume logic — **ACCEPT.** Added clean-worktree precondition and resume policy to Step 3.
    96→- #13 Worktree edge cases — **SKIP.** "Detect and reuse" is sufficient.
    97→- #14 merge-base linear history — **REJECT.** Reviewer misunderstands how merge-base works.
    98→- #15 Push safety theater — **REJECT.** Settled decision #5.
    99→- #16 Auto-patch ACs — **SKIP.** Classification rigor is sufficient. Side finding: Layer 2 must use `review-adversarial-general.xml` (task #44).
   100→- #17 Blame the spec — **ACCEPT.** Added classifier framing to Phase B (spec-class as win, not blame).
   101→- #18 Over-classifies as spec-class — **SKIP.** Evidence requirement sufficient.
   102→- #19 Sidecar config drift — **DEFER.** Valid kernel, out of scope.
   103→- #20 Two checkpoints regression — **REJECT.** Settled decision #2.
   104→- #21 One-shot review collapse — **PARTIAL ACCEPT.** One-shot Layer 2 now receives user prompt alongside diff.
   105→- #22 Pause/resume protocol — **SKIP.** Crash recovery IS pause/resume.
   106→- #23 Edge cases (no git, etc.) — **SKIP.** Git is a prerequisite, not optional.
   107→- #24 Mandatory mitigations — **SKIP.** Plan already contains all prompt-level mitigations.
   108→
   109→**Resolved (session 3 — Grok party-mode cross-pollination):**
   110→- #28 Positive Preservation — **ACCEPT.** When the spec loop discards code, extract "what worked well" as KEEP instructions carried forward. Added to Phase C loop mechanics and change log format.
   111→- #29 Golden Examples — **ACCEPT.** Optional concrete input/output examples in spec template to anchor behavior. Frozen after checkpoint 1. Added to template.
   112→- #30 INTENT_GAP two-question test — **ACCEPT.** Formalized intent-class detection: (1) Can this be resolved from existing info? (2) Does it require a user-specific decision? If #2 = yes → INTENT_GAP. Added to Phase B first pass.
   113→- #31 Fresh Context Reset per spec-loop iteration — **OUT OF SCOPE.** Kept in mind for future work.
   114→- #32 CHANGE SCOPE / FORBIDDEN spec sections — **OUT OF SCOPE.** Kept in mind for future work.
   115→
   116→**Implementation tasks (all completed):**
   117→- #25 Apply all accepted findings to the plan file — **DONE**
   118→- #26 Update plan: integration branch from project context, not hardcoded "main" — **DONE**
   119→- #27 Update plan: default to spec route when ambiguous — **DONE**
   120→- #44 Update plan: Layer 2 must use `src/core/tasks/review-adversarial-general.xml` — **DONE**
   121→- #45 Update plan: Positive Preservation in Phase C + change log format — **DONE**
   122→- #46 Update plan: Golden Examples section in spec template (frozen after CP1) — **DONE**
   123→- #47 Update plan: INTENT_GAP two-question test in Phase B first pass — **DONE**
   124→
   125→## Key Reasoning to Preserve
   126→
   127→**Why plan is source code:** The spec is like source code, the agent is the compiler. If the compiler misunderstood your source, you write clearer source — even if it's arguably a compiler bug. You work around it because you control the spec, not the agent. Spec-class findings accumulate knowledge about what the "compiler" needs to not drift.
   128→
   129→**Why information asymmetry in review:** The best findings come from a reviewer that doesn't know the "why." If you know the same session concluded 2+2=5, you'll jump to the same conclusion. But if an outside finding says 2+2=4, you're well equipped to decide whether that matters. The agent that wrote the code must NOT review it (anchoring bias) but IS the right agent to classify external findings.
   130→
   131→**Why not prescribe intent capture:** Any list of "how to ask questions" competes with training and introduces gaps. Exit criteria define "done," not the path. The moment you write "first ask about X, then probe for Y" you're creating exactly the ambiguities you're trying to avoid.
   132→
   133→**Why no platform capability detection:** LLMs hallucinate about their own tooling to please you. The only reliable check is "are you Claude Code?" — and even that belongs in the CC-native variant, not the generic flow. The only capability the generic flow probes for is subagent support.
   134→
   135→**Why sequential task execution:** Race conditions on shared code are too risky. In this incarnation, parallel execution is a hard taboo. Future versions may relax this.
   136→

# Quick-Flow Redesign — Session State (Compaction)

## What This Is

This is a compacted session state for the quick-flow redesign brainstorming/planning session. Read this file to resume the session with full context.

## Artifacts

- **Intent doc:** `_bmad-output/planning-artifacts/quick-flow-redesign-intent.md` — the original vision statement, approved by human
- **Plan (current):** `_bmad-output/planning-artifacts/quick-flow-redesign-plan.md` — the implementation plan, iteratively refined through this session
- **Analysis of old flows:** `/tmp/bmad-quick-flow-logs/analysis.md` — turn-by-turn analysis of what went wrong with the old quick-spec + quick-dev sessions
- **Oscillation research:** `/tmp/agent-loop-oscillation-research.md` — deep research on agent loop oscillation, divergence, and mitigations (13 academic papers, production reports from Devin/Cursor/Claude Code/Codex)

## Core Design Decisions (Settled)

These are not up for debate — they were explicitly decided by the human:

1. **North star: minimize human turns.** Everything serves this goal.
2. **Unified flow replaces both quick-spec and quick-dev.** One session, one context.
3. **Exactly two human checkpoints** for plan-code-review route: end of plan, end of review. Non-negotiable.
4. **Plan is source code, implementation is a build artifact.** If the agent drifted from the spec, the spec wasn't precise enough — that's a spec defect.
5. **Push is strictly prohibited by default.** Hard ban unless overridden in sidecar config. Human copy-pastes push command.
6. **All remote VC operations (push, PR) live in step 5 only.** Step 3 is local-only.
7. **No parallel task execution.** Race conditions are a hard taboo. Sequential only.
8. **Generic flow first.** Platform-agnostic. CC-native variant is future work.
9. **Don't prescribe how to capture intent.** Define exit criteria, not process. LLM knows how to ask questions from training.
10. **Skill argument is the primary expression of intent.** Don't assume you start from zero.
11. **When routing is ambiguous between one-shot and spec, default to spec.** Writing a spec for something trivial is less costly than one-shotting something complex.
12. **Adversarial code review in context-free subagent is non-negotiable** even for trivial one-shot changes.
13. **Spec loop hard cap: default 5, overridable in sidecar.**
14. **`_bmad-output/wip.md`** (all lowercase) — parking lot for deferred findings and guiding principle breadcrumbs. Append-only, never auto-loaded.
15. **Quick-flow is zero-dependency** — works with no project context files. But bootstraps/backfills context over time so it never asks the same question twice.
16. **Task sharding uses BMAD sharded workflow pattern.** Sequence file robust against crashes. Generic flow uses files; CC-native uses TaskCreate/TaskGet.
17. **Lists in prompts are examples, not exhaustive.** LLMs treat lists as exhaustive — be careful.
18. **Positive Preservation when discarding code.** Extract "what worked well" as KEEP instructions before re-deriving. Prevents loss of emergent cleverness across spec-loop iterations.
19. **Golden Examples in spec template are frozen after checkpoint 1.** Same treatment as Problem/Solution/Scope/Non-Goals.

## Classification System

Four categories for review findings:
- **Spec** — root cause traces to the spec (wrong, vague, or insufficiently precise to prevent drift). Fix the spec, re-derive code.
- **Patch** — code quality issue unrelated to the spec. Fix the code.
- **Defer** — not worth blocking. Park in wip.md.
- **Reject** — not a real finding.

**Key classification behaviors:**
- Two-pass: scan ALL findings for spec-class first. If any found and under iteration limit, fix them all, re-derive, re-review. Do NOT classify remaining findings — they're moot.
- Only classify into patch/defer/reject when no spec-class findings remain (or iteration limit hit).
- Low-confidence findings (can't confidently classify) go to the human at checkpoint 2 as the primary action item. Usually 1-3 items.

## Review Architecture

**Three roles, separated by design:**
1. **Intent/Rules Auditor (Layer 1)** — receives spec + code + project rules. No conversation context. Checks functional correctness and rule adherence. Skipped for one-shot route.
2. **Adversarial Code Reviewer (Layer 2)** — receives only diff + source code. Information-asymmetric by design. Non-negotiable for all routes including one-shot.
3. **Classifier** — the implementor agent classifying external findings. Must NOT review (anchoring bias). But well-equipped to classify because outside findings break through the anchor.

**Additional layers** extensible via sidecar config (security, accessibility, etc.).

**Findings merge** uses existing BMAD dedup-reorder-classify pattern before classification.

## Oscillation Mitigations (In Progress)

The spec-loop is the highest-risk point. Research confirmed:
- LLMs naturally converge to 2-period attractor cycles
- Self-correction without external feedback often degrades performance
- 37.6% increase in security vulnerabilities after just 5 iterations
- "Spec-rewriting is the hardest case" — no stable external anchor when agent can modify both spec and implementation

**Current mitigations in the plan:**
- Hard iteration cap (default 5)
- Frozen original intent as immutable reference (discussed but NOT yet written into the plan)

**Mitigation under discussion:**
- **Guardrails ratchet** (from Ralph Wiggum Loop literature) — each spec amendment appends a constraint documenting what was changed and why. Creates monotonically increasing constraints preventing revisiting known-bad states. Concrete and implementable. NOT yet written into the plan.

## Task List — Discussion Items

Discussion items from adversarial review of the plan. Status as of compaction:

**Completed (resolved):**
- #1 Token/cost/time budgets — context window + iteration cap are the practical mitigations. No other way in generic flow.
- #2 merge-base hardcodes "main" — actionable. Implementation task #26 created.
- #3 Migration path for WIP files — out of scope.
- #4 Dry-run flag — out of scope.
- #5 .gitignore for _bmad-output — out of scope.
- #6 Routing is stochastic — acceptable. Checkpoint catches bad routing. No change needed.
- #7 "Don't prescribe intent capture" is dangerous — rejected. Exit criteria are the guardrail.
- #8 Autonomy between checkpoints risks divergence — rejected. Quick-flow is for small tasks. Argues against north star.

**Resolved (session 2 — team-based discussion):**
- #9 Spec-loop oscillation — **ACCEPT.** Three mitigations written into Phase C: (1) frozen intent sections (Problem/Solution/Scope/Non-Goals read-only after checkpoint 1, intent-class findings escalate to human), (2) guardrails ratchet (spec change log prevents revisiting known-bad states), (3) hard iteration cap (unchanged). New classification cascade: intent-class > spec-class > patch-class.
- #10 Sequence file crash-proofing — **SKIP.** Plan is adequate as-is.
- #11 Prompt growth — **SKIP.** Non-issue for quick-flow's small task scope.
- #12 Resume logic — **ACCEPT.** Added clean-worktree precondition and resume policy to Step 3.
- #13 Worktree edge cases — **SKIP.** "Detect and reuse" is sufficient.
- #14 merge-base linear history — **REJECT.** Reviewer misunderstands how merge-base works.
- #15 Push safety theater — **REJECT.** Settled decision #5.
- #16 Auto-patch ACs — **SKIP.** Classification rigor is sufficient. Side finding: Layer 2 must use `review-adversarial-general.xml` (task #44).
- #17 Blame the spec — **ACCEPT.** Added classifier framing to Phase B (spec-class as win, not blame).
- #18 Over-classifies as spec-class — **SKIP.** Evidence requirement sufficient.
- #19 Sidecar config drift — **DEFER.** Valid kernel, out of scope.
- #20 Two checkpoints regression — **REJECT.** Settled decision #2.
- #21 One-shot review collapse — **PARTIAL ACCEPT.** One-shot Layer 2 now receives user prompt alongside diff.
- #22 Pause/resume protocol — **SKIP.** Crash recovery IS pause/resume.
- #23 Edge cases (no git, etc.) — **SKIP.** Git is a prerequisite, not optional.
- #24 Mandatory mitigations — **SKIP.** Plan already contains all prompt-level mitigations.

**Resolved (session 3 — Grok party-mode cross-pollination):**
- #28 Positive Preservation — **ACCEPT.** When the spec loop discards code, extract "what worked well" as KEEP instructions carried forward. Added to Phase C loop mechanics and change log format.
- #29 Golden Examples — **ACCEPT.** Optional concrete input/output examples in spec template to anchor behavior. Frozen after checkpoint 1. Added to template.
- #30 INTENT_GAP two-question test — **ACCEPT.** Formalized intent-class detection: (1) Can this be resolved from existing info? (2) Does it require a user-specific decision? If #2 = yes → INTENT_GAP. Added to Phase B first pass.
- #31 Fresh Context Reset per spec-loop iteration — **OUT OF SCOPE.** Kept in mind for future work.
- #32 CHANGE SCOPE / FORBIDDEN spec sections — **OUT OF SCOPE.** Kept in mind for future work.

**Implementation tasks (all completed):**
- #25 Apply all accepted findings to the plan file — **DONE**
- #26 Update plan: integration branch from project context, not hardcoded "main" — **DONE**
- #27 Update plan: default to spec route when ambiguous — **DONE**
- #44 Update plan: Layer 2 must use `src/core/tasks/review-adversarial-general.xml` — **DONE**
- #45 Update plan: Positive Preservation in Phase C + change log format — **DONE**
- #46 Update plan: Golden Examples section in spec template (frozen after CP1) — **DONE**
- #47 Update plan: INTENT_GAP two-question test in Phase B first pass — **DONE**

## Key Reasoning to Preserve

**Why plan is source code:** The spec is like source code, the agent is the compiler. If the compiler misunderstood your source, you write clearer source — even if it's arguably a compiler bug. You work around it because you control the spec, not the agent. Spec-class findings accumulate knowledge about what the "compiler" needs to not drift.

**Why information asymmetry in review:** The best findings come from a reviewer that doesn't know the "why." If you know the same session concluded 2+2=5, you'll jump to the same conclusion. But if an outside finding says 2+2=4, you're well equipped to decide whether that matters. The agent that wrote the code must NOT review it (anchoring bias) but IS the right agent to classify external findings.

**Why not prescribe intent capture:** Any list of "how to ask questions" competes with training and introduces gaps. Exit criteria define "done," not the path. The moment you write "first ask about X, then probe for Y" you're creating exactly the ambiguities you're trying to avoid.

**Why no platform capability detection:** LLMs hallucinate about their own tooling to please you. The only reliable check is "are you Claude Code?" — and even that belongs in the CC-native variant, not the generic flow. The only capability the generic flow probes for is subagent support.

**Why sequential task execution:** Race conditions on shared code are too risky. In this incarnation, parallel execution is a hard taboo. Future versions may relax this.


     1→# Quick-Flow Redesign — Implementation Plan
     2→
     3→## Platform Strategy
     4→
     5→Two variants of the same flow, same design principles:
     6→
     7→- **Quick-flow (generic)** — this document. Platform-agnostic. File-based task sharding. The only capability question it may ask the platform is "can you use subagents?" (and even that took half a day to word correctly across platforms). Everything else is file-based.
     8→- **Quick-flow CC (future work)** — Claude Code-native. Uses TaskCreate/TaskGet for verbatim task prompt injection, proper context-isolated subagent spawning, and other platform-specific tooling. Same phases, same classification logic, native implementation.
     9→
    10→## Deliverable
    11→
    12→Replace `src/bmm/workflows/bmad-quick-flow/quick-spec/` and `src/bmm/workflows/bmad-quick-flow/quick-dev/` with a single unified `src/bmm/workflows/bmad-quick-flow/` workflow. Update the agent definition and Claude Code skill entry points accordingly. This spec covers the generic variant.
    13→
    14→## File Plan
    15→
    16→### Delete
    17→
    18→- `src/bmm/workflows/bmad-quick-flow/quick-spec/` (entire directory)
    19→- `src/bmm/workflows/bmad-quick-flow/quick-dev/` (entire directory)
    20→
    21→### Create
    22→
    23→```
    24→src/bmm/workflows/bmad-quick-flow/
    25→  workflow.md                     # Entry point — routing + orchestration
    26→  tech-spec-template.md           # Lighter-weight spec template (revised)
    27→  steps/
    28→    step-01-clarify-and-route.md  # Intent clarification + scope routing
    29→    step-02-plan.md               # Investigation + spec generation (CHECKPOINT 1)
    30→    step-03-implement.md          # Code derivation + auto version control
    31→    step-04-review.md             # Adversarial review + classification + optional spec loop
    32→    step-05-present.md            # Final findings to human (CHECKPOINT 2) + PR creation
    33→```
    34→
    35→### Modify
    36→
    37→- `src/bmm/agents/quick-flow-solo-dev.agent.yaml` — replace QS/QD menu triggers with single QF trigger
    38→- Claude Code skill entry points (if separate from agent definition)
    39→
    40→## Flow Architecture
    41→
    42→### Human Checkpoints
    43→
    44→Exactly two for the plan-code-review route:
    45→
    46→1. **End of Plan (step-02)** — "Here's the spec. Approve, edit, or redirect to full BMM."
    47→2. **End of Review (step-05)** — "Here are the classified findings. Approve the final state."
    48→
    49→Everything between checkpoint 1 and checkpoint 2 is autonomous. No [A][P][C] gates. Advanced Elicitation and Party Mode remain invocable by the human at any time (as interrupts, not as gates in the critical path) but the flow never stops to offer them.
    50→
    51→### Step 1 — Clarify and Route
    52→
    53→Combines the old quick-dev mode-detection with quick-spec's understand phase. Single step because the routing decision depends on understanding the intent.
    54→
    55→**On launch:**
    56→- Load config, project-context.md (if exists), CLAUDE.md / memory (if exists)
    57→- Check for existing WIP file → offer resume or archive
    58→- Check for `ready-for-dev` tech spec → skip directly to step 3 (this was a bug in the old flow)
    59→
    60→**Clarify intent:**
    61→- The skill argument, if present, is the primary expression of intent. Treat it as the human's opening statement of what they want — not background context, not a hint, the intent itself.
    62→- Intent may also come from other sources — resolvable references, prior conversation, existing WIP or ready-for-dev specs, or any other means. Do NOT assume you start from zero. Evaluate what's already known against the exit criteria below. If intent is already clear, don't ask.
    63→- Do NOT prescribe how to capture intent — the LLM knows how to ask clarifying questions, probe for ambiguity, and synthesize messy descriptions into clear ones. That's training. Telling it how to do what it already knows creates ambiguities and contradictions of its own.
    64→- Define **exit criteria for captured intent** — the agent's job is to reach this state, however it gets there:
    65→  - Problem statement is unambiguous
    66→  - Scope has clear boundaries
    67→  - No contradictions with loaded project context
    68→  - All blocking decisions are resolved (non-blocking ones can be deferred)
    69→  - The agent can explain back to the human what it's about to do
    70→- Investigate the codebase autonomously to understand scope (use subagents, don't ask the human to explain what's in their own codebase)
    71→- Ask the human about intent and constraints, not implementation details — and only if the exit criteria aren't already met
    72→
    73→**Backfill project context:**
    74→- If version control conventions are unknown (no project-context.md or no VC section in it), ask once and write to:
    75→  - `project-context.md` if it exists (append a Version Control section)
    76→  - `_bmad-output/project-context-quickflow.md` sidecar if it doesn't
    77→- Same for any other project convention the flow needs to operate autonomously
    78→
    79→**Route:**
    80→- **Full BMM** — scope too large or too ambiguous. Recommend and exit. Don't just warn, actually redirect.
    81→- **One-shot** — trivial change (< ~3 files, clear intent, no architectural decisions). Skip to step 3 with an in-session mental plan, no spec file. Still does auto VC and review, but review is collapsed: skip Layer 1 (intent audit — overkill for trivial changes, self-check covers it), keep Layer 2 (adversarial code review — **non-negotiable**, a one-line change can cause severe unintended consequences five modules away; receives the original user prompt alongside the diff to close the intent verification gap). Skip merge/dedup (single findings source). Classify directly against user prompt.
    82→- **Plan-code-review** — the main path. Proceed to step 2.
    83→- **When ambiguous between one-shot and plan-code-review, default to plan-code-review.** Writing a spec for something trivial is less costly than one-shotting something complex.
    84→
    85→### Step 2 — Plan
    86→
    87→Merges the old quick-spec steps 2-4 into a single autonomous phase. The agent does not stop between investigation, generation, and self-review.
    88→
    89→**Actions (autonomous, no checkpoints):**
    90→1. Deep investigation — read relevant code, identify patterns, understand constraints. Use subagents.
    91→2. Generate spec — tasks (file + action + rationale), acceptance criteria (Given/When/Then), technical decisions.
    92→3. Self-review — verify completeness against "Ready for Development" standard: actionable, logical, testable, complete, self-contained.
    93→4. Write spec to `{implementation_artifacts}/tech-spec-wip.md`.
    94→
    95→**CHECKPOINT 1 — Present spec to human.**
    96→- Show summary: task count, AC count, files affected, key decisions.
    97→- Options: approve / edit / redirect to full BMM.
    98→- On approve: rename to `tech-spec-{slug}.md`, set status `ready-for-dev`, proceed to step 3. **From this point forward, the spec's Problem, Solution, Scope, and Non-Goals sections are frozen** — the autonomous loop can only amend Tasks, Acceptance Criteria, and Technical Decisions. See step 4 Phase C for the frozen-section rule and escalation protocol.
    99→
   100→### Step 3 — Implement
   101→
   102→Merges old quick-dev steps 2-4 (context gathering, execute, self-check).
   103→
   104→**Actions (autonomous):**
   105→1. Capture baseline commit. For a fresh branch: `git rev-parse HEAD`. For a resumed WIP branch: `git merge-base HEAD <integration-branch>` to find the divergence point, where `<integration-branch>` is read from project-context.md (or sidecar), defaulting to `main` if unspecified. The baseline must produce a valid diff of all work on this branch, not just the current session.
   106→2. Create feature branch and worktree automatically. Branch name: user-specified (if provided in intent) > spec slug default. User-specified branch takes priority — supports incremental changes to existing feature branches. **Idempotent:** if branch/worktree already exist (e.g., resuming a WIP or working on an existing feature branch), detect and reuse them instead of failing on duplicate creation.
   107→3. **Assert clean working tree.** Before any task executes, verify no uncommitted changes or untracked files in the worktree. If the tree is dirty and this is a fresh start, surface to human and halt — something is wrong. If the tree is dirty and this is a resume, apply the resume policy (see below). This is a step-level precondition, not a per-task check.
   108→4. Load spec tasks using the **BMAD sharded workflow pattern** — the same mechanism used for the flow's own steps, applied to task execution. Study and faithfully reproduce the existing BMAD sharded step-file architecture:
   109→   - Each task is written to its own file (`_bmad-output/tasks/task-01.md`, etc.)
   110→   - A sequence file tracks execution order, status per task, and current position
   111→   - **The sequence file must be robust against partial execution failures or crashes.** Status is written to disk after each task completes, before the next begins. On resume, the sequence file is the source of truth — completed tasks are skipped, execution picks up at the first incomplete task. No in-memory-only state.
   112→   - Read each task file fresh before execution so the full prompt lands at the end of the context window (high-attention zone). This is the generic flow's primary defense against lost-in-the-middle syndrome.
   113→   - **Note:** A Claude Code-native variant (future work) will use TaskCreate/TaskGet/TaskUpdate for verbatim task prompt injection via platform tooling. The generic flow does not attempt to detect or use platform-specific task tracking — capability self-reporting is unreliable.
   114→5. Execute tasks strictly sequentially: load next task from task list (or read next file in fallback mode) so the full task prompt is at the end of the context window (high-attention zone) → implement → verify AC → mark complete → load next. **No parallel execution — race conditions on shared code are a hard taboo.**
   115→6. Self-check: all tasks done, ACs met, patterns followed.
   116→7. Commit automatically with a conventional commit message.
   117→8. Update spec with completion status.
   118→
   119→**Resume policy (dirty working tree on re-entry to step 3):**
   120→Because the clean-tree precondition guarantees the worktree was clean before implementation started, any uncommitted changes on resume are unambiguously from the crashed/interrupted task — identified by the sequence file's current position. The agent inspects the diff against that incomplete task: if the partial work is coherent and clearly progressing toward the task's goal, continue from where it left off; if the state is unclear or inconsistent, revert the uncommitted changes and re-execute the task from scratch. There are no per-task commits — the single commit at the end of step 3 (action 7) remains the only commit point.
   121→
   122→**Halt conditions (require human):**
   123→- 3 consecutive failures on same task
   124→- Blocking ambiguity the spec doesn't resolve
   125→- Test infrastructure missing or broken — **only if the spec relies on existing tests to verify ACs.** Does not apply when the task itself is to build or fix test infrastructure.
   126→
   127→**Version control in step 3 — local only:**
   128→- Branch naming: derived from spec slug (e.g., `feat/{slug}`)
   129→- Worktree: created at start, used for all changes
   130→- Commits: automatic, conventional format
   131→- **No push, no PR, no push prompts.** All remote operations live strictly in step 5 after review patches are applied.
   132→
   133→### Step 4 — Review and Classify
   134→
   135→Merges old quick-dev steps 5-6 with a new classification system.
   136→
   137→**Phase A — Multi-Layer Review:**
   138→
   139→Two default review layers, both in isolated subagents with no conversation context or implementation reasoning. Extensible via sidecar config.
   140→
   141→**Layer 1 — Intent/Rules Audit:**
   142→- Receives: the spec (or original user prompt for one-shot), the code artifact, and any project rules/guidelines (CLAUDE.md, project-context.md, etc.)
   143→- Does NOT receive: conversation context, implementation reasoning, or the "how we got here" narrative
   144→- Checks: does the output match the intent? Were project rules and guidelines followed?
   145→- This is the functional correctness check. It catches "perfectly clean code that does the wrong thing" — the gap that self-check covers poorly due to anchoring bias.
   146→
   147→**Layer 2 — Adversarial Code Review:**
   148→- Invokes `src/core/tasks/review-adversarial-general.xml` — the existing BMAD standard building block for adversarial review — with the diff as the content input. Context isolation is about what the subagent receives, not the review procedure itself.
   149→- Receives: the diff and access to source code. **One-shot exception:** also receives the original user prompt, closing the intent verification gap without adding Layer 1. The information-asymmetry design (no spec, no conversation context) still holds for the plan-code-review route; one-shot needs the user prompt because there is no other intent artifact.
   150→- Does NOT receive (plan-code-review route): the spec, intent, rules, or conversation context
   151→- Free-form reasoning about code quality — patterns, edge cases, error handling, style
   152→- Information-asymmetric by design. Its value comes from having zero expectations.
   153→
   154→**Additional layers (optional, user-configured via sidecar):**
   155→- Security review, accessibility audit, rules-specific deep check, etc.
   156→- The default two layers are the lowest common denominator — works well for small projects, better than nothing for real work. Real projects should invest in customizing and adding layers.
   157→
   158→Both layers produce raw findings lists. Before classification in Phase B, findings are merged using the existing BMAD pattern (from quick-dev/code-review flow): deduplicate, reorder by severity, then classify. Same mechanism, not a new invention.
   159→
   160→**Phase B — Evidence-Based Classification:**
   161→- The orchestrating agent (which knows the spec and intent) classifies each finding.
   162→- **Classifier framing:** The classifier does not own the code — the code is a build artifact derived from the spec. The classifier owns the *spec*. A spec-class finding is the most valuable outcome: it means the spec gets stronger and future derivations improve. Frame spec-class discovery as a win, not a failure. This framing reduces anchoring bias by decoupling the classifier's evaluation from self-critique of its own implementation.
   163→- Classification uses a **priority cascade: intent-class > spec-class > patch-class.** If a review round produces findings at multiple levels, resolve from the top down. Intent-class findings go to the human first. After intent is resolved, re-evaluate spec-class findings against the new or confirmed intent — some may be moot. Then amend the spec incorporating still-valid spec findings. This extends the two-pass principle with one more level.
   164→  - **First pass:** scan all findings for intent-class issues using the **INTENT_GAP two-question test.** For each finding, the classifier asks: (1) Can this issue be resolved using only the information already present in the original user request + current spec? (2) Does fixing it require a user-specific decision or preference that cannot reasonably be guessed? If #2 = yes → **intent-class (INTENT_GAP).** Generate one clear, targeted question and escalate to the human at the next checkpoint. A finding is also intent-class if its root cause traces to a frozen section of the spec (Problem, Solution, Scope, or Non-Goals — see Phase C for the frozen-section rule). Both paths require human resolution before anything else proceeds.
   165→  - **Second pass:** scan remaining findings for spec-class issues. For each finding, ask: "Does the root cause trace to the mutable spec surface?" Collect all that do.
   166→  - **If any spec-class findings exist and under iteration limit:** fix them all in the spec, re-derive code, re-review. Do NOT classify remaining findings into patch/defer/reject — they are moot and will be re-evaluated against fresh code.
   167→  - **If no spec-class findings (or iteration limit reached):** proceed to full classification of all findings into patch/defer/reject.
   168→- For each finding, the classifier asks: "Is this a real problem, and if so, what is the root cause?"
   169→  - **Root cause traces to frozen intent** (the Problem, Solution, Scope, or Non-Goals are wrong, contradictory, or incomplete) → **intent class.** Only the human can resolve this. Escalate with a recommended resolution — not a raw finding dump. See Phase C.
   170→  - **Root cause traces to the mutable spec surface** (Tasks, Acceptance Criteria, or Technical Decisions are wrong, vague, or insufficiently precise to prevent agent drift) → **spec class.** If the agent drifted from the spec, the spec was not precise enough — that is a spec defect, not an implementation defect. Point to the specific spec section that failed.
   171→  - **Code quality issue unrelated to the spec** (the spec had nothing to say about this and shouldn't have — e.g., a missed edge case in error handling, a style issue, a performance concern) → **patch class.** Fix the code in place.
   172→  - **Not worth blocking on → defer class.** Append to `_bmad-output/wip.md` with context. If it suggests a guiding principle needs updating, note that too.
   173→  - **Not a real finding → reject class.**
   174→
   175→**Phase C — Spec Loop (optional, autonomous, rigidly bounded):**
   176→
   177→The spec loop is the highest-risk point in the entire flow for infinite token burn, oscillation, and divergence from original human intent. Three mechanisms work together to bound it: frozen intent sections, a spec change log, and a hard iteration cap.
   178→
   179→**Frozen intent sections:** After checkpoint 1, the spec's Problem, Solution, Scope, and Non-Goals sections are frozen — read-only for the autonomous loop. The mutable surface for autonomous spec amendments is limited to Tasks, Acceptance Criteria, and Technical Decisions. This partitions the spec into human-owned intent (stable anchor) and agent-owned derivation (amendable). If a finding's root cause traces to a frozen section, it is intent-class: escalate to the human with a recommended resolution (not just a raw finding dump). The human confirms, edits, or rejects the recommendation. Only the human can authorize changes to frozen sections. The loop continues after intent-class findings are resolved.
   180→
   181→**Spec change log (guardrails ratchet):** Each spec amendment appends to a change log embedded in the spec: what changed, what finding triggered the change, and what known-bad state the change avoids. Subsequent iterations must read the log before amending. A previous fix cannot be undone without contradicting a logged constraint — the log is append-only and acts as a monotonically increasing set of constraints. This prevents 2-period attractor cycles where the agent oscillates between two states, each "fixing" the other.
   182→
   183→**Positive Preservation:** Before discarding code from a failed iteration, the agent extracts "what worked well" — specific implementations, patterns, or solutions that were correct and effective — and records them as explicit KEEP instructions in the change log alongside the amendment. These KEEP instructions are carried forward into the next iteration's context as positive constraints: the re-derived code must preserve these behaviors. This prevents the loop from losing emergent cleverness when it fixes a spec defect — the good parts survive the rewrite.
   184→
   185→**Loop mechanics:**
   186→- If there are spec-class findings with high confidence:
   187→  - Read the change log (if any previous iterations exist)
   188→  - **Extract Positive Preservation:** identify what worked well in the current code before discarding it. Record as KEEP instructions.
   189→  - Amend the mutable spec surface to resolve the findings, respecting all logged constraints (including KEEP instructions from previous iterations)
   190→  - Append each amendment to the change log with its triggering finding, the state it avoids, and any KEEP instructions extracted
   191→  - Re-derive the affected code (respecting KEEP instructions)
   192→  - Re-run adversarial review on the new diff
   193→  - Re-classify using the full priority cascade (intent > spec > patch)
   194→  - Repeat until no more spec-class findings
   195→- If an iteration produces intent-class findings, pause the loop and escalate to the human. Resume after the human resolves intent.
   196→- If confidence is not high enough to loop autonomously, include spec-class findings in the presentation to the human.
   197→- **Hard iteration cap: default 5, overridable in quickflow sidecar config.** When the cap is hit, stop unconditionally and present everything to the human. No exceptions.
   198→
   199→**Phase D — Apply patches:**
   200→- Auto-fix all patch-class findings.
   201→- Commit the fixes.
   202→
   203→### Step 5 — Present to Human
   204→
   205→**CHECKPOINT 2 — Show classified findings list.**
   206→
   207→The flow auto-handles everything it's confident about before reaching this point. The human's primary job here is the **low-confidence bucket** — findings where the classifier was not confident enough to assign a class (weak/no evidence from spec, ambiguous rule match, borderline real issue). Usually 1-3 items max. The human classifies each in seconds: spec (update spec + regen) / patch (auto-fix) / defer (to wip.md) / reject.
   208→
   209→Present:
   210→- **Intent-class findings (requiring human decision on frozen sections)** — highest priority, if any were escalated during the spec loop
   211→- **Low-confidence findings (requiring human classification)** — the primary action item for routine runs
   212→- Spec-class findings (if any remain unresolved or were looped) — for awareness
   213→- Patch-class findings (already fixed) — for awareness
   214→- Defer-class findings (parked in wip.md) — for awareness
   215→- Reject-class findings (shown briefly) — for transparency
   216→- Overall summary: what changed, what was reviewed, what was parked, spec change log (if any iterations occurred)
   217→
   218→**Human options:**
   219→- Approve → create PR automatically, print push command
   220→- Adjust → modify specific findings or request changes
   221→- Reject → explain what's wrong, loop back to relevant phase
   222→
   223→**After approval:**
   224→- Commit any remaining review patches (if not already committed in Phase D).
   225→- **Push: strictly prohibited by default.** Print the command, wait for human confirmation. Overridable in quickflow sidecar config (`auto_push: true`), but if not explicitly overridden, this is a hard ban — no exceptions, no "just this once."
   226→- Wait for human to confirm push is done (or auto-push if overridden).
   227→- Create PR via `gh pr create` with summary derived from spec + findings.
   228→- Flow complete.
   229→
   230→## Tech-Spec Template (Revised)
   231→
   232→Lighter than the current template. Drops the verbose frontmatter in favor of essentials.
   233→
   234→```markdown
   235→---
   236→title:
   237→slug:
   238→created:
   239→status: in-progress | ready-for-dev | implementing | complete
   240→---
   241→
   242→# {title}
   243→
   244→## Problem
   245→One paragraph.
   246→
   247→## Solution
   248→One paragraph.
   249→
   250→## Scope
   251→What's in, what's out.
   252→
   253→## Non-Goals
   254→What this spec explicitly does not address. Optional but recommended — frozen after checkpoint 1 alongside Problem, Solution, and Scope.
   255→
   256→## Tasks
   257→- [ ] Task 1: {file} — {action} — {rationale}
   258→- [ ] Task 2: ...
   259→
   260→## Acceptance Criteria
   261→- [ ] AC 1: Given {X}, when {Y}, then {Z}
   262→- [ ] AC 2: ...
   263→
   264→## Technical Decisions
   265→Only if non-obvious. Brief.
   266→
   267→## Golden Examples
   268→Optional. Concrete input/output pairs that anchor expected behavior. When the spec describes a transformation, algorithm, or interface, examples make the intent unambiguous where prose alone leaves room for interpretation. Frozen after checkpoint 1 (same as Problem/Solution/Scope).
   269→
   270→## Spec Change Log
   271→Appended by the review loop. Each entry: what changed, what finding triggered it, what known-bad state it avoids, and any KEEP instructions (positive preservation — what worked well and must survive the rewrite). Empty until step 4.
   272→
   273→## Notes
   274→Anything else. Optional.
   275→```
   276→
   277→## Parking Lot File
   278→
   279→`_bmad-output/wip.md` — created on first defer-class finding, appended thereafter.
   280→
   281→```markdown
   282→# Parking Lot
   283→
   284→## {date} — {spec-title}
   285→
   286→- **Finding:** {description}
   287→  **Context:** {why it was deferred}
   288→  **Guiding principle note:** {if applicable — which principle might need updating}
   289→```
   290→
   291→## Version Control Context
   292→
   293→On first run without VC conventions, the flow asks:
   294→- Branch naming convention? (e.g., `feat/`, `fix/`, free-form)
   295→- Commit message convention? (conventional commits, free-form, etc.)
   296→- PR target? (branch name, fork vs same-repo)
   297→- Worktree usage? (if applicable to the environment)
   298→
   299→Writes answers to project-context.md (or sidecar). Never asks again.
   300→
   301→## Open Questions
   302→
   303→1. ~~**Spec loop bound**~~ — Resolved. Hard cap of 5 iterations, overridable in quickflow sidecar. Default to stop and present.
   304→2. ~~**One-shot route review**~~ — Resolved. One-shot still gets the full review pipeline. Phase A (adversarial code review) works as-is. Phase B (classification) validates against the initial user prompt instead of a spec file — same evidence-based approach, lighter reference artifact.
   305→3. ~~**Task list integration**~~ — Resolved. Generic flow uses file-based task sharding (read each task file fresh before execution). Claude Code-native variant (future work) will use TaskCreate/TaskGet for verbatim injection. Platform capability self-reporting is unreliable — the generic flow doesn't try to detect it. The only capability it may probe for is subagent support.
   306→   - Execution is strictly sequential — load next task, execute, mark complete, load next
   307→   - Full task prompt must be at the end of the context window (high-attention zone) when execution begins
   308→   - **No parallel execution.** Race conditions on shared code are too risky. Sequential only in this incarnation.
   309→

# Quick-Flow Redesign — Implementation Plan

## Platform Strategy

Two variants of the same flow, same design principles:

- **Quick-flow (generic)** — this document. Platform-agnostic. File-based task sharding. The only capability question it may ask the platform is "can you use subagents?" (and even that took half a day to word correctly across platforms). Everything else is file-based.
- **Quick-flow CC (future work)** — Claude Code-native. Uses TaskCreate/TaskGet for verbatim task prompt injection, proper context-isolated subagent spawning, and other platform-specific tooling. Same phases, same classification logic, native implementation.

## Deliverable

Replace `src/bmm/workflows/bmad-quick-flow/quick-spec/` and `src/bmm/workflows/bmad-quick-flow/quick-dev/` with a single unified `src/bmm/workflows/bmad-quick-flow/` workflow. Update the agent definition and Claude Code skill entry points accordingly. This spec covers the generic variant.

## File Plan

### Delete

- `src/bmm/workflows/bmad-quick-flow/quick-spec/` (entire directory)
- `src/bmm/workflows/bmad-quick-flow/quick-dev/` (entire directory)

### Create

```
src/bmm/workflows/bmad-quick-flow/
  workflow.md                     # Entry point — routing + orchestration
  tech-spec-template.md           # Lighter-weight spec template (revised)
  steps/
    step-01-clarify-and-route.md  # Intent clarification + scope routing
    step-02-plan.md               # Investigation + spec generation (CHECKPOINT 1)
    step-03-implement.md          # Code derivation + auto version control
    step-04-review.md             # Adversarial review + classification + optional spec loop
    step-05-present.md            # Final findings to human (CHECKPOINT 2) + PR creation
```

### Modify

- `src/bmm/agents/quick-flow-solo-dev.agent.yaml` — replace QS/QD menu triggers with single QF trigger
- Claude Code skill entry points (if separate from agent definition)

## Flow Architecture

### Human Checkpoints

Exactly two for the plan-code-review route:

1. **End of Plan (step-02)** — "Here's the spec. Approve, edit, or redirect to full BMM."
2. **End of Review (step-05)** — "Here are the classified findings. Approve the final state."

Everything between checkpoint 1 and checkpoint 2 is autonomous. No [A][P][C] gates. Advanced Elicitation and Party Mode remain invocable by the human at any time (as interrupts, not as gates in the critical path) but the flow never stops to offer them.

### Step 1 — Clarify and Route

Combines the old quick-dev mode-detection with quick-spec's understand phase. Single step because the routing decision depends on understanding the intent.

**On launch:**
- Load config, project-context.md (if exists), CLAUDE.md / memory (if exists)
- Check for existing WIP file → offer resume or archive
- Check for `ready-for-dev` tech spec → skip directly to step 3 (this was a bug in the old flow)

**Clarify intent:**
- The skill argument, if present, is the primary expression of intent. Treat it as the human's opening statement of what they want — not background context, not a hint, the intent itself.
- Intent may also come from other sources — resolvable references, prior conversation, existing WIP or ready-for-dev specs, or any other means. Do NOT assume you start from zero. Evaluate what's already known against the exit criteria below. If intent is already clear, don't ask.
- Do NOT prescribe how to capture intent — the LLM knows how to ask clarifying questions, probe for ambiguity, and synthesize messy descriptions into clear ones. That's training. Telling it how to do what it already knows creates ambiguities and contradictions of its own.
- Define **exit criteria for captured intent** — the agent's job is to reach this state, however it gets there:
  - Problem statement is unambiguous
  - Scope has clear boundaries
  - No contradictions with loaded project context
  - All blocking decisions are resolved (non-blocking ones can be deferred)
  - The agent can explain back to the human what it's about to do
- Investigate the codebase autonomously to understand scope (use subagents, don't ask the human to explain what's in their own codebase)
- Ask the human about intent and constraints, not implementation details — and only if the exit criteria aren't already met

**Backfill project context:**
- If version control conventions are unknown (no project-context.md or no VC section in it), ask once and write to:
  - `project-context.md` if it exists (append a Version Control section)
  - `_bmad-output/project-context-quickflow.md` sidecar if it doesn't
- Same for any other project convention the flow needs to operate autonomously

**Route:**
- **Full BMM** — scope too large or too ambiguous. Recommend and exit. Don't just warn, actually redirect.
- **One-shot** — trivial change (< ~3 files, clear intent, no architectural decisions). Skip to step 3 with an in-session mental plan, no spec file. Still does auto VC and review, but review is collapsed: skip Layer 1 (intent audit — overkill for trivial changes, self-check covers it), keep Layer 2 (adversarial code review — **non-negotiable**, a one-line change can cause severe unintended consequences five modules away; receives the original user prompt alongside the diff to close the intent verification gap). Skip merge/dedup (single findings source). Classify directly against user prompt.
- **Plan-code-review** — the main path. Proceed to step 2.
- **When ambiguous between one-shot and plan-code-review, default to plan-code-review.** Writing a spec for something trivial is less costly than one-shotting something complex.

### Step 2 — Plan

Merges the old quick-spec steps 2-4 into a single autonomous phase. The agent does not stop between investigation, generation, and self-review.

**Actions (autonomous, no checkpoints):**
1. Deep investigation — read relevant code, identify patterns, understand constraints. Use subagents.
2. Generate spec — tasks (file + action + rationale), acceptance criteria (Given/When/Then), technical decisions.
3. Self-review — verify completeness against "Ready for Development" standard: actionable, logical, testable, complete, self-contained.
4. Write spec to `{implementation_artifacts}/tech-spec-wip.md`.

**CHECKPOINT 1 — Present spec to human.**
- Show summary: task count, AC count, files affected, key decisions.
- Options: approve / edit / redirect to full BMM.
- On approve: rename to `tech-spec-{slug}.md`, set status `ready-for-dev`, proceed to step 3. **From this point forward, the spec's Problem, Solution, Scope, and Non-Goals sections are frozen** — the autonomous loop can only amend Tasks, Acceptance Criteria, and Technical Decisions. See step 4 Phase C for the frozen-section rule and escalation protocol.

### Step 3 — Implement

Merges old quick-dev steps 2-4 (context gathering, execute, self-check).

**Actions (autonomous):**
1. Capture baseline commit. For a fresh branch: `git rev-parse HEAD`. For a resumed WIP branch: `git merge-base HEAD <integration-branch>` to find the divergence point, where `<integration-branch>` is read from project-context.md (or sidecar), defaulting to `main` if unspecified. The baseline must produce a valid diff of all work on this branch, not just the current session.
2. Create feature branch and worktree automatically. Branch name: user-specified (if provided in intent) > spec slug default. User-specified branch takes priority — supports incremental changes to existing feature branches. **Idempotent:** if branch/worktree already exist (e.g., resuming a WIP or working on an existing feature branch), detect and reuse them instead of failing on duplicate creation.
3. **Assert clean working tree.** Before any task executes, verify no uncommitted changes or untracked files in the worktree. If the tree is dirty and this is a fresh start, surface to human and halt — something is wrong. If the tree is dirty and this is a resume, apply the resume policy (see below). This is a step-level precondition, not a per-task check.
4. Load spec tasks using the **BMAD sharded workflow pattern** — the same mechanism used for the flow's own steps, applied to task execution. Study and faithfully reproduce the existing BMAD sharded step-file architecture:
   - Each task is written to its own file (`_bmad-output/tasks/task-01.md`, etc.)
   - A sequence file tracks execution order, status per task, and current position
   - **The sequence file must be robust against partial execution failures or crashes.** Status is written to disk after each task completes, before the next begins. On resume, the sequence file is the source of truth — completed tasks are skipped, execution picks up at the first incomplete task. No in-memory-only state.
   - Read each task file fresh before execution so the full prompt lands at the end of the context window (high-attention zone). This is the generic flow's primary defense against lost-in-the-middle syndrome.
   - **Note:** A Claude Code-native variant (future work) will use TaskCreate/TaskGet/TaskUpdate for verbatim task prompt injection via platform tooling. The generic flow does not attempt to detect or use platform-specific task tracking — capability self-reporting is unreliable.
5. Execute tasks strictly sequentially: load next task from task list (or read next file in fallback mode) so the full task prompt is at the end of the context window (high-attention zone) → implement → verify AC → mark complete → load next. **No parallel execution — race conditions on shared code are a hard taboo.**
6. Self-check: all tasks done, ACs met, patterns followed.
7. Commit automatically with a conventional commit message.
8. Update spec with completion status.

**Resume policy (dirty working tree on re-entry to step 3):**
Because the clean-tree precondition guarantees the worktree was clean before implementation started, any uncommitted changes on resume are unambiguously from the crashed/interrupted task — identified by the sequence file's current position. The agent inspects the diff against that incomplete task: if the partial work is coherent and clearly progressing toward the task's goal, continue from where it left off; if the state is unclear or inconsistent, revert the uncommitted changes and re-execute the task from scratch. There are no per-task commits — the single commit at the end of step 3 (action 7) remains the only commit point.

**Halt conditions (require human):**
- 3 consecutive failures on same task
- Blocking ambiguity the spec doesn't resolve
- Test infrastructure missing or broken — **only if the spec relies on existing tests to verify ACs.** Does not apply when the task itself is to build or fix test infrastructure.

**Version control in step 3 — local only:**
- Branch naming: derived from spec slug (e.g., `feat/{slug}`)
- Worktree: created at start, used for all changes
- Commits: automatic, conventional format
- **No push, no PR, no push prompts.** All remote operations live strictly in step 5 after review patches are applied.

### Step 4 — Review and Classify

Merges old quick-dev steps 5-6 with a new classification system.

**Phase A — Multi-Layer Review:**

Two default review layers, both in isolated subagents with no conversation context or implementation reasoning. Extensible via sidecar config.

**Layer 1 — Intent/Rules Audit:**
- Receives: the spec (or original user prompt for one-shot), the code artifact, and any project rules/guidelines (CLAUDE.md, project-context.md, etc.)
- Does NOT receive: conversation context, implementation reasoning, or the "how we got here" narrative
- Checks: does the output match the intent? Were project rules and guidelines followed?
- This is the functional correctness check. It catches "perfectly clean code that does the wrong thing" — the gap that self-check covers poorly due to anchoring bias.

**Layer 2 — Adversarial Code Review:**
- Invokes `src/core/tasks/review-adversarial-general.xml` — the existing BMAD standard building block for adversarial review — with the diff as the content input. Context isolation is about what the subagent receives, not the review procedure itself.
- Receives: the diff and access to source code. **One-shot exception:** also receives the original user prompt, closing the intent verification gap without adding Layer 1. The information-asymmetry design (no spec, no conversation context) still holds for the plan-code-review route; one-shot needs the user prompt because there is no other intent artifact.
- Does NOT receive (plan-code-review route): the spec, intent, rules, or conversation context
- Free-form reasoning about code quality — patterns, edge cases, error handling, style
- Information-asymmetric by design. Its value comes from having zero expectations.

**Additional layers (optional, user-configured via sidecar):**
- Security review, accessibility audit, rules-specific deep check, etc.
- The default two layers are the lowest common denominator — works well for small projects, better than nothing for real work. Real projects should invest in customizing and adding layers.

Both layers produce raw findings lists. Before classification in Phase B, findings are merged using the existing BMAD pattern (from quick-dev/code-review flow): deduplicate, reorder by severity, then classify. Same mechanism, not a new invention.

**Phase B — Evidence-Based Classification:**
- The orchestrating agent (which knows the spec and intent) classifies each finding.
- **Classifier framing:** The classifier does not own the code — the code is a build artifact derived from the spec. The classifier owns the *spec*. A spec-class finding is the most valuable outcome: it means the spec gets stronger and future derivations improve. Frame spec-class discovery as a win, not a failure. This framing reduces anchoring bias by decoupling the classifier's evaluation from self-critique of its own implementation.
- Classification uses a **priority cascade: intent-class > spec-class > patch-class.** If a review round produces findings at multiple levels, resolve from the top down. Intent-class findings go to the human first. After intent is resolved, re-evaluate spec-class findings against the new or confirmed intent — some may be moot. Then amend the spec incorporating still-valid spec findings. This extends the two-pass principle with one more level.
  - **First pass:** scan all findings for intent-class issues using the **INTENT_GAP two-question test.** For each finding, the classifier asks: (1) Can this issue be resolved using only the information already present in the original user request + current spec? (2) Does fixing it require a user-specific decision or preference that cannot reasonably be guessed? If #2 = yes → **intent-class (INTENT_GAP).** Generate one clear, targeted question and escalate to the human at the next checkpoint. A finding is also intent-class if its root cause traces to a frozen section of the spec (Problem, Solution, Scope, or Non-Goals — see Phase C for the frozen-section rule). Both paths require human resolution before anything else proceeds.
  - **Second pass:** scan remaining findings for spec-class issues. For each finding, ask: "Does the root cause trace to the mutable spec surface?" Collect all that do.
  - **If any spec-class findings exist and under iteration limit:** fix them all in the spec, re-derive code, re-review. Do NOT classify remaining findings into patch/defer/reject — they are moot and will be re-evaluated against fresh code.
  - **If no spec-class findings (or iteration limit reached):** proceed to full classification of all findings into patch/defer/reject.
- For each finding, the classifier asks: "Is this a real problem, and if so, what is the root cause?"
  - **Root cause traces to frozen intent** (the Problem, Solution, Scope, or Non-Goals are wrong, contradictory, or incomplete) → **intent class.** Only the human can resolve this. Escalate with a recommended resolution — not a raw finding dump. See Phase C.
  - **Root cause traces to the mutable spec surface** (Tasks, Acceptance Criteria, or Technical Decisions are wrong, vague, or insufficiently precise to prevent agent drift) → **spec class.** If the agent drifted from the spec, the spec was not precise enough — that is a spec defect, not an implementation defect. Point to the specific spec section that failed.
  - **Code quality issue unrelated to the spec** (the spec had nothing to say about this and shouldn't have — e.g., a missed edge case in error handling, a style issue, a performance concern) → **patch class.** Fix the code in place.
  - **Not worth blocking on → defer class.** Append to `_bmad-output/wip.md` with context. If it suggests a guiding principle needs updating, note that too.
  - **Not a real finding → reject class.**

**Phase C — Spec Loop (optional, autonomous, rigidly bounded):**

The spec loop is the highest-risk point in the entire flow for infinite token burn, oscillation, and divergence from original human intent. Three mechanisms work together to bound it: frozen intent sections, a spec change log, and a hard iteration cap.

**Frozen intent sections:** After checkpoint 1, the spec's Problem, Solution, Scope, and Non-Goals sections are frozen — read-only for the autonomous loop. The mutable surface for autonomous spec amendments is limited to Tasks, Acceptance Criteria, and Technical Decisions. This partitions the spec into human-owned intent (stable anchor) and agent-owned derivation (amendable). If a finding's root cause traces to a frozen section, it is intent-class: escalate to the human with a recommended resolution (not just a raw finding dump). The human confirms, edits, or rejects the recommendation. Only the human can authorize changes to frozen sections. The loop continues after intent-class findings are resolved.

**Spec change log (guardrails ratchet):** Each spec amendment appends to a change log embedded in the spec: what changed, what finding triggered the change, and what known-bad state the change avoids. Subsequent iterations must read the log before amending. A previous fix cannot be undone without contradicting a logged constraint — the log is append-only and acts as a monotonically increasing set of constraints. This prevents 2-period attractor cycles where the agent oscillates between two states, each "fixing" the other.

**Positive Preservation:** Before discarding code from a failed iteration, the agent extracts "what worked well" — specific implementations, patterns, or solutions that were correct and effective — and records them as explicit KEEP instructions in the change log alongside the amendment. These KEEP instructions are carried forward into the next iteration's context as positive constraints: the re-derived code must preserve these behaviors. This prevents the loop from losing emergent cleverness when it fixes a spec defect — the good parts survive the rewrite.

**Loop mechanics:**
- If there are spec-class findings with high confidence:
  - Read the change log (if any previous iterations exist)
  - **Extract Positive Preservation:** identify what worked well in the current code before discarding it. Record as KEEP instructions.
  - Amend the mutable spec surface to resolve the findings, respecting all logged constraints (including KEEP instructions from previous iterations)
  - Append each amendment to the change log with its triggering finding, the state it avoids, and any KEEP instructions extracted
  - Re-derive the affected code (respecting KEEP instructions)
  - Re-run adversarial review on the new diff
  - Re-classify using the full priority cascade (intent > spec > patch)
  - Repeat until no more spec-class findings
- If an iteration produces intent-class findings, pause the loop and escalate to the human. Resume after the human resolves intent.
- If confidence is not high enough to loop autonomously, include spec-class findings in the presentation to the human.
- **Hard iteration cap: default 5, overridable in quickflow sidecar config.** When the cap is hit, stop unconditionally and present everything to the human. No exceptions.

**Phase D — Apply patches:**
- Auto-fix all patch-class findings.
- Commit the fixes.

### Step 5 — Present to Human

**CHECKPOINT 2 — Show classified findings list.**

The flow auto-handles everything it's confident about before reaching this point. The human's primary job here is the **low-confidence bucket** — findings where the classifier was not confident enough to assign a class (weak/no evidence from spec, ambiguous rule match, borderline real issue). Usually 1-3 items max. The human classifies each in seconds: spec (update spec + regen) / patch (auto-fix) / defer (to wip.md) / reject.

Present:
- **Intent-class findings (requiring human decision on frozen sections)** — highest priority, if any were escalated during the spec loop
- **Low-confidence findings (requiring human classification)** — the primary action item for routine runs
- Spec-class findings (if any remain unresolved or were looped) — for awareness
- Patch-class findings (already fixed) — for awareness
- Defer-class findings (parked in wip.md) — for awareness
- Reject-class findings (shown briefly) — for transparency
- Overall summary: what changed, what was reviewed, what was parked, spec change log (if any iterations occurred)

**Human options:**
- Approve → create PR automatically, print push command
- Adjust → modify specific findings or request changes
- Reject → explain what's wrong, loop back to relevant phase

**After approval:**
- Commit any remaining review patches (if not already committed in Phase D).
- **Push: strictly prohibited by default.** Print the command, wait for human confirmation. Overridable in quickflow sidecar config (`auto_push: true`), but if not explicitly overridden, this is a hard ban — no exceptions, no "just this once."
- Wait for human to confirm push is done (or auto-push if overridden).
- Create PR via `gh pr create` with summary derived from spec + findings.
- Flow complete.

## Tech-Spec Template (Revised)

Lighter than the current template. Drops the verbose frontmatter in favor of essentials.

```markdown
---
title:
slug:
created:
status: in-progress | ready-for-dev | implementing | complete
---

# {title}

## Problem
One paragraph.

## Solution
One paragraph.

## Scope
What's in, what's out.

## Non-Goals
What this spec explicitly does not address. Optional but recommended — frozen after checkpoint 1 alongside Problem, Solution, and Scope.

## Tasks
- [ ] Task 1: {file} — {action} — {rationale}
- [ ] Task 2: ...

## Acceptance Criteria
- [ ] AC 1: Given {X}, when {Y}, then {Z}
- [ ] AC 2: ...

## Technical Decisions
Only if non-obvious. Brief.

## Golden Examples
Optional. Concrete input/output pairs that anchor expected behavior. When the spec describes a transformation, algorithm, or interface, examples make the intent unambiguous where prose alone leaves room for interpretation. Frozen after checkpoint 1 (same as Problem/Solution/Scope).

## Spec Change Log
Appended by the review loop. Each entry: what changed, what finding triggered it, what known-bad state it avoids, and any KEEP instructions (positive preservation — what worked well and must survive the rewrite). Empty until step 4.

## Notes
Anything else. Optional.
```

## Parking Lot File

`_bmad-output/wip.md` — created on first defer-class finding, appended thereafter.

```markdown
# Parking Lot

## {date} — {spec-title}

- **Finding:** {description}
  **Context:** {why it was deferred}
  **Guiding principle note:** {if applicable — which principle might need updating}
```

## Version Control Context

On first run without VC conventions, the flow asks:
- Branch naming convention? (e.g., `feat/`, `fix/`, free-form)
- Commit message convention? (conventional commits, free-form, etc.)
- PR target? (branch name, fork vs same-repo)
- Worktree usage? (if applicable to the environment)

Writes answers to project-context.md (or sidecar). Never asks again.

## Open Questions

1. ~~**Spec loop bound**~~ — Resolved. Hard cap of 5 iterations, overridable in quickflow sidecar. Default to stop and present.
2. ~~**One-shot route review**~~ — Resolved. One-shot still gets the full review pipeline. Phase A (adversarial code review) works as-is. Phase B (classification) validates against the initial user prompt instead of a spec file — same evidence-based approach, lighter reference artifact.
3. ~~**Task list integration**~~ — Resolved. Generic flow uses file-based task sharding (read each task file fresh before execution). Claude Code-native variant (future work) will use TaskCreate/TaskGet for verbatim injection. Platform capability self-reporting is unreliable — the generic flow doesn't try to detect it. The only capability it may probe for is subagent support.
   - Execution is strictly sequential — load next task, execute, mark complete, load next
   - Full task prompt must be at the end of the context window (high-attention zone) when execution begins
   - **No parallel execution.** Race conditions on shared code are too risky. Sequential only in this incarnation.


Now I have the full context. The workflow doesn't have a standard config.yaml because this is the source repo of BMAD method itself. The `{project-root}/_bmad/bmm/config.yaml` doesn't exist since this project isn't "installed" with BMAD - it IS the BMAD source.

I need to work with reasonable defaults for the config values. Let me now load the project context files and proceed to step 1.

Let me set up the resolved variables:
- `project_name` = "BMAD-METHOD" (or "quick-flow-redesign")
- `planning_artifacts` = I need to figure this out from the project

- `implementation_artifacts` = I need to figure this out
- `communication_language` = English (default)
- `document_output_language` = English (default)
- `user_skill_level` = expert (seems clear from the session state)
- `date` = 2026-02-22
- `project_context` = found two project-context.md files
- `installed_path` = `src/bmm/workflows/bmad-quick-flow/quick-dev2`
- `templateFile` = `{installed_path}/tech-spec-template.md`
- `wipFile` = `{implementation_artifacts}/tech`

Now I'm setting up the file paths for the tech spec work-in-progress document and tasks directory, then checking for any existing output directories before loading the project context.


Good, I've loaded the workflow and the redesign plan. Now let me continue the initialization by loading project context and resolving paths.