@dv.nghiem/flowdeck 0.3.7 → 0.3.9

package/dist/services/quick-router.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Quick Router Service
+ *
+ * Provides task classification and stage-sequence routing for the /fd-quick
+ * autonomous workflow launcher.
+ *
+ * This module is the single source of truth for:
+ *   - Classifying user task descriptions into task types
+ *   - Mapping task types to the correct existing stage sequence
+ *   - Computing the next stage given what has already completed
+ *   - Determining whether supervisor clarification is required before proceeding
+ *
+ * It does NOT create new workflows. It routes to the existing commands:
+ *   fd-discuss, fd-design, fd-plan, fd-execute, fd-fix-bug, fd-write-docs, fd-verify
+ *
+ * Autonomy contract:
+ *   - classifyTaskWithContext() must be preferred over classifyTask() when a
+ *     preflight ExplorationResult is available.
+ *   - classificationNeeded is set to false whenever exploration evidence
+ *     supplies the missing context, eliminating the human question entirely.
+ */
+import type { ExplorationResult } from "./preflight-explorer";
+export type TaskType = "feature" | "ui-feature" | "bugfix" | "docs" | "simple" | "ambiguous";
+/** A single stage in a workflow sequence, mapping to an existing fd-* command. */
+export interface WorkflowStage {
+    /** Human-readable stage name */
+    name: string;
+    /** The registered fd-* command that implements this stage */
+    command: string;
+    /** Arguments to pass to the command (if any) */
+    args?: string;
+    /** Whether this stage requires human approval before proceeding */
+    requiresApproval: boolean;
+    /** Whether this stage can be skipped if prerequisites are absent and --override is set */
+    skippable: boolean;
+}
+export interface ClassificationResult {
+    taskType: TaskType;
+    /** 0.0–1.0 confidence in the classification */
+    confidence: number;
+    /** Which signal patterns triggered the classification */
+    signals: string[];
+    /** True when the task is explicitly UI/UX-heavy, requiring design-first */
+    requiresDesign: boolean;
+    /** True when TDD enforcement applies (always true except for docs-only) */
+    requiresTDD: boolean;
+    /** Ordered sequence of stages to execute */
+    stageSequence: WorkflowStage[];
+    /** True when the description is too vague to classify without asking a question */
+    clarificationNeeded: boolean;
+    /** The single clarifying question to ask via supervisor (when clarificationNeeded=true) */
+    clarificationPrompt?: string;
+}
+/**
+ * Classify a free-text task description into a TaskType with a confidence score.
+ *
+ * Signal matching is case-insensitive substring search. Multiple signal hits
+ * increase confidence. The highest-confidence match wins; ties break toward
+ * the more structured workflow type (feature > simple > ambiguous).
+ */
+export declare function classifyTask(description: string): ClassificationResult;
+/**
+ * Build the ordered WorkflowStage array for a given TaskType.
+ * Each stage maps 1:1 to an existing registered fd-* command.
+ */
+export declare function buildStageSequence(taskType: TaskType): WorkflowStage[];
+export interface StageProgress {
+    completedStageNames: string[];
+    blockedAtStage?: string;
+    blockedReason?: string;
+}
+export interface NextStageResult {
+    /** The stage to execute next, or null if all stages are complete */
+    stage: WorkflowStage | null;
+    /** True when all stages have been completed */
+    allComplete: boolean;
+    /** True when execution is blocked at a stage */
+    blocked: boolean;
+    blockedReason?: string;
+    /** Remaining stage names (not counting the returned stage) */
+    remaining: string[];
+}
+/**
+ * Given a stage sequence and the current progress, determine the next
+ * stage to execute.
+ *
+ * Returns null stage when all stages are complete.
+ */
+export declare function getNextStage(sequence: WorkflowStage[], progress: StageProgress): NextStageResult;
+/** The structure written to STATE.md under the `quick_run` key by /fd-quick. */
+export interface QuickRunState {
+    /** Original task description from $ARGUMENTS */
+    taskDescription: string;
+    /** Classification result */
+    taskType: TaskType;
+    confidence: number;
+    requiresDesign: boolean;
+    requiresTDD: boolean;
+    /** Ordered stage names for this run */
+    stageSequence: string[];
+    /** Stages that have been completed */
+    completedStages: string[];
+    /** Current stage being executed, if any */
+    currentStage: string | null;
+    /** Whether the run has been halted */
+    blocked: boolean;
+    blockedReason?: string;
+    /** Supervisor decisions keyed by stage name */
+    supervisorDecisions: Record<string, {
+        decision: string;
+        reasons: string[];
+        timestamp: string;
+    }>;
+    /** ISO timestamp when the run started */
+    startedAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+    /** Final run outcome */
+    outcome: "running" | "complete" | "blocked" | "failed";
+    /**
+     * Preflight exploration snapshot — persisted so later stages can
+     * reuse it without re-running exploration or re-asking the user.
+     */
+    preflightExploration?: {
+        exploredAt: string;
+        techStack: string[];
+        availableCommands: string[];
+        availableSkills: string[];
+        implementationPatterns: string[];
+        evidenceCount: number;
+        /** Whether clarification was resolved via evidence (no human asked) */
+        clarificationResolvedByEvidence: boolean;
+        /** The resolved reason when evidence answered the question */
+        clarificationResolvedReason?: string;
+    };
+    /** Questions that were suppressed by the guard (not sent to human) */
+    suppressedQuestions: string[];
+}
+/**
+ * Create a fresh QuickRunState record for a new /fd-quick run.
+ */
+export declare function createQuickRunState(taskDescription: string, classification: ClassificationResult, exploration?: ExplorationResult): QuickRunState;
+/**
+ * Classify a task description, using repo exploration evidence to resolve
+ * ambiguity before falling back to supervisor clarification.
+ *
+ * Prefer this over `classifyTask` whenever a preflight ExplorationResult is
+ * available. It eliminates unnecessary human questions when the repo already
+ * contains the answer.
+ *
+ * @param description  - Free-text task from the user
+ * @param exploration  - ExplorationResult from exploreRepo()
+ * @param sessionHistory - Questions already asked in this session (for
+ *                         deduplication via the question guard)
+ */
+export declare function classifyTaskWithContext(description: string, exploration: ExplorationResult, sessionHistory?: string[]): ClassificationResult;
+//# sourceMappingURL=quick-router.d.ts.map

