feat: add plan phase and plan gate to the quick flow

AGENTS.md

@@ -22,13 +22,13 @@ This is a **Spec-Kit preset, extension, and bundle**, not an application. It def
 |------|------|
 | `workflows/workflow.yml` | Orchestration: inputs, steps, gates, loops for feature development |
 | `workflows/bugfix-workflow.yml` | Orchestration: standard bug commands, assessment gate, and issue-to-PR finish |
-| `workflows/quick-flow.yml` | Orchestration: lightweight pipeline for trivial changes (no spec/plan/tasks) |
+| `workflows/quick-flow.yml` | Orchestration: lightweight pipeline for trivial changes (quick plan + approval gate, no spec/tasks) |
 | `preset.yml` | Main preset manifest: templates, scripts, version, tags |
 | `presets/sub-agent-delegation/preset.yml` | Delegation preset manifest: the single prepend preamble registered across parallelizable commands |
 | `extension.yml` | Extension manifest: commands, version, tags |
 | `bundle.yml` | Bundle manifest: composes preset + extension + workflows into a single install unit |
 | `scripts/` | Python 3 stdlib runtime and repository-maintenance scripts |
-| `commands/` | Agent system prompts (documentation, documentation-init, finish, quick-implement, quick-review, doc-check) |
+| `commands/` | Agent system prompts (documentation, documentation-init, finish, quick-plan, quick-implement, quick-review, doc-check) |
 | `templates/` | Structured output templates (review-findings, documentation) |
 | `tests/` | Python stdlib unittest suites for runtime scripts and workflow structure |
 
@@ -77,7 +77,8 @@ specs/                       ← Feature directories, one per feature item
     fix.md                   ← Generated by speckit.bug.fix
     test.md                  ← Generated by speckit.bug.test
   <issue>-quick-<slug>/
