@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/docs/configuration/opencode-settings.md

@@ -0,0 +1,98 @@
+# OpenCode Integration Settings
+
+FlowDeck integrates with OpenCode as a plugin. This page explains how the plugin is registered, what gets published as an npm package, and what environment variables FlowDeck reads at runtime.
+
+---
+
+## Plugin Registration
+
+FlowDeck uses the `@opencode-ai/plugin` package to register itself with OpenCode. After running `npm install @dv.nghiem/flowdeck`, the `postinstall` script (`postinstall.mjs`) automatically:
+
+1. Reads the OpenCode global config at `~/.config/opencode/opencode.json` (or `$OPENCODE_CONFIG_DIR/opencode.json`)
+2. Adds `"@dv.nghiem/flowdeck"` to the `plugin` array if not already present
+3. Sets `"default_agent": "orchestrator"` if not already set
+4. Writes the updated config back to disk
+
+OpenCode loads all plugins listed in the `plugin` array on startup.
+
+---
+
+## Package Contents
+
+The `package.json` `files` field controls what gets published as the npm package:
+
+```
+files:
+  dist/         — compiled plugin code
+  bin/          — CLI entry point
+  src/commands/ — command implementations
+  src/rules/    — coding standards
+  src/skills/   — skill definitions
+  docs/         — documentation
+  postinstall.mjs — post-install registration script
+```
+
+The npm package does **not** include `src/agents/`, `src/tools/`, `src/hooks/` (with the exception of `src/skills/`), or development files.
+
+---
+
+## Plugin Architecture
+
+FlowDeck registers its capabilities through the following source directories:
+
+### `src/agents/`
+
+Agent definitions. Each agent specifies its role, allowed tools, instructions, and delegation policies.
+
+### `src/tools/`
+
+Tool definitions. These extend OpenCode's tool set with FlowDeck-specific capabilities.
+
+### `src/hooks/`
+
+System hooks that react to OpenCode lifecycle events:
+
+| Hook File | When It Fires | Purpose |
+|-----------|---------------|---------|
+| `session-start.ts` | `session.created` | Loads prior state from `.planning/STATE.md` and injects phase/status/steps into context |
+| `compaction-hook.ts` | `experimental.session.compacting` | Injects structured planning context before context window compaction |
+| `shell-env-hook.ts` | Every `bash` tool execution | Injects `FLOWDECK_VERSION`, `PROJECT_ROOT`, `PACKAGE_MANAGER`, `DETECTED_LANGUAGES`, `FLOWDECK_PHASE` env vars |
+| `context-window-monitor.ts` | `message.updated`, `tool.execute.after` | Warns when context usage exceeds 70% of the token limit |
+| `session-idle-hook.ts` | `session.idle` (when files edited) | Sends desktop notification and logs edited file summary |
+| `notifications.ts` | Various | Desktop notification dispatch |
+| `file-tracker.ts` | During session | Tracks edited file paths across agent turns |
+
+### `src/skills/`
+
+Skill definitions exported via the plugin's skill registration API. Skills expose reusable workflow patterns (TDD, security scan, code review, etc.) to OpenCode's skill system.
+
+---
+
+## Environment Variables
+
+FlowDeck reads the following environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_CONFIG_DIR` | `~/.config/opencode` | OpenCode configuration directory |
+| `XDG_CONFIG_HOME` | `~/.config` | Used to derive `OPENCODE_CONFIG_DIR` if not set |
+| `FLOWDECK_CONTEXT_LIMIT` | `200000` | Token limit for context window monitor (used by `context-window-monitor.ts`) |
+
+FlowDeck does **not** read any API keys, tokens, or secrets. All model authentication is handled by OpenCode.
+
+---
+
+## opencode.json Schema (Plugin Section)
+
+After installation, your `opencode.json` looks like:
+
+```json
+{
+  "plugin": [
+    "@dv.nghiem/flowdeck"
+  ],
+  "default_agent": "orchestrator"
+}
+```
+
+FlowDeck's plugin reads the top-level keys described in [Configuration](index.md) (`agents`, `governance`, `model_profile`, etc.) from this same file.

package/docs/getting-started/first-project.md

@@ -0,0 +1,126 @@
+# First Project — End-to-End Walkthrough
+
+This guide walks through creating a simple feature end-to-end, showing what FlowDeck produces at each step.
+
+## Step 1: Map the Codebase
+
+```bash
+fd-map-codebase
+```
+
+FlowDeck analyses the project and creates `.codebase/` with:
+- `.codebase/CODEGRAPH.json` — dependency graph
+- `.codebase/CONVENTIONS.md` — detected code conventions
+- `.codebase/CODEBASE_INDEX.md` — high-level structural index
+
+This step is required before starting a feature.
+
+## Step 2: Start a Feature
+
+```bash
+fd-new-feature "user authentication"
+```
+
+FlowDeck initializes `.planning/` (if it doesn't exist yet) and creates `.planning/phases/phase-1/FEATURE.md`:
+
+```markdown
+# Feature: user authentication
+
+## Description
+user authentication
+
+## Status
+discuss
+
+## Created
+2026-05-26
+```
+
+## Step 3: Discuss
+
+```bash
+fd-discuss
+```
+
+The discusser agent runs structured Q&A and produces **`DISCUSS.md`**:
+
+```markdown
+# Discussion — user authentication
+
+## Q: What is the scope?
+A: [agent response]
+
+## Q: What are the constraints?
+A: [agent response]
+
+## Decisions
+- [captured decisions listed here]
+```
+
+## Step 4: Plan
+
+```bash
+fd-plan
+```
+
+When prompted, type `CONFIRM` to proceed. The planner generates **`PLAN.md`**:
+
+```markdown
+# Plan — user authentication
+
+## Wave 1 (parallel)
+- [ ] Implement user model
+- [ ] Create auth service
+- [ ] Write unit tests
+
+## Wave 2 (parallel)
+- [ ] Implement login endpoint
+- [ ] Implement registration endpoint
+- [ ] Add integration tests
+
+## Wave 3 (sequential)
+- [ ] Security audit
+- [ ] Documentation
+```
+
+## Step 5: Execute
+
+```bash
+fd-execute
+```
+
+Agents work through each wave in `PLAN.md`. Independent tasks run in parallel. State is updated in `STATE.md` after each task.
+
+## Step 6: Verify
+
+```bash
+fd-verify
+```
+
+Runs the full verification pipeline:
+- Unit and integration tests
+- Code review by reviewer agent
+- Security scan
+- Deploy check
+
+Results are written to `.planning/VERIFICATION.md`.
+
+## What You Have Now
+
+After completing the full workflow:
+
+```
+.planning/
+  STATE.md        — current phase and progress
+  ROADMAP.md      — all features and timeline
+  PLAN.md         — current feature execution plan
+  DISCUSS.md      — captured decisions
+  VERIFICATION.md — test results, review, security
+.codebase/
+  CODEGRAPH.json      — dependency graph
+  CONVENTIONS.md      — detected code conventions
+  CODEBASE_INDEX.md   — structural index
+```
+
+You can now run `/fd-status` to see the project overview, or start a new feature with `/fd-new-feature`.
+

package/docs/getting-started/installation.md

@@ -0,0 +1,73 @@
+# Installation
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai) installed and configured
+- Node.js 18+ (for npx installation)
+- Git (for curl installation)
+
+## Install Methods
+
+### Method 1: curl (recommended)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
+```
+
+This downloads and runs the official installer script. It clones the repository and runs the post-install setup.
+
+### Method 2: npx
+
+```bash
+npx @dv.nghiem/flowdeck install
+```
+
+No git required. Uses npx to fetch and install the package directly.
+
+## Verify Installation
+
+Run the health check command:
+
+```bash
+flowdeck doctor
+```
+
+Expected output shows FlowDeck version, OpenCode plugin status, and environment health.
+
+Alternatively, verify the binary is in your path:
+
+```bash
+which flowdeck
+```
+
+## Post-Installation
+
+After installation, FlowDeck registers as an OpenCode plugin. Restart OpenCode to load the plugin and its commands.
+
+## Environment Variables
+
+FlowDeck respects the following environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FLOWDECK_CONFIG` | Path to flowdeck.json config | `./flowdeck.json` |
+| `FLOWDECK_STATE_DIR` | Directory for state files | `.planning/` |
+| `OPENCODE_MODEL` | Model to use when not overridden | (OpenCode default) |
+
+## Uninstall
+
+### Method 1: npm
+
+```bash
+npm uninstall -g @dv.nghiem/flowdeck
+```
+
+### Method 2: Run uninstall script
+
+If you used the curl installer:
+
+```bash
+./uninstall.sh
+```
+
+This removes the plugin from OpenCode and cleans up installed files.

package/docs/getting-started/quick-start.md

@@ -0,0 +1,74 @@
+# Quick Start — First 15 Minutes
+
+Get FlowDeck installed and run your first feature workflow in under 15 minutes.
+
+## Step 1: Install FlowDeck
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
+```
+
+See [Installation](installation.md) for alternative install methods.
+
+## Step 2: Verify Installation
+
+```bash
+flowdeck doctor
+```
+
+Checks that FlowDeck is installed, the OpenCode plugin is loaded, and your environment is ready.
+
+## Step 3: Map the Codebase
+
+```bash
+fd-map-codebase
+```
+
+Analyses the project and writes structured indexes to `.codebase/`. This is required before starting a feature — it gives all subsequent agents the context they need.
+
+## Step 4: Start a Feature
+
+```bash
+fd-new-feature "hello world API"
+```
+
+Initializes feature context and creates a `FEATURE.md` file in the current phase directory. If `.planning/` does not exist yet, it is created automatically.
+
+## Step 5: Discuss the Feature
+
+```bash
+fd-discuss
+```
+
+Runs structured Q&A to capture requirements, constraints, and decisions. Saves to `DISCUSS.md`.
+
+## Step 6: Plan Implementation
+
+```bash
+fd-plan
+```
+
+Generates a wave-structured execution plan. When prompted, type `CONFIRM` to proceed.
+
+The planner outputs a `PLAN.md` with task waves — groups of independent tasks that can run in parallel.
+
+## Step 7: Execute
+
+```bash
+fd-execute
+```
+
+Implements the feature using TDD discipline. Parallel agents (architect, coder, tester, reviewer) work through the plan waves.
+
+## What to Expect
+
+After completing these steps you will have:
+
+- A `.planning/` directory with full project state
+- A `PLAN.md` with executable task breakdown
+- Working code with tests
+- Verification results from the review pipeline
+
+## Next Steps
+
+- [First Project → End-to-End Walkthrough](first-project.md) — see what the output files actually look like

