patchwork-os 0.2.0-alpha.0

package/templates/bridge-tools.md

@@ -0,0 +1,111 @@
+<!-- bridge-tools v{{VERSION}} -->
+
+## Bridge Tool Overrides (claude-ide-bridge)
+
+> **These rules are active when the `claude-ide-bridge` MCP server is connected** (green in `/mcp`).  
+> If the bridge is not running, fall back to standard shell equivalents.
+
+### MANDATORY: Bridge MCP tools replace shell commands AND native Claude Code tools
+
+Do NOT use native Claude Code tools or shell commands for workspace operations. Call the MCP tool instead.
+
+#### File I/O — native Claude Code tools replaced by bridge
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `Read` tool on workspace files | `getBufferContent` |
+| `Edit` tool on workspace files | `editText` (line range) or `searchAndReplace` (pattern) |
+| `Write` tool on workspace files | `editText` or `createFile` for new files |
+| `Glob` tool to find files | `findFiles` |
+| `Bash` for build/shell commands | `runInTerminal` |
+
+> **Exceptions:** `Read`/`Edit`/`Write` on files **outside** the workspace (`~/.claude/`, system paths, etc.) have no bridge equivalent — native tools are correct there.
+
+#### Diagnostics & linting
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `tsc --noEmit`, `npm run typecheck` | `getDiagnostics` |
+| `eslint .`, `biome check`, `npm run lint` | `getDiagnostics` |
+| Assuming edits are error-free after saving | `getDiagnostics` after every file edit |
+
+#### Git
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `git status` | `getGitStatus` |
+| `git diff` | `getGitDiff` |
+| `git log` | `getGitLog` |
+| `git add <file>` | `gitAdd` |
+| `git commit -m "..."` | `gitCommit` |
+| `git push` | `gitPush` |
+| `gh pr create` | `githubCreatePR` |
+
+#### Code search & navigation
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `grep -r`, `rg` | `searchWorkspace` |
+| `cat <file>` to read content | `getBufferContent` |
+| Jump to where a symbol is defined | `goToDefinition` |
+| Find all uses of a symbol | `findReferences` |
+| Understand call chains | `getCallHierarchy` |
+| Find a class or function by name | `searchWorkspaceSymbols`, `getDocumentSymbols` |
+| Calling `getHover` in a loop for N symbols | `batchGetHover` (up to 10 in one call) |
+| Calling `goToDefinition` in a loop for N symbols | `batchGoToDefinition` (up to 10 in one call) |
+| Find links / referenced files in a document | `getDocumentLinks` |
+| Understand what a file imports (signatures) | `getImportedSignatures` |
+| Function signature + parameter info at call site | `signatureHelp` |
+| Supertypes / subtypes of a class or interface | `getTypeHierarchy` |
+| Composite: hover + definition + refs + type hierarchy | `explainSymbol` |
+| Inline type annotations and parameter names | `getInlayHints` |
+
+#### Impact analysis
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| Manual `findReferences` + `getDiagnostics` per symbol | `getChangeImpact` (blast radius: diagnostics + ref counts in one call) |
+
+#### Editor annotations
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| Guessing code lens counts (test runs, references) | `getCodeLens` |
+| Guessing semantic token types/modifiers | `getSemanticTokens` |
+
+#### Refactoring
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| Guessing if a rename is safe | `refactorAnalyze` (risk level + ref count + caller count) |
+| Manually reviewing every rename site | `refactorPreview` (exact edits before committing) |
+| Manual find-and-replace rename | `renameSymbol` |
+| Manually extracting a function | `refactorExtractFunction` |
+
+#### Code quality
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `tsc --noUnusedLocals`, `ts-prune` | `detectUnusedCode` |
+| Manually reading coverage HTML | `getCodeCoverage` (parses lcov/clover, filters by min%) |
+| `npm audit`, `cargo audit` | `auditDependencies` (outdated packages) or `getSecurityAdvisories` (CVEs) |
+| `git log --follow` to find change-heavy files | `getGitHotspots` |
+| Manually writing test stubs | `generateTests` |
+| Manually writing PR description | `getPRTemplate` |
+
+#### Debugging
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `node --inspect`, `node --inspect-brk` | `setDebugBreakpoints` → `startDebugging` |
+| Adding `console.log` to inspect values | `evaluateInDebugger` inside a debug session |
+
+#### File tree
+
+| ❌ Do NOT use | ✅ Call instead |
+|---|---|
+| `ls -R`, `find . -name "*.ts"` | `getFileTree`, `findFiles` |
+
+### Session start
+
+Call `getToolCapabilities` once at the start of each session to confirm which bridge tools are available and whether the VS Code extension is connected.

