@dv.nghiem/flowdeck 0.4.7 → 0.4.8

package/docs/reference/workflow-router.md

@@ -0,0 +1,337 @@
+# Workflow Router API Reference
+
+## Overview
+
+The Workflow Router (`src/services/workflow-router.ts`) provides **adaptive workflow routing** for FlowDeck. It replaces the fixed pipeline (`discuss → plan → execute → review`) with a scoring-based system that selects the minimal sufficient workflow for each task.
+
+## When to Use
+
+Use the workflow router when:
+- You need to select a workflow class based on task characteristics
+- You want to score tasks across multiple dimensions (complexity, risk, confidence)
+- You need to escalate from a lightweight workflow to a richer one
+- You want to log routing decisions for observability
+
+## Workflow Classes
+
+| Class | Stages | When Selected |
+|-------|--------|---------------|
+| `quick` | `execute → verify` | Score ≥ 0.75 for simple/docs tasks |
+| `standard` | `plan → execute → verify` | Default for normal implementations |
+| `explore` | `discuss → plan → execute → verify` | Low confidence (< 0.60) or ambiguous tasks |
+| `ui-heavy` | `discuss → design → plan → execute → verify` | UI/UX-heavy tasks |
+| `bugfix` | `discuss → fix-bug → verify` | Bug signal dominates classification |
+| `docs-only` | `write-docs → verify` | Documentation-only changes |
+| `verify-heavy` | `plan → execute → verify` | High blast radius (≥ 5 files) or sensitive paths |
+
+## Types
+
+### `WorkflowClass`
+
+```typescript
+type WorkflowClass =
+  | "quick"
+  | "standard"
+  | "explore"
+  | "ui-heavy"
+  | "bugfix"
+  | "docs-only"
+  | "verify-heavy"
+```
+
+### `RoutingCriteria`
+
+Input data for the routing decision.
+
+```typescript
+interface RoutingCriteria {
+  taskType: TaskType
+  complexity: "cheap" | "standard" | "expensive"
+  confidence: number        // 0.0–1.0
+  blastRadius: number       // estimated files affected
+  isSensitive: boolean      // touches auth/payment/infra paths
+  codebaseFreshness: "fresh" | "stale" | "unknown"
+  requiresTests: boolean
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `taskType` | `TaskType` | Classification from `quick-router.ts` |
+| `complexity` | `"cheap" \| "standard" \| "expensive"` | From `model-router.ts` |
+| `confidence` | `number` | Classification confidence (0.0–1.0) |
+| `blastRadius` | `number` | Estimated number of files affected |
+| `isSensitive` | `boolean` | Whether the task touches sensitive paths (auth, payment, etc.) |
+| `codebaseFreshness` | `"fresh" \| "stale" \| "unknown"` | Whether `.codebase/` mapping is recent (< 24h) |
+| `requiresTests` | `boolean` | Whether the task needs tests |
+
+### `RoutingScore`
+
+Score breakdown for a routing decision.
+
+```typescript
+interface RoutingScore {
+  simplicity: number        // 0–0.30
+  confidence: number        // 0–0.20
+  lowRisk: number           // 0–0.20
+  knownCodebase: number     // 0–0.15
+  cheapComplexity: number   // 0–0.15
+  total: number             // 0–1.0
+}
+```
+
+### `WorkflowRoute`
+
+The complete routing result.
+
+```typescript
+interface WorkflowRoute {
+  workflowClass: WorkflowClass
+  stages: WorkflowStage[]
+  criteria: RoutingCriteria
+  scores: RoutingScore
+  reason: string
+}
+```
+
+### `RoutingDecision`
+
+Persisted routing decision with escalation history.
+
+```typescript
+interface RoutingDecision {
+  route: WorkflowRoute
+  escalationHistory: EscalationEvent[]
+  skippedStages: string[]
+  loggedAt: string
+}
+```
+
+## Functions
+
+### `scoreTaskForRouting`
+
+Scores a task across 5 weighted dimensions.
+
+```typescript
+export function scoreTaskForRouting(criteria: RoutingCriteria): RoutingScore
+```
+
+**Scoring dimensions:**
+
+| Dimension | Weight | Formula |
+|-----------|--------|---------|
+| Simplicity | 30% | `taskType === "simple" ? 1 : 0` |
+| Confidence | 20% | `confidence` (raw value) |
+| Low Risk | 20% | `!isSensitive && blastRadius < 3 ? 1 : 0` |
+| Known Codebase | 15% | `codebaseFreshness === "fresh" ? 1 : 0` |
+| Cheap Complexity | 15% | `complexity === "cheap" ? 1 : 0` |
+
+**Example:**
+
+```typescript
+import { scoreTaskForRouting } from "@/services/workflow-router"
+
+const criteria = {
+  taskType: "simple",
+  complexity: "cheap",
+  confidence: 1.0,
+  blastRadius: 1,
+  isSensitive: false,
+  codebaseFreshness: "fresh",
+  requiresTests: false,
+}
+
+const score = scoreTaskForRouting(criteria)
+// score.simplicity = 0.30
+// score.confidence = 0.20
+// score.lowRisk = 0.20
+// score.knownCodebase = 0.15
+// score.cheapComplexity = 0.15
+// score.total = 1.00
+```
+
+### `buildAdaptiveStageSequence`
+
+Selects the workflow class and stage sequence based on criteria.
+
+```typescript
+export function buildAdaptiveStageSequence(criteria: RoutingCriteria): WorkflowRoute
+```
+
+**Selection rules** (evaluated in order):
+
+1. **Quick workflow**: `totalScore >= 0.75` AND (`taskType === "simple"` OR `taskType === "docs"`)
+2. **Bugfix workflow**: `taskType === "bugfix"`
+3. **Docs-only workflow**: `taskType === "docs"` AND `totalScore < 0.75`
+4. **UI-heavy workflow**: `taskType === "ui-feature"`
+5. **Verify-heavy workflow**: `blastRadius >= 5` OR `isSensitive`
+6. **Explore workflow**: `confidence < 0.60` OR `taskType === "ambiguous"`
+7. **Standard workflow**: default fallback
+
+**Example:**
+
+```typescript
+import { buildAdaptiveStageSequence } from "@/services/workflow-router"
+
+const route = buildAdaptiveStageSequence({
+  taskType: "simple",
+  complexity: "cheap",
+  confidence: 1.0,
+  blastRadius: 1,
+  isSensitive: false,
+  codebaseFreshness: "fresh",
+  requiresTests: false,
+})
+
+// route.workflowClass = "quick"
+// route.stages = [{ name: "execute", command: "fd-execute", skippable: true }, ...]
+// route.reason = "Quick workflow: score 1.00 >= 0.75 for simple task"
+```
+
+### `shouldEscalate`
+
+Determines if a workflow should escalate to a richer class during execution.
+
+```typescript
+export function shouldEscalate(
+  currentClass: WorkflowClass,
+  evidence: {
+    blastRadius?: number
+    isSensitive?: boolean
+    testsFailing?: boolean
+    designNeeded?: boolean
+  },
+): WorkflowClass | null
+```
+
+**Escalation rules:**
+
+| From | To | Trigger |
+|------|-----|---------|
+| `quick` | `standard` | `blastRadius > 3` |
+| `quick` | `standard` | `testsFailing` |
+| `standard` | `verify-heavy` | `isSensitive` |
+| `standard` | `verify-heavy` | `blastRadius >= 5` |
+| `standard` | `ui-heavy` | `designNeeded` |
+
+Returns `null` if no escalation is needed.
+
+**Example:**
+
+```typescript
+import { shouldEscalate } from "@/services/workflow-router"
+
+// During execution, more files are affected than expected
+const newClass = shouldEscalate("quick", { blastRadius: 4 })
+// newClass = "standard"
+```
+
+### `logRoutingDecision`
+
+Appends a routing decision to `.codebase/WORKFLOW_ROUTING.jsonl`.
+
+```typescript
+export function logRoutingDecision(dir: string, decision: RoutingDecision): void
+```
+
+**Example:**
+
+```typescript
+import { logRoutingDecision, buildAdaptiveStageSequence } from "@/services/workflow-router"
+
+const route = buildAdaptiveStageSequence(criteria)
+const decision = {
+  route,
+  escalationHistory: [],
+  skippedStages: ["discuss", "plan"],
+  loggedAt: new Date().toISOString(),
+}
+
+logRoutingDecision("/path/to/project", decision)
+// Appends JSON line to .codebase/WORKFLOW_ROUTING.jsonl
+```
+
+### `getHistoricalCompliance`
+
+Reads historical stage compliance from `.codebase/SCORECARDS.jsonl`.
+
+```typescript
+export function getHistoricalCompliance(dir: string, taskType: TaskType): number | null
+```
+
+Averages the `stageCompliance` dimension from scorecard entries matching the given `taskType`. Returns `null` if no data exists.
+
+**Example:**
+
+```typescript
+import { getHistoricalCompliance } from "@/services/workflow-router"
+
+const compliance = getHistoricalCompliance("/path/to/project", "feature")
+// compliance = 0.85 (or null if no scorecards)
+```
+
+## Integration
+
+### With `quick-router.ts`
+
+The `buildAdaptiveWorkflow()` function in `quick-router.ts` calls `buildAdaptiveStageSequence()` to replace the deprecated `buildStageSequence()`:
+
+```typescript
+// Old (fixed)
+const stages = buildStageSequence("feature") // always returns discuss→plan→execute→verify
+
+// New (adaptive)
+const result = buildAdaptiveWorkflow(description, exploration)
+// result.workflowClass = "quick" | "standard" | ...
+// result.stageSequence = dynamically selected stages
+```
+
+### With `supervisor-binding.ts`
+
+The supervisor reads `workflowClass` from `SupervisorContext` to apply conditional phase checks:
+
+- `quick` / `docs-only` workflows skip the `fd-execute` phase check
+- `quick` / `docs-only` workflows skip the UI-heavy design approval check
+
+### With `planning-state-lib.ts`
+
+New `PlanningState` fields track routing decisions:
+
+```typescript
+interface PlanningState {
+  workflowClass?: string
+  skippedStages?: string[]
+  escalationHistory?: Array<{ from: string; to: string; trigger: string; reason: string; timestamp: string }>
+  routingScores?: { simplicity: number; confidence: number; lowRisk: number; knownCodebase: number; cheapComplexity: number; total: number }
+  routingReason?: string
+}
+```
+
+## File Output
+
+### `.codebase/WORKFLOW_ROUTING.jsonl`
+
+Each routing decision is appended as a JSON line:
+
+```json
+{
+  "route": {
+    "workflowClass": "quick",
+    "stages": [...],
+    "criteria": { ... },
+    "scores": { "simplicity": 0.30, "confidence": 0.20, "lowRisk": 0.20, "knownCodebase": 0.15, "cheapComplexity": 0.15, "total": 1.00 },
+    "reason": "Quick workflow: score 1.00 >= 0.75 for simple task"
+  },
+  "escalationHistory": [],
+  "skippedStages": ["discuss", "plan"],
+  "loggedAt": "2026-06-02T04:30:00Z"
+}
+```
+
+## See Also
+
+- [`quick-router.ts`](../services/quick-router.md) — Task classification and stage sequencing
+- [`model-router.ts`](../services/model-router.md) — Task complexity classification
+- [`supervisor-binding.ts`](../services/supervisor-binding.md) — Policy enforcement
+- [`planning-state-lib.ts`](../tools/planning-state-lib.md) — State management

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",

package/src/commands/fd-discuss.md

@@ -195,7 +195,14 @@ RQ-01: [question]
 
 ## Next Steps
 
-- Run /fd-plan to create implementation plan from these decisions
+Read STATE.md to determine `workflowClass`:
+
+- For `quick` workflows: Next step is `/fd-execute` (planning skipped for simple tasks).
+- For `docs-only` workflows: Next step is `/fd-write-docs`.
+- For `bugfix` workflows: Next step is `/fd-fix-bug`.
+- For all other workflows: Run `/fd-plan` to create implementation plan from these decisions.
+
+If the workflow class is not yet set, default to `/fd-plan`.
 ```
 
 ## D-05 Compliance

