@dv.nghiem/flowdeck 0.3.8 → 0.3.9

package/README.md

@@ -172,104 +172,3 @@ Agents not listed in `agents` inherit the active OpenCode model. See [Configurat
 ## License
 
 MIT
-
-
----
-
-## Quick Install
-
-### Method 1: curl (recommended)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
-```
-
-### Method 2: npx (no git required)
-
-```bash
-npx @dv.nghiem/flowdeck install
-```
-
-See [Installation](docs/installation.md) for prerequisites, verification steps, and environment variables.
-
----
-
-## Core Workflow
-
-FlowDeck structures every feature through a six-step cycle:
-
-```
-/fd-new-project → /fd-new-feature → /fd-discuss → /fd-plan → /fd-execute → /fd-verify
-```
-
-| Step | Command | What happens |
-|------|---------|--------------|
-| **Setup** | `/fd-new-project MyApp` | Creates `.planning/` directory with `PROJECT.md`, `STATE.md`, and `ROADMAP.md` |
-| **Define Feature** | `/fd-new-feature "…"` | Initialize feature context, creates `FEATURE.md` in current phase |
-| **Discuss** | `/fd-discuss` | `@discusser` runs structured Q&A, saves decisions to `DISCUSS.md` |
-| **Plan** | `/fd-plan` | `@planner` builds a wave-structured `PLAN.md`; you type `CONFIRM` to proceed |
-| **Execute** | `/fd-execute` | `@orchestrator` delegates to `@architect`, `@backend-coder`, `@tester`, `@reviewer` via TDD |
-| **Verify** | `/fd-verify` | Full test suite, code review, security scan, and deploy check |
-
-State is written to `.planning/STATE.md` after each phase. Use `/fd-checkpoint` to save mid-session and `/fd-resume` to reload context in a new session.
-
----
-
-## Command Reference
-
-### Workflow commands
-
-| Command | Purpose |
-|---------|---------|
-| `/fd-new-project` | Bootstrap a new project with PROJECT.md, ROADMAP.md, STATE.md |
-| `/fd-map-codebase` | Analyse and index the codebase into structured `.codebase/` files |
-| `/fd-new-feature` | Define a new feature and initialize feature context |
-| `/fd-discuss` | Pre-planning structured Q&A to capture decisions |
-| `/fd-plan` | Generate a wave-structured execution plan from decisions |
-| `/fd-execute` | Implement feature with TDD discipline and parallel agents |
-| `/fd-verify` | Full verification pipeline: tests, code review, security scan, deploy check |
-| `/fd-fix-bug` | Diagnose, fix, and verify a bug with regression test |
-| `/fd-write-docs` | Explore APIs and generate accurate documentation |
-| `/fd-deploy-check` | Pre-deploy safety check with test, security, and build verification |
-| `/fd-status` | View project progress, roadmap, and workspace overview |
-| `/fd-checkpoint` | Save a session checkpoint to STATE.md |
-| `/fd-resume` | Reload STATE.md and PLAN.md to continue interrupted session |
-| `/fd-reflect` | Post-session reflection or capture patterns as reusable skills |
-| `/fd-multi-repo` | Multi-repo orchestration — list, add, remove, or status |
-| `/fd-translate-intent` | Convert vague requests into ranked implementation options |
-| `/fd-suggest` | Analyze the codebase and suggest high-value feature opportunities |
-| `/fd-ask` | Smart agent dispatch — routes to specialist by keyword |
-| `/fd-quick` | Focused task with automatic agent selection |
-| `/fd-doctor` | Check FlowDeck installation and environment health |
-
-### Analysis commands
-
-These umbrella commands consolidate multiple analysis modules into focused entry points:
-
-| Command | Purpose |
-|---------|---------|
-| `/fd-translate-intent` | Convert vague requests into ranked implementation options with tradeoffs |
-| `/fd-suggest` | Combined opportunity and risk analysis (impact, volatility, failures, and skill gaps) |
-| `/fd-deploy-check` | Pre-change release safety checks and review routing |
-| `/fd-verify` | Standalone verification for tests, review, and security checks |
-
-See [docs/workflows.md](docs/workflows.md) for details on how analysis commands work.
-
----
-
-## Documentation
-
-| File | Description |
-|------|-------------|
-| [docs/index.md](docs/index.md) | Full documentation table of contents |
-| [docs/installation.md](docs/installation.md) | Prerequisites, install methods, verification, and uninstall |
-| [docs/quick-start.md](docs/quick-start.md) | First 15 minutes — step-by-step walkthrough |
-| [docs/configuration.md](docs/configuration.md) | `opencode.json`, project config, environment variables, plugin tools |
-| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Full agent and skill usage reference with examples |
-| [docs/workflows.md](docs/workflows.md) | Command architecture and workflow patterns |
-
----
-
-## License
-
-MIT

package/dist/hooks/compaction-hook.d.ts

@@ -6,7 +6,8 @@
  * Context includes:
  * 1. FlowDeck planning state (phase, status, pending steps)
  * 2. Recently edited files (from SessionFileTracker)
- * 3. Structured 8-section summary prompt
+ * 3. Historical session summaries from memory store
+ * 4. Structured 8-section summary prompt
  *
  * Inspired by oh-my-openagent's compaction-context-injector and
  * ECC's experimental.session.compacting handler.

package/dist/hooks/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAoDxD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,OAAO,EAAE,kBAAkB,IAGzB,QAAQ;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,mBA8BjD"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAqDxD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,OAAO,EAAE,kBAAkB,IAGzB,QAAQ;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC7B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,mBAsCjD"}

package/dist/hooks/session-start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-start.d.ts","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAkElC"}
+{"version":3,"file":"session-start.d.ts","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwElC"}

package/dist/index.js

@@ -2452,7 +2452,7 @@ async function guardRailsHook(ctx, input, _output) {
     if (!existsSync18(planningDirPath))
       return;
     if (!existsSync18(codebaseDirectory)) {
-      throw new Error(`[flowdeck] WARNING: .codebase/ not found. Run /map-codebase to map the codebase.`);
+      throw new Error(`[flowdeck] WARNING: .codebase/ not found. Run /fd-map-codebase to map the codebase.`);
     }
     const execMode = resolveExecutionMode(configPath, null);
     if (execMode === "review-only") {
@@ -2691,6 +2691,7 @@ async function sessionStartHook(ctx) {
       flowdeck_status: "no_plan",
       flowdeck_warning: "Run /fd-new-project or /fd-map-codebase to initialize.",
       flowdeck_has_codebase: existsSync20(codebaseDirectory),
+      flowdeck_session_context: getContextForDirectory(ctx.directory),
       ...workspaceRoot && config?.sub_repos ? {
         flowdeck_workspace_root: workspaceRoot,
         flowdeck_sub_repos: config.sub_repos,
@@ -2704,12 +2705,14 @@ async function sessionStartHook(ctx) {
     const content = readFileSync17(stateFilePath, "utf-8");
     const state = parseState(content);
     const currentPhase = state["current_phase"] || {};
+    const sessionContext = getContextForDirectory(ctx.directory);
     const result = {
       flowdeck_phase: currentPhase["phase"] ?? null,
       flowdeck_status: currentPhase["status"] ?? null,
       flowdeck_steps_pending: currentPhase["steps_pending"] ?? null,
       flowdeck_last_action: currentPhase["last_action"] ?? null,
-      flowdeck_has_codebase: existsSync20(codebaseDirectory)
+      flowdeck_has_codebase: existsSync20(codebaseDirectory),
+      flowdeck_session_context: sessionContext
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -2724,7 +2727,8 @@ async function sessionStartHook(ctx) {
       flowdeck_phase: null,
       flowdeck_status: "error",
       flowdeck_warning: "State file unreadable. Continuing without flowdeck context.",
-      flowdeck_has_codebase: existsSync20(codebaseDirectory)
+      flowdeck_has_codebase: existsSync20(codebaseDirectory),
+      flowdeck_session_context: getContextForDirectory(ctx.directory)
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -3366,6 +3370,12 @@ function createCompactionHook(ctx, tracker) {
         sections.push(`- … and ${edited.length - 20} more`);
       sections.push("");
     }
+    const sessionContext = getContextForDirectory(ctx.directory);
+    if (sessionContext) {
+      sections.push("## Previous Sessions Context");
+      sections.push(sessionContext);
+      sections.push("");
+    }
     output.context.push(sections.join(`
 `));
     output.prompt = STRUCTURED_SUMMARY_PROMPT.trim();
@@ -3568,6 +3578,15 @@ function createFlowDeckMcps() {
       oauth: false
     };
   }
+  if (!disabled.has("github")) {
+    mcps.github = {
+      type: "remote",
+      url: "https://api.githubcopilot.com/mcp/",
+      enabled: true,
+      ...process.env.GITHUB_TOKEN ? { headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } } : {},
+      oauth: false
+    };
+  }
   return mcps;
 }
 

package/dist/mcp/index.d.ts

@@ -1,12 +1,13 @@
 /**
  * FlowDeck built-in MCP server configurations.
  *
- * Three free, read-only remote MCPs are enabled by default:
+ * Four free, read-only remote MCPs are enabled by default:
  *   - context7    https://mcp.context7.com/mcp  (library docs lookup)
  *   - websearch   https://mcp.exa.ai/mcp        (web search via Exa)
  *   - grep_app    https://mcp.grep.app           (code search)
+ *   - github      https://api.githubcopilot.com/mcp/  (GitHub code search)
  *
- * Disable individual MCPs with: FLOWDECK_DISABLE_MCP=context7,websearch,grep_app
+ * Disable individual MCPs with: FLOWDECK_DISABLE_MCP=context7,websearch,grep_app,github
  */
 type RemoteMcp = {
     type: "remote";

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAOD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAuC9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,QAAQ,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAOD,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAmD9D"}

package/dist/services/command-validator.d.ts

@@ -43,6 +43,17 @@ export declare function auditTextForInvalidCommands(text: string): AuditResult;
  * a note that the command is unavailable. Leaves valid commands untouched.
  */
 export declare function rewriteInvalidCommandRefs(text: string): string;
+/**
+ * Combined full audit: checks both invalid /fd-* command references AND
+ * bare /word references missing the fd- prefix. Use this for file integrity tests.
+ */
+export interface FullAuditResult extends AuditResult {
+    /** Bare /word references that are missing the fd- prefix (e.g. /plan → /fd-plan) */
+    barePrefixErrors: string[];
+    /** True if any issue was found — either invalid /fd-* refs or bare prefix errors */
+    hasAnyIssue: boolean;
+}
+export declare function auditTextFull(text: string): FullAuditResult;
 /**
  * Return the full canonical command inventory for inspection/testing.
  */

package/dist/services/command-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-validator.d.ts","sourceRoot":"","sources":["../../src/services/command-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE,uBAAuB,EAAE,CAAA;IAClC,KAAK,EAAE,uBAAuB,EAAE,CAAA;IAChC,UAAU,EAAE,OAAO,CAAA;CACpB;AAQD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CAmB7E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAqBrE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAEvD"}
+{"version":3,"file":"command-validator.d.ts","sourceRoot":"","sources":["../../src/services/command-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,OAAO,EAAE,uBAAuB,EAAE,CAAA;IAClC,KAAK,EAAE,uBAAuB,EAAE,CAAA;IAChC,UAAU,EAAE,OAAO,CAAA;CACpB;AAYD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CAmB7E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAG/D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAqBrE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,oFAAoF;IACpF,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,oFAAoF;IACpF,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAQ3D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAEvD"}

package/dist/services/preflight-explorer.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Preflight Explorer Service
+ *
+ * Performs autonomous codebase exploration before any clarifying question is
+ * emitted to the user. Both /fd-quick and /fd-discuss run this first.
+ *
+ * Contract:
+ *   1. exploreRepo(dir) → ExplorationResult   (what exists in the project)
+ *   2. canAnswerFromEvidence(question, result) → boolean  (suppress logic)
+ *   3. shouldSuppressQuestion(q, result, history) → SuppressResult
+ *   4. deriveTaskContext(task, result) → DerivedTaskContext (task-relative findings)
+ *
+ * This module reads the filesystem synchronously so it can be used in both
+ * synchronous test harnesses and async agent runtimes.
+ */
+export interface ExplorationResult {
+    /** Whether .planning/STATE.md was found */
+    hasStateMD: boolean;
+    /** Whether .planning/PROJECT.md was found */
+    hasProjectMD: boolean;
+    /** Whether AGENTS.md was found at repo root */
+    hasAgentsMD: boolean;
+    /** Whether .planning/phases/ has any prior phase directories */
+    hasPriorPhases: boolean;
+    /** Whether .planning/phases/ has any DISCUSS.md from prior sessions */
+    hasPriorDiscussions: boolean;
+    /** fd-* command names found on disk (from src/commands/*.md) */
+    availableCommands: string[];
+    /** Agent names registered in this FlowDeck installation */
+    availableAgents: string[];
+    /** Skill directory names found on disk (from src/skills/ subdirectories) */
+    availableSkills: string[];
+    /** Tech stack indicators inferred from package.json / go.mod / Cargo.toml etc. */
+    techStack: string[];
+    /** Config keys present in flowdeck.json if it exists */
+    configKeys: string[];
+    /** Rules / governance keys declared in flowdeck.json */
+    governanceEnabled: boolean;
+    /** Implementation pattern hints inferred from src/ directory layout */
+    implementationPatterns: string[];
+    /** Relative paths of files that seem relevant to the task keywords */
+    relevantFiles: string[];
+    /** Evidence items that can answer common scoping questions */
+    evidenceItems: EvidenceItem[];
+    /** ISO timestamp when exploration ran */
+    exploredAt: string;
+}
+export interface EvidenceItem {
+    /** The kind of question this evidence answers */
+    answersQuestion: EvidenceQuestionKind;
+    /** Human-readable evidence summary */
+    summary: string;
+    /** Source path (relative) */
+    source: string;
+}
+export type EvidenceQuestionKind = "what-tech-stack" | "is-project-initialized" | "what-is-current-phase" | "what-patterns-exist" | "is-ui-heavy" | "has-existing-tests" | "has-existing-docs" | "has-ci-cd" | "what-agents-available" | "what-commands-available" | "what-skills-available" | "has-prior-decisions" | "has-governance";
+export interface DerivedTaskContext {
+    /** Whether the task appears to touch frontend/UI code based on repo evidence */
+    likelyUITask: boolean;
+    /** Whether the task appears to touch API/backend based on repo evidence */
+    likelyBackendTask: boolean;
+    /** Whether CI/CD config exists (relevant for deploy tasks) */
+    hasCICD: boolean;
+    /** Whether existing tests exist in the project */
+    hasTests: boolean;
+    /** Whether existing documentation exists */
+    hasDocs: boolean;
+    /** Whether governance layer is active */
+    hasGovernance: boolean;
+    /** Relevant files for this specific task */
+    relevantFiles: string[];
+    /** Tech stack summary */
+    techStack: string[];
+}
+export interface SuppressResult {
+    /** Whether the question should be suppressed */
+    suppress: boolean;
+    /** Reason for suppression (if suppressed) */
+    reason?: string;
+    /** True when the question was answered by repo evidence (vs. session dedup) */
+    answeredByEvidence?: boolean;
+    /** The evidence that answers the question (if suppressed) */
+    evidence?: EvidenceItem[];
+}
+/**
+ * Explore the repository at `dir` and return structured findings.
+ * All filesystem reads are synchronous so this can be called in test harnesses.
+ *
+ * @param dir - Absolute path to repo root (or closest available directory)
+ */
+export declare function exploreRepo(dir: string): ExplorationResult;
+/**
+ * Narrow the exploration result to what is specifically relevant for a given task.
+ * Populates `relevantFiles` based on task keywords.
+ */
+export declare function deriveTaskContext(taskDescription: string, result: ExplorationResult, dir: string): DerivedTaskContext;
+/**
+ * Determine whether a candidate question should be suppressed because it can
+ * already be answered from repo evidence.
+ *
+ * A question is suppressed when:
+ *   1. The repo contains direct evidence that answers it, OR
+ *   2. It was already asked in the current session history, OR
+ *   3. It is a trivially answerable question given known project state
+ */
+export declare function shouldSuppressQuestion(question: string, result: ExplorationResult, sessionHistory: string[]): SuppressResult;
+/**
+ * Check if a specific question can be answered from the exploration result alone.
+ */
+export declare function canAnswerFromEvidence(question: string, result: ExplorationResult): boolean;
+/**
+ * Attempt to resolve a `clarificationNeeded` classification using exploration
+ * context. Returns an updated `clarificationNeeded` flag and an optional
+ * resolved task type hint.
+ *
+ * Called by quick-router after classifyTask when clarificationNeeded=true.
+ */
+export interface ExplorationRefinement {
+    /** Whether clarification is still required after applying exploration data */
+    clarificationStillNeeded: boolean;
+    /** Reason clarification is no longer needed (if resolved) */
+    resolvedReason?: string;
+    /**
+     * Evidence-based context to pass to @supervisor if clarification is still needed.
+     * This lets the supervisor ask a tighter question.
+     */
+    supervisorContext?: string;
+}
+export declare function refineClassification(clarificationPrompt: string, result: ExplorationResult, sessionHistory: string[]): ExplorationRefinement;
+//# sourceMappingURL=preflight-explorer.d.ts.map

package/dist/services/preflight-explorer.d.ts.map

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

package/dist/services/preflight-explorer.test.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Preflight Explorer Tests
+ *
+ * Covers:
+ * - exploreRepo: discovers commands, agents, skills, tech stack from filesystem
+ * - canAnswerFromEvidence: correctly identifies suppressible questions
+ * - shouldSuppressQuestion: suppresses answered / duplicate questions
+ * - deriveTaskContext: narrows findings to task-relevant context
+ * - refineClassification: resolves ambiguous classification via evidence
+ * - createQuestionGuard: tracks asked questions and prevents duplicates
+ * - filterQuestions: returns only questions that pass the guard
+ * - needsSupervisorClarification: returns false when all questions are answered
+ * - classifyTaskWithContext: uses exploration to resolve ambiguity
+ * - createQuickRunState: persists exploration snapshot
+ * - /fd-quick performs codebase exploration before asking questions
+ * - /fd-discuss performs codebase exploration before asking questions
+ * - repo evidence prevents unnecessary human questions
+ * - supervisor-agent receives only genuine ambiguity
+ * - worker agents do not ask ad hoc questions
+ * - feature/bug/UI/docs tasks route correctly after preflight
+ * - exploration results are stored and reused
+ * - repeated question suppression works
+ */
+export {};
+//# sourceMappingURL=preflight-explorer.test.d.ts.map

package/dist/services/preflight-explorer.test.d.ts.map

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

package/dist/services/question-guard.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Question Guard Service
+ *
+ * Prevents redundant or unnecessary questions from being emitted to the user.
+ *
+ * Both /fd-quick and /fd-discuss use this guard before forwarding any
+ * clarifying question to @supervisor. Worker agents MUST NOT call ask_user
+ * directly — they check this guard first, and if the answer exists in repo
+ * evidence or session history, the question is dropped.
+ *
+ * Contract:
+ *   1. createQuestionGuard(history?)    → QuestionGuard instance
+ *   2. guard.check(question, evidence)  → CheckResult
+ *   3. guard.record(question)           → void
+ *   4. guard.getAsked()                 → string[]
+ *
+ * Only questions that pass the guard should be forwarded to @supervisor.
+ * @supervisor asks the human. Worker agents never ask the human directly.
+ */
+import type { ExplorationResult } from "./preflight-explorer";
+export interface CheckResult {
+    /** Whether the question should be allowed through to @supervisor */
+    allow: boolean;
+    /** Reason the question was blocked (when allow=false) */
+    blockReason?: string;
+    /** Whether the block was due to repo evidence answering it */
+    answeredByEvidence?: boolean;
+    /** Whether the block was due to a duplicate question */
+    duplicate?: boolean;
+}
+export interface QuestionGuard {
+    /**
+     * Check whether a question should be forwarded to @supervisor.
+     *
+     * Returns allow=true only when:
+     *   - The question has not been asked before in this session
+     *   - The question cannot be answered from repo evidence
+     *   - The question is not trivially implied by known state
+     */
+    check(question: string, exploration: ExplorationResult | null): CheckResult;
+    /**
+     * Record that a question was asked. Call this after forwarding to @supervisor
+     * so future identical questions are suppressed.
+     */
+    record(question: string): void;
+    /** Return all questions recorded in this guard instance. */
+    getAsked(): string[];
+    /** Reset the guard (for new session/run). */
+    reset(): void;
+}
+/**
+ * Create a QuestionGuard.
+ *
+ * @param initialHistory - Questions already asked in this session (for
+ *   persistence across restarts). Pass an empty array for new sessions.
+ */
+export declare function createQuestionGuard(initialHistory?: string[]): QuestionGuard;
+/**
+ * Convenience: check a list of candidate questions and return only those
+ * that should be forwarded to @supervisor. Records allowed questions.
+ */
+export declare function filterQuestions(candidates: string[], guard: QuestionGuard, exploration: ExplorationResult | null): string[];
+/**
+ * Determine whether supervisor clarification is warranted at all.
+ * Returns false when:
+ *   - No questions remain after evidence filtering
+ *   - All questions were answered by the exploration result
+ *
+ * Call this before invoking @supervisor to avoid empty escalations.
+ */
+export declare function needsSupervisorClarification(questions: string[], guard: QuestionGuard, exploration: ExplorationResult | null): boolean;
+/**
+ * Strict check for worker agents (coder, planner, tester, etc.).
+ *
+ * Worker agents MUST NOT ask the human directly. They must either:
+ *   a) use repo evidence (this returns { canProceed: true, evidence })
+ *   b) report missing data to orchestrator/supervisor
+ *
+ * This function decides which path to take.
+ */
+export interface WorkerAgentDecision {
+    /** True when the worker can proceed using evidence alone */
+    canProceed: boolean;
+    /** True when the worker must stop and report missing data upward */
+    mustEscalate: boolean;
+    /** Evidence that allows the worker to proceed (when canProceed=true) */
+    evidence?: string;
+    /** What data is missing (when mustEscalate=true) */
+    missingData?: string;
+}
+export declare function workerAgentDecision(requiredInfo: string, exploration: ExplorationResult): WorkerAgentDecision;
+//# sourceMappingURL=question-guard.d.ts.map

package/dist/services/question-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-guard.d.ts","sourceRoot":"","sources":["../../src/services/question-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAG7D,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAA;IACd,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,WAAW,CAAA;IAC3E;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,4DAA4D;IAC5D,QAAQ,IAAI,MAAM,EAAE,CAAA;IACpB,6CAA6C;IAC7C,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,GAAE,MAAM,EAAO,GAAG,aAAa,CA0ChF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,MAAM,EAAE,CASV;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EAAE,EACnB,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAAG,IAAI,GACpC,OAAO,CAGT;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,4DAA4D;IAC5D,UAAU,EAAE,OAAO,CAAA;IACnB,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAA;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,GAC7B,mBAAmB,CAmBrB"}

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

@@ -12,7 +12,14 @@
  *
  * 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 {
@@ -110,9 +117,41 @@ export interface QuickRunState {
     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): QuickRunState;
+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

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

package/package.json

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

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,13 +137,15 @@ 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
@@ -98,4 +154,5 @@ D-03: Fail fast with clear error
 - 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

@@ -25,7 +25,7 @@ Before running this flow:
 2. All `path` values in the registry resolve to actual directories on disk
 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-quick.md

@@ -6,9 +6,10 @@ argument-hint: [task description]
 # Quick — Autonomous Workflow Launcher
 
 Run the correct FlowDeck workflow automatically for any task. This command:
-- Classifies the task type
+- Explores the codebase first before asking any questions
+- Classifies the task type using both text signals and repo evidence
 - Selects the appropriate existing workflow and stage sequence
-- Routes all clarifying questions through `@supervisor`
+- Routes all clarifying questions through `@supervisor` (only when evidence cannot answer)
 - Executes each stage in order using the existing registered commands
 - Stops only when blocked, awaiting approval, or fully verified
 
@@ -16,18 +17,72 @@ Run the correct FlowDeck workflow automatically for any task. This command:
 
 ---
 
+## Step 0: Autonomous Preflight Exploration
+
+**Before asking the human anything**, explore the repository to build evidence.
+
+Invoke `@code-explorer` to inspect the following in parallel:
+
+1. **Repository structure** — `.planning/STATE.md`, `.planning/PROJECT.md`, `AGENTS.md`
+2. **Available commands** — enumerate `src/commands/*.md` filenames
+3. **Available agents** — enumerate `src/agents/*.ts` filenames
+4. **Available skills** — enumerate `src/skills/` directory names
+5. **Workflow config** — read `flowdeck.json` if present (governance, models)
+6. **Tech stack** — read `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+7. **Implementation patterns** — inspect `src/` top-level directories
+8. **Prior decisions** — check `.planning/phases/*/DISCUSS.md` files
+9. **Relevant files** — find source files matching keywords in `$ARGUMENTS`
+
+Store the exploration snapshot in STATE.md under `quick_run.preflightExploration`:
+
+```yaml
+quick_run:
+  preflightExploration:
+    exploredAt: <ISO timestamp>
+    techStack: [...]
+    availableCommands: [...]
+    availableSkills: [...]
+    implementationPatterns: [...]
+    evidenceCount: <N>
+    clarificationResolvedByEvidence: false
+    suppressedQuestions: []
+```
+
+**This step is mandatory. Do not proceed to Step 1 until exploration is complete.**
+
+### Question suppression rule
+
+After exploration, invoke the question guard before emitting any question:
+
+> A question may only be forwarded to `@supervisor` if:
+> 1. It cannot be answered by the exploration evidence
+> 2. It has not already been asked in the current session
+> 3. It is required to safely select the correct workflow
+
+If the question can be answered from repo evidence, suppress it and log it in
+`quick_run.suppressedQuestions`. Do not present it to the user.
+
+---
+
 ## Step 1: Pre-flight State Check
 
 1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
 2. Read `.planning/STATE.md` to determine if a `quick_run` entry already exists for this session.
    - If `quick_run.outcome` is `running` or `blocked`: **resume from the last completed stage** (skip to Step 5).
-   - Otherwise: proceed to Step 2.
+   - If `quick_run.preflightExploration` exists and `exploredAt` is recent (< 5 min): reuse it, skip Step 0.
+   - Otherwise: proceed to Step 0 then Step 2.
 
 ---
 
 ## Step 2: Classify the Task
 
-Parse `$ARGUMENTS` using the signal table below to determine task type and required stage sequence.
+Use **both** text-signal matching and preflight exploration evidence:
+
+Call `classifyTaskWithContext(description, explorationResult)` from `quick-router.ts`.
+
+This resolves ambiguous descriptions using repo evidence before flagging
+`clarificationNeeded`. Most short descriptions that would normally prompt a
+question are resolved by evidence (e.g., tech stack, existing patterns, prior decisions).
 
 ### Signal Classification Table
 
@@ -38,7 +93,7 @@ Parse `$ARGUMENTS` using the signal table below to determine task type and requi
 | **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 input) | *(clarify first — see Step 3)* |
+| **ambiguous** | (short, vague, or unclear — only after exploration cannot resolve) | *(clarify via supervisor — see Step 3)* |
 
 ### Classification Rules
 
@@ -47,7 +102,7 @@ Parse `$ARGUMENTS` using the signal table below to determine task type and requi
 3. **Docs signals**: if "docs", "documentation", "readme", or "write docs" is present without implementation signals, classify as `docs`.
 4. **Simple**: if "rename", "typo", "minor", or "move file" is present and description is a single, scoped operation.
 5. **Feature**: substantive description (8+ words) with no specific signal type.
-6. **Ambiguous**: description is too short (<5 words) or matches a bare imperative with no object (e.g., "improve", "add", "make it better").
+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.
 
 Record the classification result:
 ```yaml
@@ -66,21 +121,25 @@ quick_run:
 
 ---
 
-## Step 3: Supervisor-Gated Clarification (when needed)
+## Step 3: Supervisor-Gated Clarification (only when exploration cannot resolve)
 
 **Only proceed to Step 4 when classification confidence is sufficient.**
 
-If classification is `ambiguous` OR confidence is low (description < 5 words or no clear signal):
+If classification is `ambiguous` AND exploration evidence did not resolve it:
 
-1. Invoke `@supervisor` (preflight review of `fd-quick` command) with the partial task description.
-2. Present the supervisor's single clarifying question to the user. **Ask ONE question only.**
+1. Invoke `@supervisor` (preflight review of `fd-quick` command) with:
+   - The partial task description
+   - The preflight exploration snapshot (tech stack, patterns, prior decisions)
+   - The `clarificationPrompt` from the classification (already enriched with context)
+2. `@supervisor` presents the single clarifying question to the user. **Ask ONE question only.**
 3. Wait for the user's answer.
 4. Re-classify using the combined original description + the user's answer.
 5. If confidence is still low after one clarification round, route to `feature` with a note in STATE.md.
 
 **All clarification goes through `@supervisor`. Do not have specialist agents ask questions directly.**
+**Do not ask questions that can be answered from the exploration evidence.**
 
-Example supervisor clarification questions (the supervisor selects the most relevant):
+Example supervisor clarification questions (only when evidence is absent):
 - "Is this a new feature, a bug fix, or a documentation task?"
 - "Does this involve building or changing a user-facing UI (page, dashboard, component)?"
 - "Can you describe the specific bug — what is the expected vs actual behavior?"
@@ -97,6 +156,7 @@ Task classified as: <task type>
 Stage sequence:     <stage-1> → <stage-2> → ... → <stage-N>
 Requires design:    <yes / no>
 Requires TDD:       <yes / no>
+Evidence used:      <N> items from preflight exploration
 
 Running /fd-quick autonomously. I will proceed through each stage and pause only
 if I need approval, encounter a blocker, or complete the full sequence.
@@ -134,13 +194,15 @@ Before executing the stage, invoke `@supervisor` (preflight) on the stage's comm
 
 ### 5c. Execute the Stage
 
-Execute the stage using its existing command with full context:
+Execute the stage using its existing command with full context from the preflight
+exploration snapshot (available in `quick_run.preflightExploration`). Pass it to
+each stage so worker agents can use evidence directly.
 
 **Stage → Command Mapping:**
 
 | Stage | Command | Key Behavior |
 |-------|---------|--------------|
-| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Saves `DISCUSS.md`. One question at a time. |
+| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Passes preflight exploration so questions already answered by evidence are skipped. Saves `DISCUSS.md`. One question at a time. |
 | `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
 | `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
 | `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. Delegates to appropriate coder agents. |
@@ -194,6 +256,7 @@ When all stages complete:
    Task:      $ARGUMENTS
    Workflow:  <stage-1> → ... → <stage-N>
    Outcome:   ✅ COMPLETE
+   Evidence:  <N> preflight items used (0 human questions asked before exploration)
    ────────────────────────────────────────────────
    Verify result: /fd-verify
    Save state:    /fd-checkpoint

package/src/rules/common/behavioral.md

@@ -0,0 +1,63 @@
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/src/skills/codebase-mapping/SKILL.md

@@ -12,7 +12,7 @@ Produces structured documentation of a codebase that agents can read to answer "
 
 - Starting work on an unfamiliar codebase
 - Before a major feature that spans multiple modules
-- When `/map-codebase` command is invoked
+- When `/fd-map-codebase` command is invoked
 - When `.codebase/` is missing or stale
 
 ## Output Files

package/src/skills/multi-repo/SKILL.md

@@ -180,7 +180,7 @@ Conflicts must be resolved before any CHANGE PLAN is executed. The `@multi-repo-
 
 ## Independence Check Before Executing
 
-Before running `/multi-repo`:
+Before running `/fd-multi-repo`:
 - [ ] `.planning/config.json` has a `sub_repos` array with at least two entries
 - [ ] All `path` values resolve to actual directories on disk
 - [ ] Each repo has its own `.git` directory (they are separate repos, not subtrees)

package/src/skills/repo-memory-graph/SKILL.md

@@ -19,7 +19,7 @@ The Repo Memory Graph is FlowDeck's long-term knowledge store about this specifi
 ## When to Update
 
 Update the graph:
-- After running `/map-codebase`
+- After running `/fd-map-codebase`
 - When onboarding a new module
 - When a bug fix reveals a recurring pattern (add to `bug_history`)
 - When a refactor changes module ownership