     1→---
     2→title: "Project Context"
     3→description: How project-context.md guides AI agents with your project's rules and preferences
     4→sidebar:
     5→  order: 7
     6→---
     7→
     8→The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
     9→
    10→## What It Does
    11→
    12→AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
    13→- Follow generic best practices that don't match your codebase
    14→- Make inconsistent decisions across different stories
    15→- Miss project-specific requirements or constraints
    16→
    17→The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
    18→
    19→## How It Works
    20→
    21→Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
    22→
    23→**Loaded by these workflows:**
    24→- `create-architecture` — respects technical preferences during solutioning
    25→- `create-story` — informs story creation with project patterns
    26→- `dev-story` — guides implementation decisions
    27→- `code-review` — validates against project standards
    28→- `quick-dev` — applies patterns when implementing tech-specs
    29→- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context
    30→
    31→## When to Create It
    32→
    33→The `project-context.md` file is useful at any stage of a project:
    34→
    35→| Scenario | When to Create | Purpose |
    36→|----------|----------------|---------|
    37→| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
    38→| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
    39→| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
    40→| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |
    41→
    42→:::tip[Recommended]
    43→For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
    44→:::
    45→
    46→## What Goes In It
    47→
    48→The file has two main sections:
    49→
    50→### Technology Stack & Versions
    51→
    52→Documents the frameworks, languages, and tools your project uses with specific versions:
    53→
    54→```markdown
    55→## Technology Stack & Versions
    56→
    57→- Node.js 20.x, TypeScript 5.3, React 18.2
    58→- State: Zustand (not Redux)
    59→- Testing: Vitest, Playwright, MSW
    60→- Styling: Tailwind CSS with custom design tokens
    61→```
    62→
    63→### Critical Implementation Rules
    64→
    65→Documents patterns and conventions that agents might otherwise miss:
    66→
    67→```markdown
    68→## Critical Implementation Rules
    69→
    70→**TypeScript Configuration:**
    71→- Strict mode enabled — no `any` types without explicit approval
    72→- Use `interface` for public APIs, `type` for unions/intersections
    73→
    74→**Code Organization:**
    75→- Components in `/src/components/` with co-located `.test.tsx`
    76→- Utilities in `/src/lib/` for reusable pure functions
    77→- API calls use the `apiClient` singleton — never fetch directly
    78→
    79→**Testing Patterns:**
    80→- Unit tests focus on business logic, not implementation details
    81→- Integration tests use MSW to mock API responses
    82→- E2E tests cover critical user journeys only
    83→
    84→**Framework-Specific:**
    85→- All async operations use the `handleError` wrapper for consistent error handling
    86→- Feature flags accessed via `featureFlag()` from `@/lib/flags`
    87→- New routes follow the file-based routing pattern in `/src/app/`
    88→```
    89→
    90→Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
    91→
    92→## Creating the File
    93→
    94→You have three options:
    95→
    96→### Manual Creation
    97→
    98→Create the file at `_bmad-output/project-context.md` and add your rules:
    99→
   100→```bash
   101→# In your project root
   102→mkdir -p _bmad-output
   103→touch _bmad-output/project-context.md
   104→```
   105→
   106→Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
   107→
   108→### Generate After Architecture
   109→
   110→Run the `generate-project-context` workflow after completing your architecture:
   111→
   112→```bash
   113→/bmad-bmm-generate-project-context
   114→```
   115→
   116→This scans your architecture document and project files to generate a context file capturing the decisions made.
   117→
   118→### Generate for Existing Projects
   119→
   120→For existing projects, run `generate-project-context` to discover existing patterns:
   121→
   122→```bash
   123→/bmad-bmm-generate-project-context
   124→```
   125→
   126→The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
   127→
   128→## Why It Matters
   129→
   130→Without `project-context.md`, agents make assumptions that may not match your project:
   131→
   132→| Without Context | With Context |
   133→|----------------|--------------|
   134→| Uses generic patterns | Follows your established conventions |
   135→| Inconsistent style across stories | Consistent implementation |
   136→| May miss project-specific constraints | Respects all technical requirements |
   137→| Each agent decides independently | All agents align with same rules |
   138→
   139→This is especially important for:
   140→- **Quick Flow** — skips PRD and architecture, so context file fills the gap
   141→- **Team projects** — ensures all agents follow the same standards
   142→- **Existing projects** — prevents breaking established patterns
   143→
   144→## Editing and Updating
   145→
   146→The `project-context.md` file is a living document. Update it when:
   147→
   148→- Architecture decisions change
   149→- New conventions are established
   150→- Patterns evolve during implementation
   151→- You identify gaps from agent behavior
   152→
   153→You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.
   154→
   155→:::note[File Location]
   156→The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
   157→:::
   158→

---
title: "Project Context"
description: How project-context.md guides AI agents with your project's rules and preferences
sidebar:
  order: 7
---

The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.

## What It Does

AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
- Follow generic best practices that don't match your codebase
- Make inconsistent decisions across different stories
- Miss project-specific requirements or constraints

The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.

## How It Works

Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.

**Loaded by these workflows:**
- `create-architecture` — respects technical preferences during solutioning
- `create-story` — informs story creation with project patterns
- `dev-story` — guides implementation decisions
- `code-review` — validates against project standards
- `quick-dev` — applies patterns when implementing tech-specs
- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context

## When to Create It

The `project-context.md` file is useful at any stage of a project:

| Scenario | When to Create | Purpose |
|----------|----------------|---------|
| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |

:::tip[Recommended]
For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
:::

## What Goes In It

The file has two main sections:

### Technology Stack & Versions

Documents the frameworks, languages, and tools your project uses with specific versions:

```markdown
## Technology Stack & Versions

- Node.js 20.x, TypeScript 5.3, React 18.2
- State: Zustand (not Redux)
- Testing: Vitest, Playwright, MSW
- Styling: Tailwind CSS with custom design tokens
```

### Critical Implementation Rules

Documents patterns and conventions that agents might otherwise miss:

```markdown
## Critical Implementation Rules

**TypeScript Configuration:**
- Strict mode enabled — no `any` types without explicit approval
- Use `interface` for public APIs, `type` for unions/intersections

**Code Organization:**
- Components in `/src/components/` with co-located `.test.tsx`
- Utilities in `/src/lib/` for reusable pure functions
- API calls use the `apiClient` singleton — never fetch directly

**Testing Patterns:**
- Unit tests focus on business logic, not implementation details
- Integration tests use MSW to mock API responses
- E2E tests cover critical user journeys only

**Framework-Specific:**
- All async operations use the `handleError` wrapper for consistent error handling
- Feature flags accessed via `featureFlag()` from `@/lib/flags`
- New routes follow the file-based routing pattern in `/src/app/`
```

Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.

## Creating the File

You have three options:

### Manual Creation

Create the file at `_bmad-output/project-context.md` and add your rules:

```bash
# In your project root
mkdir -p _bmad-output
touch _bmad-output/project-context.md
```

Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.

### Generate After Architecture

Run the `generate-project-context` workflow after completing your architecture:

```bash
/bmad-bmm-generate-project-context
```

This scans your architecture document and project files to generate a context file capturing the decisions made.

### Generate for Existing Projects

For existing projects, run `generate-project-context` to discover existing patterns:

```bash
/bmad-bmm-generate-project-context
```

The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.

## Why It Matters

Without `project-context.md`, agents make assumptions that may not match your project:

| Without Context | With Context |
|----------------|--------------|
| Uses generic patterns | Follows your established conventions |
| Inconsistent style across stories | Consistent implementation |
| May miss project-specific constraints | Respects all technical requirements |
| Each agent decides independently | All agents align with same rules |

This is especially important for:
- **Quick Flow** — skips PRD and architecture, so context file fills the gap
- **Team projects** — ensures all agents follow the same standards
- **Existing projects** — prevents breaking established patterns

