@dv.nghiem/flowdeck 0.3.3 → 0.3.4

package/dist/tools/council.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"council.d.ts","sourceRoot":"","sources":["../../src/tools/council.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAmExE"}
+{"version":3,"file":"council.d.ts","sourceRoot":"","sources":["../../src/tools/council.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAKtD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA2ExE"}

package/dist/tools/delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/tools/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAStD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAiFzE"}
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/tools/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAYtD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA+HzE"}

package/dist/tools/dispatch-routing.d.ts

@@ -0,0 +1,6 @@
+import type { TaskType } from "../services/model-router";
+export declare function shouldRetry(promptRes: any): boolean;
+export declare function isTransientError(text?: string): boolean;
+export declare function normalizeTaskType(taskType: string | undefined, agent: string): TaskType;
+export declare function isTaskType(value: string): value is TaskType;
+//# sourceMappingURL=dispatch-routing.d.ts.map

package/dist/tools/dispatch-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-routing.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch-routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAExD,wBAAgB,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAOnD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAUvD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAcvF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAY3D"}

package/dist/tools/run-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-pipeline.d.ts","sourceRoot":"","sources":["../../src/tools/run-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAuBtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAyG5E"}
+{"version":3,"file":"run-pipeline.d.ts","sourceRoot":"","sources":["../../src/tools/run-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AA6BtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAyH5E"}

package/docs/installation.md

@@ -20,7 +20,7 @@ If OpenCode is not yet installed, follow the [OpenCode installation guide](https
 
 ## Method 1: curl (recommended)
 
-The install script downloads the latest release, copies all agents, skills, commands, and workflows to `~/.config/opencode/`, and registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json`.
+The install script registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json` and sets `orchestrator` as default agent when missing.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
@@ -29,11 +29,9 @@ curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh |
 What the script does:
 
 1. Detects your config directory (`$OPENCODE_CONFIG_DIR` or `~/.config/opencode`)
-2. Copies `agents/*.md` → `~/.config/opencode/agent/` (markdown agents for OpenCode compatibility)
-3. Compiles TypeScript agents from `src/agents/` → `dist/agents/` (for plugin-based loading)
-4. Copies `skills/*/` → `~/.config/opencode/skills/`
-5. Registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json`
-6. Sets `orchestrator` as the default agent
+2. Creates the config directory if needed
+3. Registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json` if not present
+4. Sets `orchestrator` as the default agent if not already configured
 
 ---
 
@@ -59,18 +57,9 @@ Steps explained:
 
 ## Verification
 
-After any install method, run these commands to confirm everything landed correctly:
+After any install method, run these commands to confirm registration:
 
 ```bash
-# Should print 23 or more
-ls ~/.config/opencode/agent/ | grep -c "\.md"
-
-# Should list 24 or more directories
-ls ~/.config/opencode/skills/
-
-# Should list 16 or more files
-ls ~/.config/opencode/command/
-
 # Should print @dv.nghiem/flowdeck
 cat ~/.config/opencode/opencode.json | grep flowdeck
 ```
@@ -81,7 +70,7 @@ Expected output for the last command:
 "@dv.nghiem/flowdeck"
 ```
 
-If any count is lower than expected, re-run the install command. If the `opencode.json` line is missing, the plugin will not load — add it manually (see [Configuration](configuration.md)).
+If the `opencode.json` line is missing, the plugin will not load — add it manually (see [Configuration](configuration.md)).
 
 ---
 

package/docs/intelligence.md

@@ -8,19 +8,19 @@ FlowDeck's intelligence layer adds safety-first AI editing, persistent architect
 
 | Feature | Command / Hook | Storage |
 |---------|---------------|---------|
-| Change Impact Radar | `/fd-impact-radar` | VOLATILITY.json, MEMORY.json |
+| Change Impact Radar | Integrated analysis workflow | VOLATILITY.json, MEMORY.json |
 | Patch Trust Score | Hook (automatic) | VOLATILITY.json, FAILURES.json |
-| Blast Radius Preview | `/fd-blast-radius` | MEMORY.json, FAILURES.json |
+| Blast Radius Preview | Integrated analysis workflow | MEMORY.json, FAILURES.json |
 | Repo Memory Graph | `repo-memory` tool | `.codebase/MEMORY.json` |
 | Failure Replay Engine | `failure-replay` tool | `.codebase/FAILURES.json` |
 | Safe Execution Modes | Hook (automatic) | `.planning/config.json` |
-| Test Gap Detector | `/fd-test-gap` | VOLATILITY.json |
+| Test Gap Detector | Integrated analysis workflow | VOLATILITY.json |
 | Architectural Constraint Guard | Hook (automatic) | `.codebase/CONSTRAINTS.md` |
 | Intent-to-Change Translator | `/fd-translate-intent` | — |
 | Confidence-Aware Planning | Skill | — |
-| Codebase Volatility Map | `/fd-volatility-map`, `volatility-map` tool | `.codebase/VOLATILITY.json` |
-| Human Review Routing | `/fd-review-route` | VOLATILITY.json, FAILURES.json |
-| Regression Prediction | `/fd-regression-predict` | — |
+| Codebase Volatility Map | `volatility-map` tool | `.codebase/VOLATILITY.json` |
+| Human Review Routing | Integrated analysis workflow | VOLATILITY.json, FAILURES.json |
+| Regression Prediction | Integrated analysis workflow | — |
 | Decision Trace | `decision-trace` tool + hook | `.codebase/DECISIONS.jsonl` |
 | Self-Healing Policies | `policy-engine` tool | `.codebase/POLICIES.json` |
 
@@ -28,14 +28,11 @@ FlowDeck's intelligence layer adds safety-first AI editing, persistent architect
 
 ## Slash Commands
 
-### `/fd-impact-radar`
+### Change Impact Radar
 
 Predicts which files, modules, APIs, tests, and database paths are likely to be affected before the AI edits anything.
 
-```
-/fd-impact-radar --change "refactor auth token handling" --scope all
-/fd-impact-radar --change "drop users table" --json
-```
+Use `/fd-suggest` or `/fd-translate-intent` when you need pre-change analysis with impact context.
 
 **Arguments:**
 - `--change` — describe the proposed change (free text)
@@ -46,13 +43,11 @@ Predicts which files, modules, APIs, tests, and database paths are likely to be
 
 ---
 
-### `/fd-blast-radius`
+### Blast Radius Preview
 
 Shows the likely downstream consequences of a proposed change — hidden dependencies, fragile integration points, and predicted test breakages.
 
-```
-/fd-blast-radius --change "delete legacy session table" --depth 3
-```
+Use `/fd-suggest` for broad risk discovery and `/fd-deploy-check` before release changes.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -78,14 +73,11 @@ Converts a vague request like "make checkout faster" into concrete, ranked imple
 
 ---
 
-### `/fd-volatility-map`
+### Volatility Map
 
 Displays the Codebase Volatility Map — highlights unstable zones based on churn, hotfix frequency, and unresolved TODO clusters.
 
-```
-/fd-volatility-map
-/fd-volatility-map --threshold volatile --limit 10
-```
+Use the `volatility-map` tool directly from delegated agents for incremental updates.
 
 **Arguments:**
 - `--threshold` — minimum stability level to show: `stable`, `moderate`, `volatile` (default), `critical`
@@ -96,13 +88,11 @@ Displays the Codebase Volatility Map — highlights unstable zones based on chur
 
 ---
 
-### `/fd-regression-predict`
+### Regression Prediction
 
 Estimates the most likely regression categories for a change — performance, auth, schema, UI states, async flows, etc.
 
-```
-/fd-regression-predict --change "add webhook retry logic" --categories all
-```
+FlowDeck derives regression risk from historical failures plus volatility data during analysis-oriented workflows.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -111,14 +101,11 @@ Estimates the most likely regression categories for a change — performance, au
 
 ---
 
-### `/fd-test-gap`
+### Test Gap Detector
 
 Identifies which areas of a proposed change are weakly covered by tests, and suggests the minimum high-value tests to add first.
 
-```
-/fd-test-gap --change "add payment webhook handler"
-/fd-test-gap --change "update user schema" --scope unit
-```
+Use `/fd-verify` and `/fd-deploy-check` for current test-gap surfacing in production workflows.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -127,13 +114,11 @@ Identifies which areas of a proposed change are weakly covered by tests, and sug
 
 ---
 
-### `/fd-review-route`
+### Human Review Routing
 
 Routes risky patches to the right reviewer type — security, backend, infra, domain-owner, frontend, data, or devops — based on the file paths and change description.
 
-```
-/fd-review-route --files "src/auth/token.ts,src/api/routes.ts" --change "new JWT rotation logic"
-```
+Routing to reviewer profiles is integrated into verification and deployment checks.
 
 **Arguments:**
 - `--files` — comma-separated file paths being changed

package/docs/optimization-baseline.md

@@ -0,0 +1,21 @@
+# FlowDeck Optimization Baseline
+
+Captured on 2026-05-07 before deep optimization implementation.
+
+## Dispatch Baseline
+
+- Command: `bun test src/tools/agent-dispatch.test.ts`
+- Result: 8 passing, 0 failing
+- Suite runtime (bun): 135ms
+- Wall clock runtime: 0.17s
+
+## Observability Baseline
+
+- `.codebase/` does not exist yet in a clean repo checkout.
+- Telemetry hooks emitted `status: "ok"` for all tool completions and did not classify failures.
+- Session/run IDs defaulted to `session-0` and `run-0` when runtime env variables were not set.
+
+## Routing and Cost Baseline
+
+- Dispatch tools did not call model routing or agent performance tracking.
+- `src/services/model-router.ts` and `src/services/agent-performance.ts` were present but not wired into `delegate`/`run-pipeline`.

package/docs/rules.md

@@ -1,47 +1,20 @@
 # FlowDeck Rules
 
-Rules are coding standard documents that you load into OpenCode's context. They give the AI consistent style, testing, security, and language-specific guidelines to follow across all sessions.
+Rules are coding standards used by FlowDeck agents for style, testing, security, and language-specific guidance.
 
-## How to Use Rules
+## How Rules Load
 
-### Method 1 — Project-level (recommended)
+FlowDeck loads all markdown files under `src/rules/` automatically through plugin startup. You do not need to manually copy or symlink rule files.
 
-Add the rules you want to your project's `opencode.json`. This ensures every OpenCode session in the project automatically picks them up:
+## Precedence
 
-```json
-{
-  "instructions": [
-    ".flowdeck-rules/common/coding-style.md",
-    ".flowdeck-rules/common/testing.md",
-    ".flowdeck-rules/common/security.md",
-    ".flowdeck-rules/typescript/patterns.md"
-  ]
-}
-```
-
-Where `.flowdeck-rules/` is a symlink or copy of the FlowDeck rules directory:
-
-```bash
-ln -s ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules .flowdeck-rules
-```
-
-### Method 2 — Per-session
-
-Reference a rule file directly in your prompt:
+When guidance conflicts, precedence is:
 
-```
-Follow the rules in ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules/typescript/patterns.md
-```
-
-### Method 3 — Copy to project
-
-Copy the rules directory into your project for version-controlled standards:
-
-```bash
-cp -r ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules ./flowdeck-rules
-```
+1. `AGENTS.md` and `CLAUDE.md` in the repository
+2. FlowDeck plugin rules in `src/rules/**`
+3. Runtime policy rules in `.codebase/POLICIES.json`
 
-Then commit `flowdeck-rules/` to your repository so the entire team uses the same standards.
+This keeps repository-specific conventions authoritative and lets policy learning add guardrails without overriding project intent.
 
 ---
 

package/docs/workflows.md

@@ -38,36 +38,35 @@ Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` r
 |---------|---------|------------|
 | `/fd-new-project` | Bootstrap a new project | @orchestrator |
 | `/fd-map-codebase` | Analyse and index the codebase | @mapper (×6 parallel) |
-| `/fd-settings` | Configure FlowDeck settings | @orchestrator |
 | `/fd-new-feature` | Initialize a new feature | @orchestrator |
 | `/fd-discuss` | Pre-planning discussion | @discusser |
 | `/fd-plan` | Generate a phase plan | @planner, @plan-checker |
-| `/fd-roadmap` | View / update project roadmap | @orchestrator |
-| `/fd-dashboard` | Visual progress dashboard | — |
 | `/fd-ask` | Smart agent dispatch | various |
 | `/fd-execute` | Implement feature via TDD | @orchestrator, @coder, @tester, @reviewer |
 | `/fd-verify` | Verify feature completion | @tester, @reviewer, @security-auditor |
 | `/fd-fix-bug` | Fix a bug with TDD | @debug-specialist, @tester, @coder |
-| `/fd-review-code` | Code review | @reviewer, @researcher, @tester |
 | `/fd-write-docs` | Generate documentation | @writer, @reviewer |
 | `/fd-deploy-check` | Pre-deploy safety check | @tester, @security-auditor, @reviewer |
-| `/fd-progress` | View project progress | — |
+| `/fd-status` | View project progress | — |
 | `/fd-checkpoint` | Save a session checkpoint | — |
 | `/fd-resume` | Resume from checkpoint | — |
 | `/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 | @coder or selected specialist |
+| `/fd-reflect` | Post-session reflection and skill capture | @auto-learner |
+| `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 
 ---
 
 ## Analysis Commands
 
-These umbrella commands combine multiple analysis modules:
+Analysis workflows are currently exposed through:
 
 | Command | Purpose | Flags |
 |---------|---------|-------|
-| `/fd-analyze-change` | Combined impact analysis | `--impact`, `--blast-radius`, `--regression`, `--test-gap`, `--volatility` |
-| `/fd-guarded-edit` | Edit gate decision | auto/confirm/review/block |
-| `/fd-evaluate-risk` | Standalone risk assessment | — |
 | `/fd-translate-intent` | Intent to concrete options | `assumptions`, `recommended_option` |
+| `/fd-suggest` | Suggest feature opportunities from volatility, failures, and decisions | `--category`, `--limit` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,9 @@
     "postinstall": "node postinstall.mjs",
     "prepublishOnly": "bun run clean && bun run build",
     "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "validate:docs": "node scripts/validate-docs.mjs"
   },
   "keywords": ["opencode", "plugin", "ai", "workflow", "planning"],
   "author": "DVNghiem",

package/src/rules/README.md

@@ -6,6 +6,16 @@ Coding standards for projects using FlowDeck. These define conventions that Flow
 
 Rules are loaded **automatically** by the FlowDeck plugin. No manual configuration is needed — when FlowDeck is installed, all rule files in this directory are injected into OpenCode's `instructions` at startup.
 
+## Rule Precedence
+
+When guidance conflicts, FlowDeck resolves precedence in this order:
+
+1. Repository governance files (`AGENTS.md`, `CLAUDE.md`)
+2. FlowDeck plugin rules from `src/rules/**`
+3. Runtime policies from `.codebase/POLICIES.json`
+
+This keeps repository-specific expectations authoritative while still allowing runtime policy learning.
+
 ## Selective Rules (Optional)
 
 If you want to override the default set and load only specific rules, add them to `opencode.json` under `instructions`:

package/src/rules/common/coding-style.md

@@ -9,8 +9,8 @@ Language-agnostic coding conventions followed by all FlowDeck agents.
 | 1 | **No Redundant Code** | No redundant arguments, methods, or attributes. Each piece of code must serve a purpose. |
 | 2 | **Simplicity** | Code should be simple and easy to understand. Prefer clarity over cleverness. |
 | 3 | **Clear Commands** | Code should have clear, explicit commands. No ambiguity in intent. |
-| 4 | **Extensibility** | Code must be easily extendable. Design for growth, not just current needs. |
-| 5 | **Documentation** | Code must have clear documentation at the beginning of every file. |
+| 4 | **Extensibility** | Prefer minimal designs for current requirements. Add extension points only when required by active scope. |
+| 5 | **Documentation** | Add comments when needed to explain non-obvious tradeoffs or constraints; avoid boilerplate file headers. |
 | 6 | **Information Security** | Comply with information security best practices. No secrets, no injections, no XSS. |
 | 7 | **Memory Optimization** | Optimize memory usage to the minimum possible. Avoid unnecessary allocations. |
 | 8 | **Speed** | Process speed should be as fast as possible. Prefer efficient algorithms and data structures. |

package/src/rules/typescript/patterns.md

@@ -102,7 +102,7 @@ class UserService {
 
 ## Result Types for Error Handling
 
-Never throw in business logic. Use Result types.
+Prefer explicit error contracts (Result types or typed exceptions) for business logic. Use one pattern consistently within a module.
 
 ```typescript
 type Ok<T> = { ok: true; value: T };

package/src/skills/backend-patterns/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: backend-patterns
+description: Backend architecture patterns for services, APIs, data access, and middleware design.
+origin: FlowDeck
+---
+
 # backend-patterns
 
 ## When to Activate

package/src/skills/clean-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: clean-architecture
+description: Apply Clean Architecture boundaries to keep domain logic isolated from frameworks and infrastructure.
+origin: FlowDeck
+---
+
 # clean-architecture
 
 ## When to Activate

package/src/skills/cqrs/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: cqrs
+description: Command Query Responsibility Segregation patterns for separating write and read models.
+origin: FlowDeck
+---
+
 # CQRS (Command Query Responsibility Segregation)
 
 ## When to Activate

package/src/skills/ddd-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: ddd-architecture
+description: Domain-Driven Design patterns for bounded contexts, aggregates, and ubiquitous language.
+origin: FlowDeck
+---
+
 # ddd-architecture
 
 ## When to Activate

package/src/skills/event-driven-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: event-driven-architecture
+description: Event-driven architecture patterns for asynchronous workflows and decoupled services.
+origin: FlowDeck
+---
+
 # Event-Driven Architecture
 
 ## When to Activate

package/src/skills/hexagonal-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: hexagonal-architecture
+description: Ports-and-adapters architecture patterns for testable, framework-independent domain logic.
+origin: FlowDeck
+---
+
 # hexagonal-architecture
 
 ## When to Activate

package/src/skills/layered-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: layered-architecture
+description: Layered architecture patterns for separating presentation, application, domain, and data layers.
+origin: FlowDeck
+---
+
 # layered-architecture
 
 ## When to Activate

package/src/skills/postgres-patterns/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: postgres-patterns
+description: PostgreSQL schema, query, indexing, and performance patterns.
+origin: FlowDeck
+---
+
 # postgres-patterns
 
 ## When to Activate

package/src/skills/saga-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: saga-architecture
+description: Saga coordination patterns for distributed transactions with compensating actions.
+origin: FlowDeck
+---
+
 # saga-architecture
 
 ## When to Activate