@dv.nghiem/flowdeck 0.4.1 → 0.4.3

package/docs/configuration/index.md

@@ -138,6 +138,32 @@ Defines per-agent allowed/forbidden tools, required inputs, and success criteria
 }
 ```
 
+### `costBudget` — Per-Workflow Cost Enforcement
+
+Limits estimated USD spend and token consumption per workflow run. When a limit is reached, FlowDeck can warn, stop, or escalate depending on `onExhaustion`.
+
+```json
+{
+  "governance": {
+    "costBudget": {
+      "maxEstimatedCostUSD": 1.0,
+      "maxInputTokens": 500000,
+      "maxOutputTokens": 100000,
+      "onExhaustion": "warn"
+    }
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `maxEstimatedCostUSD` | number | (none) | Maximum estimated USD cost per workflow run |
+| `maxInputTokens` | number | (none) | Maximum input tokens per workflow run |
+| `maxOutputTokens` | number | (none) | Maximum output tokens per workflow run |
+| `onExhaustion` | `"warn"` \| `"stop"` \| `"escalate"` | `"warn"` | Action taken when a limit is reached |
+
+Budget state is persisted to `.codebase/COST_BUDGETS.json`.
+
 ---
 
 ## `model_profile` — Context Window Balance

package/docs/getting-started/installation.md

@@ -44,6 +44,26 @@ which flowdeck
 
 After installation, FlowDeck registers as an OpenCode plugin. Restart OpenCode to load the plugin and its commands.
 
+## Optional: rtk Output Compression
+
+[rtk](https://github.com/rtk-ai/rtk) is a CLI proxy that compresses noisy terminal output (git, npm, test runners, linters) by 60–90% before it reaches the model context. It is optional but recommended for token savings on command-heavy workflows.
+
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+```
+
+FlowDeck detects rtk automatically. No configuration needed. Once installed:
+
+- `RTK_INSTALLED=true` and `RTK_BIN=<path>` are injected into every bash session
+- `RTK_TELEMETRY_DISABLED=1` is always set (FlowDeck disables rtk telemetry by default)
+- Agents can use `$RTK_BIN git status`, `$RTK_BIN npm test`, etc. for compressed output
+- Call `rtk-setup` (action: `"init"`) once to install the bash auto-rewrite hook
+
+See [rtk Integration reference](../reference/rtk.md) for full setup, supported commands, and telemetry details.
+
+---
+
 ## Environment Variables
 
 FlowDeck respects the following environment variables:

package/docs/reference/hooks.md

@@ -98,10 +98,25 @@ Injects the following environment variables into every bash tool execution:
 | `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 |
+| `RTK_INSTALLED` | Live `rtk --version` check | `"true"` if the rtk binary is found, `"false"` otherwise |
+| `RTK_BIN` | rtk binary path | Full path to the rtk binary (only set when `RTK_INSTALLED=true`) |
+| `RTK_TELEMETRY_DISABLED` | Set when rtk is installed | Always `"1"` when rtk is detected — blocks rtk telemetry regardless of consent state |
 
 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`
+**rtk detection:** The binary is checked once at hook creation time (startup cost only) and cached for the session lifetime. Checks `PATH` first, then `~/.local/bin/rtk` and `/usr/local/bin/rtk`.
+
+**Using rtk in bash commands:** When `RTK_INSTALLED=true`, agents can compress noisy CLI output by prefixing commands with `$RTK_BIN`:
+
+```bash
+$RTK_BIN git status      # compressed git status output
+$RTK_BIN npm test        # compressed test runner output
+$RTK_BIN tsc --noEmit    # compressed TypeScript compiler output
+```
+
+See [rtk Integration](rtk.md) for the full list of supported commands and setup instructions.
+
+**State read:** `package.json`, lockfiles, marker files, `.planning/STATE.md`, `rtk` binary (PATH check)
 
 ---
 

package/docs/reference/rtk.md

@@ -0,0 +1,162 @@
+# rtk Integration
+
+FlowDeck integrates [rtk](https://github.com/rtk-ai/rtk) — a Rust CLI proxy that compresses noisy terminal output (git, npm, test runners, linters, Docker, and more) by 60–90% before it reaches the model context.
+
+---
+
+## What rtk does
+
+rtk acts as a transparent proxy in front of supported CLI commands:
+
+```bash
+rtk git status     # same as git status, but output compressed 60-90%
+rtk npm test       # same as npm test, but noise filtered out
+rtk tsc --noEmit   # TypeScript compiler errors, signal-only
+```
+
+This reduces the number of tokens consumed by verbose CLI output — lowering cost and improving signal quality for agents that read shell output.
+
+---
+
+## Detection
+
+FlowDeck detects rtk automatically at session startup. No configuration is required.
+
+Detection checks in order:
+1. `rtk --version` via `PATH`
+2. `~/.local/bin/rtk` (default install location on Linux/macOS)
+3. `/usr/local/bin/rtk`
+
+Detection is performed once per session and cached (zero overhead per bash call).
+
+---
+
+## Environment Variables Injected
+
+When rtk is detected, FlowDeck injects the following into **every bash tool execution** via the `shell.env` hook:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `RTK_INSTALLED` | `"true"` / `"false"` | Whether rtk was found at session start |
+| `RTK_BIN` | e.g. `/home/user/.local/bin/rtk` | Full path to the rtk binary (only when installed) |
+| `RTK_TELEMETRY_DISABLED` | `"1"` | Always set when rtk is installed — blocks telemetry |
+
+Agents can use these vars directly in bash commands:
+
+```bash
+if [ "$RTK_INSTALLED" = "true" ]; then
+  $RTK_BIN git log --oneline -20
+else
+  git log --oneline -20
+fi
+```
+
+---
+
+## Telemetry
+
+FlowDeck **always disables rtk telemetry**. Two layers of protection:
+
+1. **`rtk telemetry disable`** — run automatically after every `rtk-setup init`. Stores an explicit opt-out in rtk's local config (`~/.local/share/rtk/`).
+2. **`RTK_TELEMETRY_DISABLED=1`** — injected into every bash session by FlowDeck's `shell.env` hook. Blocks telemetry at the env-var level regardless of stored consent state.
+
+Both mechanisms are active independently. The env var alone is sufficient to suppress all telemetry pings even if the config opt-out is somehow lost.
+
+See [rtk TELEMETRY.md](https://github.com/rtk-ai/rtk/blob/develop/docs/TELEMETRY.md) for what rtk would collect if telemetry were enabled.
+
+---
+
+## Supported Commands
+
+The following commands benefit from rtk compression. FlowDeck's wrapping policy (`rtk-policy.ts`) uses this list:
+
+| Command | What gets compressed |
+|---------|----------------------|
+| `git status` | Staged / unstaged file listing |
+| `git log` | Commit history |
+| `git diff` | Full diff output |
+| `git show` | Commit show output |
+| `npm test` / `bun test` | Test runner output and summaries |
+| `tsc` | TypeScript compiler diagnostics |
+| `eslint` / `biome` / `oxlint` | Lint output |
+| `jest` / `vitest` / `pytest` | Test output |
+| `cargo` | Rust build / test output |
+| `docker` | Container and image listings |
+| `kubectl` | Kubernetes resource listings |
+| `gh` | GitHub CLI output |
+| `pnpm` / `yarn` / `npx` | Package manager output |
+
+**Commands that are never wrapped** (raw output required or already compact):
+
+| Command | Reason |
+|---------|--------|
+| `git rev-parse` | Returns a single hash — already minimal |
+| `git diff --name-only` / `--name-status` / `--stat` | Already compact listing |
+| `git ls-files`, `git config`, `git symbolic-ref` | Compact structured output |
+| `codegraph` | Programmatic structured output — must not be modified |
+| `curl` | Used for downloads — raw output required |
+| `sh`, `bash`, `node`, `python` | Shell interpreters — must not be intercepted |
+
+---
+
+## Setup Tool
+
+Agents can check rtk status or trigger initialization via the `rtk-setup` tool:
+
+### Check status
+
+```
+rtk-setup (action: "status")
+```
+
+Returns current detection result, binary path, version, and instructions if rtk is not installed.
+
+### Initialize bash hook
+
+```
+rtk-setup (action: "init")
+```
+
+Runs `rtk init -g` to install the bash rewriting hook, then immediately runs `rtk telemetry disable`. Reports both outcomes.
+
+**Bash hook caveat:** `rtk init -g` writes to Claude Code / Copilot global config. Whether the hook fires automatically in OpenCode's non-interactive bash sessions depends on the runtime. Using `$RTK_BIN <cmd>` explicitly is always reliable.
+
+---
+
+## Installing rtk
+
+FlowDeck does **not** auto-install rtk. Auto-executing a remote shell script is a supply-chain risk. Install manually:
+
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+```
+
+After installation, add `~/.local/bin` to your PATH if not already present, then verify:
+
+```bash
+rtk --version
+```
+
+FlowDeck will detect the binary automatically on the next session start.
+
+---
+
+## No rtk? No problem.
+
+rtk is entirely optional. If rtk is not installed:
+- `RTK_INSTALLED=false` is injected (no `RTK_BIN` or `RTK_TELEMETRY_DISABLED`)
+- All commands run as normal — no change to behavior
+- The `rtk-setup` tool returns install instructions instead of status
+- All FlowDeck workflows remain fully functional
+
+---
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `src/services/rtk-manager.ts` | Detection (`detectRtk`), init (`initRtk`), status (`getRtkStatus`), wrapping (`wrapCommandArgs`) |
+| `src/services/rtk-policy.ts` | Command wrapping policy — supported list, compact-git exclusions, `shouldWrapWithRtk()` |
+| `src/tools/rtk-setup.ts` | Agent-callable `rtk-setup` tool |
+| `src/hooks/shell-env-hook.ts` | Injects `RTK_INSTALLED`, `RTK_BIN`, `RTK_TELEMETRY_DISABLED` into bash sessions |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",

package/src/rules/common/agent-orchestration.md

@@ -1,3 +1,10 @@
+---
+description: FlowDeck agent registry and orchestration rules — which agent to delegate to and when
+always_on: true
+stages: []
+languages: []
+---
+
 # Agent Orchestration
 
 FlowDeck provides 23 specialist agents. Each has a specific role. Using the right agent gets better results faster.

package/src/rules/common/behavioral.md

@@ -1,3 +1,10 @@
+---
+description: Core behavioral guidelines for all LLM agents — think before coding, simplicity, surgical changes, goal-driven execution
+always_on: true
+stages: []
+languages: []
+---
+
 Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
 
 **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

package/src/rules/common/coding-style.md

@@ -1,3 +1,10 @@
+---
+description: Language-agnostic coding conventions — naming, simplicity, immutability, resource cleanup
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: []
+---
+
 # Coding Style
 
 Language-agnostic coding conventions followed by all FlowDeck agents.

package/src/rules/common/git-workflow.md

@@ -1,3 +1,10 @@
+---
+description: Conventional commit format, PR workflow, clean git history standards
+always_on: false
+stages: [execute, verify]
+languages: []
+---
+
 # Git Workflow
 
 Conventional commits, clean history, and structured PR workflow.

package/src/rules/common/security.md

@@ -1,3 +1,10 @@
+---
+description: Security checklist for code changes — no hardcoded secrets, parameterized queries, input validation, auth middleware
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: []
+---
+
 # Security Standards
 
 Security requirements that apply to all code. These are checked before every merge and deployment.

package/src/rules/common/testing.md

@@ -1,3 +1,10 @@
+---
+description: TDD and testing standards — 80% coverage, Red-Green-Refactor, regression tests required
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: []
+---
+
 # Testing Standards
 
 All code must meet these testing standards before being considered done.

package/src/rules/golang/patterns.md

@@ -1,3 +1,10 @@
+---
+description: Go conventions — error handling, goroutines, interfaces, testing with t.Run
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: [go]
+---
+
 # Go Patterns
 
 Go conventions for FlowDeck projects.

package/src/rules/java/patterns.md

@@ -1,3 +1,10 @@
+---
+description: Java conventions — Java 17+ features, Spring Boot patterns, checked exceptions, testing with JUnit 5
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: [java]
+---
+
 # Java Patterns
 
 Java conventions for FlowDeck projects. Targets Java 17+.

package/src/rules/python/patterns.md

@@ -1,3 +1,10 @@
+---
+description: Python conventions — type hints, virtual environments, testing with pytest, PEP 8
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: [python]
+---
+
 # Python Patterns
 
 Python conventions for FlowDeck projects.

package/src/rules/rust/patterns.md

@@ -1,3 +1,10 @@
+---
+description: Rust conventions — ownership, error handling with Result/Option, unsafe boundaries, testing
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: [rust]
+---
+
 # Rust Patterns
 
 Rust conventions for FlowDeck projects.

package/src/rules/typescript/patterns.md

@@ -1,3 +1,10 @@
+---
+description: TypeScript-specific conventions — strict mode, type safety, async patterns, error handling
+always_on: false
+stages: [execute, fix-bug, verify]
+languages: [typescript]
+---
+
 # TypeScript Patterns
 
 TypeScript-specific conventions and patterns for FlowDeck projects.