package/src/commands/fd-execute.md

@@ -1,5 +1,5 @@
 ---
-description: Execute feature implementation from PLAN.md — TDD pipeline with backend-coder, frontend-coder, devops, tester, reviewer, and STATE.md update
+description: Execute feature implementation from PLAN.md — adaptive TDD pipeline with backend-coder, frontend-coder, devops, tester, reviewer, and STATE.md update
 argument-hint: [--phase=N] [--override]
 ---
 
@@ -57,6 +57,21 @@ BEHAVIOR → RED → GREEN → REFACTOR → next step
 
 ## Process
 
+## Workflow-Aware Execution
+
+Read STATE.md to determine the workflow class:
+- `quick` / `docs-only`: Skip full TDD cycle. Run tests once after changes.
+- `standard` / `explore` / `ui-heavy` / `verify-heavy` / `bugfix`: Follow full TDD cycle.
+
+For `quick` workflows:
+- Step 5 (Write Failing Tests) → Skip. Run existing tests after implementation.
+- Step 6 (Confirm RED) → Skip.
+- Step 7 (Implement Minimum) → Run directly.
+- Step 8 (Confirm GREEN) → Run tests after implementation.
+- Step 9 (Refactor) → Optional. Skip if no refactoring needed.
+
+For all other workflows, follow the full TDD cycle below.
+
 ### Step 1: Guard Check
 
 Verify prerequisites:
