@dv.nghiem/flowdeck 0.1.0

package/docs/feature-integration-architecture.md

@@ -0,0 +1,255 @@
+# FlowDeck Integration Architecture
+
+Second-layer integration: trust, routing, observability, and repo-intelligence.
+
+---
+
+## Overview
+
+This layer adds 8 capabilities behind the existing command architecture without expanding the top-level command surface:
+
+| Capability | Implementation | Data File |
+|---|---|---|
+| Patch Trust Engine | `src/hooks/patch-trust.ts` | `.codebase/DECISIONS.jsonl` |
+| Adaptive Model Router | `src/services/model-router.ts` | `.codebase/MODEL_ROUTER.json` |
+| Approval-Aware Execution | `src/services/approval-manager.ts` + `src/hooks/approval-hook.ts` | `.codebase/APPROVALS.json` |
+| Workflow Replay + Diff | `src/services/run-trace.ts` | `.codebase/RUNS.jsonl` |
+| Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
+| Structured Telemetry | `src/services/telemetry.ts` + `src/hooks/telemetry-hook.ts` | `.codebase/TELEMETRY.jsonl` |
+| Dashboard Integration | `src/dashboard/` | reads all `.codebase/` files |
+| Failure-to-Rule Learning | `src/services/policy-compiler.ts` (`learnFromFailure`) | `.codebase/POLICIES.json` |
+
+---
+
+## Services Layer (`src/services/`)
+
+### telemetry.ts
+Appends structured `TelemetryEvent` records to `.codebase/TELEMETRY.jsonl`.
+
+```typescript
+appendEvent(dir, { session_id, run_id, event, command, tool, model, duration_ms, status, risk_score })
+readEvents(dir, limit)
+getCommandSummary(dir)
+getRunEvents(dir, run_id)
+getRecentToolFailures(dir)
+```
+
+Event types: `command.start`, `command.end`, `tool.call`, `tool.complete`, `agent.dispatch`, `approval.request`, `approval.resolve`, `run.complete`, `run.fail`, `policy.violation`, `patch.scored`
+
+### run-trace.ts
+Records command execution runs with files touched, risk scores, and outcomes.
+
+```typescript
+startTrace(dir, command, args, session_id) → RunTrace
+endTrace(dir, run_id, status, outcome?, error?)
+touchFile(dir, run_id, filePath)
+setRiskScore(dir, run_id, score)
+getTrace(dir, run_id)
+listTraces(dir, limit)
+diffTraces(dir, run_id_a, run_id_b) → RunDiff
+```
+
+### approval-manager.ts
+Manages approval state for high-risk operations.
+
+```typescript
+requestApproval(dir, run_id, trigger, reason, options) → ApprovalRequest
+resolveApproval(dir, approval_id, "approved" | "rejected")
+checkApproval(dir, file_path, command) → ApprovalRequest | null
+getPendingApprovals(dir)
+isApprovalRequired(filePath, riskScore) → boolean
+isSensitivePath(filePath) → boolean
+```
+
+**Approval TTL:** 30 minutes. Sensitive path patterns: auth, payment, secrets, migrations, infra, production config.
+
+### model-router.ts
+Routes task types to the best available model.
+
+```typescript
+routeModel(dir, task_type, risk_score?) → RoutedModel
+buildAgentConfig(dir, agents) → AgentConfig[]
+getRouterConfig(dir) → ModelRouterConfig
+```
+
+**Default routing:**
+| Task | Primary | High-Risk Override |
+|---|---|---|
+| planning | claude-sonnet-4-5 | — |
+| implementation | claude-opus-4-5 | claude-opus-4-5 |
+| debugging | claude-sonnet-4-5 | claude-opus-4-5 |
+| review | gemini-2.5-flash | — |
+| testing | claude-haiku-4-5 | — |
+| security | claude-opus-4-5 | claude-opus-4-5 |
+
+Override by creating `.codebase/MODEL_ROUTER.json` with `{ "task_type": { "primary": "model-name" } }`.
+
+### agent-performance.ts
+Tracks success rates, costs, and durations per agent+model+task combination.
+
+```typescript
+recordRun(dir, agent, model, task_type, success, duration_ms, cost?)
+getStats(dir, filter?) → AgentPerfEntry[]
+getBestAgentForTask(dir, task_type) → AgentRecommendation | null
+getAgentLeaderboard(dir) → AgentRecommendation[]
+```
+
+Requires ≥ 3 runs per combination before making routing recommendations.
+
+---
+
+## Hooks Layer (`src/hooks/`)
+
+### Hook execution order (tool.execute.before)
+1. `telemetryHook` — record tool invocation
+2. `approvalHook` — block writes on sensitive files without approval
+3. `guardRailsHook` — enforce execution mode (auto/guarded/review-only)
+4. `toolGuardHook` — enforce architectural constraints
+5. `patchTrustHook` — score patch risk
+6. `decisionTraceHook` — record edit rationale
+
+### approval-hook.ts
+Intercepts write/edit tool calls on sensitive file paths. Throws with `APPROVAL_REQUIRED:` prefix to block. Emits `approval.request` telemetry event.
+
+Monitored tools: `write_file`, `edit_file`, `create_file`, `apply_patch`, `str_replace_editor`, `write`
+
+### telemetry-hook.ts
+Emits `tool.call` events for all tool invocations. Lightweight — never blocks.
+
+---
+
+## Command Integration
+
+### /fd-new-feature
+- Calls `startTrace()` on entry → `run_id` included in config
+- Calls `buildAgentConfig()` from model-router → no hardcoded models
+- Emits `command.start` telemetry event with risk score and phase
+
+### /fd-fix-bug
+- Calls `startTrace()` on entry → `run_id` included in config
+- Emits `command.start` telemetry with prior failure count in metadata
+
+### /fd-analyze-change
+- Consumes all impact services (impact radar, blast radius, volatility, regression)
+- Returns structured output with risk summary for dashboard
+
+### /fd-dashboard
+- Reads `DashboardData` including: `telemetrySummary`, `recentRuns`, `pendingApprovals`, `agentPerf`, `toolFailureCount`
+- Displays operational control plane sections alongside phase progress
+
+### /fd-guarded-edit
+- Run approval gate before risky operations
+- Uses `isApprovalRequired()` + `requestApproval()` pattern
+
+---
+
+## Dashboard Sections
+
+The dashboard at `http://localhost:<port>` now includes:
+
+1. **Milestone Progress** — phase timeline (existing)
+2. **Blockers** — from STATE.md (existing)
+3. **⚠ Pending Approvals** — approval requests waiting on user
+4. **Recent Runs** — last 10 command runs with status, risk, files touched
+5. **Command Telemetry** — aggregate stats per command (total runs, success rate, avg duration)
+6. **Agent Performance** — success rate per agent/model/task combination
+
+---
+
+## Data Schema
+
+### TELEMETRY.jsonl (append-only)
+```json
+{"id":"uuid","ts":"ISO","session_id":"s","run_id":"r","event":"command.end","command":"fd-fix-bug","status":"ok","duration_ms":1200,"risk_score":72}
+```
+
+### RUNS.jsonl (append-only, rewritten on end/update)
+```json
+{"run_id":"uuid","session_id":"s","command":"fd-new-feature","args":{},"started_at":"ISO","ended_at":"ISO","status":"complete","files_touched":["src/auth.ts"],"event_ids":[],"risk_score":65,"outcome":"Feature merged"}
+```
+
+### APPROVALS.json
+```json
+{"requests":[{"id":"uuid","run_id":"r","session_id":"s","requested_at":"ISO","status":"pending","trigger":"sensitive_file","reason":"Auth change","risk_score":25,"file_path":"src/auth.ts"}]}
+```
+
+### AGENT_PERF.json
+```json
+{"entries":[{"agent":"coder","model":"claude-opus-4-5","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
+```
+
+### MODEL_ROUTER.json (optional override)
+```json
+{"implementation":{"primary":"claude-sonnet-4-5","temperature":0.2},"review":{"primary":"claude-haiku-4-5"}}
+```
+
+---
+
+## Config Additions
+
+No new required config. Optional per-repo overrides:
+
+- `.codebase/MODEL_ROUTER.json` — override model routing per task type
+- `.codebase/POLICIES.json` — runtime policy rules (existing, enhanced)
+- `.codebase/CONSTRAINTS.md` — architectural constraints (existing)
+
+---
+
+## Agents
+
+Three new specialist agents available for programmatic invocation:
+
+| Agent | File | Purpose |
+|---|---|---|
+| `replay-analyst` | `agents/replay-analyst.md` | Diff run traces, surface regressions |
+| `eval-reviewer` | `agents/eval-reviewer.md` | Evaluate agent/model routing quality |
+| `cost-optimizer` | `agents/cost-optimizer.md` | Recommend cheaper routing with no quality loss |
+
+---
+
+## Policy Compiler Service (`src/services/policy-compiler.ts`)
+
+Compiles active policies from `POLICIES.json` into runtime evaluators.
+
+```typescript
+evaluatePolicies(dir, ctx) → PolicyViolation[]
+learnFromFailure(failure_type, affected_paths, root_cause?) → ProposedPolicy | null
+formatViolations(violations) → string
+```
+
+**PolicyContext fields:** `command`, `file_path`, `change_description`, `tool`, `risk_score`
+
+**Severity derivation:** Rules containing "require approval", "never", "must not" → `block`; otherwise → `warn`
+
+**Pattern learning:** Proposes policies for recognized failure types (`auth_bypass`, `payment_failure`, `migration_failure`, `infra_change`, `secrets_exposure`). Returns `null` for unrecognized patterns.
+
+---
+
+## `/fd-approve` Command (`src/commands/governance/approve.ts`)
+
+Governance command for managing approval gates raised by the approval hook.
+
+```
+/fd-approve                           # list all pending approvals
+/fd-approve --id <uuid>               # approve → operation may proceed
+/fd-approve --id <uuid> --reject      # reject → operation stays blocked
+/fd-approve --recent                  # last 10 resolved approvals
+/fd-approve --json                    # machine-readable output
+```
+
+Resolving an approval emits an `approval.resolve` telemetry event and records the decision in `APPROVALS.json`.
+
+---
+
+## Migration Notes
+
+All existing commands continue to work unchanged. New capabilities are additive:
+
+- `fd-new-feature` — now uses model router instead of hardcoded models; emits telemetry
+- `fd-fix-bug` — emits run trace on entry, evaluates policies, proposes new policies from failures
+- `fd-review-code` — shows policy violations in output table
+- Dashboard — new operational sections appear only when data exists (no empty-state noise)
+- Approval hook — only triggers for write operations on sensitive file patterns; safe paths are unaffected
+- Telemetry — append-only, never read during hook execution, cannot slow down tool calls
+
+First-run behavior: all new `.codebase/` data files are created on first use. No migration needed.