## Editing and Updating

The `project-context.md` file is a living document. Update it when:

- Architecture decisions change
- New conventions are established
- Patterns evolve during implementation
- You identify gaps from agent behavior

You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.

:::note[File Location]
The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
:::


     1→---
     2→title: '{title}'
     3→slug: '{slug}'
     4→created: '{date}'
     5→status: 'in-progress'
     6→---
     7→
     8→# {title}
     9→
    10→## Problem
    11→
    12→{problem}
    13→
    14→## Solution
    15→
    16→{solution}
    17→
    18→## Scope
    19→
    20→**In:** {in_scope}
    21→
    22→**Out:** {out_of_scope}
    23→
    24→## Non-Goals
    25→
    26→{non_goals}
    27→
    28→## Tasks
    29→
    30→- [ ] Task 1: `{file}` -- {action} -- {rationale}
    31→
    32→## Acceptance Criteria
    33→
    34→- [ ] AC 1: Given {precondition}, when {action}, then {expected_result}
    35→
    36→## Technical Decisions
    37→
    38→{technical_decisions}
    39→
    40→## Golden Examples
    41→
    42→{golden_examples}
    43→
    44→## Spec Change Log
    45→
    46→<!-- Appended by the review loop. Each entry: what changed, what triggered it, what bad state it avoids, KEEP instructions. Empty until step 4. -->
    47→
    48→## Notes
    49→
    50→{notes}
    51→

---
title: '{title}'
slug: '{slug}'
created: '{date}'
status: 'in-progress'
---

# {title}

## Problem

{problem}

## Solution

{solution}

## Scope

**In:** {in_scope}

**Out:** {out_of_scope}

## Non-Goals

{non_goals}

## Tasks

- [ ] Task 1: `{file}` -- {action} -- {rationale}

## Acceptance Criteria

- [ ] AC 1: Given {precondition}, when {action}, then {expected_result}

## Technical Decisions

{technical_decisions}

## Golden Examples

{golden_examples}

## Spec Change Log

<!-- Appended by the review loop. Each entry: what changed, what triggered it, what bad state it avoids, KEEP instructions. Empty until step 4. -->

## Notes

{notes}


     1→---
     2→name: 'step-01-clarify-and-route'
     3→description: 'Capture intent, route to execution path'
     4→
     5→wipFile: '{implementation_artifacts}/tech-spec-wip.md'
     6→---
     7→
     8→# Step 1: Clarify and Route
     9→
    10→**Step 1 of 5**
    11→
    12→## RULES
    13→
    14→- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
    15→- The skill argument IS the intent — not a hint.
    16→- Do NOT assume you start from zero.
    17→
    18→## CONTEXT
    19→
    20→- `ready-for-dev` spec in `{implementation_artifacts}`? → Confirm, skip to step 3.
    21→- `{wipFile}` exists? → Offer resume or archive.
    22→
    23→---
    24→
    25→## INSTRUCTIONS
    26→
    27→1. Clarify intent until: problem unambiguous, scope clear, no contradictions, you can explain back what you'll do.
    28→2. Backfill VC conventions to project-context if unknown.
    29→3. Route:
    30→   - **One-shot** — trivial (~3 files). `{execution_mode}` = "one-shot". → Step 3.
    31→   - **Plan-code-review** — normal. → Step 2.
    32→   - **Full BMM** — too big. Recommend and exit.
    33→   - Ambiguous? Default plan-code-review.
    34→
    35→---
    36→
    37→## NEXT
    38→
    39→- One-shot / ready-for-dev: `{installed_path}/steps/step-03-implement.md`
    40→- Plan-code-review: `{installed_path}/steps/step-02-plan.md`
    41→

---
name: 'step-01-clarify-and-route'
description: 'Capture intent, route to execution path'

wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 1: Clarify and Route

**Step 1 of 5**

## RULES

- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
- The skill argument IS the intent — not a hint.
- Do NOT assume you start from zero.

## CONTEXT

- `ready-for-dev` spec in `{implementation_artifacts}`? → Confirm, skip to step 3.
- `{wipFile}` exists? → Offer resume or archive.

---

## INSTRUCTIONS

1. Clarify intent until: problem unambiguous, scope clear, no contradictions, you can explain back what you'll do.
2. Backfill VC conventions to project-context if unknown.
3. Route:
   - **One-shot** — trivial (~3 files). `{execution_mode}` = "one-shot". → Step 3.
   - **Plan-code-review** — normal. → Step 2.
   - **Full BMM** — too big. Recommend and exit.
   - Ambiguous? Default plan-code-review.

---

## NEXT

- One-shot / ready-for-dev: `{installed_path}/steps/step-03-implement.md`
- Plan-code-review: `{installed_path}/steps/step-02-plan.md`


No files found


Now I have all the context I need. Let me set up my resolved configuration:

**Resolved Config:**
- `project_name` = "BMAD-METHOD" (this is the BMAD method source repo)
- `communication_language` = English (default; the user communicates in English)
- `document_output_language` = English
- `user_skill_level` = expert (based on the sophisticated session state and design decisions)
- `date` = 2026-02-22
- `project_context` = The docs/explanation/project-context.md is just documentation about the feature, not an actual project context file. There's no actual `_bmad-output/project-context.md` or installed project context.

- `planning_artifacts` = None found / doesn't exist in installed form
- `implementation_artifacts` = None found / doesn't exist in installed form

Since there's no config.yaml and this is the source repo, the `_bmad-output` directory doesn't exist. I'll work with reasonable defaults and use the installed path at `/Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-dev2`, pointing the template file there and determining the implementation artifacts path accordingly.

Now I'm at Step 1 - Clarify and Route. There's no ready-for-dev spec or WIP file since the output directory doesn't exist yet, so I need to ask the user what they want to build before I can proceed.


**Quick Dev 2 — Initialized**

Configuration resolved:
- **Project:** BMAD-METHOD (source repo)
- **Branch:** `exp/quick-flow-redesign`
- **Language:** English
- **Date:** 2026-02-22
- **Installed path:** `src/bmm/workflows/bmad-quick-flow/quick-dev2`
- **Implementation artifacts:** `_bmad-output/implementation-artifacts`
- **WIP file:** not found (clean start)
- **Ready-for-dev spec:** not found

---

**Step 1 of 5 — Clarify and Route**

No skill argument was provided and no existing WIP or ready-for-dev spec detected. I'm starting from zero on intent.

What do you want to build or change? Give me the task — anything from a one-liner to a multi-file feature.


Bash

say "Quick Dev 2 initialized. No task detected yet. What do you want to build?"

TTS summary


TTS summary


[Request interrupted by user]


Eliminate one human turn from quick-spec


Explore quick-spec workflow steps


Task