@@ -99,13 +114,18 @@ Check TDD stage — only proceed if stage is appropriate for the step.
 
 ### Step 5: Write Failing Tests (RED)
 
-Spawn `@tester` to write tests for the step's behavior:
+For `quick` / `docs-only` workflows: **SKIP this step.** Run existing tests after implementation in Step 8.
+
+For all other workflows, spawn `@tester` to write tests for the step's behavior:
 - **Tests MUST fail** before implementation
 - Cover acceptance cases and edge cases
 - Use AAA pattern (Arrange-Act-Assert)
 
 ### Step 6: Confirm RED
 
+For `quick` / `docs-only` workflows: **SKIP this step.**
+
+For all other workflows:
 Run failing tests:
 - **GUARD: Do NOT proceed to Step 7 until tests fail**
 - If tests pass unexpectedly, tests don't correctly describe behavior
@@ -125,7 +145,9 @@ Run tests:
 
 ### Step 9: Refactor (REFACTOR)
 
-Only if GREEN:
+For `quick` / `docs-only` workflows: **SKIP this step** unless the user explicitly requests cleanup.
+
+For all other workflows, only if GREEN:
 - Clean up code for this step
 - Remove dead code
 - Improve readability

package/src/commands/fd-new-feature.md

@@ -1,5 +1,5 @@
 ---