package/docs/index.md

@@ -1,72 +1,36 @@
-# FlowDeck Documentation
-
-FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a gated workflow — discuss, plan, design (UI-heavy), 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 specialist agents — names, roles, and when to invoke each one |
-| [Skills](skills.md) | Reusable skill patterns for common tasks |
-| [Commands](commands.md) | All 18 slash commands — syntax, arguments, and what each command triggers |
-| [Workflows](workflows.md) | Built-in workflows for common scenarios |
-| [Design-First Workflow](design-first-workflow.md) | UI-heavy workflow gates from design discovery to implementation handoff |
-| [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
-| [Intelligence Features](intelligence.md) | AI-safety features for pre-change analysis and risk assessment |
-| [Governance Layer](configuration.md#governance-config) | Agent contracts, validator, trace graph, budget, deadlock detection, and scorecards |
-| [Memory System](memory.md) | Persistent memory — recall past sessions, tool executions, and context across sessions |
-
----
-
-## Advanced
-
-| Document | Description |
-|----------|-------------|
-| [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 project with planning structure and default config |
-| `/fd-discuss <topic>` | Run structured requirements Q&A to capture decisions |
-| `/fd-plan [--phase=N]` | Generate implementation plan from decisions (requires CONFIRM) |
-| `/fd-design [--mode=draft\|review\|system]` | Run design-first planning and UI fidelity review for UI-heavy tasks |
-| `/fd-new-feature "<description>"` | Execute full feature workflow with TDD discipline |
-| `/fd-fix-bug "<description>"` | Diagnose and fix a bug with regression test |
-| `/fd-deploy-check [--check=deploy,review,analysis]` | Pre-deploy checks, code review, or pre-change analysis |
-| `/fd-status [--roadmap\|--workspace\|--phase=N]` | Combined status, roadmap, and workspace view |
-| `/fd-checkpoint` | Save current state — safe to close the session after this |
-| `/fd-resume [--yes]` | Reload STATE.md and PLAN.md to continue interrupted session |
-| `/fd-reflect [--mode=reflect,learn]` | Post-session reflection or capture skill from session |
-| `/fd-map-codebase [--incremental]` | Generate `.codebase/` documentation |
-| `/fd-write-docs [--scope=path]` | Generate documentation from public APIs |
-| `/fd-multi-repo <list\|add\|remove\|status>` | Manage multi-repo configuration |
-| `/fd-translate-intent "<vague request>"` | Convert vague request into ranked implementation options |
-| `/fd-ask "<question>"` | Route question to specialist agent |
-| `/fd-quick "<task>"` | Quick focused task with automatic agent selection |
-| `/fd-doctor` | Check FlowDeck installation and environment health |
+# FlowDeck
+
+> AI-powered multi-agent workflow orchestration with built-in safety intelligence for OpenCode
+
+FlowDeck structures every feature through a six-step cycle:
+`/fd-map-codebase` → `/fd-new-feature` → `/fd-discuss` → `/fd-plan` → `/fd-execute` → `/fd-verify`
+
+## Features
+
+- **25 agents** — architect, planner, coder, reviewer, tester, debugger, risk-analyst, policy-enforcer, and more
+- **59 skills** — reusable workflow patterns (TDD, security scan, code review, deploy check, and more)
+- **20 commands** — workflow commands for all project operations
+- **Persistent state** — resume exactly where you left off across sessions via `.planning/STATE.md`
+- **Parallel execution** — independent tasks run simultaneously in wave-structured batches
+- **AI Safety layer** — patch trust scoring, edit gates, phase gating, regression prediction built into every workflow
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/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 |
+| `/fd-execute` | Implement feature with TDD discipline and parallel agents |
+| `/fd-verify` | Full verification pipeline: tests, code review, security scan |
+| `/fd-checkpoint` | Save a mid-session checkpoint to STATE.md |
+| `/fd-resume` | Reload checkpoint to continue interrupted session |
+| `/fd-status` | View project progress and roadmap |
+| `/fd-doctor` | Check FlowDeck installation and environment health |
+
+## Next Steps
+
+- [Getting Started → Installation](getting-started/installation.md)
+- [Quick Start → First 15 Minutes](getting-started/quick-start.md)
+- [First Project → Bootstrap Your First Project](getting-started/first-project.md)

package/docs/reference/hooks.md

@@ -0,0 +1,176 @@
+# System Hooks Reference
+
+FlowDeck implements deep system hooks that react to OpenCode lifecycle events. These hooks maintain session state, inject environment context, monitor resource usage, and send notifications without requiring any explicit commands.
+
+---
+
+## Hooks Overview
+
+| Hook | Fires On | Purpose |
+|------|----------|---------|
+| `session-start` | `session.created` | Loads and injects prior planning state into the new session |
+| `compaction` | `experimental.session.compacting` | Preserves planning context before context window compaction |
+| `shell-env` | Every `bash` tool execution | Injects FlowDeck environment variables |
+| `context-window-monitor` | `message.updated`, `tool.execute.after` | Warns when context usage exceeds 70% of the token limit |
+| `session-idle` | `session.idle` (when files edited) | Desktop notification and edits summary logging |
+| `notifications` | Various | Desktop notification dispatch |
+| `file-tracker` | During session | Tracks edited file paths across agent turns |
+
+---
+
+## `session-start` Hook
+
+**File:** `src/hooks/session-start.ts`
+
+**Fires:** `session.created` — when a new OpenCode session starts.
+
+**What it does:**
+
+Reads `.planning/STATE.md` from the workspace and injects the following context keys:
+
+| Context Key | Source | Description |
+|------------|--------|-------------|
+| `flowdeck_phase` | `current_phase.phase` in STATE.md | Current planning phase or `null` if fresh |
+| `flowdeck_status` | `current_phase.status` in STATE.md | Phase status or `null` |
+| `flowdeck_steps_pending` | `current_phase.steps_pending` in STATE.md | Pending steps or `null` |
+| `flowdeck_last_action` | `current_phase.last_action` in STATE.md | Last executed action or `null` |
+| `flowdeck_has_codebase` | — | Whether `.codebase/` directory exists |
+| `flowdeck_workspace_root` | `opencode.json` workspace config | Workspace root if multi-repo detected |
+| `flowdeck_sub_repos` | `opencode.json` workspace config | List of sub-repositories |
+| `flowdeck_workspace_mode` | `opencode.json` workspace config | Workspace mode |
+
+**State read:**
+- `.planning/STATE.md`
+- `.codebase/` (existence check only)
+- `opencode.json` (workspace config, if present)
+
+**Errors:** If the state file is unreadable, the hook returns with `flowdeck_status: "error"` and a warning message — it does not block session startup.
+
+---
+
+## `compaction` Hook
+
+**File:** `src/hooks/compaction-hook.ts`
+
+**Fires:** `experimental.session.compacting` — when OpenCode triggers context window compaction.
+
+**What it does:**
+
+Injects a structured 8-section summary into the compaction context so the LLM summarization preserves FlowDeck-specific state:
+
+1. **Planning State** — First 1500 characters of `.planning/STATE.md`
+2. **Codebase Index** — First 800 characters of `.planning/CODEBASE_INDEX.md` (if present)
+3. **Recently Edited Files** — Up to 20 files from `SessionFileTracker`
+
+Then replaces the default summarization prompt with a structured template that requires the summary to include:
+- User requests (verbatim)
+- Final goal
+- Work completed
+- Remaining tasks
+- Active working context
+- Explicit constraints (verbatim)
+- Verification state
+- Delegated agent sessions (with `session_id` for resume)
+
+**State read:**
+- `.planning/STATE.md`
+- `.planning/CODEBASE_INDEX.md`
+- In-memory `SessionFileTracker` (edited paths ring buffer)
+
+---
+
+## `shell-env` Hook
+
+**File:** `src/hooks/shell-env-hook.ts`
+
+**Fires:** Every `bash` tool execution.
+
+**What it does:**
+
+Injects the following environment variables into every bash tool execution:
+
+| Env Var | Source | Description |
+|---------|--------|-------------|
+| `FLOWDECK_VERSION` | `package.json` | Installed FlowDeck version |
+| `FLOWDECK_PLUGIN` | `"true"` (constant) | Plugin activation flag |
+| `PROJECT_ROOT` | `worktree` or `directory` | Resolved project root |
+| `PACKAGE_MANAGER` | Detected lockfile | `npm`, `yarn`, `pnpm`, or `bun` |
+| `DETECTED_LANGUAGES` | Marker files scan | Comma-separated list (e.g., `typescript,python`) |
+| `PRIMARY_LANGUAGE` | Marker files scan | First detected language |
+| `FLOWDECK_PHASE` | `STATE.md` phase field | Current FlowDeck planning phase |
+
+Language detection uses marker files: `tsconfig.json` (TypeScript), `go.mod` (Go), `pyproject.toml`/`requirements.txt` (Python), `Cargo.toml` (Rust), `build.gradle`/`pom.xml` (Java).
+
+**State read:** `package.json`, lockfiles, marker files, `.planning/STATE.md`
+
+---
+
+## `context-window-monitor` Hook
+
+**File:** `src/hooks/context-window-monitor.ts`
+
+**Fires:** `message.updated` (assistant messages with token info), `tool.execute.after`.
+
+**What it does:**
+
+Tracks token usage per session. When input token usage exceeds 70% of `FLOWDECK_CONTEXT_LIMIT` (default: 200,000 tokens), appends a warning to the next tool output:
+
+```
+[FlowDeck Context Monitor]
+Context: 71.4% used (142,800/200,000 tokens), 28.6% remaining.
+You still have context remaining — do NOT rush or skip tasks. Work thoroughly.
+```
+
+The warning fires once per session (tracked by `sessionID`).
+
+**Token limit override:** Set `FLOWDECK_CONTEXT_LIMIT` env var (e.g., `FLOWDECK_CONTEXT_LIMIT=150000`).
+
+**State read:** Per-session token cache from `message.updated` events.
+
+---
+
+## `session-idle` Hook
+
+**File:** `src/hooks/session-idle-hook.ts`
+
+**Fires:** `session.idle` — when OpenCode's session becomes idle after a task is completed.
+
+**Fires only when:** At least one file has been edited during the session (empty idle events are ignored).
+
+**What it does:**
+
+1. Sends a desktop notification via `notifySessionIdle()`
+2. Logs a session summary via `client.app.log` (up to 10 edited files, then `… and N more`)
+
+**State read:** In-memory `SessionFileTracker` (edited paths ring buffer).
+
+---
+
+## `file-tracker`
+
+**File:** `src/hooks/file-tracker.ts`
+
+**When it runs:** Continuously during session, tracking every file path edited by agents.
+
+**What it does:**
+
+Maintains a ring buffer of edited file paths. Consumed by the `compaction` hook (recently edited files) and `session-idle` hook (edited summary).
+
+Implements a windowed snapshot of edited paths per session — consumed by compaction hook and idle hook.
+
+---
+
+## Other Hooks
+
+| Hook | File | Purpose |
+|------|------|---------|
+| `approval-hook` | `approval-hook.ts` | Phase/project-level approval gates |
+| `orchestrator-guard-hook` | `orchestrator-guard-hook.ts` | Guarding orchestrator delegation patterns |
+| `decision-trace-hook` | `decision-trace-hook.ts` | Decision audit trail |
+| `telemetry-hook` | `telemetry-hook.ts` | Workflow telemetry |
+| `patch-trust` | `patch-trust.ts` | AI safety: patch trust scoring |
+| `tool-guard` | `tool-guard.ts` | Tool usage guardrails |
+| `auto-learn-hook` | `auto-learn-hook.ts` | Runtime policy learning |
+| `todo-hook` | `todo-hook.ts` | Todo tracking integration |
+
+These hooks are internal governance and safety mechanisms. The five hooks described above are the ones users interact with most directly.