@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/docs/concepts/multi-repo.md

@@ -0,0 +1,227 @@
+# Multi-Repo
+
+FlowDeck can coordinate changes across multiple repositories in a single session. Each repository is registered with the session, assigned a role, and managed through the `/fd-multi-repo` command. Coordination state is persisted in `.planning/multi-repo/` so sessions can be resumed.
+
+---
+
+## /fd-multi-repo Command
+
+The `fd-multi-repo` command is the entry point for all multi-repo operations. It supports four subcommands:
+
+| Subcommand | Description |
+|------------|-------------|
+| `fd-multi-repo add <path> [role]` | Register a repository at `<path>` with an optional role |
+| `fd-multi-repo remove <path>` | Unregister a repository |
+| `fd-multi-repo list` | Print all registered repositories and their roles |
+| `fd-multi-repo status` | Show sync state, pending changes, and divergence status |
+
+**Roles** classify the repository's purpose in the session:
+
+| Role | Meaning |
+|------|---------|
+| `primary` | The main development repository (default for the first added) |
+| `library` | An internal library or shared module |
+| `service` | A microservice or backend API |
+| `frontend` | A frontend application |
+| `config` | A configuration or infrastructure repository |
+
+The role determines how FlowDeck routes planning and which agents are responsible for changes to that repo.
+
+### Adding a Repository
+
+```bash
+fd-multi-repo add /home/user/project-lib library
+```
+
+This:
+
+1. Verifies the path exists and is a git repository
+2. Reads the `flowdeck.json` config if present in that repo
+3. Records the repo in `.planning/multi-repo/REPOSITORIES.json`
+4. Runs `/fd-map-codebase` on the new repository to index it into `.codebase/<repo-name>/`
+
+### Removing a Repository
+
+```bash
+fd-multi-repo remove /home/user/project-lib
+```
+
+This removes the repository from `REPOSITORIES.json` and deletes its `.codebase/<repo-name>/` index. It does not delete any files.
+
+---
+
+## Coordination State
+
+All multi-repo state lives under `.planning/multi-repo/`:
+
+```
+.planning/multi-repo/
+  REPOSITORIES.json      — registered repos, roles, paths
+  CHANGES.json           — pending cross-repo changes
+  DEPENDENCIES.json      — dependency graph between repos
+  SYNC.json              — sync status and divergence flags
+```
+
+### REPOSITORIES.json
+
+```json
+{
+  "repositories": [
+    {
+      "name": "flowdeck",
+      "path": "/home/user/flowdeck",
+      "role": "primary",
+      "addedAt": "2026-05-26T08:00:00Z",
+      "lastSynced": "2026-05-26T10:00:00Z"
+    },
+    {
+      "name": "flowdeck-lib",
+      "path": "/home/user/flowdeck-lib",
+      "role": "library",
+      "addedAt": "2026-05-26T08:05:00Z",
+      "lastSynced": "2026-05-26T09:55:00Z"
+    }
+  ]
+}
+```
+
+### CHANGES.json
+
+Tracks planned or in-progress changes that span multiple repositories:
+
+```json
+{
+  "changes": [
+    {
+      "id": "ch-001",
+      "description": "Add telemetry API to flowdeck-lib",
+      "status": "planned",
+      "affectedRepos": ["flowdeck-lib", "flowdeck"],
+      "planRef": ".planning/PLAN.md#ch-001"
+    }
+  ]
+}
+```
+
+### DEPENDENCIES.json
+
+Records declared dependencies between repositories (e.g., `flowdeck` imports `flowdeck-lib`):
+
+```json
+{
+  "dependencies": [
+    {
+      "from": "flowdeck",
+      "to": "flowdeck-lib",
+      "type": "import",
+      "files": ["src/lib/telemetry.ts"]
+    }
+  ]
+}
+```
+
+Dependencies are inferred from import analysis during `/fd-map-codebase` but can be manually overridden in `flowdeck.json`.
+
+---
+
+## Cross-Repo Planning
+
+When `/fd-plan` runs in a multi-repo session:
+
+1. The `@planner` agent reads `DISCUSS.md` and `FEATURE.md` as usual
+2. For each planned task, it checks `DEPENDENCIES.json` to determine which repository the task belongs to
+3. Tasks are organized by repository, then by wave within each repository
+4. Tasks that span multiple repositories (e.g., adding an API to a library and updating callers in the primary) are marked as **cross-repo tasks** and placed in a shared wave
+
+**Cross-repo wave execution:**
+
+```
+Wave 1 (parallel across repos)
+  ├── [flowdeck-lib] Task 1a: Add telemetry API      → @coder (flowdeck-lib)
+  └── [flowdeck]     Task 1b: Update telemetry callers → @coder (flowdeck)
+
+Wave 2 (sequential, primary waits for library)
+  └── [flowdeck]     Task 2a: Run integration tests    → @tester
+```
+
+The orchestrator enforces that all tasks in Wave 1 complete before Wave 2 begins, even across repositories.
+
+---
+
+## Cross-Repo Execution
+
+During `/fd-execute`, the orchestrator:
+
+1. Iterates through waves
+2. For each wave, dispatches tasks to their target repositories in parallel
+3. Each agent operates in its assigned repository's working directory
+4. The `DEADLOCK_SIGNALS.jsonl` from each repository is aggregated into the primary repo's `.codebase/`
+5. If a task in one repository depends on output from another, the orchestrator waits for the source task to complete first
+
+### File Coordination
+
+When a change in one repository depends on a change in another:
+
+- The dependency is declared in `DEPENDENCIES.json`
+- The planner ensures the source task runs before the dependent task
+- If both repos are on the same filesystem, FlowDeck uses absolute paths
+- If repos are on different machines, FlowDeck uses git worktree references or suggests a shared git remote
+
+---
+
+## Multi-Repo State Sync
+
+Use `fd-multi-repo status` to see the current state:
+
+```
+fd-multi-repo status
+
+Repository: flowdeck (primary)
+  Path: /home/user/flowdeck
+  Role: primary
+  Last synced: 2026-05-26 10:00:00
+  Status: clean ✓
+
+Repository: flowdeck-lib (library)
+  Path: /home/user/flowdeck-lib
+  Role: library
+  Last synced: 2026-05-26 09:55:00
+  Status: 2 commits ahead of remote
+  Pending:
+    - ch-001: Add telemetry API
+
+Cross-repo changes:
+  ch-001: Add telemetry API to flowdeck-lib
+    Status: planned
+    Affects: flowdeck-lib, flowdeck
+    Blocker: none
+```
+
+---
+
+## Configuration
+
+Declare multi-repo dependencies explicitly in `flowdeck.json` to override inferred dependencies:
+
+```json
+{
+  "multiRepo": {
+    "repositories": [
+      {
+        "name": "flowdeck-lib",
+        "path": "/home/user/flowdeck-lib",
+        "role": "library"
+      }
+    ],
+    "dependencies": [
+      {
+        "from": "flowdeck",
+        "to": "flowdeck-lib",
+        "type": "import"
+      }
+    ]
+  }
+}
+```
+
+This is useful when FlowDeck cannot infer dependencies from imports (e.g., binary dependencies, API contracts, or generated files).

package/docs/concepts/workflows.md

@@ -0,0 +1,205 @@
+# Workflows
+
+FlowDeck structures every feature through a six-step command cycle. Each step has a clear purpose, produces specific artifacts, and transitions the project state forward.
+
+## The Six-Step Cycle
+
+```
+/fd-map-codebase
+      │
+      ▼
+/fd-new-feature ─────────────────────────────────────────┐
+      │                                                 │
+      ▼                                                 │
+/fd-discuss ─────────────────────────────────────────┐   │
+      │                                              │   │
+      ▼                                              │   │
+/fd-plan ─────────────────────────────────────────┐  │   │
+      │                                            │  │   │
+      ▼                                            │  │   │
+/fd-execute ──────────────────────────────────┐    │  │   │
+      │                                      │    │  │   │
+      ▼                                      │    │  │   │
+/fd-verify ───────────────────────────────────┘    │  │   │
+                                                   │  │   │
+               (loop back to /fd-new-feature) ◄───┘  └───┘
+```
+
+Each command reads the current `STATE.md` and writes updated state when it completes. Use `/fd-checkpoint` at any time to save a mid-session snapshot and `/fd-resume` to restore it in a new session.
+
+---
+
+## /fd-map-codebase
+
+**Purpose:** Analyse and index the codebase into structured `.codebase/` files — required before starting any feature.
+
+**Files created:**
+- `.codebase/CODEGRAPH.json`
+- `.codebase/CONVENTIONS.md`
+- `.codebase/CODEBASE_INDEX.md`
+
+**Step-by-step:**
+
+1. Scan the project files and detect languages, frameworks, and patterns.
+2. Build a structured dependency graph and write it to `.codebase/CODEGRAPH.json`.
+3. Extract conventions and write them to `.codebase/CONVENTIONS.md`.
+4. Write a high-level index to `.codebase/CODEBASE_INDEX.md`.
+
+---
+
+## /fd-new-feature
+
+**Purpose:** Define a new feature and initialize its context. Requires codebase mapping (`.codebase/`) to exist.
+
+**Files created/modified:**
+- `.planning/FEATURE.md` (created)
+- `.planning/STATE.md` (created if missing, phase updated)
+- `.planning/ROADMAP.md` (feature entry added)
+
+**Step-by-step:**
+
+1. Verify `.codebase/` exists — error if not (codebase mapping is required first).
+2. Initialize `.planning/` and `STATE.md` lazily if they do not exist.
+3. Parse the feature description from the command argument.
+4. Create `FEATURE.md` with: feature name, summary, acceptance criteria, estimated complexity, related files.
+5. Append the feature to `ROADMAP.md` with status `pending`.
+6. Update `STATE.md` — set `phase: define`, `feature: <name>`, `status: in_progress`.
+
+---
+
+## /fd-discuss
+
+**Purpose:** Pre-planning structured Q&A to capture design decisions before a plan is written.
+
+**Files created/modified:**
+- `.planning/DISCUSS.md` (created)
+- `.planning/STATE.md` (phase updated)
+
+**Step-by-step:**
+
+1. The `@discusser` agent asks a series of targeted questions covering: scope boundaries, edge cases, dependencies, non-functional requirements, and known risks.
+2. Each answer is recorded in `DISCUSS.md` under a corresponding heading.
+3. The `@risk-analyst` agent reviews the Q&A log and adds a risk summary section.
+4. `STATE.md` is updated — set `phase: discuss`, `status: ready_to_plan`.
+
+The output of `/fd-discuss` is a signed decision log that the planner treats as authoritative input.
+
+---
+
+## /fd-plan
+
+**Purpose:** Build a wave-structured execution plan from the discuss decisions.
+
+**Files created/modified:**
+- `.planning/PLAN.md` (created)
+- `.planning/STATE.md` (phase updated)
+
+**Step-by-step:**
+
+1. The `@planner` agent reads `DISCUSS.md`, `FEATURE.md`, and `PROJECT.md`.
+2. It breaks the feature into **waves** — groups of tasks that can run in parallel within a wave, with waves ordered sequentially.
+3. Each task records: description, responsible agent, files affected, rollback plan, and dependencies.
+4. The plan is written to `PLAN.md`.
+5. The user reviews the plan. Typing `CONFIRM` (case-insensitive) proceeds to execution; anything else aborts.
+6. `STATE.md` is updated — set `phase: plan_confirmed`, `status: ready_to_execute`.
+
+Wave-structured planning prevents agents from blocking on tasks that could run in parallel. Wave 1 tasks that are independent run simultaneously. Wave 2 does not start until all Wave 1 tasks are complete.
+
+---
+
+## /fd-execute
+
+**Purpose:** Implement the feature following TDD discipline, with parallel agent delegation.
+
+**Files created/modified:**
+- Implementation files (modified)
+- `.planning/STATE.md` (phase updated)
+- `.planning/PLAN.md` (tasks marked complete)
+
+**Step-by-step:**
+
+1. The `@orchestrator` reads `PLAN.md` and iterates through waves.
+2. For each wave, it calls `run-pipeline` or `delegate` to invoke specialist agents in parallel:
+   - `@architect` — validates structural decisions before coding
+   - `@coder` — writes implementation following TDD (red/green/refactor)
+   - `@tester` — writes and runs tests alongside each implementation task
+   - `@reviewer` — reviews each completed task
+3. Each agent writes its output to the implementation files and updates `PLAN.md`.
+4. Governance hooks run after every tool execution — patch trust scoring, budget tracking, and deadlock detection.
+5. `STATE.md` is updated — set `phase: execute`, `status: in_progress`. On full completion, set `status: complete`.
+
+If the deadlock detector triggers, execution pauses and the user is notified with the bounce signal.
+
+---
+
+## /fd-verify
+
+**Purpose:** Full verification pipeline — tests, code review, security scan, and deploy check.
+
+**Files created/modified:**
+- Verification reports (printed to console)
+- `.planning/STATE.md` (phase updated)
+- `.codebase/SCORECARDS.jsonl` (new scorecard entry)
+
+**Step-by-step:**
+
+1. Run the full test suite — `@tester` executes all test commands.
+2. Run `@reviewer` on every changed file since the last phase.
+3. Run `@policy-enforcer` to validate architectural constraint compliance.
+4. Run security scan (if configured) and deploy check (if configured).
+5. Compute and print the Workflow Scorecard (10 dimensions).
+6. Write a scorecard entry to `.codebase/SCORECARDS.jsonl`.
+7. Update `STATE.md` — set `phase: verify`, `status: verified` or `status: issues_found`.
+8. If issues are found, the user decides whether to loop back to `/fd-execute` or fix manually.
+
+---
+
+## State Transition Table
+
+The following table shows how the key fields in `STATE.md` change at each phase:
+
+| Field | `/fd-map-codebase` | `/fd-new-feature` | `/fd-discuss` | `/fd-plan` | `/fd-execute` | `/fd-verify` |
+|-------|--------------------|-------------------|---------------|------------|---------------|--------------|
+| `phase` | — | `define` | `discuss` | `plan_confirmed` | `execute` | `verify` |
+| `status` | — | `in_progress` | `ready_to_plan` | `ready_to_execute` | `in_progress` → `complete` | `verified` |
+| `feature` | — | set | — | — | — | — |
+| `planConfirmed` | — | — | — | `true` | — | — |
+| `checkpoint` | — | — | — | — | on `/fd-checkpoint` | — |
+
+---
+
+## Wave-Structured Execution
+
+Wave structure is the mechanism that makes parallel execution safe.
+
+```
+Wave 1 (parallel)
+  ├── Task 1a: Write user model      → @coder
+  ├── Task 1b: Write auth service    → @coder
+  └── Task 1c: Write user tests      → @tester
+
+Wave 2 (parallel, starts after all Wave 1 tasks complete)
+  ├── Task 2a: Integrate auth        → @coder
+  └── Task 2b: Write integration     → @tester
+                tests
+
+Wave 3 (sequential)
+  └── Task 3a: Deploy configuration   → @architect
+```
+
+Dependencies between waves are explicit. Tasks within a wave are independent — no task in Wave 1 depends on another task in Wave 1. This maximizes parallelism while preserving ordering guarantees.
+
+The orchestrator enforces wave ordering. It will not dispatch Wave 2 tasks until all Wave 1 tasks report completion. If a Wave 1 task fails, the orchestrator reports the failure and stops — Wave 2 is not entered.
+
+---
+
+## Mid-Session Checkpointing
+
+Any step can be paused and resumed:
+
+```bash
+/fd-checkpoint   # Save current STATE.md snapshot
+/fd-resume       # Reload latest checkpoint and continue
+```
+
+Checkpoints are written to `.planning/STATE.md`. The `/fd-resume` command reloads `STATE.md` and `PLAN.md` (if present) and reinitializes the context for the next phase step.

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 |