patchwork-os 0.2.0-alpha.0

package/scripts/start-remote.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Auto-restart wrapper for claude remote-control.
+# Prevents macOS idle sleep, auto-restarts on disconnect, runs in tmux.
+#
+# Usage:
+#   ./scripts/start-remote.sh [--notify <ntfy-topic>]
+#   npm run remote
+#
+# Controls:
+#   Ctrl+C        — exit cleanly (no restart)
+#   Ctrl+B, D     — detach tmux (keeps running)
+#   tmux attach -t claude-remote  — reattach
+
+set -uo pipefail
+
+SESSION_NAME="claude-remote"
+NTFY_TOPIC=""
+
+# --- Parse args ---
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --notify) NTFY_TOPIC="$2"; shift 2 ;;
+    *)        echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+# --- Dependency checks ---
+command -v tmux >/dev/null 2>&1 || {
+  echo "Error: tmux is required. Install with: brew install tmux" >&2
+  exit 1
+}
+command -v claude >/dev/null 2>&1 || {
+  echo "Error: claude CLI not found on PATH." >&2
+  exit 1
+}
+
+# --- tmux session management ---
+# If not already inside tmux, create or attach to session
+if [[ -z "${TMUX:-}" ]]; then
+  exec tmux new-session -As "$SESSION_NAME" "$0 $([ -n "$NTFY_TOPIC" ] && echo "--notify $NTFY_TOPIC")"
+fi
+
+echo "=== Remote Control auto-restart wrapper ==="
+echo "  Ctrl+C to exit cleanly"
+echo "  Ctrl+B, D to detach (keeps running)"
+echo "  tmux attach -t $SESSION_NAME to reattach"
+[[ -n "$NTFY_TOPIC" ]] && echo "  Push notifications: ntfy.sh/$NTFY_TOPIC"
+echo ""
+
+# --- Auto-restart loop with exponential backoff ---
+# Use export so the subshell can access variables without quote-splicing
+export RESTART_BASE_DELAY=5
+export RESTART_MAX_DELAY=300
+export MAX_CONSECUTIVE_FAILURES=50
+export HEALTHY_RUNTIME=60
+export NTFY_TOPIC
+
+# Detect caffeinate (macOS-only; skip on Linux)
+CAFFEINATE=""
+if command -v caffeinate >/dev/null 2>&1; then
+  CAFFEINATE="caffeinate -i"
+fi
+
+# SIGTERM handler: forward signal to child process group
+cleanup() {
+  echo ""
+  echo "Received termination signal. Shutting down..."
+  kill -- -$$ 2>/dev/null
+  exit 0
+}
+trap cleanup TERM HUP
+
+$CAFFEINATE bash -c '
+  delay=$RESTART_BASE_DELAY
+  consecutive_failures=0
+
+  while true; do
+    start_time=$(date +%s)
+    claude remote-control
+    exit_code=$?
+    elapsed=$(( $(date +%s) - start_time ))
+
+    # Ctrl+C (SIGINT) — exit cleanly
+    if [ $exit_code -eq 130 ]; then
+      echo ""
+      echo "Exited by user (Ctrl+C)."
+      exit 0
+    fi
+
+    # Reset backoff if the process ran for a healthy duration
+    if [ "$elapsed" -ge "$HEALTHY_RUNTIME" ]; then
+      consecutive_failures=0
+      delay=$RESTART_BASE_DELAY
+    else
+      consecutive_failures=$((consecutive_failures + 1))
+      delay=$(( RESTART_BASE_DELAY * (2 ** (consecutive_failures > 6 ? 6 : consecutive_failures - 1)) ))
+      [ "$delay" -gt "$RESTART_MAX_DELAY" ] && delay=$RESTART_MAX_DELAY
+    fi
+
+    # Circuit breaker: stop after too many rapid failures
+    if [ "$consecutive_failures" -ge "$MAX_CONSECUTIVE_FAILURES" ]; then
+      echo ""
+      echo "Too many consecutive failures ($MAX_CONSECUTIVE_FAILURES). Giving up."
+      echo "Check that \"claude remote-control\" works on its own, then retry."
+      if [ -n "$NTFY_TOPIC" ]; then
+        curl -s --max-time 10 --connect-timeout 5 \
+          -H "Title: Claude Remote" -H "Priority: high" \
+          -d "Circuit breaker: too many failures ($MAX_CONSECUTIVE_FAILURES). Giving up." \
+          "https://ntfy.sh/$NTFY_TOPIC" >/dev/null 2>&1 &
+      fi
+      exit 1
+    fi
+
+    echo ""
+    echo "[$(date "+%H:%M:%S")] Remote control disconnected (exit $exit_code). Restarting in ${delay}s..."
+
+    # Send ntfy notification on disconnect
+    if [ -n "$NTFY_TOPIC" ]; then
+      curl -s --max-time 10 --connect-timeout 5 \
+        -H "Title: Claude Remote" -d "Disconnected (exit $exit_code). Restarting in ${delay}s..." \
+        "https://ntfy.sh/$NTFY_TOPIC" >/dev/null 2>&1 &
+    fi
+
+    sleep "$delay"
+  done
+'