package/dist/services/quick-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-router.d.ts","sourceRoot":"","sources":["../../src/services/quick-router.ts"],"names":[],"mappings":"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"}

package/dist/services/quick-router.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Quick Router Tests
+ *
+ * Covers:
+ * - classifyTask: correctly classifies feature, bugfix, ui-feature, docs, simple, ambiguous
+ * - buildStageSequence: returns correct ordered stages for each task type
+ * - getNextStage: returns correct next stage and handles completed / blocked states
+ * - createQuickRunState: initialises state correctly
+ * - /fd-quick routing contracts (supervisor integration points are tested as
+ *   integration-level expectations on the returned stage sequences)
+ */
+export {};
+//# sourceMappingURL=quick-router.test.d.ts.map

package/dist/services/quick-router.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-router.test.d.ts","sourceRoot":"","sources":["../../src/services/quick-router.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/docs/commands.md

@@ -24,7 +24,7 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 | `/fd-multi-repo` | `[list \| add <path> [name] \| remove <name> \| status]` | Multi-repo orchestration |
 | `/fd-translate-intent` | `[vague intent]` | Convert vague request into ranked implementation options |
 | `/fd-ask` | `[question]` | Route question to specialist agent (architect, security, etc.) |
-| `/fd-quick` | `[task description]` | Quick focused task with automatic agent selection |
+| `/fd-quick` | `[task description]` | Autonomous workflow launcher — classifies task, selects correct workflow, runs all stages end-to-end |
 | `/fd-doctor` | — | Check FlowDeck installation and environment health |
 
 ---
@@ -483,34 +483,54 @@ Comprehensive pre-change analysis: impact radar, blast radius, regression predic
 
 ## /fd-quick
 
-**Description:** Execute a focused task without the full workflow. Selects best specialist agent automatically.
+**Description:** Autonomous workflow launcher. Classifies the task, selects the correct existing FlowDeck workflow, and runs all stages end-to-end with minimal user input. Routes all clarifying questions through `@supervisor`.
 
 **Arguments:**