-    instruction.md           ← Written by speckit.extendedflow.quick-implement
+    instruction.md           ← Written by speckit.extendedflow.quick-plan and quick-implement
+    plan.md                  ← Written by speckit.extendedflow.quick-plan (human-gated)
     review-findings.md       ← QA review output (generated by quick-review)
     doc-check.md             ← Documentation check report (generated by doc-check)
 ```
@@ -105,7 +106,7 @@ specs/                       ← Feature directories, one per feature item
 Safe to remove:
 - `specs/<NNN>-<feature-name>/` — entire feature directory (spec, plan, tasks, research, data-model, quickstart, contracts, checklists)
 - `.specify/bugs/<slug>/` — entire bugfix directory (assessment, fix, test)
-- `specs/<issue>-quick-<slug>/` — entire quick directory (instruction, review-findings, doc-check)
+- `specs/<issue>-quick-<slug>/` — entire quick directory (instruction, plan, review-findings, doc-check)
 - `.specify/feature.json` — current feature pointer
 
 Must preserve:
@@ -120,7 +121,7 @@ Must preserve:
 - **Doc Reconciliation**: The post-implementation step that updates layered documentation and flags code-vs-docs conflicts.
 - **Spec-Kit Contract**: The interface between workflow steps where `stdout` of one step becomes the `args` of the next.
 - **Bugfix Flow**: A standard Spec-Kit bug workflow (`resolve → assess → fix → test → finish`) for surgical bugfixes without spec/plan/tasks generation.
-- **Quick Flow**: A lightweight workflow (`resolve → init-quick → implement → review-fix → doc-check → finish`) for trivial, well-defined changes (label renames, message additions). No spec/plan/tasks generation, no human gates, self-fixing review in a single pass.
+- **Quick Flow**: A lightweight workflow (`resolve → init-quick → quick-plan → plan-gate → implement → review-fix → doc-check → finish`) for trivial, well-defined changes (label renames, message additions). Generates a minimal plan reviewed at a human gate, but no spec or task-list. Self-fixing review in a single pass.
 - **Sub-Agent Delegation**: The `sub-agent-delegation` preset's mechanism-neutral preamble, prepended to the parallelizable core commands. It maps the active integration (read from `.specify/integration.json`) to that backend's sub-agent primitive and falls back to sequential execution when none exists.
 
 ## Known Issues
@@ -130,7 +131,7 @@ Must preserve:
 ## Pointers to Depth
 
 - **Workflow steps & gates**: See `workflows/workflow.yml` (feature flow), `workflows/bugfix-workflow.yml` (bugfix flow), and `workflows/quick-flow.yml` (quick flow)
-- **Agent behaviors**: See `commands/speckit.extendedflow.documentation.md`, `commands/speckit.extendedflow.finish.md`, `commands/speckit.extendedflow.quick-implement.md`, `commands/speckit.extendedflow.quick-review.md`, `commands/speckit.extendedflow.doc-check.md`, plus the standard `speckit.bug.assess`, `speckit.bug.fix`, and `speckit.bug.test` commands from Spec-Kit's `bug` extension. The Feature Flow's QA loop uses the standard `speckit.analyze` and `speckit.implement`/`speckit.converge` commands.
+- **Agent behaviors**: See `commands/speckit.extendedflow.documentation.md`, `commands/speckit.extendedflow.finish.md`, `commands/speckit.extendedflow.quick-plan.md`, `commands/speckit.extendedflow.quick-implement.md`, `commands/speckit.extendedflow.quick-review.md`, `commands/speckit.extendedflow.doc-check.md`, plus the standard `speckit.bug.assess`, `speckit.bug.fix`, and `speckit.bug.test` commands from Spec-Kit's `bug` extension. The Feature Flow's QA loop uses the standard `speckit.analyze` and `speckit.implement`/`speckit.converge` commands.
 - **Output templates**: See `templates/review-findings.md`, `templates/documentation.md`
 - **Input resolution logic**: See `scripts/resolve-spec.py`
 - **Branch creation and verdict extraction**: See `scripts/create-branch.py`, `scripts/check-converge.py`, `scripts/extract-verdict.py`, `scripts/resolve-bug-context.py`, `scripts/check-bug-verdict.py`

README.md

@@ -49,7 +49,7 @@ Extended Flow ships a **family of composable flows** that share issue-to-PR auto
 
 - **Feature Flow** — the SDD lifecycle for new features (`specify → plan → tasks → analyze → implement → converge → documentation → finish`).
 - **Bugfix Flow** — the standard Spec-Kit bug lifecycle (`assess → fix → test → finish`), skipping spec/plan/tasks generation.
-- **Quick Flow** — a lightweight pipeline for trivial, well-defined changes (`implement → review-fix → doc-check → finish`), no spec/plan/tasks, no human gates, self-fixing review in a single pass.
+- **Quick Flow** — a lightweight pipeline for trivial, well-defined changes (`plan → plan-gate → implement → review-fix → doc-check → finish`). A minimal plan is reviewed at a human gate; no spec or task-list, and the self-fixing review runs in a single pass.
 
 See [Flows](docs/flows.md) for the full diagrams and step-by-step breakdown. The family is designed to grow — future flows slot in as peers.
 
@@ -110,7 +110,7 @@ specify workflow run spec-kit-quick-flow \
   --input issue="42"
 ```
 
-**What happens:** The workflow implements the change directly from your instruction, runs a self-fixing review in a single pass, checks documentation impact, then commits and opens a PR. No spec/plan/tasks generation — ideal for label changes, message additions, and other trivial tweaks.
+**What happens:** The workflow writes a minimal plan from your instruction and pauses at a plan gate for your approval, then implements the change, runs a self-fixing review in a single pass, checks documentation impact, and commits and opens a PR. No spec or task-list generation — ideal for label changes, message additions, and other trivial tweaks.
 
 <details>
 <summary><strong>Other input modes</strong></summary>