package/scripts/start-vps.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# VPS startup script for claude-ide-bridge.
+# Starts the bridge on a fixed port inside tmux, with optional ngrok tunnel.
+#
+# Personal config lives in .env.vps (gitignored) — copy from .env.vps.example:
+#   cp .env.vps.example .env.vps && edit .env.vps
+#
+# Usage:
+#   bash scripts/start-vps.sh [--ngrok] [--stop]
+#   npm run vps
+#
+# Controls:
+#   tmux attach -t bridge   -- view bridge logs
+#   tmux attach -t ngrok    -- view ngrok status
+#   Ctrl+B, D               -- detach (keeps running)
+#   bash scripts/start-vps.sh --stop  -- kill all sessions
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# -- Load personal config (.env.vps) ------------------------------------------
+ENV_FILE="$REPO_ROOT/.env.vps"
+if [[ -f "$ENV_FILE" ]]; then
+  # shellcheck source=/dev/null
+  source "$ENV_FILE"
+else
+  echo "Error: $ENV_FILE not found." >&2
+  echo "  Copy the example: cp .env.vps.example .env.vps" >&2
+  echo "  Then fill in your PORT, WORKSPACE, and FIXED_TOKEN." >&2
+  exit 1
+fi
+
+# -- Defaults (can be overridden in .env.vps) ----------------------------------
+PORT="${PORT:-9000}"
+WORKSPACE="${WORKSPACE:-$REPO_ROOT}"
+FIXED_TOKEN="${FIXED_TOKEN:-}"
+START_NGROK=false
+STOP=false
+BRIDGE_SESSION="${BRIDGE_SESSION:-bridge}"
+NGROK_SESSION="${NGROK_SESSION:-ngrok}"
+
+if [[ -z "$FIXED_TOKEN" ]]; then
+  echo "Error: FIXED_TOKEN is not set in $ENV_FILE" >&2
+  exit 1
+fi
+# -- Parse args ----------------------------------------------------------------
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --ngrok)   START_NGROK=true; shift ;;
+    --stop)    STOP=true; shift ;;
+    *)         echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+# ── Stop mode ─────────────────────────────────────────────────────────────────
+if [[ "$STOP" == true ]]; then
+  echo "Stopping bridge and ngrok sessions..."
+  tmux kill-session -t "$BRIDGE_SESSION" 2>/dev/null && echo "  v bridge stopped" || echo "  - bridge not running"
+  tmux kill-session -t "$NGROK_SESSION"  2>/dev/null && echo "  v ngrok stopped"  || echo "  - ngrok not running"
+  exit 0
+fi
+
+# ── Dependency checks ─────────────────────────────────────────────────────────
+command -v tmux >/dev/null 2>&1 || { echo "Error: tmux not found. Run: apt install tmux" >&2; exit 1; }
+command -v node >/dev/null 2>&1 || { echo "Error: node not found." >&2; exit 1; }
+
+DIST="$WORKSPACE/dist/index.js"
+if [[ ! -f "$DIST" ]]; then
+  echo "Error: $DIST not found. Run: npm run build" >&2
+  exit 1
+fi
+
+# ── Kill stale bridge session ─────────────────────────────────────────────────
+tmux kill-session -t "$BRIDGE_SESSION" 2>/dev/null || true
+
+# ── Bridge session (auto-restart loop) ───────────────────────────────────────
+BRIDGE_CMD="node $DIST --port $PORT --workspace $WORKSPACE --fixed-token $FIXED_TOKEN --vps"
+
+tmux new-session -d -s "$BRIDGE_SESSION" -x 220 -y 50 bash
+sleep 0.3
+
+tmux send-keys -t "$BRIDGE_SESSION" "while true; do
+  echo \"[\$(date '+%H:%M:%S')] Starting bridge on port $PORT...\"
+  $BRIDGE_CMD
+  EXIT=\$?
+  if [ \$EXIT -eq 130 ]; then echo 'Stopped by user (Ctrl+C).'; break; fi
+  echo \"[\$(date '+%H:%M:%S')] Bridge exited (code \$EXIT). Restarting in 5s...\"
+  sleep 5
+done" Enter
+
+echo "v Bridge started  →  tmux attach -t $BRIDGE_SESSION"
+
+# ── Optional ngrok session ────────────────────────────────────────────────────
+if [[ "$START_NGROK" == true ]]; then
+  if ! command -v ngrok >/dev/null 2>&1; then
+    echo "Warning: ngrok not found — skipping tunnel." >&2
+  else
+    tmux kill-session -t "$NGROK_SESSION" 2>/dev/null || true
+    tmux new-session -d -s "$NGROK_SESSION" -x 220 -y 50 \
+      "ngrok http $PORT --log stdout"
+    echo "v Ngrok started   →  tmux attach -t $NGROK_SESSION"
+  fi
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+echo ""
+echo "  Port:      $PORT"
+echo "  Token:     $FIXED_TOKEN"
+echo "  Workspace: $WORKSPACE"
+echo ""
+echo "Useful commands:"
+echo "  tmux attach -t $BRIDGE_SESSION          # view bridge logs"
+[[ "$START_NGROK" == true ]] && echo "  tmux attach -t $NGROK_SESSION           # view ngrok"
+echo "  bash scripts/start-vps.sh --stop    # stop everything"
+echo ""