Explore quick-spec workflow steps

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→name: quick-spec
     3→description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.
     4→main_config: '{project-root}/_bmad/bmm/config.yaml'
     5→
     6→# Checkpoint handler paths
     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→quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md'
    10→---
    11→
    12→# Quick-Spec Workflow
    13→
    14→**Goal:** Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation.
    15→
    16→**READY FOR DEVELOPMENT STANDARD:**
    17→
    18→A specification is considered "Ready for Development" ONLY if it meets the following:
    19→
    20→- **Actionable**: Every task has a clear file path and specific action.
    21→- **Logical**: Tasks are ordered by dependency (lowest level first).
    22→- **Testable**: All ACs follow Given/When/Then and cover happy path and edge cases.
    23→- **Complete**: All investigation results from Step 2 are inlined; no placeholders or "TBD".
    24→- **Self-Contained**: A fresh agent can implement the feature without reading the workflow history.
    25→
    26→---
    27→
    28→**Your Role:** You are an elite developer and spec engineer. You ask sharp questions, investigate existing code thoroughly, and produce specs that contain ALL context a fresh dev agent needs to implement the feature. No handoffs, no missing context - just complete, actionable specs.
    29→
    30→---
    31→
    32→## WORKFLOW ARCHITECTURE
    33→
    34→This uses **step-file architecture** for disciplined execution:
    35→
    36→### Core Principles
    37→
    38→- **Micro-file Design**: Each step is a self-contained instruction file that must be followed exactly
    39→- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed
    40→- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization
    41→- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
    42→- **Append-Only Building**: Build the tech-spec by updating content as directed
    43→
    44→### Step Processing Rules
    45→
    46→1. **READ COMPLETELY**: Always read the entire step file before taking any action
    47→2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
    48→3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
    49→4. **CHECK CONTINUATION**: Only proceed to next step when user selects [C] (Continue)
    50→5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
    51→6. **LOAD NEXT**: When directed, read fully and follow the next step file
    52→
    53→### Critical Rules (NO EXCEPTIONS)
    54→
    55→- **NEVER** load multiple step files simultaneously
    56→- **ALWAYS** read entire step file before execution
    57→- **NEVER** skip steps or optimize the sequence
    58→- **ALWAYS** update frontmatter of output file when completing a step
    59→- **ALWAYS** follow the exact instructions in the step file
    60→- **ALWAYS** halt at menus and wait for user input
    61→- **NEVER** create mental todo lists from future steps
    62→
    63→---
    64→
    65→## INITIALIZATION SEQUENCE
    66→
    67→### 1. Configuration Loading
    68→
    69→Load and read full config from `{main_config}` and resolve:
    70→
    71→- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
    72→- `communication_language`, `document_output_language`, `user_skill_level`
    73→- `date` as system-generated current datetime
    74→- `project_context` = `**/project-context.md` (load if exists)
    75→- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
    76→
    77→### 2. First Step Execution
    78→
    79→Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md` to begin the workflow.
    80→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→name: 'step-01-understand'
     3→description: 'Analyze the requirement delta between current state and what user wants to build'
     4→
     5→templateFile: '../tech-spec-template.md'
     6→wipFile: '{implementation_artifacts}/tech-spec-wip.md'
     7→---
     8→
     9→# Step 1: Analyze Requirement Delta
    10→
    11→**Progress: Step 1 of 4** - Next: Deep Investigation
    12→
    13→## RULES:
    14→
    15→- MUST NOT skip steps.
    16→- MUST NOT optimize sequence.
    17→- MUST follow exact instructions.
    18→- MUST NOT look ahead to future steps.
    19→- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
    20→
    21→## CONTEXT:
    22→
    23→- Variables from `workflow.md` are available in memory.
    24→- Focus: Define the technical requirement delta and scope.
    25→- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
    26→- Objective: Establish a verifiable delta between current state and target state.
    27→
    28→## SEQUENCE OF INSTRUCTIONS
    29→
    30→### 0. Check for Work in Progress
    31→
    32→a) **Before anything else, check if `{wipFile}` exists:**
    33→
    34→b) **IF WIP FILE EXISTS:**
    35→
    36→1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
    37→2. Calculate progress: `lastStep = max(stepsCompleted)`
    38→3. Present to user:
    39→
    40→```
    41→Hey {user_name}! Found a tech-spec in progress:
    42→
    43→**{title}** - Step {lastStep} of 4 complete
    44→
    45→Is this what you're here to continue?
    46→
    47→[Y] Yes, pick up where I left off
    48→[N] No, archive it and start something new
    49→```
    50→
    51→4. **HALT and wait for user selection.**
    52→
    53→a) **Menu Handling:**
    54→
    55→- **[Y] Continue existing:**
    56→  - Jump directly to the appropriate step based on `stepsCompleted`:
    57→    - `[1]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2)
    58→    - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3)
    59→    - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4)
    60→- **[N] Archive and start fresh:**
    61→  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`
    62→
    63→### 1. Greet and Ask for Initial Request
    64→
    65→a) **Greet the user briefly:**
    66→
    67→"Hey {user_name}! What are we building today?"
    68→
    69→b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.
    70→
    71→### 2. Quick Orient Scan
    72→
    73→a) **Before asking detailed questions, do a rapid scan to understand the landscape:**
    74→
    75→b) **Check for existing context docs:**
    76→
    77→- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
    78→- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
    79→- Check for any existing stories or specs related to user's request
    80→
    81→c) **If user mentioned specific code/features, do a quick scan:**
    82→
    83→- Search for relevant files/classes/functions they mentioned
    84→- Skim the structure (don't deep-dive yet - that's Step 2)
    85→- Note: tech stack, obvious patterns, file locations
    86→
    87→d) **Build mental model:**
    88→
    89→- What's the likely landscape for this feature?
    90→- What's the likely scope based on what you found?
    91→- What questions do you NOW have, informed by the code?
    92→
    93→**This scan should take < 30 seconds. Just enough to ask smart questions.**
    94→
    95→### 3. Ask Informed Questions
    96→
    97→a) **Now ask clarifying questions - but make them INFORMED by what you found:**
    98→
    99→Instead of generic questions like "What's the scope?", ask specific ones like:
   100→- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
   101→- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
   102→- "The epics doc mentions X - is this related?"
   103→
   104→**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.
   105→
   106→b) **If no existing code is found:**
   107→
   108→- Ask about intended architecture, patterns, constraints
   109→- Ask what similar systems they'd like to emulate
   110→
   111→### 4. Capture Core Understanding
   112→
   113→a) **From the conversation, extract and confirm:**
   114→
   115→- **Title**: A clear, concise name for this work
   116→- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
   117→- **Problem Statement**: What problem are we solving?
   118→- **Solution**: High-level approach (1-2 sentences)
   119→- **In Scope**: What's included
   120→- **Out of Scope**: What's explicitly NOT included
   121→
   122→b) **Ask the user to confirm the captured understanding before proceeding.**
   123→
   124→### 5. Initialize WIP File
   125→
   126→a) **Create the tech-spec WIP file:**
   127→
   128→1. Copy template from `{templateFile}`
   129→2. Write to `{wipFile}`
   130→3. Update frontmatter with captured values:
   131→   ```yaml
   132→   ---
   133→   title: '{title}'
   134→   slug: '{slug}'
   135→   created: '{date}'
   136→   status: 'in-progress'
   137→   stepsCompleted: [1]
   138→   tech_stack: []
   139→   files_to_modify: []
   140→   code_patterns: []
   141→   test_patterns: []
   142→   ---
   143→   ```
   144→4. Fill in Overview section with Problem Statement, Solution, and Scope
   145→5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
   146→6. Write the file
   147→
   148→b) **Report to user:**
   149→
   150→"Created: `{wipFile}`
   151→
   152→**Captured:**
   153→
   154→- Title: {title}
   155→- Problem: {problem_statement_summary}
   156→- Scope: {scope_summary}"
   157→
   158→### 6. Present Checkpoint Menu
   159→
   160→a) **Display menu:**
   161→
   162→Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"
   163→
   164→b) **HALT and wait for user selection.**
   165→
   166→#### Menu Handling Logic:
   167→
   168→- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
   169→- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
   170→- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
   171→- IF Any other comments or queries: respond helpfully then redisplay menu
   172→
   173→#### EXECUTION RULES:
   174→
   175→- ALWAYS halt and wait for user input after presenting menu
   176→- ONLY proceed to next step when user selects 'C'
   177→- After A or P execution, return to this menu
   178→
   179→---
   180→
   181→## REQUIRED OUTPUTS:
   182→
   183→- MUST initialize WIP file with captured metadata.
   184→
   185→## VERIFICATION CHECKLIST:
   186→
   187→- [ ] WIP check performed FIRST before any greeting.
   188→- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
   189→- [ ] User selected [C] to continue.
   190→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→name: 'step-02-investigate'
     3→description: 'Map technical constraints and anchor points within the codebase'
     4→
     5→wipFile: '{implementation_artifacts}/tech-spec-wip.md'
     6→---
     7→
     8→# Step 2: Map Technical Constraints & Anchor Points
     9→
    10→**Progress: Step 2 of 4** - Next: Generate Plan
    11→
    12→## RULES:
    13→
    14→- MUST NOT skip steps.
    15→- MUST NOT optimize sequence.
    16→- MUST follow exact instructions.
    17→- MUST NOT generate the full spec yet (that's Step 3).
    18→- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
    19→
    20→## CONTEXT:
    21→
    22→- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined.
    23→- Focus: Map the problem statement to specific anchor points in the codebase.
    24→- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified.
    25→- Objective: Provide the implementation-ready ground truth for the plan.
    26→
    27→## SEQUENCE OF INSTRUCTIONS
    28→
    29→### 1. Load Current State
    30→
    31→**Read `{wipFile}` and extract:**
    32→
    33→- Problem statement and scope from Overview section
    34→- Any context gathered in Step 1
    35→
    36→### 2. Execute Investigation Path
    37→
    38→**Universal Code Investigation:**
    39→
    40→_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._
    41→
    42→a) **Build on Step 1's Quick Scan**
    43→
    44→Review what was found in Step 1's orient scan. Then ask:
    45→
    46→"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?"
    47→
    48→b) **Read and Analyze Code**
    49→
    50→For each file/directory provided:
    51→
    52→- Read the complete file(s)
    53→- Identify patterns, conventions, coding style
    54→- Note dependencies and imports
    55→- Find related test files
    56→
    57→**If NO relevant code is found (Clean Slate):**
    58→
    59→- Identify the target directory where the feature should live.
    60→- Scan parent directories for architectural context.
    61→- Identify standard project utilities or boilerplate that SHOULD be used.
    62→- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist.
    63→
    64→
    65→c) **Document Technical Context**
    66→
    67→Capture and confirm with user:
    68→
    69→- **Tech Stack**: Languages, frameworks, libraries
    70→- **Code Patterns**: Architecture patterns, naming conventions, file structure
    71→- **Files to Modify/Create**: Specific files that will need changes or new files to be created
    72→- **Test Patterns**: How tests are structured, test frameworks used
    73→
    74→d) **Look for project-context.md**
    75→
    76→If `**/project-context.md` exists and wasn't loaded in Step 1:
    77→
    78→- Load it now
    79→- Extract patterns and conventions
    80→- Note any rules that must be followed
    81→
    82→### 3. Update WIP File
    83→
    84→**Update `{wipFile}` frontmatter:**
    85→
    86→```yaml
    87→---
    88→# ... existing frontmatter ...
    89→stepsCompleted: [1, 2]
    90→tech_stack: ['{captured_tech_stack}']
    91→files_to_modify: ['{captured_files}']
    92→code_patterns: ['{captured_patterns}']
    93→test_patterns: ['{captured_test_patterns}']
    94→---
    95→```
    96→
    97→**Update the Context for Development section:**
    98→
    99→Fill in:
   100→
   101→- Codebase Patterns (from investigation)
   102→- Files to Reference table (files reviewed)
   103→- Technical Decisions (any decisions made during investigation)
   104→
   105→**Report to user:**
   106→
   107→"**Context Gathered:**
   108→
   109→- Tech Stack: {tech_stack_summary}
   110→- Files to Modify: {files_count} files identified
   111→- Patterns: {patterns_summary}
   112→- Tests: {test_patterns_summary}"
   113→
   114→### 4. Present Checkpoint Menu
   115→
   116→Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"
   117→
   118→**HALT and wait for user selection.**
   119→
   120→#### Menu Handling Logic:
   121→
   122→- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
   123→- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
   124→- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
   125→- IF Any other comments or queries: respond helpfully then redisplay menu
   126→
   127→#### EXECUTION RULES:
   128→
   129→- ALWAYS halt and wait for user input after presenting menu
   130→- ONLY proceed to next step when user selects 'C'
   131→- After A or P execution, return to this menu
   132→
   133→---
   134→
   135→## REQUIRED OUTPUTS:
   136→
   137→- MUST document technical context (stack, patterns, files identified).
   138→- MUST update `{wipFile}` with functional context.
   139→
   140→## VERIFICATION CHECKLIST:
   141→
   142→- [ ] Technical mapping performed and documented.
   143→- [ ] `stepsCompleted: [1, 2]` set in frontmatter.
   144→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→name: 'step-03-generate'
     3→description: 'Build the implementation plan based on the technical mapping of constraints'
     4→
     5→wipFile: '{implementation_artifacts}/tech-spec-wip.md'
     6→---
     7→
     8→# Step 3: Generate Implementation Plan
     9→
    10→**Progress: Step 3 of 4** - Next: Review & Finalize
    11→
    12→## RULES:
    13→
    14→- MUST NOT skip steps.
    15→- MUST NOT optimize sequence.
    16→- MUST follow exact instructions.
    17→- MUST NOT implement anything - just document.
    18→- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
    19→
    20→## CONTEXT:
    21→
    22→- Requires `{wipFile}` with defined "Overview" and "Context for Development" sections.
    23→- Focus: Create the implementation sequence that addresses the requirement delta using the captured technical context.
    24→- Output: Implementation-ready tasks with specific files and instructions.
    25→- Target: Meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
    26→
    27→## SEQUENCE OF INSTRUCTIONS
    28→
    29→### 1. Load Current State
    30→
    31→**Read `{wipFile}` completely and extract:**
    32→
    33→- All frontmatter values
    34→- Overview section (Problem, Solution, Scope)
    35→- Context for Development section (Patterns, Files, Decisions)
    36→
    37→### 2. Generate Implementation Plan
    38→
    39→Generate specific implementation tasks:
    40→
    41→a) **Task Breakdown**
    42→
    43→- Each task should be a discrete, completable unit of work
    44→- Tasks should be ordered logically (dependencies first)
    45→- Include the specific files to modify in each task
    46→- Be explicit about what changes to make
    47→
    48→b) **Task Format**
    49→
    50→```markdown
    51→- [ ] Task N: Clear action description
    52→  - File: `path/to/file.ext`
    53→  - Action: Specific change to make
    54→  - Notes: Any implementation details
    55→```
    56→
    57→### 3. Generate Acceptance Criteria
    58→
    59→**Create testable acceptance criteria:**
    60→
    61→Each AC should follow Given/When/Then format:
    62→
    63→```markdown
    64→- [ ] AC N: Given [precondition], when [action], then [expected result]
    65→```
    66→
    67→**Ensure ACs cover:**
    68→
    69→- Happy path functionality
    70→- Error handling
    71→- Edge cases (if relevant)
    72→- Integration points (if relevant)
    73→
    74→### 4. Complete Additional Context
    75→
    76→**Fill in remaining sections:**
    77→
    78→a) **Dependencies**
    79→
    80→- External libraries or services needed
    81→- Other tasks or features this depends on
    82→- API or data dependencies
    83→
    84→b) **Testing Strategy**
    85→
    86→- Unit tests needed
    87→- Integration tests needed
    88→- Manual testing steps
    89→
    90→c) **Notes**
    91→
    92→- High-risk items from pre-mortem analysis
    93→- Known limitations
    94→- Future considerations (out of scope but worth noting)
    95→
    96→### 5. Write Complete Spec
    97→
    98→a) **Update `{wipFile}` with all generated content:**
    99→
   100→- Ensure all template sections are filled in
   101→- No placeholder text remaining
   102→- All frontmatter values current
   103→- Update status to 'review' (NOT 'ready-for-dev' - that happens after user review in Step 4)
   104→
   105→b) **Update frontmatter:**
   106→
   107→```yaml
   108→---
   109→# ... existing values ...
   110→status: 'review'
   111→stepsCompleted: [1, 2, 3]
   112→---
   113→```
   114→
   115→c) **Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4)**
   116→
   117→## REQUIRED OUTPUTS:
   118→
   119→- Tasks MUST be specific, actionable, ordered logically, with files to modify.
   120→- ACs MUST be testable, using Given/When/Then format.
   121→- Status MUST be updated to 'review'.
   122→
   123→## VERIFICATION CHECKLIST:
   124→
   125→- [ ] `stepsCompleted: [1, 2, 3]` set in frontmatter.
   126→- [ ] Spec meets the **READY FOR DEVELOPMENT** standard.
   127→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→name: 'step-04-review'
     3→description: 'Review and finalize the tech-spec'
     4→
     5→wipFile: '{implementation_artifacts}/tech-spec-wip.md'
     6→---
     7→
     8→# Step 4: Review & Finalize
     9→
    10→**Progress: Step 4 of 4** - Final Step
    11→
    12→## RULES:
    13→
    14→- MUST NOT skip steps.
    15→- MUST NOT optimize sequence.
    16→- MUST follow exact instructions.
    17→- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
    18→
    19→## CONTEXT:
    20→
    21→- Requires `{wipFile}` from Step 3.
    22→- MUST present COMPLETE spec content. Iterate until user is satisfied.
    23→- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
    24→
    25→## SEQUENCE OF INSTRUCTIONS
    26→
    27→### 1. Load and Present Complete Spec
    28→
    29→**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.**
    30→
    31→**Present to user:**
    32→
    33→"Here's your complete tech-spec. Please review:"
    34→
    35→[Display the complete spec content - all sections]
    36→
    37→"**Quick Summary:**
    38→
    39→- {task_count} tasks to implement
    40→- {ac_count} acceptance criteria to verify
    41→- {files_count} files to modify"
    42→
    43→**Present review menu:**
    44→
    45→Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode"
    46→
    47→**HALT and wait for user selection.**
    48→
    49→#### Menu Handling Logic:
    50→
    51→- IF C: Proceed to Section 3 (Finalize the Spec)
    52→- IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
    53→- IF Q: Answer questions, then redisplay this menu
    54→- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
    55→- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
    56→- IF Any other comments or queries: respond helpfully then redisplay menu
    57→
    58→#### EXECUTION RULES:
    59→
    60→- ALWAYS halt and wait for user input after presenting menu
    61→- ONLY proceed to finalize when user selects 'C'
    62→- After other menu items execution, return to this menu
    63→
    64→### 2. Handle Review Feedback
    65→
    66→a) **If user requests changes:**
    67→
    68→- Make the requested edits to `{wipFile}`
    69→- Re-present the affected sections
    70→- Ask if there are more changes
    71→- Loop until user is satisfied
    72→
    73→b) **If the spec does NOT meet the "Ready for Development" standard:**
    74→
    75→- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs).
    76→- Propose specific improvements to reach the standard.
    77→- Make the edits once the user agrees.
    78→
    79→c) **If user has questions:**
    80→
    81→- Answer questions about the spec
    82→- Clarify any confusing sections
    83→- Make clarifying edits if needed
    84→
    85→### 3. Finalize the Spec
    86→
    87→**When user confirms the spec is good AND it meets the "Ready for Development" standard:**
    88→
    89→a) Update `{wipFile}` frontmatter:
    90→
    91→   ```yaml
    92→   ---
    93→   # ... existing values ...
    94→   status: 'ready-for-dev'
    95→   stepsCompleted: [1, 2, 3, 4]
    96→   ---
    97→   ```
    98→
    99→b) **Rename WIP file to final filename:**
   100→   - Using the `slug` extracted in Section 1
   101→   - Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md`
   102→   - Store this as `finalFile` for use in menus below
   103→
   104→### 4. Present Final Menu
   105→
   106→a) **Display completion message and menu:**
   107→
   108→```
   109→**Tech-Spec Complete!**
   110→
   111→Saved to: {finalFile}
   112→
   113→---
   114→
   115→**Next Steps:**
   116→
   117→[A] Advanced Elicitation - refine further
   118→[R] Adversarial Review - critique of the spec (highly recommended)
   119→[B] Begin Development - start implementing now (not recommended)
   120→[D] Done - exit workflow
   121→[P] Party Mode - get expert feedback before dev
   122→
   123→---
   124→
   125→Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results.
   126→
   127→Copy this prompt to start dev:
   128→
   129→\`\`\`
   130→quick-dev {finalFile}
   131→\`\`\`
   132→
   133→This ensures the dev agent has clean context focused solely on implementation.
   134→```
   135→
   136→b) **HALT and wait for user selection.**
   137→
   138→#### Menu Handling Logic:
   139→
   140→- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
   141→- IF B: Read the entire workflow file at `{quick_dev_workflow}` and follow the instructions with the final spec file (warn: fresh context is better)
   142→- IF D: Exit workflow - display final confirmation and path to spec
   143→- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
   144→- IF R: Execute Adversarial Review (see below)
   145→- IF Any other comments or queries: respond helpfully then redisplay menu
   146→
   147→#### EXECUTION RULES:
   148→
   149→- ALWAYS halt and wait for user input after presenting menu
   150→- After A, P, or R execution, return to this menu
   151→
   152→#### Adversarial Review [R] Process:
   153→
   154→1. **Invoke Adversarial Review Task**:
   155→       > With `{finalFile}` constructed, load and follow the review task. If possible, use information asymmetry: load this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
   156→       <invoke-task>Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml</invoke-task>
   157→       > **Platform fallback:** If task invocation not available, load the task file and follow its instructions inline, passing `{finalFile}` as the content.
   158→       > The task should: review `{finalFile}` and return a list of findings.
   159→
   160→    2. **Process Findings**:
   161→       > Capture the findings from the task output.
   162→       > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
   163→       > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
   164→       > DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
   165→       > Order findings by severity.
   166→       > Number the ordered findings (F1, F2, F3, etc.).
   167→       > If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description
   168→
   169→    3. Return here and redisplay menu.
   170→
   171→### 5. Exit Workflow
   172→
   173→**When user selects [D]:**
   174→
   175→"**All done!** Your tech-spec is ready at:
   176→
   177→`{finalFile}`
   178→
   179→When you're ready to implement, run:
   180→
   181→```
   182→quick-dev {finalFile}
   183→```
   184→
   185→Ship it!"
   186→
   187→---
   188→
   189→## REQUIRED OUTPUTS:
   190→
   191→- MUST update status to 'ready-for-dev'.
   192→- MUST rename file to `tech-spec-{slug}.md`.
   193→- MUST provide clear next-step guidance and recommend fresh context for dev.
   194→
   195→## VERIFICATION CHECKLIST:
   196→
   197→- [ ] Complete spec presented for review.
   198→- [ ] Requested changes implemented.
   199→- [ ] Spec verified against **READY FOR DEVELOPMENT** standard.
   200→- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed.
   201→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


     1→---
     2→title: '{title}'
     3→slug: '{slug}'
     4→created: '{date}'
     5→status: 'in-progress'
     6→stepsCompleted: []
     7→tech_stack: []
     8→files_to_modify: []
     9→code_patterns: []
    10→test_patterns: []
    11→---
    12→
    13→# Tech-Spec: {title}
    14→
    15→**Created:** {date}
    16→
    17→## Overview
    18→
    19→### Problem Statement
    20→
    21→{problem_statement}
    22→
    23→### Solution
    24→
    25→{solution}
    26→
    27→### Scope
    28→
    29→**In Scope:**
    30→{in_scope}
    31→
    32→**Out of Scope:**
    33→{out_of_scope}
    34→
    35→## Context for Development
    36→
    37→### Codebase Patterns
    38→
    39→{codebase_patterns}
    40→
    41→### Files to Reference
    42→
    43→| File | Purpose |
    44→| ---- | ------- |
    45→
    46→{files_table}
    47→
    48→### Technical Decisions
    49→
    50→{technical_decisions}
    51→
    52→## Implementation Plan
    53→
    54→### Tasks
    55→
    56→{tasks}
    57→
    58→### Acceptance Criteria
    59→
    60→{acceptance_criteria}
    61→
    62→## Additional Context
    63→
    64→### Dependencies
    65→
    66→{dependencies}
    67→
    68→### Testing Strategy
    69→
    70→{testing_strategy}
    71→
    72→### Notes
    73→
    74→{notes}
    75→

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Now I have the complete picture. Let me summarize the quick-spec workflow and all human checkpoints:

## Quick-Spec Workflow Summary

The **quick-spec** workflow is a 4-step conversational spec engineering process designed to produce implementation-ready technical specifications. Here's the complete flow with every human checkpoint:

---

## WORKFLOW OVERVIEW

**Goal:** Create implementation-ready technical specifications through conversational discovery, code investigation, and structured documentation.

**Output Standard (Ready for Development):**
- Actionable: Every task has a clear file path and specific action
- Logical: Tasks ordered by dependency
- Testable: All acceptance criteria follow Given/When/Then format
- Complete: All investigation results inlined; no placeholders
- Self-Contained: Fresh agent can implement without reading workflow history

---

## STEP 1: ANALYZE REQUIREMENT DELTA (Step 1 of 4)

**What it does:**
- Checks for work in progress (WIP file)
- Greets user and captures their initial requirement
- Does a quick orient scan of existing code/docs (< 30 seconds)
- Asks informed, specific questions based on what's found
- Captures core understanding (title, slug, problem, solution, scope)
- Creates WIP file from template with initial frontmatter
- Presents checkpoint menu

**Frontmatter updated to:** `stepsCompleted: [1]`, `status: 'in-progress'`

**Human Checkpoints:**

1. **WIP File Check (BLOCKING)** - If WIP exists:
   - Presents existing spec: "Is this what you're here to continue?"
   - Options: [Y] Continue existing, [N] Archive and start fresh
   - HALTS until user selects