package/templates/dispatch-context.md

@@ -0,0 +1,33 @@
+# Claude IDE Bridge — Dispatch Context
+
+This workspace has the Claude IDE Bridge connected via MCP. When processing terse phone instructions, use bridge tools directly instead of shell commands.
+
+## Quick command mapping
+
+| Instruction | Action |
+|---|---|
+| "status" / "how's the build" | Call `getGitStatus` + `getDiagnostics` + `runTests` |
+| "run tests" / "test" | Call `runTests`, report pass/fail counts |
+| "review" / "check my changes" | Call `getGitDiff` + `getDiagnostics` for changed files |
+| "build" / "does it compile" | Call `getProjectInfo` then `getDiagnostics` or `runCommand` |
+| "what changed" / "recent" | Call `getGitLog` with limit 10 + `getGitStatus` |
+| "errors" / "diagnostics" | Call `getDiagnostics`, summarize by severity |
+| "push" | Call `gitPush` |
+| "commit" | Call `getGitStatus` → `gitAdd` → `gitCommit` |
+
+## Response format for Dispatch
+
+When the user message is short (< 20 words), assume it's from Dispatch (phone) and:
+- Keep responses under 20 lines
+- Use code blocks for structured data
+- No markdown headers — flat text
+- One-line summaries when everything is green
+- Error details only for failures (up to 5)
+
+## Available tools
+
+124+ MCP tools across: file ops, git, GitHub, LSP, diagnostics, testing, debugging, terminals, security audits, and more. Call `getToolCapabilities` if unsure what's available.
+
+## Scripted / automated `-p` calls
+
+For non-interactive scripted invocations using `-p`, pass `--bare` (Claude Code ≥ 2.1.81) to skip hooks, LSP initialization, and plugin sync. This reduces startup overhead significantly for fast one-shot automation.

package/templates/managed-agent/code-review-agent.md

@@ -0,0 +1,50 @@
+# Code Review Agent — System Prompt
+
+You are a code review agent with access to a live developer workspace via the claude-ide-bridge MCP server. You perform thorough, actionable pull request reviews grounded in the actual codebase state — not just the diff.
+
+## Workflow
+
+When asked to review a PR or branch, execute this sequence:
+
+1. **Get changed files** — call `getGitStatus` to see which files are modified/staged.
+2. **Read the diff** — call `getGitDiff` with `staged: false` to get the full working diff, or pass a `ref` to diff against a specific branch (e.g. `main`).
+3. **Check for errors** — call `getDiagnostics` with no `uri` for a workspace-wide check. Note any errors or warnings introduced in changed files.
+4. **Gather context** — call `searchWorkspace` to find relevant usages of changed functions, types, or exports. Focus on call sites that the diff affects.
+5. **Run tests (if applicable)** — call `runTests` to confirm the test suite passes. Note failures.
+6. **Post the review** — call `githubPostPRReview` with structured feedback.
+
+## Review Output Format
+
+Structure your review as follows:
+
+```
+## Summary
+One sentence: what this change does and whether it is safe to merge.
+
+## Verdict
+APPROVE | REQUEST_CHANGES | COMMENT
+
+## Issues
+- [CRITICAL] <file>:<line> — <problem> — <fix>
+- [WARNING]  <file>:<line> — <problem> — <fix>
+- [NITPICK]  <file>:<line> — <suggestion>
+
+## Diagnostics
+<paste getDiagnostics output for changed files, or "No errors">
+
+## Test Status
+<paste runTests summary, or "Not run">
+
+## Context Notes
+<anything from searchWorkspace that affects correctness or safety>
+```
+
+## Rules
+
+- Only flag issues you can substantiate from the diff, diagnostics output, or search results. Do not speculate.
+- CRITICAL = correctness bug, security issue, data loss risk, or broken API contract.
+- WARNING = logic issue, missing error handling, or performance regression with evidence.
+- NITPICK = style, naming, or minor improvement. Never block a merge on nitpicks alone.
+- If `getDiagnostics` returns errors in files the PR did not touch, note them as pre-existing and do not flag them as PR issues.
+- If `runTests` fails, include the failure output verbatim so the author can act on it.
+- Keep the review under 60 lines. Prefer one clear sentence per issue over multi-paragraph explanations.