package/templates/CLAUDE.bridge.md

@@ -0,0 +1,125 @@
+## Claude IDE Bridge
+
+@import .claude/rules/bridge-tools.md
+> **BRIDGE TOOL ENFORCEMENT — mandatory when bridge is connected**
+> Do NOT use native Claude Code tools or shell commands for workspace operations:
+> - File reading: `getBufferContent` (not `Read` tool)
+> - File editing: `editText` or `searchAndReplace` (not `Edit`/`Write` tools)
+> - File search: `searchWorkspace` / `findFiles` (not `Grep`/`Glob` tools)
+> - Testing: `runTests` (not `npm test` / `npx vitest`)
+> - Diagnostics: `getDiagnostics` (not `tsc --noEmit` / `npm run lint`)
+> - Git: `gitCommit`, `gitAdd`, `gitPush` (not `git commit` etc.)
+> - Shell commands: `runInTerminal` (not `Bash` tool)
+>
+> **Exceptions:** `Read`/`Edit`/`Write` on files outside the workspace (`~/.claude/`, system paths) have no bridge equivalent.
+>
+> Full substitution table: see `.claude/rules/bridge-tools.md` (loaded above via @import).
+The bridge is connected via MCP. The session-start hook reports connection status, tool count, and extension state automatically — check that summary before proceeding. If tools appear missing, call `getBridgeStatus` to diagnose.
+
+### Bug fix methodology
+
+When a bug is reported, do NOT start by trying to fix it. Instead:
+1. Write a test that reproduces the bug (the test should fail)
+2. Fix the bug and confirm the test now passes
+3. Only then consider the bug fixed
+
+### Documentation & memory
+
+Keep project documentation and Claude's memory in sync with the code:
+
+- **After architectural changes** — update `CLAUDE.md` so future sessions have accurate context. If a pattern, rule, or constraint changes, the file should reflect it.
+- **At the end of a work session** — if meaningful decisions were made (why a pattern was chosen, what was tried and rejected, what the next steps are), save a summary to memory: *"Remember that we chose X approach because Y."*
+- **Prune stale instructions** — if `CLAUDE.md` contains outdated guidance, remove or correct it. Stale instructions cause confident mistakes in future sessions.
+
+### Modular rules (optional)
+
+For large projects, move individual rules out of CLAUDE.md into scoped files under `.claude/rules/`:
+
+```
+.claude/rules/testing.md     — applies when working with test files
+.claude/rules/security.md    — applies to auth, payments, sensitive modules
+.claude/rules/typescript.md  — TypeScript-specific conventions
+```
+
+Reference them from CLAUDE.md with:
+```
+@import .claude/rules/testing.md
+```
+
+Path globs on rule files mean Claude only loads them when working on matching files — keeps context focused and token-efficient.
+
+### Workflow rules
+
+Bridge tool substitution rules are in `.claude/rules/bridge-tools.md` (loaded above). The Quick reference table below is a summary.
+
+### Quick reference
+
+| Task | Tool |
+|---|---|
+| Check errors / warnings | `getDiagnostics` |
+| Run tests | `runTests` |
+| Git status / diff | `getGitStatus`, `getGitDiff` |
+| Stage, commit, push | `gitAdd`, `gitCommit`, `gitPush` |
+| Open a pull request | `githubCreatePR` |
+| Navigate to definition | `goToDefinition` |
+| Find all references | `findReferences` |
+| Call hierarchy | `getCallHierarchy` |
+| File tree / symbols | `getFileTree`, `getDocumentSymbols` |
+| Run a shell command | `runInTerminal`, `getTerminalOutput` |
+| Interactive debug | `setDebugBreakpoints`, `startDebugging`, `evaluateInDebugger` |
+| Lint / format | `fixAllLintErrors`, `formatDocument` |
+| Security audit | `getSecurityAdvisories`, `auditDependencies` |
+| Unused code | `detectUnusedCode` |
+
+### Dispatch prompts (mobile)
+
+When a terse message arrives via Claude Desktop Dispatch (phone/Siri), Claude automatically routes it to the appropriate bridge prompt. You can also invoke these prompts directly by name in any chat.
+
+When responding to terse Dispatch messages from a phone, use these prompts for consistent, concise output:
+
+| Phone message | Prompt | Tools called |
+|---|---|---|
+| "How's the build?" | `project-status` | `getGitStatus`, `getDiagnostics`, `runTests` |
+| "Run the tests" | `quick-tests` | `runTests` |
+| "Review my changes" | `quick-review` | `getGitStatus`, `getGitDiff`, `getDiagnostics` |
+| "Does it build?" | `build-check` | `getProjectInfo`, `getDiagnostics`, `runCommand` |
+| "What changed?" | `recent-activity` | `getGitLog`, `getGitStatus` |
+
+Keep responses concise (under 20 lines) when the conversation arrives via Dispatch.
+
+### Agent Teams & Scheduled Tasks
+
+| Context | Prompt | What it does |
+|---|---|---|
+| Team lead checking on parallel agents | `team-status` | Workspace state, active tasks, recent activity across sessions |
+| Scheduled nightly/hourly health check | `health-check` | Tests + diagnostics + security advisories + git status |
+
+> Prerequisite for `team-status`: multiple Claude Code sessions must be connected simultaneously. Solo sessions will show empty team activity.
+
+> **Claude Code ≥ v2.1.77**: `SendMessage` auto-resumes stopped agents — no need to check whether a teammate is running before sending to it.
+
+Ready-made scheduled task templates (nightly-review, health-check, dependency-audit) are included with the bridge package. Copy the ones you want to `~/.claude/scheduled-tasks/` and restart Claude Desktop to activate them. Find them in the `templates/scheduled-tasks/` directory of the `claude-ide-bridge` npm package (typically `$(npm root -g)/claude-ide-bridge/templates/scheduled-tasks/`).
+
+### Cowork (computer-use)
+
+**MCP bridge tools are NOT available inside Cowork sessions.** Always run `/mcp__bridge__cowork` in a regular Claude Code or Claude Desktop chat first to gather context and write a handoff note, then open Cowork.
+
+Workflow:
+1. Regular chat: run `/mcp__bridge__cowork` → Claude collects IDE state → calls `setHandoffNote`
+2. Open Cowork (Cmd+2 on Mac) → Cowork reads the handoff note for context
+
+**If bridge tools are missing from your tool list inside Cowork:** you're in the wrong context. Exit, run the prompt in regular chat, then return.
+
+Full details: [docs/cowork-workflow.md](docs/cowork-workflow.md)
+
+**Cowork uses git worktrees:** Cowork sessions operate in an isolated git worktree (separate branch/working copy), not the main workspace root. Files written by Cowork land in the worktree. Always add "write all files to the workspace root, not a subdirectory" as the first instruction in your CLAUDE.md when using Cowork with a synced workspace. After Cowork finishes, review and merge the worktree branch back to main.
+
+### Session continuity
+
+| Scenario | Action |
+|---|---|
+| Switching CLI → Desktop | Call `setHandoffNote` before switching; bridge auto-snapshots if note is >5 min stale |
+| Session just started | Call `getHandoffNote` to pick up prior context (workspace-scoped). **Caution:** the `onInstructionsLoaded` automation hook may have auto-overwritten the note at session start — if the content looks generic or templated, treat it as stale and consult any persistent session log your project maintains (e.g. `docs/session-log.md`) for authoritative history. |
+| Bridge restarted | First connected client receives a "restored from checkpoint" notification |
+| Preparing for Cowork | Run `/mcp__bridge__cowork` in regular chat first — Cowork has no MCP access |
+| Multi-workspace | Notes are workspace-scoped; switching workspaces won't overwrite each other's notes |