2. **Initial Request (REQUIRED)** - "What are we building today?"
   - Waits for user description

3. **Informed Questions (REQUIRED)** - Agent asks specific clarifying questions based on code scan
   - Waits for user answers

4. **Confirm Understanding (REQUIRED)** - "Please confirm the captured understanding"
   - Title, slug, problem statement, solution, in-scope, out-of-scope
   - HALTS until user confirms

5. **Checkpoint Menu (BLOCKING)** - "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2)"
   - Options:
     - [A] → Runs Advanced Elicitation, asks "Accept improvements? (y/n)", redisplays menu
     - [P] → Runs Party Mode collaboration, asks "Accept changes? (y/n)", redisplays menu
     - [C] → Proceeds to Step 2
     - Other → Responds helpfully, redisplays menu
   - HALTS until user selects [C]

---

## STEP 2: MAP TECHNICAL CONSTRAINTS & ANCHOR POINTS (Step 2 of 4)

**What it does:**
- Reads WIP file from Step 1
- Builds on the quick scan from Step 1
- Asks user: "Are there other files/directories I should investigate deeply?"
- Reads and analyzes code, identifies patterns, dependencies, test files
- If clean slate: documents this explicitly
- Captures tech stack, code patterns, files to modify/create, test patterns
- Confirms technical context with user
- Updates WIP file with technical findings
- Presents checkpoint menu