package/templates/managed-agent/managed-agent-mcp.json

@@ -0,0 +1,102 @@
+{
+  "_note": "MCP server config for attaching claude-ide-bridge to an Anthropic Managed Agent. Paste into platform.claude.com → Settings → MCP Servers. Replace YOUR_BRIDGE_URL and YOUR_TOKEN before use.",
+  "_docs": "Full setup guide: documents/managed-agents.md. VPS setup: deploy/README.md + docs/remote-access.md.",
+
+  "name": "claude-ide-bridge",
+  "description": "Live workspace tools: git, file search, diagnostics, tests, LSP (when VS Code extension connected).",
+
+  "transport": {
+    "_note": "Streamable HTTP transport. Bridge exposes MCP at POST /mcp with Bearer token auth.",
+    "type": "http",
+    "url": "https://YOUR_BRIDGE_URL/mcp",
+    "headers": {
+      "Authorization": "Bearer YOUR_TOKEN"
+    }
+  },
+
+  "_setup": {
+    "step1": "Start bridge on VPS: claude-ide-bridge --bind 0.0.0.0 --full --fixed-token YOUR_TOKEN --watch --workspace /path/to/project",
+    "step2": "Place nginx with TLS in front (see deploy/nginx-claude-bridge.conf.template). Managed Agents requires HTTPS.",
+    "step3": "Replace YOUR_BRIDGE_URL with your domain (e.g. bridge.example.com) and YOUR_TOKEN with the fixed token.",
+    "step4": "Verify: curl -H 'Authorization: Bearer YOUR_TOKEN' https://YOUR_BRIDGE_URL/health",
+    "recommended_flags": "--bind 0.0.0.0 --full --fixed-token <uuid> --watch --vps",
+    "token_tip": "Use --fixed-token to prevent token rotation between agent invocations. Store token in a secrets manager."
+  },
+
+  "_headless_tools": {
+    "note": "These tools work without VS Code extension connected.",
+    "git": [
+      "getGitStatus",
+      "getGitDiff",
+      "getGitLog",
+      "gitAdd",
+      "gitCommit",
+      "gitPush",
+      "gitPull",
+      "gitCheckout",
+      "gitListBranches",
+      "gitBlame"
+    ],
+    "github": [
+      "githubCreatePR",
+      "githubListPRs",
+      "githubViewPR",
+      "githubGetPRDiff",
+      "githubPostPRReview",
+      "githubCreateIssue",
+      "githubListIssues"
+    ],
+    "files": [
+      "getBufferContent",
+      "createFile",
+      "deleteFile",
+      "renameFile",
+      "findFiles",
+      "getFileTree"
+    ],
+    "search": ["searchWorkspace", "searchWorkspaceSymbols"],
+    "shell": ["runCommand", "runInTerminal", "getTerminalOutput"],
+    "tests": ["runTests"],
+    "diagnostics": ["getDiagnostics"],
+    "project": [
+      "getProjectInfo",
+      "getProjectContext",
+      "getDependencyTree",
+      "auditDependencies",
+      "getSecurityAdvisories"
+    ]
+  },
+
+  "_extension_required_tools": {
+    "note": "These tools return isError:true when VS Code extension is not connected. They work when code-server runs on the VPS with the bridge extension installed.",
+    "lsp": [
+      "getHover",
+      "getCallHierarchy",
+      "getChangeImpact",
+      "explainSymbol",
+      "getInlayHints",
+      "signatureHelp",
+      "getTypeHierarchy",
+      "getDocumentSymbols"
+    ],
+    "refactor": [
+      "refactorAnalyze",
+      "refactorPreview",
+      "renameSymbol",
+      "refactorExtractFunction"
+    ],
+    "debugger": [
+      "setDebugBreakpoints",
+      "startDebugging",
+      "evaluateInDebugger",
+      "getDebugState"
+    ],
+    "editor": [
+      "getOpenEditors",
+      "captureScreenshot",
+      "openFile",
+      "formatDocument",
+      "fixAllLintErrors"
+    ]
+  }
+}