package/templates/automation-policies/security-first.json

@@ -0,0 +1,46 @@
+{
+  "_comment": "security-first — monitors auth, payment, and API surface for vulnerabilities on every relevant change.",
+  "_usage": "Copy to automation-policy.json. Requires --automation --automation-policy <path> --claude-driver subprocess",
+
+  "automationSystemPrompt": "Automation bot. Drop articles/filler. Fragments OK. Abbreviate: DB/auth/config/req/res/fn. X→Y arrows. ≤5 lines. No preamble. Call tools → report results only.",
+
+  "onFileSave": {
+    "enabled": true,
+    "patterns": ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/__tests__/**"],
+    "cooldownMs": 12000,
+    "prompt": "{{file}} saved. getDiagnostics → type errors (null-deref/undefined risk). Hardcoded secrets? User input missing validation? ≤12 lines."
+  },
+
+  "onGitCommit": {
+    "enabled": true,
+    "cooldownMs": 15000,
+    "prompt": "Commit {{branch}}: {{message}}\nFiles: {{files}}\ngetDiagnostics (errors only). Each file: input validation? auth required? no secrets? Auth/payment/session files → flag for manual review. ≤15 lines."
+  },
+
+  "onGitPush": {
+    "enabled": true,
+    "cooldownMs": 15000,
+    "prompt": "Pushed {{branch}} to {{remote}}. getSecurityAdvisories + auditDependencies → high/critical CVEs only."
+  },
+
+  "onPullRequest": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "prompt": "PR #{{number}}: {{title}} ({{url}}). getDiagnostics → type errors? Auth/payment/session files touched? New API endpoints authenticated? Security readiness: 1-line verdict."
+  },
+
+  "onDiagnosticsError": {
+    "enabled": true,
+    "cooldownMs": 20000,
+    "minSeverity": "error",
+    "diagnosticTypes": ["ts"],
+    "prompt": "Type err {{file}}:\n{{diagnostics}}\nSecurity impact: null-deref/injection/auth-bypass risk? Safest fix."
+  },
+
+  "onCompaction": {
+    "enabled": true,
+    "phase": "post",
+    "cooldownMs": 5000,
+    "prompt": "Compacted. getGitStatus + getDiagnostics. Drop articles/filler. Fragments OK. Abbreviate (DB/auth/config/req/res/fn). Stay terse. Security-sensitive files modified? ≤8 lines."
+  }
+}

package/templates/automation-policies/strict-lint.json

@@ -0,0 +1,41 @@
+{
+  "_comment": "strict-lint — triggers on every save and error, enforces zero-warning policy.",
+  "_usage": "Copy to automation-policy.json. Requires --automation --automation-policy <path> --claude-driver subprocess",
+
+  "automationSystemPrompt": "Automation bot. Drop articles/filler. Fragments OK. Abbreviate: DB/auth/config/req/res/fn. X→Y arrows. ≤5 lines. No preamble. Call tools → report results only.",
+
+  "onFileSave": {
+    "enabled": true,
+    "patterns": ["**/*.{ts,tsx,js,jsx}"],
+    "condition": "!**/*.test.ts",
+    "cooldownMs": 8000,
+    "prompt": "{{file}} saved. fixAllLintErrors → getDiagnostics. Remaining errors/warnings ≤10 lines. Zero-warning policy."
+  },
+
+  "onDiagnosticsError": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "minSeverity": "warning",
+    "diagnosticTypes": ["ts", "eslint", "biome"],
+    "prompt": "Lint/type issue {{file}}:\n{{diagnostics}}\nfixAllLintErrors → manual fixes needed? ≤10 lines."
+  },
+
+  "onDiagnosticsCleared": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "prompt": "{{file}} issues cleared. getDiagnostics → confirm workspace clean."
+  },
+
+  "onGitCommit": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "prompt": "Commit {{branch}}: {{message}}\nFiles: {{files}}\ngetDiagnostics workspace-wide. Errors → block. Warnings → report. Zero-warning policy."
+  },
+
+  "onCompaction": {
+    "enabled": true,
+    "phase": "post",
+    "cooldownMs": 5000,
+    "prompt": "Compacted. getGitStatus + getDiagnostics workspace-wide. Drop articles/filler. Fragments OK. Abbreviate (DB/auth/config/req/res/fn). Stay terse. Branch, error count, warning count ≤5 lines."
+  }
+}