-- `[task description]` — what you need done
-
-**Agent Selection Matrix:**
-
-| Task Type | Agent |
-|-----------|-------|
-| Backend code | @backend-coder |
-| Frontend code | @frontend-coder |
-| DevOps/infra code | @devops |
-| Explore/understand | @code-explorer |
-| Review code | @reviewer |
-| Security review | @security-auditor |
-| Design/architecture | @architect |
-| Write tests | @tester |
-| Documentation | @doc-updater |
-| Research | @researcher |
-| Debug | @debug-specialist |
-| Performance | @performance-optimizer |
-| Build error | @build-error-resolver |
+- `[task description]` — what you need done (any phrasing — the command classifies it)
+
+**Task Classification:**
+
+| Classification | Trigger Signals | Stage Sequence |
+|----------------|-----------------|----------------|
+| `feature` | Substantive description, no specific signals | `discuss → plan → execute → verify` |
+| `ui-feature` | landing page, dashboard, admin panel, app screen, ux flow | `discuss → design → plan → execute → verify` |
+| `bugfix` | fix, bug, error, crash, regression, broken, exception | `discuss → fix-bug → verify` |
+| `docs` | docs, documentation, readme, api docs, write docs | `discuss → write-docs → verify` |
+| `simple` | rename, typo, minor, move file | `execute → verify` |
+| `ambiguous` | vague or too short | *supervisor asks one clarifying question* |
+
+**What it does:**
+1. Classifies the task from `$ARGUMENTS` using signal patterns
+2. Routes ambiguous tasks through `@supervisor` for a single focused clarifying question
+3. Presents the selected stage sequence to the user
+4. Executes each stage in order using the existing registered commands (`/fd-discuss`, `/fd-plan`, etc.)
+5. Gates each stage through `@supervisor` preflight review (approve / revise / block / escalate)
+6. Respects all workflow discipline: TDD gates, design-first gate for UI tasks, plan CONFIRM gate
+7. Pauses only when a supervisor gate requires user approval, or when blocked
+8. Records all routing decisions, stage transitions, and supervisor decisions in STATE.md
+9. On block: explains exactly what stopped execution and what is needed to resume
+
+**What it preserves:**
+- All existing commands (`/fd-discuss`, `/fd-plan`, `/fd-execute`, etc.) remain independently usable
+- TDD enforcement is never bypassed
+- Design-first gate for UI-heavy tasks is enforced
+- Plan CONFIRM gate is always presented to the user
+- Verify pipeline always runs at end
 
 **Example:**
 ```
-/fd-quick find where the session token is validated
-/fd-quick add rate limiting to the API
+/fd-quick add two-factor authentication to the login system
+/fd-quick fix the checkout crash when cart is empty
+/fd-quick build a new analytics dashboard for admin users
+/fd-quick write API documentation for the user service
+/fd-quick rename MAX_RETRIES constant to RETRY_LIMIT
+```
+
+**Resume after a block:**
+```
+/fd-quick <original task description>
 ```
+`/fd-quick` resumes from the last completed stage automatically.
 
 ---
 

package/docs/quick-start.md

@@ -190,6 +190,8 @@ This writes the current execution state to `.planning/STATE.md`. To reload conte
 
 > **Skip to execute for small tasks** — for a quick bug fix, you do not need to run `/fd-discuss` and `/fd-plan`. Use `/fd-fix-bug` directly and let `@debug-specialist` handle the full cycle.
 
+> **Let `/fd-quick` drive the whole workflow** — instead of manually calling each command in sequence, run `/fd-quick <your task>` and the system classifies the task, selects the correct workflow (feature, bug fix, UI-heavy, docs), and runs all stages autonomously. It pauses only when your explicit input is needed (e.g., plan CONFIRM, approval gates). Existing commands remain fully usable standalone.
+
 ---
 
 ← [Back to Index](index.md)

package/docs/workflows.md