**Frontmatter updated to:** `stepsCompleted: [1, 2]`, updates `tech_stack`, `files_to_modify`, `code_patterns`, `test_patterns`

**Human Checkpoints:**

1. **Investigation Scope (REQUIRED)** - "Are there other files or directories I should investigate deeply?"
   - Waits for user to identify additional investigation targets

2. **Confirm Technical Context (REQUIRED)** - Presents findings:
   - Tech Stack summary
   - Files to Modify count
   - Patterns summary
   - Test Patterns summary
   - Waits for user confirmation or corrections

3. **Checkpoint Menu (BLOCKING)** - "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3)"
   - Options: [A], [P], [C] (same behavior as Step 1), Other
   - HALTS until user selects [C]

---

## STEP 3: GENERATE IMPLEMENTATION PLAN (Step 3 of 4)

**What it does:**
- Reads complete WIP file from Step 2
- Generates specific implementation tasks (discrete, ordered by dependency)
- Each task includes file path and specific action
- Generates testable acceptance criteria in Given/When/Then format covering:
  - Happy path functionality
  - Error handling
  - Edge cases
  - Integration points
- Completes remaining sections (Dependencies, Testing Strategy, Notes)
- Updates WIP file status to 'review' and `stepsCompleted: [1, 2, 3]`
- **Automatically proceeds to Step 4** (no user menu here)

**Frontmatter updated to:** `stepsCompleted: [1, 2, 3]`, `status: 'review'`

**Human Checkpoints:** NONE - This step is fully automated. No user interaction required.

---

## STEP 4: REVIEW & FINALIZE (Step 4 of 4)

**What it does:**
- Reads complete WIP file from Step 3
- Presents complete spec content to user for review
- Presents review menu with options
- Handles user feedback (edits, questions, additional refinement)
- Validates spec meets "Ready for Development" standard
- Finalizes spec by:
  - Updating frontmatter to `status: 'ready-for-dev'` and `stepsCompleted: [1, 2, 3, 4]`
  - Renaming file from `tech-spec-wip.md` to `tech-spec-{slug}.md`
- Presents final menu with next-step options
- Recommends fresh context for implementation

**Frontmatter updated to:** `stepsCompleted: [1, 2, 3, 4]`, `status: 'ready-for-dev'`

**Human Checkpoints:**

1. **Review Menu (BLOCKING)** - Presents complete spec and asks:
   "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode"
   - Options:
     - [C] → Proceeds to finalization
     - [E] → Handles review feedback (Section 2), then redisplays menu
     - [Q] → Answers questions, redisplays menu
     - [A] → Runs Advanced Elicitation, asks "Accept improvements? (y/n)", redisplays menu
     - [P] → Runs Party Mode, asks "Accept changes? (y/n)", redisplays menu
     - Other → Responds helpfully, redisplays menu
   - HALTS until user selects [C]

2. **Edit Handling (LOOPED)** - If [E] selected:
   - Makes requested edits
   - Re-presents affected sections
   - Asks "More changes?" (loops until satisfied)
   - Returns to Review Menu

3. **Final Menu (BLOCKING)** - Once spec is approved and ready:
   "**Next Steps:**
   [A] Advanced Elicitation - refine further
   [R] Adversarial Review - critique of the spec (highly recommended)
   [B] Begin Development - start implementing now (not recommended)
   [D] Done - exit workflow
   [P] Party Mode - get expert feedback before dev"
   - Options:
     - [A] → Runs Advanced Elicitation, redisplays menu
     - [R] → Runs Adversarial Review task (identifies issues/gaps), redisplays menu
     - [B] → Starts quick-dev workflow (warns about fresh context being better)
     - [D] → Exits workflow, displays final confirmation
     - [P] → Runs Party Mode, redisplays menu
     - Other → Responds helpfully, redisplays menu
   - HALTS until user selects

---

## COMPLETE HUMAN CHECKPOINT MAP

Here's every point where a human MUST take an action:

| Step | Checkpoint | Type | User Must... |
|------|-----------|------|--------------|
| 1 | WIP File Check | Blocking Gate | Select [Y/N] to continue existing or start fresh |
| 1 | Initial Request | Required Input | Describe what they're building |
| 1 | Informed Q&A | Required Input | Answer clarifying questions about the feature |
| 1 | Confirm Understanding | Approval Gate | Approve captured title, problem, scope, solution |
| 1 | Step 1 Menu | Blocking Gate | Select [A/P/C] - must select [C] to proceed |
| 2 | Investigation Scope | Required Input | Identify additional files/directories to investigate |
| 2 | Confirm Technical Context | Approval Gate | Approve tech stack, files, patterns, test findings |
| 2 | Step 2 Menu | Blocking Gate | Select [A/P/C] - must select [C] to proceed |
| 3 | (None) | Automated | No human interaction in Step 3 |
| 4 | Review Complete Spec | Blocking Gate | Select [C/E/Q/A/P] - must select [C] to finalize |
| 4 | Edit Feedback (if [E]) | Looped Approval | Approve edits in loop until satisfied |
| 4 | Final Menu | Blocking Gate | Select [A/R/B/D/P] - can refine further or start dev |

---

## KEY INSIGHTS

1. **Steps 1-2 are Heavy on Human Input**: Require specific answers, approvals at multiple gates
2. **Step 3 is Fully Automated**: No user interaction - purely generation
3. **Step 4 is Iterative**: User can request edits multiple times in a loop before finalizing
4. **Optional Enhancement Loops**: At Steps 1, 2, 4 users can invoke Advanced Elicitation [A] or Party Mode [P] to refine specs further
5. **Adversarial Review in Final Step**: Recommended before development to catch issues proactively
6. **Fresh Context Recommended**: After spec is ready, recommends running `quick-dev` in a separate, fresh agent context

The workflow enforces strict sequential execution with clear gates at each checkpoint—users cannot skip steps or proceed without explicit selection of a continuation option.

agentId: a891f091a6272c280 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 28683
tool_uses: 6
duration_ms: 27539</usage>

Prompt:
Read and summarize the full quick-spec workflow and all its step files. I need to understand the current flow, especially where human checkpoints/turns are required.

Read these files in order:
1. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md
2. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md
3. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md
4. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md
5. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md
6. /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/tech-spec-template.md

For each step, identify:
- What the step does
- Whether it requires human input/approval (a human turn)
- What checkpoints exist
- What gates or approvals block progress

Give me the complete picture of every point where a human must interact.


Now I have a clear picture of the quick-spec workflow's human checkpoints. Let me analyze where we can eliminate one human turn.

The current human turns in quick-spec are:

**Step 1:**
1. WIP file check (conditional - only if WIP exists)
2. Initial request - describe what they're building
3. Informed Q&A - answer clarifying questions
4. Confirm understanding - approve captured intent
5. Step 1 menu - select [C] to proceed

**Step 2:**
6. Investigation scope - identify additional files/dirs
7. Confirm technical context - approve findings

8. Step 2 menu - select [C] to proceed

**Step 3:** (none - automated)

**Step 4:**
9. Review complete spec - select [C/E/Q/A/P]
10. Edit feedback (looped, optional)
11. Final menu - select next steps

Looking at which turn to eliminate, the investigation scope question stands out as the most redundant candidate—the agent should be able to intelligently identify relevant files and directories without asking the user to enumerate them. I need to clarify the user's intent before making changes—they want to eliminate one human turn from the quick-spec flow, but there are multiple candidates, so I should ask which specific step they'd prefer to remove or if they want me to recommend the best option based on the analysis I've done.


Good, I've mapped every human turn in quick-spec. Here's the breakdown:

**Step 1 — 5 human turns:**
1. WIP check (conditional)
2. "What are we building?" (initial request)
3. Q&A (clarifying questions)
4. Confirm understanding (approve captured intent)
5. [A][P][C] menu gate

**Step 2 — 3 human turns:**
6. "Any other files I should investigate?" (investigation scope)
7. Confirm technical context (approve findings)
8. [A][P][C] menu gate

**Step 3 — 0 turns** (fully automated)

**Step 4 — 2-3 human turns:**
9. Review spec + [C/E/Q/A/P] menu
10. Final menu (next steps)

Which turn do you want eliminated?


AskUserQuestion

Question: Which human turn should be eliminated from quick-spec?

Choices:
Remove 'Any other files I should investigate?' — agent should figure this out autonomously from codebase exploration. Aligns with QD2 design philosophy.
## Step 2 — Current

```
Agent: Are there other files or directories
       I should investigate deeply?
Human: (must answer)          ← ELIMINATED
Agent: (investigates)
Agent: Here's what I found...
Human: (confirms findings)
```

## Step 2 — After

```
Agent: (autonomously investigates everything)
Agent: Here's what I found...
Human: (confirms findings)
```
Remove one of the blocking menu gates. Agent auto-continues instead of waiting for [C]. User can still interrupt to request elicitation/party mode.
## Current (end of Step 1 or 2)

```
Agent: Checkpoint complete.
       [A] Advanced Elicitation
       [P] Party Mode
       [C] Continue
Human: C                       ← ELIMINATED
```

## After

```
Agent: Checkpoint complete.
       (Tip: interrupt for [A] or [P])
Agent: (auto-continues to next step)
```
Merge the 'confirm understanding' gate into the spec review at Step 4. Don't stop to confirm — just carry forward and let the human review everything at once.
## Step 1 — Current

```
Agent: Here's what I captured:
       Title: ...
       Problem: ...
       Scope: ...
Human: Looks good             ← ELIMINATED
Agent: [A][P][C] menu
```

## Step 1 — After

```
Agent: Here's what I captured:
       Title: ...
       Problem: ...
       Scope: ...
Agent: (auto-continues to investigation)
```


User has answered your questions: "Which human turn should be eliminated from quick-spec?"="#5 or #8: [A][P][C] menu" selected markdown:
## Current (end of Step 1 or 2)

```
Agent: Checkpoint complete.
       [A] Advanced Elicitation
       [P] Party Mode
       [C] Continue
Human: C                       ← ELIMINATED
```

## After

```
Agent: Checkpoint complete.
       (Tip: interrupt for [A] or [P])
Agent: (auto-continues to next step)
```. You can now continue with the user's answers in mind.

Question: Which human turn should be eliminated from quick-spec?

Choices:
Remove 'Any other files I should investigate?' — agent should figure this out autonomously from codebase exploration. Aligns with QD2 design philosophy.
## Step 2 — Current

```
Agent: Are there other files or directories
       I should investigate deeply?
Human: (must answer)          ← ELIMINATED
Agent: (investigates)
Agent: Here's what I found...
Human: (confirms findings)
```

## Step 2 — After

```
Agent: (autonomously investigates everything)
Agent: Here's what I found...
Human: (confirms findings)
```
Remove one of the blocking menu gates. Agent auto-continues instead of waiting for [C]. User can still interrupt to request elicitation/party mode.
## Current (end of Step 1 or 2)

```
Agent: Checkpoint complete.
       [A] Advanced Elicitation
       [P] Party Mode
       [C] Continue
Human: C                       ← ELIMINATED
```

## After

```
Agent: Checkpoint complete.
       (Tip: interrupt for [A] or [P])
Agent: (auto-continues to next step)
```
Merge the 'confirm understanding' gate into the spec review at Step 4. Don't stop to confirm — just carry forward and let the human review everything at once.
## Step 1 — Current

```
Agent: Here's what I captured:
       Title: ...
       Problem: ...
       Scope: ...
Human: Looks good             ← ELIMINATED
Agent: [A][P][C] menu
```

## Step 1 — After

```
Agent: Here's what I captured:
       Title: ...
       Problem: ...
       Scope: ...
Agent: (auto-continues to investigation)
```