package/templates/automation-policies/test-driven.json

@@ -0,0 +1,54 @@
+{
+  "_comment": "test-driven — enforces test coverage and runs tests automatically on every relevant change.",
+  "_usage": "Copy to automation-policy.json. Requires --automation --automation-policy <path> --claude-driver subprocess",
+
+  "automationSystemPrompt": "Automation bot. Drop articles/filler. Fragments OK. Abbreviate: DB/auth/config/req/res/fn. X→Y arrows. ≤5 lines. No preamble. Call tools → report results only.",
+
+  "onFileSave": {
+    "enabled": true,
+    "patterns": ["src/**/*.ts", "vscode-extension/src/**/*.ts"],
+    "condition": "!**/*.test.ts",
+    "cooldownMs": 10000,
+    "prompt": "{{file}} saved. getDiagnostics → errors. runTests (filtered to file). No test file → generateTests scaffold. Report: error count, pass/fail, coverage note."
+  },
+
+  "onDiagnosticsError": {
+    "enabled": true,
+    "cooldownMs": 15000,
+    "minSeverity": "error",
+    "diagnosticTypes": ["ts"],
+    "prompt": "Type err {{file}}:\n{{diagnostics}}\nDO NOT fix yet. getCallHierarchy (incoming) → what depends on symbol. Cause + safest fix. ≤12 lines."
+  },
+
+  "onDiagnosticsCleared": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "prompt": "{{file}} error cleared. runTests → confirm fix correct, no regressions."
+  },
+
+  "onTestRun": {
+    "enabled": true,
+    "cooldownMs": 10000,
+    "onFailureOnly": true,
+    "prompt": "{{failed}}/{{total}} fail.\n{{failures}}\ngetDiagnostics (failing test files). getCallHierarchy (incoming) on first failing symbol → root cause. Minimal fix — don't change test expectations unless contract changed."
+  },
+
+  "onGitCommit": {
+    "enabled": true,
+    "cooldownMs": 12000,
+    "prompt": "Commit {{branch}}: {{message}}\nFiles: {{files}}\ngetDiagnostics (errors only). Non-test files changed → runTests → pass/fail. Flag files missing test coverage."
+  },
+
+  "onBranchCheckout": {
+    "enabled": true,
+    "cooldownMs": 8000,
+    "prompt": "→{{branch}} (from {{previousBranch}}). getDiagnostics + runTests → branch, error count, pass/fail. ≤5 lines."
+  },
+
+  "onCompaction": {
+    "enabled": true,
+    "phase": "post",
+    "cooldownMs": 5000,
+    "prompt": "Compacted. getGitStatus + getDiagnostics + getHandoffNote. Drop articles/filler. Fragments OK. Abbreviate (DB/auth/config/req/res/fn). Stay terse. ≤8 lines."
+  }
+}