@@ -56,7 +56,7 @@ Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` r
 | `/fd-multi-repo` | Multi-repo orchestration | @multi-repo-coordinator, @architect |
 | `/fd-translate-intent` | Convert vague requests to ranked implementation options | @architect, @researcher |
 | `/fd-suggest` | Suggest high-value feature opportunities from codebase signals | @researcher, @architect |
-| `/fd-quick` | Fast focused task execution | @backend-coder/@frontend-coder/@devops or selected specialist |
+| `/fd-quick` | Autonomous workflow launcher — classifies task, runs correct stage sequence end-to-end | @supervisor, @orchestrator, and all workflow agents |
 | `/fd-reflect` | Post-session reflection and skill capture | @auto-learner |
 | `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,16 +45,16 @@
   },
   "homepage": "https://github.com/DVNghiem/FlowDeck#readme",
   "dependencies": {
-    "@opencode-ai/plugin": "^1.4.0"
+    "@opencode-ai/plugin": "^1.14.49"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "bun-types": "^1.3.13",
-    "ejs": "^3.1.9",
-    "typescript": "^5.7.0",
-    "vitest": "^2.0.0"
+    "@types/node": "^25.7.0",
+    "bun-types": "^1.3.14",
+    "ejs": "^5.0.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
-    "@opencode-ai/sdk": "^1.4.0"
+    "@opencode-ai/sdk": "^1.14.49"
   }
 }

package/src/commands/fd-deploy-check.md

@@ -89,7 +89,7 @@ Required fixes before deploy:
 - [ ] [fix 1]
 - [ ] [fix 2]
 
-Run /deploy-check again after fixing.
+Run /fd-deploy-check again after fixing.
 ```
 
 ## No-go conditions (automatic)
@@ -102,7 +102,7 @@ Any of these → automatic NO-GO:
 
 ### Step 4: Code Review Scope (--check=review)
 
-If `/deploy-check --check=review [scope]` provided: review files matching scope.
+If `/fd-deploy-check --check=review [scope]` provided: review files matching scope.
 If no scope: review all files changed since last commit.
 
 ```bash

package/src/commands/fd-discuss.md

@@ -17,10 +17,44 @@ Run a structured requirements discussion session and capture decisions.
 
 ## Process
 
+### Step 0: Autonomous Codebase Exploration
+
+**Before asking the user any question**, explore the repository to gather evidence.
+
+Invoke `@code-explorer` to inspect:
+
+1. **Project files** — `.planning/PROJECT.md` (goals, tech stack, constraints)
+2. **Session state** — `.planning/STATE.md` (current phase, prior decisions)
+3. **Prior discussions** — `.planning/phases/*/DISCUSS.md` (already-captured decisions)
+4. **Tech stack** — `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+5. **Implementation patterns** — `src/` directory structure (services, components, api, etc.)
+6. **AGENTS.md / rules** — any project-level constraints or conventions
+7. **Relevant source files** — files matching keywords in `$ARGUMENTS`
+
+Store exploration findings in the discussion context. These will be used to:
+- Skip questions whose answers are already known from the codebase
+- Inform the `@discusser` agent with concrete evidence
+- Prevent worker agents from emitting questions to the user
+
+### Question suppression rule
+
+After exploration, apply the question guard before each `@discusser` question:
+
+> A `@discusser` question is skipped if:
+> 1. The answer already exists in `PROJECT.md`, `STATE.md`, or prior `DISCUSS.md` files
+> 2. The answer is determinable from the tech stack / implementation patterns
+> 3. The question was already answered in a prior session for this phase
+
+If a question is suppressed, record it in the DISCUSS.md `## Suppressed Questions` section
+with the evidence that answered it.
+
 ### Step 1: Load Context
 
 Read `.planning/PROJECT.md` to understand the project vision and goals.
 Read `.planning/STATE.md` to determine the current phase and context.
+Read any prior `.planning/phases/phase-<N>/DISCUSS.md` for existing decisions.
+
+Use exploration findings (from Step 0) to populate the discusser's starting context.
 
 ### Step 2: Determine Phase
 
@@ -32,11 +66,18 @@ Decisions will be saved to `.planning/phases/phase-{N}/DISCUSS.md`.
 Spawn @discusser agent with:
 - Project context (from PROJECT.md)
 - Current phase number
+- **Preflight exploration findings** (tech stack, patterns, existing decisions)
 - Instructions to ask ONE question per turn
+- Instructions to skip questions already answered by exploration evidence
 
 ### Step 4: Q&A Loop
 
 The @discusser agent asks one question at a time.
+Before each question, the question guard is checked:
+- If the question can be answered from exploration evidence → skip it, record as suppressed
+- If the question was already asked in a prior session for this phase → skip it
+- Otherwise → ask the user
+
 After each user response:
 - Assign D-XX number to any new decision
 - Record: topic, choice, rationale
@@ -44,7 +85,7 @@ After each user response:
 
 Continue until all required topics are covered or user says to stop early.
 