package/templates/recipes/ambient-journal.yaml

@@ -0,0 +1,11 @@
+name: ambient-journal
+description: Append a timestamped line to your daily journal whenever a git commit lands.
+trigger:
+  type: git_hook
+  on: post-commit
+steps:
+  - tool: file.append
+    path: ~/.patchwork/journal/{{date}}.md
+    content: "- {{time}}  committed {{hash}} — {{message}}\n"
+output:
+  path: ~/.patchwork/inbox/ambient-journal.md

package/templates/recipes/daily-status.yaml

@@ -0,0 +1,21 @@
+name: daily-status
+description: Every morning at 08:00, summarize yesterday's commits + today's calendar hints from local files.
+trigger:
+  type: cron
+  at: "0 8 * * *"
+steps:
+  - tool: git.log_since
+    since: "24h"
+    into: commits
+  - tool: file.read
+    path: ~/.patchwork/planned.md
+    into: plan
+    optional: true
+  - agent:
+      prompt: |
+        Write a 5-line morning brief. Yesterday's commits: {{commits}}.
+        Today's plan: {{plan}}.
+      into: brief
+  - tool: file.write
+    path: ~/.patchwork/inbox/daily-status-{{date}}.md
+    content: "{{brief}}\n"

package/templates/recipes/lint-on-save.yaml

@@ -0,0 +1,13 @@
+name: lint-on-save
+description: On every save of a .ts/.tsx file, surface new diagnostics to the inbox.
+trigger:
+  type: on_file_save
+  glob: "**/*.{ts,tsx}"
+steps:
+  - tool: diagnostics.get
+    uri: "{{file}}"
+    into: diags
+  - tool: file.append
+    path: ~/.patchwork/inbox/lint.md
+    content: "- {{time}}  {{file}} — {{diags.errors}} errors, {{diags.warnings}} warnings\n"
+    when: "{{diags.errors}} > 0 || {{diags.warnings}} > 0"

package/templates/recipes/stale-branches.yaml

@@ -0,0 +1,18 @@
+name: stale-branches
+description: Weekly sweep — list local branches with no commits in 30+ days.
+trigger:
+  type: cron
+  at: "0 9 * * MON"
+steps:
+  - tool: git.stale_branches
+    days: 30
+    into: stale
+  - tool: file.write
+    path: ~/.patchwork/inbox/stale-branches-{{date}}.md
+    content: |
+      # Stale branches ({{date}})
+
+      Branches with no activity in 30+ days:
+      {{stale}}
+
+      Review, then delete with: git branch -D <name>

package/templates/recipes/watch-failing-tests.yaml

@@ -0,0 +1,15 @@
+name: watch-failing-tests
+description: When tests fail, drop a one-paragraph explanation into the inbox.
+trigger:
+  type: on_test_run
+  filter: failure
+steps:
+  - agent:
+      prompt: |
+        Tests just failed. Runner: {{runner}}. Failed: {{failed}} / {{total}}.
+        Failures: {{failures}}.
+        Write 3 sentences: which test, likely cause, first thing to check.
+      into: summary
+  - tool: file.append
+    path: ~/.patchwork/inbox/test-failures.md
+    content: "\n## {{date}} {{time}}\n{{summary}}\n"

package/templates/scheduled-tasks/dependency-audit/SKILL.md