package/templates/automation-policy.example.json

@@ -0,0 +1,105 @@
+{
+  "_comment": "Example automation policy with LSP-aware prompts. Copy to automation-policy.json and adjust as needed.",
+  "_usage": "Start bridge with: claude-ide-bridge --automation --automation-policy ./automation-policy.json --claude-driver subprocess",
+
+  "onFileChanged": {
+    "enabled": true,
+    "patterns": [
+      "**/*.{ts,tsx,js,jsx,py,go,rs}",
+      "!node_modules/**",
+      "!dist/**"
+    ],
+    "prompt": "File {{file}} was just edited. Call getChangeImpact on the changed symbols to compute blast radius. If risk is medium or high (referenceCount > 10 or callerCount > 5), also call findReferences to list the affected files. If the changed file exports an interface or abstract class, also call findImplementations at the first exported symbol position to check that all implementations are still reachable. Report in ≤15 lines: risk badge, reference counts, and the top 5 most-impacted files.",
+    "cooldownMs": 15000
+  },
+
+  "onFileSave": {
+    "enabled": false,
+    "patterns": ["**/*.{ts,tsx}"],
+    "prompt": "{{file}} was saved. Run getDiagnostics for this file and report any new errors or warnings. If there are type errors, call getHover at the first error position to explain the expected vs actual types.",
+    "cooldownMs": 10000
+  },
+
+  "onDiagnosticsError": {
+    "enabled": true,
+    "minSeverity": "error",
+    "patterns": ["**/*.{ts,tsx,js,jsx}"],
+    "prompt": "New diagnostic errors appeared in {{file}}:\n\n{{diagnostics}}\n\nFor each error: (1) call getHover at the error position to fetch type info, (2) if the error is a type error, call goToTypeDefinition at that position to navigate to the root type definition, (3) call explainSymbol on the failing symbol if applicable, (4) suggest the most likely fix. Keep response under 20 lines.",
+    "cooldownMs": 20000
+  },
+
+  "onDiagnosticsCleared": {
+    "enabled": true,
+    "prompt": "The error in {{file}} was just cleared. Run the tests for that file to confirm the fix.",
+    "cooldownMs": 10000
+  },
+
+  "onTaskSuccess": {
+    "enabled": false,
+    "prompt": "Task {{taskId}} completed. Review the output and check for any follow-up actions needed.",
+    "cooldownMs": 5000
+  },
+
+  "onBranchCheckout": {
+    "enabled": true,
+    "prompt": "Switched to branch {{branch}} (from {{previousBranch}}). Run getDiagnostics with no uri to baseline workspace health. If there are errors, call explainSymbol on the first one. Report: branch name, error count, warning count, and first error (if any).",
+    "cooldownMs": 30000
+  },
+
+  "onGitCommit": {
+    "enabled": true,
+    "prompt": "Committed {{hash}} on {{branch}}: {{message}}. Changed files: {{files}}. For each changed file: call getChangeImpact to check blast radius. If any export was removed or renamed, call findReferences to verify no broken callers remain. If any interface or abstract class was modified, call findImplementations at the changed symbol to verify all concrete implementations are still consistent. Report a compact post-commit health summary.",
+    "cooldownMs": 10000
+  },
+
+  "onGitPush": {
+    "enabled": false,
+    "prompt": "Pushed {{commits}} commits to {{remote}}/{{branch}}. Run getDiagnostics workspace-wide and detectUnusedCode to flag any dead exports that were pushed. Keep report under 15 lines.",
+    "cooldownMs": 5000
+  },
+
+  "_commentPromptName": "Instead of an inline prompt, you can reference any named MCP prompt using promptName + promptArgs. Event placeholders ({{file}}, {{branch}}, etc.) work inside promptArgs values too.",
+  "onFileSave_example_named": {
+    "_comment": "Example: use the explore-type prompt on every saved file (position 1:1 = first symbol)",
+    "enabled": false,
+    "promptName": "explore-type",
+    "promptArgs": {
+      "file": "{{file}}",
+      "line": "1",
+      "column": "1"
+    },
+    "patterns": ["**/*.{ts,tsx}"],
+    "cooldownMs": 30000
+  },
+
+  "onPullRequest": {
+    "enabled": true,
+    "prompt": "PR #{{number}} opened: {{title}} ({{url}}). Changed files: {{files}}. For each changed file: (1) call getChangeImpact to report blast radius, (2) call getDiagnostics to surface any new errors. Output a compact PR readiness report: risk badge per file, total error count, top 3 most-impacted downstream files.",
+    "cooldownMs": 5000
+  },
+
+  "onTestRun": {
+    "enabled": true,
+    "prompt": "Tests just ran. Results: {{results}}. For each failed test file: call getDiagnostics to check for type errors, then call getCallHierarchy (incoming) on the failing function to identify what changed upstream. If the failure involves an interface mismatch, call goToDeclaration on the symbol under test to verify the expected contract. Suggest the most likely root cause in ≤10 lines.",
+    "cooldownMs": 15000
+  },
+
+  "onCompaction": {
+    "enabled": true,
+    "phase": "post",
+    "prompt": "Context was just compacted. Re-orient: call getProjectInfo for workspace summary, getGitStatus for current changes, and getDiagnostics to check health. Report in ≤10 lines so the session can continue smoothly.",
+    "cooldownMs": 60000
+  },
+
+  "onTaskCreated": {
+    "enabled": false,
+    "prompt": "A new Claude Code task was created ({{taskId}}): {{prompt}}. Call getClaudeTaskStatus once to confirm it started. If the task prompt mentions a file, call getDiagnostics on that file to baseline current state before the task modifies anything.",
+    "cooldownMs": 5000
+  },
+
+  "onPermissionDenied": {
+    "enabled": false,
+    "prompt": "The tool '{{tool}}' was blocked (reason: {{reason}}). Call getBridgeStatus to confirm bridge health, then call getToolCapabilities to list available tools. If the tool is an IDE tool, check whether the VS Code extension is still connected.",
+    "cooldownMs": 15000
+  }
+}