-description: Start a new feature — initialize feature context in .planning/, capture description, and guide through discuss → plan → execute → verify
+description: Start a new feature — initialize feature context in .planning/, classify the task, select the adaptive workflow, and guide through the minimal sufficient stage sequence
 argument-hint: [feature name or description]
 ---
 
@@ -65,20 +65,113 @@ Update the current phase entry in STATE.md:
 - Set `status` to `defined`
 - Set `last_action` to `"Feature defined: $ARGUMENTS"`
 
-### Step 4: Present Feature Workflow
+### Step 4: Classify and Present Workflow
+
+Classify the task using `classifyTask($ARGUMENTS)` and score it for routing.
+
+Record the classification in STATE.md:
+```yaml
+workflowClass: <quick|standard|explore|ui-heavy|bugfix|docs-only|verify-heavy>
+routingScores:
+  simplicity: <0-1>
+  confidence: <0-1>
+  lowRisk: <0-1>
+  knownCodebase: <0-1>
+  cheapComplexity: <0-1>
+  total: <0-1>
+routingReason: <why this workflow was selected>
+```
+
+Report what was created and present the next steps based on workflow class:
+
+For `quick` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: quick (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next step:
+  1. /fd-execute          — run implementation directly (discuss and plan skipped)
+```
+
+For `standard` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: standard (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
 
-Report what was created and present the next steps clearly:
+Next steps (in order):
+  1. /fd-plan             — create implementation plan
+  2. /fd-execute          — run TDD pipeline to implement the plan
+  3. /fd-verify           — run full test + review pipeline
+```
 
+For `explore` workflows:
 ```
 ✅ Feature initialized: $ARGUMENTS
    Phase: <N>
+   Workflow: explore (score: <total>)
    File: .planning/phases/phase-<N>/FEATURE.md
 
 Next steps (in order):
   1. /fd-discuss          — capture requirements, scope, and acceptance criteria
   2. /fd-plan             — create implementation plan from discussion decisions
   3. /fd-execute          — run TDD pipeline to implement the plan
-  4. /fd-verify           — run full test + review + deploy-check pipeline
+  4. /fd-verify           — run full test + review pipeline
+```
+
+For `ui-heavy` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: ui-heavy (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next steps (in order):
+  1. /fd-discuss          — capture requirements
+  2. /fd-design           — create design system and wireframes
+  3. /fd-plan             — create implementation plan
+  4. /fd-execute          — run TDD pipeline
+  5. /fd-verify           — run full test + review pipeline
+```
+
+For `bugfix` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: bugfix (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next steps (in order):
+  1. /fd-discuss          — reproduce and confirm the bug
+  2. /fd-fix-bug          — fix with regression test
+  3. /fd-verify           — verify the fix
+```
+
+For `docs-only` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: docs-only (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next step:
+  1. /fd-write-docs       — write documentation directly
+```
+
+For `verify-heavy` workflows:
+```
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   Workflow: verify-heavy (score: <total>)
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next steps (in order):
+  1. /fd-plan             — create detailed implementation plan
+  2. /fd-execute          — implement with enhanced verification
+  3. /fd-verify           — run full test + security review + deploy-check
 ```
 
 ## Error Handling

package/src/commands/fd-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Create detailed implementation plan from DISCUSS.md decisions — research-first, save PLAN.md, update STATE.md, require CONFIRM before execution
+description: Create detailed implementation plan — research-first, adaptive guard check (skip discuss for quick workflows), save PLAN.md, update STATE.md, require CONFIRM before execution
 argument-hint: [--phase=N] [--yes]
 ---
 
@@ -50,14 +50,24 @@ If research is stale or missing:
 
 ### Step 1: Guard Check
 
-D-06: Verify DISCUSS.md exists and is confirmed.
+D-06: Verify prerequisites for planning.
 
-If no DISCUSS.md found:
+Read STATE.md to check `workflowClass`:
+
+**For `quick` / `docs-only` workflows:**
+- DISCUSS.md is NOT required.
+- Proceed directly to Step 2.
+- Log: "Quick workflow — skipping DISCUSS.md guard"
+
+**For all other workflows:**
+- Verify DISCUSS.md exists and is confirmed.
+
+If no DISCUSS.md found (and not quick/docs-only):
 ```
 Error: DISCUSS.md not found. Run /fd-discuss [topic] first.
 ```
 
-If DISCUSS.md exists but not confirmed:
+If DISCUSS.md exists but not confirmed (and not quick/docs-only):
 ```
 Error: DISCUSS.md not yet confirmed. Complete the discuss phase first.
 ```

package/src/commands/fd-quick.md

@@ -1,5 +1,5 @@
 ---
-description: Autonomous workflow launcher — classifies the task, selects the correct existing workflow, and runs the full stage sequence (discuss → plan → execute → verify and variants) end-to-end with minimal user input
+description: Autonomous workflow launcher — classifies the task, selects the adaptive workflow class via scoring, and runs the minimal sufficient stage sequence end-to-end with minimal user input
 argument-hint: [task description]
 ---
 
@@ -86,14 +86,14 @@ question are resolved by evidence (e.g., tech stack, existing patterns, prior de
 
 ### Signal Classification Table
 
-| Task Type | Strong Signal Keywords | Stage Sequence |
-|-----------|------------------------|----------------|
-| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause, why is, stack trace | `discuss → fix-bug → verify` |
-| **ui-feature** | landing page, dashboard, admin panel, app screen, onboarding, wireframe, design system, ux flow, web app, website, responsive layout, navbar, modal, sidebar, frontend page | `discuss → design → plan → execute → verify` |
-| **docs** | docs, documentation, readme, api docs, usage guide, write docs, document, changelog, tutorial, docstring | `discuss → write-docs → verify` |
-| **simple** | rename, move file, minor, typo, update constant, update config, bump version, one-liner | `execute → verify` |
-| **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
-| **ambiguous** | (short, vague, or unclear — only after exploration cannot resolve) | *(clarify via supervisor — see Step 3)* |
+| Task Type | Strong Signal Keywords | Workflow Class | Typical Stages |
+|-----------|------------------------|----------------|----------------|
+| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause, why is, stack trace | `bugfix` | `discuss → fix-bug → verify` |
+| **ui-feature** | landing page, dashboard, admin panel, app screen, onboarding, wireframe, design system, ux flow, web app, website, responsive layout, navbar, modal, sidebar, frontend page | `ui-heavy` | `discuss → design → plan → execute → verify` |
+| **docs** | docs, documentation, readme, api docs, usage guide, write docs, document, changelog, tutorial, docstring | `docs-only` | `write-docs → verify` |
+| **simple** | rename, move file, minor, typo, update constant, update config, bump version, one-liner | `quick` | `execute → verify` |
+| **feature** | (substantive description, 8+ words, no above signals) | `standard` | `plan → execute → verify` |
+| **ambiguous** | (short, vague, or unclear — only after exploration cannot resolve) | `explore` | `discuss → plan → execute → verify` |
 
 ### Classification Rules
 
@@ -104,6 +104,25 @@ question are resolved by evidence (e.g., tech stack, existing patterns, prior de
 5. **Feature**: substantive description (8+ words) with no specific signal type.
 6. **Ambiguous** (only when exploration cannot resolve): description is too short (<5 words) or matches a bare imperative with no object (e.g., "improve", "add", "make it better") AND repo evidence does not clarify scope or type.
 
+### Adaptive Workflow Selection
+
+After classification, the router scores the task across multiple dimensions:
+- **Simplicity** (30%): Is this a simple, focused change?
+- **Confidence** (20%): How well does the description match known patterns?
+- **Low Risk** (20%): Is blast radius < 3 files and no sensitive paths?
+- **Known Codebase** (15%): Is the codebase mapping fresh (< 24h)?
+- **Cheap Complexity** (15%): Is the task cheap (classify, validate, summarize)?
+
+The workflow class is selected based on the total score and task type:
+- Score >= 0.75 + simple/docs → `quick` workflow
+- Bug signals dominate → `bugfix` workflow
+- UI signals present → `ui-heavy` workflow
+- Blast radius >= 5 or sensitive paths → `verify-heavy` workflow
+- Confidence < 0.60 or ambiguous → `explore` workflow
+- Default → `standard` workflow
+
+The router prefers the lightest workflow that is sufficient. Escalation occurs during execution if the initial path proves insufficient.
+
 Record the classification result:
 ```yaml
 quick_run:
@@ -288,15 +307,23 @@ If execution cannot continue at any stage:
 
 ---
 
-## Workflow Discipline (Non-Negotiable)
+## Workflow Discipline (Adaptive)
+
+The following gates apply based on the selected workflow class:
+
+- **Design-first**: `ui-heavy` tasks MUST complete the `design` stage before `execute`. No override unless user explicitly requests it.
+- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR for `standard`, `explore`, `ui-heavy`, and `verify-heavy` workflows. `quick` and `docs-only` workflows run tests after changes instead.
+- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM (for workflows that include planning).
+- **Regression test**: `bugfix` requires a failing regression test before implementation.
+- **Verify**: All workflows end with `/fd-verify` when code files are changed. `quick` workflows may skip verify if no code was changed.
+
+### Skipped Stages
 
-These gates from the existing workflow system are **never bypassed by /fd-quick**:
+For `quick` and `docs-only` workflows, the following stages are intentionally skipped:
+- `discuss` — requirements are clear from the task description
+- `plan` — the task is small enough to not need a formal plan
 
-- **Design-first**: `ui-feature` tasks MUST complete the `design` stage (with `@design` approval and handoff) before `execute` can begin. No `--override` unless user explicitly requests it.
-- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR. `/fd-quick` does not skip tests.
-- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM. `/fd-quick` presents the plan and waits.
-- **Regression test**: `fix-bug` requires a failing regression test before implementation (per `/fd-fix-bug`).
-- **Verify**: All workflows end with `/fd-verify` to confirm all checks pass before marking complete.
+Skipped stages are logged in STATE.md under `skippedStages` with the reason "lightest sufficient workflow".
 
 ---