@@ -0,0 +1,77 @@
+## Installation
+
+Copy this template to your Claude Desktop scheduled-tasks directory:
+
+```bash
+mkdir -p ~/.claude/scheduled-tasks/dependency-audit
+cp /path/to/claude-ide-bridge/templates/scheduled-tasks/dependency-audit/SKILL.md \
+   ~/.claude/scheduled-tasks/dependency-audit/SKILL.md
+```
+
+Then restart Claude Desktop to detect the new scheduled task. Configure the schedule in Claude Desktop settings under "Scheduled Tasks".
+
+> The bridge must be running when this task fires. Start it with `claude-ide-bridge --watch` or `npm run start-all`.
+
+> **Emergency stop**: Set `CLAUDE_CODE_DISABLE_CRON=1` in your environment to immediately halt all scheduled cron jobs mid-session. Useful if a task runs amok or you need to suppress scheduled runs temporarily.
+
+---
+---
+name: dependency-audit
+description: Scan dependencies for security vulnerabilities and outdated packages. Run weekly via Claude Desktop scheduled tasks.
+---
+
+# Dependency Security Audit
+
+Scan all project dependencies for known security vulnerabilities.
+
+## Steps
+
+1. Call `getProjectInfo` to detect the project type and package manager
+2. Call `getSecurityAdvisories` to check for known CVEs in dependencies
+3. Call `auditDependencies` to run the package manager's native audit (npm audit, cargo audit, pip-audit, etc.)
+4. Call `getDependencyTree` to understand the full dependency graph for any flagged packages
+
+## Report Format
+
+```
+# Dependency Audit — <date>
+
+## Package Manager: <npm|cargo|pip|go>
+
+## Vulnerabilities Found: <N total>
+
+### Critical (N)
+<package@version — CVE-XXXX-XXXXX — description>
+  Fix: upgrade to <version> | No fix available
+
+### High (N)
+<package@version — CVE-XXXX-XXXXX — description>
+  Fix: upgrade to <version> | No fix available
+
+### Moderate (N)
+<package@version — description>
+
+## Outdated Packages
+<package — current → latest>  (only packages ≥1 major version OR ≥3 minor versions behind)
+Direct: listed in package.json. Transitive: pulled in by direct dependencies.
+
+## Recommended Actions
+1. <specific upgrade command or action>
+2. <specific upgrade command or action>
+
+## Overall: SECURE | REVIEW NEEDED | ACTION REQUIRED
+```
+
+## Grading Criteria
+
+- **SECURE** — 0 vulnerabilities + ≤2 patch-level outdated packages
+- **REVIEW NEEDED** — 1-2 moderate advisories OR ≥3 outdated packages
+- **ACTION REQUIRED** — any critical/high vulnerability
+
+## Guidelines
+
+- Focus on actionable findings — skip informational-only advisories
+- Report only packages ≥1 major version OR ≥3 minor versions behind as "outdated"
+- Direct dependencies: listed in package.json. Transitive: pulled in by direct dependencies. Flag transitive dependencies separately.
+- For each vulnerability, include the fix command if one exists (e.g., `npm install package@version`)
+- If no vulnerabilities found, report "All clear — 0 vulnerabilities across N dependencies"

package/templates/scheduled-tasks/health-check/SKILL.md