@@ -203,7 +203,7 @@ A standard Spec-Kit bug lifecycle for surgical bugfixes. It uses `speckit.bug.as
 
 ### Quick Flow
 
-A lightweight pipeline for trivial, well-defined changes. Skips spec/plan/tasks entirely and uses a **self-fixing review** in a single pass. See [docs/flows.md](docs/flows.md#quick-flow) for the full diagram and step table.
+A lightweight pipeline for trivial, well-defined changes. Produces a minimal plan that pauses at a human gate, then implements and uses a **self-fixing review** in a single pass. No spec or task-list. See [docs/flows.md](docs/flows.md#quick-flow) for the full diagram and step table.
 
 ---
 
@@ -233,6 +233,7 @@ Run these standalone outside the workflows:
 | `/speckit.extendedflow.documentation` | Documentation reconciliation only |
 | `/speckit.extendedflow.documentation-init` | Bootstrap documentation for an existing project |
 | `/speckit.extendedflow.finish` | Cleanup, commit, and PR (post-implementation) |
+| `/speckit.extendedflow.quick-plan` | Minimal plan for a trivial change (human-gated) |
 | `/speckit.extendedflow.quick-implement` | Direct implementation for trivial changes |
 | `/speckit.extendedflow.quick-review` | Self-fixing review (review + fix in one pass) |
 | `/speckit.extendedflow.doc-check` | Lightweight documentation impact check |

bundle.yml

@@ -5,7 +5,7 @@ bundle:
   name: "Spec-Kit Extended Flow"
   version: "0.17.0"
   role: "developer"
-  description: "A complete agentic engineering pipeline: SDD workflow with Python runtime scripts, the standard implement/converge loop, living documentation reconciliation, standard Spec-Kit bug flow, and a quick-change pipeline. Installs the main preset (templates + scripts), the integration-agnostic sub-agent delegation preset, the extension (7 commands), and 3 workflows (feature, bugfix, quick) in one operation."
+  description: "A complete agentic engineering pipeline: SDD workflow with Python runtime scripts, the standard implement/converge loop, living documentation reconciliation, standard Spec-Kit bug flow, and a quick-change pipeline. Installs the main preset (templates + scripts), the integration-agnostic sub-agent delegation preset, the extension (8 commands), and 3 workflows (feature, bugfix, quick) in one operation."
   author: "Markus Wondrak"
   repository: "https://github.com/markuswondrak/spec-kit-extended-flow"
   license: "MIT"

commands/speckit.extendedflow.quick-implement.md

@@ -1,15 +1,16 @@
 # Spec-Kit Extended Flow Quick Implement Agent
 
-You are the **Quick Implement Agent** — a focused implementation agent for trivial, well-defined changes. You receive a clear instruction and implement it directly, without spec/plan/tasks generation.
+You are the **Quick Implement Agent** — a focused implementation agent for trivial, well-defined changes. You receive a clear instruction and an approved plan, and implement directly, without spec/task generation.
 
 ## Your Role
 
-You are the implementer for simple changes: label renames, message additions, small tweaks. The instruction you receive IS the specification — it is complete and unambiguous. You do NOT generate specs, plans, or task breakdowns. You implement the change directly.
+You are the implementer for simple changes: label renames, message additions, small tweaks. The instruction you receive IS the specification — it is complete and unambiguous. The quick plan tells you which files to touch and how the change will be verified. You do NOT generate specs or task breakdowns. You implement the change directly.
 
 ## Inputs
 
 1. **Instruction text** — passed as args (from `resolve-spec.py` stdout). This is the complete change request.
 2. **Feature Directory** — read `.specify/feature.json` to determine the current feature directory (e.g., `specs/42-quick-change-login-label`).
+3. **Plan** — read `specs/<feature-dir>/plan.md` (produced by quick-plan and approved at the gate). It names the files to change and the verification approach.
 
 ## Outputs
 
@@ -20,13 +21,15 @@ You are the implementer for simple changes: label renames, message additions, sm
 
 1. Read `.specify/feature.json` to determine the feature directory.
 2. Write the instruction text to `specs/<feature-dir>/instruction.md`. This preserves the original request for the review agent.
-3. Analyze the codebase to locate the relevant code for the requested change.
-4. Implement the change — make the minimal, targeted modification described in the instruction.
-5. Run existing tests to verify no regressions.
-6. Run lints / type-checks to verify code quality.
+3. Read `specs/<feature-dir>/plan.md` for the approved files-to-change and verification approach.
+4. Analyze the codebase to locate the relevant code for the requested change.
+5. Implement the change — make the minimal, targeted modification described in the instruction and plan.
+6. Run existing tests to verify no regressions.
+7. Run lints / type-checks to verify code quality.
 
 ## Constraints
 
+- **Follow the approved plan** — implement the change the plan describes. If the plan is wrong or incomplete, report this and stop rather than expanding scope.
 - **Minimal change** — implement ONLY what the instruction requests. No refactors, no improvements beyond the request.
 - **No scope expansion** — do not add features, fix unrelated bugs, or restructure code.
 - **Preserve existing behavior** — the change must not break any existing tests or functionality.

commands/speckit.extendedflow.quick-plan.md

@@ -0,0 +1,55 @@
+# Spec-Kit Extended Flow Quick Plan Agent
+
+You are the **Quick Plan Agent** — a focused planning agent for trivial, well-defined changes. You receive a clear instruction and produce a short, lightweight plan. The human reviews this plan at a gate before implementation begins.
+
+## Your Role
+
+You are the planning step for simple changes: label renames, message additions, small tweaks. The instruction you receive IS the specification — it is complete and unambiguous. You do NOT generate specs or task breakdowns, and you do NOT write code. You produce a minimal plan that names the files to touch, the exact change, and how it will be verified.
+
+## Inputs
+
+1. **Instruction text** — passed as args (from `resolve-spec.py` stdout). This is the complete change request.
+2. **Feature Directory** — read `.specify/feature.json` to determine the current feature directory (e.g., `specs/42-quick-change-login-label`).
+
+## Outputs
+
+1. **`specs/<feature-dir>/instruction.md`** — the original instruction text, preserved for the review agent.
+2. **`specs/<feature-dir>/plan.md`** — the lightweight plan reviewed at the human gate.
+
+## Steps
+
+1. Read `.specify/feature.json` to determine the feature directory.
+2. Write the instruction text to `specs/<feature-dir>/instruction.md`. This preserves the original request for the review agent.
+3. Analyze the codebase to locate the relevant code for the requested change.
+4. Write `specs/<feature-dir>/plan.md` using the structure below. Keep it short — this is a quick change, not an architecture document.
+5. Do NOT modify source files. Implementation happens in the next step.
+
+## Plan Structure
+
+Write `specs/<feature-dir>/plan.md` with this structure:
+
+```markdown
+# Quick Plan
+
+## Summary
+<One sentence describing the change.>
+
+## Files to Change
+| File | Change |
+|------|--------|
+| <path> | <exact, minimal change> |
+
+## Verification
+<How the change will be verified: tests to run, lints, type-checks, manual check.>
+
+## Risks / Assumptions
+<None, or the assumptions made and anything that may need a design decision.>
+```
+
+## Constraints
+
+- **Minimal plan** — describe ONLY what the instruction requests. No refactors, no improvements beyond the request.
+- **No scope expansion** — do not plan features, unrelated bug fixes, or restructuring.
+- **No code changes** — you plan; you do not implement.
+- **Do NOT generate a full spec or task list** — this is the Quick Flow, not the Feature Flow.
+- If the instruction is ambiguous or requires design decisions, say so in the plan's Risks / Assumptions section and recommend the Feature Flow. The human gate exists to catch this before implementation.

docs/flows.md

@@ -85,36 +85,43 @@ When started from a GitHub issue, the Bugfix Flow creates a `fix/<issue>-<slug>`
 
 ## Quick Flow
 
-A lightweight pipeline for trivial, well-defined changes. It skips spec/plan/tasks generation entirely and uses a **self-fixing review** in a single pass — the reviewer finds issues and fixes them in one step.
+A lightweight pipeline for trivial, well-defined changes. It skips spec and task-list generation; instead it produces a **minimal plan** that a human approves at a gate before implementation. It uses a **self-fixing review** in a single pass — the reviewer finds issues and fixes them in one step.
 
 ```mermaid
 flowchart TD
     A[resolve-spec] --> B{issue?}
     B -->|yes| C[create-branch]
     B -->|no| D[init-quick]
     C --> D
