@dv.nghiem/flowdeck 0.3.8 → 0.4.0

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/dist/services/recommended-question.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recommended-question.test.d.ts.map

package/dist/services/recommended-question.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommended-question.test.d.ts","sourceRoot":"","sources":["../../src/services/recommended-question.test.ts"],"names":[],"mappings":""}

package/dist/services/supervisor-binding.d.ts

@@ -51,6 +51,8 @@ export interface SupervisorDecision {
     confidenceScore: number;
     /** Whether this was a preflight or post-stage review */
     reviewPhase: SupervisorReviewPhase;
+    /** Present when decision is 'escalate' — a recommended question for the human */
+    clarificationQuestion?: string;
     /** ISO timestamp */
     timestamp: string;
 }
@@ -104,7 +106,7 @@ export declare function isRegisteredTarget(name: string): {
  * not exist, it returns decision="block" with exists=false and explains that
  * the requested target is not registered.
  */
-export declare function runSupervisorReview(directory: string, targetName: string, ctx?: SupervisorContext): SupervisorDecision;
+export declare function runSupervisorReview(directory: string, targetName: string, ctx?: SupervisorContext, clarificationQuestion?: string): SupervisorDecision;
 /**
  * Shorthand: should execution proceed given a decision and the current config mode?
  * In "advisory" mode, only "block" with a missing-existence check is hard-stopped.

package/dist/services/supervisor-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supervisor-binding.d.ts","sourceRoot":"","sources":["../../src/services/supervisor-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAsBvC,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAMnC,CAAA;AAIV,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAA;AAChF,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;AACnE,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,YAAY,CAAA;AAE9D,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,QAAQ,EAAE,sBAAsB,CAAA;IAChC,kCAAkC;IAClC,UAAU,EAAE,oBAAoB,CAAA;IAChC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAA;IAClB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAA;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,2BAA2B;IAC3B,cAAc,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAA;IAC/D,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAA;IACvB,wDAAwD;IACxD,WAAW,EAAE,qBAAqB,CAAA;IAClC,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,yCAAyC;IACzC,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAA;IAC3B,8DAA8D;IAC9D,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,mBAAmB,EAAE,OAAO,CAAA;CAC7B;AAID,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,wBAAwB,CAsBnF;AAID,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,oBAAoB,CAAA;CAAE,CAIhG;AA4LD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,iBAAsB,GAC1B,kBAAkB,CA4FpB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,UAAU,GAAG,QAAQ,EAC3B,QAAQ,EAAE,OAAO,GAChB,OAAO,CAWT"}
+{"version":3,"file":"supervisor-binding.d.ts","sourceRoot":"","sources":["../../src/services/supervisor-binding.ts"],"names":[],"mappings":"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"}

package/dist/tools/codebase-index.d.ts

@@ -0,0 +1,30 @@
+export interface FileSnapshot {
+    lastModifiedAt: string;
+    lastModifiedBy: string;
+    changeType: "added" | "modified" | "deleted";
+    sourceStage: string;
+}
+export interface ExplorationEntry {
+    stage: string;
+    timestamp: string;
+    filesExplored: string[];
+    reason: string;
+}
+export interface CodebaseIndex {
+    exists: boolean;
+    lastUpdatedAt: string;
+    lastUpdatedBy: string;
+    sourceStage: string;
+    changedFiles: string[];
+    fileSnapshots: Record<string, FileSnapshot>;
+    explorationHistory: ExplorationEntry[];
+    summaryVersion: number;
+    freshnessStatus: "fresh" | "stale" | "unknown";
+}
+export declare function readCodebaseIndex(dir: string): CodebaseIndex;
+export declare function isCodebaseIndexFresh(dir: string, maxAgeMs?: number): boolean;
+export declare function writeCodebaseIndex(dir: string, index: Omit<CodebaseIndex, "exists">): void;
+export declare function appendChangedFiles(dir: string, agent: string, stage: string, files: string[]): void;
+export declare function recordExploration(dir: string, stage: string, filesExplored: string[], reason: string): void;
+export declare function getFileSnapshot(dir: string, filePath: string): FileSnapshot | null;
+//# sourceMappingURL=codebase-index.d.ts.map

package/dist/tools/codebase-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-index.d.ts","sourceRoot":"","sources":["../../src/tools/codebase-index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;IAC5C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAC3C,kBAAkB,EAAE,gBAAgB,EAAE,CAAA;IACtC,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;CAC/C;AAMD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CA+B5D;AAkED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAgB,GAAG,OAAO,CAOnF;AAOD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,IAAI,CAyB1F;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EAAE,GACd,IAAI,CAgCN;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,GACb,IAAI,CAuBN;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAGlF"}

package/dist/tools/codebase-index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=codebase-index.test.d.ts.map

package/dist/tools/codebase-index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codebase-index.test.d.ts","sourceRoot":"","sources":["../../src/tools/codebase-index.test.ts"],"names":[],"mappings":""}

package/dist/tools/codegraph-tool.d.ts

@@ -0,0 +1,3 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+export declare const codegraphTool: ToolDefinition;
+//# sourceMappingURL=codegraph-tool.d.ts.map

package/dist/tools/codegraph-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph-tool.d.ts","sourceRoot":"","sources":["../../src/tools/codegraph-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAa/D,eAAO,MAAM,aAAa,EAAE,cA6G1B,CAAA"}

package/dist/tools/planning-state-lib.d.ts

@@ -49,6 +49,16 @@ export interface PlanningState {
     blockers: string[];
     /** TDD workflow state (undefined when TDD not active) */
     tdd: TDDState | undefined;
+    /** When this state was last updated */
+    lastUpdatedAt: string;
+    /** Which agent last updated the state */
+    lastUpdatedBy: string;
+    /** Phase when state was last updated */
+    lastUpdatedPhase: number;
+    /** Monotonically increasing version number */
+    summaryVersion: number;
+    /** Whether the state is still considered fresh enough to use */
+    freshnessStatus: "fresh" | "stale" | "unknown";
 }
 /** Extended PlanningState with TDD state for internal use */
 export type PlanningStateWithTDD = PlanningState & {
@@ -57,6 +67,19 @@ export type PlanningStateWithTDD = PlanningState & {
 export declare function getTDDState(state: PlanningState): TDDState | undefined;
 export declare function parseState(content: string): Record<string, unknown>;
 export declare function timestamp(): string;
+/**
+ * Returns true if state was updated within maxAgeMs milliseconds.
+ * Defaults to 5 minutes.
+ */
+export declare function isStateFresh(state: PlanningState, maxAgeMs?: number): boolean;
+/**
+ * Mark the state as stale by updating freshnessStatus and appending to history.
+ */
+export declare function markStateStale(dir: string): void;
+/**
+ * Publish a state update with fresh metadata. Called after any significant change.
+ */
+export declare function publishStateUpdate(dir: string, agent: string, phase: number): void;
 export declare function appendHistory(stateContent: string, action: string): string;
 export declare function readPlanningState(dir: string): PlanningState;
 export declare function hasDesignGateSatisfied(state: PlanningState): boolean;

package/dist/tools/planning-state-lib.d.ts.map

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

package/docs/agents/index.md

@@ -0,0 +1,154 @@
+# Agents
+
+FlowDeck runs a 27-agent system coordinated by an orchestrator. Each agent has a specific capability contract and specialized model configuration. The orchestrator selects specialists based on context and delegates work through the `delegate` tool.
+
+## Delegation Model
+
+The orchestrator holds the user session, decomposes requests, and dispatches to specialist agents via the `delegate` tool. Each specialist operates in its own context window and reports results back to the orchestrator. Agents are classified by mode:
+
+- **primary**: visible and selectable from the user interface
+- **subagent**: internal only, invoked programmatically by other agents
+- **all**: works in both primary and subagent contexts
+
+```
+user → @orchestrator → @planner
+                  → @backend-coder
+                  → @frontend-coder
+                  → @reviewer
+                  → @security-auditor
+                  → ...
+```
+
+All agent configurations are in `src/agents/`. Agent definitions use YAML frontmatter (description, mode, model, temperature, steps, permission).
+
+---
+
+## Orchestration
+
+### @orchestrator
+
+The central coordinator. Delegates to specialist agents, coordinates wave-structured task execution, and routes tool calls through the supervisor guard for pre-flight and post-execution review. The orchestrator holds the user session context and is the only agent visible as the default agent.
+
+---
+
+## Planning
+
+### @architect
+
+System design and boundary decisions. Produces architecture diagrams, evaluates technical choices, and enforces architectural constraints. Works upstream of implementation to establish clear boundaries before coding starts.
+
+### @planner
+
+Wave-structured task planning. Takes feature requests and produces phased implementation plans with dependency graphs, file-level scope assignments, and observable success criteria per step. The output of `@planner` feeds directly into `@backend-coder` and `@frontend-coder`.
+
+### @discusser
+
+Structured pre-planning Q&A. Asks clarifying questions in a systematic order to surface ambiguities before `@planner` produces a plan. Prevents the wrong plan from being built by ensuring the problem is fully understood first.
+
+### @plan-checker
+
+Reviews PLAN.md files for quality before execution. Checks completeness, feasibility, and testability. Returns PASS or FAIL with specific recommendations.
+
+---
+
+## Implementation
+
+### @backend-coder
+
+Implements server-side logic using TDD. Specializes in TypeScript/Node.js services, database integrations, API route handlers, and background workers. Uses `tdd-workflow` skill by default — writes failing tests first, then minimum implementation.
+
+### @frontend-coder
+
+Implements UI and client-side interactions using TDD. Specializes in React/Vue components, state management, API client calls, and responsive styling. Uses the same TDD discipline as `@backend-coder` but adapted for the frontend context.
+
+### @devops
+
+Infrastructure and deployment automation. Handles Docker, Kubernetes, CI/CD pipelines, cloud provisioning, and environment configuration. Ensures the system is deployable and monitorable before any feature is considered complete.
+
+### @tester
+
+Test strategy and gap detection. Analyzes modified files, identifies coverage gaps, and suggests the minimum viable test set to close them. Uses `test-gap-detector` and `test-coverage` skills to drive coverage enforcement.
+
+### @debug-specialist
+
+Systematic bug diagnosis and repair. Follows a structured root-cause analysis workflow: isolate the failure mode, confirm the reproduction case, identify the root cause, apply a targeted fix, then verify with a regression test.
+
+### @build-error-resolver
+
+Diagnoses and fixes build errors, compilation failures, and dependency issues. Use immediately when a build fails, types error out, or dependencies are broken.
+
+---
+
+## Review
+
+### @reviewer
+
+Post-commit code review. Reviews only changed code, applies the security checklist first, then quality checks. Reports findings severity-ranked with specific remediation steps and a clear pass/fail verdict.
+
+### @security-auditor
+
+Security vulnerability detection. Scans for OWASP Top 10 issues: SQL injection, XSS, authentication bypass, path traversal, hardcoded credentials, and insecure deserialization. Requires a separate review pass before merging any security-sensitive change.
+
+### @risk-analyst
+
+Failure mode analysis. Identifies what can break from a given change, estimates blast radius, and ranks risks by likelihood and impact. Produces a risk register with specific mitigations for each identified failure mode.
+
+---
+
+## Governance
+
+### @policy-enforcer
+
+Governance rule enforcement. Validates that agent actions comply with configured policies: guard rails, permission scopes, architectural constraints, and coding standards. Escalates violations with a specific policy citation.
+
+### @supervisor
+
+Pre-flight and post-execution review of tool calls. Intercepts and validates agent actions against configured policies before execution, and audits decisions after completion for compliance tracking.
+
+---
+
+## Utility
+
+### @writer
+
+Documentation generation. Reads code structure and produces documentation: API docs from route definitions, component docs from props, README from package manifest. Follows the project conventions in `docs/`.
+
+### @doc-updater
+
+Updates existing documentation to reflect code changes. Tracks which docs need updating when files are modified and keeps documentation in sync with implementation.
+
+### @mapper
+
+Codebase indexing. Builds and maintains a searchable index of the codebase: file purposes, dependency graph, API surface, and ownership. Used by `@planner` and `@discusser` for context before planning.
+
+### @code-explorer
+
+Explores unfamiliar code quickly. Analyzes file structure, traces dependencies, and produces summaries that help other agents understand a new module or codebase area without reading every line.
+
+### @researcher
+
+API docs and library research. Reads documentation, extracts relevant patterns, and answers questions about libraries, frameworks, and tools used in the project.
+
+### @performance-optimizer
+
+Identifies and fixes performance bottlenecks using data. Profiles code, detects N+1 queries, analyzes bundle size, and optimizes React render performance. Measures before and after to verify improvements.
+
+### @refactor-guide
+
+Guides safe refactoring of existing code without changing behavior. Provides step-by-step transformation guidance, ensures tests stay green, and helps extract functions or restructure modules.
+
+### @auto-learner
+
+Continuously learns from project patterns and agent decisions. Improves future recommendations by analyzing what worked well in similar past tasks.
+
+### @design
+
+Design-first workflow coordinator. Produces wireframes, component specs, and design token decisions. Runs before `@frontend-coder` starts implementation to ensure UI consistency and user experience quality.
+
+### @task-splitter
+
+Decomposes complex tasks into parallel workstreams. Analyzes dependencies, groups independent work into waves, and produces a plan for multi-agent execution.
+
+### @architect (already listed in Planning)
+
+System design and boundary decisions. See Planning section above.

package/docs/commands/fd-ask.md

@@ -1,51 +1,83 @@
----
-description: Smart dispatch — routes a free-form task to the appropriate specialized agent without requiring a workflow
-argument-hint: "--task '<description>'"
----
+# /fd-ask
 
-Route a free-form task to the best specialized agent automatically.
+**Purpose:** Smart agent dispatch — routes a focused question to the appropriate specialist.
 
-**What this does:**
-1. Parses your task description using keyword scoring
-2. Picks the best-fit agent from 12 specialists
-3. Runs the Impact Radar if the task involves change analysis
-4. Dispatches the task directly — no workflow, no STATE.md required
+## Usage
 
-**Routing table:**
+/fd-ask [question]
 
-| Keywords | Agent |
-|---|---|
-| design, architecture, component | `@architect` |
-| impact, blast radius, affected | `@researcher` + radar |
-| security, vulnerability, CVE | `@security-auditor` |
-| performance, bottleneck, slow | `@performance-optimizer` |
-| debug, error, crash, exception | `@debug-specialist` |
-| test, coverage, spec, TDD | `@tester` |
-| refactor, cleanup, simplify | `@backend-coder` / `@frontend-coder` / `@devops` |
-| document, docs, README | `@writer` |
-| explain, query, find, explore | `@code-explorer` |
-| deploy, release, migration | `@devops` |
-| plan, roadmap, breakdown | `@planner` |
-| (anything else) | `@orchestrator` |
+## Arguments
 
-**Examples:**
+- `question` — the question to route to a specialist agent
 
+## What Happens
+
+Analyze the question to determine the best specialist from this routing table:
+
+| Keywords / Topic | Agent |
+|-----------------|-------|
+| ui, ux, wireframe, landing page, dashboard, admin panel, app screen, design system | **@design** |
+| design, architecture, structure, system, component, API | **@architect** |
+| security, auth, vulnerability, token, permission, injection | **@security-auditor** |
+| performance, speed, slow, optimize, latency, cache, memory | **@performance** |
+| impact, change, affect, downstream, dependency, blast | **@researcher** (impact mode) |
+| test, coverage, regression, tdd, gap | **@tester** |
+| bug, error, crash, debug, trace | **@debug-specialist** |
+| general / unclear | **@orchestrator** |
+
+Once the specialist is identified:
+1. Delegate the question to that specialist with full context
+2. Include `.codebase/ARCHITECTURE.md` if available and relevant
+3. Include `.planning/STATE.md` phase context if relevant
+4. Return the specialist's answer directly
+
+## Output / State
+
+Present the answer clearly with:
+- Which specialist answered
+- The answer (no padding, no ceremony)
+- Any follow-up suggestions if the question opens further threads
+
+## Examples
+
+**Ask an architecture question:**
+```
+/fd-ask "What is the best way to structure a new API endpoint?"
+```
+Routes to: @architect
+
+**Ask a security question:**
 ```
-/fd-ask --task "system design for a real-time notification service"
-/fd-ask --task "explain how the payment flow works"
-/fd-ask --task "is there a security issue with the rate limiter"
-/fd-ask --task "why is the login endpoint slow"
-/fd-ask --task "what files are affected if I change the auth module"
-/fd-ask --task "write tests for the checkout service"
-/fd-ask --agent security-auditor --task "review the JWT implementation"
+/fd-ask "How should we handle token expiration securely?"
 ```
+Routes to: @security-auditor
 
-**Override routing:** Use `--agent` to force a specific agent.
+**Ask about performance:**
+```
+/fd-ask "Why is the login page slow on mobile?"
+```
+Routes to: @performance
+
+**Ask about a bug:**
+```
+/fd-ask "Why does the session timeout error appear randomly?"
+```
+Routes to: @debug-specialist
 
-## What Next?
+**Ask about test coverage:**
+```
+/fd-ask "What parts of the auth module are not tested?"
+```
+Routes to: @tester
+
+**Ask about UI design:**
+```
+/fd-ask "Should the dashboard use tabs or a sidebar for navigation?"
+```
+Routes to: @design
 
-After `/fd-ask` completes, you can go deeper:
+## Related Commands
 
-1. **Full workflow** → `/fd-fix-bug`, `/fd-new-feature`, `/fd-verify`
-2. **Detailed planning** → `/fd-discuss`, `/fd-plan`
-3. **Another question** → `/fd-ask --task '...'`
+- `/fd-discuss` — structured exploration of a topic with multiple questions
+- `/fd-suggest` — get feature recommendations
+- `/fd-translate-intent` — convert a vague request into concrete options

package/docs/commands/fd-checkpoint.md

@@ -1,10 +1,65 @@
----
-description: Save current state to STATE.md — safe to close session after this
----
-Run the FlowDeck checkpoint command to save the current project state.
+# /fd-checkpoint
 
-## What Next?
+**Purpose:** Force-save mid-session checkpoint to STATE.md and write a CHECKPOINT.md summary — safe to close the session and resume later with `/fd-resume`.
 
-1. **Continue working** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`
+## Usage
+
+/fd-checkpoint
+
+## What Happens
+
+1. **Pre-flight check.**
+   - Verify `.planning/STATE.md` exists — error if not found ("No active project to checkpoint.")
+
+2. **Read current STATE.md.** Parse phase, status, steps_complete, and other tracked fields.
+
+3. **Update STATE.md.**
+   - Set `last_updated` to current timestamp
+   - Ensure `status` reflects current state accurately
+   - Scan `.planning/phases/phase-<N>/PLAN.md` for completed steps and update `steps_complete` if tracked
+
+4. **Write CHECKPOINT.md.** Creates `.planning/phases/phase-<N>/CHECKPOINT.md`:
+
+```markdown
+# Checkpoint
+
+**Saved:** <timestamp>
+**Phase:** <N>
+**Status:** <status>
+**Plan confirmed:** <yes/no>
+
+## What was done
+
+<brief summary of recent changes in this session>
+
+## What's next
+
+<next uncompleted step from PLAN.md, or "No plan active">
+```
+
+5. **Report.** Present checkpoint summary including phase, status, file path, and the `/fd-resume` command.
+
+## Output / State
+
+Files created:
+- `.planning/phases/phase-<N>/CHECKPOINT.md`
+
+STATE.md updates:
+```yaml
+last_updated: "<timestamp>"
+status: <current status>
+steps_complete: [1, 2, ...]   # if tracked in PLAN.md
+```
+
+## Examples
+
+```
+/fd-checkpoint
+```
+
+Save a checkpoint for the current session. Safe to close afterward.
+
+## Related Commands
+
+- `/fd-resume` — reload the checkpointed state and continue
+- `/fd-map-codebase` — map the codebase (required before starting a feature)