@@ -0,0 +1,73 @@
+## Installation
+
+Copy this template to your Claude Desktop scheduled-tasks directory:
+
+```bash
+mkdir -p ~/.claude/scheduled-tasks/health-check
+cp /path/to/claude-ide-bridge/templates/scheduled-tasks/health-check/SKILL.md \
+   ~/.claude/scheduled-tasks/health-check/SKILL.md
+```
+
+Then restart Claude Desktop to detect the new scheduled task. Configure the schedule in Claude Desktop settings under "Scheduled Tasks".
+
+> The bridge must be running when this task fires. Start it with `claude-ide-bridge --watch` or `npm run start-all`.
+
+> **Emergency stop**: Set `CLAUDE_CODE_DISABLE_CRON=1` in your environment to immediately halt all scheduled cron jobs mid-session. Useful if a task runs amok or you need to suppress scheduled runs temporarily.
+
+---
+---
+name: health-check
+description: Comprehensive project health — tests, diagnostics, security, and git status. Run hourly or daily via Claude Desktop scheduled tasks.
+---
+
+# Project Health Check
+
+Run a comprehensive health check covering all aspects of project quality.
+
+## Steps
+
+1. Call `getGitStatus` — branch, uncommitted changes, ahead/behind remote
+2. Call `getDiagnostics` — all errors and warnings, grouped by file
+3. Call `runTests` — full test suite with pass/fail/skip counts
+4. Call `getSecurityAdvisories` — known vulnerabilities in dependencies
+5. Call `auditDependencies` if available — package manager security audit
+
+## Report Format
+
+```
+# Health Check — <date> <time>
+
+## Git
+Branch: <name>
+Status: <clean | N uncommitted>
+Remote: <up to date | N ahead, M behind>
+
+## Diagnostics
+Errors: N | Warnings: M
+<file:line — message>  (list all errors, up to 20)
+
+## Tests
+Result: <N passed, M failed, K skipped> (Xs)
+<failing test — reason>  (list all failures)
+
+## Security
+Advisories: <N critical, M high, K moderate | None>
+<package — severity — title>  (list all)
+
+## Overall: HEALTHY | DEGRADED | FAILING
+<1-2 sentence summary>
+```
+
+## Grading Criteria
+
+- **HEALTHY**: 0 errors, all tests pass, no critical/high advisories
+- **DEGRADED**: warnings only, or moderate-severity advisories
+- **FAILING**: any errors, test failures, or critical/high advisories
+
+## Guidelines
+
+- If `getSecurityAdvisories` or `auditDependencies` are unavailable, note "Security: not checked (tools unavailable)"
+- For security advisories, report only HIGH and CRITICAL severity. Moderate/low can be logged but don't affect the grade.
+- This runs unattended — no interactive prompts, no questions
+- Keep the report structured and scannable
+- Avoid emojis in automated reports for clarity.

package/templates/scheduled-tasks/nightly-review/SKILL.md

@@ -0,0 +1,69 @@
+## Installation
+
+Copy this template to your Claude Desktop scheduled-tasks directory:
+
+```bash
+mkdir -p ~/.claude/scheduled-tasks/nightly-review
+cp /path/to/claude-ide-bridge/templates/scheduled-tasks/nightly-review/SKILL.md \
+   ~/.claude/scheduled-tasks/nightly-review/SKILL.md
+```
+
+Then restart Claude Desktop to detect the new scheduled task. Configure the schedule in Claude Desktop settings under "Scheduled Tasks".
+
+> The bridge must be running when this task fires. Start it with `claude-ide-bridge --watch` or `npm run start-all`.
+
+> **Emergency stop**: Set `CLAUDE_CODE_DISABLE_CRON=1` in your environment to immediately halt all scheduled cron jobs mid-session. Useful if a task runs amok or you need to suppress scheduled runs temporarily.
+
+---
+---
+name: nightly-review
+description: Review uncommitted changes, check diagnostics, and summarize test status. Run nightly via Claude Desktop scheduled tasks.
+---
+
+# Nightly Code Review
+
+Review the current state of the project and produce a structured report.
+
+## Steps
+
+1. Call `getGitStatus` to check branch state and uncommitted changes
+2. Call `getGitDiff` to review the actual changes
+3. Call `getDiagnostics` to check for errors and warnings across the workspace
+4. Call `runTests` to verify the test suite passes
+
+## Report Format
+
+```
+# Nightly Review — <date>
+
+## Git
+Branch: <name>
+Uncommitted: <N files changed, M insertions, K deletions>
+
+## Changes Summary
+<file-by-file summary, 1 line per file: what changed and why it looks correct or concerning>
+Example: `src/bridge.ts: Added error handling for stale connections (+12 lines)`
+
+## Diagnostics
+<N errors, M warnings — list files with errors>
+
+## Tests
+<N passed, M failed, K skipped (Xs)>
+<list any failures with test name + reason>
+
+## Assessment
+<CLEAN | NEEDS ATTENTION | BROKEN>
+<1-3 sentences summarizing the overall state and any recommended actions>
+```
+
+## Action Matrix
+
+- **CLEAN** — no action needed
+- **NEEDS ATTENTION** — leave a note for the next session
+- **BROKEN** — flag immediately
+
+## Guidelines
+
+- Be thorough but concise — this report is read the next morning
+- Flag anything that looks like it was left in a broken state (failing tests, syntax errors, merge conflicts)
+- If everything is clean, keep the report short: "All clear — N tests passing, 0 errors"