-    D --> E[quick-implement]
-    E --> F[quick-review]
-    F --> G{PASS?}
-    G -->|yes| H[doc-check]
-    G -->|no| I[❌ abort]
-    H --> J[finish]
-    J --> K[✅ done]
+    D --> E[quick-plan]
+    E --> F{plan gate}
+    F -->|approve| G[quick-implement]
+    F -->|reject| H[❌ abort]
+    G --> I[quick-review]
+    I --> J{PASS?}
+    J -->|yes| K[doc-check]
+    J -->|no| H
+    K --> L[finish]
+    L --> M[✅ done]
 ```
 
 1. **Init** — Create or reuse the feature directory and `feature.json` pointer
-2. **Implement** — Direct implementation from the instruction (no tasks.md)
-3. **Review + Fix** — Self-fixing review in a single pass
-4. **Doc Check** — Lightweight documentation impact check
-5. **Finish** — Cleanup, commit, PR
+2. **Plan** — Produce a minimal plan from the instruction (no tasks.md)
+3. **Plan Gate** — Human reviews `plan.md`; approve to implement, reject to stop
+4. **Implement** — Direct implementation from the instruction and approved plan
+5. **Review + Fix** — Self-fixing review in a single pass
+6. **Doc Check** — Lightweight documentation impact check
+7. **Finish** — Cleanup, commit, PR
 
 | Step | Type | Description |
 |------|------|-------------|
 | `resolve-spec` | shell | Resolves the run's `spec`/`file`/`issue` inputs to instruction content |
 | `load-models` | shell | Loads per-step model overrides from `model.config.json` |
 | `create-branch` | shell | *(issue only)* Creates `feature/<issue>-<slug>` branch |
 | `init-quick` | shell | Creates or reuses the feature directory and writes `feature.json` with `type: "quick"` |
-| `quick-implement` | command | Implements the change directly from the instruction |
+| `quick-plan` | command | Produces a minimal `plan.md` from the instruction |
+| `quick-plan-gate` | gate | Human approves or rejects the plan |
+| `quick-implement` | command | Implements the change from the instruction and approved plan |
 | `quick-review` | command | Self-fixing review: reviews and corrects in one pass → PASS or FAIL |
 | `doc-check` | command | Lightweight documentation impact check, flags conflicts |
 | `finish` | command | Cleans up, commits (`chore:` prefix), opens PR when issue provided |

docs/reference.md

@@ -33,6 +33,7 @@ This split exists because Spec-Kit's architecture reserves commands for extensio
 | Documentation init | `commands/speckit.extendedflow.documentation-init.md` | Doc bootstrap agent prompt |
 | Project init | `commands/speckit.extendedflow.project-init.md` | Project analysis + template tailoring agent prompt |
 | Finish agent | `commands/speckit.extendedflow.finish.md` | Cleanup, commit, PR agent prompt |
+| Quick plan | `commands/speckit.extendedflow.quick-plan.md` | Minimal plan agent for trivial changes, reviewed at a human gate |
 | Quick implement | `commands/speckit.extendedflow.quick-implement.md` | Direct implementation agent for trivial changes |
 | Quick review | `commands/speckit.extendedflow.quick-review.md` | Self-fixing review agent (review + fix in one pass) |
 | Doc check | `commands/speckit.extendedflow.doc-check.md` | Lightweight documentation impact check agent |