The user wants to eliminate the [A][P][C] menu gates. Now let me clarify: both menus (#5 at end of Step 1 and #8 at end of Step 2), or just one?

The user selected "#5 or #8: [A][P][C] menu" — this implies eliminating at least one, possibly both. Let me check — the intent was "Eliminate one human turn." So likely one of the two menus. But since both are the same pattern, the most natural thing is to eliminate both. Let me ask, or just pick the most impactful.

Actually, the user said "Eliminate one human turn" and chose the [A][P][C] menu pattern.

Since the same menu appears in both steps, removing it from just one would be inconsistent. I'll go ahead and eliminate the [A][P][C] menu from both Step 1 and Step 2, which streamlines the flow by removing two interactive gates. the workflow entirely makes sense — both menus are redundant since the user has already confirmed their intent right before each one appears. I'll remove both to streamline the flow.

Now I'm reviewing the step files to see exactly what needs to be modified.


Good — eliminating the [A][P][C] menu gates. Both Step 1 and Step 2 have the identical pattern. Since you said "one human turn" — do you want both removed (they're the same construct), or just one?

I'll go ahead and read the exact sections to modify.


---
name: 'step-01-understand'
description: 'Analyze the requirement delta between current state and what user wants to build'

templateFile: '../tech-spec-template.md'
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 1: Analyze Requirement Delta

**Progress: Step 1 of 4** - Next: Deep Investigation

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- MUST NOT look ahead to future steps.
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Variables from `workflow.md` are available in memory.
- Focus: Define the technical requirement delta and scope.
- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
- Objective: Establish a verifiable delta between current state and target state.

## SEQUENCE OF INSTRUCTIONS

### 0. Check for Work in Progress

a) **Before anything else, check if `{wipFile}` exists:**

b) **IF WIP FILE EXISTS:**

1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
2. Calculate progress: `lastStep = max(stepsCompleted)`
3. Present to user:

```
Hey {user_name}! Found a tech-spec in progress:

**{title}** - Step {lastStep} of 4 complete

Is this what you're here to continue?

[Y] Yes, pick up where I left off
[N] No, archive it and start something new
```

4. **HALT and wait for user selection.**

a) **Menu Handling:**

- **[Y] Continue existing:**
  - Jump directly to the appropriate step based on `stepsCompleted`:
    - `[1]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2)
    - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3)
    - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4)
- **[N] Archive and start fresh:**
  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`

### 1. Greet and Ask for Initial Request

a) **Greet the user briefly:**

"Hey {user_name}! What are we building today?"

b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.

### 2. Quick Orient Scan

a) **Before asking detailed questions, do a rapid scan to understand the landscape:**

b) **Check for existing context docs:**

- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
- Check for any existing stories or specs related to user's request

c) **If user mentioned specific code/features, do a quick scan:**

- Search for relevant files/classes/functions they mentioned
- Skim the structure (don't deep-dive yet - that's Step 2)
- Note: tech stack, obvious patterns, file locations

d) **Build mental model:**

- What's the likely landscape for this feature?
- What's the likely scope based on what you found?
- What questions do you NOW have, informed by the code?

**This scan should take < 30 seconds. Just enough to ask smart questions.**

### 3. Ask Informed Questions

a) **Now ask clarifying questions - but make them INFORMED by what you found:**

Instead of generic questions like "What's the scope?", ask specific ones like:
- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
- "The epics doc mentions X - is this related?"

**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.

b) **If no existing code is found:**

- Ask about intended architecture, patterns, constraints
- Ask what similar systems they'd like to emulate

### 4. Capture Core Understanding

a) **From the conversation, extract and confirm:**

- **Title**: A clear, concise name for this work
- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
- **Problem Statement**: What problem are we solving?
- **Solution**: High-level approach (1-2 sentences)
- **In Scope**: What's included
- **Out of Scope**: What's explicitly NOT included

b) **Ask the user to confirm the captured understanding before proceeding.**

### 5. Initialize WIP File

a) **Create the tech-spec WIP file:**

1. Copy template from `{templateFile}`
2. Write to `{wipFile}`
3. Update frontmatter with captured values:
   ```yaml
   ---
   title: '{title}'
   slug: '{slug}'
   created: '{date}'
   status: 'in-progress'
   stepsCompleted: [1]
   tech_stack: []
   files_to_modify: []
   code_patterns: []
   test_patterns: []
   ---
   ```
4. Fill in Overview section with Problem Statement, Solution, and Scope
5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
6. Write the file

b) **Report to user:**

"Created: `{wipFile}`

**Captured:**

- Title: {title}
- Problem: {problem_statement_summary}
- Scope: {scope_summary}"

### 6. Present Checkpoint Menu

a) **Display menu:**

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"

b) **HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

---

## REQUIRED OUTPUTS:

- MUST initialize WIP file with captured metadata.

## VERIFICATION CHECKLIST:

- [ ] WIP check performed FIRST before any greeting.
- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
- [ ] User selected [C] to continue.


---
name: 'step-02-investigate'
description: 'Map technical constraints and anchor points within the codebase'

wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 2: Map Technical Constraints & Anchor Points

**Progress: Step 2 of 4** - Next: Generate Plan

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- MUST NOT generate the full spec yet (that's Step 3).
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined.
- Focus: Map the problem statement to specific anchor points in the codebase.
- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified.
- Objective: Provide the implementation-ready ground truth for the plan.

## SEQUENCE OF INSTRUCTIONS

### 1. Load Current State

**Read `{wipFile}` and extract:**

- Problem statement and scope from Overview section
- Any context gathered in Step 1

### 2. Execute Investigation Path

**Universal Code Investigation:**

_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._

a) **Build on Step 1's Quick Scan**

Review what was found in Step 1's orient scan. Then ask:

"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?"

b) **Read and Analyze Code**

For each file/directory provided:

- Read the complete file(s)
- Identify patterns, conventions, coding style
- Note dependencies and imports
- Find related test files

**If NO relevant code is found (Clean Slate):**

- Identify the target directory where the feature should live.
- Scan parent directories for architectural context.
- Identify standard project utilities or boilerplate that SHOULD be used.
- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist.

c) **Document Technical Context**

Capture and confirm with user:

- **Tech Stack**: Languages, frameworks, libraries
- **Code Patterns**: Architecture patterns, naming conventions, file structure
- **Files to Modify/Create**: Specific files that will need changes or new files to be created
- **Test Patterns**: How tests are structured, test frameworks used

d) **Look for project-context.md**

If `**/project-context.md` exists and wasn't loaded in Step 1:

- Load it now
- Extract patterns and conventions
- Note any rules that must be followed

### 3. Update WIP File

**Update `{wipFile}` frontmatter:**

```yaml
---
# ... existing frontmatter ...
stepsCompleted: [1, 2]
tech_stack: ['{captured_tech_stack}']
files_to_modify: ['{captured_files}']
code_patterns: ['{captured_patterns}']
test_patterns: ['{captured_test_patterns}']
---
```

**Update the Context for Development section:**

Fill in:

- Codebase Patterns (from investigation)
- Files to Reference table (files reviewed)
- Technical Decisions (any decisions made during investigation)

**Report to user:**

"**Context Gathered:**

- Tech Stack: {tech_stack_summary}
- Files to Modify: {files_count} files identified
- Patterns: {patterns_summary}
- Tests: {test_patterns_summary}"

### 4. Present Checkpoint Menu

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"

**HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

---

## REQUIRED OUTPUTS:

- MUST document technical context (stack, patterns, files identified).
- MUST update `{wipFile}` with functional context.

## VERIFICATION CHECKLIST:

- [ ] Technical mapping performed and documented.
- [ ] `stepsCompleted: [1, 2]` set in frontmatter.