@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/configuration/index.md

@@ -0,0 +1,208 @@
+# Configuration
+
+FlowDeck is configured via the OpenCode configuration file at `~/.config/opencode/opencode.json` (or `$OPENCODE_CONFIG_DIR/opencode.json`). This file is managed by FlowDeck's `postinstall` script — the plugin is registered automatically when you install FlowDeck.
+
+> **Note:** FlowDeck uses `opencode.json` (OpenCode's global config), not `flowdeck.json`. This page documents the schema understood by FlowDeck's plugin layer.
+
+---
+
+## Top-Level Schema
+
+```json
+{
+  "agents": { ... },
+  "governance": { ... },
+  "model_profile": "balanced",
+  "tdd_enforced": false,
+  "approval_required": false,
+  "volatility_threshold": 0.5,
+  "default_agent": "orchestrator"
+}
+```
+
+All keys are optional unless noted.
+
+---
+
+## `agents` — Per-Agent Model Override
+
+> **Default:** every agent inherits the active OpenCode model.
+
+Override the model for specific agents when you want a cheaper or more capable model for particular roles (e.g., a fast model for summarization, Opus for complex planning).
+
+```json
+{
+  "agents": {
+    "planner":    { "model": "anthropic/claude-opus-4" },
+    "architect":  { "model": "anthropic/claude-opus-4" },
+    "reviewer":  { "model": "openai/gpt-4o-mini" },
+    "tester":     { "model": "anthropic/claude-sonnet-4" },
+    "debugger":   { "model": "openai/gpt-4o-mini" }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | string | Full model spec in `provider/model` format. Examples: `anthropic/claude-opus-4`, `openai/gpt-4o-mini`, `google/gemini-2.5-pro` |
+
+---
+
+## `governance` — Runtime Safety Services
+
+FlowDeck's governance layer validates multi-agent execution. Each service can be toggled independently.
+
+```json
+{
+  "governance": {
+    "validator": {
+      "mode": "advisory"
+    },
+    "delegationBudget": {
+      "maxToolCalls": 200,
+      "maxDepth": 8,
+      "maxSameStepRetries": 3
+    },
+    "deadlockDetection": {
+      "enabled": true,
+      "bounceThreshold": 3,
+      "autoStop": false
+    },
+    "scorecard": {
+      "enabled": true
+    },
+    "agentContractRegistry": {
+      "contracts": {}
+    }
+  }
+}
+```
+
+### `validator` — Agent Validation Mode
+
+| Mode | Description |
+|------|-------------|
+| `off` | No validation performed |
+| `advisory` | Logs violations; does not block execution |
+| `strict` | Blocks agent actions that violate their capability contract |
+
+In `advisory` mode, a violation produces a warning in the session log:
+```
+[flowdeck/validator] Agent 'coder' called forbidden tool 'deleteFile'
+```
+
+### `delegationBudget` — Per-Run Resource Limits
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `maxToolCalls` | number | Maximum tool calls per agent invocation |
+| `maxDepth` | number | Maximum delegation chain depth (e.g., orchestrator → architect → coder is depth 2) |
+| `maxSameStepRetries` | number | Maximum retries when an agent is stuck on the same step |
+
+### `deadlockDetection` — Loop and Stall Detection
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable deadlock/loop detection |
+| `bounceThreshold` | number | Number of same-task bounces before flagging as a potential loop |
+| `autoStop` | boolean | If `true`, stops execution when a deadlock is detected |
+
+Deadlock signals are written to `.codebase/DEADLOCK_SIGNALS.jsonl`.
+
+### `scorecard` — Workflow Quality Recording
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable 10-dimension workflow quality scorecard |
+
+Scorecards are written to `.codebase/SCORECARDS.jsonl` after each run. Dimensions include TDD adherence, design-first completion, approval rate, and budget efficiency.
+
+### `agentContractRegistry` — Agent Capability Contracts
+
+Defines per-agent allowed/forbidden tools, required inputs, and success criteria.
+
+```json
+{
+  "governance": {
+    "agentContractRegistry": {
+      "contracts": {
+        "coder": {
+          "allowedTools": ["Read", "Edit", "Bash", "WebSearch"],
+          "forbiddenTools": ["Write"],
+          "requires": ["task_description"],
+          "successCriteria": ["compiles", "tests_pass"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## `model_profile` — Context Window Balance
+
+Controls how FlowDeck balances token usage vs. thoroughness.
+
+| Value | Description |
+|-------|-------------|
+| `balanced` | Default. Moderate context usage. Good for most workflows. |
+| `fast` | Prioritizes low token usage. Use for simple, well-understood tasks. |
+| `thorough` | Maximizes context usage. Use for complex multi-file refactors or unfamiliar codebases. |
+
+---
+
+## `tdd_enforced` — Test-Driven Development Enforcement
+
+> **Default:** `false`
+
+When `true`, FlowDeck agents will enforce TDD discipline: failing tests must be written before any implementation code is added. The `reviewer` agent will flag any implementation that is not preceded by a failing test.
+
+---
+
+## `approval_required` — Phase Approval Gates
+
+> **Default:** `false`
+
+When `true`, FlowDeck will pause at each phase boundary and require explicit user approval before proceeding. Useful for high-stakes changes where you want to review plan output before execution begins.
+
+---
+
+## `volatility_threshold` — Risk Scoring Cutoff
+
+> **Default:** `0.5` | **Range:** `0.0` – `1.0`
+
+Used by FlowDeck's AI safety layer to determine when a change is considered "volatile" (high risk of regression). Changes with a volatility score above this threshold are flagged or blocked depending on governance mode.
+
+- `0.0` — everything is flagged as volatile
+- `1.0` — nothing is flagged (effectively disabled)
+- `0.3` — conservative; flags many changes
+- `0.7` — permissive; only flags obviously risky changes
+
+---
+
+## `default_agent` — Default Dispatch Target
+
+> **Default:** `orchestrator`
+
+Sets the agent that receives commands when no explicit agent is specified. The `orchestrator` coordinates sub-agents and is the appropriate default for most workflows.
+
+```json
+{
+  "default_agent": "orchestrator"
+}
+```
+
+Other valid targets include `planner`, `architect`, `coder`, `reviewer`, `tester`, `debugger`, `risk-analyst`, and `policy-enforcer`.
+
+---
+
+## Environment Variables
+
+FlowDeck reads the following environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_CONFIG_DIR` | `~/.config/opencode` | OpenCode configuration directory |
+| `XDG_CONFIG_HOME` | `~/.config` | XDG Base Directory, used to derive `OPENCODE_CONFIG_DIR` |
+| `FLOWDECK_CONTEXT_LIMIT` | `200000` | Context window token limit for context monitor warnings |

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)