package/docs/index.md

@@ -0,0 +1,75 @@
+# FlowDeck Documentation
+
+FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates 29 specialist agents through a four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
+
+---
+
+## Getting Started
+
+| Document | Description |
+|----------|-------------|
+| [Installation](installation.md) | Prerequisites, all three install methods, verification commands, and how to uninstall |
+| [Quick Start](quick-start.md) | Step-by-step walkthrough of your first 15 minutes with FlowDeck |
+| [Best Practices](best-practices.md) | Maximize efficiency and safety with Spec-Driven Development and Ensemble Reasoning |
+
+---
+
+## Reference
+
+| Document | Description |
+|----------|-------------|
+| [Agents](agents.md) | All 29 agents — names, roles, models, and when to invoke each one |
+| [Skills](skills.md) | All 24 skills — what each skill does and example prompts that activate it |
+| [Commands](commands.md) | All 27 slash commands — syntax, arguments, and what each command triggers |
+| [Workflows](workflows.md) | All 15 built-in workflows — flow diagrams, inputs, outputs, and agent involvement |
+| [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
+| [Intelligence Features](intelligence.md) | 15 AI-safety features: impact radar, patch trust, blast radius, decision trace, and more |
+
+---
+
+## Advanced
+
+| Document | Description |
+|----------|-------------|
+| [Parallel Execution](parallel-execution.md) | How FlowDeck fans out independent tasks across multiple agents simultaneously |
+| [Multi-Repo](multi-repo.md) | Coordinating changes across two or more repositories in a single session |
+| [Notifications](notifications.md) | Desktop and system alerts for long-running task completion |
+
+---
+
+## Setup & Maintenance
+
+| Document | Description |
+|----------|-------------|
+| [Configuration](configuration.md) | `opencode.json` fields, project config schema, environment variables, and plugin tools |
+| [Troubleshooting](troubleshooting.md) | Fixes for the most common problems: missing agents, corrupted state, build failures |
+
+---
+
+## Quick Command Cheat Sheet
+
+| Command | What it does |
+|---------|--------------|
+| `/fd-new-project <name>` | Initialize `.planning/` directory structure for a new project |
+| `/fd-discuss <phase>` | Run structured requirements Q&A with `@discusser` |
+| `/fd-plan <phase>` | Generate a wave-structured `PLAN.md` (requires `CONFIRMED` to execute) |
+| `/fd-new-feature "<description>"` | Execute full feature workflow via `@orchestrator` |
+| `/fd-review-code [staged\|branch]` | Parallel review by `@reviewer`, `@security-auditor`, `@tester` |
+| `/fd-fix-bug "<description>"` | Diagnose and fix a bug with regression test |
+| `/fd-checkpoint` | Save current state — safe to close the session after this |
+| `/fd-resume` | Reload `STATE.md` and `PLAN.md` context in a new session |
+| `/fd-progress` | Print current state, active plan, and recent results |
+| `/fd-map-codebase` | Generate `.codebase/` documentation from source analysis |
+| `/fd-roadmap` | View or update phase statuses and milestones |
+| `/fd-dashboard` | Open the project dashboard with phase progress and blockers |
+| `/fd-deploy-check` | Run pre-deployment checks and produce a go/no-go verdict |
+| `/fd-write-docs` | Generate or update project documentation |
+| `/fd-multi-repo` | Coordinate a change across multiple registered repositories |
+| `/fd-settings` | View or update FlowDeck model assignments and configuration |
+| `/fd-impact-radar` | Predict affected files/APIs/tests before editing |
+| `/fd-blast-radius` | Show downstream consequences and hidden dependencies of a change |
+| `/fd-translate-intent` | Convert vague request into ranked concrete implementation options |
+| `/fd-volatility-map` | Show unstable code zones by churn and hotfix frequency |
+| `/fd-regression-predict` | Estimate likely regression categories before making a change |
+| `/fd-test-gap` | Identify weakly-tested areas in a proposed change |
+| `/fd-review-route` | Route risky patches to security, backend, infra, or domain reviewers |

package/docs/installation.md

@@ -0,0 +1,134 @@
+# FlowDeck Installation
+
+This guide covers all three ways to install FlowDeck, how to verify the installation, how to keep it up to date, and how to remove it cleanly.
+
+---
+
+## Prerequisites
+
+Before installing FlowDeck, ensure the following tools are available:
+
+| Requirement | Minimum version | Check command |
+|-------------|----------------|---------------|
+| OpenCode | 1.0 | `opencode --version` |
+| Node.js | 18 | `node --version` |
+| npm | 9 | `npm --version` |
+
+If OpenCode is not yet installed, follow the [OpenCode installation guide](https://opencode.ai/docs) before continuing.
+
+---
+
+## 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`.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
+```
+
+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
+
+---
+
+## Method 2: npx (no git required)
+
+If you prefer not to clone the repository, run FlowDeck's bundled installer directly through npm:
+
+```bash
+npx @dv.nghiem/flowdeck install
+```
+
+This fetches the latest published package from the npm registry and runs the same installation steps as the curl method.
+
+---
+
+Steps explained:
+
+- `npm install` — fetches Node.js dependencies
+- `npm run build` — compiles TypeScript source in `src/` to `dist/`
+- `bash install.sh` — copies built assets to `~/.config/opencode/` and updates `opencode.json`
+
+---
+
+## Verification
+
+After any install method, run these commands to confirm everything landed correctly:
+
+```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
+```
+
+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)).
+
+---
+
+## Updating FlowDeck
+
+### curl method
+
+Re-running the install script downloads and applies the latest version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
+```
+
+The script overwrites existing FlowDeck files and updates the plugin cache.
+
+### npm method
+
+```bash
+npm update -g @dv.nghiem/flowdeck && npx @dv.nghiem/flowdeck install
+```
+
+---
+
+## Uninstalling
+
+```bash
+bash uninstall.sh
+```
+You can also add the `--local` flag to uninstall from a local project `.opencode/` directory instead of the global config.
+
+The uninstall script automatically scans the FlowDeck package and safely removes any installed agents, skills, and commands from your OpenCode config directory. It does not delete your project's `.planning/` directory or any state files.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_CONFIG_DIR` | `~/.config/opencode` | Override the directory where FlowDeck installs agents, skills, and commands |
+| `XDG_CONFIG_HOME` | `~/.config` | Standard XDG base directory; used when `OPENCODE_CONFIG_DIR` is not set |
+
+Set `OPENCODE_CONFIG_DIR` before running the install script to place FlowDeck files in a non-default location:
+
+```bash
+OPENCODE_CONFIG_DIR=/custom/path bash install.sh
+```
+
+---
+
+← [Back to Index](index.md)