-Structure the discussion:
+Structure the discussion (skip topics already answered by exploration):
 
 1. **Scope** — What exactly needs to be built/changed? What is out of scope?
 2. **Constraints** — Technical constraints, deadlines, dependencies?
@@ -53,6 +94,7 @@ Structure the discussion:
 5. **UI classification** — Is this task user-facing and UI-heavy (website/app/dashboard/admin/landing/onboarding)?
 
 Ask questions one at a time. Wait for answers before proceeding.
+Do not ask about things the codebase already reveals.
 
 ## Decision Recording
 
@@ -65,12 +107,24 @@ After the discussion, write `.planning/phases/phase-<N>/DISCUSS.md`:
 **Date:** <timestamp>
 **Topic:** <topic>
 
+## Preflight Evidence Used
+
+- Tech stack: <detected stack>
+- Prior decisions loaded: <yes/no>
+- Questions suppressed by evidence: <N>
+
 ## Decisions
 
 D-01: [Topic] — [Decision] ([Rationale])
 D-02: [Topic] — [Decision] ([Rationale])
 ...
 
+## Suppressed Questions
+
+(Questions that were answered by repo evidence and not asked of the user)
+- "<question>" → answered by: <evidence source>
+...
+
 ## Open Questions
 
 - <any unresolved items>
@@ -83,19 +137,22 @@ D-02: [Topic] — [Decision] ([Rationale])
 ## D-05 Compliance
 
 - Loads PROJECT.md + current phase STATE.md
-- Invokes @discusser agent
+- **Performs codebase exploration before any question is asked (Step 0)**
+- Invokes @discusser agent with full exploration context
 - Saves decisions with D-XX numbering to DISCUSS.md
 - One question at a time (no compound questions)
+- Questions suppressed when answered by evidence
 
 ## Completion
 
-Report: decisions captured, file path, and suggest running `/fd-plan`.
+Report: decisions captured, questions suppressed, file path, and suggest running `/fd-plan`.
 If UI-heavy, also suggest running `/fd-design --mode=draft` before `/fd-execute`.
 
 ## Error Handling
 
 D-03: Fail fast with clear error
-- If PROJECT.md not found: error with "Run /new-project first"
+- If PROJECT.md not found: error with "Run /fd-new-project first"
 - If STATE.md not found: error with "Project not initialized"
 - If @discusser fails: error with "Discusser agent unavailable"
+- If @code-explorer fails during preflight: proceed with reduced evidence (log warning)
 - No partial state saved on error

package/src/commands/fd-map-codebase.md

@@ -19,7 +19,7 @@ Check if `.codebase/` directory already exists. If present, warn and require con
 
 If `.codebase/` directory already exists:
 ```
-Warning: .codebase/ already exists. Running /map-codebase will overwrite existing docs.
+Warning: .codebase/ already exists. Running /fd-map-codebase will overwrite existing docs.
 Continue? (y/n)
 ```
 If user declines, abort. If user confirms, proceed.

package/src/commands/fd-multi-repo.md

@@ -16,16 +16,16 @@ Orchestrates a feature or fix that spans multiple repositories in a microservice
 - A shared library is being upgraded with a breaking change
 - You need a coordinated rollout across services
 
-Do not use for single-repo work. Use `/new-feature` instead.
+Do not use for single-repo work. Use `/fd-new-feature` instead.
 
 ## Prerequisites
 
 Before running this flow:
 1. `.planning/config.json` has a `sub_repos` array with the relevant repos registered
 2. All `path` values in the registry resolve to actual directories on disk
-3. A description of the intended change is available (from `/discuss` or passed directly)
+3. A description of the intended change is available (from `/fd-discuss` or passed directly)
 
-If the registry is empty or not set up, run `/multi-repo --add` first.
+If the registry is empty or not set up, run `/fd-multi-repo --add` first.
 
 ## Behavior
 

package/src/commands/fd-plan.md

@@ -17,7 +17,7 @@ D-06: Verify DISCUSS.md exists and is confirmed.
 
 If no DISCUSS.md found:
 ```
-Error: DISCUSS.md not found. Run /discuss [topic] first.
+Error: DISCUSS.md not found. Run /fd-discuss [topic] first.
 ```
 
 If DISCUSS.md exists but not confirmed: