@dv.nghiem/flowdeck 0.3.9 → 0.4.0

package/docs/multi-repo.md

@@ -1,201 +0,0 @@
-# Multi-Repo & Microservices
-
-FlowDeck supports coordinating changes across multiple repositories in a microservice architecture. The `@multi-repo-coordinator` agent manages dependency graphs, determines change order, and produces per-repo CHANGE PLANs.
-
----
-
-## When to Use Multi-Repo Mode
-
-Multi-repo mode is appropriate when:
-
-- A shared API contract is changing and multiple services need to update their clients
-- A breaking change requires a coordinated rollout with a specific service order
-- A new cross-cutting capability (authentication, distributed tracing, audit logging) must be added to several services at once
-- Dependency upgrades need to be applied consistently across a service mesh
-
-Single-repo mode is sufficient for all other work. Multi-repo coordination adds overhead — only enable it when the cross-repo dependency is real.
-
----
-
-## Setup
-
-### Step 1 — Initialize the root repository
-
-If your root (orchestrating) repository is not already a FlowDeck project:
-
-```
-/fd-new-project MyPlatform
-```
-
-This creates `.planning/` and `.planning/config.json` in the root repo.
-
-### Step 2 — Register service repositories
-
-```
-/fd-multi-repo --add ../user-service upstream-api
-/fd-multi-repo --add ../order-service consumer
-/fd-multi-repo --add ../notification-service consumer
-/fd-multi-repo --add ../api-gateway edge
-```
-
-Each `--add` command:
-1. Resolves and validates the path
-2. Detects the tech stack (language, framework) from the target repo's files
-3. Appends an entry to `sub_repos` in `.planning/config.json`
-
-### Step 3 — Verify registration
-
-```
-/fd-multi-repo --list
-```
-
-Expected output:
-
-```
-Registered repositories:
-  user-service       ../user-service         role: upstream-api    tech: node+typescript
-  order-service      ../order-service        role: consumer        tech: node+typescript
-  notification-svc   ../notification-service  role: consumer        tech: python
-  api-gateway        ../api-gateway          role: edge            tech: golang
-```
-
----
-
-## config.json sub_repos Schema
-
-Registered repos are stored in `.planning/config.json` under the `sub_repos` key:
-
-```json
-{
-  "sub_repos": [
-    {
-      "name": "user-service",
-      "path": "../user-service",
-      "role": "upstream-api",
-      "tech_stack": "node+typescript",
-      "owner_team": "platform"
-    },
-    {
-      "name": "order-service",
-      "path": "../order-service",
-      "role": "consumer",
-      "tech_stack": "node+typescript",
-      "owner_team": "commerce"
-    },
-    {
-      "name": "notification-service",
-      "path": "../notification-service",
-      "role": "consumer",
-      "tech_stack": "python",
-      "owner_team": "growth"
-    },
-    {
-      "name": "api-gateway",
-      "path": "../api-gateway",
-      "role": "edge",
-      "tech_stack": "golang",
-      "owner_team": "platform"
-    }
-  ]
-}
-```
-
-All fields except `owner_team` are required. `owner_team` is optional but recommended — it enables `@multi-repo-coordinator` to surface team-level communication needs in the CHANGE PLAN.
-
----
-
-## Role Vocabulary
-
-The `role` field tells `@multi-repo-coordinator` how each service fits into the dependency graph. It uses this to determine change order and to classify changes as breaking or non-breaking.
-
-| Role | Meaning |
-|------|---------|
-| `upstream-api` | Exposes an API that other services consume. Changes here propagate outward. |
-| `consumer` | Calls one or more upstream APIs. Must update its client when upstream contracts change. |
-| `edge` | API gateway or entry point. Routes external traffic and may enforce rate limits or authentication. |
-| `shared-lib` | A library imported by other services. Breaking changes here affect every consumer simultaneously. |
-| `worker` | Background job processor. Typically a consumer of events or queues; rarely an upstream dependency. |
-| `data-store` | Database, cache, or storage service. Schema changes here can be breaking for any direct consumer. |
-
----
-
-## Running a Cross-Repo Change
-
-Invoke `@multi-repo-coordinator` with a plain-language description of the cross-cutting change:
-
-```
-@multi-repo-coordinator I need to add user preferences to the user-service API and
-update all consumer services to use the new endpoint.
-```
-
-### What `@multi-repo-coordinator` does
-
-1. **Reads `sub_repos`** from `.planning/config.json` to identify all registered services
-2. **Builds the dependency graph** — in the example above: `user-service → order-service`, `user-service → notification-service`, and `api-gateway → user-service`
-3. **Determines change order** based on roles: upstream services change first, consumers second, edge last
-4. **Classifies the change**: adding a new field or endpoint is non-breaking; renaming or removing is breaking. Breaking changes require a compatibility strategy (versioned endpoints, feature flags, or synchronized cutover)
-5. **Produces a CHANGE PLAN** for each affected repository in dependency order
-
----
-
-## CHANGE PLAN Format
-
-`@multi-repo-coordinator` produces a CHANGE PLAN that is saved to `.planning/fd-multi-repo/CHANGE-<timestamp>.md`:
-
-```
-CHANGE PLAN — user-preferences feature
-
-Order of changes:
-  1. user-service (upstream-api)   — add GET /users/{id}/preferences endpoint
-  2. order-service (consumer)      — update UserClient to call new preferences endpoint
-  3. notification-service (consumer) — update notification triggers with user preferences
-  4. api-gateway (edge)            — add /preferences route, update rate limit policy
-
-Breaking changes: None (additive endpoint — existing clients unaffected)
-Rollout strategy: canary → staging → production per service in the order above
-
-Owner teams notified:
-  platform (user-service, api-gateway)
-  commerce (order-service)
-  growth (notification-service)
-```
-
-For breaking changes, the CHANGE PLAN includes a compatibility section:
-
-```
-Breaking changes: YES — /users/{id} response shape modified (field renamed)
-Compatibility strategy:
-  - Deploy user-service@v2 alongside v1 (parallel run)
-  - Migrate consumers to v2 endpoint one-by-one
-  - Deprecate v1 after all consumers are migrated (target: 2 sprints)
-  - Remove v1 after deprecation window closes
-```
-
----
-
-## Multi-Repo Workflow
-
-The `multi-repo-flow` workflow orchestrates the full end-to-end process:
-
-1. **Analyze** — `@code-explorer` runs in each registered repo and builds a combined dependency graph
-2. **Classify** — `@multi-repo-coordinator` identifies which changes are breaking vs non-breaking and determines service change order
-3. **Plan** — produces a CHANGE PLAN per repo in dependency order
-4. **Execute** — role-routed implementation agent (`@backend-coder`/`@frontend-coder`/`@devops`) is invoked per repo in order; `@tester` runs per repo in parallel with the selected implementation agent (using that repo's test suite)
-5. **Verify** — `@reviewer` and `@security-auditor` run per repo after implementation; integration tests are run across the full service mesh in staging before any production rollout
-
-Each step produces output files in `.planning/fd-multi-repo/` so the entire process is auditable.
-
----
-
-## Multi-Repo Commands Reference
-
-| Command | What it does |
-|---------|-------------|
-| `/fd-multi-repo --add <path> <role>` | Register a repo with the given path and role |
-| `/fd-multi-repo --list` | Print a table of all registered repos |
-| `/fd-multi-repo --status` | Show `git status` summary for every registered repo |
-| `/fd-multi-repo --remove <name>` | Remove a repo from `sub_repos` by name |
-
----
-
-← [Back to Index](index.md)

package/docs/notifications.md

@@ -1,170 +0,0 @@
-# System Notifications
-
-FlowDeck fires desktop notifications when commands that require your attention complete. This is useful when you switch to another application while the AI processes a task — you will be alerted when your input is needed or when a long-running command is ready for review.
-
----
-
-## How It Works
-
-When an interactive command finishes (one that either asks questions or produces output you need to approve), FlowDeck sends a desktop notification through the OS notification system. Notification urgency depends on the command:
-
-- **Critical-level (urgent):** `/fd-discuss`, `/fd-plan`, `/fd-verify`, `/fd-deploy-check`, `/fd-new-project`  
-  These commands present questions or decisions that block further progress. The notification is sent at high urgency so it appears even in Do Not Disturb mode on some systems.
-
-- **Info-level:** `/fd-new-feature`, `/fd-fix-bug`, `/fd-write-docs`, `/fd-checkpoint`  
-  These commands complete autonomously and notify you that output is ready for review. Low urgency — appears in notification center but does not interrupt focus.
-
-Notifications are **best-effort**: if the notification system is unavailable (missing package, SSH session without display, headless CI), FlowDeck logs a warning and continues silently. No command is blocked by a notification failure.
-
----
-
-## Linux (`notify-send`)
-
-FlowDeck uses `notify-send` from the `libnotify` package. A desktop session (X11 or Wayland) must be active.
-
-### Installation
-
-```bash
-# Debian / Ubuntu
-sudo apt install libnotify-bin
-
-# Fedora / RHEL / CentOS Stream
-sudo dnf install libnotify
-
-# Arch Linux
-sudo pacman -S libnotify
-```
-
-### Verify
-
-```bash
-notify-send "FlowDeck" "Notifications working"
-```
-
-A toast notification should appear in the top-right corner of your desktop (or wherever your notification daemon places them — GNOME, KDE, and sway all position them differently).
-
----
-
-## macOS (`osascript`)
-
-`osascript` is a standard macOS tool available on every installation. No additional packages are needed.
-
-### Allow notifications from Terminal
-
-macOS requires per-application notification permission:
-
-1. Open **System Preferences** (macOS 12 and earlier) or **System Settings** (macOS 13+)
-2. Navigate to **Notifications**
-3. Find **Terminal** in the app list (or your OpenCode host application if you run it outside Terminal)
-4. Set **Allow Notifications** to on
-5. Choose **Alerts** or **Banners** depending on your preference
-
-### Verify
-
-```bash
-osascript -e 'display notification "Notifications working" with title "FlowDeck"'
-```
-
----
-
-## Windows (PowerShell toast)
-
-FlowDeck uses the `Windows.UI.Notifications` WinRT API via PowerShell. This requires Windows 10 or later and PowerShell 5 or later. No additional installation is needed.
-
-### Allow notifications from PowerShell
-
-1. Open **Settings → System → Notifications**
-2. Scroll to the app list and find **Windows PowerShell**
-3. Enable notifications for Windows PowerShell
-
-### Verify
-
-```powershell
-[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
-$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
-    [Windows.UI.Notifications.ToastTemplateType]::ToastText02)
-$template.SelectSingleNode("//text[@id='1']").InnerText = "FlowDeck"
-$template.SelectSingleNode("//text[@id='2']").InnerText = "Notifications working"
-$toast = [Windows.UI.Notifications.ToastNotification]::new($template)
-[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("FlowDeck").Show($toast)
-```
-
----
-
-## Notification Content Reference
-
-| Command | Title | Body |
-|---------|-------|------|
-| `/fd-discuss` | `FlowDeck: /fd-discuss` | Your input is needed — please check OpenCode |
-| `/fd-plan` | `FlowDeck: /fd-plan` | Your input is needed — please check OpenCode |
-| `/fd-verify` | `FlowDeck: /fd-verify` | Your input is needed — please check OpenCode |
-| `/fd-deploy-check` | `FlowDeck: /fd-deploy-check` | Your input is needed — please check OpenCode |
-| `/fd-new-project` | `FlowDeck: /fd-new-project` | Your input is needed — please check OpenCode |
-| `/fd-new-feature` | `FlowDeck: /fd-new-feature complete` | Review the output and choose your next step |
-| `/fd-fix-bug` | `FlowDeck: /fd-fix-bug complete` | Review the output and choose your next step |
-| `/fd-write-docs` | `FlowDeck: /fd-write-docs complete` | Review the output and choose your next step |
-| `/fd-checkpoint` | `FlowDeck: /fd-checkpoint` | State saved — safe to close this session |
-
----
-
-## Disabling Notifications
-
-Notifications are opt-out at the OS level. To stop receiving them:
-
-- **Linux:** Uninstall `libnotify-bin` (`sudo apt remove libnotify-bin`) or close your notification daemon
-- **macOS:** System Settings → Notifications → find Terminal → set Allow Notifications to off
-- **Windows:** Settings → System → Notifications → Windows PowerShell → toggle off
-
-Alternatively, when FlowDeck runs in a non-interactive environment (CI pipeline, headless server, SSH session without `$DISPLAY`) it detects the absence of a notification system and skips notification dispatch automatically. No configuration is needed for headless use.
-
----
-
-## Troubleshooting
-
-### Linux: notifications not appearing
-
-**`notify-send` command not found:**
-```bash
-which notify-send   # should return a path
-sudo apt install libnotify-bin
-```
-
-**`notify-send` runs but nothing appears:**
-```bash
-echo $DISPLAY   # must not be empty; e.g. :0 or :1
-```
-
-If `$DISPLAY` is empty, you are in a session that is not connected to a display server. Set it explicitly if you are connected to a local machine via SSH:
-```bash
-export DISPLAY=:0
-notify-send "test" "test"
-```
-
-**Running under Wayland:**
-```bash
-echo $WAYLAND_DISPLAY   # should be wayland-0 or similar
-```
-
-Some distributions require `notify-send` version 0.8+ for Wayland support. Check: `notify-send --version`.
-
----
-
-### macOS: notifications not appearing
-
-1. Run the verification command above — if it shows no notification, Terminal notifications are disabled
-2. Check System Settings → Notifications → Terminal → Allow Notifications is on
-3. Check that **Focus** or **Do Not Disturb** is not suppressing alerts
-4. On macOS 14+, check that notification permissions have not been reset after an OS update
-
----
-
-### Windows: notifications not appearing
-
-1. Verify Settings → System → Notifications → **Notifications** master toggle is on
-2. Verify **Windows PowerShell** is enabled in the app-level list
-3. Check that **Focus Assist** is not set to **Alarms only** during your work hours
-4. If running OpenCode as an administrator, PowerShell inherits elevated privileges; some Windows configurations suppress toasts from elevated processes
-
----
-
-← [Back to Index](index.md)

package/docs/optimization-baseline.md

@@ -1,21 +0,0 @@
-# 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/quick-start.md

@@ -1,197 +0,0 @@
-# Quick Start
-
-Get FlowDeck running on a project in 15 minutes.
-
----
-
-## Step 0: Verify the Installation
-
-Before opening OpenCode, confirm the install completed successfully:
-
-```bash
-ls ~/.config/opencode/agent/ | grep -c "\.md"   # expect 23+
-ls ~/.config/opencode/skills/                    # expect 24 directories
-ls ~/.config/opencode/command/                   # expect 16 files
-```
-
-If any count is short, re-run the installer. See [Installation](installation.md) for details.
-
----
-
-## Step 1: Open a Project in OpenCode
-
-Navigate to your project directory and start OpenCode:
-
-```bash
-cd my-project
-opencode
-```
-
-FlowDeck activates automatically because `@dv.nghiem/flowdeck` is registered in `~/.config/opencode/opencode.json`. All agents, skills, and commands are available immediately.
-
----
-
-## Step 2: Initialize FlowDeck
-
-Run the setup command inside the OpenCode session:
-
-```
-/fd-new-project MyApp
-```
-
-This creates the `.planning/` directory at your project root with the following structure:
-
-```
-.planning/
-├── PROJECT.md       # Project context: name, goals, constraints, tech stack
-├── STATE.md         # Current execution state, tracked by all agents
-├── ROADMAP.md       # Phase definitions and features
-└── config.json      # FlowDeck project configuration
-```
-
-You will be prompted to fill in basic project details. The more context you provide in `PROJECT.md`, the better agents perform throughout the workflow.
-
----
-
-## Step 3: Map the Codebase (existing projects only)
-
-If you are adding FlowDeck to an existing project rather than starting from scratch, run:
-
-```
-/fd-map-codebase
-```
-
-`@mapper` analyzes your source tree and generates `.codebase/` documentation files:
-
-- `.codebase/STACK.md` — tech stack with detected versions and frameworks
-- `.codebase/ARCHITECTURE.md` — component structure and data flow between modules
-- `.codebase/CONVENTIONS.md` — naming patterns, code style, and project-specific idioms
-
-All subsequent agents read these files for context. Skip this step for brand-new projects.
-
----
-
-## Step 4: Define a New Feature
-
-Before discussing requirements, initialize the feature:
-
-```
-/fd-new-feature user authentication
-```
-
-`@orchestrator` creates `.planning/phases/phase-1/FEATURE.md` and updates `STATE.md`. This establishes the feature context and shows you the next steps in the workflow:
-1. /fd-discuss
-2. /fd-plan
-3. /fd-execute
-4. /fd-verify
-
----
-
-## Step 5: Start a Discussion
-
-Requirements gathering comes next. Run:
-
-```
-/fd-discuss
-```
-
-`@discusser` asks structured questions about your goals, constraints, and success criteria — one question at a time. Each answer is numbered and tracked as a decision (`D-01`, `D-02`, …).
-
-When you finish answering, the decisions are saved to `.planning/phases/phase-1/DISCUSS.md`.
-
-**Tips:**
-- Answer specifically. `@discusser` follows up on vague responses.
-- Explicit "out of scope" decisions are as useful as "in scope" ones — they prevent scope creep later.
-- The session ends with: `"Requirements gathering complete. N decisions recorded."`
-
----
-
-## Step 6: Create an Implementation Plan
-
-With requirements captured, generate the plan:
-
-```
-/fd-plan
-```
-
-`@planner` reads `DISCUSS.md` and produces a wave-structured `PLAN.md` in `.planning/phases/phase-1/`. Then `@plan-checker` reviews it for quality — checking that task sizes are reasonable, success criteria are specific, and wave dependencies are correct.
-
-You are shown the plan and prompted for confirmation. **Type `CONFIRM` to allow execution to proceed.** Review carefully before confirming:
-
-- Are success criteria observable and specific?
-- Are individual tasks sized to 1–3 hours?
-- Do wave dependencies reflect the actual build order?
-
----
-
-## Step 7: Execute the Feature
-
-Once the plan is confirmed, start implementation:
-
-```
-/fd-execute
-```
-
-`@orchestrator` reads `STATE.md` and `PLAN.md`, then delegates work to specialist agents in wave order via a TDD cycle (RED → GREEN → REFACTOR):
-
-1. **Behavior** — Define acceptance cases from PLAN.md
-2. **RED** — Write failing tests covering each behavior
-3. **GREEN** — Implement minimum code to pass tests
-4. **REFACTOR** — Clean up code while tests remain green
-5. **Review** — `@reviewer` checks code quality and TDD discipline
-
-You see progress updates as each task completes. Independent tasks within a wave run simultaneously.
-
----
-
-## Step 8: Verify Feature Completion
-
-After implementation, run the full verification pipeline:
-
-```
-/fd-verify
-```
-
-This runs four checks in parallel:
-- **Tests** — Full test suite must pass
-- **Code Review** — `@reviewer` checks quality, security, conventions
-- **Security Scan** — `@security-auditor` checks for vulnerabilities
-- **Deploy Check** — Build verification, CVE audit, readiness assessment
-
-If all checks pass, the phase is marked **VERIFIED**. If any check fails, the report shows what needs fixing.
-
----
-
-## Step 9: Review the Results
-
-Before closing OpenCode, checkpoint your progress:
-
-```
-/fd-checkpoint
-```
-
-This writes the current execution state to `.planning/STATE.md`. To reload context in a future session:
-
-```
-/fd-resume
-```
-
-`/fd-resume` reads `STATE.md` and the active `PLAN.md` and restores full context for all agents.
-
----
-
-## Tips
-
-> **Check status at any time** — `/fd-status` prints the current state, active plan, and a summary of recent results without modifying anything.
-
-> **Context after a restart** — always run `/fd-resume` at the start of a new OpenCode session on a project that was previously active. Agents have no memory between sessions without it.
-
-> **Follow the workflow order** — the cycle `/fd-new-feature → /fd-discuss → /fd-plan → /fd-execute → /fd-verify` ensures requirements are captured before implementation and verification happens at the end.
-
-> **Skip to execute for small tasks** — for a quick bug fix, you do not need to run `/fd-discuss` and `/fd-plan`. Use `/fd-fix-bug` directly and let `@debug-specialist` handle the full cycle.
-
-> **Let `/fd-quick` drive the whole workflow** — instead of manually calling each command in sequence, run `/fd-quick <your task>` and the system classifies the task, selects the correct workflow (feature, bug fix, UI-heavy, docs), and runs all stages autonomously. It pauses only when your explicit input is needed (e.g., plan CONFIRM, approval gates). Existing commands remain fully usable standalone.
-
----
-
-← [Back to Index](index.md)