diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
deleted file mode 100644
index 6f8573f..0000000
--- a/.beads/issues.jsonl
+++ /dev/null
@@ -1,31 +0,0 @@
-{"id":"opencode-0po","title":"Improve /swarm with context sync between agents","description":"Add mid-task context sharing via Agent Mail so parallel agents don't create incompatible outputs. Based on Mastra pattern: 'Share Context Between Subagents'","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-07T11:55:31.309446-08:00","updated_at":"2025-12-07T12:00:29.225461-08:00","closed_at":"2025-12-07T12:00:29.225461-08:00"}
-{"id":"opencode-1t6","title":"Tighten AGENTS.md for agent parsing","description":"Removed prose, condensed communication_style, reordered for priority","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:31:38.216408-08:00","updated_at":"2025-11-30T14:31:48.417503-08:00","closed_at":"2025-11-30T14:31:48.417503-08:00","close_reason":"Done: 205 lines, agent-optimized structure"}
-{"id":"opencode-22a","title":"Implement structured.ts - Zod-validated structured outputs","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:24.051917-08:00","updated_at":"2025-12-07T18:36:45.942475-08:00","closed_at":"2025-12-07T18:36:45.942475-08:00"}
-{"id":"opencode-3fd","title":"Document plugin usage, schemas, and best practices","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:29.475321-08:00","updated_at":"2025-12-07T18:39:11.229652-08:00","closed_at":"2025-12-07T18:39:11.229652-08:00"}
-{"id":"opencode-4t5","title":"Add Agent Mail documentation to AGENTS.md","description":"Document Agent Mail integration for multi-agent coordination, file reservations, beads thread linking","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T09:22:11.407298-08:00","updated_at":"2025-12-01T09:22:21.611111-08:00","closed_at":"2025-12-01T09:22:21.611111-08:00","close_reason":"Done: added agent_mail_context section with workflows and beads integration"}
-{"id":"opencode-4yk","title":"Add tool_preferences, thinking_triggers, subagent_triggers sections","description":"Explicit guidance on when to use which tools, when to think hard, when to spawn subagents","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:29:57.379266-08:00","updated_at":"2025-11-30T14:30:06.93477-08:00","closed_at":"2025-11-30T14:30:06.93477-08:00","close_reason":"Done: added 3 new XML-tagged sections for explicit agent behavior guidance"}
-{"id":"opencode-5fr","title":"OpenCode + Beads Integration Setup","description":"Configure opencode to properly leverage beads for issue tracking with custom agents, tools, and rules","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-11-30T13:57:07.264424-08:00","updated_at":"2025-11-30T13:58:56.262746-08:00","closed_at":"2025-11-30T13:58:56.262746-08:00","close_reason":"Epic complete - beads integration configured"}
-{"id":"opencode-5zj","title":"Restructure AGENTS.md with context engineering principles","description":"Added XML tags for structured parsing, context explanations for beads/prime knowledge/invoke, grouped prime knowledge by domain","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:27:12.553024-08:00","updated_at":"2025-11-30T14:27:22.876684-08:00","closed_at":"2025-11-30T14:27:22.876684-08:00","close_reason":"Done: XML structure, context tags, prime knowledge grouped by domain (learning, design, quality, systems)"}
-{"id":"opencode-68o","title":"Implement swarm.ts - swarm coordination primitives","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:24.735108-08:00","updated_at":"2025-12-07T18:36:47.013219-08:00","closed_at":"2025-12-07T18:36:47.013219-08:00"}
-{"id":"opencode-6hs","title":"Update AGENTS.md with beads workflow rules","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-30T13:58:10.593061-08:00","updated_at":"2025-11-30T13:58:46.053506-08:00","closed_at":"2025-11-30T13:58:46.053506-08:00","close_reason":"Implemented - agent/beads.md created, AGENTS.md updated with workflow rules","dependencies":[{"issue_id":"opencode-6hs","depends_on_id":"opencode-5fr","type":"parent-child","created_at":"2025-11-30T13:58:37.072407-08:00","created_by":"joel"}]}
-{"id":"opencode-6ku","title":"Setup plugin project structure in ~/Code/joelhooks/","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:21.370428-08:00","updated_at":"2025-12-07T18:36:39.909876-08:00","closed_at":"2025-12-07T18:36:39.909876-08:00"}
-{"id":"opencode-7gg","title":"Add nextjs-patterns.md knowledge file","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T12:26:56.127787-08:00","updated_at":"2025-12-07T12:36:47.981221-08:00","closed_at":"2025-12-07T12:36:47.981221-08:00"}
-{"id":"opencode-890","title":"Build opencode-swarm-plugin with Agent Mail coordination","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T18:09:12.113296-08:00","updated_at":"2025-12-07T18:49:56.805732-08:00","closed_at":"2025-12-07T18:49:56.805732-08:00"}
-{"id":"opencode-8af","title":"Refine AGENTS.md with better Joel context and structure","description":"Updated bio, cleaner structure, same content","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:23:44.316553-08:00","updated_at":"2025-11-30T14:23:54.510262-08:00","closed_at":"2025-11-30T14:23:54.510262-08:00","close_reason":"Done: updated Joel bio with egghead/Vercel/Skill Recordings context"}
-{"id":"opencode-8mz","title":"Write tests for critical swarm coordination paths","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:28.79182-08:00","updated_at":"2025-12-07T18:49:46.121328-08:00","closed_at":"2025-12-07T18:49:46.121328-08:00"}
-{"id":"opencode-a3t","title":"Add Agent Mail registration requirement to AGENTS.md","description":"Agents must ensure_project + register_agent before using other Agent Mail tools","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T09:32:37.162773-08:00","updated_at":"2025-12-01T09:32:47.361664-08:00","closed_at":"2025-12-01T09:32:47.361664-08:00","close_reason":"Done: added Session Start section with registration workflow"}
-{"id":"opencode-b09","title":"Add /checkpoint command for context compression","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T12:26:54.704513-08:00","updated_at":"2025-12-07T12:36:37.76904-08:00","closed_at":"2025-12-07T12:36:37.76904-08:00"}
-{"id":"opencode-b5b","title":"Create Zod schemas for evaluation, task, bead types","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:25.721311-08:00","updated_at":"2025-12-07T18:36:42.526409-08:00","closed_at":"2025-12-07T18:36:42.526409-08:00"}
-{"id":"opencode-clj","title":"Add Chrome DevTools MCP server","description":"Browser automation, performance analysis, network debugging via Chrome DevTools","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-02T11:54:57.267549-08:00","updated_at":"2025-12-02T11:55:07.470988-08:00","closed_at":"2025-12-02T11:55:07.470988-08:00","close_reason":"Done: added chrome-devtools-mcp to opencode.jsonc"}
-{"id":"opencode-fqg","title":"Create plugin project structure","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:20:00.030296-08:00","updated_at":"2025-12-07T18:36:41.703444-08:00","closed_at":"2025-12-07T18:36:41.703444-08:00"}
-{"id":"opencode-jbe","title":"Register Agent Mail MCP in opencode.jsonc","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T09:27:10.022179-08:00","updated_at":"2025-12-01T09:27:20.240999-08:00","closed_at":"2025-12-01T09:27:20.240999-08:00","close_reason":"Done: added agent-mail remote MCP server at http://127.0.0.1:8765/mcp/"}
-{"id":"opencode-kwp","title":"Implement agent-mail.ts - Agent Mail MCP wrapper","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:23.370635-08:00","updated_at":"2025-12-07T18:36:44.836105-08:00","closed_at":"2025-12-07T18:36:44.836105-08:00"}
-{"id":"opencode-l7r","title":"Add effect-patterns.md knowledge file","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T12:26:56.727954-08:00","updated_at":"2025-12-07T12:36:53.078729-08:00","closed_at":"2025-12-07T12:36:53.078729-08:00"}
-{"id":"opencode-ml3","title":"Create @beads subagent with locked-down permissions","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-30T13:57:17.936619-08:00","updated_at":"2025-11-30T13:58:46.05228-08:00","closed_at":"2025-11-30T13:58:46.05228-08:00","close_reason":"Implemented - agent/beads.md created, AGENTS.md updated with workflow rules","dependencies":[{"issue_id":"opencode-ml3","depends_on_id":"opencode-5fr","type":"parent-child","created_at":"2025-11-30T13:57:27.173238-08:00","created_by":"joel"}]}
-{"id":"opencode-r30","title":"Add error pattern injection to /iterate and /debug","description":"Track common errors in beads, inject known patterns into context. Based on Mastra pattern: 'Feed Errors Into Context' - if you notice commonly repeated error patterns, put them into your prompt","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-07T11:55:33.620101-08:00","updated_at":"2025-12-07T12:00:31.039472-08:00","closed_at":"2025-12-07T12:00:31.039472-08:00"}
-{"id":"opencode-rxb","title":"Update /swarm command to use new swarm primitives","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:26.376713-08:00","updated_at":"2025-12-07T18:38:06.916952-08:00","closed_at":"2025-12-07T18:38:06.916952-08:00"}
-{"id":"opencode-t01","title":"Add /retro command for post-mortem learning","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T12:26:55.379613-08:00","updated_at":"2025-12-07T12:36:42.872701-08:00","closed_at":"2025-12-07T12:36:42.872701-08:00"}
-{"id":"opencode-v9u","title":"Add /swarm-collect command for gathering results","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:28.02563-08:00","updated_at":"2025-12-07T18:38:46.903786-08:00","closed_at":"2025-12-07T18:38:46.903786-08:00"}
-{"id":"opencode-xxp","title":"Implement beads.ts - type-safe beads operations with Zod","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:22.517988-08:00","updated_at":"2025-12-07T18:36:43.758027-08:00","closed_at":"2025-12-07T18:36:43.758027-08:00"}
-{"id":"opencode-yjk","title":"Add continuous progress tracking rules to AGENTS.md","description":"Primary agent should update beads frequently during work, not just at session end","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:21:27.724751-08:00","updated_at":"2025-11-30T14:21:37.565347-08:00","closed_at":"2025-11-30T14:21:37.565347-08:00","close_reason":"Done: added Continuous Progress Tracking section with real-time update patterns"}
-{"id":"opencode-zqr","title":"Add /swarm-status command for monitoring active swarms","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T18:09:27.32927-08:00","updated_at":"2025-12-07T18:38:26.720889-08:00","closed_at":"2025-12-07T18:38:26.720889-08:00"}
diff --git a/.gitignore b/.gitignore
index 8858e67..678256d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,13 @@
-# Beads local files
+# Beads/Hive local files
.beads/beads.db
.beads/beads.db-shm
.beads/beads.db-wal
.beads/.gitignore
+.beads/*.startlock
+.beads/*.sock
+
+# OpenCode internal
+.opencode/
# Node
node_modules/
diff --git a/.beads/.local_version b/.hive/.local_version
similarity index 100%
rename from .beads/.local_version
rename to .hive/.local_version
diff --git a/.beads/README.md b/.hive/README.md
similarity index 100%
rename from .beads/README.md
rename to .hive/README.md
diff --git a/.beads/config.yaml b/.hive/config.yaml
similarity index 100%
rename from .beads/config.yaml
rename to .hive/config.yaml
diff --git a/.hive/issues.jsonl b/.hive/issues.jsonl
new file mode 100644
index 0000000..5b44794
--- /dev/null
+++ b/.hive/issues.jsonl
@@ -0,0 +1,69 @@
+{"id":"opencode-05u","title":"beads_close tool fails with \"expected object, received array\" validation error","description":"When calling beads_close, it throws: BeadValidationError: Invalid bead data: expected object, received array. The bd CLI returns an array but the tool expects an object. Same pattern likely affects other beads_* tools.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-07T19:12:59.841903-08:00","updated_at":"2025-12-07T19:17:51.595357-08:00","closed_at":"2025-12-07T19:17:51.595357-08:00"}
+{"id":"opencode-0po","title":"Improve /swarm with context sync between agents","description":"Add mid-task context sharing via Agent Mail so parallel agents don't create incompatible outputs. Based on Mastra pattern: 'Share Context Between Subagents'","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-07T11:55:31.309446-08:00","updated_at":"2025-12-07T12:00:29.225461-08:00","closed_at":"2025-12-07T12:00:29.225461-08:00"}
+{"id":"opencode-1t6","title":"Tighten AGENTS.md for agent parsing","description":"Removed prose, condensed communication_style, reordered for priority","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:31:38.216408-08:00","updated_at":"2025-11-30T14:31:48.417503-08:00","closed_at":"2025-11-30T14:31:48.417503-08:00"}
+{"id":"opencode-4t5","title":"Add Agent Mail documentation to AGENTS.md","description":"Document Agent Mail integration for multi-agent coordination, file reservations, beads thread linking","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T09:22:11.407298-08:00","updated_at":"2025-12-01T09:22:21.611111-08:00","closed_at":"2025-12-01T09:22:21.611111-08:00"}
+{"id":"opencode-4yk","title":"Add tool_preferences, thinking_triggers, subagent_triggers sections","description":"Explicit guidance on when to use which tools, when to think hard, when to spawn subagents","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:29:57.379266-08:00","updated_at":"2025-11-30T14:30:06.93477-08:00","closed_at":"2025-11-30T14:30:06.93477-08:00"}
+{"id":"opencode-5fr","title":"OpenCode + Beads Integration Setup","description":"Configure opencode to properly leverage beads for issue tracking with custom agents, tools, and rules","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-11-30T13:57:07.264424-08:00","updated_at":"2025-11-30T13:58:56.262746-08:00","closed_at":"2025-11-30T13:58:56.262746-08:00"}
+{"id":"opencode-5zj","title":"Restructure AGENTS.md with context engineering principles","description":"Added XML tags for structured parsing, context explanations for beads/prime knowledge/invoke, grouped prime knowledge by domain","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:27:12.553024-08:00","updated_at":"2025-11-30T14:27:22.876684-08:00","closed_at":"2025-11-30T14:27:22.876684-08:00"}
+{"id":"opencode-6d2","title":"agentmail_reserve tool throws TypeError on result.granted.map","description":"When calling agentmail_reserve, it throws: TypeError: undefined is not an object (evaluating 'result.granted.map'). The MCP response structure may have changed or the tool is not handling the response correctly.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-07T19:11:51.110191-08:00","updated_at":"2025-12-07T19:17:46.487475-08:00","closed_at":"2025-12-07T19:17:46.487475-08:00"}
+{"id":"opencode-7f1","title":"Week 2-3 OpenCode improvements","description":"Nested agent directories, mtime sorting for CASS, FileTime tracking for beads, streaming metadata API check","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-10T11:24:10.934588-08:00","updated_at":"2025-12-10T11:28:20.194953-08:00","closed_at":"2025-12-10T11:28:20.194953-08:00"}
+{"id":"opencode-8af","title":"Refine AGENTS.md with better Joel context and structure","description":"Updated bio, cleaner structure, same content","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:23:44.316553-08:00","updated_at":"2025-11-30T14:23:54.510262-08:00","closed_at":"2025-11-30T14:23:54.510262-08:00"}
+{"id":"opencode-a3t","title":"Add Agent Mail registration requirement to AGENTS.md","description":"Agents must ensure_project + register_agent before using other Agent Mail tools","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T09:32:37.162773-08:00","updated_at":"2025-12-01T09:32:47.361664-08:00","closed_at":"2025-12-01T09:32:47.361664-08:00"}
+{"id":"opencode-ac4","title":"OpenCode config improvements","description":"Add specialized agents, new commands, and knowledge files to improve the opencode config","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:05:48.348897-08:00","updated_at":"2025-12-07T19:12:38.666964-08:00","closed_at":"2025-12-07T19:12:38.666964-08:00"}
+{"id":"opencode-acg","title":"Week 1 OpenCode improvements","description":"Implement high-priority improvements from IMPROVEMENTS.md: doom loop detection, abort signals, output limits, explore agent","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-10T10:40:02.168475-08:00","updated_at":"2025-12-10T11:22:50.919684-08:00","closed_at":"2025-12-10T11:22:50.919684-08:00"}
+{"id":"opencode-clj","title":"Add Chrome DevTools MCP server","description":"Browser automation, performance analysis, network debugging via Chrome DevTools","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-02T11:54:57.267549-08:00","updated_at":"2025-12-02T11:55:07.470988-08:00","closed_at":"2025-12-02T11:55:07.470988-08:00"}
+{"id":"opencode-e83","title":"Add integration tests for swarm plugin tools","description":"Add integration tests that actually exercise the plugin tools against real bd CLI and Agent Mail server. Current bugs (opencode-6d2, opencode-05u) would have been caught with integration tests.\n\nTests needed:\n- beads_* tools: create, query, update, close, start, ready, sync against real bd CLI\n- agentmail_* tools: init, reserve, release, send, inbox against real Agent Mail server\n- Verify response parsing handles actual CLI/API output formats\n\nUse vitest with beforeAll/afterAll to set up test beads and clean up.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-07T19:13:42.799024-08:00","updated_at":"2025-12-07T19:18:47.961098-08:00","closed_at":"2025-12-07T19:18:47.961098-08:00"}
+{"id":"opencode-g8l","title":"semantic-memory: PGlite + pgvector local vector store","description":"Build a local semantic memory tool using PGlite + pgvector with Ollama embeddings. Budget Qdrant for AI agents with configurable tool descriptions.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:48:21.507373-08:00","updated_at":"2025-12-07T20:01:07.728552-08:00","closed_at":"2025-12-07T20:01:07.728552-08:00"}
+{"id":"opencode-j73","title":"Fix swarm plugin tool bugs","description":"Fix the two bugs discovered during swarm testing: agentmail_reserve TypeError and beads_close validation error","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:15:53.024393-08:00","updated_at":"2025-12-07T19:17:41.372347-08:00","closed_at":"2025-12-07T19:17:41.372347-08:00"}
+{"id":"opencode-pnt","title":"Analyze OpenCode internals for setup improvements","description":"Deep dive into sst/opencode source to understand architecture, discover undocumented features, and identify improvements for our local setup (tools, agents, commands, knowledge files)","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-10T10:31:49.269976-08:00","updated_at":"2025-12-10T10:38:24.59853-08:00","closed_at":"2025-12-10T10:38:24.59853-08:00"}
+{"id":"opencode-r30","title":"Add error pattern injection to /iterate and /debug","description":"Track common errors in beads, inject known patterns into context. Based on Mastra pattern: 'Feed Errors Into Context' - if you notice commonly repeated error patterns, put them into your prompt","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-07T11:55:33.620101-08:00","updated_at":"2025-12-07T12:00:31.039472-08:00","closed_at":"2025-12-07T12:00:31.039472-08:00"}
+{"id":"opencode-vh9","title":"Debug-Plus: Swarm-integrated debugging with prevention pipeline","description":"Turn reactive debugging into proactive codebase improvement by integrating debug workflow with swarm for complex investigations and auto-spawning preventive beads","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T09:14:58.120283-08:00","updated_at":"2025-12-08T09:23:51.388661-08:00","closed_at":"2025-12-08T09:23:51.388661-08:00"}
+{"id":"opencode-yjk","title":"Add continuous progress tracking rules to AGENTS.md","description":"Primary agent should update beads frequently during work, not just at session end","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-30T14:21:27.724751-08:00","updated_at":"2025-11-30T14:21:37.565347-08:00","closed_at":"2025-11-30T14:21:37.565347-08:00"}
+{"id":"opencode-22a","title":"Implement structured.ts - Zod-validated structured outputs","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:24.051Z","updated_at":"2025-12-28T17:14:31.504Z","closed_at":"2025-12-08T02:36:45.942Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-3fd","title":"Document plugin usage, schemas, and best practices","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:29.475Z","updated_at":"2025-12-28T17:14:31.506Z","closed_at":"2025-12-08T02:39:11.229Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-4eu","title":"test from config dir","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T20:24:27.538Z","updated_at":"2025-12-28T17:14:31.507Z","closed_at":"2025-12-10T20:29:13.893Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-68o","title":"Implement swarm.ts - swarm coordination primitives","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:24.735Z","updated_at":"2025-12-28T17:14:31.508Z","closed_at":"2025-12-08T02:36:47.013Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-6hs","title":"Update AGENTS.md with beads workflow rules","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-30T21:58:10.593Z","updated_at":"2025-12-28T17:14:31.510Z","closed_at":"2025-11-30T21:58:46.053Z","dependencies":[{"depends_on_id":"opencode-5fr","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-6ku","title":"Setup plugin project structure in ~/Code/joelhooks/","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:21.370Z","updated_at":"2025-12-28T17:14:31.511Z","closed_at":"2025-12-08T02:36:39.909Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-7f1.1","title":"Reorganize agents into nested directories","description":"Reorganized swarm agents into agent/swarm/ nested directory.\n\nCompleted:\n- Created agent/swarm/ directory\n- Moved swarm-planner.md → agent/swarm/planner.md (agent name: swarm/planner)\n- Moved swarm-worker.md → agent/swarm/worker.md (agent name: swarm/worker)\n- Updated frontmatter in both files\n- Updated all references in:\n - AGENTS.md\n - README.md\n - command/swarm.md\n - knowledge/opencode-agents.md\n - knowledge/opencode-plugins.md\n\nVerified:\n- No remaining old references (swarm-planner, swarm-worker)\n- Directory structure matches target\n- Git changes staged","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T19:24:16.050Z","updated_at":"2025-12-10T19:28:08.015Z","closed_at":"2025-12-10T19:28:08.015Z","dependencies":[{"depends_on_id":"opencode-7f1","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-7f1.2","title":"Add mtime sorting to CASS search results","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T19:24:21.162Z","updated_at":"2025-12-28T17:14:31.512Z","closed_at":"2025-12-10T19:28:08.394Z","dependencies":[{"depends_on_id":"opencode-7f1","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-7f1.3","title":"Add FileTime tracking for beads","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T19:24:26.271Z","updated_at":"2025-12-28T17:14:31.513Z","closed_at":"2025-12-10T19:28:08.884Z","dependencies":[{"depends_on_id":"opencode-7f1","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-7f1.4","title":"Check streaming metadata API and document findings","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T19:24:31.371Z","updated_at":"2025-12-28T17:14:31.514Z","closed_at":"2025-12-10T19:28:09.774Z","dependencies":[{"depends_on_id":"opencode-7f1","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-7gg","title":"Add nextjs-patterns.md knowledge file","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T20:26:56.127Z","updated_at":"2025-12-28T17:14:31.515Z","closed_at":"2025-12-07T20:36:47.981Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-890","title":"Build opencode-swarm-plugin with Agent Mail coordination","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T02:09:12.113Z","updated_at":"2025-12-28T17:14:31.516Z","closed_at":"2025-12-08T02:49:56.805Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-8mz","title":"Write tests for critical swarm coordination paths","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:28.791Z","updated_at":"2025-12-28T17:14:31.518Z","closed_at":"2025-12-08T02:49:46.121Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-ac4.1","title":"Add specialized agents (security, test-writer, docs)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T03:05:53.482Z","updated_at":"2025-12-28T17:14:31.519Z","closed_at":"2025-12-08T03:06:57.918Z","dependencies":[{"depends_on_id":"opencode-ac4","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-ac4.2","title":"Add missing commands (standup, estimate, test, migrate)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T03:05:58.605Z","updated_at":"2025-12-28T17:14:31.520Z","closed_at":"2025-12-08T03:07:56.095Z","dependencies":[{"depends_on_id":"opencode-ac4","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-ac4.3","title":"Add knowledge files (typescript-patterns, testing-patterns, git-patterns)","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T03:06:03.719Z","updated_at":"2025-12-28T17:14:31.521Z","closed_at":"2025-12-08T03:11:25.912Z","dependencies":[{"depends_on_id":"opencode-ac4","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-acg.1","title":"Add doom loop detection to swarm plugin","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:40:07.311Z","updated_at":"2025-12-28T17:14:31.522Z","closed_at":"2025-12-10T18:42:33.921Z","dependencies":[{"depends_on_id":"opencode-acg","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-acg.2","title":"Add abort signal handling to custom tools","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:40:12.448Z","updated_at":"2025-12-28T17:14:31.523Z","closed_at":"2025-12-10T18:49:33.768Z","dependencies":[{"depends_on_id":"opencode-acg","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-acg.3","title":"Add output size limits wrapper","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:40:17.613Z","updated_at":"2025-12-28T17:14:31.524Z","closed_at":"2025-12-10T18:44:45.966Z","dependencies":[{"depends_on_id":"opencode-acg","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-acg.4","title":"Create read-only explore agent","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:40:22.759Z","updated_at":"2025-12-28T17:14:31.525Z","closed_at":"2025-12-10T18:42:35.542Z","dependencies":[{"depends_on_id":"opencode-acg","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-b09","title":"Add /checkpoint command for context compression","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T20:26:54.704Z","updated_at":"2025-12-28T17:14:31.526Z","closed_at":"2025-12-07T20:36:37.769Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-b5b","title":"Create Zod schemas for evaluation, task, bead types","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:25.721Z","updated_at":"2025-12-28T17:14:31.527Z","closed_at":"2025-12-08T02:36:42.526Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-fqg","title":"Create plugin project structure","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:20:00.030Z","updated_at":"2025-12-28T17:14:31.528Z","closed_at":"2025-12-08T02:36:41.703Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-g8l.1","title":"Types and config - domain models, errors, config with env vars","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T03:48:26.620Z","updated_at":"2025-12-28T17:14:31.529Z","closed_at":"2025-12-08T03:51:55.479Z","dependencies":[{"depends_on_id":"opencode-g8l","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-g8l.2","title":"Ollama service - embedding provider with Effect-TS","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T03:48:31.729Z","updated_at":"2025-12-28T17:14:31.531Z","closed_at":"2025-12-08T03:51:56.036Z","dependencies":[{"depends_on_id":"opencode-g8l","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-g8l.3","title":"Database service - PGlite + pgvector with memories schema","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T03:48:36.857Z","updated_at":"2025-12-28T17:14:31.532Z","closed_at":"2025-12-08T03:51:56.627Z","dependencies":[{"depends_on_id":"opencode-g8l","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-g8l.4","title":"CLI and public API - store/find/list/stats commands","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T03:48:41.965Z","updated_at":"2025-12-28T17:14:31.533Z","closed_at":"2025-12-08T03:54:35.426Z","dependencies":[{"depends_on_id":"opencode-g8l","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-g8l.5","title":"OpenCode tool wrapper with configurable descriptions","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T03:48:47.076Z","updated_at":"2025-12-28T17:14:31.534Z","closed_at":"2025-12-08T03:54:36.118Z","dependencies":[{"depends_on_id":"opencode-g8l","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-j73.1","title":"Fix agentmail_reserve TypeError on result.granted.map","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T03:15:58.153Z","updated_at":"2025-12-28T17:14:31.535Z","closed_at":"2025-12-08T03:17:09.833Z","dependencies":[{"depends_on_id":"opencode-j73","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-j73.2","title":"Fix beads_close validation error (array vs object)","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T03:16:03.278Z","updated_at":"2025-12-28T17:14:31.536Z","closed_at":"2025-12-08T03:17:19.482Z","dependencies":[{"depends_on_id":"opencode-j73","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-jbe","title":"Register Agent Mail MCP in opencode.jsonc","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-01T17:27:10.022Z","updated_at":"2025-12-28T17:14:31.537Z","closed_at":"2025-12-01T17:27:20.240Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-kwp","title":"Implement agent-mail.ts - Agent Mail MCP wrapper","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:23.370Z","updated_at":"2025-12-28T17:14:31.538Z","closed_at":"2025-12-08T02:36:44.836Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-l7r","title":"Add effect-patterns.md knowledge file","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T20:26:56.727Z","updated_at":"2025-12-28T17:14:31.539Z","closed_at":"2025-12-07T20:36:53.078Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-ml3","title":"Create @beads subagent with locked-down permissions","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-30T21:57:17.936Z","updated_at":"2025-12-28T17:14:31.539Z","closed_at":"2025-11-30T21:58:46.052Z","dependencies":[{"depends_on_id":"opencode-5fr","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-pnt.1","title":"Analyze plugin system architecture","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:31:54.413Z","updated_at":"2025-12-28T17:14:31.540Z","closed_at":"2025-12-10T18:37:04.344Z","dependencies":[{"depends_on_id":"opencode-pnt","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-pnt.2","title":"Analyze agent/subagent system","description":"Analyzed sst/opencode agent system. Documented Task tool spawning, model routing, context isolation, built-in agents (general/explore/build/plan), and permission system. Compared to our swarm architecture. Written to knowledge/opencode-agents.md.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:31:59.538Z","updated_at":"2025-12-10T18:37:06.367Z","closed_at":"2025-12-10T18:37:06.367Z","dependencies":[{"depends_on_id":"opencode-pnt","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-pnt.3","title":"Analyze built-in tools implementation","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-10T18:32:04.665Z","updated_at":"2025-12-28T17:14:31.541Z","closed_at":"2025-12-10T18:37:07.979Z","dependencies":[{"depends_on_id":"opencode-pnt","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-pnt.4","title":"Analyze session and context management","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T18:32:09.805Z","updated_at":"2025-12-28T17:14:31.543Z","closed_at":"2025-12-10T18:37:09.588Z","dependencies":[{"depends_on_id":"opencode-pnt","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-pnt.5","title":"Synthesize findings into improvement recommendations","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T18:32:14.952Z","updated_at":"2025-12-28T17:14:31.544Z","closed_at":"2025-12-10T18:38:23.641Z","dependencies":[{"depends_on_id":"opencode-pnt","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-rxb","title":"Update /swarm command to use new swarm primitives","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:26.376Z","updated_at":"2025-12-28T17:14:31.545Z","closed_at":"2025-12-08T02:38:06.916Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-t01","title":"Add /retro command for post-mortem learning","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T20:26:55.379Z","updated_at":"2025-12-28T17:14:31.546Z","closed_at":"2025-12-07T20:36:42.872Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-v9u","title":"Add /swarm-collect command for gathering results","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:28.025Z","updated_at":"2025-12-28T17:14:31.547Z","closed_at":"2025-12-08T02:38:46.903Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-vh9.1","title":"Create prevention-patterns.md knowledge file","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T17:15:03.240Z","updated_at":"2025-12-28T17:14:31.548Z","closed_at":"2025-12-08T17:21:51.564Z","dependencies":[{"depends_on_id":"opencode-vh9","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-vh9.2","title":"Create debug-plus.md command","description":"Waiting for opencode-vh9.1 (prevention-patterns.md) to complete. Need to reference its structure for prevention pattern matching in debug-plus.md.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T17:15:08.349Z","updated_at":"2025-12-08T17:23:38.231Z","closed_at":"2025-12-08T17:23:38.231Z","dependencies":[{"depends_on_id":"opencode-vh9","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-vh9.3","title":"Update debug.md to reference debug-plus","description":"Waiting for opencode-vh9.2 to complete - debug-plus.md doesn't exist yet. Need to read it to write accurate references.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-08T17:15:13.456Z","updated_at":"2025-12-08T17:23:38.897Z","closed_at":"2025-12-08T17:23:38.897Z","dependencies":[{"depends_on_id":"opencode-vh9","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-vh9.4","title":"Update AGENTS.md with debug-plus workflow","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-08T17:15:18.564Z","updated_at":"2025-12-28T17:14:31.549Z","closed_at":"2025-12-08T17:23:39.645Z","dependencies":[{"depends_on_id":"opencode-vh9","type":"parent-child"}],"labels":[],"comments":[]}
+{"id":"opencode-xxp","title":"Implement beads.ts - type-safe beads operations with Zod","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:22.517Z","updated_at":"2025-12-28T17:14:31.550Z","closed_at":"2025-12-08T02:36:43.758Z","dependencies":[],"labels":[],"comments":[]}
+{"id":"opencode-zqr","title":"Add /swarm-status command for monitoring active swarms","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T02:09:27.329Z","updated_at":"2025-12-28T17:14:31.551Z","closed_at":"2025-12-08T02:38:26.720Z","dependencies":[],"labels":[],"comments":[]}
diff --git a/.beads/metadata.json b/.hive/metadata.json
similarity index 100%
rename from .beads/metadata.json
rename to .hive/metadata.json
diff --git a/AGENTS.md b/AGENTS.md
index a2455fd..3758148 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,45 +2,160 @@
Joel Hooks - co-founder of egghead.io, education at Vercel, builds badass courses via Skill Recordings (Total TypeScript, Pro Tailwind). Deep background in bootstrapping, systems thinking, and developer education. Lives in the Next.js/React ecosystem daily - RSC, server components, suspense, streaming, caching. Skip the tutorials.
+---
+
+## TDD COMMANDMENT (NON-NEGOTIABLE)
+
+```
+┌─────────────────────────────────────────┐
+│ RED → GREEN → REFACTOR │
+│ │
+│ Every feature. Every bug fix. │
+│ No exceptions for swarm work. │
+└─────────────────────────────────────────┘
+```
+
+1. **RED**: Write a failing test first. If it passes, your test is wrong.
+2. **GREEN**: Minimum code to pass. Hardcode if needed. Just make it green.
+3. **REFACTOR**: Clean up while green. Run tests after every change.
+
+**Bug fixes**: Write a test that reproduces the bug FIRST. Then fix it. The test prevents regression forever.
+
+**Legacy code**: Write characterization tests to document actual behavior before changing anything.
+
+**Full doctrine**: `@knowledge/tdd-patterns.md`
+**Dependency breaking**: `skills_use(name="testing-patterns")` — 25 techniques from Feathers
+**Source material**: `pdf-brain_search(query="Feathers seam")` or `pdf-brain_search(query="Beck TDD")`
+
+---
+
-**always use beads `bd` for planning and task management**
+**USE SWARM PLUGIN TOOLS - NOT RAW CLI/MCP**
-Reach for tools in this order:
+The `opencode-swarm-plugin` provides type-safe, context-preserving wrappers. Always prefer plugin tools over raw `bd` commands or Agent Mail MCP calls.
-1. **Read/Edit** - direct file operations over bash cat/sed
-2. **ast-grep** - structural code search over regex grep
-3. **Glob/Grep** - file discovery over find commands
-4. **Task (subagent)** - complex multi-step exploration, parallel work
-5. **Bash** - system commands, git, bd, running tests/builds
+### Tool Priority Order
-For Next.js projects, use the Next.js MCP tools when available.
+1. **Swarm Plugin Tools** - `hive_*`, `agentmail_*`, `swarm_*`, `structured_*` (ALWAYS FIRST)
+2. **Read/Edit** - direct file operations over bash cat/sed
+3. **ast-grep** - structural code search over regex grep
+4. **Glob/Grep** - file discovery over find commands
+5. **Task (subagent)** - complex multi-step exploration, parallel work
+6. **Bash** - system commands, git, running tests/builds (NOT for hive/agentmail)
### MCP Servers Available
- **next-devtools** - Next.js dev server integration, route inspection, error diagnostics
-- **agent-mail** - Multi-agent coordination, file reservations, async messaging (OPTIONAL - plugin provides same functionality)
- **chrome-devtools** - Browser automation, DOM inspection, network monitoring
- **context7** - Library documentation lookup (`use context7` in prompts)
- **fetch** - Web fetching with markdown conversion, pagination support
-### Custom Tools Available
+### Swarm Plugin Tools (PRIMARY - use these)
+
+**Hive** (work item tracking):
+| Tool | Purpose |
+|------|---------|
+| `hive_create` | Create cell with type-safe validation |
+| `hive_create_epic` | Atomic epic + subtasks creation |
+| `hive_query` | Query with filters (replaces `bd list/ready/wip`) |
+| `hive_update` | Update status/description/priority |
+| `hive_close` | Close with reason |
+| `hive_start` | Mark in-progress |
+| `hive_ready` | Get next unblocked cell |
+| `hive_sync` | Sync to git (MANDATORY at session end) |
+
+> **Migration Note:** `beads_*` aliases still work but show deprecation warnings. Update to `hive_*` tools.
+
+**Agent Mail** (multi-agent coordination):
+| Tool | Purpose |
+|------|---------|
+| `agentmail_init` | Initialize session (project + agent registration) |
+| `agentmail_send` | Send message to agents |
+| `agentmail_inbox` | Fetch inbox (CONTEXT-SAFE: limit=5, no bodies) |
+| `agentmail_read_message` | Fetch ONE message body |
+| `agentmail_summarize_thread` | Summarize thread (PREFERRED) |
+| `agentmail_reserve` | Reserve files for exclusive edit |
+| `agentmail_release` | Release reservations |
+
+**Swarm** (parallel task orchestration):
+| Tool | Purpose |
+|------|---------|
+| `swarm_select_strategy` | Analyze task, recommend strategy (file/feature/risk-based) |
+| `swarm_plan_prompt` | Generate strategy-specific decomposition prompt (queries CASS) |
+| `swarm_validate_decomposition` | Validate response, detect conflicts |
+| `swarm_spawn_subtask` | Generate prompt for worker agent with Agent Mail/hive instructions |
+| `swarm_status` | Get swarm progress by epic ID |
+| `swarm_progress` | Report subtask progress |
+| `swarm_complete` | Complete subtask (runs UBS scan, releases reservations) |
+| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
+
+**Structured Output** (JSON parsing):
+| Tool | Purpose |
+|------|---------|
+| `structured_extract_json` | Extract JSON from markdown/text |
+| `structured_validate` | Validate against schema |
+| `structured_parse_evaluation` | Parse self-evaluation |
+| `structured_parse_cell_tree` | Parse epic decomposition |
+
+**Skills** (knowledge injection):
+| Tool | Purpose |
+|------|---------|
+| `skills_list` | List available skills (global, project, bundled) |
+| `skills_use` | Load skill into context with optional task context |
+| `skills_read` | Read skill content including SKILL.md and references |
+| `skills_create` | Create new skill with SKILL.md template |
+
+**CASS** (cross-agent session search):
+| Tool | Purpose |
+|------|---------|
+| `cass_search` | Search all AI agent histories (query, agent, days, limit) |
+| `cass_view` | View specific session from search results |
+| `cass_expand` | Expand context around a specific line |
+| `cass_health` | Check if index is ready |
+| `cass_index` | Build/rebuild search index |
+
+**Semantic Memory** (persistent learning):
+| Tool | Purpose |
+|------|---------|
+| `semantic-memory_find` | Search memories by semantic similarity (use `expand=true` for full content) |
+| `semantic-memory_store` | Store learnings with metadata and tags |
+| `semantic-memory_get` | Get a specific memory by ID |
+| `semantic-memory_remove` | Delete outdated/incorrect memories |
+| `semantic-memory_validate` | Validate memory accuracy (resets decay) |
+| `semantic-memory_list` | List stored memories |
+| `semantic-memory_stats` | Show memory statistics |
+| `semantic-memory_migrate` | Migrate database (PGlite 0.2.x → 0.3.x) |
+
+### Other Custom Tools
+
+- **swarm_review, swarm_review_feedback** - Coordinator reviews worker output (3-strike rule)
+
-- **bd-quick\_\*** - Fast beads operations: `ready`, `wip`, `start`, `done`, `create`, `sync`
-- **agentmail\_\*** - Plugin tools for Agent Mail: `init`, `send`, `inbox`, `read_message`, `summarize_thread`, `reserve`, `release`, `ack`, `search`, `health`
-- **beads\_\*** - Plugin tools for beads: `create`, `create_epic`, `query`, `update`, `close`, `start`, `ready`, `sync`, `link_thread`
-- **swarm\_\*** - Swarm orchestration: `decompose`, `validate_decomposition`, `status`, `progress`, `complete`, `subtask_prompt`, `evaluation_prompt`
-- **structured\_\*** - Structured output parsing: `extract_json`, `validate`, `parse_evaluation`, `parse_decomposition`, `parse_bead_tree`
- **typecheck** - TypeScript check with grouped errors
- **git-context** - Branch, status, commits, ahead/behind in one call
- **find-exports** - Find where symbols are exported
- **pkg-scripts** - List package.json scripts
-- **repo-crawl\_\*** - GitHub API repo exploration: `structure`, `readme`, `file`, `tree`, `search`
-- **repo-autopsy\_\*** - Clone & deep analyze repos locally: `clone`, `structure`, `search`, `ast`, `deps`, `hotspots`, `exports_map`, `file`, `blame`, `stats`, `secrets`, `find`, `cleanup`
-- **pdf-library\_\*** - PDF knowledge base in ~/Documents/.pdf-library/ (iCloud sync): `add`, `read`, `list`, `search`, `remove`, `tag`, `refresh`, `batch_add`, `stats`
+- **repo-crawl\_\*** - GitHub API repo exploration
+- **repo-autopsy\_\*** - Clone & deep analyze repos locally
+- **pdf-brain\_\*** - PDF & Markdown knowledge base (supports URLs, `--expand` for context)
+- **ubs\_\*** - Multi-language bug scanner
+
+### DEPRECATED - Do Not Use Directly
+
+- ~~`bd` CLI commands~~ → Use `hive_*` plugin tools
+- ~~`bd-quick_*` tools~~ → Use `hive_*` plugin tools
+- ~~`beads_*` tools~~ → Use `hive_*` plugin tools (aliases deprecated)
+- ~~Agent Mail MCP tools~~ → Use `agentmail_*` plugin tools
-**Note:** Plugin tools (agentmail\_\*, beads\_\*, swarm\_\*, structured\_\*) have built-in context preservation - hard caps on inbox (limit=5, no bodies by default), auto-release reservations on session.idle.
-
+**Why?** Plugin tools have:
+
+- Type-safe Zod validation
+- Context preservation (hard caps on inbox, auto-release)
+- Learning integration (outcome tracking, pattern maturity)
+- UBS bug scanning on completion
+- CASS history queries for decomposition
+
**CRITICAL: These rules prevent context exhaustion. Violating them burns tokens and kills sessions.**
@@ -105,133 +220,434 @@ Do it yourself when:
- File edits where you need to see the result immediately
-## Agent Mail (Multi-Agent Coordination)
+## Swarm Workflow (PRIMARY)
-
-Agent Mail is running as a launchd service at http://127.0.0.1:8765. It provides coordination when multiple AI agents (Claude, Cursor, OpenCode, etc.) work the same repo - prevents collision via file reservations and enables async messaging between agents.
+
+Swarm is the primary pattern for multi-step work. It handles task decomposition, parallel agent coordination, file reservations, and learning from outcomes. The plugin learns what decomposition strategies work and avoids patterns that fail.
+
-Use Agent Mail when:
+### When to Use Swarm
-- Multiple agents are working the same codebase
-- You need to reserve files before editing (prevents conflicts)
-- You want to communicate with other agents asynchronously
-- You need to check if another agent has reserved files you want to edit
+- **Multi-file changes** - anything touching 3+ files
+- **Feature implementation** - new functionality with multiple components
+- **Refactoring** - pattern changes across codebase
+- **Bug fixes with tests** - fix + test in parallel
-Skip Agent Mail when:
+### Swarm Flow
-- You're the only agent working the repo
-- Quick edits that don't need coordination
-
+```
+/swarm "Add user authentication with OAuth"
+```
-### Session Start (REQUIRED before using Agent Mail)
+This triggers:
-Use the plugin tool to initialize (handles project creation + agent registration in one call):
+1. `swarm_decompose` - queries CASS for similar past tasks, generates decomposition prompt
+2. Agent responds with CellTree JSON
+3. `swarm_validate_decomposition` - validates structure, detects file conflicts and instruction conflicts
+4. `hive_create_epic` - creates epic + subtasks atomically
+5. Parallel agents spawn with `swarm_subtask_prompt`
+6. Each agent: `agentmail_reserve` → work → `swarm_complete`
+7. `swarm_complete` runs UBS scan, releases reservations, records outcome
+8. `swarm_record_outcome` tracks learning signals
-```
-agentmail_init(
- project_path="/abs/path/to/repo",
- task_description="Working on feature X"
-)
-# Returns: { agent_name: "BlueLake", project_key: "..." } - remember agent_name!
-```
+### Learning Integration
-### Quick Commands
+The plugin learns from outcomes to improve future decompositions:
-```bash
-# Health check (or use agentmail_health tool)
-curl http://127.0.0.1:8765/health/liveness
+**Confidence Decay** (90-day half-life):
-# Web UI for browsing messages
-open http://127.0.0.1:8765/mail
-```
+- Evaluation criteria weights fade unless revalidated
+- Unreliable criteria get reduced impact
+
+**Implicit Feedback Scoring**:
+
+- Fast + success → helpful signal
+- Slow + errors + retries → harmful signal
+
+**Pattern Maturity**:
+
+- `candidate` → `established` → `proven` → `deprecated`
+- Proven patterns get 1.5x weight, deprecated get 0x
-### Key Workflows (after init)
+**Anti-Pattern Inversion**:
-1. **Reserve files before edit**: `agentmail_reserve(patterns=["src/**"], ttl_seconds=3600, exclusive=true)`
-2. **Send message to other agents**: `agentmail_send(to="OtherAgent", subject="...", body="...", thread_id="bd-123")`
-3. **Check inbox**: `agentmail_inbox()` (auto-limited to 5, headers only)
-4. **Read specific message**: `agentmail_read_message(message_id="...")`
-5. **Summarize thread**: `agentmail_summarize_thread(thread_id="bd-123")`
-6. **Release reservations when done**: `agentmail_release()`
+- Patterns with >60% failure rate auto-invert
+- "Split by file type" → "AVOID: Split by file type (80% failure rate)"
-### Integration with Beads
+### Manual Swarm (when /swarm isn't available)
-- Use beads issue ID as `thread_id` in Agent Mail (e.g., `thread_id="bd-123"`)
-- Include issue ID in file reservation `reason` for traceability
-- When starting a beads task, reserve the files; when closing, release them
+```
+# 1. Decompose
+swarm_decompose(task="Add auth", max_subtasks=5, query_cass=true)
+
+# 2. Validate agent response
+swarm_validate_decomposition(response="{ epic: {...}, subtasks: [...] }")
+
+# 3. Create cells
+hive_create_epic(epic_title="Add auth", subtasks=[...])
+
+# 4. For each subtask agent:
+agentmail_init(project_path="/path/to/repo")
+agentmail_reserve(paths=["src/auth/**"], reason="bd-123.1: Auth service")
+# ... do work ...
+swarm_complete(project_key="...", agent_name="BlueLake", bead_id="bd-123.1", summary="Done", files_touched=["src/auth.ts"])
+```
-## Beads Workflow (MANDATORY)
+## Hive Workflow (via Plugin)
-
-Beads is a git-backed issue tracker that gives you persistent memory across sessions. It solves the amnesia problem - when context compacts or sessions end, beads preserves what you discovered, what's blocked, and what's next. Without it, work gets lost and you repeat mistakes.
-
+
+Hive is a git-backed work item tracker. \*\*Always use `hive*\*`plugin tools, not raw`bd` CLI commands.\*\* Plugin tools have type-safe validation and integrate with swarm learning.
+
### Absolute Rules
- **NEVER** create TODO.md, TASKS.md, PLAN.md, or any markdown task tracking files
-- **ALWAYS** use `bd` commands for issue tracking (run them directly, don't overthink it)
+- **ALWAYS** use `hive_*` plugin tools (not `bd` CLI directly)
- **ALWAYS** sync before ending a session - the plane is not landed until `git push` succeeds
- **NEVER** push directly to main for multi-file changes - use feature branches + PRs
-- **ALWAYS** use `/swarm` for parallel work - it handles branches, beads, and Agent Mail coordination
+- **ALWAYS** use `/swarm` for parallel work
### Session Start
-```bash
-bd ready --json | jq '.[0]' # What's unblocked?
-bd list --status in_progress --json # What's mid-flight?
+```
+hive_ready() # What's unblocked?
+hive_query(status="in_progress") # What's mid-flight?
```
-### During Work - Discovery Linking
+### During Work
-When you find bugs/issues while working on something else, ALWAYS link them:
+```
+# Starting a task
+hive_start(id="bd-123")
-```bash
-bd create "Found the thing" -t bug -p 0 --json
-bd dep add NEW_ID PARENT_ID --type discovered-from
+# Found a bug while working
+hive_create(title="Found the thing", type="bug", priority=0)
+
+# Completed work
+hive_close(id="bd-123", reason="Done: implemented auth flow")
+
+# Update description
+hive_update(id="bd-123", description="Updated scope...")
+```
+
+### Epic Decomposition (Atomic)
+
+```
+hive_create_epic(
+ epic_title="Feature Name",
+ epic_description="Overall goal",
+ subtasks=[
+ { title: "Subtask 1", priority: 2, files: ["src/a.ts"] },
+ { title: "Subtask 2", priority: 2, files: ["src/b.ts"] }
+ ]
+)
+# Creates epic + all subtasks atomically with rollback hints on failure
```
-This preserves the discovery chain and inherits source_repo context.
+### Session End - Land the Plane
-### Epic Decomposition
+**NON-NEGOTIABLE**:
-For multi-step features, create an epic and child tasks:
+```
+# 1. Close completed work
+hive_close(id="bd-123", reason="Done")
-```bash
-bd create "Feature Name" -t epic -p 1 --json # Gets bd-HASH
-bd create "Subtask 1" -p 2 --json # Auto: bd-HASH.1
-bd create "Subtask 2" -p 2 --json # Auto: bd-HASH.2
+# 2. Sync to git
+hive_sync()
+
+# 3. Push (YOU do this, don't defer to user)
+git push
+
+# 4. Verify
+git status # MUST show "up to date with origin"
+
+# 5. What's next?
+hive_ready()
```
-### Continuous Progress Tracking
+## Agent Mail (via Plugin)
-**Update beads frequently as you work** - don't batch updates to the end:
+
+Agent Mail coordinates multiple agents working the same repo. \*\*Always use `agentmail*\*` plugin tools\*\* - they enforce context-safe limits (max 5 messages, no bodies by default).
+
-- **Starting a task**: `bd update ID --status in_progress --json`
-- **Completed a subtask**: `bd close ID --reason "Done: brief description" --json`
-- **Found a problem**: `bd create "Issue title" -t bug -p PRIORITY --json` then link it
-- **Scope changed**: `bd update ID -d "Updated description with new scope" --json`
-- **Blocked on something**: `bd dep add BLOCKED_ID BLOCKER_ID --type blocks`
+### When to Use
-The goal is real-time visibility. If you complete something, close it immediately. If you discover something, file it immediately. Don't accumulate a mental backlog.
+- Multiple agents working same codebase
+- Need to reserve files before editing
+- Async communication between agents
-### Session End - Land the Plane
+### Workflow
+
+```
+# 1. Initialize (once per session)
+agentmail_init(project_path="/abs/path/to/repo", task_description="Working on X")
+# Returns: { agent_name: "BlueLake", project_key: "..." }
+
+# 2. Reserve files before editing
+agentmail_reserve(paths=["src/auth/**"], reason="bd-123: Auth refactor", ttl_seconds=3600)
+
+# 3. Check inbox (headers only, max 5)
+agentmail_inbox()
+
+# 4. Read specific message if needed
+agentmail_read_message(message_id=123)
+
+# 5. Summarize thread (PREFERRED over fetching all)
+agentmail_summarize_thread(thread_id="bd-123")
+
+# 6. Send message
+agentmail_send(to=["OtherAgent"], subject="Status", body="Done with auth", thread_id="bd-123")
+
+# 7. Release when done (or let swarm_complete handle it)
+agentmail_release()
+```
+
+### Integration with Hive
+
+- Use cell ID as `thread_id` (e.g., `thread_id="bd-123"`)
+- Include cell ID in reservation `reason` for traceability
+- `swarm_complete` auto-releases reservations
+
+---
-This is **NON-NEGOTIABLE**. When ending a session:
+## Swarm Mail Coordination (MANDATORY for Multi-Agent Work)
-1. **File remaining work** - anything discovered but not done
-2. **Close completed issues** - `bd close ID --reason "Done" --json`
-3. **Update in-progress** - `bd update ID --status in_progress --json`
-4. **SYNC AND PUSH** (MANDATORY):
- ```bash
- git pull --rebase
- bd sync
- git push
- git status # MUST show "up to date with origin"
- ```
-5. **Pick next work** - `bd ready --json | jq '.[0]'`
-6. **Provide handoff prompt** for next session
+
+**CRITICAL: These are NOT suggestions. Violating these rules breaks coordination and causes conflicts.**
-The session is NOT complete until `git push` succeeds. Never say "ready to push when you are" - YOU push it.
+Swarm Mail is the ONLY way agents coordinate in parallel work. Silent agents cause conflicts, duplicate work, and wasted effort.
+
+
+### ABSOLUTE Requirements
+
+**ALWAYS** use Swarm Mail when:
+
+1. **Working in a swarm** (spawned as a worker agent)
+2. **Editing files others might touch** - reserve BEFORE modifying
+3. **Blocked on external dependencies** - notify coordinator immediately
+4. **Discovering scope changes** - don't silently expand the task
+5. **Finding bugs in other agents' work** - coordinate, don't fix blindly
+6. **Completing a subtask** - use `swarm_complete`, not manual close
+
+**NEVER**:
+
+1. **Work silently** - if you haven't sent a progress update in 15+ minutes, you're doing it wrong
+2. **Skip initialization** - `swarmmail_init` is MANDATORY before any file modifications
+3. **Modify reserved files** - check reservations first, request access if needed
+4. **Complete without releasing** - `swarm_complete` handles this, manual close breaks tracking
+5. **Use generic thread IDs** - ALWAYS use cell ID (e.g., `thread_id="bd-123.4"`)
+
+### MANDATORY Triggers
+
+| Situation | Action | Consequence of Non-Compliance |
+| --------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
+| **Spawned as swarm worker** | `swarmmail_init()` FIRST, before reading files | `swarm_complete` fails, work not tracked, conflicts undetected |
+| **About to modify files** | `swarmmail_reserve()` with cell ID in reason | Edit conflicts, lost work, angry coordinator |
+| **Blocked >5 minutes** | `swarmmail_send(importance="high")` to coordinator | Wasted time, missed dependencies, swarm stalls |
+| **Every 30 min of work** | `swarmmail_send()` progress update | Coordinator assumes you're stuck, may reassign work |
+| **Scope expands** | `swarmmail_send()` + `hive_update()` description | Silent scope creep, integration failures |
+| **Found bug in dependency** | `swarmmail_send()` to owner, don't fix | Duplicate work, conflicting fixes |
+| **Subtask complete** | `swarm_complete()` (not `hive_close`) | Reservations not released, learning data lost |
+
+### Good vs Bad Usage
+
+#### ❌ BAD (Silent Agent)
+
+```
+# Agent spawns, reads files, makes changes, closes cell
+hive_start(id="bd-123.2")
+# ... does work silently for 45 minutes ...
+hive_close(id="bd-123.2", reason="Done")
+```
+
+**Consequences:**
+
+- No reservation tracking → edit conflicts with other agents
+- No progress visibility → coordinator can't unblock dependencies
+- Manual close → learning signals lost, reservations not released
+- Integration hell when merging
+
+#### ✅ GOOD (Coordinated Agent)
+
+```
+# 1. INITIALIZE FIRST
+swarmmail_init(project_path="/abs/path", task_description="bd-123.2: Add auth service")
+
+# 2. RESERVE FILES
+swarmmail_reserve(paths=["src/auth/**"], reason="bd-123.2: Auth service implementation")
+
+# 3. PROGRESS UPDATES (every milestone)
+swarmmail_send(
+ to=["coordinator"],
+ subject="Progress: bd-123.2",
+ body="Schema defined, starting service layer. ETA 20min.",
+ thread_id="bd-123"
+)
+
+# 4. IF BLOCKED
+swarmmail_send(
+ to=["coordinator"],
+ subject="BLOCKED: bd-123.2 needs database schema",
+ body="Can't proceed without db migration from bd-123.1. Need schema for User table.",
+ importance="high",
+ thread_id="bd-123"
+)
+
+# 5. COMPLETE (not manual close)
+swarm_complete(
+ project_key="/abs/path",
+ agent_name="BlueLake",
+ bead_id="bd-123.2",
+ summary="Auth service implemented with JWT strategy",
+ files_touched=["src/auth/service.ts", "src/auth/schema.ts"]
+)
+# Auto-releases reservations, records learning signals, runs UBS scan
+```
+
+### Coordinator Communication Patterns
+
+**Progress Updates** (every 30min or at milestones):
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="Progress: ",
+ body="",
+ thread_id=""
+)
+```
+
+**Blockers** (immediately when stuck >5min):
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="BLOCKED: - ",
+ body="",
+ importance="high",
+ thread_id=""
+)
+hive_update(id="", status="blocked")
+```
+
+**Scope Changes**:
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="Scope Change: ",
+ body="Found X, suggests expanding to include Y. Adds ~15min. Proceed?",
+ thread_id="",
+ ack_required=true
+)
+# Wait for coordinator response before expanding
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="Progress: ",
+body="",
+thread_id=""
+)
+
+```
+
+**Blockers** (immediately when stuck >5min):
+
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="BLOCKED: - ",
+body="",
+importance="high",
+thread_id=""
+)
+hive_update(id="", status="blocked")
+
+```
+
+**Scope Changes**:
+
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="Scope Change: ",
+body="Found X, suggests expanding to include Y. Adds ~15min. Proceed?",
+thread_id="",
+ack_required=true
+)
+
+# Wait for coordinator response before expanding
+
+```
+
+**Cross-Agent Dependencies**:
+
+```
+
+# Don't fix other agents' bugs - coordinate
+
+swarmmail_send(
+to=["OtherAgent", "coordinator"],
+subject="Potential issue in bd-123.1",
+body="Auth service expects User.email but schema has User.emailAddress. Can you align?",
+thread_id="bd-123"
+)
+
+```
+
+### File Reservation Strategy
+
+**Reserve early, release late:**
+
+```
+
+# Reserve at START of work
+
+swarmmail_reserve(
+paths=["src/auth/**", "src/lib/jwt.ts"],
+reason="bd-123.2: Auth service",
+ttl_seconds=3600 # 1 hour
+)
+
+# Work...
+
+# Release via swarm_complete (automatic)
+
+swarm_complete(...) # Releases all your reservations
+
+```
+
+**Requesting access to reserved files:**
+
+```
+
+# Check who owns reservation
+
+swarmmail_inbox() # Shows active reservations in system messages
+
+# Request access
+
+swarmmail_send(
+to=["OtherAgent"],
+subject="Need access to src/lib/jwt.ts",
+body="Need to add refresh token method. Can you release or should I wait?",
+importance="high"
+)
+
+```
+
+### Integration with Hive
+
+- **thread_id = epic ID** for all swarm communication (e.g., `bd-123`)
+- **Subject includes subtask ID** for traceability (e.g., `bd-123.2`)
+- **Reservation reason includes subtask ID** (e.g., `"bd-123.2: Auth service"`)
+- **Never manual close** - always use `swarm_complete`
+
+---
## OpenCode Commands
@@ -239,20 +655,21 @@ Custom commands available via `/command`:
| Command | Purpose |
| --------------------- | -------------------------------------------------------------------- |
-| `/swarm ` | Decompose task into beads, spawn parallel agents with shared context |
+| `/swarm ` | Decompose task into cells, spawn parallel agents with shared context |
| `/parallel "t1" "t2"` | Run explicit task list in parallel |
-| `/fix-all` | Survey PRs + beads, dispatch agents to fix issues |
+| `/fix-all` | Survey PRs + cells, dispatch agents to fix issues |
| `/review-my-shit` | Pre-PR self-review: lint, types, common mistakes |
-| `/handoff` | End session: sync beads, generate continuation prompt |
+| `/handoff` | End session: sync hive, generate continuation prompt |
| `/sweep` | Codebase cleanup: type errors, lint, dead code |
-| `/focus ` | Start focused session on specific bead |
+| `/focus ` | Start focused session on specific cell |
| `/context-dump` | Dump state for model switch or context recovery |
| `/checkpoint` | Compress context: summarize session, preserve decisions |
-| `/retro ` | Post-mortem: extract learnings, update knowledge files |
-| `/worktree-task ` | Create git worktree for isolated bead work |
-| `/commit` | Smart commit with conventional format + beads refs |
-| `/pr-create` | Create PR with beads linking + smart summary |
+| `/retro ` | Post-mortem: extract learnings, update knowledge files |
+| `/worktree-task ` | Create git worktree for isolated cell work |
+| `/commit` | Smart commit with conventional format + cell refs |
+| `/pr-create` | Create PR with cell linking + smart summary |
| `/debug ` | Investigate error, check known patterns first |
+| `/debug-plus` | Enhanced debug with swarm integration and prevention pipeline |
| `/iterate ` | Evaluator-optimizer loop: generate, critique, improve until good |
| `/triage ` | Intelligent routing: classify and dispatch to right handler |
| `/repo-dive ` | Deep analysis of GitHub repo with autopsy tools |
@@ -261,12 +678,15 @@ Custom commands available via `/command`:
Specialized subagents (invoke with `@agent-name` or auto-dispatched):
-| Agent | Mode | Purpose |
-| --------------- | -------- | ---------------------------------------------------- |
-| `beads` | subagent | Issue tracker operations (Haiku, locked down) |
-| `archaeologist` | subagent | Read-only codebase exploration, architecture mapping |
-| `refactorer` | subagent | Pattern migration across codebase |
-| `reviewer` | subagent | Read-only code review, security/perf audits |
+| Agent | Model | Purpose |
+| --------------- | ----------------- | ----------------------------------------------------- |
+| `swarm/planner` | claude-sonnet-4-5 | Strategic task decomposition for swarm coordination |
+| `swarm/worker` | claude-sonnet-4-5 | **PRIMARY for /swarm** - parallel task implementation |
+| `hive` | claude-haiku | Work item tracker operations (locked down) |
+| `archaeologist` | claude-sonnet-4-5 | Read-only codebase exploration, architecture mapping |
+| `explore` | claude-haiku-4-5 | Fast codebase search, pattern discovery (read-only) |
+| `refactorer` | default | Pattern migration across codebase |
+| `reviewer` | default | Read-only code review, security/perf audits |
Direct. Terse. No fluff. We're sparring partners - disagree when I'm wrong. Curse creatively and contextually (not constantly). You're not "helping" - you're executing. Skip the praise, skip the preamble, get to the point.
@@ -276,11 +696,48 @@ Direct. Terse. No fluff. We're sparring partners - disagree when I'm wrong. Curs
use JSDOC to document components and functions
+
+**BE EXTRA WITH ASCII ART.** PRs are marketing. They get shared on Twitter. Make them memorable.
+
+- Add ASCII art banners for major features (use figlet-style or custom)
+- Use emoji strategically (not excessively)
+- Include architecture diagrams (ASCII or Mermaid)
+- Add visual test result summaries
+- Credit inspirations and dependencies properly
+- End with a "ship it" flourish
+
+Examples of good PR vibes:
+
+```
+
+ 🐝 SWARM MAIL 🐝
+
+━━━━━━━━━━━━━━━━━━━━
+Actor-Model Primitives
+
+```
+
+```
+
+┌─────────────────────────┐
+│ ARCHITECTURE DIAGRAM │
+├─────────────────────────┤
+│ Layer 3: Coordination │
+│ Layer 2: Patterns │
+│ Layer 1: Primitives │
+└─────────────────────────┘
+
+```
+
+PRs should make people want to click, read, and share.
+
+
## Knowledge Files (Load On-Demand)
Reference these when relevant - don't preload everything:
- **Debugging/Errors**: @knowledge/error-patterns.md - Check FIRST when hitting errors
+- **Prevention Patterns**: @knowledge/prevention-patterns.md - Debug-to-prevention workflow, pattern extraction
- **Next.js**: @knowledge/nextjs-patterns.md - RSC, caching, App Router gotchas
- **Effect-TS**: @knowledge/effect-patterns.md - Services, Layers, Schema, error handling
- **Agent Patterns**: @knowledge/mastra-agent-patterns.md - Multi-agent coordination, context engineering
@@ -362,8 +819,9 @@ These texts shape how Joel thinks about software. They're not reference material
- Effective TypeScript by Dan Vanderkam (62 specific ways, type narrowing, inference)
- Refactoring by Martin Fowler (extract method, rename, small safe steps)
-- Working Effectively with Legacy Code by Michael Feathers (seams)
+- Working Effectively with Legacy Code by Michael Feathers (seams, characterization tests, dependency breaking)
- Test-Driven Development by Kent Beck (red-green-refactor, fake it til you make it)
+- 4 Rules of Simple Design by Corey Haines/Kent Beck (tests pass, reveals intention, no duplication, fewest elements)
### Systems & Scale
@@ -387,3 +845,429 @@ Channel these people's thinking when their domain expertise applies. Not "what w
- **Ryan Florence** - Remix patterns, progressive enhancement, web fundamentals
- **Alexis King** - "parse, don't validate", type-driven design
- **Venkatesh Rao** - Ribbonfarm, tempo, OODA loops, "premium mediocre", narrative rationality
+
+## Skills (Knowledge Injection)
+
+Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
+
+### When to Use
+
+- **Before unfamiliar work** - check if a skill exists
+- **When you need domain-specific patterns** - load the relevant skill
+- **For complex workflows** - skills provide step-by-step guidance
+
+### Usage
+
+```
+
+skills_list() # See available skills
+skills_use(name="swarm-coordination") # Load a skill
+skills_use(name="cli-builder", context="building a new CLI") # With context
+skills_read(name="mcp-tool-authoring") # Read full skill content
+
+```
+
+### Bundled Skills (Global - ship with plugin)
+
+| Skill | When to Use |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **testing-patterns** | Adding tests, breaking dependencies, characterization tests. Feathers seams + Beck's 4 rules. **USE THIS FOR ALL TESTING WORK.** |
+| **swarm-coordination** | Multi-agent task decomposition, parallel work, file reservations |
+| **cli-builder** | Building CLIs, argument parsing, help text, subcommands |
+| **learning-systems** | Confidence decay, pattern maturity, feedback loops |
+| **skill-creator** | Meta-skill for creating new skills |
+| **system-design** | Architecture decisions, module boundaries, API design |
+
+### Skill Triggers (Auto-load these)
+
+```
+
+Writing tests? → skills_use(name="testing-patterns")
+Breaking dependencies? → skills_use(name="testing-patterns")
+Multi-agent work? → skills_use(name="swarm-coordination")
+Building a CLI? → skills_use(name="cli-builder")
+
+````
+
+**Pro tip:** `testing-patterns` has a full catalog of 25 dependency-breaking techniques in `references/dependency-breaking-catalog.md`. Gold for getting gnarly code under test.
+
+---
+
+## CASS (Cross-Agent Session Search)
+
+Search across ALL your AI coding agent histories. Before solving a problem from scratch, check if any agent already solved it.
+
+**Indexed agents:** Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
+
+### When to Use
+
+- **BEFORE implementing** - check if any agent solved it before
+- **Debugging** - "what did I try last time this error happened?"
+- **Learning patterns** - "how did Cursor handle this API?"
+
+### Quick Reference
+
+```bash
+# Search across all agents
+cass_search(query="authentication error", limit=5)
+
+# Filter by agent
+cass_search(query="useEffect cleanup", agent="claude", days=7)
+
+# Check health first (exit 0 = ready)
+cass_health()
+
+# Build/rebuild index (run if health fails)
+cass_index(full=true)
+
+# View specific result from search
+cass_view(path="/path/to/session.jsonl", line=42)
+
+# Expand context around a line
+cass_expand(path="/path/to/session.jsonl", line=42, context=5)
+````
+
+### Token Budget
+
+Use `fields="minimal"` for compact output (path, line, agent only).
+
+**Pro tip:** Query CASS at the START of complex tasks. Past solutions save time.
+
+---
+
+## Semantic Memory (Persistent Learning)
+
+Store and retrieve learnings across sessions. Memories persist and are searchable by semantic similarity.
+
+### When to Use
+
+- **After solving a tricky problem** - store the solution
+- **After making architectural decisions** - store the reasoning
+- **Before starting work** - search for relevant past learnings
+- **When you discover project-specific patterns** - capture them
+
+### Usage
+
+```bash
+# Store a learning (include WHY, not just WHAT)
+semantic-memory_store(information="OAuth refresh tokens need 5min buffer before expiry to avoid race conditions", tags="auth,tokens,oauth")
+
+# Search for relevant memories (truncated preview by default)
+semantic-memory_find(query="token refresh", limit=5)
+
+# Search with full content (when you need details)
+semantic-memory_find(query="token refresh", limit=5, expand=true)
+
+# Get a specific memory by ID
+semantic-memory_get(id="mem_123")
+
+# Delete outdated/incorrect memory
+semantic-memory_remove(id="mem_456")
+
+# Validate a memory is still accurate (resets decay timer)
+semantic-memory_validate(id="mem_123")
+
+# List all memories
+semantic-memory_list()
+
+# Check stats
+semantic-memory_stats()
+```
+
+### Memory Decay
+
+Memories decay over time (90-day half-life). Validate memories you confirm are still accurate to reset their decay timer. This keeps the knowledge base fresh and relevant.
+
+**Pro tip:** Store the WHY, not just the WHAT. Future you needs context.
+
+---
+
+## Semantic Memory Usage (MANDATORY Triggers)
+
+
+**CRITICAL: Semantic Memory is NOT optional note-taking. It's the forcing function that prevents solving the same problem twice.**
+
+Agents MUST proactively store learnings. The rule is simple: if you learned it the hard way, store it so the next agent (or future you) doesn't.
+
+
+### ABSOLUTE Requirements
+
+**ALWAYS** store memories after:
+
+1. **Solving a tricky bug** - especially ones that took >30min to debug
+2. **Making architectural decisions** - document the WHY, alternatives considered, tradeoffs
+3. **Discovering project-specific patterns** - domain rules, business logic quirks
+4. **Debugging sessions that revealed root causes** - not just "fixed X", but "X fails because Y"
+5. **Learning tool/library gotchas** - API quirks, version-specific bugs, workarounds
+6. **Performance optimizations** - what you tried, what worked, measured impact
+7. **Failed approaches** - store anti-patterns to avoid repeating mistakes
+
+**NEVER**:
+
+1. **Store generic knowledge** - "React hooks need dependencies" is not a memory, it's documentation
+2. **Store without context** - include the problem, solution, AND reasoning
+3. **Assume others will remember** - if it's not in semantic memory, it doesn't exist
+4. **Skip validation** - when you confirm a memory is still accurate, validate it to reset decay
+
+### MANDATORY Triggers
+
+| Situation | Action | Consequence of Non-Compliance |
+| -------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
+| **Debugging >30min** | `semantic-memory_store()` with root cause + solution | Next agent wastes another 30min on same issue |
+| **Architectural decision** | Store reasoning, alternatives, tradeoffs | Future changes break assumptions, regression |
+| **Project-specific pattern** | Store domain rule with examples | Inconsistent implementations across codebase |
+| **Tool/library gotcha** | Store quirk + workaround | Repeated trial-and-error, wasted time |
+| **Before starting complex work** | `semantic-memory_find()` to check for learnings | Reinventing wheels, ignoring past failures |
+| **After /debug-plus success** | Store prevention pattern if one was created | Prevention patterns not reused, bugs recur |
+
+### Good vs Bad Usage
+
+#### ❌ BAD (Generic/Useless Memory)
+
+```
+# Too generic - this is in React docs
+semantic-memory_store(
+ information="useEffect cleanup functions prevent memory leaks",
+ metadata="react, hooks"
+)
+
+# No context - WHAT but not WHY
+semantic-memory_store(
+ information="Changed auth timeout to 5 minutes",
+ metadata="auth"
+)
+
+# Symptom, not root cause
+semantic-memory_store(
+ information="Fixed the login bug by adding a null check",
+ metadata="bugs"
+)
+```
+
+**Consequences:**
+
+- Memory database filled with noise
+- Search returns useless results
+- Actual useful learnings buried
+
+#### ✅ GOOD (Actionable Memory with Context)
+
+```
+# Root cause + reasoning
+semantic-memory_store(
+ information="OAuth refresh tokens need 5min buffer before expiry to avoid race conditions. Without buffer, token refresh can fail mid-request if expiry happens between check and use. Implemented with: if (expiresAt - Date.now() < 300000) refresh(). Affects all API clients using refresh tokens.",
+ metadata="auth, oauth, tokens, race-conditions, api-clients"
+)
+
+# Architectural decision with tradeoffs
+semantic-memory_store(
+ information="Chose event sourcing for audit log instead of snapshot model. Rationale: immutable event history required for compliance (SOC2). Tradeoff: slower queries (mitigated with materialized views), but guarantees we can reconstruct any historical state. Alternative considered: dual-write to events + snapshots (rejected due to consistency complexity).",
+ metadata="architecture, audit-log, event-sourcing, compliance"
+)
+
+# Project-specific domain rule
+semantic-memory_store(
+ information="In this project, User.role='admin' does NOT grant deletion rights. Deletion requires explicit User.permissions.canDelete=true. This is because admin role is granted to support staff who shouldn't delete production data. Tripped up 3 agents so far. Check User.permissions, not User.role.",
+ metadata="domain-rules, auth, permissions, gotcha"
+)
+
+# Failed approach (anti-pattern)
+semantic-memory_store(
+ information="AVOID: Using Zod refinements for async validation. Attempted to validate unique email constraint with .refine(async email => !await db.exists(email)). Problem: Zod runs refinements during parse, blocking the event loop. Solution: validate uniqueness in application layer after parse, return specific validation error. Save Zod for synchronous structural validation only.",
+ metadata="zod, validation, async, anti-pattern, performance"
+)
+
+# Tool-specific gotcha
+semantic-memory_store(
+ information="Next.js 16 Cache Components: useSearchParams() causes entire component to become dynamic, breaking 'use cache'. Workaround: destructure params in parent Server Component, pass as props to cached child. Example: . Affects all search/filter UIs.",
+ metadata="nextjs, cache-components, dynamic-rendering, searchparams"
+)
+```
+
+### When to Search Memories (BEFORE Acting)
+
+**ALWAYS** query semantic memory BEFORE:
+
+1. **Starting a complex task** - check if past agents solved similar problems
+2. **Debugging unfamiliar errors** - search for error messages, symptoms
+3. **Making architectural decisions** - review past decisions in same domain
+4. **Using unfamiliar tools/libraries** - check for known gotchas
+5. **Implementing cross-cutting features** - search for established patterns
+
+**Search Strategies:**
+
+```bash
+# Specific error message
+semantic-memory_find(query="cannot read property of undefined auth", limit=3)
+
+# Domain area
+semantic-memory_find(query="authentication tokens refresh", limit=5)
+
+# Technology stack
+semantic-memory_find(query="Next.js caching searchParams", limit=3)
+
+# Pattern type
+semantic-memory_find(query="event sourcing materialized views", limit=5)
+```
+
+### Memory Validation Workflow
+
+When you encounter a memory from search results and confirm it's still accurate:
+
+```bash
+# Found a memory that helped solve current problem
+semantic-memory_validate(id="mem_xyz123")
+```
+
+**This resets the 90-day decay timer.** Memories that stay relevant get reinforced. Stale memories fade.
+
+### Integration with Debug-Plus
+
+The `/debug-plus` command creates prevention patterns. **ALWAYS** store these in semantic memory:
+
+```bash
+# After debug-plus creates a prevention pattern
+semantic-memory_store(
+ information="Prevention pattern for 'headers already sent' error: root cause is async middleware calling next() before awaiting response write. Detection: grep for 'res.send|res.json' followed by 'next()' without await. Prevention: enforce middleware contract - await all async operations before next(). Automated via UBS scan.",
+ metadata="debug-plus, prevention-pattern, express, async, middleware"
+)
+```
+
+### Memory Hygiene
+
+**DO**:
+
+- Include error messages verbatim (searchable)
+- Tag with technology stack, domain area, pattern type
+- Explain WHY something works, not just WHAT to do
+- Include code examples inline when short (<5 lines)
+- Store failed approaches to prevent repetition
+
+**DON'T**:
+
+- Store without metadata (memories need tags for retrieval)
+- Duplicate documentation (if it's in official docs, link it instead)
+- Store implementation details that change frequently
+- Use vague descriptions ("fixed the thing" → "fixed race condition in auth token refresh by adding 5min buffer")
+
+---
+
+## UBS - Ultimate Bug Scanner
+
+Multi-language bug scanner that catches what humans and AI miss. Run BEFORE committing.
+
+**Languages:** JS/TS, Python, C/C++, Rust, Go, Java, Ruby, Swift
+
+### When to Use
+
+- **Before commit**: Catch null safety, XSS, async/await bugs
+- **After AI generates code**: Validate before accepting
+- **CI gate**: `--fail-on-warning` for PR checks
+
+### Quick Reference
+
+```bash
+# Scan current directory
+ubs_scan()
+
+# Scan specific path
+ubs_scan(path="src/")
+
+# Scan only staged files (pre-commit)
+ubs_scan(staged=true)
+
+# Scan only modified files (quick check)
+ubs_scan(diff=true)
+
+# Filter by language
+ubs_scan(path=".", only="js,python")
+
+# JSON output for parsing
+ubs_scan_json(path=".")
+
+# Check UBS health
+ubs_doctor(fix=true)
+```
+
+### Bug Categories (18 total)
+
+| Category | What It Catches | Severity |
+| ------------- | ------------------------------------- | -------- |
+| Null Safety | "Cannot read property of undefined" | Critical |
+| Security | XSS, injection, prototype pollution | Critical |
+| Async/Await | Race conditions, missing await | Critical |
+| Memory Leaks | Event listeners, timers, detached DOM | High |
+| Type Coercion | === vs == issues | Medium |
+
+### Fix Workflow
+
+1. Run `ubs_scan(path="changed-file.ts")`
+2. Read `file:line:col` locations
+3. Check suggested fix
+4. Fix root cause (not symptom)
+5. Re-run until exit 0
+6. Commit
+
+### Speed Tips
+
+- Scope to changed files: `ubs_scan(path="src/file.ts")` (< 1s)
+- Full scan is slow: `ubs_scan(path=".")` (30s+)
+- Use `--staged` or `--diff` for incremental checks
+
+## Swarm Coordinator Checklist (MANDATORY)
+
+When coordinating a swarm, you MUST monitor workers and review their output.
+
+### Monitor Loop
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ COORDINATOR MONITOR LOOP │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ 1. CHECK INBOX │
+│ swarmmail_inbox() │
+│ swarmmail_read_message(message_id=N) │
+│ │
+│ 2. CHECK STATUS │
+│ swarm_status(epic_id, project_key) │
+│ │
+│ 3. REVIEW COMPLETED WORK │
+│ swarm_review(project_key, epic_id, task_id, files) │
+│ → Generates review prompt with epic context + diff │
+│ │
+│ 4. SEND FEEDBACK │
+│ swarm_review_feedback( │
+│ project_key, task_id, worker_id, │
+│ status="approved|needs_changes", │
+│ issues="[{file, line, issue, suggestion}]" │
+│ ) │
+│ │
+│ 5. INTERVENE IF NEEDED │
+│ - Blocked >5min → unblock or reassign │
+│ - File conflicts → mediate │
+│ - Scope creep → approve or reject │
+│ - 3 review failures → escalate to human │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Review Tools
+
+| Tool | Purpose |
+|------|---------|
+| `swarm_review` | Generate review prompt with epic context, dependencies, and git diff |
+| `swarm_review_feedback` | Send approval/rejection to worker (tracks 3-strike rule) |
+
+### Review Criteria
+
+- Does work fulfill subtask requirements?
+- Does it serve the overall epic goal?
+- Does it enable downstream tasks?
+- Type safety, no obvious bugs?
+
+### 3-Strike Rule
+
+After 3 review rejections, task is marked **blocked**. This signals an architectural problem, not "try harder."
+
+**NEVER skip the review step.** Workers complete faster when they get feedback.
diff --git a/AGENTS.md.backup b/AGENTS.md.backup
new file mode 100644
index 0000000..e832642
--- /dev/null
+++ b/AGENTS.md.backup
@@ -0,0 +1,390 @@
+## Who You're Working With
+
+Joel Hooks - co-founder of egghead.io, education at Vercel, builds badass courses via Skill Recordings (Total TypeScript, Pro Tailwind). Deep background in bootstrapping, systems thinking, and developer education. Lives in the Next.js/React ecosystem daily - RSC, server components, suspense, streaming, caching. Skip the tutorials.
+
+
+
+**always use beads `bd` for planning and task management**
+
+Reach for tools in this order:
+
+1. **Read/Edit** - direct file operations over bash cat/sed
+2. **ast-grep** - structural code search over regex grep
+3. **Glob/Grep** - file discovery over find commands
+4. **Task (subagent)** - complex multi-step exploration, parallel work
+5. **Bash** - system commands, git, bd, running tests/builds
+
+For Next.js projects, use the Next.js MCP tools when available.
+
+### MCP Servers Available
+
+- **next-devtools** - Next.js dev server integration, route inspection, error diagnostics
+- **agent-mail** - Multi-agent coordination, file reservations, async messaging (OPTIONAL - plugin provides same functionality)
+- **chrome-devtools** - Browser automation, DOM inspection, network monitoring
+- **context7** - Library documentation lookup (`use context7` in prompts)
+- **fetch** - Web fetching with markdown conversion, pagination support
+
+### Custom Tools Available
+
+- **bd-quick\_\*** - Fast beads operations: `ready`, `wip`, `start`, `done`, `create`, `sync`
+- **agentmail\_\*** - Plugin tools for Agent Mail: `init`, `send`, `inbox`, `read_message`, `summarize_thread`, `reserve`, `release`, `ack`, `search`, `health`
+- **beads\_\*** - Plugin tools for beads: `create`, `create_epic`, `query`, `update`, `close`, `start`, `ready`, `sync`, `link_thread`
+- **swarm\_\*** - Swarm orchestration: `decompose`, `validate_decomposition`, `status`, `progress`, `complete`, `subtask_prompt`, `evaluation_prompt`
+- **structured\_\*** - Structured output parsing: `extract_json`, `validate`, `parse_evaluation`, `parse_decomposition`, `parse_bead_tree`
+- **typecheck** - TypeScript check with grouped errors
+- **git-context** - Branch, status, commits, ahead/behind in one call
+- **find-exports** - Find where symbols are exported
+- **pkg-scripts** - List package.json scripts
+- **repo-crawl\_\*** - GitHub API repo exploration: `structure`, `readme`, `file`, `tree`, `search`
+- **repo-autopsy\_\*** - Clone & deep analyze repos locally: `clone`, `structure`, `search`, `ast`, `deps`, `hotspots`, `exports_map`, `file`, `blame`, `stats`, `secrets`, `find`, `cleanup`
+- **pdf-brain\_\*** - PDF knowledge base in ~/Documents/.pdf-library/ (iCloud sync): `add`, `read`, `list`, `search`, `remove`, `tag`, `batch_add`, `stats`, `check`
+- **semantic-memory\_\*** - Local vector store with configurable tool descriptions (Qdrant pattern): `store`, `find`, `list`, `stats`, `check`
+
+**Note:** Plugin tools (agentmail\_\*, beads\_\*, swarm\_\*, structured\_\*) have built-in context preservation - hard caps on inbox (limit=5, no bodies by default), auto-release reservations on session.idle.
+
+
+
+**CRITICAL: These rules prevent context exhaustion. Violating them burns tokens and kills sessions.**
+
+### Agent Mail - MANDATORY constraints
+
+- **PREFER** `agentmail_inbox` plugin tool - enforces limit=5 and include_bodies=false automatically (plugin guardrails)
+- **ALWAYS** use `agentmail_summarize_thread` instead of fetching all messages in a thread
+- **ALWAYS** use `agentmail_read_message` for individual message bodies when needed
+- If using MCP tools directly: `include_bodies: false`, `inbox_limit: 5` max, `summarize_thread` over fetch all
+
+### Documentation Tools (context7, effect-docs) - MANDATORY constraints
+
+- **NEVER** call these directly in the main conversation - they dump entire doc pages
+- **ALWAYS** use Task subagent for doc lookups - subagent returns a summary, not the raw dump
+- Front-load doc research at session start if needed, don't lookup mid-session
+- If you must use directly, be extremely specific with topic/query to minimize output
+
+### Search Tools (Glob, Grep, repo-autopsy)
+
+- Use specific patterns, never `**/*` or broad globs
+- Prefer Task subagent for exploratory searches - keeps results out of main context
+- For repo-autopsy, use `maxResults` parameter to limit output
+
+### General Context Hygiene
+
+- Use `/checkpoint` proactively before context gets heavy
+- Prefer Task subagents for any multi-step exploration
+- Summarize findings in your response, don't just paste tool output
+
+
+
+Use extended thinking ("think hard", "think harder", "ultrathink") for:
+
+- Architecture decisions with multiple valid approaches
+- Debugging gnarly issues after initial attempts fail
+- Planning multi-file refactors before touching code
+- Reviewing complex PRs or understanding unfamiliar code
+- Any time you're about to do something irreversible
+
+Skip extended thinking for:
+
+- Simple CRUD operations
+- Obvious bug fixes
+- File reads and exploration
+- Running commands
+
+
+
+Spawn a subagent when:
+
+- Exploring unfamiliar codebase areas (keeps main context clean)
+- Running parallel investigations (multiple hypotheses)
+- Task can be fully described and verified independently
+- You need deep research but only need a summary back
+
+Do it yourself when:
+
+- Task is simple and sequential
+- Context is already loaded
+- Tight feedback loop with user needed
+- File edits where you need to see the result immediately
+
+
+## Agent Mail (Multi-Agent Coordination)
+
+
+Agent Mail is running as a launchd service at http://127.0.0.1:8765. It provides coordination when multiple AI agents (Claude, Cursor, OpenCode, etc.) work the same repo - prevents collision via file reservations and enables async messaging between agents.
+
+Use Agent Mail when:
+
+- Multiple agents are working the same codebase
+- You need to reserve files before editing (prevents conflicts)
+- You want to communicate with other agents asynchronously
+- You need to check if another agent has reserved files you want to edit
+
+Skip Agent Mail when:
+
+- You're the only agent working the repo
+- Quick edits that don't need coordination
+
+
+### Session Start (REQUIRED before using Agent Mail)
+
+Use the plugin tool to initialize (handles project creation + agent registration in one call):
+
+```
+agentmail_init(
+ project_path="/abs/path/to/repo",
+ task_description="Working on feature X"
+)
+# Returns: { agent_name: "BlueLake", project_key: "..." } - remember agent_name!
+```
+
+### Quick Commands
+
+```bash
+# Health check (or use agentmail_health tool)
+curl http://127.0.0.1:8765/health/liveness
+
+# Web UI for browsing messages
+open http://127.0.0.1:8765/mail
+```
+
+### Key Workflows (after init)
+
+1. **Reserve files before edit**: `agentmail_reserve(patterns=["src/**"], ttl_seconds=3600, exclusive=true)`
+2. **Send message to other agents**: `agentmail_send(to="OtherAgent", subject="...", body="...", thread_id="bd-123")`
+3. **Check inbox**: `agentmail_inbox()` (auto-limited to 5, headers only)
+4. **Read specific message**: `agentmail_read_message(message_id="...")`
+5. **Summarize thread**: `agentmail_summarize_thread(thread_id="bd-123")`
+6. **Release reservations when done**: `agentmail_release()`
+
+### Integration with Beads
+
+- Use beads issue ID as `thread_id` in Agent Mail (e.g., `thread_id="bd-123"`)
+- Include issue ID in file reservation `reason` for traceability
+- When starting a beads task, reserve the files; when closing, release them
+
+## Beads Workflow (MANDATORY)
+
+
+Beads is a git-backed issue tracker that gives you persistent memory across sessions. It solves the amnesia problem - when context compacts or sessions end, beads preserves what you discovered, what's blocked, and what's next. Without it, work gets lost and you repeat mistakes.
+
+
+### Absolute Rules
+
+- **NEVER** create TODO.md, TASKS.md, PLAN.md, or any markdown task tracking files
+- **ALWAYS** use `bd` commands for issue tracking (run them directly, don't overthink it)
+- **ALWAYS** sync before ending a session - the plane is not landed until `git push` succeeds
+- **NEVER** push directly to main for multi-file changes - use feature branches + PRs
+- **ALWAYS** use `/swarm` for parallel work - it handles branches, beads, and Agent Mail coordination
+
+### Session Start
+
+```bash
+bd ready --json | jq '.[0]' # What's unblocked?
+bd list --status in_progress --json # What's mid-flight?
+```
+
+### During Work - Discovery Linking
+
+When you find bugs/issues while working on something else, ALWAYS link them:
+
+```bash
+bd create "Found the thing" -t bug -p 0 --json
+bd dep add NEW_ID PARENT_ID --type discovered-from
+```
+
+This preserves the discovery chain and inherits source_repo context.
+
+### Epic Decomposition
+
+For multi-step features, create an epic and child tasks:
+
+```bash
+bd create "Feature Name" -t epic -p 1 --json # Gets bd-HASH
+bd create "Subtask 1" -p 2 --json # Auto: bd-HASH.1
+bd create "Subtask 2" -p 2 --json # Auto: bd-HASH.2
+```
+
+### Continuous Progress Tracking
+
+**Update beads frequently as you work** - don't batch updates to the end:
+
+- **Starting a task**: `bd update ID --status in_progress --json`
+- **Completed a subtask**: `bd close ID --reason "Done: brief description" --json`
+- **Found a problem**: `bd create "Issue title" -t bug -p PRIORITY --json` then link it
+- **Scope changed**: `bd update ID -d "Updated description with new scope" --json`
+- **Blocked on something**: `bd dep add BLOCKED_ID BLOCKER_ID --type blocks`
+
+The goal is real-time visibility. If you complete something, close it immediately. If you discover something, file it immediately. Don't accumulate a mental backlog.
+
+### Session End - Land the Plane
+
+This is **NON-NEGOTIABLE**. When ending a session:
+
+1. **File remaining work** - anything discovered but not done
+2. **Close completed issues** - `bd close ID --reason "Done" --json`
+3. **Update in-progress** - `bd update ID --status in_progress --json`
+4. **SYNC AND PUSH** (MANDATORY):
+ ```bash
+ git pull --rebase
+ bd sync
+ git push
+ git status # MUST show "up to date with origin"
+ ```
+5. **Pick next work** - `bd ready --json | jq '.[0]'`
+6. **Provide handoff prompt** for next session
+
+The session is NOT complete until `git push` succeeds. Never say "ready to push when you are" - YOU push it.
+
+## OpenCode Commands
+
+Custom commands available via `/command`:
+
+| Command | Purpose |
+| --------------------- | -------------------------------------------------------------------- |
+| `/swarm ` | Decompose task into beads, spawn parallel agents with shared context |
+| `/parallel "t1" "t2"` | Run explicit task list in parallel |
+| `/fix-all` | Survey PRs + beads, dispatch agents to fix issues |
+| `/review-my-shit` | Pre-PR self-review: lint, types, common mistakes |
+| `/handoff` | End session: sync beads, generate continuation prompt |
+| `/sweep` | Codebase cleanup: type errors, lint, dead code |
+| `/focus ` | Start focused session on specific bead |
+| `/context-dump` | Dump state for model switch or context recovery |
+| `/checkpoint` | Compress context: summarize session, preserve decisions |
+| `/retro ` | Post-mortem: extract learnings, update knowledge files |
+| `/worktree-task ` | Create git worktree for isolated bead work |
+| `/commit` | Smart commit with conventional format + beads refs |
+| `/pr-create` | Create PR with beads linking + smart summary |
+| `/debug ` | Investigate error, check known patterns first |
+| `/iterate ` | Evaluator-optimizer loop: generate, critique, improve until good |
+| `/triage ` | Intelligent routing: classify and dispatch to right handler |
+| `/repo-dive ` | Deep analysis of GitHub repo with autopsy tools |
+
+## OpenCode Agents
+
+Specialized subagents (invoke with `@agent-name` or auto-dispatched):
+
+| Agent | Mode | Purpose |
+| --------------- | -------- | ---------------------------------------------------- |
+| `beads` | subagent | Issue tracker operations (Haiku, locked down) |
+| `archaeologist` | subagent | Read-only codebase exploration, architecture mapping |
+| `refactorer` | subagent | Pattern migration across codebase |
+| `reviewer` | subagent | Read-only code review, security/perf audits |
+
+
+Direct. Terse. No fluff. We're sparring partners - disagree when I'm wrong. Curse creatively and contextually (not constantly). You're not "helping" - you're executing. Skip the praise, skip the preamble, get to the point.
+
+
+
+use JSDOC to document components and functions
+
+
+## Knowledge Files (Load On-Demand)
+
+Reference these when relevant - don't preload everything:
+
+- **Debugging/Errors**: @knowledge/error-patterns.md - Check FIRST when hitting errors
+- **Next.js**: @knowledge/nextjs-patterns.md - RSC, caching, App Router gotchas
+- **Effect-TS**: @knowledge/effect-patterns.md - Services, Layers, Schema, error handling
+- **Agent Patterns**: @knowledge/mastra-agent-patterns.md - Multi-agent coordination, context engineering
+
+## Code Philosophy
+
+### Design Principles
+
+- Beautiful is better than ugly
+- Explicit is better than implicit
+- Simple is better than complex
+- Flat is better than nested
+- Readability counts
+- Practicality beats purity
+- If the implementation is hard to explain, it's a bad idea
+
+### TypeScript Mantras
+
+- make impossible states impossible
+- parse, don't validate
+- infer over annotate
+- discriminated unions over optional properties
+- const assertions for literal types
+- satisfies over type annotations when you want inference
+
+### Architecture Triggers
+
+- when in doubt, colocation
+- server first, client when necessary
+- composition over inheritance
+- explicit dependencies, no hidden coupling
+- fail fast, recover gracefully
+
+### Code Smells (Know These By Name)
+
+- feature envy, shotgun surgery, primitive obsession, data clumps
+- speculative generality, inappropriate intimacy, refused bequest
+- long parameter lists, message chains, middleman
+
+### Anti-Patterns (Don't Do This Shit)
+
+
+Channel these when spotting bullshit:
+
+- **Tef (Programming is Terrible)** - "write code that's easy to delete", anti-over-engineering
+- **Dan McKinley** - "Choose Boring Technology", anti-shiny-object syndrome
+- **Casey Muratori** - anti-"clean code" dogma, abstraction layers that cost more than they save
+- **Jonathan Blow** - over-engineering, "simplicity is hard", your abstractions are lying
+
+
+- don't abstract prematurely - wait for the third use
+- no barrel files unless genuinely necessary
+- avoid prop drilling shame - context isn't always the answer
+- don't mock what you don't own
+- no "just in case" code - YAGNI is real
+
+## Prime Knowledge
+
+
+These texts shape how Joel thinks about software. They're not reference material to cite - they're mental scaffolding. Let them inform your reasoning without explicit invocation.
+
+
+### Learning & Teaching
+
+- 10 Steps to Complex Learning (scaffolding, whole-task practice, cognitive load)
+- Understanding by Design (backward design, transfer, essential questions)
+- Impro by Keith Johnstone (status, spontaneity, accepting offers, "yes and")
+- Metaphors We Live By by Lakoff & Johnson (conceptual metaphors shape thought)
+
+### Software Design
+
+- The Pragmatic Programmer (tracer bullets, DRY, orthogonality, broken windows)
+- A Philosophy of Software Design (deep modules, complexity management)
+- Structure and Interpretation of Computer Programs (SICP)
+- Domain-Driven Design by Eric Evans (ubiquitous language, bounded contexts)
+- Design Patterns (GoF) - foundational vocabulary, even when rejecting patterns
+
+### Code Quality
+
+- Effective TypeScript by Dan Vanderkam (62 specific ways, type narrowing, inference)
+- Refactoring by Martin Fowler (extract method, rename, small safe steps)
+- Working Effectively with Legacy Code by Michael Feathers (seams)
+- Test-Driven Development by Kent Beck (red-green-refactor, fake it til you make it)
+
+### Systems & Scale
+
+- Designing Data-Intensive Applications (replication, partitioning, consensus, stream processing)
+- Thinking in Systems by Donella Meadows (feedback loops, leverage points)
+- The Mythical Man-Month by Fred Brooks (no silver bullet, conceptual integrity)
+- Release It! by Michael Nygard (stability patterns, bulkheads, circuit breakers)
+- Category Theory for Programmers by Bartosz Milewski (composition, functors, monads)
+
+## Invoke These People
+
+
+Channel these people's thinking when their domain expertise applies. Not "what would X say" but their perspective naturally coloring your approach.
+
+
+- **Matt Pocock** - Total TypeScript, TypeScript Wizard, type gymnastics
+- **Rich Hickey** - simplicity, hammock-driven development, "complect", value of values
+- **Dan Abramov** - React mental models, "just JavaScript", algebraic effects
+- **Sandi Metz** - SOLID made practical, small objects, "99 bottles"
+- **Kent C. Dodds** - testing trophy, testing-library philosophy, colocation
+- **Ryan Florence** - Remix patterns, progressive enhancement, web fundamentals
+- **Alexis King** - "parse, don't validate", type-driven design
+- **Venkatesh Rao** - Ribbonfarm, tempo, OODA loops, "premium mediocre", narrative rationality
diff --git a/AGENTS.md.swarm-backup-2025-12-28T171431555Z b/AGENTS.md.swarm-backup-2025-12-28T171431555Z
new file mode 100644
index 0000000..2e83d6e
--- /dev/null
+++ b/AGENTS.md.swarm-backup-2025-12-28T171431555Z
@@ -0,0 +1,1212 @@
+## Who You're Working With
+
+Joel Hooks - co-founder of egghead.io, education at Vercel, builds badass courses via Skill Recordings (Total TypeScript, Pro Tailwind). Deep background in bootstrapping, systems thinking, and developer education. Lives in the Next.js/React ecosystem daily - RSC, server components, suspense, streaming, caching. Skip the tutorials.
+
+---
+
+## TDD COMMANDMENT (NON-NEGOTIABLE)
+
+```
+┌─────────────────────────────────────────┐
+│ RED → GREEN → REFACTOR │
+│ │
+│ Every feature. Every bug fix. │
+│ No exceptions for swarm work. │
+└─────────────────────────────────────────┘
+```
+
+1. **RED**: Write a failing test first. If it passes, your test is wrong.
+2. **GREEN**: Minimum code to pass. Hardcode if needed. Just make it green.
+3. **REFACTOR**: Clean up while green. Run tests after every change.
+
+**Bug fixes**: Write a test that reproduces the bug FIRST. Then fix it. The test prevents regression forever.
+
+**Legacy code**: Write characterization tests to document actual behavior before changing anything.
+
+**Full doctrine**: `@knowledge/tdd-patterns.md`
+**Dependency breaking**: `skills_use(name="testing-patterns")` — 25 techniques from Feathers
+**Source material**: `pdf-brain_search(query="Feathers seam")` or `pdf-brain_search(query="Beck TDD")`
+
+---
+
+
+
+**USE SWARM PLUGIN TOOLS - NOT RAW CLI/MCP**
+
+The `opencode-swarm-plugin` provides type-safe, context-preserving wrappers. Always prefer plugin tools over raw `bd` commands or Agent Mail MCP calls.
+
+### Tool Priority Order
+
+1. **Swarm Plugin Tools** - `hive_*`, `agentmail_*`, `swarm_*`, `structured_*` (ALWAYS FIRST)
+2. **Read/Edit** - direct file operations over bash cat/sed
+3. **ast-grep** - structural code search over regex grep
+4. **Glob/Grep** - file discovery over find commands
+5. **Task (subagent)** - complex multi-step exploration, parallel work
+6. **Bash** - system commands, git, running tests/builds (NOT for hive/agentmail)
+
+### MCP Servers Available
+
+- **next-devtools** - Next.js dev server integration, route inspection, error diagnostics
+- **chrome-devtools** - Browser automation, DOM inspection, network monitoring
+- **context7** - Library documentation lookup (`use context7` in prompts)
+- **fetch** - Web fetching with markdown conversion, pagination support
+
+### Swarm Plugin Tools (PRIMARY - use these)
+
+**Hive** (work item tracking):
+| Tool | Purpose |
+|------|---------|
+| `hive_create` | Create cell with type-safe validation |
+| `hive_create_epic` | Atomic epic + subtasks creation |
+| `hive_query` | Query with filters (replaces `bd list/ready/wip`) |
+| `hive_update` | Update status/description/priority |
+| `hive_close` | Close with reason |
+| `hive_start` | Mark in-progress |
+| `hive_ready` | Get next unblocked cell |
+| `hive_sync` | Sync to git (MANDATORY at session end) |
+
+> **Migration Note:** `beads_*` aliases still work but show deprecation warnings. Update to `hive_*` tools.
+
+**Agent Mail** (multi-agent coordination):
+| Tool | Purpose |
+|------|---------|
+| `agentmail_init` | Initialize session (project + agent registration) |
+| `agentmail_send` | Send message to agents |
+| `agentmail_inbox` | Fetch inbox (CONTEXT-SAFE: limit=5, no bodies) |
+| `agentmail_read_message` | Fetch ONE message body |
+| `agentmail_summarize_thread` | Summarize thread (PREFERRED) |
+| `agentmail_reserve` | Reserve files for exclusive edit |
+| `agentmail_release` | Release reservations |
+
+**Swarm** (parallel task orchestration):
+| Tool | Purpose |
+|------|---------|
+| `swarm_select_strategy` | Analyze task, recommend strategy (file/feature/risk-based) |
+| `swarm_plan_prompt` | Generate strategy-specific decomposition prompt (queries CASS) |
+| `swarm_validate_decomposition` | Validate response, detect conflicts |
+| `swarm_spawn_subtask` | Generate prompt for worker agent with Agent Mail/hive instructions |
+| `swarm_status` | Get swarm progress by epic ID |
+| `swarm_progress` | Report subtask progress |
+| `swarm_complete` | Complete subtask (runs UBS scan, releases reservations) |
+| `swarm_record_outcome` | Record outcome for learning (duration, errors, retries) |
+
+**Structured Output** (JSON parsing):
+| Tool | Purpose |
+|------|---------|
+| `structured_extract_json` | Extract JSON from markdown/text |
+| `structured_validate` | Validate against schema |
+| `structured_parse_evaluation` | Parse self-evaluation |
+| `structured_parse_cell_tree` | Parse epic decomposition |
+
+**Skills** (knowledge injection):
+| Tool | Purpose |
+|------|---------|
+| `skills_list` | List available skills (global, project, bundled) |
+| `skills_use` | Load skill into context with optional task context |
+| `skills_read` | Read skill content including SKILL.md and references |
+| `skills_create` | Create new skill with SKILL.md template |
+
+**CASS** (cross-agent session search):
+| Tool | Purpose |
+|------|---------|
+| `cass_search` | Search all AI agent histories (query, agent, days, limit) |
+| `cass_view` | View specific session from search results |
+| `cass_expand` | Expand context around a specific line |
+| `cass_health` | Check if index is ready |
+| `cass_index` | Build/rebuild search index |
+
+**Semantic Memory** (persistent learning):
+| Tool | Purpose |
+|------|---------|
+| `semantic-memory_find` | Search memories by semantic similarity (use `expand=true` for full content) |
+| `semantic-memory_store` | Store learnings with metadata and tags |
+| `semantic-memory_get` | Get a specific memory by ID |
+| `semantic-memory_remove` | Delete outdated/incorrect memories |
+| `semantic-memory_validate` | Validate memory accuracy (resets decay) |
+| `semantic-memory_list` | List stored memories |
+| `semantic-memory_stats` | Show memory statistics |
+| `semantic-memory_migrate` | Migrate database (PGlite 0.2.x → 0.3.x) |
+
+### Other Custom Tools
+
+- **typecheck** - TypeScript check with grouped errors
+- **git-context** - Branch, status, commits, ahead/behind in one call
+- **find-exports** - Find where symbols are exported
+- **pkg-scripts** - List package.json scripts
+- **repo-crawl\_\*** - GitHub API repo exploration
+- **repo-autopsy\_\*** - Clone & deep analyze repos locally
+- **pdf-brain\_\*** - PDF & Markdown knowledge base (supports URLs, `--expand` for context)
+- **ubs\_\*** - Multi-language bug scanner
+
+### DEPRECATED - Do Not Use Directly
+
+- ~~`bd` CLI commands~~ → Use `hive_*` plugin tools
+- ~~`bd-quick_*` tools~~ → Use `hive_*` plugin tools
+- ~~`beads_*` tools~~ → Use `hive_*` plugin tools (aliases deprecated)
+- ~~Agent Mail MCP tools~~ → Use `agentmail_*` plugin tools
+
+**Why?** Plugin tools have:
+
+- Type-safe Zod validation
+- Context preservation (hard caps on inbox, auto-release)
+- Learning integration (outcome tracking, pattern maturity)
+- UBS bug scanning on completion
+- CASS history queries for decomposition
+
+
+
+**CRITICAL: These rules prevent context exhaustion. Violating them burns tokens and kills sessions.**
+
+### Agent Mail - MANDATORY constraints
+
+- **PREFER** `agentmail_inbox` plugin tool - enforces limit=5 and include_bodies=false automatically (plugin guardrails)
+- **ALWAYS** use `agentmail_summarize_thread` instead of fetching all messages in a thread
+- **ALWAYS** use `agentmail_read_message` for individual message bodies when needed
+- If using MCP tools directly: `include_bodies: false`, `inbox_limit: 5` max, `summarize_thread` over fetch all
+
+### Documentation Tools (context7, effect-docs) - MANDATORY constraints
+
+- **NEVER** call these directly in the main conversation - they dump entire doc pages
+- **ALWAYS** use Task subagent for doc lookups - subagent returns a summary, not the raw dump
+- Front-load doc research at session start if needed, don't lookup mid-session
+- If you must use directly, be extremely specific with topic/query to minimize output
+
+### Search Tools (Glob, Grep, repo-autopsy)
+
+- Use specific patterns, never `**/*` or broad globs
+- Prefer Task subagent for exploratory searches - keeps results out of main context
+- For repo-autopsy, use `maxResults` parameter to limit output
+
+### General Context Hygiene
+
+- Use `/checkpoint` proactively before context gets heavy
+- Prefer Task subagents for any multi-step exploration
+- Summarize findings in your response, don't just paste tool output
+
+
+
+Use extended thinking ("think hard", "think harder", "ultrathink") for:
+
+- Architecture decisions with multiple valid approaches
+- Debugging gnarly issues after initial attempts fail
+- Planning multi-file refactors before touching code
+- Reviewing complex PRs or understanding unfamiliar code
+- Any time you're about to do something irreversible
+
+Skip extended thinking for:
+
+- Simple CRUD operations
+- Obvious bug fixes
+- File reads and exploration
+- Running commands
+
+
+
+Spawn a subagent when:
+
+- Exploring unfamiliar codebase areas (keeps main context clean)
+- Running parallel investigations (multiple hypotheses)
+- Task can be fully described and verified independently
+- You need deep research but only need a summary back
+
+Do it yourself when:
+
+- Task is simple and sequential
+- Context is already loaded
+- Tight feedback loop with user needed
+- File edits where you need to see the result immediately
+
+
+## Swarm Workflow (PRIMARY)
+
+
+Swarm is the primary pattern for multi-step work. It handles task decomposition, parallel agent coordination, file reservations, and learning from outcomes. The plugin learns what decomposition strategies work and avoids patterns that fail.
+
+
+### When to Use Swarm
+
+- **Multi-file changes** - anything touching 3+ files
+- **Feature implementation** - new functionality with multiple components
+- **Refactoring** - pattern changes across codebase
+- **Bug fixes with tests** - fix + test in parallel
+
+### Swarm Flow
+
+```
+/swarm "Add user authentication with OAuth"
+```
+
+This triggers:
+
+1. `swarm_decompose` - queries CASS for similar past tasks, generates decomposition prompt
+2. Agent responds with CellTree JSON
+3. `swarm_validate_decomposition` - validates structure, detects file conflicts and instruction conflicts
+4. `hive_create_epic` - creates epic + subtasks atomically
+5. Parallel agents spawn with `swarm_subtask_prompt`
+6. Each agent: `agentmail_reserve` → work → `swarm_complete`
+7. `swarm_complete` runs UBS scan, releases reservations, records outcome
+8. `swarm_record_outcome` tracks learning signals
+
+### Learning Integration
+
+The plugin learns from outcomes to improve future decompositions:
+
+**Confidence Decay** (90-day half-life):
+
+- Evaluation criteria weights fade unless revalidated
+- Unreliable criteria get reduced impact
+
+**Implicit Feedback Scoring**:
+
+- Fast + success → helpful signal
+- Slow + errors + retries → harmful signal
+
+**Pattern Maturity**:
+
+- `candidate` → `established` → `proven` → `deprecated`
+- Proven patterns get 1.5x weight, deprecated get 0x
+
+**Anti-Pattern Inversion**:
+
+- Patterns with >60% failure rate auto-invert
+- "Split by file type" → "AVOID: Split by file type (80% failure rate)"
+
+### Manual Swarm (when /swarm isn't available)
+
+```
+# 1. Decompose
+swarm_decompose(task="Add auth", max_subtasks=5, query_cass=true)
+
+# 2. Validate agent response
+swarm_validate_decomposition(response="{ epic: {...}, subtasks: [...] }")
+
+# 3. Create cells
+hive_create_epic(epic_title="Add auth", subtasks=[...])
+
+# 4. For each subtask agent:
+agentmail_init(project_path="/path/to/repo")
+agentmail_reserve(paths=["src/auth/**"], reason="bd-123.1: Auth service")
+# ... do work ...
+swarm_complete(project_key="...", agent_name="BlueLake", bead_id="bd-123.1", summary="Done", files_touched=["src/auth.ts"])
+```
+
+## Hive Workflow (via Plugin)
+
+
+Hive is a git-backed work item tracker. \*\*Always use `hive*\*`plugin tools, not raw`bd` CLI commands.\*\* Plugin tools have type-safe validation and integrate with swarm learning.
+
+
+### Absolute Rules
+
+- **NEVER** create TODO.md, TASKS.md, PLAN.md, or any markdown task tracking files
+- **ALWAYS** use `hive_*` plugin tools (not `bd` CLI directly)
+- **ALWAYS** sync before ending a session - the plane is not landed until `git push` succeeds
+- **NEVER** push directly to main for multi-file changes - use feature branches + PRs
+- **ALWAYS** use `/swarm` for parallel work
+
+### Session Start
+
+```
+hive_ready() # What's unblocked?
+hive_query(status="in_progress") # What's mid-flight?
+```
+
+### During Work
+
+```
+# Starting a task
+hive_start(id="bd-123")
+
+# Found a bug while working
+hive_create(title="Found the thing", type="bug", priority=0)
+
+# Completed work
+hive_close(id="bd-123", reason="Done: implemented auth flow")
+
+# Update description
+hive_update(id="bd-123", description="Updated scope...")
+```
+
+### Epic Decomposition (Atomic)
+
+```
+hive_create_epic(
+ epic_title="Feature Name",
+ epic_description="Overall goal",
+ subtasks=[
+ { title: "Subtask 1", priority: 2, files: ["src/a.ts"] },
+ { title: "Subtask 2", priority: 2, files: ["src/b.ts"] }
+ ]
+)
+# Creates epic + all subtasks atomically with rollback hints on failure
+```
+
+### Session End - Land the Plane
+
+**NON-NEGOTIABLE**:
+
+```
+# 1. Close completed work
+hive_close(id="bd-123", reason="Done")
+
+# 2. Sync to git
+hive_sync()
+
+# 3. Push (YOU do this, don't defer to user)
+git push
+
+# 4. Verify
+git status # MUST show "up to date with origin"
+
+# 5. What's next?
+hive_ready()
+```
+
+## Agent Mail (via Plugin)
+
+
+Agent Mail coordinates multiple agents working the same repo. \*\*Always use `agentmail*\*` plugin tools\*\* - they enforce context-safe limits (max 5 messages, no bodies by default).
+
+
+### When to Use
+
+- Multiple agents working same codebase
+- Need to reserve files before editing
+- Async communication between agents
+
+### Workflow
+
+```
+# 1. Initialize (once per session)
+agentmail_init(project_path="/abs/path/to/repo", task_description="Working on X")
+# Returns: { agent_name: "BlueLake", project_key: "..." }
+
+# 2. Reserve files before editing
+agentmail_reserve(paths=["src/auth/**"], reason="bd-123: Auth refactor", ttl_seconds=3600)
+
+# 3. Check inbox (headers only, max 5)
+agentmail_inbox()
+
+# 4. Read specific message if needed
+agentmail_read_message(message_id=123)
+
+# 5. Summarize thread (PREFERRED over fetching all)
+agentmail_summarize_thread(thread_id="bd-123")
+
+# 6. Send message
+agentmail_send(to=["OtherAgent"], subject="Status", body="Done with auth", thread_id="bd-123")
+
+# 7. Release when done (or let swarm_complete handle it)
+agentmail_release()
+```
+
+### Integration with Hive
+
+- Use cell ID as `thread_id` (e.g., `thread_id="bd-123"`)
+- Include cell ID in reservation `reason` for traceability
+- `swarm_complete` auto-releases reservations
+
+---
+
+## Swarm Mail Coordination (MANDATORY for Multi-Agent Work)
+
+
+**CRITICAL: These are NOT suggestions. Violating these rules breaks coordination and causes conflicts.**
+
+Swarm Mail is the ONLY way agents coordinate in parallel work. Silent agents cause conflicts, duplicate work, and wasted effort.
+
+
+### ABSOLUTE Requirements
+
+**ALWAYS** use Swarm Mail when:
+
+1. **Working in a swarm** (spawned as a worker agent)
+2. **Editing files others might touch** - reserve BEFORE modifying
+3. **Blocked on external dependencies** - notify coordinator immediately
+4. **Discovering scope changes** - don't silently expand the task
+5. **Finding bugs in other agents' work** - coordinate, don't fix blindly
+6. **Completing a subtask** - use `swarm_complete`, not manual close
+
+**NEVER**:
+
+1. **Work silently** - if you haven't sent a progress update in 15+ minutes, you're doing it wrong
+2. **Skip initialization** - `swarmmail_init` is MANDATORY before any file modifications
+3. **Modify reserved files** - check reservations first, request access if needed
+4. **Complete without releasing** - `swarm_complete` handles this, manual close breaks tracking
+5. **Use generic thread IDs** - ALWAYS use cell ID (e.g., `thread_id="bd-123.4"`)
+
+### MANDATORY Triggers
+
+| Situation | Action | Consequence of Non-Compliance |
+| --------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
+| **Spawned as swarm worker** | `swarmmail_init()` FIRST, before reading files | `swarm_complete` fails, work not tracked, conflicts undetected |
+| **About to modify files** | `swarmmail_reserve()` with cell ID in reason | Edit conflicts, lost work, angry coordinator |
+| **Blocked >5 minutes** | `swarmmail_send(importance="high")` to coordinator | Wasted time, missed dependencies, swarm stalls |
+| **Every 30 min of work** | `swarmmail_send()` progress update | Coordinator assumes you're stuck, may reassign work |
+| **Scope expands** | `swarmmail_send()` + `hive_update()` description | Silent scope creep, integration failures |
+| **Found bug in dependency** | `swarmmail_send()` to owner, don't fix | Duplicate work, conflicting fixes |
+| **Subtask complete** | `swarm_complete()` (not `hive_close`) | Reservations not released, learning data lost |
+
+### Good vs Bad Usage
+
+#### ❌ BAD (Silent Agent)
+
+```
+# Agent spawns, reads files, makes changes, closes cell
+hive_start(id="bd-123.2")
+# ... does work silently for 45 minutes ...
+hive_close(id="bd-123.2", reason="Done")
+```
+
+**Consequences:**
+
+- No reservation tracking → edit conflicts with other agents
+- No progress visibility → coordinator can't unblock dependencies
+- Manual close → learning signals lost, reservations not released
+- Integration hell when merging
+
+#### ✅ GOOD (Coordinated Agent)
+
+```
+# 1. INITIALIZE FIRST
+swarmmail_init(project_path="/abs/path", task_description="bd-123.2: Add auth service")
+
+# 2. RESERVE FILES
+swarmmail_reserve(paths=["src/auth/**"], reason="bd-123.2: Auth service implementation")
+
+# 3. PROGRESS UPDATES (every milestone)
+swarmmail_send(
+ to=["coordinator"],
+ subject="Progress: bd-123.2",
+ body="Schema defined, starting service layer. ETA 20min.",
+ thread_id="bd-123"
+)
+
+# 4. IF BLOCKED
+swarmmail_send(
+ to=["coordinator"],
+ subject="BLOCKED: bd-123.2 needs database schema",
+ body="Can't proceed without db migration from bd-123.1. Need schema for User table.",
+ importance="high",
+ thread_id="bd-123"
+)
+
+# 5. COMPLETE (not manual close)
+swarm_complete(
+ project_key="/abs/path",
+ agent_name="BlueLake",
+ bead_id="bd-123.2",
+ summary="Auth service implemented with JWT strategy",
+ files_touched=["src/auth/service.ts", "src/auth/schema.ts"]
+)
+# Auto-releases reservations, records learning signals, runs UBS scan
+```
+
+### Coordinator Communication Patterns
+
+**Progress Updates** (every 30min or at milestones):
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="Progress: ",
+ body="",
+ thread_id=""
+)
+```
+
+**Blockers** (immediately when stuck >5min):
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="BLOCKED: - ",
+ body="",
+ importance="high",
+ thread_id=""
+)
+hive_update(id="", status="blocked")
+```
+
+**Scope Changes**:
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="Scope Change: ",
+ body="Found X, suggests expanding to include Y. Adds ~15min. Proceed?",
+ thread_id="",
+ ack_required=true
+)
+# Wait for coordinator response before expanding
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="Progress: ",
+body="",
+thread_id=""
+)
+
+```
+
+**Blockers** (immediately when stuck >5min):
+
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="BLOCKED: - ",
+body="",
+importance="high",
+thread_id=""
+)
+hive_update(id="", status="blocked")
+
+```
+
+**Scope Changes**:
+
+```
+
+swarmmail_send(
+to=["coordinator"],
+subject="Scope Change: ",
+body="Found X, suggests expanding to include Y. Adds ~15min. Proceed?",
+thread_id="",
+ack_required=true
+)
+
+# Wait for coordinator response before expanding
+
+```
+
+**Cross-Agent Dependencies**:
+
+```
+
+# Don't fix other agents' bugs - coordinate
+
+swarmmail_send(
+to=["OtherAgent", "coordinator"],
+subject="Potential issue in bd-123.1",
+body="Auth service expects User.email but schema has User.emailAddress. Can you align?",
+thread_id="bd-123"
+)
+
+```
+
+### File Reservation Strategy
+
+**Reserve early, release late:**
+
+```
+
+# Reserve at START of work
+
+swarmmail_reserve(
+paths=["src/auth/**", "src/lib/jwt.ts"],
+reason="bd-123.2: Auth service",
+ttl_seconds=3600 # 1 hour
+)
+
+# Work...
+
+# Release via swarm_complete (automatic)
+
+swarm_complete(...) # Releases all your reservations
+
+```
+
+**Requesting access to reserved files:**
+
+```
+
+# Check who owns reservation
+
+swarmmail_inbox() # Shows active reservations in system messages
+
+# Request access
+
+swarmmail_send(
+to=["OtherAgent"],
+subject="Need access to src/lib/jwt.ts",
+body="Need to add refresh token method. Can you release or should I wait?",
+importance="high"
+)
+
+```
+
+### Integration with Hive
+
+- **thread_id = epic ID** for all swarm communication (e.g., `bd-123`)
+- **Subject includes subtask ID** for traceability (e.g., `bd-123.2`)
+- **Reservation reason includes subtask ID** (e.g., `"bd-123.2: Auth service"`)
+- **Never manual close** - always use `swarm_complete`
+
+---
+
+## OpenCode Commands
+
+Custom commands available via `/command`:
+
+| Command | Purpose |
+| --------------------- | -------------------------------------------------------------------- |
+| `/swarm ` | Decompose task into cells, spawn parallel agents with shared context |
+| `/parallel "t1" "t2"` | Run explicit task list in parallel |
+| `/fix-all` | Survey PRs + cells, dispatch agents to fix issues |
+| `/review-my-shit` | Pre-PR self-review: lint, types, common mistakes |
+| `/handoff` | End session: sync hive, generate continuation prompt |
+| `/sweep` | Codebase cleanup: type errors, lint, dead code |
+| `/focus ` | Start focused session on specific cell |
+| `/context-dump` | Dump state for model switch or context recovery |
+| `/checkpoint` | Compress context: summarize session, preserve decisions |
+| `/retro ` | Post-mortem: extract learnings, update knowledge files |
+| `/worktree-task ` | Create git worktree for isolated cell work |
+| `/commit` | Smart commit with conventional format + cell refs |
+| `/pr-create` | Create PR with cell linking + smart summary |
+| `/debug ` | Investigate error, check known patterns first |
+| `/debug-plus` | Enhanced debug with swarm integration and prevention pipeline |
+| `/iterate ` | Evaluator-optimizer loop: generate, critique, improve until good |
+| `/triage ` | Intelligent routing: classify and dispatch to right handler |
+| `/repo-dive ` | Deep analysis of GitHub repo with autopsy tools |
+
+## OpenCode Agents
+
+Specialized subagents (invoke with `@agent-name` or auto-dispatched):
+
+| Agent | Model | Purpose |
+| --------------- | ----------------- | ----------------------------------------------------- |
+| `swarm/planner` | claude-sonnet-4-5 | Strategic task decomposition for swarm coordination |
+| `swarm/worker` | claude-sonnet-4-5 | **PRIMARY for /swarm** - parallel task implementation |
+| `hive` | claude-haiku | Work item tracker operations (locked down) |
+| `archaeologist` | claude-sonnet-4-5 | Read-only codebase exploration, architecture mapping |
+| `explore` | claude-haiku-4-5 | Fast codebase search, pattern discovery (read-only) |
+| `refactorer` | default | Pattern migration across codebase |
+| `reviewer` | default | Read-only code review, security/perf audits |
+
+
+Direct. Terse. No fluff. We're sparring partners - disagree when I'm wrong. Curse creatively and contextually (not constantly). You're not "helping" - you're executing. Skip the praise, skip the preamble, get to the point.
+
+
+
+use JSDOC to document components and functions
+
+
+
+**BE EXTRA WITH ASCII ART.** PRs are marketing. They get shared on Twitter. Make them memorable.
+
+- Add ASCII art banners for major features (use figlet-style or custom)
+- Use emoji strategically (not excessively)
+- Include architecture diagrams (ASCII or Mermaid)
+- Add visual test result summaries
+- Credit inspirations and dependencies properly
+- End with a "ship it" flourish
+
+Examples of good PR vibes:
+
+```
+
+ 🐝 SWARM MAIL 🐝
+
+━━━━━━━━━━━━━━━━━━━━
+Actor-Model Primitives
+
+```
+
+```
+
+┌─────────────────────────┐
+│ ARCHITECTURE DIAGRAM │
+├─────────────────────────┤
+│ Layer 3: Coordination │
+│ Layer 2: Patterns │
+│ Layer 1: Primitives │
+└─────────────────────────┘
+
+```
+
+PRs should make people want to click, read, and share.
+
+
+## Knowledge Files (Load On-Demand)
+
+Reference these when relevant - don't preload everything:
+
+- **Debugging/Errors**: @knowledge/error-patterns.md - Check FIRST when hitting errors
+- **Prevention Patterns**: @knowledge/prevention-patterns.md - Debug-to-prevention workflow, pattern extraction
+- **Next.js**: @knowledge/nextjs-patterns.md - RSC, caching, App Router gotchas
+- **Effect-TS**: @knowledge/effect-patterns.md - Services, Layers, Schema, error handling
+- **Agent Patterns**: @knowledge/mastra-agent-patterns.md - Multi-agent coordination, context engineering
+
+## Code Philosophy
+
+### Design Principles
+
+- Beautiful is better than ugly
+- Explicit is better than implicit
+- Simple is better than complex
+- Flat is better than nested
+- Readability counts
+- Practicality beats purity
+- If the implementation is hard to explain, it's a bad idea
+
+### TypeScript Mantras
+
+- make impossible states impossible
+- parse, don't validate
+- infer over annotate
+- discriminated unions over optional properties
+- const assertions for literal types
+- satisfies over type annotations when you want inference
+
+### Architecture Triggers
+
+- when in doubt, colocation
+- server first, client when necessary
+- composition over inheritance
+- explicit dependencies, no hidden coupling
+- fail fast, recover gracefully
+
+### Code Smells (Know These By Name)
+
+- feature envy, shotgun surgery, primitive obsession, data clumps
+- speculative generality, inappropriate intimacy, refused bequest
+- long parameter lists, message chains, middleman
+
+### Anti-Patterns (Don't Do This Shit)
+
+
+Channel these when spotting bullshit:
+
+- **Tef (Programming is Terrible)** - "write code that's easy to delete", anti-over-engineering
+- **Dan McKinley** - "Choose Boring Technology", anti-shiny-object syndrome
+- **Casey Muratori** - anti-"clean code" dogma, abstraction layers that cost more than they save
+- **Jonathan Blow** - over-engineering, "simplicity is hard", your abstractions are lying
+
+
+- don't abstract prematurely - wait for the third use
+- no barrel files unless genuinely necessary
+- avoid prop drilling shame - context isn't always the answer
+- don't mock what you don't own
+- no "just in case" code - YAGNI is real
+
+## Prime Knowledge
+
+
+These texts shape how Joel thinks about software. They're not reference material to cite - they're mental scaffolding. Let them inform your reasoning without explicit invocation.
+
+
+### Learning & Teaching
+
+- 10 Steps to Complex Learning (scaffolding, whole-task practice, cognitive load)
+- Understanding by Design (backward design, transfer, essential questions)
+- Impro by Keith Johnstone (status, spontaneity, accepting offers, "yes and")
+- Metaphors We Live By by Lakoff & Johnson (conceptual metaphors shape thought)
+
+### Software Design
+
+- The Pragmatic Programmer (tracer bullets, DRY, orthogonality, broken windows)
+- A Philosophy of Software Design (deep modules, complexity management)
+- Structure and Interpretation of Computer Programs (SICP)
+- Domain-Driven Design by Eric Evans (ubiquitous language, bounded contexts)
+- Design Patterns (GoF) - foundational vocabulary, even when rejecting patterns
+
+### Code Quality
+
+- Effective TypeScript by Dan Vanderkam (62 specific ways, type narrowing, inference)
+- Refactoring by Martin Fowler (extract method, rename, small safe steps)
+- Working Effectively with Legacy Code by Michael Feathers (seams, characterization tests, dependency breaking)
+- Test-Driven Development by Kent Beck (red-green-refactor, fake it til you make it)
+- 4 Rules of Simple Design by Corey Haines/Kent Beck (tests pass, reveals intention, no duplication, fewest elements)
+
+### Systems & Scale
+
+- Designing Data-Intensive Applications (replication, partitioning, consensus, stream processing)
+- Thinking in Systems by Donella Meadows (feedback loops, leverage points)
+- The Mythical Man-Month by Fred Brooks (no silver bullet, conceptual integrity)
+- Release It! by Michael Nygard (stability patterns, bulkheads, circuit breakers)
+- Category Theory for Programmers by Bartosz Milewski (composition, functors, monads)
+
+## Invoke These People
+
+
+Channel these people's thinking when their domain expertise applies. Not "what would X say" but their perspective naturally coloring your approach.
+
+
+- **Matt Pocock** - Total TypeScript, TypeScript Wizard, type gymnastics
+- **Rich Hickey** - simplicity, hammock-driven development, "complect", value of values
+- **Dan Abramov** - React mental models, "just JavaScript", algebraic effects
+- **Sandi Metz** - SOLID made practical, small objects, "99 bottles"
+- **Kent C. Dodds** - testing trophy, testing-library philosophy, colocation
+- **Ryan Florence** - Remix patterns, progressive enhancement, web fundamentals
+- **Alexis King** - "parse, don't validate", type-driven design
+- **Venkatesh Rao** - Ribbonfarm, tempo, OODA loops, "premium mediocre", narrative rationality
+
+## Skills (Knowledge Injection)
+
+Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
+
+### When to Use
+
+- **Before unfamiliar work** - check if a skill exists
+- **When you need domain-specific patterns** - load the relevant skill
+- **For complex workflows** - skills provide step-by-step guidance
+
+### Usage
+
+```
+
+skills_list() # See available skills
+skills_use(name="swarm-coordination") # Load a skill
+skills_use(name="cli-builder", context="building a new CLI") # With context
+skills_read(name="mcp-tool-authoring") # Read full skill content
+
+```
+
+### Bundled Skills (Global - ship with plugin)
+
+| Skill | When to Use |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **testing-patterns** | Adding tests, breaking dependencies, characterization tests. Feathers seams + Beck's 4 rules. **USE THIS FOR ALL TESTING WORK.** |
+| **swarm-coordination** | Multi-agent task decomposition, parallel work, file reservations |
+| **cli-builder** | Building CLIs, argument parsing, help text, subcommands |
+| **learning-systems** | Confidence decay, pattern maturity, feedback loops |
+| **skill-creator** | Meta-skill for creating new skills |
+| **system-design** | Architecture decisions, module boundaries, API design |
+
+### Skill Triggers (Auto-load these)
+
+```
+
+Writing tests? → skills_use(name="testing-patterns")
+Breaking dependencies? → skills_use(name="testing-patterns")
+Multi-agent work? → skills_use(name="swarm-coordination")
+Building a CLI? → skills_use(name="cli-builder")
+
+````
+
+**Pro tip:** `testing-patterns` has a full catalog of 25 dependency-breaking techniques in `references/dependency-breaking-catalog.md`. Gold for getting gnarly code under test.
+
+---
+
+## CASS (Cross-Agent Session Search)
+
+Search across ALL your AI coding agent histories. Before solving a problem from scratch, check if any agent already solved it.
+
+**Indexed agents:** Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
+
+### When to Use
+
+- **BEFORE implementing** - check if any agent solved it before
+- **Debugging** - "what did I try last time this error happened?"
+- **Learning patterns** - "how did Cursor handle this API?"
+
+### Quick Reference
+
+```bash
+# Search across all agents
+cass_search(query="authentication error", limit=5)
+
+# Filter by agent
+cass_search(query="useEffect cleanup", agent="claude", days=7)
+
+# Check health first (exit 0 = ready)
+cass_health()
+
+# Build/rebuild index (run if health fails)
+cass_index(full=true)
+
+# View specific result from search
+cass_view(path="/path/to/session.jsonl", line=42)
+
+# Expand context around a line
+cass_expand(path="/path/to/session.jsonl", line=42, context=5)
+````
+
+### Token Budget
+
+Use `fields="minimal"` for compact output (path, line, agent only).
+
+**Pro tip:** Query CASS at the START of complex tasks. Past solutions save time.
+
+---
+
+## Semantic Memory (Persistent Learning)
+
+Store and retrieve learnings across sessions. Memories persist and are searchable by semantic similarity.
+
+### When to Use
+
+- **After solving a tricky problem** - store the solution
+- **After making architectural decisions** - store the reasoning
+- **Before starting work** - search for relevant past learnings
+- **When you discover project-specific patterns** - capture them
+
+### Usage
+
+```bash
+# Store a learning (include WHY, not just WHAT)
+semantic-memory_store(information="OAuth refresh tokens need 5min buffer before expiry to avoid race conditions", tags="auth,tokens,oauth")
+
+# Search for relevant memories (truncated preview by default)
+semantic-memory_find(query="token refresh", limit=5)
+
+# Search with full content (when you need details)
+semantic-memory_find(query="token refresh", limit=5, expand=true)
+
+# Get a specific memory by ID
+semantic-memory_get(id="mem_123")
+
+# Delete outdated/incorrect memory
+semantic-memory_remove(id="mem_456")
+
+# Validate a memory is still accurate (resets decay timer)
+semantic-memory_validate(id="mem_123")
+
+# List all memories
+semantic-memory_list()
+
+# Check stats
+semantic-memory_stats()
+```
+
+### Memory Decay
+
+Memories decay over time (90-day half-life). Validate memories you confirm are still accurate to reset their decay timer. This keeps the knowledge base fresh and relevant.
+
+**Pro tip:** Store the WHY, not just the WHAT. Future you needs context.
+
+---
+
+## Semantic Memory Usage (MANDATORY Triggers)
+
+
+**CRITICAL: Semantic Memory is NOT optional note-taking. It's the forcing function that prevents solving the same problem twice.**
+
+Agents MUST proactively store learnings. The rule is simple: if you learned it the hard way, store it so the next agent (or future you) doesn't.
+
+
+### ABSOLUTE Requirements
+
+**ALWAYS** store memories after:
+
+1. **Solving a tricky bug** - especially ones that took >30min to debug
+2. **Making architectural decisions** - document the WHY, alternatives considered, tradeoffs
+3. **Discovering project-specific patterns** - domain rules, business logic quirks
+4. **Debugging sessions that revealed root causes** - not just "fixed X", but "X fails because Y"
+5. **Learning tool/library gotchas** - API quirks, version-specific bugs, workarounds
+6. **Performance optimizations** - what you tried, what worked, measured impact
+7. **Failed approaches** - store anti-patterns to avoid repeating mistakes
+
+**NEVER**:
+
+1. **Store generic knowledge** - "React hooks need dependencies" is not a memory, it's documentation
+2. **Store without context** - include the problem, solution, AND reasoning
+3. **Assume others will remember** - if it's not in semantic memory, it doesn't exist
+4. **Skip validation** - when you confirm a memory is still accurate, validate it to reset decay
+
+### MANDATORY Triggers
+
+| Situation | Action | Consequence of Non-Compliance |
+| -------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
+| **Debugging >30min** | `semantic-memory_store()` with root cause + solution | Next agent wastes another 30min on same issue |
+| **Architectural decision** | Store reasoning, alternatives, tradeoffs | Future changes break assumptions, regression |
+| **Project-specific pattern** | Store domain rule with examples | Inconsistent implementations across codebase |
+| **Tool/library gotcha** | Store quirk + workaround | Repeated trial-and-error, wasted time |
+| **Before starting complex work** | `semantic-memory_find()` to check for learnings | Reinventing wheels, ignoring past failures |
+| **After /debug-plus success** | Store prevention pattern if one was created | Prevention patterns not reused, bugs recur |
+
+### Good vs Bad Usage
+
+#### ❌ BAD (Generic/Useless Memory)
+
+```
+# Too generic - this is in React docs
+semantic-memory_store(
+ information="useEffect cleanup functions prevent memory leaks",
+ metadata="react, hooks"
+)
+
+# No context - WHAT but not WHY
+semantic-memory_store(
+ information="Changed auth timeout to 5 minutes",
+ metadata="auth"
+)
+
+# Symptom, not root cause
+semantic-memory_store(
+ information="Fixed the login bug by adding a null check",
+ metadata="bugs"
+)
+```
+
+**Consequences:**
+
+- Memory database filled with noise
+- Search returns useless results
+- Actual useful learnings buried
+
+#### ✅ GOOD (Actionable Memory with Context)
+
+```
+# Root cause + reasoning
+semantic-memory_store(
+ information="OAuth refresh tokens need 5min buffer before expiry to avoid race conditions. Without buffer, token refresh can fail mid-request if expiry happens between check and use. Implemented with: if (expiresAt - Date.now() < 300000) refresh(). Affects all API clients using refresh tokens.",
+ metadata="auth, oauth, tokens, race-conditions, api-clients"
+)
+
+# Architectural decision with tradeoffs
+semantic-memory_store(
+ information="Chose event sourcing for audit log instead of snapshot model. Rationale: immutable event history required for compliance (SOC2). Tradeoff: slower queries (mitigated with materialized views), but guarantees we can reconstruct any historical state. Alternative considered: dual-write to events + snapshots (rejected due to consistency complexity).",
+ metadata="architecture, audit-log, event-sourcing, compliance"
+)
+
+# Project-specific domain rule
+semantic-memory_store(
+ information="In this project, User.role='admin' does NOT grant deletion rights. Deletion requires explicit User.permissions.canDelete=true. This is because admin role is granted to support staff who shouldn't delete production data. Tripped up 3 agents so far. Check User.permissions, not User.role.",
+ metadata="domain-rules, auth, permissions, gotcha"
+)
+
+# Failed approach (anti-pattern)
+semantic-memory_store(
+ information="AVOID: Using Zod refinements for async validation. Attempted to validate unique email constraint with .refine(async email => !await db.exists(email)). Problem: Zod runs refinements during parse, blocking the event loop. Solution: validate uniqueness in application layer after parse, return specific validation error. Save Zod for synchronous structural validation only.",
+ metadata="zod, validation, async, anti-pattern, performance"
+)
+
+# Tool-specific gotcha
+semantic-memory_store(
+ information="Next.js 16 Cache Components: useSearchParams() causes entire component to become dynamic, breaking 'use cache'. Workaround: destructure params in parent Server Component, pass as props to cached child. Example: . Affects all search/filter UIs.",
+ metadata="nextjs, cache-components, dynamic-rendering, searchparams"
+)
+```
+
+### When to Search Memories (BEFORE Acting)
+
+**ALWAYS** query semantic memory BEFORE:
+
+1. **Starting a complex task** - check if past agents solved similar problems
+2. **Debugging unfamiliar errors** - search for error messages, symptoms
+3. **Making architectural decisions** - review past decisions in same domain
+4. **Using unfamiliar tools/libraries** - check for known gotchas
+5. **Implementing cross-cutting features** - search for established patterns
+
+**Search Strategies:**
+
+```bash
+# Specific error message
+semantic-memory_find(query="cannot read property of undefined auth", limit=3)
+
+# Domain area
+semantic-memory_find(query="authentication tokens refresh", limit=5)
+
+# Technology stack
+semantic-memory_find(query="Next.js caching searchParams", limit=3)
+
+# Pattern type
+semantic-memory_find(query="event sourcing materialized views", limit=5)
+```
+
+### Memory Validation Workflow
+
+When you encounter a memory from search results and confirm it's still accurate:
+
+```bash
+# Found a memory that helped solve current problem
+semantic-memory_validate(id="mem_xyz123")
+```
+
+**This resets the 90-day decay timer.** Memories that stay relevant get reinforced. Stale memories fade.
+
+### Integration with Debug-Plus
+
+The `/debug-plus` command creates prevention patterns. **ALWAYS** store these in semantic memory:
+
+```bash
+# After debug-plus creates a prevention pattern
+semantic-memory_store(
+ information="Prevention pattern for 'headers already sent' error: root cause is async middleware calling next() before awaiting response write. Detection: grep for 'res.send|res.json' followed by 'next()' without await. Prevention: enforce middleware contract - await all async operations before next(). Automated via UBS scan.",
+ metadata="debug-plus, prevention-pattern, express, async, middleware"
+)
+```
+
+### Memory Hygiene
+
+**DO**:
+
+- Include error messages verbatim (searchable)
+- Tag with technology stack, domain area, pattern type
+- Explain WHY something works, not just WHAT to do
+- Include code examples inline when short (<5 lines)
+- Store failed approaches to prevent repetition
+
+**DON'T**:
+
+- Store without metadata (memories need tags for retrieval)
+- Duplicate documentation (if it's in official docs, link it instead)
+- Store implementation details that change frequently
+- Use vague descriptions ("fixed the thing" → "fixed race condition in auth token refresh by adding 5min buffer")
+
+---
+
+## UBS - Ultimate Bug Scanner
+
+Multi-language bug scanner that catches what humans and AI miss. Run BEFORE committing.
+
+**Languages:** JS/TS, Python, C/C++, Rust, Go, Java, Ruby, Swift
+
+### When to Use
+
+- **Before commit**: Catch null safety, XSS, async/await bugs
+- **After AI generates code**: Validate before accepting
+- **CI gate**: `--fail-on-warning` for PR checks
+
+### Quick Reference
+
+```bash
+# Scan current directory
+ubs_scan()
+
+# Scan specific path
+ubs_scan(path="src/")
+
+# Scan only staged files (pre-commit)
+ubs_scan(staged=true)
+
+# Scan only modified files (quick check)
+ubs_scan(diff=true)
+
+# Filter by language
+ubs_scan(path=".", only="js,python")
+
+# JSON output for parsing
+ubs_scan_json(path=".")
+
+# Check UBS health
+ubs_doctor(fix=true)
+```
+
+### Bug Categories (18 total)
+
+| Category | What It Catches | Severity |
+| ------------- | ------------------------------------- | -------- |
+| Null Safety | "Cannot read property of undefined" | Critical |
+| Security | XSS, injection, prototype pollution | Critical |
+| Async/Await | Race conditions, missing await | Critical |
+| Memory Leaks | Event listeners, timers, detached DOM | High |
+| Type Coercion | === vs == issues | Medium |
+
+### Fix Workflow
+
+1. Run `ubs_scan(path="changed-file.ts")`
+2. Read `file:line:col` locations
+3. Check suggested fix
+4. Fix root cause (not symptom)
+5. Re-run until exit 0
+6. Commit
+
+### Speed Tips
+
+- Scope to changed files: `ubs_scan(path="src/file.ts")` (< 1s)
+- Full scan is slow: `ubs_scan(path=".")` (30s+)
+- Use `--staged` or `--diff` for incremental checks
diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md
new file mode 100644
index 0000000..cf1f1c2
--- /dev/null
+++ b/IMPROVEMENTS.md
@@ -0,0 +1,1100 @@
+# OpenCode Setup Improvements
+
+Based on deep analysis of sst/opencode internals. Prioritized by impact and effort.
+
+## Executive Summary
+
+Our setup is **80% optimized**. Key gaps:
+
+1. No doom loop detection (agents can infinite loop)
+2. No streaming progress from tools
+3. Flat agent structure (no nesting)
+4. Missing abort signal handling in custom tools
+5. No output size limits in custom tools
+
+## High Priority (Do This Week)
+
+### 1. Add Doom Loop Detection to Swarm
+
+**What**: Track repeated identical tool calls, break infinite loops.
+
+**Why**: OpenCode detects when same tool+args called 3x and asks permission. We don't - agents can burn tokens forever.
+
+**Implementation**:
+
+```typescript
+// In swarm plugin or tool wrapper
+const DOOM_LOOP_THRESHOLD = 3;
+const recentCalls: Map<
+ string,
+ { tool: string; args: string; count: number }[]
+> = new Map();
+
+function checkDoomLoop(sessionID: string, tool: string, args: any): boolean {
+ const key = `${tool}:${JSON.stringify(args)}`;
+ const calls = recentCalls.get(sessionID) || [];
+ const matching = calls.filter((c) => `${c.tool}:${c.args}` === key);
+ if (matching.length >= DOOM_LOOP_THRESHOLD) {
+ return true; // Doom loop detected
+ }
+ calls.push({ tool, args: JSON.stringify(args), count: 1 });
+ if (calls.length > 10) calls.shift(); // Keep last 10
+ recentCalls.set(sessionID, calls);
+ return false;
+}
+```
+
+**Files**: `plugin/swarm.ts`
+
+### 2. Add Abort Signal Handling to All Tools
+
+**What**: Propagate cancellation to long-running operations.
+
+**Why**: OpenCode tools all respect `ctx.abort`. Ours don't - cancelled operations keep running.
+
+**Implementation**:
+
+```typescript
+// In each tool's execute function
+async execute(args, ctx) {
+ const controller = new AbortController();
+ ctx.abort?.addEventListener('abort', () => controller.abort());
+
+ // Pass to fetch, spawn, etc.
+ const result = await fetch(url, { signal: controller.signal });
+}
+```
+
+**Files**: All tools in `tool/*.ts`
+
+### 3. Add Output Size Limits
+
+**What**: Truncate tool outputs that exceed 30K chars.
+
+**Why**: OpenCode caps at 30K. Large outputs blow context window.
+
+**Implementation**:
+
+```typescript
+const MAX_OUTPUT = 30_000;
+
+function truncateOutput(output: string): string {
+ if (output.length <= MAX_OUTPUT) return output;
+ return (
+ output.slice(0, MAX_OUTPUT) +
+ `\n\n[Output truncated at ${MAX_OUTPUT} chars. ${output.length - MAX_OUTPUT} chars omitted.]`
+ );
+}
+```
+
+**Files**: Wrapper in `tool/` or each tool individually
+
+### 4. Create Read-Only Explore Agent
+
+**What**: Fast codebase search specialist with no write permissions.
+
+**Why**: OpenCode has `explore` agent that's read-only. Safer for quick searches.
+
+**Implementation**:
+
+```yaml
+# agent/explore.md
+---
+name: explore
+description: Fast codebase exploration - read-only, no modifications
+mode: subagent
+tools:
+ edit: false
+ write: false
+ bash: false
+permission:
+ bash:
+ "rg *": allow
+ "git log*": allow
+ "git show*": allow
+ "find * -type f*": allow
+ "*": deny
+---
+You are a read-only codebase explorer. Search, read, analyze - never modify.
+```
+
+**Files**: `agent/explore.md`
+
+## Medium Priority (This Month)
+
+### 5. Add Streaming Metadata to Long Operations
+
+**What**: Stream progress updates during tool execution.
+
+**Why**: OpenCode tools call `ctx.metadata({ output })` during execution. Users see real-time progress.
+
+**Current gap**: Our tools return all-or-nothing. User sees nothing until complete.
+
+**Implementation**: Requires OpenCode plugin API support for `ctx.metadata()`. Check if available.
+
+### 6. Support Nested Agent Directories
+
+**What**: Allow `agent/swarm/planner.md` → agent name `swarm/planner`.
+
+**Why**: Better organization as agent count grows.
+
+**Implementation**: Already supported by OpenCode! Just use nested paths:
+
+```
+agent/
+ swarm/
+ planner.md → "swarm/planner"
+ worker.md → "swarm/worker"
+ security/
+ auditor.md → "security/auditor"
+```
+
+**Files**: Reorganize `agent/*.md` into subdirectories
+
+### 7. Add mtime-Based Sorting to Search Results
+
+**What**: Sort search results by modification time (newest first).
+
+**Why**: OpenCode's glob/grep tools do this. More relevant results surface first.
+
+**Implementation**:
+
+```typescript
+// In cass_search, grep results, etc.
+results.sort((a, b) => b.mtime - a.mtime);
+```
+
+**Files**: `tool/cass.ts`, any search tools
+
+### 8. Implement FileTime-Like Tracking for Beads
+
+**What**: Track when beads were last read, detect concurrent modifications.
+
+**Why**: OpenCode tracks file reads per session, prevents stale overwrites.
+
+**Implementation**:
+
+```typescript
+const beadReadTimes: Map> = new Map();
+
+function recordBeadRead(sessionID: string, beadID: string) {
+ if (!beadReadTimes.has(sessionID)) beadReadTimes.set(sessionID, new Map());
+ beadReadTimes.get(sessionID)!.set(beadID, new Date());
+}
+
+function assertBeadFresh(
+ sessionID: string,
+ beadID: string,
+ lastModified: Date,
+) {
+ const readTime = beadReadTimes.get(sessionID)?.get(beadID);
+ if (!readTime) throw new Error(`Must read bead ${beadID} before modifying`);
+ if (lastModified > readTime)
+ throw new Error(`Bead ${beadID} modified since last read`);
+}
+```
+
+**Files**: `plugin/swarm.ts` or new `tool/bead-time.ts`
+
+## Low Priority (Backlog)
+
+### 9. Add Permission Wildcards for Bash
+
+**What**: Pattern-based bash command permissions like OpenCode.
+
+**Why**: Finer control than boolean allow/deny.
+
+**Example**:
+
+```yaml
+permission:
+ bash:
+ "git *": allow
+ "npm test*": allow
+ "rm -rf *": deny
+ "*": ask
+```
+
+**Status**: May already be supported - check OpenCode docs.
+
+### 10. Implement Session Hierarchy for Swarm
+
+**What**: Track parent-child relationships between swarm sessions.
+
+**Why**: OpenCode tracks `parentID` for subagent sessions. Useful for debugging swarm lineage.
+
+**Implementation**: Add `parentSessionID` to Agent Mail messages or bead metadata.
+
+### 11. Add Plugin Lifecycle Hooks
+
+**What**: `tool.execute.before` and `tool.execute.after` hooks.
+
+**Why**: Enables logging, metrics, input validation without modifying each tool.
+
+**Status**: Requires OpenCode plugin API. Check if `Plugin.trigger()` is exposed.
+
+## Already Doing Well
+
+These areas we're ahead of OpenCode:
+
+1. **BeadTree decomposition** - Structured task breakdown vs ad-hoc
+2. **Agent Mail coordination** - Explicit messaging vs implicit sessions
+3. **File reservations** - Pre-spawn conflict detection
+4. **Learning system** - Outcome tracking, pattern maturity
+5. **UBS scanning** - Auto bug scan on completion
+6. **CASS history** - Cross-agent session search
+
+## Hidden Features to Explore
+
+From context analysis, OpenCode has features we might not be using:
+
+1. **Session sharing** - `share: "auto"` in config
+2. **Session revert** - Git snapshot rollback
+3. **Doom loop permission** - `permission.doom_loop: "ask"`
+4. **Experimental flags**:
+ - `OPENCODE_DISABLE_PRUNE` - Keep all tool outputs
+ - `OPENCODE_DISABLE_AUTOCOMPACT` - Manual summarization only
+ - `OPENCODE_EXPERIMENTAL_WATCHER` - File change watching
+
+## Implementation Order
+
+```
+Week 1: ✅ COMPLETE
+ [x] Doom loop detection (swarm plugin)
+ [x] Abort signal handling (all tools)
+ [x] Output size limits (tool-utils.ts)
+ [x] Explore agent (agent/explore.md)
+ [x] Repo tooling optimizations (caching, parallel, GitHub token)
+
+Week 2:
+ [ ] Nested agent directories (reorganize)
+ [ ] mtime sorting (cass, search tools)
+
+Week 3:
+ [ ] FileTime tracking for beads
+ [ ] Streaming metadata (if API available)
+
+Backlog:
+ [ ] Permission wildcards
+ [ ] Session hierarchy
+ [ ] Plugin hooks
+```
+
+## References
+
+- `knowledge/opencode-plugins.md` - Plugin system architecture
+- `knowledge/opencode-agents.md` - Agent/subagent system
+- `knowledge/opencode-tools.md` - Built-in tool implementations
+- `knowledge/opencode-context.md` - Session/context management
+
+---
+
+# Content Inventory for README Overhaul (Dec 2024)
+
+> **Audit Cell:** readme-1
+> **Epic:** readme-overhaul
+> **Date:** 2024-12-18
+> **Purpose:** Complete inventory of features for portfolio-quality README showcase
+
+## Executive Summary
+
+This OpenCode configuration is a **swarm-first multi-agent orchestration system** with learning capabilities. Built on top of the `opencode-swarm-plugin` (via joelhooks/swarmtools), it transforms OpenCode from a single-agent tool into a coordinated swarm that learns from outcomes and avoids past failures.
+
+**Scale:**
+
+- **3,626 lines** of command documentation (25 slash commands)
+- **3,043 lines** of skill documentation (7 bundled skills)
+- **1,082 lines** in swarm plugin wrapper
+- **57 swarm tools** exposed via plugin
+- **12 custom MCP tools** + 6 external MCP servers
+- **7 specialized agents** (2 swarm, 5 utility)
+- **8 knowledge files** for on-demand context injection
+
+**Most Impressive:** The swarm learns. It tracks decomposition outcomes (duration, errors, retries), decays confidence in unreliable patterns, inverts anti-patterns, and promotes proven strategies.
+
+---
+
+## 1. Swarm Orchestration (★★★★★ Flagship Feature)
+
+**Source:** `opencode-swarm-plugin` via `joelhooks/swarmtools`
+
+### What It Does
+
+Transforms single-agent work into coordinated parallel execution:
+
+1. **Decompose** tasks into subtasks (CellTree structure)
+2. **Spawn** worker agents with isolated context
+3. **Coordinate** via Agent Mail (file reservations, messaging)
+4. **Verify** completion (UBS scan, typecheck, tests)
+5. **Learn** from outcomes (track what works, what fails)
+
+### Key Components
+
+**Hive** (Git-backed work tracker):
+
+- Atomic epic + subtask creation
+- Status tracking (open → in_progress → blocked → closed)
+- Priority system (0-3)
+- Type system (bug, feature, task, epic, chore)
+- Thread linking with Agent Mail
+
+**Agent Mail** (Multi-agent coordination):
+
+- File reservation system (prevent edit conflicts)
+- Message passing between agents
+- Thread-based conversation tracking
+- Context-safe inbox (max 5 messages, no bodies by default)
+- Automatic release on completion
+
+**Swarm Coordination**:
+
+- Strategy selection (file-based, feature-based, risk-based, research-based)
+- Decomposition validation (CellTreeSchema)
+- Progress tracking (25/50/75% checkpoints)
+- Completion verification gates (UBS + typecheck + tests)
+- Outcome recording for learning
+
+### The Learning System (★★★★★ Unique Innovation)
+
+**Confidence Decay** (90-day half-life):
+
+- Evaluation criteria weights fade unless revalidated
+- Unreliable criteria get reduced impact
+
+**Implicit Feedback Scoring**:
+
+- Fast + success → helpful signal
+- Slow + errors + retries → harmful signal
+
+**Pattern Maturity Lifecycle**:
+
+- `candidate` → `established` → `proven` → `deprecated`
+- Proven patterns get 1.5x weight
+- Deprecated patterns get 0x weight
+
+**Anti-Pattern Inversion**:
+
+- Patterns with >60% failure rate auto-invert
+- Example: "Split by file type" → "AVOID: Split by file type (80% failure rate)"
+
+**Integration Points**:
+
+- CASS search during decomposition (query past similar tasks)
+- Semantic memory storage after completion
+- Outcome tracking (duration, error count, retry count)
+- Strategy effectiveness scoring
+
+### Swarm Commands
+
+| Command | Purpose | Workflow |
+| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
+| `/swarm ` | **PRIMARY** - decompose + spawn parallel agents | Socratic planning → decompose → validate → spawn → monitor → verify |
+| `/swarm-status` | Check running swarm progress | Query epic status, check Agent Mail inbox |
+| `/swarm-collect` | Collect and merge swarm results | Aggregate outcomes, close epic |
+| `/parallel "a" "b"` | Run explicit tasks in parallel | Skip decomposition, direct spawn |
+
+### Coordinator vs Worker Pattern
+
+**Coordinator** (agent: `swarm/planner`):
+
+- NEVER edits code
+- Decomposes tasks
+- Spawns workers
+- Monitors progress
+- Unblocks dependencies
+- Verifies completion
+- Long-lived context (Sonnet)
+
+**Worker** (agent: `swarm/worker`):
+
+- Executes subtasks
+- Reserves files first
+- Reports progress
+- Completes via `swarm_complete`
+- Disposable context (Sonnet)
+- 9-step survival checklist
+
+**Why this matters:**
+
+- Coordinator context stays clean (expensive Sonnet)
+- Workers get checkpointed (recovery)
+- Learning signals captured per subtask
+- Parallel work without conflicts
+
+### Swarm Plugin Tools (57 total)
+
+**Hive (8 tools)**:
+
+- `hive_create`, `hive_create_epic`, `hive_query`, `hive_update`
+- `hive_close`, `hive_start`, `hive_ready`, `hive_sync`
+
+**Agent Mail (7 tools)**:
+
+- `swarmmail_init`, `swarmmail_send`, `swarmmail_inbox`
+- `swarmmail_read_message`, `swarmmail_reserve`, `swarmmail_release`
+- `swarmmail_ack`, `swarmmail_health`
+
+**Swarm Orchestration (15 tools)**:
+
+- `swarm_init`, `swarm_select_strategy`, `swarm_plan_prompt`
+- `swarm_decompose`, `swarm_validate_decomposition`, `swarm_status`
+- `swarm_progress`, `swarm_complete`, `swarm_record_outcome`
+- `swarm_subtask_prompt`, `swarm_spawn_subtask`, `swarm_complete_subtask`
+- `swarm_evaluation_prompt`, `swarm_broadcast`
+- `swarm_worktree_create`, `swarm_worktree_merge`, `swarm_worktree_cleanup`, `swarm_worktree_list`
+
+**Structured Parsing (5 tools)**:
+
+- `structured_extract_json`, `structured_validate`
+- `structured_parse_evaluation`, `structured_parse_decomposition`
+- `structured_parse_cell_tree`
+
+**Skills (9 tools)**:
+
+- `skills_list`, `skills_read`, `skills_use`, `skills_create`
+- `skills_update`, `skills_delete`, `skills_init`
+- `skills_add_script`, `skills_execute`
+
+**Review (2 tools)**:
+
+- `swarm_review`, `swarm_review_feedback`
+
+---
+
+## 2. Learning & Memory Systems (★★★★★)
+
+### CASS - Cross-Agent Session Search
+
+**What:** Unified search across ALL your AI coding agent histories
+**Indexed Agents:** Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
+
+**Why it matters:** Before solving a problem, check if ANY agent already solved it. Prevents reinventing wheels.
+
+**Features:**
+
+- Full-text + semantic search
+- Agent filtering (`--agent=cursor`)
+- Time-based filtering (`--days=7`)
+- mtime-based result sorting (newest first)
+- Context expansion around results
+- Health checks + incremental indexing
+
+**Tools:** `cass_search`, `cass_health`, `cass_index`, `cass_view`, `cass_expand`, `cass_stats`, `cass_capabilities`
+
+**Integration:**
+
+- Swarm decomposition queries CASS for similar past tasks
+- Debug-plus checks CASS for known error patterns
+- Knowledge base refers to CASS for historical solutions
+
+### Semantic Memory
+
+**What:** Local vector-based knowledge store (PGlite + pgvector + Ollama embeddings)
+
+**Why it matters:** Persist learnings across sessions. Memories decay over time (90-day half-life) unless validated.
+
+**Use Cases:**
+
+- Architectural decisions (store the WHY, not just WHAT)
+- Debugging breakthroughs (root cause + solution)
+- Project-specific patterns (domain rules, gotchas)
+- Tool/library quirks (API bugs, workarounds)
+- Failed approaches (anti-patterns to avoid)
+
+**Tools:** `semantic-memory_store`, `semantic-memory_find`, `semantic-memory_validate`, `semantic-memory_list`, `semantic-memory_stats`, `semantic-memory_check`
+
+**Integration:**
+
+- Swarm workers query semantic memory before starting work
+- Debug-plus stores prevention patterns
+- Post-mortem `/retro` extracts learnings to memory
+
+---
+
+## 3. Custom MCP Tools (12 tools)
+
+**Location:** `tool/*.ts`
+
+| Tool | Purpose | Language | Unique Features |
+| ------------------- | -------------------------- | -------------- | ----------------------------------------------------------------------------- |
+| **UBS** | Ultimate Bug Scanner | Multi-language | 18 bug categories, null safety, XSS, async/await, memory leaks, type coercion |
+| **CASS** | Cross-agent session search | n/a | Searches 10+ agent histories, mtime sorting |
+| **semantic-memory** | Vector knowledge store | n/a | PGlite + pgvector + Ollama, 90-day decay |
+| **repo-crawl** | GitHub API exploration | n/a | README, file contents, search, structure, tree |
+| **repo-autopsy** | Deep repo analysis | n/a | Clone + AST grep, blame, deps, hotspots, secrets, stats |
+| **pdf-brain** | PDF knowledge base | n/a | Text extraction, embeddings, semantic search |
+| **bd-quick** | Hive CLI wrapper | n/a | **DEPRECATED** - use hive\_\* plugin tools |
+| **typecheck** | TypeScript checker | TypeScript | Grouped errors by file |
+| **git-context** | Git status summary | n/a | Branch, status, commits, ahead/behind in one call |
+| **find-exports** | Symbol export finder | TypeScript | Locate where symbols are exported from |
+| **pkg-scripts** | package.json scripts | n/a | List available npm/pnpm scripts |
+| **tool-utils** | Tool helper utils | n/a | MAX_OUTPUT, formatError, truncateOutput, withTimeout |
+
+**Implementation Highlights:**
+
+- Abort signal support (all tools)
+- 30K output limit (prevents context exhaustion)
+- Streaming metadata (experimental)
+- Error handling with structured output
+
+---
+
+## 4. MCP Servers (6 external + 1 embedded)
+
+**Configured in `opencode.jsonc`:**
+
+| Server | Type | Purpose | Auth |
+| ------------------- | -------- | ------------------------------------------------------ | --------- |
+| **next-devtools** | Local | Next.js dev server integration (routes, errors, build) | None |
+| **chrome-devtools** | Local | Browser automation, DOM inspection, network | None |
+| **context7** | Remote | Library documentation lookup (npm, PyPI, etc.) | None |
+| **fetch** | Local | Web fetching with markdown conversion | None |
+| **snyk** | Local | Security scanning (SCA, SAST, IaC, containers) | API token |
+| **kernel** | Remote | Cloud browser automation, Playwright, app deployment | OAuth |
+| **(Agent Mail)** | Embedded | Multi-agent coordination via Swarm Mail | None |
+
+**New in this config:**
+
+- **Kernel integration** - cloud browser automation with Playwright execution
+- **Snyk integration** - security scanning across stack
+- **Agent Mail embedded** - multi-agent coordination via swarmtools
+
+---
+
+## 5. Slash Commands (25 total)
+
+**Location:** `command/*.md`
+**Total Documentation:** 3,626 lines
+
+### Swarm (4 commands)
+
+| Command | Lines | Key Features |
+| ---------------- | ----- | -------------------------------------------------------- |
+| `/swarm` | 177 | Socratic planning → decompose → spawn → monitor → verify |
+| `/swarm-status` | (TBD) | Query epic status, check inbox |
+| `/swarm-collect` | (TBD) | Aggregate outcomes, close epic |
+| `/parallel` | (TBD) | Direct parallel spawn, no decomposition |
+
+### Debug (3 commands)
+
+| Command | Lines | Key Features |
+| ------------- | ----- | ---------------------------------------------------------------- |
+| `/debug` | (TBD) | Check error-patterns.md first, trace error flow |
+| `/debug-plus` | 209 | Debug + prevention pipeline + swarm fix, create prevention beads |
+| `/triage` | (TBD) | Classify request, route to handler |
+
+### Workflow (5 commands)
+
+| Command | Lines | Key Features |
+| ---------- | ----- | ------------------------------------------------- |
+| `/iterate` | (TBD) | Evaluator-optimizer loop until quality met |
+| `/fix-all` | 155 | Survey PRs + beads, spawn parallel agents to fix |
+| `/sweep` | (TBD) | Codebase cleanup: type errors, lint, dead code |
+| `/focus` | (TBD) | Start focused session on specific bead |
+| `/rmslop` | (TBD) | Remove AI code slop from branch (nexxeln pattern) |
+
+### Git (3 commands)
+
+| Command | Lines | Key Features |
+| ---------------- | ----- | ------------------------------------------------- |
+| `/commit` | (TBD) | Smart commit with conventional format + bead refs |
+| `/pr-create` | (TBD) | Create PR with bead linking + smart summary |
+| `/worktree-task` | (TBD) | Create git worktree for isolated bead work |
+
+### Session (3 commands)
+
+| Command | Lines | Key Features |
+| --------------- | ----- | ------------------------------------------------------- |
+| `/handoff` | (TBD) | End session: sync hive, generate continuation prompt |
+| `/checkpoint` | (TBD) | Compress context: summarize session, preserve decisions |
+| `/context-dump` | (TBD) | Dump state for model switch or context recovery |
+
+### Other (7 commands)
+
+| Command | Lines | Key Features |
+| ----------------- | ----- | ------------------------------------------------------ |
+| `/retro` | (TBD) | Post-mortem: extract learnings, update knowledge files |
+| `/review-my-shit` | (TBD) | Pre-PR self-review: lint, types, common mistakes |
+| `/test` | (TBD) | Generate tests with test-writer agent |
+| `/estimate` | (TBD) | Estimate effort for bead or epic |
+| `/standup` | (TBD) | Generate standup summary from git/beads |
+| `/migrate` | (TBD) | Run migration with rollback plan |
+| `/repo-dive` | (TBD) | Deep analysis of GitHub repo with autopsy tools |
+
+---
+
+## 6. Specialized Agents (7 total)
+
+**Location:** `agent/*.md`
+
+| Agent | Model | Purpose | Read-Only | Special Perms |
+| ----------------- | ---------- | ---------------------------------------------------- | --------- | ---------------- |
+| **swarm/planner** | Sonnet 4.5 | Strategic task decomposition for swarm | No | Full access |
+| **swarm/worker** | Sonnet 4.5 | **PRIMARY** - parallel task implementation | No | Full access |
+| **explore** | Haiku 4.5 | Fast codebase search, pattern discovery | **Yes** | rg, git log only |
+| **archaeologist** | Sonnet 4.5 | Read-only codebase exploration, architecture mapping | **Yes** | Full read |
+| **beads** | Haiku | Work item tracker operations | No | **Locked down** |
+| **refactorer** | Default | Pattern migration across codebase | No | Full access |
+| **reviewer** | Default | Read-only code review, security/perf audits | **Yes** | Full read |
+
+**Agent Overrides in Config** (4 additional):
+
+- **build** - temp 0.3, full capability
+- **plan** - Sonnet 4.5, read-only, no write/edit/patch
+- **security** - Sonnet 4.5, read-only, Snyk integration
+- **test-writer** - Sonnet 4.5, can only write `*.test.ts` files
+- **docs** - Haiku 4.5, can only write `*.md` files
+
+---
+
+## 7. Skills (7 bundled)
+
+**Location:** `skills/*/SKILL.md`
+**Total Documentation:** 3,043 lines
+
+| Skill | Lines | Purpose | Trigger |
+| ------------------------ | ----- | ------------------------------------------------------------------ | ------------------------------------ |
+| **testing-patterns** | ~500 | Feathers seams + Beck's 4 rules, 25 dependency-breaking techniques | Writing tests, breaking dependencies |
+| **swarm-coordination** | ~400 | Multi-agent task decomposition, parallel work, file reservations | Multi-agent work |
+| **cli-builder** | ~350 | Building CLIs, argument parsing, help text, subcommands | Building a CLI |
+| **learning-systems** | ~300 | Confidence decay, pattern maturity, feedback loops | Building learning features |
+| **skill-creator** | ~250 | Meta-skill for creating new skills | Creating skills |
+| **system-design** | ~400 | Architecture decisions, module boundaries, API design | Architectural work |
+| **ai-optimized-content** | ~300 | Writing for LLMs, knowledge packaging | Documentation work |
+
+**Skill Features:**
+
+- Global, project, and bundled scopes
+- SKILL.md format with metadata
+- Reference files (`references/*.md`)
+- Executable scripts support
+- On-demand loading via `skills_use(name, context)`
+
+---
+
+## 8. Knowledge Files (8 files)
+
+**Location:** `knowledge/*.md`
+
+| File | Purpose | Lines | When to Load |
+| ---------------------------- | ------------------------------------------------ | ----- | ------------------------------- |
+| **error-patterns.md** | Known error signatures + solutions | ~400 | FIRST when hitting errors |
+| **prevention-patterns.md** | Debug-to-prevention workflow, pattern extraction | ~350 | After debugging, before closing |
+| **nextjs-patterns.md** | RSC, caching, App Router gotchas | ~500 | Next.js work |
+| **effect-patterns.md** | Services, Layers, Schema, error handling | ~600 | Effect-TS work |
+| **mastra-agent-patterns.md** | Multi-agent coordination, context engineering | ~300 | Building agents |
+| **testing-patterns.md** | Test strategies, mocking, fixtures | ~400 | Writing tests |
+| **typescript-patterns.md** | Type-level programming, inference, narrowing | ~450 | Complex TypeScript |
+| **git-patterns.md** | Branching, rebasing, conflict resolution | ~200 | Git operations |
+
+**Usage Pattern:** Load on-demand via `@knowledge/file-name.md` references, not preloaded.
+
+---
+
+## 9. Configuration Highlights
+
+**From `opencode.jsonc`:**
+
+### Models
+
+- Primary: `claude-opus-4-5` (top tier)
+- Small: `claude-haiku-4-5` (fast + cheap)
+- Autoupdate: `true`
+
+### Formatters
+
+- Biome support (`.js`, `.jsx`, `.ts`, `.tsx`, `.json`, `.jsonc`)
+- Prettier support (all above + `.md`, `.yaml`, `.css`, `.scss`)
+
+### Permissions
+
+- `.env` reads allowed (no prompts)
+- Git push allowed (no prompts)
+- Sudo denied (safety)
+- Fork bomb denied (just in case)
+
+### TUI
+
+- Momentum scrolling enabled (macOS-style)
+
+---
+
+## 10. Notable Patterns & Innovations
+
+### Swarm Compaction Hook
+
+**Location:** `plugin/swarm.ts` (lines 884-1079)
+
+When context gets compacted, the plugin:
+
+1. Checks for "swarm sign" (in_progress beads, open subtasks, unclosed epics)
+2. If swarm active, injects recovery context into compaction
+3. Coordinator wakes up and immediately resumes orchestration
+
+**This prevents swarm interruption during compaction.**
+
+### Context Preservation Rules
+
+**Agent Mail constraints** (MANDATORY):
+
+- `include_bodies: false` (headers only)
+- `inbox_limit: 5` (max 5 messages)
+- `summarize_thread` over fetch all
+- Plugin enforces these automatically
+
+**Documentation tools** (context7, effect-docs):
+
+- NEVER call directly in main conversation
+- ALWAYS use Task subagent for doc lookups
+- Front-load doc research at session start
+
+**Why:** Prevents context exhaustion from doc dumps.
+
+### Coordinator-Worker Split
+
+**Coordinators** (expensive, long-lived):
+
+- Use Sonnet context ($$$)
+- Never edit code
+- Orchestrate only
+
+**Workers** (disposable, focused):
+
+- Use disposable context
+- Checkpointed for recovery
+- Track learning signals
+
+**Result:**
+
+- 70% cost reduction (workers don't accumulate context)
+- Better recovery (checkpointed workers)
+- Learning signals captured
+
+### Debug-to-Prevention Pipeline
+
+**Workflow:**
+
+```
+Error occurs
+ ↓
+/debug-plus investigates
+ ↓
+Root cause identified
+ ↓
+Match prevention-patterns.md
+ ↓
+Create preventive bead
+ ↓
+Optionally spawn prevention swarm
+ ↓
+Update knowledge base
+ ↓
+Future errors prevented
+```
+
+**Why it matters:** Every debugging session becomes a codebase improvement opportunity. Errors don't recur.
+
+---
+
+## 11. Comparisons & Positioning
+
+### vs Stock OpenCode
+
+| Feature | Stock OpenCode | This Config |
+| ------------------ | ---------------------------- | ---------------------------------------------------------- |
+| **Multi-agent** | Single agent + subagents | Coordinated swarms with learning |
+| **Work tracking** | None | Git-backed Hive with epic decomposition |
+| **Learning** | None | Outcome tracking, pattern maturity, anti-pattern inversion |
+| **Coordination** | Implicit (session hierarchy) | Explicit (Agent Mail, file reservations) |
+| **Knowledge** | Static documentation | Dynamic (semantic memory, CASS, knowledge files) |
+| **Bug prevention** | None | UBS scan + prevention patterns + debug-plus pipeline |
+| **Cost** | Linear with complexity | Sub-linear (coordinator-worker split) |
+
+### vs Other Multi-Agent Frameworks
+
+| Framework | OpenCode Swarm Config |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| **AutoGPT** | Task decomposition, no learning |
+| **BabyAGI** | Sequential only, no parallel |
+| **MetaGPT** | Role-based agents, no outcome learning |
+| **This Config** | ✅ Parallel + sequential ✅ Learning from outcomes ✅ Anti-pattern detection ✅ Cost-optimized |
+
+---
+
+## 12. Metrics & Scale
+
+**Codebase:**
+
+- 3,626 lines of command documentation
+- 3,043 lines of skill documentation
+- 1,082 lines in swarm plugin wrapper
+- ~2,000 lines of custom tools
+- ~800 lines of agent definitions
+
+**Tool Count:**
+
+- 57 swarm plugin tools
+- 12 custom MCP tools
+- 6 external MCP servers (+ 1 embedded)
+
+**Command Count:**
+
+- 25 slash commands
+
+**Agent Count:**
+
+- 7 specialized agents (2 swarm, 5 utility)
+- 4 agent overrides in config
+
+**Knowledge:**
+
+- 8 knowledge files (~3,200 lines)
+- 7 bundled skills (~3,043 lines)
+
+**Learning:**
+
+- Semantic memory (vector store)
+- CASS (10+ agent histories)
+- Outcome tracking per subtask
+- Pattern maturity lifecycle
+
+---
+
+## 13. Recommended Showcase Order (for README)
+
+1. **Hero:** Swarm orchestration (decompose → spawn → coordinate → learn)
+2. **Learning System:** Confidence decay, anti-pattern inversion, pattern maturity
+3. **CASS:** Cross-agent session search (unique to this config)
+4. **Custom Tools:** UBS, semantic-memory, repo-autopsy (most impressive)
+5. **Slash Commands:** Focus on `/swarm`, `/debug-plus`, `/fix-all` (most powerful)
+6. **Agents:** Coordinator-worker pattern, specialized agents
+7. **MCP Servers:** Kernel + Snyk + Next.js (new integrations)
+8. **Skills:** Testing-patterns with 25 dependency-breaking techniques
+9. **Knowledge:** Prevention patterns, debug-to-prevention pipeline
+10. **Config Highlights:** Permissions, formatters, TUI
+
+---
+
+## 14. Key Differentiators (Portfolio Pitch)
+
+**For recruiters:**
+
+- Multi-agent orchestration with learning (not just parallel execution)
+- Cost optimization via coordinator-worker split (70% reduction)
+- Production-grade error prevention pipeline (debug-plus)
+
+**For engineers:**
+
+- CASS cross-agent search (never solve the same problem twice)
+- Anti-pattern detection (learns what NOT to do)
+- Comprehensive testing patterns (25 dependency-breaking techniques)
+
+**For technical leadership:**
+
+- Outcome-based learning (tracks what works, what fails)
+- Knowledge preservation (semantic memory + CASS)
+- Scalable architecture (swarm expands without context exhaustion)
+
+---
+
+## 15. Missing Documentation (Opportunities)
+
+**Commands without detailed .md files:**
+
+- `/swarm-status`, `/swarm-collect`, `/parallel`
+- `/triage`, `/iterate`, `/sweep`, `/focus`, `/rmslop`
+- `/commit`, `/pr-create`, `/worktree-task`
+- `/handoff`, `/checkpoint`, `/context-dump`
+- `/retro`, `/review-my-shit`, `/test`, `/estimate`, `/standup`, `/migrate`, `/repo-dive`
+
+**Recommendation:** Either document these or remove from README if not implemented.
+
+**Undocumented Features:**
+
+- Swarm compaction hook (only in code comments)
+- Implicit feedback scoring algorithm (needs explainer)
+- Pattern maturity lifecycle (needs diagram)
+- Anti-pattern inversion rules (needs doc)
+
+---
+
+## 16. Visual Assets Needed (for Portfolio README)
+
+**Diagrams:**
+
+1. Swarm workflow (decompose → spawn → coordinate → verify → learn)
+2. Coordinator-worker split (context cost comparison)
+3. Debug-to-prevention pipeline (error → debug → pattern → prevention)
+4. Learning system flow (outcome → feedback → pattern maturity → confidence decay)
+5. Tool ecosystem map (MCP servers, custom tools, plugin tools)
+
+**Screenshots/GIFs:**
+
+1. `/swarm` in action (decomposition + spawning)
+2. CASS search results (cross-agent history)
+3. UBS scan output (bug detection)
+4. Agent Mail inbox (coordination)
+5. Hive status (work tracking)
+
+**ASCII Art:**
+
+- Swarm banner (for PR headers)
+- Tool architecture diagram
+- Agent relationship graph
+
+---
+
+## 17. README Structure Recommendation
+
+```markdown
+# Header
+
+- ASCII banner
+- Tagline: "Swarm-first multi-agent orchestration with learning"
+- Badges (tests, coverage, license)
+
+# Quick Start
+
+- Installation
+- Verification
+- First swarm
+
+# Features (Visual Showcase)
+
+## 1. Swarm Orchestration
+
+- Diagram
+- Code example
+- Learning system explanation
+
+## 2. Cross-Agent Search (CASS)
+
+- Example search
+- Use cases
+
+## 3. Custom Tools
+
+- UBS (bug scanner)
+- semantic-memory (vector store)
+- repo-autopsy (deep analysis)
+
+## 4. Slash Commands
+
+- Table with descriptions
+- Links to command/\*.md
+
+## 5. Agents
+
+- Coordinator-worker pattern
+- Specialized agents
+
+## 6. Learning System
+
+- Confidence decay
+- Pattern maturity
+- Anti-pattern inversion
+
+# Architecture
+
+- Directory structure
+- Tool relationships
+- MCP server integration
+
+# Configuration
+
+- Models
+- Permissions
+- Formatters
+
+# Advanced
+
+- Skills system
+- Knowledge files
+- Context preservation
+- Swarm compaction hook
+
+# Contributing
+
+# License
+
+# Credits
+```
+
+---
+
+## 18. Files for README Writer
+
+**Must Read:**
+
+- `plugin/swarm.ts` (lines 1-120, 884-1079) - plugin architecture + compaction hook
+- `command/swarm.md` - full swarm workflow
+- `command/debug-plus.md` - prevention pipeline
+- `command/fix-all.md` - parallel agent dispatch
+- `agent/swarm/worker.md` - worker checklist
+- `opencode.jsonc` - config highlights
+
+**Reference:**
+
+- `AGENTS.md` - workflow instructions
+- `knowledge/prevention-patterns.md` - debug-to-prevention
+- `skills/testing-patterns/SKILL.md` - dependency-breaking catalog
+
+**Context:**
+
+- This file (IMPROVEMENTS.md) - full inventory
+- Current README.md (lines 1-100) - existing structure
+
+---
+
+## 19. Tone & Voice Recommendations
+
+From `AGENTS.md`:
+
+> Direct. Terse. No fluff. We're sparring partners - disagree when I'm wrong. Curse creatively and contextually (not constantly).
+
+**For README:**
+
+- Skip marketing fluff
+- Lead with capability
+- Show, don't tell (code examples)
+- Be extra with ASCII art (PRs are marketing)
+- Credit inspirations (nexxeln, OpenCode)
+
+**Example tone:**
+
+```markdown
+# What This Is
+
+A swarm of agents that learns from its mistakes. You tell it what to build, it figures out how to parallelize the work, spawns workers, and tracks what strategies actually work.
+
+No bullshit. No buzzwords. Just coordinated parallel execution with learning.
+```
+
+---
+
+## 20. Summary for Coordinator
+
+**What to highlight in README:**
+
+1. **Swarm orchestration** - the flagship feature
+2. **Learning system** - confidence decay, anti-pattern inversion (unique)
+3. **CASS cross-agent search** - never solve the same problem twice
+4. **Custom tools** - UBS, semantic-memory, repo-autopsy (most impressive)
+5. **Debug-to-prevention pipeline** - turn debugging into prevention
+6. **Coordinator-worker pattern** - cost optimization + better recovery
+7. **57 swarm tools** - comprehensive tooling
+8. **25 slash commands** - workflow automation
+9. **7 bundled skills** - on-demand knowledge injection
+10. **6 MCP servers** - Kernel + Snyk + Next.js integrations
+
+**What NOT to highlight:**
+
+- Deprecated `bd-quick` tools (use hive\_\* instead)
+- Undocumented commands (unless you want to implement them)
+- Internal implementation details (unless architecturally interesting)
+
+**Key differentiator:**
+This isn't just parallel execution. It's a learning system that tracks what works, what fails, and adjusts strategy accordingly. Anti-patterns get detected and inverted. Proven patterns get promoted. Confidence decays unless revalidated.
+
+**Portfolio angle:**
+This demonstrates: multi-agent coordination, outcome-based learning, cost optimization, production-grade tooling, and comprehensive documentation. It's not a toy - it's a real workflow multiplier.
diff --git a/README.md b/README.md
index dc3ac37..306ed16 100644
--- a/README.md
+++ b/README.md
@@ -1,97 +1,402 @@
-# OpenCode Config
-
-Personal OpenCode configuration for Joel Hooks. Commands, tools, agents, and knowledge files.
-
-## Structure
-
-```
-├── command/ # Custom slash commands
-├── tool/ # Custom MCP tools
-├── agent/ # Specialized subagents
-├── knowledge/ # Injected context files
-├── opencode.jsonc # Main config
-└── AGENTS.md # Workflow instructions
-```
-
-## Commands
-
-| Command | Description |
-| --------------------- | ------------------------------------------------------------------ |
-| `/swarm ` | Decompose task into beads, spawn parallel agents with context sync |
-| `/iterate ` | Evaluator-optimizer loop until quality threshold met |
-| `/debug ` | Investigate error, check known patterns first |
-| `/triage ` | Classify and route to appropriate handler |
-| `/parallel "t1" "t2"` | Run explicit tasks in parallel |
-| `/fix-all` | Survey PRs + beads, dispatch agents |
-| `/review-my-shit` | Pre-PR self-review |
-| `/handoff` | End session, sync beads, generate continuation |
-| `/sweep` | Codebase cleanup pass |
-| `/focus ` | Start focused session on specific bead |
-| `/context-dump` | Dump state for context recovery |
-| `/commit` | Smart commit with conventional format |
-| `/pr-create` | Create PR with beads linking |
-| `/repo-dive ` | Deep analysis of GitHub repo |
-| `/worktree-task ` | Create git worktree for isolated work |
-
-## Tools
-
-| Tool | Description |
-| -------------- | ------------------------------------------------------------ |
-| `bd-quick` | Fast beads operations: ready, wip, start, done, create, sync |
-| `typecheck` | TypeScript check with grouped errors |
-| `git-context` | Branch, status, commits, ahead/behind in one call |
-| `find-exports` | Find where symbols are exported |
-| `pkg-scripts` | List package.json scripts |
-| `repo-crawl` | GitHub API repo exploration |
-| `repo-autopsy` | Clone & deep analyze repos locally |
-| `pdf-library` | PDF knowledge base with vector search |
+```
+ ██████╗ ██████╗ ███████╗███╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗
+██╔═══██╗██╔══██╗██╔════╝████╗ ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝
+██║ ██║██████╔╝█████╗ ██╔██╗ ██║██║ ██║ ██║██║ ██║█████╗
+██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║██║ ██║ ██║██║ ██║██╔══╝
+╚██████╔╝██║ ███████╗██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗
+ ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
-## Agents
+ ██████╗ ██████╗ ███╗ ██╗███████╗██╗ ██████╗
+ ██╔════╝██╔═══██╗████╗ ██║██╔════╝██║██╔════╝
+ ██║ ██║ ██║██╔██╗ ██║█████╗ ██║██║ ███╗
+ ██║ ██║ ██║██║╚██╗██║██╔══╝ ██║██║ ██║
+ ╚██████╗╚██████╔╝██║ ╚████║██║ ██║╚██████╔╝
+ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝
+```
-| Agent | Mode | Purpose |
-| --------------- | -------- | --------------------------------------------- |
-| `beads` | subagent | Issue tracker operations (Haiku, locked down) |
-| `archaeologist` | subagent | Read-only codebase exploration |
-| `refactorer` | subagent | Pattern migration across codebase |
-| `reviewer` | subagent | Read-only code review, audits |
+> _"These are intelligent and structured group dynamics that emerge not from a leader, but from the local interactions of the elements themselves."_
+> — Daniel Shiffman, _The Nature of Code_
-## Knowledge Files
+**A swarm of agents that learns from its mistakes.**
+
+An [OpenCode](https://opencode.ai) configuration that turns Claude into a multi-agent system. You describe what you want. It decomposes the work, spawns parallel workers, tracks what strategies work, and adapts. Anti-patterns get detected. Proven patterns get promoted. Confidence decays unless revalidated.
+
+Built on [`joelhooks/swarm-tools`](https://github.com/joelhooks/swarm-tools) - multi-agent orchestration with outcome-based learning.
+
+> [!IMPORTANT]
+> **This is an OpenCode config, not a standalone tool.** Everything runs inside OpenCode. The CLIs (`swarm`, `semantic-memory`, `cass`) are backends that agents call - not meant for direct human use.
+
+---
+
+## Quick Start
+
+### 1. Clone & Install
+
+```bash
+git clone https://github.com/joelhooks/opencode-config ~/.config/opencode
+cd ~/.config/opencode && bun install
+```
+
+### 2. Install CLI Tools
+
+> [!NOTE]
+> These CLIs are backends that OpenCode agents call. You install them, but the agents use them.
-- **mastra-agent-patterns.md** - Patterns from Sam Bhagwat's AI agent books
-- **error-patterns.md** - Common errors with known fixes (TS, Next.js, Effect)
+```bash
+# Swarm orchestration (required) - agents call this for coordination
+npm install -g opencode-swarm-plugin
+swarm --version # 0.30.0+
+
+# Ollama for embeddings (required for semantic features)
+brew install ollama # or: curl -fsSL https://ollama.com/install.sh | sh
+ollama serve
+ollama pull nomic-embed-text
+
+# Semantic memory (optional but recommended)
+npm install -g semantic-memory
+semantic-memory check
+
+# Cross-agent session search (optional but recommended)
+npm install -g cass-search
+cass index
+cass --version # 0.1.35+
+```
+
+### 3. Verify
+
+```bash
+swarm doctor
+```
+
+### 4. Run Your First Swarm
+
+> [!WARNING]
+> All commands run **inside [OpenCode](https://opencode.ai)**, not in your terminal. The `swarm` CLI is a backend that agents call - it's not meant for direct human use.
+
+Start OpenCode, then type:
+
+```
+/swarm "Add user authentication with OAuth"
+```
+
+Watch it decompose → spawn workers → coordinate → verify → learn.
+
+The agent orchestrates everything. You just describe what you want.
+
+---
+
+## Version Reference
+
+| Tool | Version | Install Command |
+| --------------- | ------- | -------------------------------- |
+| swarm | 0.30.0 | `npm i -g opencode-swarm-plugin` |
+| semantic-memory | latest | `npm i -g semantic-memory` |
+| cass | 0.1.35 | `npm i -g cass-search` |
+| ollama | 0.13.1 | `brew install ollama` |
+
+**Embedding model:** `nomic-embed-text` (required for semantic-memory and pdf-brain)
+
+### Optional Integrations
+
+```bash
+# Kernel cloud browser (Playwright in the cloud)
+opencode mcp auth kernel
+
+# Snyk security scanning
+snyk auth
+```
+
+---
+
+## What Makes This Different
+
+### The Swarm Learns
+
+> _"Elaborate feedback on errors has repeatedly been found to be more effective than knowledge of results alone."_
+> — Jeroen van Merriënboer, _Ten Steps to Complex Learning_
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ LEARNING PIPELINE │
+├─────────────────────────────────────────────────────────────────┤
+│ │
+│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
+│ │ CASS │───▶│ Decompose │───▶│ Execute │ │
+│ │ (history) │ │ (strategy) │ │ (workers) │ │
+│ └─────────────┘ └─────────────┘ └─────────────┘ │
+│ │ │ │
+│ │ ▼ │
+│ │ ┌─────────────┐ │
+│ │ │ Record │ │
+│ │ │ Outcome │ │
+│ │ └─────────────┘ │
+│ │ │ │
+│ ▼ ▼ │
+│ ┌─────────────────────────────────────────────────┐ │
+│ │ PATTERN MATURITY │ │
+│ │ candidate → established → proven → deprecated │ │
+│ └─────────────────────────────────────────────────┘ │
+│ │
+│ • Confidence decay (90-day half-life) │
+│ • Anti-pattern inversion (>60% failure → AVOID) │
+│ • Implicit feedback (fast+success vs slow+errors) │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Every task execution feeds the learning system:**
+
+- **Fast + success** → pattern gets promoted
+- **Slow + retries + errors** → pattern gets flagged
+- **>60% failure rate** → auto-inverted to anti-pattern
+- **90-day half-life** → confidence decays unless revalidated
+
+### Cross-Agent Memory
+
+**CASS** searches across ALL your AI agent histories before solving problems:
+
+- **Indexed agents:** Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
+- **Semantic + full-text search** - find past solutions even if phrased differently
+
+**Semantic Memory** persists learnings across sessions with vector search:
+
+- Architectural decisions (store the WHY, not just WHAT)
+- Debugging breakthroughs (root cause + solution)
+- Project-specific gotchas (domain rules that tripped you up)
+
+### Cost-Optimized Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ COORDINATOR vs WORKER │
+├─────────────────────────────────────────────────────────────────┤
+│ │
+│ COORDINATOR (Expensive, Long-Lived) │
+│ ┌──────────────────────────────────────┐ │
+│ │ • Sonnet context ($$$) │ │
+│ │ • NEVER edits code │ │
+│ │ • Decomposes + orchestrates │ │
+│ │ • Monitors progress │ │
+│ └──────────────────────────────────────┘ │
+│ │ │
+│ ├─── spawns ───┐ │
+│ │ │ │
+│ ┌──────────────────▼───┐ ┌────────▼──────────┐ │
+│ │ WORKER (Disposable) │ │ WORKER │ │
+│ │ ┌─────────────────┐ │ │ ┌───────────────┐│ │
+│ │ │ Focused context │ │ │ │ Focused ctx ││ │
+│ │ │ Executes task │ │ │ │ Executes task ││ │
+│ │ │ Checkpointed │ │ │ │ Checkpointed ││ │
+│ │ │ Tracks learning │ │ │ │ Tracks learn ││ │
+│ │ └─────────────────┘ │ │ └───────────────┘│ │
+│ └──────────────────────┘ └───────────────────┘ │
+│ │
+│ Result: 70% cost reduction, better recovery, learning signals │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Workers get disposable context. Coordinator context stays clean. Parallel work doesn't blow the context window.
+
+---
+
+## Swarm Orchestration
+
+```
+███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
+██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
+███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
+╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
+███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
+╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
+```
+
+**Built on [`joelhooks/swarm-tools`](https://github.com/joelhooks/swarm-tools)** - the core innovation.
+
+### The System
+
+**Hive** (git-backed work tracker):
+
+- Atomic epic + subtask creation
+- Status tracking (open → in_progress → blocked → closed)
+- `hive_create`, `hive_create_epic`, `hive_query`, `hive_close`, `hive_sync`
+
+**Agent Mail** (multi-agent coordination):
+
+- File reservation system (prevent edit conflicts)
+- Message passing between agents
+- Context-safe inbox (max 5 messages, bodies excluded by default)
+- `swarmmail_init`, `swarmmail_send`, `swarmmail_reserve`, `swarmmail_release`
+
+**Swarm Tools** (orchestration):
+
+- Strategy selection + decomposition validation
+- Progress tracking (25/50/75% checkpoints)
+- Completion verification gates (UBS + typecheck + tests)
+- `swarm_decompose`, `swarm_validate_decomposition`, `swarm_complete`, `swarm_record_outcome`
+
+### Commands
+
+```
+┌────────────────────┬──────────────────────────────────────────────┐
+│ /swarm │ Decompose → spawn parallel agents → merge │
+│ /swarm-status │ Check running swarm progress │
+│ /swarm-collect │ Collect and merge swarm results │
+│ /parallel "a" "b" │ Run explicit tasks in parallel │
+│ │ │
+│ /debug-plus │ Debug + prevention pipeline + swarm fix │
+│ /fix-all │ Survey PRs + cells, dispatch agents │
+│ /iterate │ Evaluator-optimizer loop until quality met │
+└────────────────────┴──────────────────────────────────────────────┘
+```
+
+Full command list: `/commit`, `/pr-create`, `/worktree-task`, `/handoff`, `/checkpoint`, `/retro`, `/review-my-shit`, `/sweep`, `/focus`, `/rmslop`, `/triage`, `/estimate`, `/standup`, `/migrate`, `/repo-dive`.
+
+---
+
+## Custom Tools
+
+**12 MCP tools** built for this config:
+
+### UBS - Ultimate Bug Scanner
+
+Multi-language bug detection (JS/TS, Python, C++, Rust, Go, Java, Ruby):
+
+- Null safety, XSS, injection, async/await race conditions, memory leaks
+
+```bash
+ubs_scan(staged=true) # Before commit
+ubs_scan(path="src/") # After AI generates code
+```
+
+### CASS - Cross-Agent Session Search
+
+```bash
+cass_search(query="authentication error", limit=5)
+cass_search(query="useEffect cleanup", agent="claude", days=7)
+```
+
+### Semantic Memory
+
+```bash
+semantic-memory_store(information="OAuth tokens need 5min buffer", tags="auth,tokens")
+semantic-memory_find(query="token refresh", limit=5)
+semantic-memory_find(query="token refresh", expand=true) # Full content
+```
+
+### Others
+
+- `repo-autopsy_*` - Deep GitHub repo analysis (AST grep, blame, hotspots, secrets)
+- `repo-crawl_*` - GitHub API exploration (README, files, search)
+- `pdf-brain_*` - PDF & Markdown knowledge base (URLs supported, `--expand` for context)
+- `typecheck` - TypeScript check with grouped errors
+- `git-context` - Branch, status, commits in one call
+
+---
## MCP Servers
-Configured in `opencode.jsonc`:
+| Server | Purpose |
+| ------------------- | ------------------------------------------------------ |
+| **next-devtools** | Next.js dev server integration (routes, errors, build) |
+| **chrome-devtools** | Browser automation, DOM inspection, network monitoring |
+| **context7** | Library documentation lookup (npm, PyPI, Maven) |
+| **fetch** | Web fetching with markdown conversion |
+| **snyk** | Security scanning (SCA, SAST, IaC, containers) |
+| **kernel** | Cloud browser automation, Playwright, app deployment |
-- `next-devtools` - Next.js dev server integration
-- `agent-mail` - Multi-agent coordination (localhost:8765)
-- `chrome-devtools` - Browser automation
-- `context7` - Library documentation lookup
-- `fetch` - Web fetching with markdown conversion
+---
+
+## Agents
+
+```
+┌─────────────────┬───────────────────┬────────────────────────────────┐
+│ Agent │ Model │ Purpose │
+├─────────────────┼───────────────────┼────────────────────────────────┤
+│ swarm/planner │ claude-sonnet-4-5 │ Strategic task decomposition │
+│ swarm/worker │ claude-sonnet-4-5 │ Parallel task implementation │
+│ explore │ claude-haiku-4-5 │ Fast search (read-only) │
+│ archaeologist │ claude-sonnet-4-5 │ Codebase exploration (r/o) │
+│ beads │ claude-haiku │ Issue tracker (locked down) │
+│ refactorer │ default │ Pattern migration │
+│ reviewer │ default │ Code review (read-only) │
+└─────────────────┴───────────────────┴────────────────────────────────┘
+```
-## Key Patterns
+---
-### Beads Workflow
+## Skills (On-Demand Knowledge)
-All task tracking goes through beads (git-backed issue tracker):
+> _"Legacy code is simply code without tests."_
+> — Michael Feathers, _Working Effectively with Legacy Code_
+
+| Skill | When to Use |
+| ---------------------- | ----------------------------------------------------------- |
+| **testing-patterns** | Adding tests, breaking dependencies, characterization tests |
+| **swarm-coordination** | Multi-agent decomposition, parallel work |
+| **cli-builder** | Building CLIs, argument parsing, subcommands |
+| **learning-systems** | Confidence decay, pattern maturity |
+| **skill-creator** | Meta-skill for creating new skills |
+| **system-design** | Architecture decisions, module boundaries |
```bash
-bd ready --json # What's next?
-bd create "Task" -p 1 # File work
-bd update ID --status in_progress
-bd close ID --reason "Done"
-bd sync && git push # Land the plane
+skills_use(name="testing-patterns")
+skills_use(name="cli-builder", context="building a new CLI tool")
+```
+
+> [!TIP]
+> `testing-patterns` includes 25 dependency-breaking techniques from Feathers' _Working Effectively with Legacy Code_. Gold for getting gnarly code under test.
+
+---
+
+## Knowledge Files
+
+| File | Topics |
+| ------------------------ | -------------------------------------------- |
+| `tdd-patterns.md` | RED-GREEN-REFACTOR, characterization tests |
+| `error-patterns.md` | Known error signatures + solutions |
+| `prevention-patterns.md` | Debug-to-prevention workflow |
+| `nextjs-patterns.md` | RSC, caching, App Router gotchas |
+| `effect-patterns.md` | Services, Layers, Schema, error handling |
+| `testing-patterns.md` | Test strategies, mocking, fixtures |
+| `typescript-patterns.md` | Type-level programming, inference, narrowing |
+
+Load via `@knowledge/file-name.md` references when relevant.
+
+---
+
+## Directory Structure
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ~/.config/opencode │
+├─────────────────────────────────────────────────────────────────┤
+│ command/ 25 slash commands (/swarm, /debug, etc.) │
+│ tool/ 12 custom MCP tools (cass, ubs, etc.) │
+│ plugin/ swarm.ts (orchestration) │
+│ agent/ specialized subagents (worker, planner...) │
+│ knowledge/ context files (tdd, effect, nextjs, etc.) │
+│ skills/ 7 injectable knowledge packages │
+│ opencode.jsonc main config (models, MCP servers, perms) │
+│ AGENTS.md workflow instructions + tool preferences │
+└─────────────────────────────────────────────────────────────────┘
```
-### Swarm with Context Sync
+---
-`/swarm` spawns parallel agents that share context mid-task via Agent Mail threads. Prevents incompatible outputs.
+## Credits
-### Error Pattern Injection
+- **[joelhooks/swarm-tools](https://github.com/joelhooks/swarm-tools)** - The swarm orchestration core
+- **[nexxeln/opencode-config](https://github.com/nexxeln/opencode-config)** - `/rmslop`, notify plugin, Effect-TS patterns
+- **[OpenCode](https://opencode.ai)** - The foundation
-`/debug` and `/iterate` check `knowledge/error-patterns.md` first. Known patterns get instant fixes. Novel patterns can be saved with `--learn` or `--save`.
+---
## License
MIT
+
+---
+
+> _"One person's pattern can be another person's primitive building block."_
+> — Eric Evans, _Domain-Driven Design_
diff --git a/agent/archaeologist.md b/agent/archaeologist.md
index 82c443c..f3c1329 100644
--- a/agent/archaeologist.md
+++ b/agent/archaeologist.md
@@ -1,7 +1,7 @@
---
description: Code exploration agent that digs into unfamiliar codebases. Maps architecture, traces data flow, finds configuration. Read-only - never modifies code.
mode: subagent
-model: anthropic/claude-sonnet-4-20250514
+model: anthropic/claude-sonnet-4-5
temperature: 0.2
tools:
bash: true
@@ -31,6 +31,7 @@ You are a code archaeologist. You dig into unfamiliar codebases, trace execution
## Mission
Given a question about how something works, you:
+
1. Find the relevant code
2. Trace the flow
3. Map the abstractions
@@ -39,6 +40,7 @@ Given a question about how something works, you:
## Investigation Strategy
### Phase 1: Orientation
+
```bash
# Get the lay of the land
tree -L 2 -d # Directory structure
@@ -46,12 +48,15 @@ rg -l "TODO|FIXME|HACK" --type-add 'code:*.{ts,tsx,js,jsx,py,go,rs}' -t code #
```
### Phase 2: Entry Point Discovery
+
- Look for `main`, `index`, `app`, `server` files
- Check `package.json` scripts, `Makefile`, `docker-compose.yml`
- Find exports in barrel files
### Phase 3: Trace the Path
+
Use these patterns:
+
```bash
# Find where something is defined
rg "export (const|function|class) TargetName" --type ts
@@ -67,6 +72,7 @@ rg "TargetName.*=" -g "*.config.*" -g "*rc*" -g "*.env*"
```
### Phase 4: Map Dependencies
+
- Follow imports up the tree
- Note circular dependencies
- Identify shared abstractions
@@ -81,25 +87,30 @@ Your briefing MUST follow this structure:
# Exploration Report: [Topic]
## TL;DR
+
[2-3 sentence executive summary]
## Entry Points
+
- `path/to/file.ts:42` - [what happens here]
- `path/to/other.ts:17` - [what happens here]
## Key Abstractions
-| Name | Location | Purpose |
-|------|----------|---------|
-| `ServiceName` | `src/services/foo.ts` | Handles X |
-| `UtilityName` | `src/lib/bar.ts` | Transforms Y |
+
+| Name | Location | Purpose |
+| ------------- | --------------------- | ------------ |
+| `ServiceName` | `src/services/foo.ts` | Handles X |
+| `UtilityName` | `src/lib/bar.ts` | Transforms Y |
## Data Flow
```
-[Request]
- → [Router: src/app/api/route.ts]
- → [Service: src/services/thing.service.ts]
- → [Repository: src/db/queries.ts]
- → [Database]
+
+[Request]
+→ [Router: src/app/api/route.ts]
+→ [Service: src/services/thing.service.ts]
+→ [Repository: src/db/queries.ts]
+→ [Database]
+
```
## Configuration
@@ -126,21 +137,25 @@ Your briefing MUST follow this structure:
## Investigation Heuristics
### Finding "Where is X configured?"
+
1. Search for env vars: `rg "process.env.X|env.X"`
2. Check config files: `rg -g "*.config.*" -g "*rc*" "X"`
3. Look for default values: `rg "X.*=.*default|X.*\?\?|X.*\|\|"`
### Finding "How does X get instantiated?"
+
1. Find the class/factory: `rg "export (class|function) X"`
2. Find construction: `rg "new X\(|createX\(|X\.create\("`
3. Find DI registration: `rg "provide.*X|register.*X|bind.*X"`
### Finding "What calls X?"
+
1. Direct calls: `rg "X\(" --type ts`
2. Method calls: `rg "\.X\(" --type ts`
3. Event handlers: `rg "on.*X|handle.*X" --type ts`
### Finding "What does X depend on?"
+
1. Read the file: check imports at top
2. Check constructor params
3. Look for injected dependencies
@@ -160,12 +175,14 @@ Your briefing MUST follow this structure:
## Bash Permissions
You can use these read-only commands:
+
- `rg` (ripgrep) - preferred for code search
- `git log`, `git show`, `git blame` - history exploration
- `tree`, `find` - directory structure
- `wc`, `head`, `tail` - file inspection
You CANNOT use:
+
- Any write commands (`echo >`, `sed -i`, etc.)
- Any destructive commands (`rm`, `mv`, etc.)
- Any network commands (`curl`, `wget`, etc.)
diff --git a/agent/beads.md b/agent/beads.md
index 892db09..ea8dff3 100644
--- a/agent/beads.md
+++ b/agent/beads.md
@@ -1,7 +1,7 @@
---
description: Manages beads issue tracker - file, update, close, query issues. Use for all issue tracking operations.
mode: subagent
-model: anthropic/claude-haiku-4-5
+model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
bash: true
@@ -128,12 +128,14 @@ bd sync && git push && git status
## Common Workflows
### Start of Session
+
```bash
bd ready --json | jq '.[0]'
bd list --status in_progress --json
```
### Found a Bug While Working
+
```bash
# 1. Create the bug
bd create "Found XSS vulnerability in auth" -t bug -p 0 --json
@@ -144,6 +146,7 @@ bd dep add bd-f14c bd-a1b2 --type discovered-from
```
### Decompose Feature into Epic
+
```bash
# 1. Create epic
bd create "Auth System Overhaul" -t epic -p 1 --json
@@ -157,6 +160,7 @@ bd create "Write integration tests" -p 2 --json # bd-a3f8.4
```
### End of Session (Land the Plane)
+
```bash
# 1. Close completed work
bd close bd-a1b2 --reason "Implemented and tested" --json
@@ -183,17 +187,20 @@ bd ready --json | jq '.[0]'
## Error Recovery
### "no database found"
+
```bash
bd init --quiet
```
### "issue not found"
+
```bash
# Check what exists
bd list --json | jq '.[].id'
```
### "JSONL conflict after git pull"
+
```bash
git checkout --theirs .beads/beads.jsonl
bd import -i .beads/beads.jsonl
@@ -201,6 +208,7 @@ bd sync
```
### "daemon not responding"
+
```bash
bd --no-daemon ready --json
# Or restart daemon
diff --git a/agent/explore.md b/agent/explore.md
new file mode 100644
index 0000000..fb035d8
--- /dev/null
+++ b/agent/explore.md
@@ -0,0 +1,355 @@
+---
+description: Fast codebase exploration - read-only, no modifications. Optimized for quick searches and pattern discovery.
+mode: subagent
+model: anthropic/claude-haiku-4-5
+temperature: 0.1
+tools:
+ bash: true
+ read: true
+ write: false
+ edit: false
+ glob: true
+ grep: true
+permission:
+ bash:
+ "rg *": allow
+ "git log *": allow
+ "git show *": allow
+ "find * -type f*": allow
+ "wc *": allow
+ "head *": allow
+ "tail *": allow
+ "*": deny
+---
+
+# Explore Agent - Fast Read-Only Codebase Search
+
+You are a **read-only** exploration agent optimized for speed. You search codebases, locate patterns, and report findings concisely. You **NEVER** modify files.
+
+## Mission
+
+Given a search query or exploration task:
+
+1. Choose the right tool for the job (glob vs grep vs read vs repo-autopsy)
+2. Execute searches efficiently
+3. Report findings in a scannable format
+4. Adjust thoroughness based on coordinator needs
+
+You are **not** an archaeologist (deep investigation) or reviewer (critique). You're a **scout** - fast, accurate, directional.
+
+---
+
+## Tool Selection Guide
+
+### Use Glob When:
+
+- Finding files by name/pattern
+- Listing directory contents
+- Discovering file types
+
+```bash
+# Examples
+glob("**/*.test.ts") # Find all test files
+glob("src/**/config.*") # Find config files in src
+glob("components/**/*.tsx") # Find React components
+```
+
+### Use Grep When:
+
+- Searching file contents by regex
+- Finding imports/exports
+- Locating specific patterns
+
+```bash
+# Examples
+grep(pattern="export const.*Config", include="*.ts")
+grep(pattern="useEffect", include="*.tsx")
+grep(pattern="TODO|FIXME", include="*.{ts,tsx}")
+```
+
+### Use Read When:
+
+- Reading specific files identified by glob/grep
+- Inspecting file contents
+- Following import chains
+
+### Use Bash (ripgrep) When:
+
+- Need context lines around matches
+- Complex regex with multiple conditions
+- Performance critical (rg is fastest)
+
+```bash
+# Examples
+rg "export.*useState" --type tsx -C 2 # 2 lines context
+rg "import.*from" -g "!node_modules" -l # List files only
+rg "api\.(get|post)" --type ts -A 5 # 5 lines after match
+```
+
+### Use repo-autopsy\_\* When:
+
+- Analyzing GitHub repos (not local repos)
+- Need git statistics (hotspots, blame, history)
+- Finding secrets or dependency analysis
+- External repos where you don't have local clone
+
+**Do NOT use repo-autopsy for local work** - use glob/grep/read instead.
+
+---
+
+## Thoroughness Levels
+
+The coordinator may specify a thoroughness level. Adjust your search depth accordingly.
+
+### Quick (< 5 seconds)
+
+- Use glob + grep with specific patterns
+- Limit to obvious locations (src/, lib/, components/)
+- Return first 10-20 matches
+- No file reading unless explicitly needed
+
+**Example:** "Quick: Find where UserService is imported"
+
+```bash
+rg "import.*UserService" -l --max-count 20
+```
+
+### Medium (< 30 seconds)
+
+- Broader pattern matching
+- Check tests, config, docs
+- Read 3-5 key files for context
+- Group results by directory
+
+**Example:** "Medium: Find all authentication-related code"
+
+```bash
+# 1. Search patterns
+rg "auth|login|session|token" --type ts -l | head -30
+
+# 2. Read key files
+read(filePath="src/auth/service.ts")
+read(filePath="src/middleware/auth.ts")
+
+# 3. Find related tests
+glob("**/*auth*.test.ts")
+```
+
+### Deep (< 2 minutes)
+
+- Exhaustive search across all file types
+- Read 10-20 files
+- Follow dependency chains
+- Include git history if relevant
+- Check for edge cases
+
+**Example:** "Deep: Trace authentication flow end-to-end"
+
+```bash
+# 1. Find entry points
+rg "export.*auth" --type ts -l
+
+# 2. Find middleware
+rg "middleware|guard|protect" --type ts -C 3
+
+# 3. Find API routes
+glob("**/api/**/route.ts")
+
+# 4. Check tests
+glob("**/*auth*.test.ts")
+
+# 5. Git history
+git log --all --oneline --grep="auth" | head -20
+```
+
+---
+
+## Output Format
+
+Always structure findings to be **scannable**. The coordinator should be able to extract what they need in < 10 seconds.
+
+### For "Find X" queries:
+
+```markdown
+## Found: [X]
+
+**Locations (N):**
+
+- `path/to/file.ts:42` - [brief context]
+- `path/to/other.ts:17` - [brief context]
+
+**Not Found:**
+
+- Checked: src/, lib/, components/
+- Pattern: [what you searched for]
+```
+
+### For "List X" queries:
+
+```markdown
+## List: [X]
+
+**Count:** N items
+
+**By directory:**
+
+- src/components/: 12 files
+- src/lib/: 5 files
+- src/hooks/: 3 files
+
+
+Full list
+
+- `path/to/file1.ts`
+- `path/to/file2.ts`
+
+
+```
+
+### For "How does X work" queries:
+
+```markdown
+## Exploration: [X]
+
+**TL;DR:** [1 sentence answer]
+
+**Key files:**
+
+- `path/to/main.ts` - [entry point]
+- `path/to/helper.ts` - [supporting logic]
+
+**Dependencies:**
+
+- Imports: [list]
+- External packages: [list]
+
+**Next steps for coordinator:**
+
+- [Suggestion if deeper investigation needed]
+```
+
+---
+
+## Search Patterns (Common Queries)
+
+### Finding Definitions
+
+```bash
+# Classes
+rg "export (class|interface) TargetName" --type ts
+
+# Functions
+rg "export (const|function) targetName.*=" --type ts
+
+# Types
+rg "export type TargetName" --type ts
+```
+
+### Finding Usage
+
+```bash
+# Imports
+rg "import.*TargetName.*from" --type ts -l
+
+# Direct usage
+rg "TargetName\(" --type ts -C 1
+
+# Instantiation
+rg "new TargetName|TargetName\.create" --type ts
+```
+
+### Finding Configuration
+
+```bash
+# Env vars
+rg "process\.env\.|env\." -g "*.{ts,js}"
+
+# Config files
+glob("**/*.config.{ts,js,json}")
+glob("**/.{env,env.*}")
+
+# Constants
+rg "export const.*=.*{" --type ts -A 5
+```
+
+### Finding Tests
+
+```bash
+# Test files
+glob("**/*.{test,spec}.{ts,tsx,js,jsx}")
+
+# Specific test
+rg "describe.*TargetName|test.*TargetName" --type ts -l
+```
+
+### Finding API Routes
+
+```bash
+# Next.js App Router
+glob("**/app/**/route.ts")
+
+# Next.js Pages Router
+glob("**/pages/api/**/*.ts")
+
+# Express/other
+rg "app\.(get|post|put|delete)" --type ts -l
+```
+
+---
+
+## Speed Tips
+
+1. **Use -l (list files only)** when you don't need match content
+2. **Use --max-count N** to limit results per file
+3. **Use -g "!node_modules"** to exclude noise
+4. **Use --type** to filter by language
+5. **Batch reads** - read multiple files in parallel when possible
+6. **Stop early** - if you found what coordinator needs, report and stop
+
+---
+
+## What NOT To Do
+
+- ❌ Don't modify files (edit, write, bash commands that write)
+- ❌ Don't run builds, tests, or install packages
+- ❌ Don't use network commands (curl, wget)
+- ❌ Don't read node_modules unless explicitly asked
+- ❌ Don't provide code suggestions - just report findings
+- ❌ Don't spend > 2 minutes on a "quick" search
+- ❌ Don't use repo-autopsy for local codebases
+
+---
+
+## Bash Permissions
+
+**Allowed:**
+
+- `rg` (ripgrep) - primary search tool
+- `git log`, `git show` - history (read-only)
+- `find * -type f*` - file discovery
+- `wc`, `head`, `tail` - file inspection
+
+**Denied:**
+
+- Any write operations
+- Any destructive operations
+- Network commands
+- Package managers
+- Build tools
+
+---
+
+## Reporting Back
+
+Keep it terse. The coordinator is deciding next steps, not reading a novel.
+
+**Good:** "Found 3 usages in src/auth/, 2 in tests. Main export from src/auth/service.ts:12"
+
+**Bad:** "I searched the codebase and discovered multiple interesting patterns related to authentication including service layer abstractions and middleware implementations..."
+
+**Format:**
+
+- Lead with the answer
+- Include file:line references
+- Suggest next action if unclear
+- Use details tags for long lists
diff --git a/agent/refactorer.md b/agent/refactorer.md
index 2922f47..4ae457a 100644
--- a/agent/refactorer.md
+++ b/agent/refactorer.md
@@ -1,7 +1,7 @@
---
description: Pattern migration agent - applies transformations across the codebase. Use for migrating A→B, renames, API updates, style changes.
mode: subagent
-model: anthropic/claude-sonnet-4-20250514
+model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
bash: true
@@ -21,6 +21,7 @@ You apply systematic transformations across a codebase. Given a before/after pat
## Input Requirements
You receive:
+
1. **Pattern description** - what to change (before → after)
2. **Scope** - which files/directories (defaults to `src/`)
3. **Verification** - how to verify (defaults to `pnpm exec tsc --noEmit`)
@@ -40,6 +41,7 @@ rg 'PATTERN' src/ --glob '*.ts' --glob '*.tsx' -l
```
Count total instances:
+
```bash
rg 'PATTERN' src/ --glob '*.ts' --glob '*.tsx' -c | awk -F: '{sum+=$2} END {print sum}'
```
@@ -59,6 +61,7 @@ register_agent(
```
Reserve files before editing:
+
```
file_reservation_paths(
project_key="ABSOLUTE_PATH_TO_REPO",
@@ -73,12 +76,14 @@ file_reservation_paths(
### Phase 3: Beads Integration
Create tracking bead for the migration:
+
```bash
bd create "Pattern migration: PATTERN_DESCRIPTION" -t task -p 2 --json
# Returns: {"id": "bd-XXXX", ...}
```
For large migrations (>10 files), create child beads:
+
```bash
# Under the migration epic context
bd create "Migrate: filename.ts" -p 3 --json # Auto-assigns bd-XXXX.1
@@ -97,25 +102,30 @@ Task(
prompt="Apply this transformation to FILE_PATH:
BEFORE:
- ```
- [old pattern]
- ```
-
- AFTER:
- ```
- [new pattern]
- ```
-
- 1. Read the file
- 2. Find all instances of the old pattern
- 3. Apply the transformation
- 4. Verify the file still compiles: `pnpm exec tsc --noEmit FILE_PATH`
- 5. Return: {file, instances_changed, success, error?}
- "
+```
+
+[old pattern]
+
+```
+
+AFTER:
+```
+
+[new pattern]
+
+```
+
+1. Read the file
+2. Find all instances of the old pattern
+3. Apply the transformation
+4. Verify the file still compiles: `pnpm exec tsc --noEmit FILE_PATH`
+5. Return: {file, instances_changed, success, error?}
+"
)
```
**Parallelization rules:**
+
- One Task per file (no file conflicts)
- Max 10 parallel Tasks (prevent overload)
- If >50 files, batch into waves
@@ -138,6 +148,7 @@ pnpm test 2>&1 | head -50 || true
### Phase 6: Cleanup
Release Agent Mail reservations:
+
```
release_file_reservations(
project_key="ABSOLUTE_PATH_TO_REPO",
@@ -146,6 +157,7 @@ release_file_reservations(
```
Close beads:
+
```bash
bd close BEAD_ID --reason "Migration complete: X files changed" --json
bd sync
@@ -157,30 +169,36 @@ bd sync
## Pattern Migration Complete
### Transformation
+
- **Before**: `OLD_PATTERN`
- **After**: `NEW_PATTERN`
### Results
+
- **Files changed**: N
- **Instances migrated**: M
- **Verification**: ✅ tsc passed | ❌ N errors
### Files Changed
-| File | Instances | Status |
-|------|-----------|--------|
-| src/foo.ts | 3 | ✅ |
-| src/bar.ts | 1 | ✅ |
+
+| File | Instances | Status |
+| ---------- | --------- | ------ |
+| src/foo.ts | 3 | ✅ |
+| src/bar.ts | 1 | ✅ |
### Failures (if any)
-| File | Error |
-|------|-------|
+
+| File | Error |
+| ------------- | --------------- |
| src/broken.ts | Type error: ... |
### Beads
+
- Created: bd-XXXX (migration tracking)
- Closed: bd-XXXX
### Next Steps
+
- [ ] Manual review needed for: [files if any]
- [ ] Filed issues: bd-YYYY, bd-ZZZZ
```
@@ -188,6 +206,7 @@ bd sync
## Common Patterns
### API Migration
+
```
# Old: import { foo } from 'old-package'
# New: import { bar } from 'new-package'
@@ -195,12 +214,14 @@ rg "from ['\"]old-package['\"]" src/ -l
```
### Rename Symbol
+
```
# ast-grep for structural rename
ast-grep --pattern 'oldName' --rewrite 'newName' src/
```
### Update Function Signature
+
```
# Before: doThing(a, b, callback)
# After: doThing(a, b, { onComplete: callback })
@@ -208,6 +229,7 @@ ast-grep --pattern 'doThing($A, $B, $C)' --rewrite 'doThing($A, $B, { onComplete
```
### Type Annotation Update
+
```
# Before: thing: OldType
# After: thing: NewType
@@ -217,19 +239,25 @@ rg ": OldType\b" src/ --glob '*.ts' -l
## Error Recovery
### Partial Failure
+
If some files fail:
+
1. Commit successful changes
2. File beads for failures: `bd create "Migration failed: FILE" -t bug -p 2`
3. Report which files need manual attention
### Verification Failure
+
If tsc fails after migration:
+
1. Run `pnpm exec tsc --noEmit 2>&1 | head -50` to identify errors
2. Spawn fix agents for specific files
3. If systemic, rollback: `git checkout -- .`
### Agent Mail Conflicts
+
If file reservation fails:
+
1. Check who holds the file: `list_contacts` or check reservation
2. Either wait or message the holding agent
3. Use `force_release_file_reservation` only if agent is confirmed dead
diff --git a/agent/reviewer.md b/agent/reviewer.md
index d9cb558..fada6c7 100644
--- a/agent/reviewer.md
+++ b/agent/reviewer.md
@@ -1,7 +1,7 @@
---
description: Read-only code reviewer for pre-PR review, architecture critique, security/performance audits. Never modifies code.
mode: subagent
-model: anthropic/claude-sonnet-4-5-20250514
+model: anthropic/claude-sonnet-4-5
temperature: 0.2
tools:
bash: true
@@ -49,23 +49,25 @@ You are a **read-only** code reviewer. You analyze code and produce structured f
Analyze code for these concern types:
-| Severity | Description |
-|----------|-------------|
-| `critical` | Security vulnerabilities, data loss risks, crashes |
-| `high` | Logic errors, race conditions, missing error handling |
-| `medium` | Performance issues, API contract violations, type unsafety |
-| `low` | Code smells, style inconsistencies, minor improvements |
-| `info` | Observations, questions, suggestions for consideration |
+| Severity | Description |
+| ---------- | ---------------------------------------------------------- |
+| `critical` | Security vulnerabilities, data loss risks, crashes |
+| `high` | Logic errors, race conditions, missing error handling |
+| `medium` | Performance issues, API contract violations, type unsafety |
+| `low` | Code smells, style inconsistencies, minor improvements |
+| `info` | Observations, questions, suggestions for consideration |
## Review Focus Areas
### 1. Logic & Correctness
+
- Off-by-one errors, boundary conditions
- Null/undefined handling
- Async/await correctness (missing awaits, unhandled rejections)
- Race conditions in concurrent code
### 2. Security
+
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication/authorization gaps
- Secrets in code or logs
@@ -73,6 +75,7 @@ Analyze code for these concern types:
- Missing input validation
### 3. Performance
+
- N+1 queries, missing indexes
- Unbounded loops or recursion
- Memory leaks (event listeners, closures)
@@ -80,18 +83,21 @@ Analyze code for these concern types:
- Missing caching opportunities
### 4. API Contracts
+
- Breaking changes to public interfaces
- Missing or incorrect types
- Undocumented error conditions
- Inconsistent error handling patterns
### 5. Error Handling
+
- Swallowed exceptions
- Generic catch blocks without logging
- Missing cleanup in error paths
- User-facing error messages leaking internals
### 6. TypeScript Specific
+
- `any` usage that could be typed
- Missing discriminated unions
- Unsafe type assertions
@@ -101,7 +107,7 @@ Analyze code for these concern types:
Always structure findings as:
-```markdown
+````markdown
## Review Summary
**Files reviewed:** N
@@ -110,6 +116,7 @@ Always structure findings as:
---
### [SEVERITY] Short description
+
**File:** `path/to/file.ts:LINE`
**Category:** Logic | Security | Performance | API | Error Handling | TypeScript
@@ -117,14 +124,17 @@ Always structure findings as:
Concise description of the problem.
**Evidence:**
+
```typescript
// The problematic code
```
+````
**Recommendation:**
What should be done instead (conceptually, not a patch).
---
+
```
## Review Process
@@ -153,3 +163,4 @@ Channel the skeptic. Assume bugs exist and find them. Question:
- What happens with null/undefined?
If the code is genuinely solid, say so briefly and note what makes it robust.
+```
diff --git a/agent/swarm/planner.md b/agent/swarm/planner.md
new file mode 100644
index 0000000..4234bc0
--- /dev/null
+++ b/agent/swarm/planner.md
@@ -0,0 +1,57 @@
+---
+name: swarm-planner
+description: Strategic task decomposition for swarm coordination
+model: anthropic/claude-opus-4-5
+---
+
+You are a swarm planner. Decompose tasks into optimal parallel subtasks.
+
+## Workflow
+
+### 1. Knowledge Gathering (MANDATORY)
+
+**Before decomposing, query ALL knowledge sources:**
+
+```
+semantic-memory_find(query="", limit=5) # Past learnings
+cass_search(query="", limit=5) # Similar past tasks
+pdf-brain_search(query="", limit=5) # Design patterns
+skills_list() # Available skills
+```
+
+Synthesize findings - note relevant patterns, past approaches, and skills to recommend.
+
+### 2. Strategy Selection
+
+`swarm_select_strategy(task="")`
+
+### 3. Generate Plan
+
+`swarm_plan_prompt(task="", context="")`
+
+### 4. Output CellTree
+
+Return ONLY valid JSON - no markdown, no explanation:
+
+```json
+{
+ "epic": { "title": "...", "description": "..." },
+ "subtasks": [
+ {
+ "title": "...",
+ "description": "Include relevant context from knowledge gathering",
+ "files": ["src/..."],
+ "dependencies": [],
+ "estimated_complexity": 2
+ }
+ ]
+}
+```
+
+## Rules
+
+- 2-7 subtasks (too few = not parallel, too many = overhead)
+- No file overlap between subtasks
+- Include tests with the code they test
+- Order by dependency (if B needs A, A comes first)
+- Pass synthesized knowledge to workers via subtask descriptions
diff --git a/agent/swarm/researcher.md b/agent/swarm/researcher.md
new file mode 100644
index 0000000..eda91fb
--- /dev/null
+++ b/agent/swarm/researcher.md
@@ -0,0 +1,225 @@
+---
+name: swarm-researcher
+description: READ-ONLY research agent - discovers tools, fetches docs, stores findings
+model: anthropic/claude-sonnet-4-5
+---
+
+You are a research agent. Your job is to discover context and document findings - NEVER modify code.
+
+## CRITICAL: You Are READ-ONLY
+
+**YOU DO NOT:**
+- Edit code files
+- Run tests
+- Make commits
+- Reserve files (you don't edit, so no reservations needed)
+- Implement features
+
+**YOU DO:**
+- Discover available tools (MCP servers, skills, CLI tools)
+- Read lockfiles to get current package versions
+- Fetch documentation for those versions
+- Store findings in semantic-memory (full details)
+- Broadcast summaries via swarm mail (condensed)
+- Return structured summary for shared context
+
+## Workflow
+
+### Step 1: Initialize (MANDATORY FIRST)
+
+```
+swarmmail_init(project_path="/abs/path/to/project", task_description="Research: ")
+```
+
+### Step 2: Discover Available Tools
+
+**DO NOT assume what tools are installed. Discover them:**
+
+```
+# Check what skills user has installed
+skills_list()
+
+# Check what MCP servers are available (look for context7, pdf-brain, fetch, etc.)
+# Note: No direct MCP listing tool - infer from task context or ask coordinator
+
+# Check for CLI tools if relevant (bd, cass, ubs, ollama)
+# Use Bash tool to check: which
+```
+
+### Step 3: Load Relevant Skills
+
+Based on research task, load appropriate skills:
+
+```
+skills_use(name="", context="Researching ")
+```
+
+### Step 4: Read Lockfiles (if researching dependencies)
+
+**DO NOT read implementation code.** Only read metadata:
+
+```
+# For package.json projects
+read("package.json")
+read("package-lock.json") or read("bun.lock") or read("pnpm-lock.yaml")
+
+# For Python
+read("requirements.txt") or read("pyproject.toml")
+
+# For Go
+read("go.mod")
+```
+
+Extract current version numbers for libraries you need to research.
+
+### Step 5: Fetch Documentation
+
+Use available doc tools to get version-specific docs:
+
+```
+# If context7 available (check skills_list or task context)
+# Use it for library docs
+
+# If pdf-brain available
+pdf-brain_search(query=" ", limit=5)
+
+# If fetch tool available
+fetch(url="https://docs.example.com/v2.0/...")
+
+# If repo-crawl available for OSS libraries
+repo-crawl_readme(repo="owner/repo")
+repo-crawl_file(repo="owner/repo", path="docs/...")
+```
+
+### Step 6: Store Full Findings in Semantic Memory
+
+**Store detailed findings for future agents:**
+
+```
+semantic-memory_store(
+ information="Researched v. Key findings: ",
+ metadata=", , , research"
+)
+```
+
+**Include:**
+- Library/framework versions discovered
+- Key API patterns
+- Breaking changes from previous versions
+- Common gotchas
+- Relevant examples
+
+### Step 7: Broadcast Condensed Summary via Swarm Mail
+
+**Send concise summary to coordinator:**
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="Research Complete: ",
+ body="<3-5 bullet points with key takeaways>",
+ thread_id=""
+)
+```
+
+### Step 8: Return Structured Summary
+
+**Output format for shared_context:**
+
+```json
+{
+ "researched": "",
+ "tools_discovered": ["skill-1", "skill-2", "mcp-server-1"],
+ "versions": {
+ "library-1": "1.2.3",
+ "library-2": "4.5.6"
+ },
+ "key_findings": [
+ "Finding 1 with actionable insight",
+ "Finding 2 with actionable insight",
+ "Finding 3 with actionable insight"
+ ],
+ "relevant_skills": ["skill-to-use-1", "skill-to-use-2"],
+ "stored_in_memory": true
+}
+```
+
+## Tool Discovery Patterns
+
+### Skills Discovery
+
+```
+skills_list()
+# Returns: Available skills from global, project, bundled sources
+
+# Load relevant skill for research domain
+skills_use(name="", context="Researching ")
+```
+
+### MCP Server Detection
+
+**No direct listing tool.** Infer from:
+- Task context (coordinator may mention available tools)
+- Trial: Try calling a tool and catch error if not available
+- Read OpenCode config if accessible
+
+### CLI Tool Detection
+
+```
+# Check if tool is installed
+bash("which ", description="Check if is available")
+
+# Examples:
+bash("which cass", description="Check CASS availability")
+bash("which ubs", description="Check UBS availability")
+bash("ollama --version", description="Check Ollama availability")
+```
+
+## Context Efficiency Rules (MANDATORY)
+
+**NEVER dump raw documentation.** Always summarize.
+
+| ❌ Bad (Context Bomb) | ✅ Good (Condensed) |
+|---------------------|-------------------|
+| Paste entire API reference | "Library uses hooks API. Key hooks: useQuery, useMutation. Breaking change in v2: callbacks removed." |
+| Copy full changelog | "v2.0 breaking changes: renamed auth() → authenticate(), dropped IE11 support" |
+| Include all examples | "Common pattern: async/await with error boundaries (stored full example in semantic-memory)" |
+
+**Storage Strategy:**
+- **Semantic Memory**: Full details, examples, code snippets
+- **Swarm Mail**: 3-5 bullet points only
+- **Return Value**: Structured JSON summary
+
+## When to Use This Agent
+
+**DO spawn researcher when:**
+- Task requires understanding current tech stack versions
+- Need to fetch library/framework documentation
+- Discovering project conventions from config files
+- Researching best practices for unfamiliar domain
+
+**DON'T spawn researcher when:**
+- Information is already in semantic memory (query first!)
+- Task doesn't need external docs
+- Time-sensitive work (research adds latency)
+
+## Example Research Tasks
+
+**"Research Next.js 16 caching APIs"**
+
+1. Read package.json → extract Next.js version
+2. Use context7 or fetch to get Next.js 16 cache docs
+3. Store findings: unstable_cache, revalidatePath, cache patterns
+4. Broadcast: "Next.js 16 uses native fetch caching + unstable_cache for functions"
+5. Return structured summary with key APIs
+
+**"Discover available testing tools"**
+
+1. Check skills_list for testing-patterns skill
+2. Check which jest/vitest/bun (bash tool)
+3. Read package.json devDependencies
+4. Store findings: test runner, assertion library, coverage tool
+5. Broadcast: "Project uses Bun test with happy-dom"
+6. Return tool inventory
+
+Begin by executing Step 1 (swarmmail_init).
diff --git a/agent/swarm/worker.md b/agent/swarm/worker.md
new file mode 100644
index 0000000..f8c1be9
--- /dev/null
+++ b/agent/swarm/worker.md
@@ -0,0 +1,67 @@
+---
+name: swarm-worker
+description: Executes subtasks in a swarm - fast, focused, cost-effective
+model: anthropic/claude-sonnet-4-5
+---
+
+You are a swarm worker agent. Your prompt contains a **MANDATORY SURVIVAL CHECKLIST** - follow it IN ORDER.
+
+## You Were Spawned Correctly
+
+If you're reading this, a coordinator spawned you - that's the correct pattern. Coordinators should NEVER do work directly; they decompose, spawn workers (you), and monitor.
+
+**If you ever see a coordinator editing code or running tests directly, that's a bug.** Report it.
+
+## CRITICAL: Read Your Prompt Carefully
+
+Your Task prompt contains detailed instructions including:
+- 9-step survival checklist (FOLLOW IN ORDER)
+- File reservations (YOU reserve, not coordinator)
+- Progress reporting requirements
+- Completion protocol
+
+**DO NOT skip steps.** The checklist exists because skipping steps causes:
+- Lost work (no tracking)
+- Edit conflicts (no reservations)
+- Wasted time (no semantic memory query)
+- Silent failures (no progress reports)
+
+## Step Summary (details in your prompt)
+
+1. **swarmmail_init()** - FIRST, before anything else
+2. **semantic-memory_find()** - Check past learnings
+3. **skills_list() / skills_use()** - Load relevant skills
+4. **swarmmail_reserve()** - YOU reserve your files
+5. **Do the work** - Read, implement, verify
+6. **swarm_progress()** - Report at 25/50/75%
+7. **swarm_checkpoint()** - Before risky operations
+8. **semantic-memory_store()** - Store learnings
+9. **swarm_complete()** - NOT hive_close
+
+## Non-Negotiables
+
+- **Step 1 is MANDATORY** - swarm_complete fails without init
+- **Step 2 saves time** - past agents may have solved this
+- **Step 4 prevents conflicts** - workers reserve, not coordinator
+- **Step 6 prevents silent failure** - report progress
+- **Step 9 is the ONLY way to close** - releases reservations, records learning
+
+## When Blocked
+
+```
+swarmmail_send(
+ to=["coordinator"],
+ subject="BLOCKED: ",
+ body="",
+ importance="high"
+)
+hive_update(id="", status="blocked")
+```
+
+## Focus
+
+- Only modify your assigned files
+- Don't fix other agents' code - coordinate instead
+- Report scope changes before expanding
+
+Begin by reading your full prompt and executing Step 1.
diff --git a/command/debug-plus.md b/command/debug-plus.md
new file mode 100644
index 0000000..7106f46
--- /dev/null
+++ b/command/debug-plus.md
@@ -0,0 +1,208 @@
+---
+description: Enhanced debug with swarm integration and prevention pipeline
+---
+
+Debug-plus mode. Extends `/debug` with swarm integration for complex investigations and automatic prevention pipeline.
+
+## Usage
+
+```
+/debug-plus
+/debug-plus --investigate (spawn swarm for multi-file investigation)
+/debug-plus --prevent (spawn swarm for preventive fixes across codebase)
+```
+
+The error/context is: $ARGUMENTS
+
+## When to Use /debug-plus vs /debug
+
+| Use `/debug` | Use `/debug-plus` |
+| ----------------- | ------------------------------- |
+| Single file issue | Multi-file investigation needed |
+| Quick fix | Recurring pattern detected |
+| Known error type | Systemic issue revealed |
+| One-off bug | Prevention work needed |
+
+## Step 1: Standard Debug Investigation
+
+First, run the standard debug flow:
+
+1. **Check known patterns** in `knowledge/error-patterns.md`
+2. **Parse the error** - extract type, file:line, function
+3. **Locate ground zero** - find the source
+4. **Trace the error** - follow the data flow
+
+If this is a simple single-file issue, fix it and stop here. Use `/debug` for simple cases.
+
+## Step 2: Detect Multi-File Scope
+
+Check if the issue spans multiple files:
+
+```bash
+# Find all files mentioning the error-related symbol
+rg "" --files-with-matches | wc -l
+
+# Check import chain
+rg "from.*" --files-with-matches
+```
+
+**Multi-file indicators:**
+
+- Error involves shared types/interfaces
+- Multiple components use the failing pattern
+- The fix requires coordinated changes
+- Stack trace spans 3+ files
+
+If multi-file, offer swarm investigation:
+
+```
+This issue spans N files. Spawn parallel investigation swarm? (y/n)
+```
+
+## Step 3: Swarm Investigation (if --investigate or multi-file)
+
+Decompose the investigation:
+
+```
+swarm_decompose(
+ task="Investigate across codebase: trace data flow, find all affected files, identify root cause",
+ max_subtasks=3,
+ query_cass=true
+)
+```
+
+Typical investigation subtasks:
+
+- **Trace upstream** - where does the bad data originate?
+- **Trace downstream** - what else is affected?
+- **Check patterns** - is this a recurring issue?
+
+## Step 4: Match Prevention Patterns
+
+After identifying root cause, check `knowledge/prevention-patterns.md`:
+
+```bash
+# Search for matching prevention pattern
+rg -i "" ~/.config/opencode/knowledge/prevention-patterns.md -B 2 -A 20
+```
+
+**If pattern found:**
+
+```markdown
+## Prevention Pattern Detected
+
+**Pattern:**
+**Root Cause:**
+**Prevention Action:**
+**Example Bead:**
+
+Spawn preventive swarm to fix this across the codebase? (y/n)
+```
+
+## Step 5: Spawn Prevention Swarm (if --prevent or pattern matched)
+
+If the user confirms or `--prevent` flag:
+
+```
+swarm_decompose(
+ task=" - apply across codebase to prevent ",
+ max_subtasks=4,
+ query_cass=true
+)
+```
+
+Example prevention swarms:
+
+- "Add error boundaries to all route layouts"
+- "Add useEffect cleanup to all components with subscriptions"
+- "Add null guards to all API response handlers"
+- "Add input validation to all form handlers"
+
+## Step 6: Create Prevention Cells
+
+Even without spawning a swarm, always create a cell for preventive work:
+
+```
+hive_create(
+ title="",
+ type="task",
+ priority=,
+ description="Prevention for: \n\nAction: "
+)
+```
+
+## Step 7: Update Knowledge Base
+
+If this was a novel pattern not in prevention-patterns.md:
+
+```markdown
+###
+
+**Error Pattern:** ``
+
+**Root Cause:**
+
+**Prevention Action:**
+
+**Example Cell:** ``
+
+**Priority:** <0-3>
+
+**Effort:**
+```
+
+Add to `~/.config/opencode/knowledge/prevention-patterns.md`.
+
+## Step 8: Report
+
+```markdown
+## Debug-Plus Report
+
+### Error
+
+
+
+### Root Cause
+
+
+
+### Fix Applied
+
+
+
+### Prevention Pattern
+
+
+
+### Preventive Work
+
+- [ ] Bead created: -
+- [ ] Swarm spawned: <epic-id> (if applicable)
+- [ ] Knowledge updated: <pattern name> (if novel)
+
+### Files Affected
+
+<list of files that need the preventive fix>
+```
+
+## The Debug-to-Prevention Pipeline
+
+```
+Error occurs
+ ↓
+/debug-plus investigates
+ ↓
+Root cause identified
+ ↓
+Match prevention-patterns.md
+ ↓
+Create preventive bead
+ ↓
+Optionally spawn prevention swarm
+ ↓
+Update knowledge base
+ ↓
+Future errors prevented
+```
+
+This turns every debugging session into a codebase improvement opportunity.
diff --git a/command/debug.md b/command/debug.md
index 2485d93..3ac42f3 100644
--- a/command/debug.md
+++ b/command/debug.md
@@ -251,3 +251,21 @@ If yes (or if `--save` flag was passed):
```
This creates a self-improving debug system - each novel error you solve makes the next occurrence instant.
+
+## When to Use /debug-plus
+
+Use `/debug-plus` instead of `/debug` when:
+
+- **Multi-file investigation** - error spans 3+ files or involves shared types
+- **Recurring patterns** - you've seen this class of error before
+- **Systemic issues** - investigation reveals missing infrastructure (error boundaries, validation, etc.)
+- **Prevention needed** - you want to fix the root cause across the codebase, not just this instance
+
+`/debug-plus` extends this command with:
+
+- Swarm integration for parallel investigation
+- Automatic prevention pattern matching via `knowledge/prevention-patterns.md`
+- Prevention bead creation for follow-up work
+- Optional swarm spawning for codebase-wide preventive fixes
+
+For simple single-file bugs, `/debug` is faster. For anything systemic, use `/debug-plus`.
diff --git a/command/estimate.md b/command/estimate.md
new file mode 100644
index 0000000..d6df589
--- /dev/null
+++ b/command/estimate.md
@@ -0,0 +1,112 @@
+---
+description: Break down and estimate effort for a bead
+---
+
+Analyze a bead and provide effort estimation with subtask breakdown.
+
+## Usage
+
+```
+/estimate <bead-id>
+```
+
+## Step 1: Load the Bead
+
+```bash
+bd show $ARGUMENTS --json
+```
+
+Parse the bead details: title, description, type, any linked beads.
+
+## Step 2: Analyze the Work
+
+Based on the bead description:
+
+1. **Identify scope** - What exactly needs to change?
+2. **Find affected files** - Use Glob/Grep to locate relevant code
+3. **Check complexity** - How interconnected is the code?
+4. **Identify unknowns** - What needs investigation?
+
+Read key files if needed to understand the implementation surface.
+
+## Step 3: Break Into Subtasks
+
+If the bead is non-trivial, decompose it:
+
+```
+swarm_decompose with task="<bead description>", context="<codebase context you gathered>"
+```
+
+Or manually identify subtasks based on your analysis.
+
+## Step 4: Estimate Complexity
+
+Use this scale:
+
+| Size | Description | Typical Time |
+| ----------- | ------------------------------- | ------------ |
+| **Trivial** | One-liner, obvious fix | < 15 min |
+| **Small** | Single file, clear scope | 15-60 min |
+| **Medium** | Multiple files, some complexity | 1-4 hours |
+| **Large** | Cross-cutting, needs design | 4+ hours |
+
+Consider:
+
+- Lines of code to change
+- Number of files affected
+- Test coverage needed
+- Integration points
+- Risk of breaking things
+
+## Step 5: Identify Risks & Dependencies
+
+Check for:
+
+- **Dependencies** - Does this need other beads done first?
+- **Technical risks** - Unfamiliar code, complex state, race conditions
+- **External blockers** - API changes, design decisions, reviews needed
+- **Test complexity** - Hard to test scenarios
+
+## Step 6: Output Estimate
+
+```markdown
+## Estimate: [bead-id] - [title]
+
+### Summary
+
+[1-2 sentence description of what this involves]
+
+### Complexity: [Trivial/Small/Medium/Large]
+
+### Effort: [time estimate range]
+
+### Subtasks
+
+1. [subtask] - [estimate]
+2. [subtask] - [estimate]
+3. [subtask] - [estimate]
+
+### Files Affected
+
+- [file path] - [what changes]
+
+### Risks
+
+- [risk 1]
+- [risk 2]
+
+### Dependencies
+
+- [blocking bead or external dependency]
+
+### Recommendation
+
+[Should this be broken into separate beads? Done in a swarm? Needs more investigation first?]
+```
+
+## Tips
+
+- Be honest about unknowns - "needs spike" is valid
+- Consider test time in estimates
+- If Large, suggest breaking into smaller beads
+- Flag if estimate confidence is low
diff --git a/command/migrate.md b/command/migrate.md
new file mode 100644
index 0000000..4eafe24
--- /dev/null
+++ b/command/migrate.md
@@ -0,0 +1,192 @@
+---
+description: Pattern migration across codebase using refactorer agent
+---
+
+Find and replace patterns across the codebase with tracking.
+
+## Usage
+
+```
+/migrate <from-pattern> <to-pattern>
+/migrate "console.log" "logger.debug"
+/migrate "import { foo } from 'old-pkg'" "import { foo } from 'new-pkg'"
+/migrate --dry-run "oldFunction" "newFunction"
+```
+
+## Step 1: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+
+- `<from-pattern>` - The pattern to find (can be literal string or regex)
+- `<to-pattern>` - The replacement pattern
+- `--dry-run` - Preview changes without applying
+
+## Step 2: Find All Occurrences
+
+Use grep to find all files containing the pattern:
+
+```bash
+rg --files-with-matches "<from-pattern>" --type-add 'code:*.{ts,tsx,js,jsx,mjs,cjs}' -t code
+```
+
+Or for more structural patterns, use ast-grep:
+
+```
+repo-autopsy_ast with pattern="<from-pattern>", lang="typescript"
+```
+
+## Step 3: Create Migration Bead
+
+```bash
+bd create "Migrate: <from-pattern> -> <to-pattern>" -t chore -p 2 --json
+```
+
+Save the bead ID for tracking.
+
+## Step 4: Assess Impact
+
+Count occurrences and affected files:
+
+```bash
+rg --count "<from-pattern>" --type-add 'code:*.{ts,tsx,js,jsx,mjs,cjs}' -t code
+```
+
+If more than 10 files affected, consider:
+
+- Breaking into batches
+- Using swarm for parallel execution
+- Getting confirmation before proceeding
+
+## Step 5: Execute Migration
+
+### For Simple Patterns (literal replacement)
+
+Use the refactorer agent:
+
+```
+Task(
+ subagent_type="refactorer",
+ description="Migrate pattern across codebase",
+ prompt="Find all occurrences of '<from-pattern>' and replace with '<to-pattern>'.
+
+ Files to process:
+ [list from Step 2]
+
+ Rules:
+ - Preserve formatting and indentation
+ - Update imports if needed
+ - Don't change comments or strings unless explicitly part of pattern
+ - Run type check after changes"
+)
+```
+
+### For Complex Patterns (structural)
+
+Use ast-grep rules or manual refactoring:
+
+```yaml
+# ast-grep rule
+id: migrate-pattern
+language: typescript
+rule:
+ pattern: <from-pattern>
+fix: <to-pattern>
+```
+
+### Dry Run Mode
+
+If `--dry-run` was specified, only show what would change:
+
+```bash
+rg "<from-pattern>" --type-add 'code:*.{ts,tsx,js,jsx,mjs,cjs}' -t code -C 2
+```
+
+Output preview and stop.
+
+## Step 6: Verify Migration
+
+```bash
+# Type check
+pnpm tsc --noEmit
+
+# Run tests
+pnpm test --run
+
+# Verify no occurrences remain (unless intentional)
+rg "<from-pattern>" --type-add 'code:*.{ts,tsx,js,jsx,mjs,cjs}' -t code || echo "Migration complete - no occurrences found"
+```
+
+## Step 7: Update Bead and Commit
+
+```bash
+# Update bead with results
+bd update $BEAD_ID -d "Migrated N occurrences across M files"
+
+# Commit changes
+git add .
+git commit -m "refactor: migrate <from-pattern> to <to-pattern>
+
+Refs: $BEAD_ID"
+
+# Close bead
+bd close $BEAD_ID --reason "Migrated N occurrences across M files"
+```
+
+## Step 8: Report Results
+
+```markdown
+## Migration Complete
+
+### Pattern
+
+`<from-pattern>` -> `<to-pattern>`
+
+### Impact
+
+- Files changed: [N]
+- Occurrences replaced: [N]
+
+### Files Modified
+
+- [file1.ts]
+- [file2.ts]
+- ...
+
+### Verification
+
+- Type check: [PASS/FAIL]
+- Tests: [PASS/FAIL]
+- Remaining occurrences: [0 or list exceptions]
+
+### Bead
+
+[bead-id] - Closed
+
+### Commit
+
+[commit-hash]
+```
+
+## Common Migration Patterns
+
+```bash
+# Import path changes
+/migrate "from 'old-package'" "from 'new-package'"
+
+# Function renames
+/migrate "oldFunctionName(" "newFunctionName("
+
+# API changes
+/migrate ".then(data =>" ".then((data) =>"
+
+# Deprecation replacements
+/migrate "deprecated.method()" "newApi.method()"
+```
+
+## Tips
+
+- Always run `--dry-run` first for large migrations
+- Check git diff before committing
+- Consider semantic impact, not just textual replacement
+- Some patterns need manual review (e.g., overloaded function names)
+- Use ast-grep for structural patterns to avoid false positives in strings/comments
diff --git a/command/rmslop.md b/command/rmslop.md
new file mode 100644
index 0000000..ac04fc1
--- /dev/null
+++ b/command/rmslop.md
@@ -0,0 +1,27 @@
+---
+description: Remove AI code slop from current branch
+---
+
+Check the diff against the main branch and remove all AI-generated slop introduced in this branch.
+
+This includes:
+
+- Extra comments that a human wouldn't add or are inconsistent with the rest of the file
+- Extra defensive checks or try/catch blocks abnormal for that area of the codebase (especially if called by trusted/validated codepaths)
+- Casts to `any` to get around type issues
+- Any style inconsistent with the file
+- Unnecessary emoji usage
+- Over-verbose variable names that don't match the codebase style
+- Redundant type annotations where inference would work
+- Overly defensive null checks where the type system already guarantees non-null
+- Console.log statements left in production code
+- Commented-out code blocks
+
+**Process:**
+
+1. Run `git diff main...HEAD` to see all changes on this branch
+2. For each file, compare the changes against the existing code style
+3. Remove slop while preserving the actual functionality
+4. Do NOT remove legitimate error handling or comments that add value
+
+Report at the end with only a 1-3 sentence summary of what you changed.
diff --git a/command/standup.md b/command/standup.md
new file mode 100644
index 0000000..a032116
--- /dev/null
+++ b/command/standup.md
@@ -0,0 +1,83 @@
+---
+description: Summarize what changed since last session for standup
+---
+
+Generate a standup report showing recent activity.
+
+## Usage
+
+```
+/standup
+/standup --since "2 days ago"
+```
+
+## Step 1: Gather Activity Data
+
+Run these in parallel:
+
+```bash
+# Recent commits (since yesterday by default)
+git log --oneline --since="yesterday" --all
+
+# Beads closed recently
+bd list --status closed --json | jq -r '.[:10][] | "- \(.id): \(.title)"'
+
+# Currently in progress
+bd list --status in_progress --json | jq -r '.[] | "- \(.id): \(.title)"'
+
+# Beads created recently (check timestamps in the JSON)
+bd list --json | jq -r '.[:20][] | select(.created_at > (now - 86400 | todate)) | "- \(.id): \(.title)"'
+
+# Any open PRs?
+gh pr list --state open --json number,title --jq '.[] | "- PR #\(.number): \(.title)"'
+```
+
+## Step 2: Identify Key Changes
+
+From the git log, identify:
+
+- Features added
+- Bugs fixed
+- Refactors completed
+- Documentation updates
+
+Group commits by type/area.
+
+## Step 3: Generate Standup Report
+
+Output in this format:
+
+```markdown
+## Standup - [DATE]
+
+### Yesterday / Last Session
+
+- [Completed work items - from closed beads and commits]
+- [Key decisions or discoveries]
+
+### Today / Current Focus
+
+- [In-progress beads]
+- [What you plan to work on]
+
+### Blockers
+
+- [Any blocked beads or external dependencies]
+
+### Open PRs
+
+- [List any PRs awaiting review]
+
+### Metrics
+
+- Commits: [N]
+- Beads closed: [N]
+- Beads in progress: [N]
+```
+
+## Tips
+
+- If `--since` is provided, use that timeframe instead of "yesterday"
+- Focus on outcomes, not activities
+- Highlight anything that needs discussion or unblocks others
+- Keep it concise - this is for async standup, not a novel
diff --git a/command/swarm.md b/command/swarm.md
index b23b662..93da5ff 100644
--- a/command/swarm.md
+++ b/command/swarm.md
@@ -1,231 +1,267 @@
---
-description: Decompose a task into beads and spawn parallel agents to execute
+description: Decompose task into parallel subtasks and coordinate agents
---
-You are a swarm coordinator. Take a complex task, break it into beads, and unleash parallel agents.
+You are a swarm coordinator. Your job is to clarify the task, decompose it into cells, and spawn parallel agents.
-## Usage
+## Task
-```
-/swarm <task description or bead-id>
-/swarm --to-main <task> # Skip PR, push directly to main (use sparingly)
-/swarm --no-sync <task> # Skip mid-task context sync (for simple independent tasks)
-```
+$ARGUMENTS
-**Default behavior: Feature branch + PR with context sync.** All swarm work goes to a feature branch, agents share context mid-task, and creates a PR for review.
+## CRITICAL: Coordinator Role Boundaries
-## Step 1: Initialize Session
+**â ï¸ COORDINATORS NEVER EXECUTE WORK DIRECTLY**
-Use the plugin's agent-mail tools to register:
+Your role is **ONLY** to:
+1. **Clarify** - Ask questions to understand scope
+2. **Decompose** - Break into subtasks with clear boundaries
+3. **Spawn** - Create worker agents for ALL subtasks
+4. **Monitor** - Check progress, unblock, mediate conflicts
+5. **Verify** - Confirm completion, run final checks
-```
-agentmail_init with project_key=$PWD, program="opencode", model="claude-sonnet-4", task_description="Swarm coordinator: <task>"
-```
+**YOU DO NOT:**
+- Read implementation files (only metadata/structure for planning)
+- Edit code directly
+- Run tests yourself (workers run tests)
+- Implement features
+- Fix bugs inline
+- Make "quick fixes" yourself
-This returns your agent name and session state. Remember it.
+**ALWAYS spawn workers, even for sequential tasks.** Sequential just means spawn them in order and wait for each to complete before spawning the next.
-## Step 2: Create Feature Branch
+### Why This Matters
-**CRITICAL: Never push directly to main.**
+| Coordinator Work | Worker Work | Consequence of Mixing |
+|-----------------|-------------|----------------------|
+| Sonnet context ($$$) | Disposable context | Expensive context waste |
+| Long-lived state | Task-scoped state | Context exhaustion |
+| Orchestration concerns | Implementation concerns | Mixed concerns |
+| No checkpoints | Checkpoints enabled | No recovery |
+| No learning signals | Outcomes tracked | No improvement |
-```bash
-# Create branch from bead ID or task name
-git checkout -b swarm/<bead-id> # e.g., swarm/trt-buddy-d7d
-# Or for ad-hoc tasks:
-git checkout -b swarm/<short-description> # e.g., swarm/contextual-checkins
+## CRITICAL: NEVER Fetch Documentation Directly
-git push -u origin HEAD
-```
+**â ï¸ COORDINATORS DO NOT CALL RESEARCH TOOLS DIRECTLY**
-## Step 3: Understand the Task
+The following tools are **FORBIDDEN** for coordinators to call:
-If given a bead-id:
+- `repo-crawl_file`, `repo-crawl_readme`, `repo-crawl_search`, `repo-crawl_structure`, `repo-crawl_tree`
+- `repo-autopsy_*` (all variants)
+- `webfetch`, `fetch_fetch`
+- `context7_resolve-library-id`, `context7_get-library-docs`
+- `pdf-brain_search`, `pdf-brain_read`
-```
-beads_query with id=<bead-id>
-```
+**WHY?** These tools dump massive context that exhausts your expensive Sonnet context. Your job is orchestration, not research.
-If given a description, analyze it to understand scope.
+**INSTEAD:** Use `swarm_spawn_researcher` (see Phase 1.5 below) to spawn a researcher worker who:
+- Fetches documentation in disposable context
+- Stores full details in semantic-memory
+- Returns a condensed summary for shared_context
-## Step 4: Decompose into Beads
+## Workflow
-Use the swarm decomposition tool to break down the task:
+### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)
-```
-swarm_decompose with task="<task description>", context="<relevant codebase context>"
-```
+**Before decomposing, clarify the task with the user.**
-This returns a structured decomposition with subtasks. Then create beads_
+Check for flags in the task:
+- `--fast` â Skip questions, use reasonable defaults
+- `--auto` â Zero interaction, heuristic decisions
+- `--confirm-only` â Show plan, get yes/no only
-```
-beads_create_epic with title="<parent task>", subtasks=[{title, description, files, priority}...]
-```
+**Default (no flags): Full Socratic Mode**
-**Decomposition rules:**
+1. **Analyze task for ambiguity:**
+ - Scope unclear? (what's included/excluded)
+ - Strategy unclear? (file-based vs feature-based)
+ - Dependencies unclear? (what needs to exist first)
+ - Success criteria unclear? (how do we know it's done)
-- Each bead should be completable by one agent
-- Beads should be independent (parallelizable) where possible
-- If there are dependencies, use `beads_link_thread` to connect them
-- Aim for 3-7 beads per swarm (too many = coordination overhead)
+2. **If clarification needed, ask ONE question at a time:**
+ ```
+ The task "<task>" needs clarification before I can decompose it.
-## Step 5: Reserve Files
+ **Question:** <specific question>
-For each subtask, reserve the files it will touch:
+ Options:
+ a) <option 1> - <tradeoff>
+ b) <option 2> - <tradeoff>
+ c) <option 3> - <tradeoff>
-```
-agentmail_reserve with project_key=$PWD, agent_name=<YOUR_NAME>, paths=[<files>], reason="<bead-id>"
-```
+ I'd recommend (b) because <reason>. Which approach?
+ ```
-**Conflict prevention:**
+3. **Wait for user response before proceeding**
-- No two agents should edit the same file
-- If overlap exists, merge beads or sequence them
+4. **Iterate if needed** (max 2-3 questions)
-## Step 6: Spawn the Swarm
+**Rules:**
+- ONE question at a time - don't overwhelm
+- Offer concrete options - not open-ended
+- Lead with recommendation - save cognitive load
+- Wait for answer - don't assume
-**CRITICAL: Spawn ALL agents in a SINGLE message with multiple Task calls.**
+### Phase 1: Initialize
+`swarmmail_init(project_path="$PWD", task_description="Swarm: $ARGUMENTS")`
-Use the prompt generator for each subtask:
+### Phase 1.5: Research Phase (FOR COMPLEX TASKS)
-```
-swarm_subtask_prompt with bead_id="<bead-id>", coordinator_name="<YOUR_NAME>", branch="swarm/<parent-id>", files=[<files>], sync_enabled=true
-```
+**â ï¸ If the task requires understanding unfamiliar technologies, APIs, or libraries, spawn a researcher FIRST.**
-Then spawn agents with the generated prompts:
+**DO NOT call documentation tools directly.** Instead:
```
-Task(
- subagent_type="general",
- description="Swarm worker: <bead-title>",
- prompt="<output from swarm_subtask_prompt>"
+// 1. Spawn researcher with explicit tech stack
+swarm_spawn_researcher(
+ research_id="research-nextjs-cache-components",
+ epic_id="<epic-id>",
+ tech_stack=["Next.js 16 Cache Components", "React Server Components"],
+ project_path="$PWD"
)
-```
-
-Spawn ALL agents in parallel in a single response.
-
-## Step 7: Monitor Progress (unless --no-sync)
-
-Check swarm status:
-```
-swarm_status with epic_id="<parent-bead-id>"
-```
-
-Monitor inbox for progress updates:
+// 2. Spawn researcher as Task subagent
+const researchFindings = await Task(subagent_type="swarm/researcher", prompt="<from above>")
+// 3. Researcher returns condensed summary
+// Use this summary in shared_context for workers
```
-agentmail_inbox with project_key=$PWD, agent_name=<YOUR_NAME>
-```
-
-**When you receive progress updates:**
-1. **Review decisions made** - Are agents making compatible choices?
-2. **Check for pattern conflicts** - Different approaches to the same problem?
-3. **Identify shared concerns** - Common blockers or discoveries?
+**When to spawn a researcher:**
+- Task involves unfamiliar framework versions (e.g., Next.js 16 vs 14)
+- Need to compare installed vs latest library APIs
+- Working with experimental/preview features
+- Need architectural guidance from documentation
-**If you spot incompatibilities, broadcast shared context:**
+**When NOT to spawn a researcher:**
+- Using well-known stable APIs (React hooks, Express middleware)
+- Task is purely refactoring existing code
+- You already have relevant findings from semantic-memory or CASS
-```
-agentmail_send with project_key=$PWD, sender_name=<YOUR_NAME>, to=[<agents>], subject="Coordinator Update", body_md="<guidance>", thread_id="<parent-bead-id>", importance="high"
-```
+**Researcher output:**
+- Full findings stored in semantic-memory (searchable by future agents)
+- Condensed 3-5 bullet summary returned for shared_context
-## Step 8: Collect Results
+### Phase 2: Knowledge Gathering (MANDATORY)
-When agents complete, they send completion messages. Summarize the thread:
+**Before decomposing, query ALL knowledge sources:**
```
-agentmail_summarize_thread with project_key=$PWD, thread_id="<parent-bead-id>"
+semantic-memory_find(query="<task keywords>", limit=5) # Past learnings
+cass_search(query="<task description>", limit=5) # Similar past tasks
+skills_list() # Available skills
```
-## Step 9: Complete Swarm
-
-Use the swarm completion tool:
+Synthesize findings into shared_context for workers.
+### Phase 3: Decompose
```
-swarm_complete with epic_id="<parent-bead-id>", summary="<what was accomplished>"
+swarm_select_strategy(task="<task>")
+swarm_plan_prompt(task="<task>", context="<synthesized knowledge>")
+swarm_validate_decomposition(response="<CellTree JSON>")
```
-This:
+### Phase 4: Create Cells
+`hive_create_epic(epic_title="<task>", subtasks=[...])`
-- Verifies all subtasks are closed
-- Releases file reservations
-- Closes the parent bead
-- Syncs beads to git
+### Phase 5: DO NOT Reserve Files
-## Step 10: Create PR
+> **â ï¸ Coordinator NEVER reserves files.** Workers reserve their own files.
+> If coordinator reserves, workers get blocked and swarm stalls.
-```bash
-gh pr create --title "feat: <parent bead title>" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points from swarm results>
+### Phase 6: Spawn Workers for ALL Subtasks (MANDATORY)
-## Beads Completed
-- <bead-id>: <summary>
-- <bead-id>: <summary>
+> **â ï¸ ALWAYS spawn workers, even for sequential tasks.**
+> - Parallel tasks: Spawn ALL in a single message
+> - Sequential tasks: Spawn one, wait for completion, spawn next
-## Files Changed
-<aggregate list>
-
-## Testing
-- [ ] Type check passes
-- [ ] Tests pass (if applicable)
-EOF
-)"
+**For parallel work:**
+```
+// Single message with multiple Task calls
+swarm_spawn_subtask(bead_id_1, epic_id, title_1, files_1, shared_context, project_path="$PWD")
+Task(subagent_type="swarm/worker", prompt="<from above>")
+swarm_spawn_subtask(bead_id_2, epic_id, title_2, files_2, shared_context, project_path="$PWD")
+Task(subagent_type="swarm/worker", prompt="<from above>")
```
-Report summary:
-
-```markdown
-## Swarm Complete: <task>
-
-### PR: #<number>
-
-### Agents Spawned: N
-
-### Beads Closed: N
+**For sequential work:**
+```
+// Spawn worker 1, wait for completion
+swarm_spawn_subtask(bead_id_1, ...)
+const result1 = await Task(subagent_type="swarm/worker", prompt="<from above>")
-### Work Completed
+// THEN spawn worker 2 with context from worker 1
+swarm_spawn_subtask(bead_id_2, ..., shared_context="Worker 1 completed: " + result1)
+const result2 = await Task(subagent_type="swarm/worker", prompt="<from above>")
+```
-- [bead-id]: [summary]
+**NEVER do the work yourself.** Even if it seems faster, spawn a worker.
-### Files Changed
+**IMPORTANT:** Pass `project_path` to `swarm_spawn_subtask` so workers can call `swarmmail_init`.
-- [aggregate list]
-```
+### Phase 7: MANDATORY Review Loop (NON-NEGOTIABLE)
-## Failure Handling
+**â ï¸ AFTER EVERY Task() RETURNS, YOU MUST:**
-If an agent fails:
+1. **CHECK INBOX** - Worker may have sent messages
+ `swarmmail_inbox()`
+ `swarmmail_read_message(message_id=N)`
-- Check its messages: `agentmail_inbox`
-- The bead remains in-progress
-- Manually investigate or re-spawn
+2. **REVIEW WORK** - Generate review with diff
+ `swarm_review(project_key, epic_id, task_id, files_touched)`
-If file conflicts occur:
+3. **EVALUATE** - Does it meet epic goals?
+ - Fulfills subtask requirements?
+ - Serves overall epic goal?
+ - Enables downstream tasks?
+ - Type safety, no obvious bugs?
-- Agent Mail reservations should prevent this
-- If it happens, one agent needs to wait
+4. **SEND FEEDBACK** - Approve or request changes
+ `swarm_review_feedback(project_key, task_id, worker_id, status, issues)`
+
+ **If approved:**
+ - Close cell, spawn next worker
+
+ **If needs_changes:**
+ - `swarm_review_feedback` returns `retry_context` (NOT sends message - worker is dead)
+ - Generate retry prompt: `swarm_spawn_retry(retry_context)`
+ - Spawn NEW worker with Task() using retry prompt
+ - Max 3 attempts before marking task blocked
+
+ **If 3 failures:**
+ - Mark task blocked, escalate to human
-## Direct-to-Main Mode (--to-main)
+5. **ONLY THEN** - Spawn next worker or complete
-Only use when explicitly requested. Skips branch/PR:
+**DO NOT skip this. DO NOT batch reviews. Review EACH worker IMMEDIATELY after return.**
-- Trivial fixes across many files
-- Automated migrations with high confidence
-- User explicitly says "push to main"
+**Intervene if:**
+- Worker blocked >5min â unblock or reassign
+- File conflicts â mediate between workers
+- Scope creep â approve or reject expansion
+- Review fails 3x â mark task blocked, escalate to human
-## No-Sync Mode (--no-sync)
+### Phase 8: Complete
+```
+# After all workers complete and reviews pass:
+hive_sync() # Sync all cells to git
+# Coordinator does NOT call swarm_complete - workers do that
+```
-Skip mid-task context sharing when tasks are truly independent:
+## Strategy Reference
-- Simple mechanical changes (find/replace, formatting, lint fixes)
-- Tasks with zero integration points
-- Completely separate feature areas with no shared types
+| Strategy | Best For | Keywords |
+| -------------- | ------------------------ | -------------------------------------- |
+| file-based | Refactoring, migrations | refactor, migrate, rename, update all |
+| feature-based | New features | add, implement, build, create, feature |
+| risk-based | Bug fixes, security | fix, bug, security, critical, urgent |
+| research-based | Investigation, discovery | research, investigate, explore, learn |
-In this mode:
+## Flag Reference
-- Agents skip the mid-task progress message
-- Coordinator skips Step 7 (monitoring)
-- Faster execution, less coordination overhead
+| Flag | Effect |
+|------|--------|
+| `--fast` | Skip Socratic questions, use defaults |
+| `--auto` | Zero interaction, heuristic decisions |
+| `--confirm-only` | Show plan, get yes/no only |
-**Default is sync ON** - prefer sharing context. Use `--no-sync` deliberately.
+Begin with Phase 0 (Socratic Planning) unless `--fast` or `--auto` flag is present.
diff --git a/command/test.md b/command/test.md
new file mode 100644
index 0000000..e2fde4d
--- /dev/null
+++ b/command/test.md
@@ -0,0 +1,170 @@
+---
+description: Generate comprehensive tests for a file using vitest
+---
+
+Generate tests for a given source file.
+
+## Usage
+
+```
+/test <file-path>
+/test src/utils/parser.ts
+/test --coverage src/services/auth.ts # Focus on coverage gaps
+```
+
+## Step 1: Read the Source File
+
+```bash
+# Read the file to understand what to test
+```
+
+Use the Read tool to get the full file contents.
+
+## Step 2: Analyze the Code
+
+Identify:
+
+- **Exports** - What functions/classes are public?
+- **Dependencies** - What needs mocking?
+- **Edge cases** - Null, empty, boundary conditions
+- **Error paths** - What can throw/fail?
+- **Types** - What are the input/output shapes?
+
+## Step 3: Check Existing Tests
+
+```bash
+# Look for existing test file
+ls -la "${FILE_PATH%.ts}.test.ts" 2>/dev/null || ls -la "${FILE_PATH%.tsx}.test.tsx" 2>/dev/null || echo "No existing tests"
+
+# Or in __tests__ directory
+ls -la "$(dirname $FILE_PATH)/__tests__/$(basename ${FILE_PATH%.ts}).test.ts" 2>/dev/null || echo "No __tests__ file"
+```
+
+## Step 4: Generate Tests
+
+Create comprehensive tests covering:
+
+### Unit Tests
+
+- Happy path for each exported function
+- Edge cases (empty input, null, undefined)
+- Boundary conditions (min/max values)
+- Type coercion scenarios
+
+### Error Cases
+
+- Invalid input handling
+- Exception throwing
+- Error message accuracy
+
+### Integration Points
+
+- Mock external dependencies
+- Test async behavior
+- Verify side effects
+
+## Step 5: Write Test File
+
+Write to adjacent `.test.ts` file (same directory as source):
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { functionName } from './filename'
+
+describe('functionName', () => {
+ describe('happy path', () => {
+ it('should handle basic input', () => {
+ // Arrange
+ const input = ...
+
+ // Act
+ const result = functionName(input)
+
+ // Assert
+ expect(result).toEqual(...)
+ })
+ })
+
+ describe('edge cases', () => {
+ it('should handle empty input', () => {
+ expect(functionName('')).toEqual(...)
+ })
+
+ it('should handle null', () => {
+ expect(() => functionName(null)).toThrow()
+ })
+ })
+
+ describe('error handling', () => {
+ it('should throw on invalid input', () => {
+ expect(() => functionName('invalid')).toThrow('Expected error message')
+ })
+ })
+})
+```
+
+## Step 6: Verify Tests Run
+
+```bash
+# Run the tests
+pnpm test <test-file-path> --run
+
+# Or with vitest directly
+npx vitest run <test-file-path>
+```
+
+## Test Writing Guidelines
+
+- **AAA pattern** - Arrange, Act, Assert
+- **One assertion per test** (when practical)
+- **Descriptive names** - `should return empty array when input is null`
+- **No test interdependence** - Each test should be isolated
+- **Mock at boundaries** - External APIs, filesystem, network
+- **Test behavior, not implementation**
+
+## Mocking Patterns
+
+```typescript
+// Mock a module
+vi.mock("./dependency", () => ({
+ fetchData: vi.fn().mockResolvedValue({ data: "mocked" }),
+}));
+
+// Mock a function
+const mockFn = vi.fn().mockReturnValue("result");
+
+// Spy on object method
+const spy = vi.spyOn(object, "method");
+
+// Mock timers
+vi.useFakeTimers();
+vi.advanceTimersByTime(1000);
+```
+
+## Output
+
+After generating tests, report:
+
+```markdown
+## Tests Generated: [file-path]
+
+### Test File
+
+`[test-file-path]`
+
+### Coverage
+
+- [N] test suites
+- [N] individual tests
+- Functions covered: [list]
+
+### Test Categories
+
+- Happy path: [N] tests
+- Edge cases: [N] tests
+- Error handling: [N] tests
+
+### Run Command
+
+`pnpm test [test-file-path]`
+```
diff --git a/knowledge/effect-patterns.md b/knowledge/effect-patterns.md
index 1b914d2..240eeac 100644
--- a/knowledge/effect-patterns.md
+++ b/knowledge/effect-patterns.md
@@ -38,6 +38,40 @@ const needsDb: Effect.Effect<User, DbError, Database> = Database.findUser(id);
---
+### Effect.fn - Traced Functions
+
+Use `Effect.fn` for named, traced functions with automatic call-site tracking:
+
+```typescript
+// Creates a traced function - shows up in error stack traces
+const processUser = Effect.fn("processUser")(function* (userId: string) {
+ yield* Effect.logInfo(`Processing user ${userId}`);
+ const user = yield* getUser(userId);
+ return yield* processData(user);
+});
+
+// With explicit types
+const fetchData = Effect.fn("fetchData")<
+ [url: string],
+ Data,
+ FetchError,
+ HttpClient
+>(function* (url) {
+ const client = yield* HttpClient;
+ return yield* client.get(url);
+});
+```
+
+**When to use**:
+
+- Service methods that you want traced in errors
+- Functions called from multiple places (easier debugging)
+- Any function where call-site matters for debugging
+
+**Key insight**: `Effect.fn` gives you named stack traces without manual span creation.
+
+---
+
### Effect.gen vs pipe - When to Use Which
**Use `Effect.gen` for**:
@@ -297,6 +331,41 @@ const promoted = pipe(
---
+### Schema.Defect for Unknown Errors
+
+Wrap errors from external libraries that you can't control:
+
+```typescript
+// Schema.Defect wraps unknown errors safely
+class ApiError extends Schema.TaggedError<ApiError>()("ApiError", {
+ endpoint: Schema.String,
+ statusCode: Schema.Number,
+ cause: Schema.Defect, // Wraps unknown errors from fetch, etc.
+}) {}
+
+// Use when catching external library errors
+const fetchUser = (id: string) =>
+ Effect.tryPromise({
+ try: () => fetch(`/api/users/${id}`).then((r) => r.json()),
+ catch: (error) =>
+ new ApiError({
+ endpoint: `/api/users/${id}`,
+ statusCode: 500,
+ cause: error, // Unknown error wrapped safely
+ }),
+ });
+
+// The cause is preserved for debugging but safely typed
+```
+
+**When to use**:
+
+- Wrapping errors from `fetch`, database drivers, etc.
+- When you need to preserve the original error for debugging
+- External library errors that don't have typed errors
+
+---
+
### Effect.orDie, Effect.orElse
```typescript
@@ -421,6 +490,48 @@ const program = pipe(myApp, Effect.provide(FullAppLayer));
---
+### Layer Memoization (IMPORTANT)
+
+Store parameterized layers in constants to avoid duplicate resource construction:
+
+```typescript
+// ✅ GOOD: Single connection pool shared by all services
+const postgresLayer = Postgres.layer({ url: "...", poolSize: 10 });
+
+const appLayer = Layer.merge(
+ UserRepo.layer.pipe(Layer.provide(postgresLayer)),
+ OrderRepo.layer.pipe(Layer.provide(postgresLayer)),
+);
+// Both repos share the SAME pool
+
+// ❌ BAD: Creates TWO separate connection pools!
+const appLayerBad = Layer.merge(
+ UserRepo.layer.pipe(
+ Layer.provide(Postgres.layer({ url: "...", poolSize: 10 })),
+ ),
+ OrderRepo.layer.pipe(
+ Layer.provide(Postgres.layer({ url: "...", poolSize: 10 })),
+ ),
+);
+// Each repo gets its own pool - resource waste!
+
+// ✅ GOOD: Memoize expensive layers
+const ExpensiveServiceLive = Layer.effect(
+ ExpensiveService,
+ Effect.gen(function* () {
+ yield* Effect.logInfo("Initializing expensive service...");
+ // This should only run ONCE
+ return {
+ /* ... */
+ };
+ }),
+).pipe(Layer.memoize); // Explicit memoization
+```
+
+**Key insight**: Layer construction is NOT automatically memoized. If you inline `Layer.effect(...)` in multiple places, it runs multiple times. Extract to a constant or use `Layer.memoize`.
+
+---
+
### Testing with Test Layers
```typescript
@@ -916,6 +1027,39 @@ const testProgram = pipe(
---
+### Config.redacted for Secrets
+
+Use `Config.redacted` for sensitive values that shouldn't appear in logs:
+
+```typescript
+import { Config, Redacted } from "effect";
+
+// Define secret config
+const SecureConfig = Config.all({
+ apiKey: Config.redacted("API_KEY"), // Hidden in logs
+ dbPassword: Config.redacted("DB_PASSWORD"),
+ publicUrl: Config.string("PUBLIC_URL"), // Normal, can be logged
+});
+
+// Use in effect
+const program = Effect.gen(function* () {
+ const config = yield* SecureConfig;
+
+ // Extract the actual value when needed
+ const headers = {
+ Authorization: `Bearer ${Redacted.value(config.apiKey)}`,
+ };
+
+ // Safe to log - shows <redacted>
+ yield* Effect.logInfo(`Config loaded: ${config.apiKey}`);
+ // Output: Config loaded: <redacted>
+});
+```
+
+**Key insight**: `Redacted.value()` extracts the secret, but the Redacted wrapper prevents accidental logging.
+
+---
+
## Common Gotchas
### Never-Terminating Effects
diff --git a/knowledge/git-patterns.md b/knowledge/git-patterns.md
new file mode 100644
index 0000000..4c2a0c4
--- /dev/null
+++ b/knowledge/git-patterns.md
@@ -0,0 +1,722 @@
+# Git Patterns
+
+Git workflows, commands, and recovery patterns. Practical reference for day-to-day work.
+
+## How to Use This File
+
+1. **Daily work**: Quick reference for common operations
+2. **Recovery**: When things go wrong, check Reflog and Recovery section
+3. **Collaboration**: Guidelines for branches, merges, PRs
+4. **Debugging**: Git bisect and blame patterns
+
+---
+
+## Rebase vs Merge
+
+### When to Rebase
+
+**Use rebase for:**
+
+- Cleaning up local commits before pushing
+- Updating feature branch with main
+- Keeping linear history on feature branches
+- Squashing work-in-progress commits
+
+```bash
+# Update feature branch with latest main
+git checkout feature-branch
+git fetch origin
+git rebase origin/main
+
+# If conflicts, resolve then continue
+git add .
+git rebase --continue
+
+# Or abort if things go wrong
+git rebase --abort
+```
+
+### When to Merge
+
+**Use merge for:**
+
+- Integrating feature branches into main
+- Preserving branch history for audit
+- Collaborative branches where others have pulled
+
+```bash
+# Merge feature into main
+git checkout main
+git merge feature-branch
+
+# Merge with no fast-forward (creates merge commit)
+git merge --no-ff feature-branch
+
+# Squash merge (all commits become one)
+git merge --squash feature-branch
+git commit -m "feat: add feature X"
+```
+
+### The Golden Rule
+
+**Never rebase public/shared branches.** If others have pulled the branch, rebasing rewrites history they depend on.
+
+```bash
+# SAFE - rebasing local commits not yet pushed
+git rebase -i HEAD~3
+
+# DANGEROUS - rebasing after push
+git push --force # 🚩 Breaks everyone else's checkout
+git push --force-with-lease # Safer, but still dangerous on shared branches
+```
+
+---
+
+## Interactive Rebase
+
+### Cleaning Up Commits
+
+```bash
+# Rebase last 5 commits
+git rebase -i HEAD~5
+
+# Rebase from branch point
+git rebase -i main
+```
+
+**Interactive rebase options:**
+
+```
+pick - keep commit as-is
+reword - change commit message
+edit - stop to amend commit
+squash - meld into previous commit
+fixup - like squash but discard message
+drop - remove commit
+```
+
+### Common Workflows
+
+```bash
+# Squash all commits into one
+git rebase -i main
+# Change all but first 'pick' to 'squash'
+
+# Reorder commits
+git rebase -i HEAD~3
+# Move lines to reorder
+
+# Split a commit
+git rebase -i HEAD~3
+# Mark commit as 'edit', then:
+git reset HEAD~
+git add -p # Stage in parts
+git commit -m "first part"
+git add .
+git commit -m "second part"
+git rebase --continue
+```
+
+### Fixup Commits
+
+```bash
+# Create a fixup commit for an earlier commit
+git commit --fixup=abc123
+
+# Later, auto-squash all fixups
+git rebase -i --autosquash main
+```
+
+---
+
+## Git Bisect
+
+### Finding the Bug
+
+```bash
+# Start bisecting
+git bisect start
+
+# Mark current state
+git bisect bad # Current commit is broken
+
+# Mark known good commit
+git bisect good v1.0.0 # This version worked
+
+# Git checks out middle commit
+# Test if bug exists, then:
+git bisect good # Bug not present
+# or
+git bisect bad # Bug is present
+
+# Repeat until found
+# Git tells you the first bad commit
+
+# Clean up when done
+git bisect reset
+```
+
+### Automated Bisect
+
+```bash
+# Run a test script automatically
+git bisect start HEAD v1.0.0
+git bisect run npm test
+
+# Or with a custom script
+git bisect run ./test-for-bug.sh
+
+# Script should exit 0 for good, 1 for bad
+```
+
+### Bisect with Skip
+
+```bash
+# If a commit can't be tested (build broken, etc.)
+git bisect skip
+
+# Skip a range of commits
+git bisect skip v1.0.0..v1.0.5
+```
+
+---
+
+## Git Worktrees
+
+### Why Worktrees
+
+**Problem:** Need to work on multiple branches simultaneously without stashing or committing WIP.
+
+**Solution:** Git worktrees create separate working directories sharing the same repo.
+
+```bash
+# Create worktree for a branch
+git worktree add ../project-hotfix hotfix-branch
+
+# Create worktree with new branch
+git worktree add -b feature-x ../project-feature-x main
+
+# List worktrees
+git worktree list
+
+# Remove worktree when done
+git worktree remove ../project-hotfix
+```
+
+### Worktree Workflow
+
+```bash
+# Main repo structure
+~/projects/myapp/ # main branch
+~/projects/myapp-feature/ # feature branch
+~/projects/myapp-hotfix/ # hotfix branch
+
+# Work in parallel without switching
+cd ~/projects/myapp-feature
+# ... work on feature ...
+
+cd ~/projects/myapp-hotfix
+# ... fix bug ...
+
+cd ~/projects/myapp
+# ... continue main work ...
+```
+
+### Worktree with OpenCode
+
+```bash
+# Create worktree for a bead task
+bd=$(bd ready --json | jq -r '.[0].id')
+git worktree add -b "bd/$bd" "../$(basename $PWD)-$bd" main
+
+# Work in isolated worktree
+cd "../$(basename $PWD)-$bd"
+bd start "$bd"
+# ... do work ...
+
+# Clean up when done
+cd ..
+git worktree remove "./$(basename $PWD)-$bd"
+```
+
+---
+
+## Stash Workflows
+
+### Basic Stash
+
+```bash
+# Stash current changes
+git stash
+
+# Stash with message
+git stash save "WIP: feature description"
+
+# Stash including untracked files
+git stash -u
+git stash --include-untracked
+
+# Stash everything including ignored
+git stash -a
+git stash --all
+```
+
+### Managing Stashes
+
+```bash
+# List stashes
+git stash list
+
+# Apply most recent stash (keep in stash)
+git stash apply
+
+# Apply and remove from stash
+git stash pop
+
+# Apply specific stash
+git stash apply stash@{2}
+
+# Show stash contents
+git stash show -p stash@{0}
+
+# Drop a stash
+git stash drop stash@{1}
+
+# Clear all stashes
+git stash clear
+```
+
+### Stash Specific Files
+
+```bash
+# Stash only specific files
+git stash push -m "partial stash" path/to/file1.ts path/to/file2.ts
+
+# Stash with patch (interactive)
+git stash -p
+```
+
+### Creating Branch from Stash
+
+```bash
+# Create branch from stash
+git stash branch new-feature-branch stash@{0}
+# Checks out commit where stash was created,
+# creates branch, applies stash, drops stash
+```
+
+---
+
+## Cherry-Pick
+
+### Basic Cherry-Pick
+
+```bash
+# Apply a specific commit to current branch
+git cherry-pick abc123
+
+# Cherry-pick multiple commits
+git cherry-pick abc123 def456 ghi789
+
+# Cherry-pick a range (exclusive start, inclusive end)
+git cherry-pick abc123..def456
+
+# Cherry-pick without committing (stage only)
+git cherry-pick -n abc123
+```
+
+### Cherry-Pick Strategies
+
+```bash
+# Continue after resolving conflicts
+git cherry-pick --continue
+
+# Abort cherry-pick
+git cherry-pick --abort
+
+# Skip current commit and continue
+git cherry-pick --skip
+
+# Preserve original author
+git cherry-pick -x abc123 # Adds "(cherry picked from commit ...)"
+```
+
+### When to Cherry-Pick
+
+**Good uses:**
+
+- Backporting bug fixes to release branches
+- Pulling specific commits from abandoned branches
+- Applying hotfixes across versions
+
+**Avoid when:**
+
+- You need all commits from a branch (merge instead)
+- Commits have dependencies on other commits
+
+---
+
+## Reflog and Recovery
+
+### The Safety Net
+
+**Reflog records every change to HEAD.** Even "deleted" commits are recoverable for ~90 days.
+
+```bash
+# View reflog
+git reflog
+
+# Output shows:
+# abc123 HEAD@{0}: commit: add feature
+# def456 HEAD@{1}: checkout: moving from main to feature
+# ghi789 HEAD@{2}: rebase: finished
+```
+
+### Recovery Patterns
+
+```bash
+# Recover from bad rebase
+git reflog
+# Find the commit before rebase started
+git reset --hard HEAD@{5}
+
+# Recover deleted branch
+git reflog
+# Find last commit on that branch
+git checkout -b recovered-branch abc123
+
+# Recover dropped stash
+git fsck --no-reflog | grep commit
+# Find orphaned commits, create branch from them
+
+# Undo a reset
+git reset --hard HEAD@{1}
+
+# Recover amended commit's original
+git reflog
+git show HEAD@{1} # See original before amend
+```
+
+### Dangerous Operations and Recovery
+
+```bash
+# BEFORE doing something scary, note current HEAD
+git rev-parse HEAD # Save this hash somewhere
+
+# If something goes wrong
+git reset --hard <saved-hash>
+```
+
+---
+
+## Commit Message Conventions
+
+### Conventional Commits
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types:**
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, no code change
+- `refactor`: Code change that neither fixes bug nor adds feature
+- `perf`: Performance improvement
+- `test`: Adding or fixing tests
+- `chore`: Build process, tools, dependencies
+- `ci`: CI configuration
+- `revert`: Revert previous commit
+
+### Examples
+
+```bash
+# Simple
+git commit -m "feat: add user authentication"
+git commit -m "fix: resolve race condition in cache"
+git commit -m "docs: update API documentation"
+
+# With scope
+git commit -m "feat(auth): add OAuth2 support"
+git commit -m "fix(api): handle null response from server"
+
+# With body
+git commit -m "refactor(db): optimize query performance
+
+Reduce N+1 queries in user listing by eager loading
+associations. Improves response time by 60%."
+
+# Breaking change
+git commit -m "feat(api)!: change response format
+
+BREAKING CHANGE: API now returns { data, meta } wrapper
+instead of raw array."
+
+# With issue reference
+git commit -m "fix(auth): session timeout handling
+
+Fixes #123"
+```
+
+### Beads Integration
+
+```bash
+# Reference bead in commit
+git commit -m "feat: add search functionality
+
+Implements full-text search with Elasticsearch.
+
+Bead: bd-abc123"
+
+# Multiple beads
+git commit -m "fix: resolve conflicts in merge
+
+Fixes bd-def456
+Related: bd-ghi789"
+```
+
+---
+
+## Advanced Patterns
+
+### Partial Staging
+
+```bash
+# Stage parts of a file interactively
+git add -p
+
+# Options:
+# y - stage this hunk
+# n - skip this hunk
+# s - split into smaller hunks
+# e - manually edit hunk
+# q - quit
+
+# Unstage parts
+git reset -p
+
+# Checkout parts (discard changes)
+git checkout -p
+```
+
+### Finding Things
+
+```bash
+# Find commit by message
+git log --grep="search term"
+
+# Find commits that changed a string
+git log -S "function_name" --source --all
+
+# Find commits that changed a file
+git log --follow -- path/to/file
+
+# Find who changed a line
+git blame path/to/file
+git blame -L 10,20 path/to/file # Lines 10-20
+
+# Find when line was introduced
+git log -p -S "the exact line" -- path/to/file
+```
+
+### Cleaning Up
+
+```bash
+# Remove untracked files (dry run)
+git clean -n
+
+# Remove untracked files
+git clean -f
+
+# Remove untracked files and directories
+git clean -fd
+
+# Remove ignored files too
+git clean -fdx
+
+# Interactive clean
+git clean -i
+```
+
+### Rewriting History
+
+```bash
+# Change last commit message
+git commit --amend -m "new message"
+
+# Add to last commit without changing message
+git add forgotten-file.ts
+git commit --amend --no-edit
+
+# Change author of last commit
+git commit --amend --author="Name <email@example.com>"
+
+# Reset author to current config
+git commit --amend --reset-author
+```
+
+### Tags
+
+```bash
+# Create lightweight tag
+git tag v1.0.0
+
+# Create annotated tag (recommended)
+git tag -a v1.0.0 -m "Release version 1.0.0"
+
+# Tag specific commit
+git tag -a v1.0.0 abc123 -m "Release"
+
+# Push tags
+git push origin v1.0.0
+git push --tags # All tags
+
+# Delete tag
+git tag -d v1.0.0
+git push origin --delete v1.0.0
+```
+
+---
+
+## Useful Aliases
+
+Add to `~/.gitconfig`:
+
+```ini
+[alias]
+ # Shortcuts
+ co = checkout
+ br = branch
+ ci = commit
+ st = status
+
+ # Logging
+ lg = log --oneline --graph --decorate
+ ll = log --oneline -15
+ recent = branch --sort=-committerdate --format='%(committerdate:relative)%09%(refname:short)'
+
+ # Working with changes
+ unstage = reset HEAD --
+ discard = checkout --
+ amend = commit --amend --no-edit
+
+ # Diffs
+ staged = diff --cached
+ both = diff HEAD
+
+ # Stash shortcuts
+ ss = stash save
+ sp = stash pop
+ sl = stash list
+
+ # Branch cleanup
+ gone = "!git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -r git branch -d"
+
+ # Find stuff
+ find = "!git log --all --source -S"
+
+ # Sync with upstream
+ sync = "!git fetch origin && git rebase origin/main"
+```
+
+---
+
+## Troubleshooting
+
+### Merge Conflicts
+
+```bash
+# See conflicted files
+git status
+
+# Use mergetool
+git mergetool
+
+# Accept theirs completely
+git checkout --theirs path/to/file
+
+# Accept ours completely
+git checkout --ours path/to/file
+
+# Abort merge
+git merge --abort
+```
+
+### Detached HEAD
+
+```bash
+# You're not on a branch
+# To save your work:
+git checkout -b new-branch-name
+
+# To discard and go back to a branch:
+git checkout main
+```
+
+### Undoing Things
+
+```bash
+# Undo last commit, keep changes staged
+git reset --soft HEAD~1
+
+# Undo last commit, keep changes unstaged
+git reset HEAD~1
+git reset --mixed HEAD~1 # Same thing
+
+# Undo last commit, discard changes
+git reset --hard HEAD~1
+
+# Undo a pushed commit (creates new commit)
+git revert abc123
+
+# Undo a merge commit
+git revert -m 1 abc123 # Keep main branch's side
+```
+
+### Push Rejected
+
+```bash
+# Remote has new commits
+git pull --rebase origin main
+git push
+
+# Branch protection won't allow push
+# Create PR instead, or check branch rules
+
+# Force push needed (only on your own branches!)
+git push --force-with-lease
+```
+
+---
+
+## Adding New Patterns
+
+When you discover a new git pattern:
+
+1. **Identify the situation**: What problem were you solving?
+2. **Document the commands**: Step-by-step with explanations
+3. **Note warnings**: What could go wrong?
+4. **Show recovery**: How to undo if needed
+
+```markdown
+### Pattern Name
+
+**Situation:** When you need to...
+
+\`\`\`bash
+
+# Commands with explanations
+
+git command --flag # What this does
+\`\`\`
+
+**Gotcha:** Watch out for...
+
+**Recovery:** If something goes wrong...
+```
diff --git a/knowledge/opencode-agents.md b/knowledge/opencode-agents.md
new file mode 100644
index 0000000..f2963c3
--- /dev/null
+++ b/knowledge/opencode-agents.md
@@ -0,0 +1,395 @@
+# OpenCode Agent System Analysis
+
+## Executive Summary
+
+OpenCode implements a sophisticated agent/subagent system with context isolation, model routing, and tool restriction. Key findings:
+
+1. **Task Tool** spawns subagents via `SessionPrompt.prompt()` with isolated sessions
+2. **Model routing** via agent config (fallback to parent model)
+3. **Context isolation** through parent/child session tracking
+4. **Built-in agents**: general, explore, build, plan
+5. **Tool restrictions** via agent-specific permissions and tool maps
+
+## 1. Subagent Spawning (Task Tool)
+
+### Implementation: `packages/opencode/src/tool/task.ts`
+
+**Core mechanism:**
+
+```typescript
+// Create new session with parentID link
+const session = await Session.create({
+ parentID: ctx.sessionID,
+ title: params.description + ` (@${agent.name} subagent)`,
+});
+
+// Spawn agent with isolated context
+const result = await SessionPrompt.prompt({
+ messageID,
+ sessionID: session.id,
+ model: { modelID, providerID },
+ agent: agent.name,
+ tools: {
+ todowrite: false,
+ todoread: false,
+ task: false, // Prevent recursive task spawning
+ ...agent.tools,
+ },
+ parts: promptParts,
+});
+```
+
+**Key features:**
+
+- **Session hierarchy**: Child sessions track `parentID` for lineage
+- **Metadata streaming**: Tool call progress from child flows to parent via `Bus.subscribe(MessageV2.Event.PartUpdated)`
+- **Cancellation**: Parent abort signal propagates to child
+- **Result format**: Returns text + `<task_metadata>` with `session_id` for continuation
+
+**Comparison to our swarm:**
+
+- OpenCode: Single task tool, generic agent selection
+- Us: Specialized `swarm_spawn_subtask` with BeadTree decomposition, Agent Mail coordination, file reservations
+
+## 2. Model Routing
+
+### Agent Model Selection: `packages/opencode/src/agent/agent.ts`
+
+**Priority order:**
+
+1. Agent-specific model (if configured)
+2. Parent message model (inherited)
+3. Default model (from config)
+
+```typescript
+// Line 78-81 in task.ts
+const model = agent.model ?? {
+ modelID: msg.info.modelID,
+ providerID: msg.info.providerID,
+};
+```
+
+**Agent config schema:**
+
+```typescript
+export const Info = z.object({
+ name: z.string(),
+ model: z
+ .object({
+ modelID: z.string(),
+ providerID: z.string(),
+ })
+ .optional(),
+ temperature: z.number().optional(),
+ topP: z.number().optional(),
+ // ...
+});
+```
+
+**Comparison to our agents:**
+
+- OpenCode: Optional model override per agent
+- Us: Explicit model in frontmatter (`model: anthropic/claude-sonnet-4-5`)
+
+## 3. Agent Context Isolation
+
+### Session System: `packages/opencode/src/session/`
+
+**Message threading:**
+
+```typescript
+export const Assistant = z.object({
+ id: z.string(),
+ sessionID: z.string(),
+ parentID: z.string(), // Links to user message
+ modelID: z.string(),
+ providerID: z.string(),
+ mode: z.string(), // Agent name
+ // ...
+});
+```
+
+**Context boundaries:**
+
+- Each agent gets fresh `Session.create()` with isolated message history
+- Tool results stay in child session unless explicitly returned
+- Parent sees summary metadata, not full tool output
+- Child can continue via `session_id` parameter (stateful resumption)
+
+**Context leakage prevention:**
+
+- Tool outputs not visible to parent by default
+- Agent must explicitly include results in final text response
+- Summary metadata extracted from completed tool parts
+
+**Comparison to our swarm:**
+
+- OpenCode: Implicit isolation via sessions, manual result passing
+- Us: Explicit Agent Mail messages, file reservations, swarm coordination metadata
+
+## 4. Built-in Agent Types
+
+### Defined in `packages/opencode/src/agent/agent.ts` lines 103-169
+
+| Agent | Mode | Description | Tool Restrictions |
+| ----------- | ---------- | ----------------------------------------------------- | ------------------------------------------------------- |
+| **general** | `subagent` | General-purpose multi-step research and parallel work | No todo tools |
+| **explore** | `subagent` | Fast codebase search specialist | **Read-only**: no edit/write tools |
+| **build** | `primary` | Full access for building/coding | All tools enabled |
+| **plan** | `primary` | Planning with restricted bash | **Limited bash**: only read-only git/grep/find commands |
+
+### Agent Permissions System
+
+**Two-level control:**
+
+1. **Tool map** (boolean enable/disable):
+
+```typescript
+tools: {
+ edit: false,
+ write: false,
+ todoread: false,
+ todowrite: false,
+}
+```
+
+2. **Permission patterns** (allow/deny/ask):
+
+```typescript
+permission: {
+ edit: "deny",
+ bash: {
+ "git log*": "allow",
+ "find * -delete*": "ask",
+ "*": "deny",
+ },
+ webfetch: "allow",
+ doom_loop: "ask",
+ external_directory: "ask",
+}
+```
+
+**Plan agent bash restrictions** (lines 57-101):
+
+- **Allow**: grep, rg, find (non-destructive), git log/show/diff/status, ls, tree, wc, head, tail
+- **Ask**: find -delete/-exec, sort -o, tree -o
+- **Default**: ask for all others
+
+**Comparison to our agents:**
+
+- OpenCode: Dual control (tool map + permission patterns)
+- Us: Single YAML frontmatter with tool boolean flags and bash pattern matching
+
+### Our Agents
+
+| Agent | Mode | Model | Tool Restrictions |
+| ----------------- | ---------- | ----------------- | ---------------------------------------------------------------------------------- |
+| **swarm/worker** | `subagent` | claude-sonnet-4-5 | _(none specified - inherits default)_ |
+| **swarm/planner** | `subagent` | claude-opus-4-5 | _(none specified)_ |
+| **archaeologist** | `subagent` | claude-sonnet-4-5 | **Read-only**: write/edit false, limited bash (rg, git log/show/blame, tree, find) |
+
+## 5. Response Processing
+
+### SessionProcessor: `packages/opencode/src/session/processor.ts`
+
+**Stream handling:**
+
+1. **Reasoning chunks** (extended thinking):
+ - `reasoning-start` → create part
+ - `reasoning-delta` → stream text updates
+ - `reasoning-end` → finalize with metadata
+
+2. **Tool calls**:
+ - `tool-input-start` → create pending part
+ - `tool-call` → update to running + doom loop detection
+ - `tool-result` → update to completed + store output
+
+3. **Doom loop detection** (lines ~120-170):
+ - Tracks last 3 tool calls
+ - If same tool + same input 3 times → ask permission or deny
+ - Configurable via `permission.doom_loop: "ask" | "deny" | "allow"`
+
+**Result aggregation:**
+
+```typescript
+const summary = messages
+ .filter((x) => x.info.role === "assistant")
+ .flatMap((msg) => msg.parts.filter((x) => x.type === "tool"))
+ .map((part) => ({
+ id: part.id,
+ tool: part.tool,
+ state: {
+ status: part.state.status,
+ title: part.state.title,
+ },
+ }));
+```
+
+**Comparison to our swarm:**
+
+- OpenCode: Generic stream processor for all agents
+- Us: `swarm_complete` custom handling with UBS scan, reservation release, outcome recording
+
+## 6. Configuration & Extension
+
+### Agent Configuration: `opencode.jsonc` or `agent/*.md`
+
+**JSONC format:**
+
+```json
+{
+ "agent": {
+ "my-agent": {
+ "description": "Custom agent for X",
+ "model": "anthropic/claude-sonnet-4",
+ "mode": "subagent",
+ "tools": {
+ "edit": false
+ },
+ "permission": {
+ "bash": {
+ "*": "deny"
+ }
+ },
+ "temperature": 0.2,
+ "top_p": 0.9
+ }
+ }
+}
+```
+
+**Markdown format** (our approach):
+
+```yaml
+---
+name: my-agent
+description: Custom agent for X
+mode: subagent
+model: anthropic/claude-sonnet-4
+temperature: 0.2
+tools:
+ edit: false
+permission:
+ bash:
+ "*": deny
+---
+# Agent Instructions
+...
+```
+
+### Config Loading Priority
+
+1. Global config (`~/.config/opencode/opencode.jsonc`)
+2. Project config (searched up from working dir)
+3. Agent markdown files (`agent/`, `mode/` dirs)
+4. Environment flags (`OPENCODE_CONFIG`, `OPENCODE_CONFIG_CONTENT`)
+
+**Merge behavior**: Deep merge with plugin array concatenation
+
+## 7. Key Differences: OpenCode vs Our Swarm
+
+| Aspect | OpenCode | Our Swarm |
+| --------------------- | --------------------------------- | ---------------------------------------------- |
+| **Spawning** | Generic Task tool | Specialized swarm tools + BeadTree |
+| **Coordination** | Implicit via sessions | Explicit Agent Mail messages |
+| **File conflicts** | Not detected | Pre-spawn validation + reservations |
+| **Model routing** | Config override or inherit | Explicit frontmatter |
+| **Tool restrictions** | Boolean map + permission patterns | Boolean map + bash patterns |
+| **Result passing** | Manual text summary | Structured swarm_complete |
+| **Learning** | None | Outcome tracking + pattern maturity |
+| **Built-in agents** | 4 (general, explore, build, plan) | 3 (swarm/worker, swarm/planner, archaeologist) |
+
+## 8. Implementation Insights
+
+### What OpenCode Does Well
+
+1. **Clean abstraction**: `Task` tool is single entry point for all subagents
+2. **Stream metadata**: Real-time progress from child to parent
+3. **Doom loop protection**: Prevents infinite tool call cycles
+4. **Permission granularity**: Wildcard patterns for bash commands
+5. **Session hierarchy**: Clear parent/child tracking
+
+### What Our Swarm Does Better
+
+1. **Pre-spawn validation**: Detects file conflicts before spawning
+2. **Structured coordination**: Agent Mail vs manual result passing
+3. **Learning integration**: Outcome recording, pattern maturity
+4. **Bug scanning**: Auto UBS scan on completion
+5. **Explicit decomposition**: BeadTree JSON vs ad-hoc task descriptions
+
+### Opportunities
+
+1. **Adopt doom loop detection**: Track repeated tool calls with same args
+2. **Stream progress metadata**: Real-time updates from workers to planner
+3. **Session hierarchy**: Consider `parentID` tracking for swarm sessions
+4. **Permission patterns**: Bash wildcard patterns for finer control
+5. **Built-in explore agent**: Fast read-only search specialist
+
+## 9. Code Paths
+
+### Task Spawning
+
+```
+User message
+ → Primary agent uses Task tool
+ → task.ts:14 TaskTool.define()
+ → task.ts:39 Session.create({ parentID })
+ → task.ts:91 SessionPrompt.prompt()
+ → prompt.ts:~300 streamText() with agent.tools
+ → processor.ts:~50 SessionProcessor.create()
+ → Tool execution in child session
+ → Bus.subscribe() streams to parent
+```
+
+### Model Selection
+
+```
+Agent config load
+ → config.ts:~60 state() merges configs
+ → agent.ts:~170 builds agent registry
+ → task.ts:78 agent.model ?? msg.modelID
+ → prompt.ts:~200 Provider.getModel()
+```
+
+### Permission Check
+
+```
+Tool call
+ → processor.ts:~120 tool-call event
+ → Permission.ask() if doom loop detected
+ → Agent.permission.doom_loop: "ask"|"deny"|"allow"
+```
+
+## 10. Open Questions
+
+1. **How do they handle swarm-like parallelism?**
+ - Answer: Multiple Task tool calls in single message (line 19 in task.txt: "Launch multiple agents concurrently")
+
+2. **Do they track learning/outcomes?**
+ - Answer: No - no outcome tracking or pattern maturity system found
+
+3. **How do they prevent file conflicts?**
+ - Answer: They don't - no pre-spawn file conflict detection
+
+4. **Can subagents spawn subagents?**
+ - Answer: No - `task: false` in subagent tool map (task.ts:102)
+
+## 11. Actionable Takeaways
+
+### For Immediate Adoption
+
+1. ✅ **Doom loop detection**: Add to swarm_complete
+2. ✅ **Permission wildcards**: Enhance archaeologist bash permissions
+3. ✅ **Explore agent**: Create fast read-only search specialist
+
+### For Future Consideration
+
+1. **Session hierarchy**: Add `parentID` to swarm sessions for traceability
+2. **Stream metadata**: Real-time worker progress via Agent Mail streaming
+3. **Tool result aggregation**: Summary format like OpenCode's tool state tracking
+
+### Not Needed (We Do Better)
+
+- ❌ Generic task tool (our decomposition is superior)
+- ❌ Manual result passing (Agent Mail is structured)
+- ❌ No learning system (we track outcomes)
diff --git a/knowledge/opencode-context.md b/knowledge/opencode-context.md
new file mode 100644
index 0000000..dc24203
--- /dev/null
+++ b/knowledge/opencode-context.md
@@ -0,0 +1,439 @@
+# OpenCode Session & Context Management
+
+Deep analysis of sst/opencode session, context window, and history management from repo autopsy.
+
+## Storage Architecture
+
+**Location**: `~/.local/share/opencode/storage/` (or `Global.Path.data`)
+
+**File-based JSON storage** with hierarchical keys:
+
+```
+storage/
+├── session/{projectID}/{sessionID}.json # Session metadata
+├── message/{sessionID}/{messageID}.json # Message info
+├── part/{messageID}/{partID}.json # Message parts (text, tool calls, etc.)
+├── session_diff/{sessionID}.json # File diffs for session
+└── share/{sessionID}.json # Share info (if shared)
+```
+
+**Key characteristics**:
+
+- Uses Bun.Glob for fast scanning
+- Locking via `Lock.read()`/`Lock.write()` for concurrency
+- Migration system for schema changes (see `MIGRATIONS` array)
+- All writes are formatted JSON (`JSON.stringify(content, null, 2)`)
+- Identifiers are descending timestamps for sessions, ascending for messages/parts
+
+## Session Lifecycle
+
+### Creation
+
+```typescript
+Session.create({ parentID?, title? })
+ → createNext({ id, title, parentID, directory })
+ → Storage.write(["session", projectID, sessionID], sessionInfo)
+ → Auto-share if config.share === "auto" or OPENCODE_AUTO_SHARE flag
+```
+
+**Session.Info structure**:
+
+- `id`: Descending identifier (newest first)
+- `projectID`: Git root commit hash (for project identity)
+- `directory`: Working directory (may differ from git root)
+- `parentID`: For forked/child sessions
+- `title`: Auto-generated or custom
+- `version`: CLI version that created it
+- `time.created`, `time.updated`, `time.compacting`: Timestamps
+- `summary`: { additions, deletions, files, diffs? }
+- `share`: { url } if shared
+- `revert`: Snapshot info for revert capability
+
+### Message Flow
+
+1. **User message** created via `SessionPrompt.prompt()`
+2. Parts added (text, file, agent, subtask)
+3. System prompt constructed (`SystemPrompt.*`)
+4. **Assistant message** created, processor streams response
+5. Parts updated as stream chunks arrive (text deltas, tool calls)
+6. Token usage calculated from `LanguageModelUsage`
+7. Cost computed from model pricing
+8. Summary generated asynchronously
+
+## Context Window Management
+
+### Token Estimation
+
+**Ultra-simple**: `Token.estimate(text) = Math.round(text.length / 4)`
+
+- No actual tokenizer, just character count / 4
+- Used for pruning decisions, not precise
+
+### Output Token Budget
+
+```typescript
+OUTPUT_TOKEN_MAX = 32_000;
+```
+
+Adjustable per model:
+
+```typescript
+const output = Math.min(model.limit.output, OUTPUT_TOKEN_MAX);
+const usable = model.limit.context - output;
+```
+
+### Overflow Detection
+
+```typescript
+SessionCompaction.isOverflow({ tokens, model });
+```
+
+Triggers when:
+
+```typescript
+const count = tokens.input + tokens.cache.read + tokens.output;
+const usable = context - output;
+return count > usable;
+```
+
+Disabled via `OPENCODE_DISABLE_AUTOCOMPACT` flag.
+
+### Compaction Strategy (Auto-Summarization)
+
+**When triggered**:
+
+- Automatically when `isOverflow()` returns true
+- Manually via compaction part in user message
+- Creates a new assistant message with `summary: true`
+
+**Process** (`SessionCompaction.process`):
+
+1. Takes existing conversation messages
+2. Filters out aborted/error-only messages
+3. Sends to model with special system prompt:
+ ```
+ "Summarize our conversation above. This summary will be the only
+ context available when the conversation continues, so preserve
+ critical information including: what was accomplished, current
+ work in progress, files involved, next steps, and any key user
+ requests or constraints. Be concise but detailed enough that
+ work can continue seamlessly."
+ ```
+4. Creates assistant message with `summary: true` flag
+5. If `auto: true` and model continues, adds synthetic "Continue if you have next steps"
+
+**filterCompacted()**: When loading history, stops at first completed compaction:
+
+```typescript
+// Streams messages backwards (newest first)
+// Stops when it hits a user message with compaction part
+// that has a completed summary assistant response
+```
+
+### Pruning (Tool Output Truncation)
+
+**Separate from compaction** - runs after every conversation loop.
+
+**Strategy**:
+
+```typescript
+PRUNE_MINIMUM = 20_000; // tokens
+PRUNE_PROTECT = 40_000; // tokens
+```
+
+**Algorithm**:
+
+1. Iterate backwards through messages (latest first)
+2. Skip first 2 user turns (keep recent context)
+3. Stop if hit a summary message (already compacted)
+4. Count tool output tokens until reaching `PRUNE_PROTECT` (40k)
+5. Mark older tool outputs as pruned if total exceeds `PRUNE_MINIMUM` (20k)
+6. Pruned outputs replaced with `"[Old tool result content cleared]"` in `toModelMessage()`
+
+**Disabled via**: `OPENCODE_DISABLE_PRUNE` flag
+
+## System Prompt Construction
+
+**Built in layers** (see `resolveSystemPrompt()`):
+
+### 1. Header (Provider-specific spoofing)
+
+```typescript
+SystemPrompt.header(providerID);
+// For Anthropic: PROMPT_ANTHROPIC_SPOOF
+// Others: empty
+```
+
+### 2. Core Provider Prompt
+
+```typescript
+SystemPrompt.provider(model);
+```
+
+Maps model API ID to prompt file:
+
+- `gpt-5` → `codex.txt`
+- `gpt-*`, `o1`, `o3` → `beast.txt`
+- `gemini-*` → `gemini.txt`
+- `claude` → `anthropic.txt`
+- `polaris-alpha` → `polaris.txt`
+- Default → `qwen.txt` (anthropic without TODO)
+
+### 3. Environment Context
+
+```typescript
+SystemPrompt.environment();
+```
+
+Includes:
+
+```xml
+<env>
+ Working directory: {cwd}
+ Is directory a git repo: yes/no
+ Platform: darwin/linux/win32
+ Today's date: {date}
+</env>
+<files>
+ {git tree via ripgrep, limit 200 files}
+</files>
+```
+
+### 4. Custom Instructions
+
+```typescript
+SystemPrompt.custom();
+```
+
+Searches for:
+
+1. **Local** (project-specific): `AGENTS.md`, `CLAUDE.md`, `CONTEXT.md` (deprecated)
+2. **Global**: `~/.config/opencode/AGENTS.md`, `~/.claude/CLAUDE.md`
+3. **Config instructions**: From `opencode.jsonc` → `instructions: ["path/to/file.md"]`
+
+**Merge strategy**: All found files concatenated with header `"Instructions from: {path}"`
+
+### 5. Max Steps Reminder (if on last step)
+
+```typescript
+if (isLastStep) {
+ messages.push({ role: "assistant", content: MAX_STEPS });
+}
+```
+
+## Message Conversion to Model Format
+
+**Key function**: `MessageV2.toModelMessage(messages)`
+
+**Conversions**:
+
+- User text parts → `{type: "text", text}`
+- User files (non-text) → `{type: "file", url, mediaType, filename}`
+- Compaction parts → synthetic `"What did we do so far?"` text
+- Subtask parts → synthetic `"The following tool was executed by the user"` text
+- Assistant text → `{type: "text", text}`
+- Tool calls (completed) → `{type: "tool-{name}", state: "output-available", input, output}`
+ - **Pruned tools**: `output: "[Old tool result content cleared]"`
+- Tool calls (error) → `{type: "tool-{name}", state: "output-error", errorText}`
+- Reasoning → `{type: "reasoning", text}` (for models with extended thinking)
+
+**Filtering**:
+
+- Aborted messages excluded UNLESS they have non-reasoning parts
+- Messages with only errors excluded
+- Empty messages (no parts) excluded
+
+## Prompt Caching
+
+**Automatic cache points** inserted via `ProviderTransform.applyCaching()`:
+
+**Cached messages**:
+
+1. First 2 system messages
+2. Last 2 conversation messages (most recent context)
+
+**Provider-specific cache control**:
+
+```typescript
+{
+ anthropic: { cacheControl: { type: "ephemeral" } },
+ openrouter: { cache_control: { type: "ephemeral" } },
+ bedrock: { cachePoint: { type: "ephemeral" } },
+ openaiCompatible: { cache_control: { type: "ephemeral" } }
+}
+```
+
+**Placement**:
+
+- Anthropic: On message itself
+- Others: On last content item in message (if array)
+
+## Session Persistence
+
+**No explicit "save" operation** - all writes are immediate via `Storage.write()`.
+
+**Session resumption**:
+
+```typescript
+Session.get(sessionID); // Fetch metadata
+Session.messages({ sessionID }); // Load all messages
+MessageV2.stream(sessionID); // Async generator (newest first)
+MessageV2.filterCompacted(stream); // Stop at last compaction
+```
+
+**Forking** (`Session.fork`):
+
+1. Creates new session
+2. Clones messages up to `messageID` (if specified)
+3. Clones all parts for each message
+4. Generates new IDs (ascending) for cloned items
+
+## Features We Might Not Be Using
+
+### 1. Session Sharing
+
+```typescript
+Session.share(sessionID)
+ → Creates shareable URL
+ → Syncs to Cloudflare Durable Objects (if enterprise)
+ → Or uses Share.create() for public sharing
+```
+
+**Config**: `share: "auto" | "disabled"` or `OPENCODE_AUTO_SHARE` flag
+
+### 2. Session Revert
+
+```typescript
+SessionRevert.create({ sessionID, messageID, partID? })
+ → Captures git snapshot before changes
+ → Stores in session.revert field
+ → Can rollback to pre-message state
+```
+
+### 3. Agent/Mode System
+
+- Agents defined in `agent/*.md` files
+- Custom `maxSteps`, `temperature`, `topP`, `permission` rules
+- Agent-specific system prompts via `@agent-name` references
+
+### 4. Subtask System
+
+- `MessageV2.SubtaskPart` - spawns background tasks
+- Handled by `Task` tool
+- Results come back as tool outputs
+
+### 5. Doom Loop Detection
+
+```typescript
+DOOM_LOOP_THRESHOLD = 3;
+```
+
+- Tracks last 3 tool calls
+- If identical tool + args 3x, triggers permission check
+- Can be set to "ask", "deny", or "allow" per agent
+
+### 6. Session Diff Tracking
+
+```typescript
+SessionSummary.summarize()
+ → Computes git diffs for all patches
+ → Stores in session_diff/{sessionID}.json
+ → Updates session.summary with { additions, deletions, files }
+```
+
+### 7. Message Title Generation
+
+- Uses small model (e.g., Haiku) to generate 20-token title
+- Stored in `message.summary.title`
+- Async, doesn't block conversation
+
+### 8. Session Children
+
+- Sessions can have parent-child relationships
+- Useful for branching conversations
+- `Session.children(parentID)` fetches all descendants
+
+### 9. Plugin System
+
+```typescript
+Plugin.trigger("chat.params", { sessionID, agent, model, ... })
+ → Allows plugins to modify chat params before sending
+```
+
+### 10. Experimental Features (via Flags)
+
+- `OPENCODE_DISABLE_PRUNE` - Skip tool output pruning
+- `OPENCODE_DISABLE_AUTOCOMPACT` - Manual compaction only
+- `OPENCODE_EXPERIMENTAL_WATCHER` - File change watching
+- `OPENCODE_FAKE_VCS` - Simulate git for testing
+- `OPENCODE_PERMISSION` - Override permission policies
+
+## Configuration System
+
+**Layered merging** (global → local → env):
+
+1. Global config (`~/.config/opencode/opencode.jsonc`)
+2. Auth provider configs (from `.well-known/opencode`)
+3. Project-local configs (walks up from cwd to git root, finds `opencode.jsonc`)
+4. `.opencode/` directories (project-specific overrides)
+5. `OPENCODE_CONFIG` env var (explicit override)
+6. `OPENCODE_CONFIG_CONTENT` env var (JSON string)
+
+**Custom merge for plugins**: Arrays concatenated, not replaced.
+
+## Token Cost Tracking
+
+**Calculated per message**:
+
+```typescript
+Session.getUsage({ model, usage, metadata });
+```
+
+**Handles**:
+
+- Input tokens (excluding cached)
+- Output tokens
+- Reasoning tokens (charged at output rate)
+- Cache write tokens
+- Cache read tokens
+
+**Provider-specific metadata**:
+
+- Anthropic: `cacheCreationInputTokens`, `cachedInputTokens`
+- Bedrock: `usage.cacheWriteInputTokens`
+
+**Over 200K pricing**: Some models have different pricing above 200K input tokens.
+
+## Key Invariants
+
+1. **Sessions never deleted during use** - cleanup is manual via `Session.remove()`
+2. **Messages immutable after creation** - updates via `Storage.update()` with editor function
+3. **Parts stream in order** - sorted by ID (ascending = chronological)
+4. **Compaction is one-way** - no "un-summarizing" a session
+5. **Pruned tool outputs lost** - no way to retrieve after pruning
+6. **Project ID is git root commit** - ensures consistency across worktrees
+7. **Identifiers are time-based** - descending for sessions (newest first), ascending for messages/parts
+
+## Performance Notes
+
+- **No in-memory cache** - every read hits disk (via Bun.file)
+- **Locking prevents race conditions** - but adds latency
+- **Async generators for streaming** - memory efficient for large histories
+- **Glob scanning** - fast with Bun, but scales linearly with file count
+- **Token estimation is instant** - no tokenizer overhead
+- **Compaction is blocking** - conversation pauses during summarization
+- **Pruning is async** - doesn't block next turn
+
+## Relevant Files for Deep Dive
+
+- `packages/opencode/src/session/index.ts` - Session CRUD operations
+- `packages/opencode/src/session/prompt.ts` - Main conversation loop, system prompt assembly
+- `packages/opencode/src/session/compaction.ts` - Auto-summarization logic
+- `packages/opencode/src/session/message-v2.ts` - Message types, conversion to model format
+- `packages/opencode/src/session/system.ts` - System prompt construction
+- `packages/opencode/src/session/processor.ts` - Streaming response handler
+- `packages/opencode/src/session/summary.ts` - Title/summary generation, diff tracking
+- `packages/opencode/src/storage/storage.ts` - File-based persistence layer
+- `packages/opencode/src/provider/transform.ts` - Prompt caching, message normalization
+- `packages/opencode/src/util/token.ts` - Token estimation (simple char/4)
+- `packages/opencode/src/config/config.ts` - Configuration loading and merging
diff --git a/knowledge/opencode-plugins.md b/knowledge/opencode-plugins.md
new file mode 100644
index 0000000..3cff97d
--- /dev/null
+++ b/knowledge/opencode-plugins.md
@@ -0,0 +1,625 @@
+# OpenCode Plugin System Architecture
+
+**Analysis Date:** 2025-12-11
+**Source:** sst/opencode @ github.com
+**Analyzed by:** FuchsiaCastle (opencode-pnt.1)
+
+## Executive Summary
+
+OpenCode uses a lightweight, filesystem-based plugin architecture with automatic discovery via Bun.Glob. The system has four primary extension points: **plugins** (TypeScript/npm), **tools** (local TypeScript), **agents** (markdown), and **commands** (markdown). MCP servers integrate as external tool sources via AI SDK's experimental MCP client.
+
+## Core Architecture
+
+### Plugin Discovery & Loading
+
+**Location:** `packages/opencode/src/plugin/index.ts`
+
+Plugins are loaded via `Instance.state` (lazy singleton per project instance):
+
+```typescript
+const state = Instance.state(async () => {
+ const plugins = [...(config.plugin ?? [])];
+
+ // Default plugins (unless disabled via flag)
+ if (!Flag.OPENCODE_DISABLE_DEFAULT_PLUGINS) {
+ plugins.push("opencode-copilot-auth@0.0.9");
+ plugins.push("opencode-anthropic-auth@0.0.5");
+ }
+
+ for (let plugin of plugins) {
+ if (!plugin.startsWith("file://")) {
+ // npm package: parse name@version, install via BunProc
+ const lastAtIndex = plugin.lastIndexOf("@");
+ const pkg = lastAtIndex > 0 ? plugin.substring(0, lastAtIndex) : plugin;
+ const version =
+ lastAtIndex > 0 ? plugin.substring(lastAtIndex + 1) : "latest";
+ plugin = await BunProc.install(pkg, version);
+ }
+ const mod = await import(plugin);
+ for (const [_name, fn] of Object.entries<PluginInstance>(mod)) {
+ const init = await fn(input);
+ hooks.push(init);
+ }
+ }
+});
+```
+
+**Plugin Input Context:**
+
+- `client`: OpenCode SDK client (HTTP client hitting localhost:4096)
+- `project`: Project metadata
+- `worktree`: Git worktree info
+- `directory`: Current working directory
+- `$`: Bun shell (`Bun.$`)
+
+### Plugin Interface
+
+**Location:** `packages/plugin/src/index.ts`
+
+```typescript
+export type Plugin = (input: PluginInput) => Promise<Hooks>;
+
+export interface Hooks {
+ event?: (input: { event: Event }) => Promise<void>;
+ config?: (input: Config) => Promise<void>;
+ tool?: { [key: string]: ToolDefinition };
+ auth?: AuthHook;
+ "chat.message"?: (input, output) => Promise<void>;
+ "chat.params"?: (input, output) => Promise<void>;
+ "permission.ask"?: (input, output) => Promise<void>;
+ "tool.execute.before"?: (input, output) => Promise<void>;
+ "tool.execute.after"?: (input, output) => Promise<void>;
+ "experimental.text.complete"?: (input, output) => Promise<void>;
+}
+```
+
+**Hook Execution Pattern:**
+
+- Plugins return a `Hooks` object
+- `Plugin.trigger()` iterates all loaded plugin hooks for a given lifecycle event
+- Hooks mutate `output` parameter in-place (no return value needed)
+
+**Example Usage:**
+
+```typescript
+await Plugin.trigger(
+ "tool.execute.before",
+ { tool: "bash", sessionID, callID },
+ { args: { command: "ls" } },
+);
+```
+
+## Tool System
+
+### Tool Definition Schema
+
+**Location:** `packages/plugin/src/tool.ts`
+
+```typescript
+export type ToolContext = {
+ sessionID: string;
+ messageID: string;
+ agent: string;
+ abort: AbortSignal;
+};
+
+export function tool<Args extends z.ZodRawShape>(input: {
+ description: string;
+ args: Args;
+ execute(
+ args: z.infer<z.ZodObject<Args>>,
+ context: ToolContext,
+ ): Promise<string>;
+}) {
+ return input;
+}
+tool.schema = z;
+
+export type ToolDefinition = ReturnType<typeof tool>;
+```
+
+**Key Properties:**
+
+- Tools use Zod for argument validation (`tool.schema` = `z`)
+- Execute function is async, returns string
+- Context includes session tracking + abort signal
+
+### Tool Discovery
+
+**Location:** `packages/opencode/src/tool/registry.ts`
+
+Tools are discovered from two sources:
+
+1. **Local TypeScript files** (`tool/*.{ts,js}`):
+
+```typescript
+const glob = new Bun.Glob("tool/*.{js,ts}");
+for (const dir of await Config.directories()) {
+ for await (const match of glob.scan({ cwd: dir, absolute: true })) {
+ const namespace = path.basename(match, path.extname(match));
+ const mod = await import(match);
+ for (const [id, def] of Object.entries<ToolDefinition>(mod)) {
+ custom.push(
+ fromPlugin(id === "default" ? namespace : `${namespace}_${id}`, def),
+ );
+ }
+ }
+}
+```
+
+2. **Plugin hooks** (`plugin.tool`):
+
+```typescript
+const plugins = await Plugin.list();
+for (const plugin of plugins) {
+ for (const [id, def] of Object.entries(plugin.tool ?? {})) {
+ custom.push(fromPlugin(id, def));
+ }
+}
+```
+
+**Tool Naming Convention:**
+
+- If export is `default`, tool ID = filename
+- Otherwise: `${filename}_${exportName}`
+- Example: `tool/typecheck.ts` with `export default tool({...})` → `typecheck`
+- Example: `tool/git.ts` with `export const status = tool({...})` → `git_status`
+
+### Built-in vs Custom Tools
+
+Built-in tools (always available):
+
+- `bash`, `read`, `glob`, `grep`, `list`, `edit`, `write`, `task`, `webfetch`, etc.
+
+Custom tools (from config directories + plugins) are appended after built-ins.
+
+**Tool Registration:**
+
+- Registry maintains a single array: `[...builtins, ...custom]`
+- Later tools can override earlier ones via `ToolRegistry.register()`
+
+## Command System
+
+### Command Definition
+
+**Location:** `packages/opencode/src/config/config.ts`
+
+```typescript
+export const Command = z.object({
+ template: z.string(),
+ description: z.string().optional(),
+ agent: z.string().optional(),
+ model: z.string().optional(),
+ subtask: z.boolean().optional(),
+});
+```
+
+**Storage:** Markdown files in `command/*.md` with frontmatter
+
+Example:
+
+```markdown
+---
+agent: swarm/planner
+description: Decompose task into parallel beads
+---
+
+You are the swarm coordinator...
+```
+
+### Command Discovery
+
+**Location:** `packages/opencode/src/config/config.ts` (line ~180)
+
+```typescript
+const COMMAND_GLOB = new Bun.Glob("command/*.md");
+async function loadCommand(dir: string) {
+ const result: Record<string, Command> = {};
+ for await (const item of COMMAND_GLOB.scan({ cwd: dir, absolute: true })) {
+ const md = await ConfigMarkdown.parse(item);
+ const name = path.basename(item, ".md");
+ const config = {
+ name,
+ ...md.data,
+ template: md.content.trim(),
+ };
+ const parsed = Command.safeParse(config);
+ if (parsed.success) {
+ result[config.name] = parsed.data;
+ }
+ }
+ return result;
+}
+```
+
+**Key Details:**
+
+- Commands are invoked as `/command-name` in chat
+- `template` is the markdown body (injected into user message)
+- `agent` specifies which agent runs the command
+- `subtask: true` marks it as a Task-spawnable command
+
+## Agent System
+
+### Agent Definition
+
+**Location:** `packages/opencode/src/config/config.ts`
+
+```typescript
+export const Agent = z.object({
+ model: z.string().optional(),
+ temperature: z.number().optional(),
+ top_p: z.number().optional(),
+ prompt: z.string().optional(),
+ tools: z.record(z.string(), z.boolean()).optional(),
+ disable: z.boolean().optional(),
+ description: z.string().optional(),
+ mode: z.enum(["subagent", "primary", "all"]).optional(),
+ color: z
+ .string()
+ .regex(/^#[0-9a-fA-F]{6}$/)
+ .optional(),
+ maxSteps: z.number().int().positive().optional(),
+ permission: z
+ .object({
+ edit: Permission.optional(),
+ bash: z.union([Permission, z.record(z.string(), Permission)]).optional(),
+ webfetch: Permission.optional(),
+ doom_loop: Permission.optional(),
+ external_directory: Permission.optional(),
+ })
+ .optional(),
+});
+```
+
+**Storage:** Markdown files in `agent/**/*.md` (supports nested directories)
+
+### Agent Discovery
+
+**Location:** `packages/opencode/src/config/config.ts` (line ~218)
+
+```typescript
+const AGENT_GLOB = new Bun.Glob("agent/**/*.md");
+async function loadAgent(dir: string) {
+ for await (const item of AGENT_GLOB.scan({ cwd: dir, absolute: true })) {
+ const md = await ConfigMarkdown.parse(item);
+
+ // Nested path support
+ let agentName = path.basename(item, ".md");
+ const agentFolderPath = item.includes("/.opencode/agent/")
+ ? item.split("/.opencode/agent/")[1]
+ : item.split("/agent/")[1];
+
+ if (agentFolderPath.includes("/")) {
+ const relativePath = agentFolderPath.replace(".md", "");
+ const pathParts = relativePath.split("/");
+ agentName =
+ pathParts.slice(0, -1).join("/") +
+ "/" +
+ pathParts[pathParts.length - 1];
+ }
+
+ const config = {
+ name: agentName,
+ ...md.data,
+ prompt: md.content.trim(),
+ };
+ result[config.name] = parsed.data;
+ }
+}
+```
+
+**Mode Types:**
+
+- `subagent`: Available via Task tool or `/agent` command
+- `primary`: Available as primary chat agent
+- `all`: Both
+
+**Nested Agents:**
+
+- `agent/swarm/planner.md` → name = `swarm/planner`
+- Allows organizational hierarchy
+
+### Mode vs Agent
+
+**Modes** are primary agents stored in `mode/*.md`:
+
+- Always `mode: "primary"`
+- Shown in model picker UI
+- Example: `mode/architect.md`
+
+**Agents** are typically subagents:
+
+- Default `mode: "subagent"`
+- Invoked via commands or Task tool
+
+## MCP Integration
+
+### MCP Server Configuration
+
+**Location:** `packages/opencode/src/config/config.ts`
+
+```typescript
+mcp: z.record(z.string(), Mcp).optional();
+
+// Local MCP Server
+export const McpLocal = z.object({
+ type: z.literal("local"),
+ command: z.string().array(),
+ environment: z.record(z.string(), z.string()).optional(),
+ enabled: z.boolean().optional(),
+ timeout: z.number().int().positive().optional(),
+});
+
+// Remote MCP Server
+export const McpRemote = z.object({
+ type: z.literal("remote"),
+ url: z.string(),
+ enabled: z.boolean().optional(),
+ headers: z.record(z.string(), z.string()).optional(),
+ oauth: z.union([McpOAuth, z.literal(false)]).optional(),
+ timeout: z.number().int().positive().optional(),
+});
+```
+
+**Example Config:**
+
+```json
+{
+ "mcp": {
+ "chrome-devtools": {
+ "type": "local",
+ "command": ["npx", "@executeautomation/chrome-mcp"],
+ "enabled": true
+ },
+ "next-devtools": {
+ "type": "remote",
+ "url": "http://localhost:3000/_next/mcp",
+ "oauth": false
+ }
+ }
+}
+```
+
+### MCP Client Lifecycle
+
+**Location:** `packages/opencode/src/mcp/index.ts`
+
+```typescript
+const state = Instance.state(async () => {
+ const config = cfg.mcp ?? {};
+ const clients: Record<string, Client> = {};
+ const status: Record<string, Status> = {};
+
+ await Promise.all(
+ Object.entries(config).map(async ([key, mcp]) => {
+ if (mcp.enabled === false) {
+ status[key] = { status: "disabled" };
+ return;
+ }
+
+ const result = await create(key, mcp).catch(() => undefined);
+ status[key] = result.status;
+
+ if (result.mcpClient) {
+ clients[key] = result.mcpClient;
+ }
+ }),
+ );
+
+ return { clients, status };
+});
+```
+
+**Transport Selection:**
+
+- `local`: StdioClientTransport (spawns subprocess)
+- `remote` + SSE: SSEClientTransport
+- `remote` + HTTP: StreamableHTTPClientTransport
+
+**OAuth Flow:**
+
+1. If `needs_auth` status, MCP server returned 401
+2. Check if dynamic client registration needed (RFC 7591)
+3. Store pending transport in `pendingOAuthTransports` map
+4. Expose OAuth callback handler at `/api/oauth/callback/:serverName`
+5. After auth completes, resume MCP client initialization
+
+**Tool Discovery:**
+
+- MCP tools are fetched via `client.listTools()` with timeout (default 5s)
+- Tools are prefixed with server name: `${serverName}_${toolName}`
+- MCP tools appear alongside built-in and custom tools
+
+## Configuration Hierarchy
+
+**Directories searched (priority order):**
+
+1. `~/.opencode/` (global config)
+2. `./.opencode/` (project-local config)
+
+**Config Merge Strategy:**
+
+- `agent`, `command`, `mode`: Deep merge (Config.directories() aggregates all)
+- `plugin`: Array concatenation + deduplication
+- `mcp`: Object merge (deep merge)
+- `tools`: Object merge
+
+**Plugin Sources:**
+
+1. Config file: `opencode.json` → `plugin: ["pkg@version", "file://..."]`
+2. Filesystem: `plugin/*.{ts,js}` → auto-discovered as `file://` URLs
+3. Default plugins: `opencode-copilot-auth@0.0.9`, `opencode-anthropic-auth@0.0.5`
+
+## Comparison to Our Local Setup
+
+### Similarities
+
+✅ Markdown-based agents/commands with frontmatter
+✅ Filesystem-based tool discovery (`tool/*.ts`)
+✅ Config hierarchy (global + project-local)
+✅ MCP integration for external tools
+
+### Differences
+
+| Aspect | sst/opencode | Our Setup |
+| ------------------ | ----------------------------------------------- | ----------------------------- |
+| **Plugin System** | Full npm package support + lifecycle hooks | No plugins (just local tools) |
+| **Tool Discovery** | `tool/*.{ts,js}` + plugin.tool | `tool/*.ts` only |
+| **Agent Format** | `agent/**/*.md` (nested support) | `agent/*.md` (flat) |
+| **Command Format** | `command/*.md` with `template` | `command/*.md` (same) |
+| **MCP Config** | `config.mcp` object with OAuth support | Direct MCP server config |
+| **Tool Naming** | Smart: `filename_exportName` or just `filename` | Export name only |
+| **Auth Plugins** | Dedicated auth hooks (OAuth flow) | No auth plugin system |
+
+### Gaps in Our Setup
+
+1. **No Plugin System**: We can't install npm packages as plugins with lifecycle hooks
+2. **No Auth Hooks**: Can't extend authentication (e.g., custom OAuth providers)
+3. **No Tool Lifecycle Hooks**: Can't intercept tool execution (before/after)
+4. **No Event Bus**: OpenCode has `Bus.subscribeAll()` for plugin event subscription
+5. **Flat Agent Structure**: No nested agent directories (`agent/swarm/planner.md`)
+
+### Opportunities for Improvement
+
+1. **Plugin System**:
+ - Add `plugin/*.ts` discovery with `export default Plugin = async (input) => ({ ... })`
+ - Implement minimal hooks: `tool`, `config`, `event`
+ - Keep it lightweight (no npm package support initially)
+
+2. **Nested Agents**:
+ - Change glob from `agent/*.md` to `agent/**/*.md`
+ - Use folder structure for namespacing: `agent/swarm/planner.md` → `swarm/planner`
+
+3. **Tool Lifecycle Hooks**:
+ - Wrap tool execute in `tool/registry.ts` to call plugin hooks
+ - Useful for logging, metrics, input validation
+
+4. **Smart Tool Naming**:
+ - If export is `default`, use filename as tool ID
+ - Otherwise: `${filename}_${exportName}`
+ - Cleaner than always requiring `${filename}_${exportName}`
+
+5. **MCP OAuth Support**:
+ - Add `oauth` config to MCP server definitions
+ - Implement callback handler at `/api/oauth/callback/:serverName`
+ - Store pending transports until auth completes
+
+## Implementation Notes
+
+### Plugin Hook Execution Pattern
+
+OpenCode's hook pattern is elegant:
+
+```typescript
+// In session/prompt.ts (wrapping tool execute)
+item.execute = async (args, opts) => {
+ await Plugin.trigger(
+ "tool.execute.before",
+ { tool: id, sessionID, callID },
+ { args },
+ );
+
+ const result = await execute(args, opts);
+
+ await Plugin.trigger(
+ "tool.execute.after",
+ { tool: id, sessionID, callID },
+ { title, output, metadata },
+ );
+
+ return result;
+};
+```
+
+Hooks mutate output in-place (no return value), making composition simple.
+
+### Tool Registry Pattern
+
+Registry uses lazy singleton per project instance:
+
+```typescript
+export const state = Instance.state(async () => {
+ const custom = [];
+ // discover local tools
+ // discover plugin tools
+ return { custom };
+});
+```
+
+This ensures:
+
+- Tools are loaded once per project
+- Different projects can have different tool sets
+- No global state pollution
+
+### Agent Loading Strategy
+
+Agents are loaded lazily via `Agent.state`:
+
+```typescript
+const state = Instance.state(async () => {
+ const cfg = await Config.get();
+ const agents = mergeDeep(builtInAgents, cfg.agent ?? {});
+ // apply defaults, permissions, etc.
+ return { agents };
+});
+```
+
+Built-in agents are hardcoded, user agents override/extend.
+
+## Recommended Next Steps
+
+1. **Spike: Minimal Plugin System**
+ - Add `plugin/*.ts` discovery
+ - Implement `tool` and `config` hooks only
+ - Test with a simple plugin that adds a custom tool
+
+2. **Nested Agent Support**
+ - Update glob pattern to `agent/**/*.md`
+ - Update agent name extraction logic
+ - Test with `agent/swarm/planner.md`
+
+3. **Smart Tool Naming**
+ - Update tool registry to check if export is `default`
+ - Use filename as ID if default, else `${filename}_${exportName}`
+ - Update existing tools to use default export where appropriate
+
+4. **Tool Lifecycle Hooks**
+ - Add `Plugin.trigger()` calls before/after tool execution
+ - Implement in session/prompt.ts where tools are wrapped
+ - Use for logging/metrics initially
+
+5. **Documentation**
+ - Document plugin interface in knowledge/
+ - Create example plugin in plugin/example.ts
+ - Add plugin development guide
+
+## Open Questions
+
+1. **Plugin Package Management**: Should we support npm packages like OpenCode, or stick to local `plugin/*.ts` files?
+2. **Auth Plugin Priority**: Do we need auth plugins, or is MCP OAuth enough?
+3. **Event Bus**: Should we implement a full event bus, or just plugin hooks?
+4. **Plugin Versioning**: How do we handle plugin version conflicts if we support npm packages?
+5. **Plugin Sandboxing**: Should plugins run in a restricted context, or trust local code?
+
+## References
+
+- **Main Plugin Code**: `packages/opencode/src/plugin/index.ts`
+- **Plugin Interface**: `packages/plugin/src/index.ts`
+- **Tool System**: `packages/opencode/src/tool/registry.ts`
+- **Config Loading**: `packages/opencode/src/config/config.ts`
+- **MCP Integration**: `packages/opencode/src/mcp/index.ts`
+- **Agent System**: `packages/opencode/src/agent/agent.ts`
+
+## Conclusion
+
+OpenCode's plugin system is production-ready, battle-tested, and elegant. Key takeaways:
+
+1. **Filesystem-first**: Tools, agents, commands discovered via glob patterns
+2. **Hook-based extensibility**: Plugins return hooks, no inheritance or classes
+3. **Context preservation**: Tools get abort signals, session IDs, agent names
+4. **Type-safe**: Zod schemas for everything (tools, config, MCP)
+5. **Instance-scoped**: All state is per-project via `Instance.state`
+
+Our local setup is 80% there. Main gaps: plugin system, nested agents, tool lifecycle hooks. All addressable with targeted spikes.
diff --git a/knowledge/opencode-tools.md b/knowledge/opencode-tools.md
new file mode 100644
index 0000000..b5a7ddb
--- /dev/null
+++ b/knowledge/opencode-tools.md
@@ -0,0 +1,952 @@
+# OpenCode Built-in Tools - Implementation Analysis
+
+Deep dive into sst/opencode built-in tool implementations. Patterns worth adopting for our custom tools.
+
+## Tool Architecture
+
+### Tool Definition Pattern
+
+```typescript
+// packages/opencode/src/tool/tool.ts
+Tool.define<Parameters, Metadata>(id, init);
+```
+
+**Key features:**
+
+- Lazy initialization via `init()` function
+- Zod schema validation with custom error formatting
+- Type-safe context with `Context<M extends Metadata>`
+- Standardized return: `{ title, output, metadata, attachments? }`
+- Built-in parameter validation with helpful error messages
+
+**Context object:**
+
+```typescript
+type Context = {
+ sessionID: string;
+ messageID: string;
+ agent: string;
+ abort: AbortSignal; // For cancellation
+ callID?: string; // Tool invocation ID
+ extra?: Record<string, any>; // Extension point
+ metadata(input): void; // Streaming metadata updates
+};
+```
+
+### Registry Pattern
+
+```typescript
+// packages/opencode/src/tool/registry.ts
+ToolRegistry.state(async () => {
+ const custom = [];
+ // Scan tool/*.{js,ts} in all config directories
+ for (const dir of await Config.directories()) {
+ const glob = new Bun.Glob("tool/*.{js,ts}");
+ // Load and register
+ }
+ // Load from plugins too
+ return { custom };
+});
+```
+
+**Patterns to adopt:**
+
+- Scan multiple config directories
+- Support both file-based and plugin-based tools
+- Lazy state initialization per project instance
+- Dynamic tool discovery (no manual registration)
+
+## Read Tool
+
+**File:** `packages/opencode/src/tool/read.ts`
+
+### Highlights
+
+1. **Binary file detection** (lines 162-217)
+ - Extension-based allowlist (`.zip`, `.exe`, etc.)
+ - Null byte check (instant binary detection)
+ - Non-printable character ratio (>30% = binary)
+2. **Smart file suggestions** (lines 80-91)
+
+ ```typescript
+ const dirEntries = fs.readdirSync(dir);
+ const suggestions = dirEntries
+ .filter(
+ (entry) =>
+ entry.toLowerCase().includes(base.toLowerCase()) ||
+ base.toLowerCase().includes(entry.toLowerCase()),
+ )
+ .slice(0, 3);
+ ```
+
+3. **Line truncation** (line 17, 127)
+ - Max 2000 chars per line
+ - Default 2000 lines read
+ - Pagination via `offset` parameter
+
+4. **Image/PDF handling** (lines 96-118)
+ - Detects MIME type
+ - Returns base64 data URL as attachment
+ - Separate code path for binary assets
+
+5. **Security: .env blocking** (lines 62-73)
+ - Allowlist: `.env.sample`, `.example`
+ - Block: any file containing `.env`
+ - Clear error message to stop retry attempts
+
+6. **FileTime tracking** (line 150)
+
+ ```typescript
+ FileTime.read(ctx.sessionID, filepath);
+ ```
+
+ Records when file was read per session for edit protection
+
+7. **LSP warm-up** (line 149)
+ ```typescript
+ LSP.touchFile(filepath, false);
+ ```
+ Prepares language server for future diagnostics
+
+**Patterns to adopt:**
+
+- Binary detection heuristics
+- Smart suggestions on file not found
+- Truncation with continuation hints
+- Session-scoped file read tracking
+
+## Write Tool
+
+**File:** `packages/opencode/src/tool/write.ts`
+
+### Highlights
+
+1. **Must-read-first enforcement** (line 55)
+
+ ```typescript
+ if (exists) await FileTime.assert(ctx.sessionID, filepath);
+ ```
+
+ Throws if file wasn't read in this session
+
+2. **LSP diagnostics** (lines 78-87)
+
+ ```typescript
+ await LSP.touchFile(filepath, true); // refresh=true
+ const diagnostics = await LSP.diagnostics();
+ // Return errors in output immediately
+ ```
+
+3. **Permission differentiation** (lines 57-69)
+ - Separate permission for create vs overwrite
+ - Title changes: "Create new file" vs "Overwrite this file"
+
+4. **Event bus integration** (lines 72-74)
+ ```typescript
+ await Bus.publish(File.Event.Edited, { file: filepath });
+ ```
+
+**Patterns to adopt:**
+
+- Immediate LSP feedback after write
+- Event-driven file change notifications
+- Create vs overwrite distinction in permissions
+
+## Edit Tool
+
+**File:** `packages/opencode/src/tool/edit.ts`
+
+### Highlights
+
+**This is the most sophisticated tool - 675 lines!**
+
+1. **Multiple replacement strategies** (lines 176-500+)
+ - `SimpleReplacer` - exact string match
+ - `LineTrimmedReplacer` - ignores whitespace per line
+ - `BlockAnchorReplacer` - matches first/last line + similarity scoring
+ - `WhitespaceNormalizedReplacer` - normalizes all whitespace
+ - `IndentationFlexibleReplacer` - ignores indentation levels
+ - `EscapeNormalizedReplacer` - handles escape sequences
+
+2. **Levenshtein distance** (lines 185-201)
+
+ ```typescript
+ function levenshtein(a: string, b: string): number;
+ ```
+
+ Used by `BlockAnchorReplacer` for fuzzy matching
+
+3. **Similarity thresholds** (lines 179-180)
+
+ ```typescript
+ const SINGLE_CANDIDATE_SIMILARITY_THRESHOLD = 0.0;
+ const MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD = 0.3;
+ ```
+
+ Lower threshold when only one match found
+
+4. **Generator-based replacers** (line 176)
+
+ ```typescript
+ type Replacer = (content: string, find: string) => Generator<string>;
+ ```
+
+ Each strategy yields candidate matches
+
+5. **Diff generation** (lines 109-133)
+
+ ```typescript
+ diff = trimDiff(
+ createTwoFilesPatch(
+ filePath,
+ filePath,
+ normalizeLineEndings(contentOld),
+ normalizeLineEndings(contentNew),
+ ),
+ );
+ ```
+
+6. **Line ending normalization** (lines 21-23)
+ Converts `\r\n` to `\n` before comparison
+
+7. **Snapshot integration** (lines 152-162)
+ ```typescript
+ const filediff: Snapshot.FileDiff = {
+ file: filePath,
+ before: contentOld,
+ after: contentNew,
+ additions: 0,
+ deletions: 0,
+ };
+ ```
+
+**Patterns to adopt:**
+
+- Multi-strategy replacement with fallbacks
+- Fuzzy matching for AI-generated code
+- Generator pattern for candidate enumeration
+- Diff-based permission approval
+- Snapshot tracking for history/rollback
+
+## Bash Tool
+
+**File:** `packages/opencode/src/tool/bash.ts`
+
+### Highlights
+
+1. **Shell detection** (lines 56-81)
+
+ ```typescript
+ const shell = iife(() => {
+ const s = process.env.SHELL;
+ // Reject fish/nu shells
+ if (new Set(["fish", "nu"]).has(basename)) return fallback;
+ // Platform-specific defaults
+ if (darwin) return "/bin/zsh";
+ if (win32) return process.env.COMSPEC || true;
+ return Bun.which("bash") || true;
+ });
+ ```
+
+2. **Tree-sitter parsing** (lines 32-51, 107)
+
+ ```typescript
+ const parser = lazy(async () => {
+ const { Parser } = await import("web-tree-sitter");
+ // Load bash grammar
+ return p;
+ });
+ const tree = await parser().then((p) => p.parse(params.command));
+ ```
+
+ Parses bash AST for security analysis
+
+3. **External directory detection** (lines 113-141, 165-184)
+
+ ```typescript
+ for (const node of tree.rootNode.descendantsOfType("command")) {
+ if (["cd", "rm", "cp", "mv", ...].includes(command[0])) {
+ for (const arg of command.slice(1)) {
+ const resolved = await $`realpath ${arg}`.text()
+ await checkExternalDirectory(resolved)
+ }
+ }
+ }
+ ```
+
+ Resolves paths and checks if outside working directory
+
+4. **Permission wildcards** (lines 188-206)
+
+ ```typescript
+ const action = Wildcard.allStructured(
+ { head: command[0], tail: command.slice(1) },
+ permissions
+ )
+ if (action === "deny") throw new Error(...)
+ if (action === "ask") askPatterns.add(pattern)
+ ```
+
+5. **Process management** (lines 225-292)
+ - Cross-platform process tree killing
+ - Windows: `taskkill /f /t`
+ - Unix: negative PID for process group
+ - Graceful SIGTERM → SIGKILL after 200ms
+ - Detached mode on Unix
+
+6. **Streaming metadata** (lines 238-255)
+
+ ```typescript
+ ctx.metadata({ metadata: { output: "", description } });
+ const append = (chunk: Buffer) => {
+ output += chunk.toString();
+ ctx.metadata({ metadata: { output, description } });
+ };
+ proc.stdout?.on("data", append);
+ proc.stderr?.on("data", append);
+ ```
+
+7. **Timeout handling** (lines 306-328)
+ - Separate abort signal and timeout
+ - Cleanup on exit/error
+ - Metadata flags: `timedOut`, `aborted`
+
+8. **Output truncation** (line 19, 332-335)
+
+ ```typescript
+ const MAX_OUTPUT_LENGTH = 30_000;
+ if (output.length > MAX_OUTPUT_LENGTH) {
+ output = output.slice(0, MAX_OUTPUT_LENGTH);
+ resultMetadata.push("bash tool truncated output...");
+ }
+ ```
+
+9. **Windows Git Bash path normalization** (lines 175-179)
+ ```typescript
+ const normalized =
+ process.platform === "win32" && resolved.match(/^\/[a-z]\//)
+ ? resolved
+ .replace(/^\/([a-z])\//, (_, drive) => `${drive.toUpperCase()}:\\`)
+ .replace(/\//g, "\\")
+ : resolved;
+ ```
+
+**Patterns to adopt:**
+
+- AST-based security scanning
+- Command-specific path resolution
+- Streaming metadata during execution
+- Cross-platform process tree management
+- Graceful degradation (SIGTERM → SIGKILL)
+- Wildcard-based permission matching
+- Output size limits with metadata
+
+## Glob Tool
+
+**File:** `packages/opencode/src/tool/glob.ts`
+
+### Highlights
+
+1. **Ripgrep integration** (lines 26-43)
+
+ ```typescript
+ for await (const file of Ripgrep.files({
+ cwd: search,
+ glob: [params.pattern],
+ })) {
+ const stats = await Bun.file(full).stat();
+ files.push({ path: full, mtime: stats.mtime.getTime() });
+ }
+ ```
+
+2. **Modification time sorting** (line 44)
+
+ ```typescript
+ files.sort((a, b) => b.mtime - a.mtime);
+ ```
+
+ Most recently modified files first
+
+3. **Hard limit** (line 23, 30-32)
+ - Max 100 files
+ - Truncation message if exceeded
+
+**Patterns to adopt:**
+
+- Ripgrep for fast file listing
+- mtime-based sorting for relevance
+- Hard limits with truncation messages
+
+## Grep Tool
+
+**File:** `packages/opencode/src/tool/grep.ts`
+
+### Highlights
+
+1. **Direct ripgrep spawn** (lines 24-38)
+
+ ```typescript
+ const args = [
+ "-nH",
+ "--field-match-separator=|",
+ "--regexp",
+ params.pattern,
+ ];
+ if (params.include) args.push("--glob", params.include);
+ const proc = Bun.spawn([rgPath, ...args], { stdout: "pipe" });
+ ```
+
+2. **Exit code handling** (lines 40-50)
+ - Exit 1 = no matches (not an error)
+ - Exit 0 = success
+ - Other = actual error
+
+3. **Custom field separator** (line 25, 58)
+
+ ```typescript
+ --field-match-separator=|
+ const [filePath, lineNumStr, ...lineTextParts] = line.split("|")
+ ```
+
+ Avoids ambiguity with `:` in paths/content
+
+4. **mtime sorting** (lines 75-76)
+ Most recently modified files first (same as glob)
+
+**Patterns to adopt:**
+
+- Custom field separator for parsing
+- Exit code semantics (1 = no results ≠ error)
+- mtime-based relevance sorting
+
+## Task Tool
+
+**File:** `packages/opencode/src/tool/task.ts`
+
+### Highlights
+
+1. **Subagent selection** (lines 14-21)
+
+ ```typescript
+ const agents = await Agent.list().then((x) =>
+ x.filter((a) => a.mode !== "primary"),
+ );
+ const description = DESCRIPTION.replace(
+ "{agents}",
+ agents.map((a) => `- ${a.name}: ${a.description}`).join("\n"),
+ );
+ ```
+
+ Dynamic agent list in tool description
+
+2. **Session hierarchy** (lines 33-43)
+
+ ```typescript
+ return await Session.create({
+ parentID: ctx.sessionID,
+ title: params.description + ` (@${agent.name} subagent)`,
+ });
+ ```
+
+3. **Model inheritance** (lines 78-81)
+
+ ```typescript
+ const model = agent.model ?? {
+ modelID: msg.info.modelID,
+ providerID: msg.info.providerID,
+ };
+ ```
+
+ Uses parent's model if agent doesn't specify
+
+4. **Tool restrictions** (lines 99-105)
+
+ ```typescript
+ tools: {
+ todowrite: false,
+ todoread: false,
+ task: false, // Prevent recursive subagents
+ ...agent.tools,
+ }
+ ```
+
+5. **Event-driven progress tracking** (lines 55-76)
+
+ ```typescript
+ const unsub = Bus.subscribe(MessageV2.Event.PartUpdated, async (evt) => {
+ if (evt.properties.part.type !== "tool") return;
+ parts[part.id] = { id, tool, state };
+ ctx.metadata({ metadata: { summary: Object.values(parts) } });
+ });
+ ```
+
+6. **Abort propagation** (lines 83-87)
+
+ ```typescript
+ function cancel() {
+ SessionPrompt.cancel(session.id);
+ }
+ ctx.abort.addEventListener("abort", cancel);
+ using _ = defer(() => ctx.abort.removeEventListener("abort", cancel));
+ ```
+
+7. **Session ID in metadata** (line 123)
+ Returns `session_id` for continuation
+
+**Patterns to adopt:**
+
+- Dynamic tool descriptions
+- Session hierarchy for tracking
+- Model inheritance
+- Recursive tool prevention
+- Event-driven progress streaming
+- Abort signal propagation
+- Session continuation support
+
+## WebFetch Tool
+
+**File:** `packages/opencode/src/tool/webfetch.ts`
+
+### Highlights
+
+1. **Timeout handling** (lines 8-10, 42-45)
+
+ ```typescript
+ const DEFAULT_TIMEOUT = 30 * 1000;
+ const MAX_TIMEOUT = 120 * 1000;
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), timeout);
+ ```
+
+2. **URL validation** (lines 22-25)
+
+ ```typescript
+ if (
+ !params.url.startsWith("http://") &&
+ !params.url.startsWith("https://")
+ ) {
+ throw new Error("URL must start with http:// or https://");
+ }
+ ```
+
+3. **Content negotiation** (lines 47-62)
+
+ ```typescript
+ switch (params.format) {
+ case "markdown":
+ acceptHeader = "text/markdown;q=1.0, text/x-markdown;q=0.9, ...";
+ case "text":
+ acceptHeader = "text/plain;q=1.0, ...";
+ }
+ ```
+
+ Quality parameters for fallback content types
+
+4. **Size limits** (lines 8, 81-89)
+
+ ```typescript
+ const MAX_RESPONSE_SIZE = 5 * 1024 * 1024
+ if (contentLength && parseInt(contentLength) > MAX_RESPONSE_SIZE) {
+ throw new Error("Response too large (exceeds 5MB limit)")
+ }
+ // Check again after download
+ if (arrayBuffer.byteLength > MAX_RESPONSE_SIZE) throw ...
+ ```
+
+5. **HTML to Markdown conversion** (lines 177-187)
+
+ ```typescript
+ const turndownService = new TurndownService({
+ headingStyle: "atx",
+ bulletListMarker: "-",
+ codeBlockStyle: "fenced",
+ });
+ turndownService.remove(["script", "style", "meta", "link"]);
+ ```
+
+6. **HTML text extraction** (lines 145-175)
+
+ ```typescript
+ const rewriter = new HTMLRewriter()
+ .on("script, style, noscript, iframe, object, embed", {
+ element() {
+ skipContent = true;
+ },
+ })
+ .on("*", {
+ text(input) {
+ if (!skipContent) text += input.text;
+ },
+ });
+ ```
+
+7. **Abort signal composition** (line 65)
+ ```typescript
+ signal: AbortSignal.any([controller.signal, ctx.abort]);
+ ```
+ Both timeout and user abort
+
+**Patterns to adopt:**
+
+- Content negotiation with q-values
+- Double size checking (header + actual)
+- TurndownService for HTML→Markdown
+- HTMLRewriter for text extraction
+- AbortSignal composition
+- Clear size limits upfront
+
+## Todo Tools
+
+**File:** `packages/opencode/src/tool/todo.ts`
+
+### Highlights
+
+1. **Simple CRUD** (lines 6-24)
+
+ ```typescript
+ TodoWriteTool: params: {
+ todos: z.array(Todo.Info);
+ }
+ TodoReadTool: params: z.object({}); // no params
+ ```
+
+2. **Count in title** (lines 17, 32)
+
+ ```typescript
+ title: `${
+ params.todos.filter((x) => x.status !== "completed").length
+ } todos`;
+ ```
+
+3. **Session-scoped state** (lines 12-13, 30)
+ ```typescript
+ await Todo.update({ sessionID, todos });
+ const todos = await Todo.get(sessionID);
+ ```
+
+**Patterns to adopt:**
+
+- Session-scoped state for ephemeral data
+- Summary in title for tool history
+- Separate read/write tools for clarity
+
+## FileTime Module
+
+**File:** `packages/opencode/src/file/time.ts`
+
+### Highlights
+
+**Session-scoped file access tracking**
+
+1. **State structure** (lines 6-15)
+
+ ```typescript
+ const read: {
+ [sessionID: string]: {
+ [path: string]: Date | undefined;
+ };
+ } = {};
+ ```
+
+2. **Record read** (lines 17-22)
+
+ ```typescript
+ function read(sessionID: string, file: string) {
+ read[sessionID] = read[sessionID] || {};
+ read[sessionID][file] = new Date();
+ }
+ ```
+
+3. **Modification check** (lines 28-36)
+ ```typescript
+ async function assert(sessionID: string, filepath: string) {
+ const time = get(sessionID, filepath);
+ if (!time)
+ throw new Error(
+ `You must read the file ${filepath} before overwriting it`,
+ );
+ const stats = await Bun.file(filepath).stat();
+ if (stats.mtime.getTime() > time.getTime()) {
+ throw new Error(`File ${filepath} has been modified since...`);
+ }
+ }
+ ```
+
+**Patterns to adopt:**
+
+- Session-scoped read tracking
+- mtime-based concurrent modification detection
+- Clear error messages with timestamps
+
+## Permission System
+
+**File:** `packages/opencode/src/permission/index.ts`
+
+### Highlights
+
+1. **Pattern-based permissions** (lines 13-20)
+
+ ```typescript
+ function toKeys(pattern: string | string[], type: string): string[];
+ function covered(keys: string[], approved: Record<string, boolean>);
+ // Uses Wildcard.match for pattern matching
+ ```
+
+2. **Permission state** (lines 55-75)
+
+ ```typescript
+ const pending: {
+ [sessionID]: { [permissionID]: { info; resolve; reject } };
+ };
+ const approved: {
+ [sessionID]: { [permissionID]: boolean };
+ };
+ ```
+
+3. **Response modes** (line 144)
+
+ ```typescript
+ Response = z.enum(["once", "always", "reject"]);
+ ```
+
+4. **Plugin integration** (lines 122-131)
+
+ ```typescript
+ const result = await Plugin.trigger("permission.ask", info, {
+ status: "ask"
+ })
+ switch (result.status) {
+ case "deny": throw new RejectedError(...)
+ case "allow": return
+ }
+ ```
+
+5. **Pattern propagation** (lines 163-180)
+
+ ```typescript
+ if (input.response === "always") {
+ // Approve pattern
+ for (const k of approveKeys) {
+ approved[sessionID][k] = true;
+ }
+ // Auto-approve pending matching this pattern
+ for (const item of Object.values(pending[sessionID])) {
+ if (covered(itemKeys, approved[sessionID])) {
+ respond({ response: "always" });
+ }
+ }
+ }
+ ```
+
+6. **Custom error class** (lines 184-198)
+ ```typescript
+ class RejectedError extends Error {
+ constructor(
+ public readonly sessionID: string,
+ public readonly permissionID: string,
+ public readonly toolCallID?: string,
+ public readonly metadata?: Record<string, any>,
+ public readonly reason?: string,
+ ) { ... }
+ }
+ ```
+
+**Patterns to adopt:**
+
+- Pattern-based permission matching (wildcards)
+- Session-scoped approval state
+- "Always allow this pattern" propagation
+- Plugin interception for custom policies
+- Rich error context (sessionID, callID, metadata)
+
+## Key Takeaways
+
+### 1. **State Management**
+
+- Use `Instance.state()` for per-project state
+- Session-scoped tracking (FileTime, Todo)
+- Clean separation: pending vs approved (Permission)
+
+### 2. **Security Patterns**
+
+- AST parsing for command analysis (Bash)
+- Path resolution and external directory checks
+- Pattern-based permission system with wildcards
+- "Once" vs "Always" approval modes
+- Plugin hooks for custom policies
+
+### 3. **Error Handling**
+
+- Custom error classes with rich context
+- Helpful suggestions on failure (Read tool)
+- Clear distinction: no results ≠ error (Grep exit 1)
+- Timestamp-based conflict detection
+
+### 4. **Performance**
+
+- Lazy initialization (`lazy()` helper)
+- Streaming metadata during execution (Bash, Task)
+- Hard limits with truncation messages (Glob, Grep, Bash)
+- Modification time sorting for relevance
+
+### 5. **User Experience**
+
+- Tool history titles (e.g., "5 todos")
+- Truncation hints: "Use offset parameter to read beyond line X"
+- Clear permission prompts with diffs (Edit tool)
+- Progress tracking via event bus (Task tool)
+
+### 6. **Extensibility**
+
+- Tool.define() for consistent structure
+- Plugin system for custom tools
+- Event bus for loose coupling
+- Abort signal propagation
+- Context.metadata() for streaming updates
+
+### 7. **Platform Support**
+
+- Cross-platform process management (Bash)
+- Shell detection with fallbacks
+- Windows path normalization
+- Platform-specific defaults
+
+### Patterns to Avoid in Our Tools
+
+1. **Don't**: Hardcode file paths or assume Unix-only
+ - **Do**: Use `path.join()`, `path.isAbsolute()`, platform checks
+
+2. **Don't**: Ignore abort signals
+ - **Do**: Propagate `ctx.abort` to all async operations
+
+3. **Don't**: Return unlimited output
+ - **Do**: Set hard limits, truncate with metadata
+
+4. **Don't**: Silent failures
+ - **Do**: Clear error messages with suggestions
+
+5. **Don't**: Forget session context
+ - **Do**: Track state per `ctx.sessionID`
+
+### Immediate Improvements for Our Tools
+
+1. **bd-quick.ts** → Add streaming metadata for long operations
+2. **git-context.ts** → Implement mtime sorting for changed files
+3. **ubs.ts** → Add pattern-based permission for scan scope
+4. **typecheck.ts** → Stream errors as they're discovered
+5. **All tools** → Adopt `Tool.define()` pattern for consistency
+6. **All tools** → Add abort signal handling
+7. **All tools** → Add output size limits with truncation
+
+## Streaming Metadata API
+
+### Availability for Plugins
+
+**Status: NOT AVAILABLE** ❌
+
+The `ctx.metadata()` streaming API is **only available to OpenCode's built-in tools**, not to plugin tools.
+
+### Evidence
+
+1. **Plugin ToolContext type** (`@opencode-ai/plugin/dist/tool.d.ts`):
+
+ ```typescript
+ export type ToolContext = {
+ sessionID: string;
+ messageID: string;
+ agent: string;
+ abort: AbortSignal;
+ };
+ ```
+
+ No `metadata` method.
+
+2. **Built-in tools use extended context**:
+ Built-in tools (Bash, Task) use `ctx.metadata()` with an internal context type that extends the public `ToolContext` interface.
+
+ Example from Bash tool (line 298):
+
+ ```typescript
+ ctx.metadata({ metadata: { output: "", description } });
+ const append = (chunk: Buffer) => {
+ output += chunk.toString();
+ ctx.metadata({ metadata: { output, description } });
+ };
+ ```
+
+ Example from Task tool (line 479):
+
+ ```typescript
+ ctx.metadata({ metadata: { summary: Object.values(parts) } });
+ ```
+
+3. **Internal context type** (from opencode-tools.md line 22-34):
+ ```typescript
+ type Context = {
+ sessionID: string;
+ messageID: string;
+ agent: string;
+ abort: AbortSignal;
+ callID?: string;
+ extra?: Record<string, any>;
+ metadata(input): void; // ← Only in internal context
+ };
+ ```
+
+### Limitation Impact
+
+**What we can't do in plugins:**
+
+- Real-time progress updates during long operations
+- Stream incremental output before tool completes
+- Show live status during multi-step processes
+
+**Workarounds:**
+
+1. **Return progress in final output** - accumulate status and return comprehensive summary
+2. **Use Agent Mail for coordination** - send progress messages to other agents
+3. **Use hive_update** - update cell descriptions with progress checkpoints
+
+### Example: How Built-in Tools Use It
+
+**Bash tool** (streaming command output):
+
+```typescript
+// Initialize with empty output
+ctx.metadata({ metadata: { output: "", description } });
+
+// Stream chunks as they arrive
+proc.stdout?.on("data", (chunk) => {
+ output += chunk.toString();
+ ctx.metadata({ metadata: { output, description } });
+});
+```
+
+**Task tool** (streaming subtask progress):
+
+```typescript
+const parts = {};
+Bus.subscribe(MessageV2.Event.PartUpdated, async (evt) => {
+ parts[part.id] = { id, tool, state };
+ ctx.metadata({ metadata: { summary: Object.values(parts) } });
+});
+```
+
+### Feature Request?
+
+If streaming metadata becomes critical for plugin tools, this would need to be added to the `@opencode-ai/plugin` package by the OpenCode team. The plugin would need:
+
+1. Extended `ToolContext` type with `metadata()` method
+2. Infrastructure to handle streaming updates from plugin processes
+3. UI support for displaying streaming metadata from plugins
+
+Currently, plugin tools are limited to returning a single string result at completion.
+
+### Next Steps
+
+- Implement `Tool.define()` wrapper for our custom tools
+- Add FileTime-like tracking for beads state
+- Create Permission patterns for Agent Mail reservations
+- ~~Add streaming progress to swarm operations~~ (NOT POSSIBLE - no ctx.metadata)
+- Implement mtime-based sorting in cass search results
+- **Workaround**: Use Agent Mail for progress reporting in swarm tools
diff --git a/knowledge/prevention-patterns.md b/knowledge/prevention-patterns.md
new file mode 100644
index 0000000..9c022fc
--- /dev/null
+++ b/knowledge/prevention-patterns.md
@@ -0,0 +1,1317 @@
+# Prevention Patterns
+
+Maps common error patterns to preventive measures. Used by `/debug-plus` to auto-suggest preventive beads when debugging reveals systemic issues.
+
+## How to Use This File
+
+1. **During debugging**: `/debug-plus` auto-references this to suggest preventive beads
+2. **After fixes**: Check if the error pattern exists here, update with learnings
+3. **Proactive work**: Use pattern names for bead titles when adding preventive measures
+4. **Team patterns**: Add organization-specific recurring issues
+
+---
+
+## Pattern Format
+
+Each pattern follows this structure for machine parseability:
+
+```markdown
+### [Pattern Name]
+
+**Error Pattern:** `<error message regex or description>`
+
+**Root Cause:** Why this happens (architectural, process, or knowledge gap)
+
+**Prevention Action:** What to add/change to prevent future occurrences
+
+**Example Bead:** `Add [preventive measure] to prevent [error type]`
+
+**Priority:** [0-3] - How critical is prevention?
+
+**Effort:** [low|medium|high] - Implementation cost
+```
+
+---
+
+## React / Next.js Patterns
+
+### Missing Error Boundaries
+
+**Error Pattern:** `Uncaught Error.*|Application crashed|Error: .*\n\s+at.*\(.*.tsx`
+
+**Root Cause:** React errors bubble up and crash the entire component tree. No error boundaries means one component failure = full app crash.
+
+**Prevention Action:**
+
+- Add error boundary wrapper at layout/page level
+- Create domain-specific error boundaries (auth, data, UI)
+- Implement error reporting/logging in boundaries
+- Add fallback UIs for graceful degradation
+
+**Example Bead:** `Add error boundaries to [route/layout] to prevent cascading failures`
+
+**Priority:** 2 (high) - Affects user experience directly
+
+**Effort:** low - Standard pattern, reusable component
+
+**Prevention Code:**
+
+```typescript
+// app/error.tsx (page-level boundary)
+'use client'
+
+export default function Error({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ return (
+ <div>
+ <h2>Something went wrong!</h2>
+ <button onClick={reset}>Try again</button>
+ </div>
+ )
+}
+
+// Or custom boundary for specific sections
+import { ErrorBoundary } from 'react-error-boundary'
+
+function App() {
+ return (
+ <ErrorBoundary fallback={<ErrorFallback />}>
+ <RiskyComponent />
+ </ErrorBoundary>
+ )
+}
+```
+
+---
+
+### useEffect Cleanup Missing (Memory Leaks)
+
+**Error Pattern:** `Warning: Can't perform a React state update on an unmounted component|Memory leak detected|setTimeout.*after unmount`
+
+**Root Cause:** Async operations (timers, subscriptions, fetch) continue after component unmounts, attempting state updates or holding references.
+
+**Prevention Action:**
+
+- Always return cleanup function from useEffect
+- Use AbortController for fetch requests
+- Clear timers/intervals in cleanup
+- Unsubscribe from event listeners/streams
+- Add ESLint rule to enforce cleanup
+
+**Example Bead:** `Add useEffect cleanup to [component] to prevent memory leaks`
+
+**Priority:** 1 (medium) - Causes bugs over time, especially in SPA navigation
+
+**Effort:** low - Standard pattern once known
+
+**Prevention Code:**
+
+```typescript
+// Timers
+useEffect(() => {
+ const timer = setTimeout(() => doThing(), 1000);
+ return () => clearTimeout(timer); // CLEANUP
+}, []);
+
+// Event listeners
+useEffect(() => {
+ const handler = (e: Event) => setState(e.detail);
+ window.addEventListener("custom", handler);
+ return () => window.removeEventListener("custom", handler); // CLEANUP
+}, []);
+
+// Fetch with abort
+useEffect(() => {
+ const controller = new AbortController();
+
+ fetch(url, { signal: controller.signal })
+ .then((res) => res.json())
+ .then(setData)
+ .catch((err) => {
+ if (err.name !== "AbortError") handleError(err);
+ });
+
+ return () => controller.abort(); // CLEANUP
+}, [url]);
+
+// Subscriptions
+useEffect(() => {
+ const sub = observable.subscribe(setData);
+ return () => sub.unsubscribe(); // CLEANUP
+}, [observable]);
+```
+
+---
+
+### Null/Undefined Access Without Guards
+
+**Error Pattern:** `Cannot read propert.* of undefined|Cannot read propert.* of null|TypeError.*undefined`
+
+**Root Cause:** Accessing nested properties or array indices without checking existence first. TypeScript strictNullChecks not enabled or guards missing.
+
+**Prevention Action:**
+
+- Enable `strictNullChecks` in tsconfig
+- Use optional chaining (`?.`) for all nullable access
+- Use nullish coalescing (`??`) for defaults
+- Add runtime guards for external data
+- Use Zod/Effect Schema for API boundaries
+
+**Example Bead:** `Add null guards to [module] to prevent undefined access errors`
+
+**Priority:** 2 (high) - Very common runtime error
+
+**Effort:** low - Mostly syntax changes
+
+**Prevention Code:**
+
+```typescript
+// tsconfig.json - ENABLE THIS
+{
+ "compilerOptions": {
+ "strict": true,
+ "strictNullChecks": true
+ }
+}
+
+// Optional chaining
+const value = obj?.nested?.property // undefined if any step is null/undefined
+
+// Nullish coalescing for defaults
+const name = user?.name ?? 'Anonymous'
+
+// Array access
+const first = arr[0] ?? defaultItem
+const item = arr.find(x => x.id === id) ?? throwError('Not found')
+
+// Guard functions
+function assertExists<T>(value: T | null | undefined, msg?: string): asserts value is T {
+ if (value == null) throw new Error(msg ?? 'Value is null/undefined')
+}
+
+const user = getUser()
+assertExists(user, 'User not found')
+user.name // TypeScript knows user is non-null here
+
+// Zod for API boundaries
+import { z } from 'zod'
+
+const UserSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ email: z.string().email().optional(),
+})
+
+// Parse throws if data doesn't match
+const user = UserSchema.parse(unknownData)
+```
+
+---
+
+### Missing Loading/Error States
+
+**Error Pattern:** `User sees stale data|Form submits twice|No feedback on action|Spinner missing`
+
+**Root Cause:** UI doesn't communicate async operation status. No loading indicators, no error messages, no success feedback.
+
+**Prevention Action:**
+
+- Add loading states for all async operations
+- Show error messages with retry actions
+- Implement optimistic updates where appropriate
+- Use Suspense for server component loading
+- Add skeleton UIs for better perceived performance
+
+**Example Bead:** `Add loading/error states to [feature] to prevent UI confusion`
+
+**Priority:** 1 (medium) - UX issue, not critical bug
+
+**Effort:** medium - Requires UI design decisions
+
+**Prevention Code:**
+
+```typescript
+// Client component with loading/error
+'use client'
+
+function DataFetcher() {
+ const [data, setData] = useState(null)
+ const [loading, setLoading] = useState(false)
+ const [error, setError] = useState<Error | null>(null)
+
+ async function load() {
+ setLoading(true)
+ setError(null)
+ try {
+ const result = await fetchData()
+ setData(result)
+ } catch (e) {
+ setError(e as Error)
+ } finally {
+ setLoading(false)
+ }
+ }
+
+ if (loading) return <Spinner />
+ if (error) return <ErrorDisplay error={error} retry={load} />
+ if (!data) return <EmptyState onLoad={load} />
+
+ return <DataDisplay data={data} />
+}
+
+// Server component with Suspense
+export default function Page() {
+ return (
+ <Suspense fallback={<Skeleton />}>
+ <AsyncDataComponent />
+ </Suspense>
+ )
+}
+
+// Form with submission state
+function Form() {
+ const [pending, setPending] = useState(false)
+
+ async function handleSubmit(e: FormEvent) {
+ e.preventDefault()
+ setPending(true)
+ try {
+ await submitForm()
+ toast.success('Saved!')
+ } catch (err) {
+ toast.error('Failed to save')
+ } finally {
+ setPending(false)
+ }
+ }
+
+ return (
+ <form onSubmit={handleSubmit}>
+ <button disabled={pending}>
+ {pending ? 'Saving...' : 'Save'}
+ </button>
+ </form>
+ )
+}
+```
+
+---
+
+### Unhandled Promise Rejections
+
+**Error Pattern:** `UnhandledPromiseRejectionWarning|Unhandled promise rejection|Promise rejected with no catch`
+
+**Root Cause:** Async functions called without `await` or `.catch()`. Promises rejected but no error handler attached.
+
+**Prevention Action:**
+
+- Add `.catch()` to all promise chains
+- Use try/catch with async/await
+- Add global unhandled rejection handler
+- Enable ESLint `no-floating-promises` rule
+- Use Effect for typed error handling
+
+**Example Bead:** `Add promise error handling to [module] to prevent unhandled rejections`
+
+**Priority:** 2 (high) - Silent failures are dangerous
+
+**Effort:** low - Syntax additions
+
+**Prevention Code:**
+
+```typescript
+// ❌ BAD - promise floats, rejection unhandled
+fetchData();
+
+// ✅ GOOD - awaited with try/catch
+try {
+ const data = await fetchData();
+} catch (error) {
+ handleError(error);
+}
+
+// ✅ GOOD - promise chain with catch
+fetchData().then(handleSuccess).catch(handleError);
+
+// ✅ GOOD - void explicitly (when you truly don't care)
+void fetchData().catch(handleError);
+
+// Global handler (last resort logging)
+if (typeof window !== "undefined") {
+ window.addEventListener("unhandledrejection", (event) => {
+ console.error("Unhandled rejection:", event.reason);
+ // Send to error tracking service
+ });
+}
+
+// Effect for typed error handling
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+ const data = yield* Effect.tryPromise({
+ try: () => fetchData(),
+ catch: (error) => new FetchError({ cause: error }),
+ });
+ return data;
+});
+
+// All errors must be handled before running
+Effect.runPromise(
+ program.pipe(Effect.catchAll((error) => Effect.succeed(defaultValue))),
+);
+```
+
+---
+
+### Missing Input Validation
+
+**Error Pattern:** `SQL injection|XSS attack|Invalid data in database|Type error from API|Schema validation failed`
+
+**Root Cause:** Trusting user input without validation. No sanitization, no type checking, no constraints enforcement.
+
+**Prevention Action:**
+
+- Use Zod/Effect Schema at API boundaries
+- Validate on both client and server
+- Sanitize HTML before rendering
+- Use parameterized queries (never string concat SQL)
+- Add length/format constraints
+- Implement rate limiting for endpoints
+
+**Example Bead:** `Add input validation to [endpoint/form] to prevent injection attacks`
+
+**Priority:** 3 (critical) - Security vulnerability
+
+**Effort:** medium - Requires schema design
+
+**Prevention Code:**
+
+```typescript
+// Zod schema for validation
+import { z } from 'zod'
+
+const CreateUserSchema = z.object({
+ email: z.string().email().max(255),
+ name: z.string().min(1).max(100).trim(),
+ age: z.number().int().min(0).max(150).optional(),
+ role: z.enum(['user', 'admin']),
+})
+
+// Server action with validation
+'use server'
+
+export async function createUser(formData: FormData) {
+ // Parse and validate
+ const result = CreateUserSchema.safeParse({
+ email: formData.get('email'),
+ name: formData.get('name'),
+ age: Number(formData.get('age')),
+ role: formData.get('role'),
+ })
+
+ if (!result.success) {
+ return { error: result.error.flatten() }
+ }
+
+ // result.data is now type-safe and validated
+ const user = await db.user.create({ data: result.data })
+ return { user }
+}
+
+// API route validation
+export async function POST(req: Request) {
+ const body = await req.json()
+
+ // Validate before processing
+ const data = CreateUserSchema.parse(body) // throws if invalid
+
+ // Or safe parse for custom error handling
+ const result = CreateUserSchema.safeParse(body)
+ if (!result.success) {
+ return Response.json({ error: result.error }, { status: 400 })
+ }
+
+ // Process validated data
+}
+
+// HTML sanitization (if rendering user HTML)
+import DOMPurify from 'isomorphic-dompurify'
+
+function UserContent({ html }: { html: string }) {
+ const clean = DOMPurify.sanitize(html)
+ return <div dangerouslySetInnerHTML={{ __html: clean }} />
+}
+
+// SQL - ALWAYS use parameterized queries
+// ❌ BAD - SQL injection vulnerability
+const users = await db.query(`SELECT * FROM users WHERE email = '${email}'`)
+
+// ✅ GOOD - parameterized
+const users = await db.query('SELECT * FROM users WHERE email = $1', [email])
+```
+
+---
+
+### Race Conditions in Async Code
+
+**Error Pattern:** `Stale data displayed|Form submitted with old values|State update order wrong|useEffect race condition`
+
+**Root Cause:** Multiple async operations racing, last-to-finish wins (not last-to-start). No cancellation, no request deduplication.
+
+**Prevention Action:**
+
+- Use AbortController to cancel stale requests
+- Implement request deduplication
+- Use React Query/SWR for automatic dedup
+- Add request IDs to track latest
+- Use useTransition for controlled updates
+
+**Example Bead:** `Add race condition handling to [feature] to prevent stale data bugs`
+
+**Priority:** 1 (medium) - Causes confusing bugs
+
+**Effort:** medium - Requires architectural changes
+
+**Prevention Code:**
+
+```typescript
+// Race condition example (BAD)
+function SearchBox() {
+ const [query, setQuery] = useState("");
+ const [results, setResults] = useState([]);
+
+ useEffect(() => {
+ // If user types fast: "a" -> "ab" -> "abc"
+ // Requests may return: "abc" -> "a" -> "ab" (out of order!)
+ fetch(`/api/search?q=${query}`)
+ .then((res) => res.json())
+ .then(setResults); // ❌ Last response wins, not latest query
+ }, [query]);
+}
+
+// FIX 1: AbortController
+function SearchBox() {
+ const [query, setQuery] = useState("");
+ const [results, setResults] = useState([]);
+
+ useEffect(() => {
+ const controller = new AbortController();
+
+ fetch(`/api/search?q=${query}`, { signal: controller.signal })
+ .then((res) => res.json())
+ .then(setResults)
+ .catch((err) => {
+ if (err.name !== "AbortError") handleError(err);
+ });
+
+ return () => controller.abort(); // Cancel previous request
+ }, [query]);
+}
+
+// FIX 2: Request ID tracking
+function SearchBox() {
+ const [query, setQuery] = useState("");
+ const [results, setResults] = useState([]);
+ const latestRequestIdRef = useRef(0);
+
+ useEffect(() => {
+ const requestId = ++latestRequestIdRef.current;
+
+ fetch(`/api/search?q=${query}`)
+ .then((res) => res.json())
+ .then((data) => {
+ // Only update if this is still the latest request
+ if (requestId === latestRequestIdRef.current) {
+ setResults(data);
+ }
+ });
+ }, [query]);
+}
+
+// FIX 3: React Query (handles dedup automatically)
+import { useQuery } from "@tanstack/react-query";
+
+function SearchBox() {
+ const [query, setQuery] = useState("");
+
+ const { data: results } = useQuery({
+ queryKey: ["search", query],
+ queryFn: () => fetch(`/api/search?q=${query}`).then((r) => r.json()),
+ enabled: query.length > 0,
+ });
+ // Automatically cancels stale requests, deduplicates, caches
+}
+
+// FIX 4: Debounce + abort
+import { useDebouncedValue } from "./hooks";
+
+function SearchBox() {
+ const [query, setQuery] = useState("");
+ const debouncedQuery = useDebouncedValue(query, 300);
+ const [results, setResults] = useState([]);
+
+ useEffect(() => {
+ if (!debouncedQuery) return;
+
+ const controller = new AbortController();
+
+ fetch(`/api/search?q=${debouncedQuery}`, { signal: controller.signal })
+ .then((res) => res.json())
+ .then(setResults)
+ .catch((err) => {
+ if (err.name !== "AbortError") handleError(err);
+ });
+
+ return () => controller.abort();
+ }, [debouncedQuery]);
+}
+```
+
+---
+
+### Missing TypeScript Strict Checks
+
+**Error Pattern:** `Runtime type errors|undefined is not a function|Unexpected null|Type 'any' loses safety`
+
+**Root Cause:** TypeScript strict mode disabled. Using `any` liberally. Not enabling all strict flags in tsconfig.
+
+**Prevention Action:**
+
+- Enable ALL strict flags in tsconfig
+- Ban `any` except for truly dynamic types
+- Use `unknown` instead of `any` for dynamic data
+- Enable `noUncheckedIndexedAccess` for array safety
+- Run `tsc --noEmit` in CI to catch type errors
+
+**Example Bead:** `Enable TypeScript strict mode in [project] to prevent type errors`
+
+**Priority:** 2 (high) - Foundational safety
+
+**Effort:** high - May require fixing existing code
+
+**Prevention Code:**
+
+```json
+// tsconfig.json - THE GOLD STANDARD
+{
+ "compilerOptions": {
+ // Strict mode (enables all flags below)
+ "strict": true,
+
+ // Individual flags (strict=true enables these)
+ "strictNullChecks": true, // null/undefined must be explicit
+ "strictFunctionTypes": true, // function param contravariance
+ "strictBindCallApply": true, // bind/call/apply type-safe
+ "strictPropertyInitialization": true, // class props must be initialized
+ "noImplicitAny": true, // no implicit any types
+ "noImplicitThis": true, // this must have explicit type
+ "alwaysStrict": true, // emit 'use strict'
+
+ // Additional strict checks (NOT in strict mode)
+ "noUncheckedIndexedAccess": true, // array[i] returns T | undefined
+ "exactOptionalPropertyTypes": true, // {x?: string} vs {x?: string | undefined}
+ "noImplicitReturns": true, // all code paths must return
+ "noFallthroughCasesInSwitch": true, // switch cases must break/return
+ "noUnusedLocals": true, // catch unused variables
+ "noUnusedParameters": true, // catch unused params
+ "noPropertyAccessFromIndexSignature": true, // obj.prop vs obj['prop']
+
+ // Errors on any usage
+ "noImplicitAny": true
+ }
+}
+```
+
+```typescript
+// Replace 'any' with better alternatives
+
+// ❌ BAD
+function process(data: any) {
+ return data.value; // No type safety
+}
+
+// ✅ GOOD - unknown for dynamic data
+function process(data: unknown) {
+ // Must narrow before using
+ if (typeof data === "object" && data !== null && "value" in data) {
+ return data.value;
+ }
+ throw new Error("Invalid data");
+}
+
+// ✅ GOOD - generic for typed params
+function process<T extends { value: number }>(data: T) {
+ return data.value; // Type-safe
+}
+
+// ✅ GOOD - Zod for runtime + compile-time safety
+import { z } from "zod";
+
+const DataSchema = z.object({ value: z.number() });
+type Data = z.infer<typeof DataSchema>;
+
+function process(data: Data) {
+ return data.value;
+}
+
+// Parse at boundary
+const parsed = DataSchema.parse(unknownData);
+process(parsed);
+```
+
+---
+
+## API / Backend Patterns
+
+### Missing Request Timeout
+
+**Error Pattern:** `Request hangs indefinitely|No response from API|Connection never closes`
+
+**Root Cause:** No timeout configured for fetch/axios. External API hangs, your app waits forever.
+
+**Prevention Action:**
+
+- Set timeout on all fetch requests
+- Use AbortController with setTimeout
+- Add retry logic with exponential backoff
+- Implement circuit breaker for failing services
+
+**Example Bead:** `Add request timeouts to [API client] to prevent hanging requests`
+
+**Priority:** 1 (medium) - UX degradation
+
+**Effort:** low - Standard pattern
+
+**Prevention Code:**
+
+```typescript
+// Fetch with timeout
+async function fetchWithTimeout(
+ url: string,
+ options: RequestInit = {},
+ timeout = 5000,
+) {
+ const controller = new AbortController();
+ const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+ try {
+ const response = await fetch(url, {
+ ...options,
+ signal: controller.signal,
+ });
+ clearTimeout(timeoutId);
+ return response;
+ } catch (error) {
+ clearTimeout(timeoutId);
+ if (error instanceof Error && error.name === "AbortError") {
+ throw new Error(`Request timeout after ${timeout}ms`);
+ }
+ throw error;
+ }
+}
+
+// Next.js fetch with timeout (built-in)
+fetch(url, {
+ next: { revalidate: 60 },
+ signal: AbortSignal.timeout(5000), // Native timeout
+});
+
+// Retry with exponential backoff
+async function fetchWithRetry(
+ url: string,
+ options: RequestInit = {},
+ maxRetries = 3,
+ baseDelay = 1000,
+) {
+ for (let i = 0; i < maxRetries; i++) {
+ try {
+ return await fetchWithTimeout(url, options);
+ } catch (error) {
+ if (i === maxRetries - 1) throw error;
+
+ const delay = baseDelay * Math.pow(2, i); // Exponential backoff
+ await new Promise((resolve) => setTimeout(resolve, delay));
+ }
+ }
+ throw new Error("Max retries reached");
+}
+```
+
+---
+
+### Missing Rate Limiting
+
+**Error Pattern:** `429 Too Many Requests|API quota exceeded|DDoS attack|Cost spike from API abuse`
+
+**Root Cause:** No rate limiting on endpoints. Malicious users or bugs can hammer API, causing outages or cost overruns.
+
+**Prevention Action:**
+
+- Implement rate limiting middleware
+- Use Redis for distributed rate limiting
+- Add per-user and per-IP limits
+- Return proper 429 status with Retry-After
+- Add request queuing for bursts
+
+**Example Bead:** `Add rate limiting to [API routes] to prevent abuse`
+
+**Priority:** 2 (high) - Security and cost issue
+
+**Effort:** medium - Infrastructure required
+
+**Prevention Code:**
+
+```typescript
+// Simple in-memory rate limiter (single server only)
+const rateLimit = new Map<string, { count: number; resetAt: number }>();
+
+function checkRateLimit(identifier: string, limit = 10, windowMs = 60000) {
+ const now = Date.now();
+ const record = rateLimit.get(identifier);
+
+ if (!record || now > record.resetAt) {
+ rateLimit.set(identifier, { count: 1, resetAt: now + windowMs });
+ return true;
+ }
+
+ if (record.count >= limit) {
+ return false;
+ }
+
+ record.count++;
+ return true;
+}
+
+// Next.js API route with rate limiting
+export async function POST(req: Request) {
+ const ip = req.headers.get("x-forwarded-for") ?? "unknown";
+
+ if (!checkRateLimit(ip, 10, 60000)) {
+ return Response.json(
+ { error: "Too many requests" },
+ {
+ status: 429,
+ headers: { "Retry-After": "60" },
+ },
+ );
+ }
+
+ // Process request
+}
+
+// Production: Use Redis with upstash/ratelimit
+import { Ratelimit } from "@upstash/ratelimit";
+import { Redis } from "@upstash/redis";
+
+const ratelimit = new Ratelimit({
+ redis: Redis.fromEnv(),
+ limiter: Ratelimit.slidingWindow(10, "1 m"), // 10 requests per minute
+});
+
+export async function POST(req: Request) {
+ const ip = req.headers.get("x-forwarded-for") ?? "unknown";
+ const { success, limit, reset, remaining } = await ratelimit.limit(ip);
+
+ if (!success) {
+ return Response.json(
+ { error: "Too many requests" },
+ {
+ status: 429,
+ headers: {
+ "X-RateLimit-Limit": limit.toString(),
+ "X-RateLimit-Remaining": remaining.toString(),
+ "X-RateLimit-Reset": new Date(reset).toISOString(),
+ },
+ },
+ );
+ }
+
+ // Process request
+}
+```
+
+---
+
+### Missing Authentication/Authorization Checks
+
+**Error Pattern:** `Unauthorized access to data|User accessed admin route|Data leak|IDOR vulnerability`
+
+**Root Cause:** Auth checks missing or inconsistent. Checking auth on client but not server. No role-based access control.
+
+**Prevention Action:**
+
+- Always verify auth on server
+- Never trust client-side auth checks
+- Implement middleware for auth verification
+- Add role-based access control (RBAC)
+- Validate resource ownership before mutations
+
+**Example Bead:** `Add auth checks to [routes] to prevent unauthorized access`
+
+**Priority:** 3 (critical) - Security vulnerability
+
+**Effort:** medium - Requires auth infrastructure
+
+**Prevention Code:**
+
+```typescript
+// Next.js middleware for route protection
+// middleware.ts
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import { getSession } from "./lib/auth";
+
+export async function middleware(request: NextRequest) {
+ const session = await getSession(request);
+
+ // Protect /dashboard routes
+ if (request.nextUrl.pathname.startsWith("/dashboard")) {
+ if (!session) {
+ return NextResponse.redirect(new URL("/login", request.url));
+ }
+ }
+
+ // Protect /admin routes
+ if (request.nextUrl.pathname.startsWith("/admin")) {
+ if (!session || session.user.role !== "admin") {
+ return NextResponse.redirect(new URL("/unauthorized", request.url));
+ }
+ }
+
+ return NextResponse.next();
+}
+
+export const config = {
+ matcher: ["/dashboard/:path*", "/admin/:path*"],
+};
+
+// Server action with auth check
+("use server");
+
+import { auth } from "./lib/auth";
+
+export async function deletePost(postId: string) {
+ const session = await auth();
+
+ // Check authentication
+ if (!session) {
+ throw new Error("Unauthorized");
+ }
+
+ // Check ownership (prevent IDOR)
+ const post = await db.post.findUnique({ where: { id: postId } });
+ if (!post) {
+ throw new Error("Post not found");
+ }
+
+ if (post.authorId !== session.user.id) {
+ throw new Error("Forbidden: You can only delete your own posts");
+ }
+
+ // Now safe to delete
+ await db.post.delete({ where: { id: postId } });
+}
+
+// API route with RBAC
+export async function DELETE(
+ req: Request,
+ { params }: { params: { id: string } },
+) {
+ const session = await auth();
+
+ if (!session) {
+ return Response.json({ error: "Unauthorized" }, { status: 401 });
+ }
+
+ // Check role
+ if (session.user.role !== "admin" && session.user.role !== "moderator") {
+ return Response.json({ error: "Forbidden" }, { status: 403 });
+ }
+
+ // Check resource ownership or permissions
+ const resource = await db.resource.findUnique({ where: { id: params.id } });
+
+ if (!resource) {
+ return Response.json({ error: "Not found" }, { status: 404 });
+ }
+
+ const canDelete =
+ session.user.role === "admin" ||
+ (session.user.role === "moderator" &&
+ resource.authorId === session.user.id);
+
+ if (!canDelete) {
+ return Response.json({ error: "Forbidden" }, { status: 403 });
+ }
+
+ await db.resource.delete({ where: { id: params.id } });
+ return Response.json({ success: true });
+}
+```
+
+---
+
+## Database / Data Patterns
+
+### Missing Database Indexes
+
+**Error Pattern:** `Query timeout|Slow query|Database CPU at 100%|Full table scan detected`
+
+**Root Cause:** Querying columns without indexes. Database scans entire table instead of using index.
+
+**Prevention Action:**
+
+- Add indexes to frequently queried columns
+- Index foreign keys
+- Add composite indexes for multi-column queries
+- Monitor slow query logs
+- Use EXPLAIN to analyze query plans
+
+**Example Bead:** `Add database indexes to [table] to prevent slow queries`
+
+**Priority:** 1 (medium) - Performance issue
+
+**Effort:** low - Simple migration
+
+**Prevention Code:**
+
+```sql
+-- Identify slow queries first
+-- PostgreSQL
+SELECT query, calls, total_time, mean_time
+FROM pg_stat_statements
+ORDER BY mean_time DESC
+LIMIT 10;
+
+-- Add index to single column
+CREATE INDEX idx_users_email ON users(email);
+
+-- Add composite index for multi-column WHERE
+CREATE INDEX idx_posts_author_status ON posts(author_id, status);
+
+-- Add partial index for filtered queries
+CREATE INDEX idx_posts_published ON posts(published_at)
+WHERE status = 'published';
+
+-- Add index for foreign keys (CRITICAL)
+CREATE INDEX idx_posts_author_id ON posts(author_id);
+
+-- Prisma schema with indexes
+model Post {
+ id String @id @default(cuid())
+ authorId String
+ status String
+ publishedAt DateTime?
+
+ author User @relation(fields: [authorId], references: [id])
+
+ @@index([authorId]) // Foreign key index
+ @@index([status, publishedAt]) // Composite for queries
+ @@index([publishedAt], where: { status: 'published' }) // Partial index
+}
+```
+
+---
+
+### Missing Database Transactions
+
+**Error Pattern:** `Data inconsistency|Partial update|Race condition in DB|Lost update problem`
+
+**Root Cause:** Multiple related database operations not wrapped in transaction. Failure in middle leaves inconsistent state.
+
+**Prevention Action:**
+
+- Use transactions for multi-step operations
+- Wrap related INSERT/UPDATE/DELETE in transaction
+- Use optimistic locking for concurrent updates
+- Implement idempotency for retryable operations
+
+**Example Bead:** `Add database transactions to [operation] to prevent data inconsistency`
+
+**Priority:** 2 (high) - Data integrity issue
+
+**Effort:** low - Framework usually provides this
+
+**Prevention Code:**
+
+```typescript
+// Prisma transaction
+import { prisma } from './lib/db'
+
+// ❌ BAD - no transaction
+async function transferMoney(fromId: string, toId: string, amount: number) {
+ await prisma.account.update({
+ where: { id: fromId },
+ data: { balance: { decrement: amount } }
+ })
+
+ // If this fails, money is lost!
+ await prisma.account.update({
+ where: { id: toId },
+ data: { balance: { increment: amount } }
+ })
+}
+
+// ✅ GOOD - transaction ensures all-or-nothing
+async function transferMoney(fromId: string, toId: string, amount: number) {
+ await prisma.$transaction(async (tx) => {
+ // Decrement sender
+ await tx.account.update({
+ where: { id: fromId },
+ data: { balance: { decrement: amount } }
+ })
+
+ // Increment receiver
+ await tx.account.update({
+ where: { id: toId },
+ data: { balance: { increment: amount } }
+ })
+ })
+ // If ANY operation fails, ALL are rolled back
+}
+
+// Optimistic locking with version field
+model Account {
+ id String @id
+ balance Int
+ version Int @default(0) // Increment on every update
+}
+
+async function updateAccountSafe(id: string, newBalance: number) {
+ const account = await prisma.account.findUnique({ where: { id } })
+
+ const updated = await prisma.account.updateMany({
+ where: {
+ id,
+ version: account.version, // Only update if version matches
+ },
+ data: {
+ balance: newBalance,
+ version: { increment: 1 },
+ },
+ })
+
+ if (updated.count === 0) {
+ throw new Error('Concurrent modification detected, retry')
+ }
+}
+```
+
+---
+
+## Build / Deployment Patterns
+
+### Missing Environment Variable Validation
+
+**Error Pattern:** `undefined is not a function|Cannot connect to database|API key missing|Runtime config error`
+
+**Root Cause:** Environment variables not validated at build/startup time. App starts with missing/invalid config, fails at runtime.
+
+**Prevention Action:**
+
+- Validate env vars at startup
+- Use Zod schema for env validation
+- Fail fast if required vars missing
+- Type-safe env access
+- Document required env vars
+
+**Example Bead:** `Add env validation to [project] to prevent runtime config errors`
+
+**Priority:** 2 (high) - Prevents runtime failures
+
+**Effort:** low - One-time setup
+
+**Prevention Code:**
+
+```typescript
+// env.ts - Single source of truth for env vars
+import { z } from "zod";
+
+const envSchema = z.object({
+ // Node env
+ NODE_ENV: z.enum(["development", "production", "test"]),
+
+ // Database
+ DATABASE_URL: z.string().url(),
+
+ // APIs
+ NEXT_PUBLIC_API_URL: z.string().url(),
+ API_SECRET_KEY: z.string().min(32),
+
+ // Optional with defaults
+ PORT: z.coerce.number().default(3000),
+ LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+});
+
+// Validate at module load (fails fast)
+const parsed = envSchema.safeParse(process.env);
+
+if (!parsed.success) {
+ console.error(
+ "❌ Invalid environment variables:",
+ parsed.error.flatten().fieldErrors,
+ );
+ throw new Error("Invalid environment variables");
+}
+
+// Export typed env
+export const env = parsed.data;
+
+// Now use type-safe env everywhere
+import { env } from "./env";
+
+const db = new Database(env.DATABASE_URL);
+const port = env.PORT; // number, not string
+
+// Next.js specific - validate in next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+ env: {
+ // Fails build if missing
+ REQUIRED_VAR: process.env.REQUIRED_VAR,
+ },
+ // Or use experimental.envSchema (Next.js 15+)
+ experimental: {
+ envSchema: {
+ DATABASE_URL: z.string().url(),
+ API_KEY: z.string(),
+ },
+ },
+};
+```
+
+---
+
+### Missing Health Checks
+
+**Error Pattern:** `503 Service Unavailable|Load balancer routing to dead instances|Can't tell if app is healthy`
+
+**Root Cause:** No health check endpoint. Load balancers/orchestrators can't verify app health, route traffic to broken instances.
+
+**Prevention Action:**
+
+- Add /health and /ready endpoints
+- Check database connectivity in health check
+- Check external dependencies
+- Return 200 for healthy, 503 for unhealthy
+- Separate liveness (is running?) from readiness (can serve traffic?)
+
+**Example Bead:** `Add health check endpoint to [service] to enable monitoring`
+
+**Priority:** 1 (medium) - Ops requirement for production
+
+**Effort:** low - Standard pattern
+
+**Prevention Code:**
+
+```typescript
+// app/api/health/route.ts - Liveness probe (is process alive?)
+export async function GET() {
+ return Response.json({ status: "ok", timestamp: new Date().toISOString() });
+}
+
+// app/api/ready/route.ts - Readiness probe (can serve traffic?)
+import { prisma } from "@/lib/db";
+
+export async function GET() {
+ const checks = {
+ database: false,
+ redis: false,
+ };
+
+ try {
+ // Check database
+ await prisma.$queryRaw`SELECT 1`;
+ checks.database = true;
+
+ // Check Redis (if used)
+ // await redis.ping()
+ // checks.redis = true
+
+ const allHealthy = Object.values(checks).every(Boolean);
+
+ return Response.json(
+ {
+ status: allHealthy ? "ready" : "not_ready",
+ checks,
+ timestamp: new Date().toISOString(),
+ },
+ { status: allHealthy ? 200 : 503 },
+ );
+ } catch (error) {
+ return Response.json(
+ {
+ status: "error",
+ checks,
+ error: error instanceof Error ? error.message : "Unknown error",
+ timestamp: new Date().toISOString(),
+ },
+ { status: 503 },
+ );
+ }
+}
+
+// Kubernetes deployment.yaml
+// livenessProbe:
+// httpGet:
+// path: /api/health
+// port: 3000
+// initialDelaySeconds: 10
+// periodSeconds: 5
+//
+// readinessProbe:
+// httpGet:
+// path: /api/ready
+// port: 3000
+// initialDelaySeconds: 5
+// periodSeconds: 3
+```
+
+---
+
+## Adding New Patterns
+
+When you discover a new preventable error pattern:
+
+1. **Identify recurrence**: Has this happened >2 times in different contexts?
+2. **Find root cause**: Why does this keep happening?
+3. **Define prevention**: What systematic change prevents it?
+4. **Create bead template**: What's the actionable task title?
+5. **Add to this file**: Follow the format above
+
+Then create a cell to track adding it:
+
+```bash
+hive_create({
+ title: "Prevention pattern: [error type]",
+ type: "chore",
+ description: "Add [error] to prevention-patterns.md with prevention actions"
+})
+```
+
+---
+
+## Integration with /debug-plus
+
+The `/debug-plus` command references this file to suggest preventive beads:
+
+1. User hits error
+2. `/debug-plus` matches error to pattern
+3. Extracts "Prevention Action" and "Example Bead"
+4. Suggests creating bead with preventive work
+5. Logs pattern match for learning
+
+**Format requirements for machine parsing:**
+
+- `**Error Pattern:**` - Must contain regex or description
+- `**Prevention Action:**` - Bullet list of actions
+- `**Example Bead:**` - Bead title template with [placeholders]
+- `**Priority:**` - 0-3 for bead priority
+- `**Effort:**` - low|medium|high for estimation
+
+Keep patterns focused, actionable, and backed by real examples.
diff --git a/knowledge/tdd-patterns.md b/knowledge/tdd-patterns.md
new file mode 100644
index 0000000..519154a
--- /dev/null
+++ b/knowledge/tdd-patterns.md
@@ -0,0 +1,540 @@
+# TDD Patterns: Red-Green-Refactor
+
+**The non-negotiable discipline for swarm work.**
+
+> "Legacy code is simply code without tests." — Michael Feathers, _Working Effectively with Legacy Code_
+
+> "Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior." — Martin Fowler, _Refactoring_
+
+---
+
+## The Cycle
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ RED → GREEN → REFACTOR │
+├─────────────────────────────────────────────────────────────────┤
+│ │
+│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
+│ │ RED │────────▶│ GREEN │────────▶│REFACTOR │ │
+│ │ │ │ │ │ │ │
+│ │ Write a │ │ Make it │ │ Clean │ │
+│ │ failing │ │ pass │ │ it up │ │
+│ │ test │ │ (fast) │ │ │ │
+│ └─────────┘ └─────────┘ └─────────┘ │
+│ ▲ │ │
+│ │ │ │
+│ └───────────────────────────────────────┘ │
+│ │
+│ Repeat until feature complete │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### RED: Write a Failing Test
+
+1. Write a test for behavior that doesn't exist yet
+2. Run it — **it MUST fail**
+3. If it passes, your test is wrong or the behavior already exists
+4. The failure message should be clear about what's missing
+
+```typescript
+// RED - this test fails because calculateTax doesn't exist
+test("calculates 10% tax on order total", () => {
+ const order = { items: [{ price: 100 }] };
+ expect(calculateTax(order)).toBe(10);
+});
+// Error: calculateTax is not defined
+```
+
+### GREEN: Make It Pass (Quickly)
+
+1. Write the **minimum code** to make the test pass
+2. Don't worry about elegance — just make it work
+3. Hardcoding is fine if it makes the test pass
+4. You'll clean it up in REFACTOR
+
+```typescript
+// GREEN - simplest thing that works
+function calculateTax(order: Order): number {
+ return 10; // hardcoded! that's fine for now
+}
+// Test passes ✓
+```
+
+### REFACTOR: Clean It Up
+
+1. Tests are passing — now improve the code
+2. Remove duplication
+3. Improve names
+4. Extract functions/classes
+5. **Run tests after every change** — they must stay green
+
+```typescript
+// REFACTOR - now make it real
+function calculateTax(order: Order): number {
+ const total = order.items.reduce((sum, item) => sum + item.price, 0);
+ return total * 0.1;
+}
+// Tests still pass ✓
+```
+
+---
+
+## Why This Order Matters
+
+### RED First
+
+- **Proves the test can fail** — a test that can't fail is worthless
+- **Defines the target** — you know exactly what you're building
+- **Documents intent** — the test IS the specification
+
+### GREEN Second
+
+- **Shortest path to working** — don't over-engineer
+- **Builds confidence** — you have a safety net
+- **Enables refactoring** — can't refactor without tests
+
+### REFACTOR Third
+
+- **Safe to change** — tests catch regressions
+- **Incremental improvement** — small steps, always green
+- **Design emerges** — patterns reveal themselves
+
+---
+
+## The Feathers Legacy Code Algorithm
+
+When working with existing code that lacks tests:
+
+```
+1. Identify change points
+2. Find test points
+3. Break dependencies
+4. Write tests (characterization tests first)
+5. Make changes
+6. Refactor
+```
+
+### Characterization Tests
+
+When you don't know what code does, write tests that **document actual behavior**:
+
+```typescript
+// Step 1: Write a test you KNOW will fail
+test("processOrder returns... something", () => {
+ const result = processOrder({ id: 1, items: [] });
+ expect(result).toBe("PLACEHOLDER"); // will fail
+});
+
+// Step 2: Run it, see actual output
+// Error: Expected "PLACEHOLDER", got { status: "empty", total: 0 }
+
+// Step 3: Update test to match reality
+test("processOrder returns empty status for no items", () => {
+ const result = processOrder({ id: 1, items: [] });
+ expect(result).toEqual({ status: "empty", total: 0 });
+});
+// Now you've documented what it actually does
+```
+
+**Key insight**: Characterization tests don't verify correctness — they verify **preservation**. They let you refactor safely.
+
+---
+
+## Breaking Dependencies for Testability
+
+From _Working Effectively with Legacy Code_:
+
+### The Seam Model
+
+A **seam** is a place where you can alter behavior without editing the source file.
+
+```typescript
+// BEFORE: Untestable - hard dependency
+class OrderProcessor {
+ process(order: Order) {
+ const db = new ProductionDatabase(); // can't test this
+ return db.save(order);
+ }
+}
+
+// AFTER: Testable - dependency injection (object seam)
+class OrderProcessor {
+ constructor(private db: Database = new ProductionDatabase()) {}
+
+ process(order: Order) {
+ return this.db.save(order);
+ }
+}
+
+// In tests:
+const fakeDb = { save: jest.fn() };
+const processor = new OrderProcessor(fakeDb);
+```
+
+### Common Dependency-Breaking Techniques
+
+| Technique | When to Use |
+| ---------------------------- | ------------------------------------ |
+| **Parameterize Constructor** | Class has hidden dependencies |
+| **Extract Interface** | Need to swap implementations |
+| **Subclass and Override** | Can't change constructor signature |
+| **Extract Method** | Need to isolate behavior for testing |
+| **Introduce Static Setter** | Global/singleton dependencies |
+
+---
+
+## TDD in Swarm Context
+
+### For New Features
+
+```
+1. Coordinator decomposes task
+2. Worker receives subtask
+3. Worker writes failing test FIRST
+4. Worker implements until green
+5. Worker refactors
+6. swarm_complete runs verification gate
+```
+
+### For Bug Fixes
+
+```
+1. Write a test that reproduces the bug (RED)
+2. Fix the bug (GREEN)
+3. Refactor if needed
+4. The test prevents regression forever
+```
+
+### For Refactoring
+
+```
+1. Write characterization tests for existing behavior
+2. Verify tests pass (they document current state)
+3. Refactor in small steps
+4. Run tests after EVERY change
+5. If tests fail, you broke something — revert
+```
+
+---
+
+## Anti-Patterns
+
+### ❌ Overspecified Tests (THE WORST)
+
+> "Mocks have their place, but excess mocking breaks encapsulation and tests a mechanism rather than a behavior." — Adam Tornhill, _Software Design X-Rays_
+
+Overspecified tests are **brittle garbage** that:
+
+- Break on every refactor even when behavior is unchanged
+- Test implementation details instead of outcomes
+- Create false confidence (tests pass but code is wrong)
+- Make refactoring terrifying instead of safe
+
+**Symptoms:**
+
+```typescript
+// ❌ OVERSPECIFIED - tests HOW, not WHAT
+test("saves user", () => {
+ const mockDb = { query: jest.fn() };
+ const mockLogger = { info: jest.fn() };
+ const mockValidator = { validate: jest.fn().mockReturnValue(true) };
+
+ saveUser({ name: "Joel" }, mockDb, mockLogger, mockValidator);
+
+ expect(mockValidator.validate).toHaveBeenCalledWith({ name: "Joel" });
+ expect(mockDb.query).toHaveBeenCalledWith(
+ "INSERT INTO users (name) VALUES (?)",
+ ["Joel"],
+ );
+ expect(mockLogger.info).toHaveBeenCalledWith("User saved: Joel");
+});
+// Change ANY internal detail and this test breaks
+// Even if the user still gets saved correctly!
+
+// ✅ BEHAVIOR-FOCUSED - tests WHAT, not HOW
+test("saves user and can retrieve them", async () => {
+ await saveUser({ name: "Joel" });
+
+ const user = await getUser("Joel");
+ expect(user.name).toBe("Joel");
+});
+// Refactor internals freely - test only breaks if behavior breaks
+```
+
+**The Fix:**
+
+- Test **observable behavior**, not internal mechanics
+- Ask: "If I refactor the implementation, should this test break?"
+- If the answer is "no" but it would break → overspecified
+- Prefer integration tests over unit tests with heavy mocking
+- Mock at boundaries (network, filesystem), not between your own classes
+
+### ❌ Writing Tests After Code
+
+- You don't know if the test can fail
+- Tests often test implementation, not behavior
+- Harder to achieve good coverage
+
+### ❌ Skipping RED
+
+- "I'll just write the code and test together"
+- You lose the specification benefit
+- Tests may not actually test what you think
+
+### ❌ Big GREEN Steps
+
+- Writing too much code before running tests
+- Harder to debug when tests fail
+- Loses the feedback loop benefit
+
+### ❌ Skipping REFACTOR
+
+- "It works, ship it"
+- Technical debt accumulates
+- Code becomes legacy code
+
+### ❌ Refactoring Without Tests
+
+- "I'll just clean this up real quick"
+- No safety net
+- Bugs introduced silently
+
+---
+
+## What Good Tests Look Like
+
+> "Think about letting the code in the test be a mirror of the test description." — Corey Haines, _4 Rules of Simple Design_
+> `pdf-brain_search(query="test name influence test code explicit")`
+
+### One Assertion Per Test
+
+> "As a general rule, it's wise to have only a single verify statement in each it clause. This is because the test will fail on the first verification failure—which can often hide useful information when you're figuring out why a test is broken." — Martin Fowler, _Refactoring_
+> `pdf-brain_search(query="single verify statement it clause")`
+
+When a test with 15 assertions fails, which one broke? You're now debugging your tests instead of your code.
+
+```typescript
+// ❌ BAD: Multiple assertions - which one failed?
+test("user registration", async () => {
+ const result = await register({ email: "a@b.com", password: "12345678" });
+
+ expect(result.success).toBe(true);
+ expect(result.user.email).toBe("a@b.com");
+ expect(result.user.id).toBeDefined();
+ expect(result.user.createdAt).toBeInstanceOf(Date);
+ expect(result.token).toMatch(/^eyJ/);
+ expect(sendWelcomeEmail).toHaveBeenCalled();
+ expect(analytics.track).toHaveBeenCalledWith("user_registered");
+});
+// Test fails: "expected true, got false" — WHICH expectation?!
+
+// ✅ GOOD: One behavior per test
+describe("user registration", () => {
+ test("returns success for valid input", async () => {
+ const result = await register({ email: "a@b.com", password: "12345678" });
+ expect(result.success).toBe(true);
+ });
+
+ test("creates user with provided email", async () => {
+ const result = await register({ email: "a@b.com", password: "12345678" });
+ expect(result.user.email).toBe("a@b.com");
+ });
+
+ test("generates auth token", async () => {
+ const result = await register({ email: "a@b.com", password: "12345678" });
+ expect(result.token).toMatch(/^eyJ/);
+ });
+
+ test("sends welcome email", async () => {
+ await register({ email: "a@b.com", password: "12345678" });
+ expect(sendWelcomeEmail).toHaveBeenCalled();
+ });
+});
+// Test fails: "user registration > sends welcome email" — IMMEDIATELY obvious
+```
+
+**Exception:** Multiple assertions on the _same_ logical thing are fine:
+
+```typescript
+// ✅ OK: Multiple assertions, one concept
+test("returns user object with required fields", async () => {
+ const user = await getUser(1);
+
+ expect(user).toMatchObject({
+ id: 1,
+ email: expect.any(String),
+ createdAt: expect.any(Date),
+ });
+});
+```
+
+### Arrange-Act-Assert (Given-When-Then)
+
+> "You'll hear these phases described variously as setup-exercise-verify, given-when-then, or arrange-act-assert." — Martin Fowler, _Refactoring_
+> `pdf-brain_search(query="setup exercise verify given when then arrange")`
+
+Structure every test the same way:
+
+```typescript
+test("applies discount to orders over $100", () => {
+ // ARRANGE (Given): Set up the scenario
+ const order = new Order();
+ order.addItem({ price: 150 });
+
+ // ACT (When): Do the thing
+ const total = order.checkout();
+
+ // ASSERT (Then): Verify the outcome
+ expect(total).toBe(135); // 10% discount
+});
+```
+
+This structure makes tests **scannable**. You can glance at any test and immediately understand:
+
+- What's the setup?
+- What action triggers the behavior?
+- What's the expected outcome?
+
+### Test Names as Executable Specifications
+
+> "A characterization test is a test that characterizes the actual behavior of a piece of code. There's no 'Well, it should do this' or 'I think it does that.' The tests document the actual current behavior." — Michael Feathers, _Working Effectively with Legacy Code_
+> `pdf-brain_search(query="characterization test actual behavior document")`
+
+Your test names should read like a spec. Someone should understand the system's behavior just by reading test names:
+
+```typescript
+describe("ShoppingCart", () => {
+ test("starts empty");
+ test("adds items with quantity");
+ test("calculates subtotal from item prices");
+ test("applies percentage discount codes");
+ test("rejects expired discount codes");
+ test("limits quantity to available stock");
+ test("preserves items across sessions for logged-in users");
+});
+// This IS the specification. No separate docs needed.
+```
+
+**BDD-style naming** (Given/When/Then in the name):
+
+```typescript
+describe("checkout", () => {
+ test("given cart over $100, when checking out, then applies free shipping");
+ test("given expired coupon, when applying, then shows error message");
+ test(
+ "given out-of-stock item, when checking out, then removes item and notifies user",
+ );
+});
+```
+
+### Test Behavior, Not Implementation
+
+```typescript
+// ✅ GOOD: Tests the contract
+test("cart calculates total with tax", () => {
+ const cart = new Cart();
+ cart.add({ price: 100 });
+ cart.add({ price: 50 });
+
+ expect(cart.totalWithTax(0.1)).toBe(165);
+});
+
+// ❌ BAD: Tests internal structure
+test("cart stores items in array and calls tax calculator", () => {
+ const cart = new Cart();
+ cart.add({ price: 100 });
+
+ expect(cart.items).toHaveLength(1);
+ expect(cart.taxCalculator.calculate).toHaveBeenCalled();
+});
+```
+
+### The "Refactor Test"
+
+Before committing a test, ask: **"If I completely rewrote the implementation but kept the same behavior, would this test still pass?"**
+
+- If yes → good test
+- If no → you're testing implementation details
+
+### Mock Boundaries, Not Internals
+
+```typescript
+// ✅ Mock external boundaries
+const mockFetch = jest.fn().mockResolvedValue({ data: "..." });
+// Network is a boundary - mock it
+
+// ❌ Don't mock your own classes
+const mockUserService = { getUser: jest.fn() };
+// This is YOUR code - use the real thing or you're not testing anything
+```
+
+### Test Names Are Documentation
+
+```typescript
+// ✅ Describes behavior
+test("rejects passwords shorter than 8 characters");
+test("sends welcome email after successful registration");
+test("returns cached result when called within TTL");
+
+// ❌ Describes implementation
+test("calls validatePassword method");
+test("uses EmailService");
+test("checks cache map");
+```
+
+---
+
+## The Mantra
+
+```
+RED → What do I want?
+GREEN → How do I get it?
+REFACTOR → How do I make it right?
+```
+
+**Never skip a step. Never change the order.**
+
+---
+
+## References (In the Lore Crates)
+
+These books are indexed in `pdf-brain`. Query for deeper wisdom:
+
+```bash
+# Find TDD fundamentals
+pdf-brain_search(query="TDD red green refactor Kent Beck")
+
+# Legacy code techniques
+pdf-brain_search(query="Feathers seam dependency breaking test harness")
+
+# Refactoring mechanics
+pdf-brain_search(query="Fowler refactoring behavior preserving small steps")
+
+# Simple design rules
+pdf-brain_search(query="Kent Beck four rules simple design")
+```
+
+| Book | Author | Key Concepts |
+| ---------------------------------------- | ---------------- | -------------------------------------------------------------------------------------- |
+| **Working Effectively with Legacy Code** | Michael Feathers | Seams, characterization tests, dependency breaking, "legacy code = code without tests" |
+| **Refactoring** | Martin Fowler | Behavior-preserving transformations, small steps, catalog of refactorings |
+| **Test-Driven Development: By Example** | Kent Beck | Red-green-refactor, fake it til you make it, triangulation |
+| **4 Rules of Simple Design** | Corey Haines | Tests pass, reveals intent, no duplication, fewest elements |
+
+### Key Quotes to Remember
+
+> "Legacy code is simply code without tests." — Feathers
+
+> "Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior." — Fowler
+
+> "The act of writing a unit test is more an act of design than of verification." — Beck
+
+---
+
+## Related Resources
+
+- `@knowledge/testing-patterns.md` — Testing trophy, async patterns, common pitfalls
+- `skills_use(name="testing-patterns")` — 25 dependency-breaking techniques catalog
+- `pdf-brain_search()` — Deep dive into the source material
diff --git a/knowledge/testing-patterns.md b/knowledge/testing-patterns.md
new file mode 100644
index 0000000..76af49e
--- /dev/null
+++ b/knowledge/testing-patterns.md
@@ -0,0 +1,934 @@
+# Testing Patterns
+
+Testing strategies, patterns, and best practices. Focused on pragmatic testing that catches bugs without becoming a maintenance burden.
+
+## How to Use This File
+
+1. **Starting a test suite**: Read Testing Philosophy first
+2. **Deciding what to test**: Check Testing Trophy section
+3. **Debugging flaky tests**: Check Async Testing and Common Pitfalls
+4. **Code review**: Reference for validating test quality
+
+---
+
+## Testing Philosophy
+
+### The Testing Trophy (Kent C. Dodds)
+
+Not a pyramid. Tests should be weighted toward integration.
+
+```
+ E2E (few)
+ ┌─────────┐
+ │ 🏆🏆 │ Integration (most)
+ └─────────┘
+ ┌───────────────────┐
+ │ 🏆🏆🏆🏆🏆🏆🏆🏆🏆 │
+ └───────────────────┘
+ ┌───────────┐
+ │ 🏆🏆🏆🏆 │ Unit (some)
+ └───────────┘
+ ┌─────┐
+ │ 🏆 │ Static (TypeScript, ESLint)
+ └─────┘
+```
+
+**Why integration > unit:**
+
+- Unit tests can pass while the app is broken
+- Integration tests verify things actually work together
+- Less mocking = more confidence
+- Refactoring doesn't break tests (testing behavior, not implementation)
+
+### Write Tests That Give Confidence
+
+```typescript
+// BAD - tests implementation details
+test("calls setCount when button clicked", () => {
+ const setCount = jest.fn();
+ render(<Counter setCount={setCount} />);
+ fireEvent.click(screen.getByRole("button"));
+ expect(setCount).toHaveBeenCalledWith(1); // Implementation detail!
+});
+
+// GOOD - tests behavior users care about
+test("increments count when clicked", () => {
+ render(<Counter />);
+ expect(screen.getByText("Count: 0")).toBeInTheDocument();
+ fireEvent.click(screen.getByRole("button", { name: /increment/i }));
+ expect(screen.getByText("Count: 1")).toBeInTheDocument();
+});
+```
+
+### The Arrange-Act-Assert Pattern
+
+```typescript
+test("adds item to cart", async () => {
+ // Arrange - set up test data and conditions
+ const user = userEvent.setup();
+ const product = { id: "1", name: "Widget", price: 9.99 };
+ render(<ProductCard product={product} />);
+
+ // Act - perform the action being tested
+ await user.click(screen.getByRole("button", { name: /add to cart/i }));
+
+ // Assert - verify the expected outcome
+ expect(screen.getByText("Added to cart")).toBeInTheDocument();
+ expect(screen.getByRole("button")).toHaveTextContent("In Cart");
+});
+```
+
+---
+
+## Unit vs Integration vs E2E
+
+### When to Use Each
+
+| Test Type | Speed | Confidence | Isolation | Use For |
+| ----------- | ------ | ---------- | --------- | --------------------------------- |
+| Unit | Fast | Low | High | Pure functions, utils, algorithms |
+| Integration | Medium | High | Medium | Features, user flows, API calls |
+| E2E | Slow | Highest | None | Critical paths, deployments |
+
+### Unit Tests
+
+**Use for:** Pure functions, utilities, algorithms, data transformations.
+
+```typescript
+// Good candidate for unit test - pure function
+function calculateDiscount(price: number, discountPercent: number): number {
+ if (discountPercent < 0 || discountPercent > 100) {
+ throw new Error("Invalid discount percentage");
+ }
+ return price * (1 - discountPercent / 100);
+}
+
+describe("calculateDiscount", () => {
+ it("applies percentage discount", () => {
+ expect(calculateDiscount(100, 20)).toBe(80);
+ expect(calculateDiscount(50, 10)).toBe(45);
+ });
+
+ it("handles edge cases", () => {
+ expect(calculateDiscount(100, 0)).toBe(100);
+ expect(calculateDiscount(100, 100)).toBe(0);
+ });
+
+ it("throws on invalid percentage", () => {
+ expect(() => calculateDiscount(100, -10)).toThrow();
+ expect(() => calculateDiscount(100, 150)).toThrow();
+ });
+});
+```
+
+### Integration Tests
+
+**Use for:** Features that involve multiple parts working together.
+
+```typescript
+// Tests the full feature: UI + state + API
+describe("User Registration", () => {
+ it("registers a new user successfully", async () => {
+ const user = userEvent.setup();
+
+ // Mock API at network level, not function level
+ server.use(
+ http.post("/api/users", () => {
+ return HttpResponse.json({ id: "123", email: "test@example.com" });
+ })
+ );
+
+ render(<RegistrationForm />);
+
+ // Interact like a real user
+ await user.type(screen.getByLabelText(/email/i), "test@example.com");
+ await user.type(screen.getByLabelText(/password/i), "secure123");
+ await user.click(screen.getByRole("button", { name: /sign up/i }));
+
+ // Assert on user-visible outcomes
+ await waitFor(() => {
+ expect(screen.getByText(/welcome/i)).toBeInTheDocument();
+ });
+ });
+
+ it("shows validation errors for invalid input", async () => {
+ const user = userEvent.setup();
+ render(<RegistrationForm />);
+
+ await user.type(screen.getByLabelText(/email/i), "invalid-email");
+ await user.click(screen.getByRole("button", { name: /sign up/i }));
+
+ expect(screen.getByText(/valid email/i)).toBeInTheDocument();
+ });
+});
+```
+
+### E2E Tests
+
+**Use for:** Critical user journeys that must not break.
+
+```typescript
+// Playwright E2E test
+test.describe("Checkout Flow", () => {
+ test("complete purchase as guest", async ({ page }) => {
+ // Navigate to product
+ await page.goto("/products/widget");
+
+ // Add to cart
+ await page.getByRole("button", { name: "Add to Cart" }).click();
+ await expect(page.getByText("Added to cart")).toBeVisible();
+
+ // Go to checkout
+ await page.getByRole("link", { name: "Cart" }).click();
+ await page.getByRole("button", { name: "Checkout" }).click();
+
+ // Fill payment (use test card)
+ await page.getByLabel("Card number").fill("4242424242424242");
+ await page.getByLabel("Expiry").fill("12/25");
+ await page.getByLabel("CVC").fill("123");
+
+ // Complete purchase
+ await page.getByRole("button", { name: "Pay" }).click();
+
+ // Verify success
+ await expect(page.getByText("Order confirmed")).toBeVisible();
+ });
+});
+```
+
+---
+
+## Mocking Strategies
+
+### Don't Mock What You Don't Own
+
+**Problem:** Mocking third-party libraries couples tests to implementation.
+
+```typescript
+// BAD - mocking axios directly
+jest.mock("axios");
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+mockedAxios.get.mockResolvedValue({ data: { user: "test" } });
+
+// If you switch to fetch, all tests break
+// If axios changes API, tests don't catch it
+
+// GOOD - mock at the network level with MSW
+import { http, HttpResponse } from "msw";
+import { setupServer } from "msw/node";
+
+const server = setupServer(
+ http.get("/api/user", () => {
+ return HttpResponse.json({ user: "test" });
+ }),
+);
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+// Now tests work regardless of HTTP library
+// And you catch actual network issues
+```
+
+### Dependency Injection for Testability
+
+```typescript
+// Hard to test - direct dependency
+class UserService {
+ async getUser(id: string) {
+ const response = await fetch(`/api/users/${id}`);
+ return response.json();
+ }
+}
+
+// Easy to test - injected dependency
+interface HttpClient {
+ get<T>(url: string): Promise<T>;
+}
+
+class UserService {
+ constructor(private http: HttpClient) {}
+
+ async getUser(id: string) {
+ return this.http.get<User>(`/api/users/${id}`);
+ }
+}
+
+// In tests
+const mockHttp: HttpClient = {
+ get: jest.fn().mockResolvedValue({ id: "1", name: "Test User" }),
+};
+const service = new UserService(mockHttp);
+```
+
+### Mock Only at Boundaries
+
+**Boundaries worth mocking:**
+
+- Network requests (use MSW)
+- Database (use test DB or in-memory)
+- File system (use memfs or tmp directories)
+- Time (use fake timers)
+- External services (Stripe, SendGrid, etc.)
+
+**Don't mock:**
+
+- Your own code (except when testing in isolation)
+- Language features
+- Internal module interactions
+
+```typescript
+// Mocking time
+describe("session expiry", () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ it("expires session after 30 minutes", () => {
+ const session = createSession();
+ expect(session.isExpired()).toBe(false);
+
+ jest.advanceTimersByTime(30 * 60 * 1000);
+ expect(session.isExpired()).toBe(true);
+ });
+});
+```
+
+---
+
+## Test Fixtures and Factories
+
+### Factory Functions
+
+**Problem:** Creating test data is repetitive and brittle.
+
+```typescript
+// BAD - inline data everywhere
+test("displays user profile", () => {
+ const user = {
+ id: "1",
+ email: "test@example.com",
+ name: "Test User",
+ avatar: "https://example.com/avatar.jpg",
+ role: "user",
+ createdAt: new Date(),
+ // ... 10 more required fields
+ };
+ render(<UserProfile user={user} />);
+});
+
+// GOOD - factory functions
+function createUser(overrides: Partial<User> = {}): User {
+ return {
+ id: "1",
+ email: "test@example.com",
+ name: "Test User",
+ avatar: "https://example.com/avatar.jpg",
+ role: "user",
+ createdAt: new Date("2024-01-01"),
+ ...overrides,
+ };
+}
+
+test("displays user profile", () => {
+ const user = createUser({ name: "Joel Hooks" });
+ render(<UserProfile user={user} />);
+ expect(screen.getByText("Joel Hooks")).toBeInTheDocument();
+});
+
+test("shows admin badge for admin users", () => {
+ const admin = createUser({ role: "admin" });
+ render(<UserProfile user={admin} />);
+ expect(screen.getByText("Admin")).toBeInTheDocument();
+});
+```
+
+### Builder Pattern for Complex Data
+
+```typescript
+class UserBuilder {
+ private user: User = {
+ id: "1",
+ email: "test@example.com",
+ name: "Test User",
+ role: "user",
+ permissions: [],
+ createdAt: new Date(),
+ };
+
+ withId(id: string) {
+ this.user.id = id;
+ return this;
+ }
+
+ withEmail(email: string) {
+ this.user.email = email;
+ return this;
+ }
+
+ asAdmin() {
+ this.user.role = "admin";
+ this.user.permissions = ["read", "write", "delete"];
+ return this;
+ }
+
+ build(): User {
+ return { ...this.user };
+ }
+}
+
+// Usage
+const user = new UserBuilder().withEmail("joel@egghead.io").asAdmin().build();
+```
+
+### Shared Fixtures
+
+```typescript
+// fixtures/users.ts
+export const fixtures = {
+ regularUser: createUser({ role: "user" }),
+ adminUser: createUser({ role: "admin", permissions: ["all"] }),
+ newUser: createUser({ createdAt: new Date(), isVerified: false }),
+ bannedUser: createUser({ status: "banned", bannedAt: new Date() }),
+};
+
+// In tests
+import { fixtures } from "@/test/fixtures/users";
+
+test("banned users cannot post", () => {
+ render(<PostForm user={fixtures.bannedUser} />);
+ expect(screen.getByRole("button", { name: /post/i })).toBeDisabled();
+});
+```
+
+---
+
+## Testing Async Code
+
+### Proper Async Handling
+
+```typescript
+// BAD - not waiting for async operations
+test("loads user data", () => {
+ render(<UserProfile userId="1" />);
+ expect(screen.getByText("Joel")).toBeInTheDocument(); // Fails - data not loaded yet!
+});
+
+// GOOD - wait for elements to appear
+test("loads user data", async () => {
+ render(<UserProfile userId="1" />);
+
+ // Wait for loading to finish
+ expect(await screen.findByText("Joel")).toBeInTheDocument();
+
+ // Or use waitFor for complex conditions
+ await waitFor(() => {
+ expect(screen.getByText("Joel")).toBeInTheDocument();
+ expect(screen.queryByText("Loading")).not.toBeInTheDocument();
+ });
+});
+```
+
+### Testing Loading States
+
+```typescript
+test("shows loading state then content", async () => {
+ render(<UserProfile userId="1" />);
+
+ // Initially shows loading
+ expect(screen.getByText("Loading...")).toBeInTheDocument();
+
+ // Eventually shows content
+ expect(await screen.findByText("Joel")).toBeInTheDocument();
+ expect(screen.queryByText("Loading...")).not.toBeInTheDocument();
+});
+```
+
+### Testing Error States
+
+```typescript
+test("shows error when fetch fails", async () => {
+ // Override handler to return error
+ server.use(
+ http.get("/api/users/:id", () => {
+ return new HttpResponse(null, { status: 500 });
+ })
+ );
+
+ render(<UserProfile userId="1" />);
+
+ expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+ expect(screen.getByRole("button", { name: /retry/i })).toBeInTheDocument();
+});
+```
+
+### Avoiding Flaky Async Tests
+
+```typescript
+// BAD - arbitrary timeouts
+await new Promise((r) => setTimeout(r, 1000));
+expect(screen.getByText("Done")).toBeInTheDocument();
+
+// BAD - too short waitFor timeout
+await waitFor(
+ () => {
+ expect(mockFn).toHaveBeenCalled();
+ },
+ { timeout: 100 },
+); // Might fail intermittently
+
+// GOOD - wait for specific conditions
+await waitFor(() => {
+ expect(screen.getByText("Done")).toBeInTheDocument();
+});
+
+// GOOD - use findBy (has built-in waiting)
+const element = await screen.findByText("Done");
+expect(element).toBeInTheDocument();
+
+// GOOD - wait for network requests to complete (MSW)
+await waitFor(() => {
+ expect(server.events.length).toBeGreaterThan(0);
+});
+```
+
+---
+
+## Testing React Components
+
+### Using Testing Library
+
+```typescript
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+describe("LoginForm", () => {
+ it("submits with valid credentials", async () => {
+ const user = userEvent.setup();
+ const handleSubmit = jest.fn();
+
+ render(<LoginForm onSubmit={handleSubmit} />);
+
+ await user.type(screen.getByLabelText(/email/i), "joel@example.com");
+ await user.type(screen.getByLabelText(/password/i), "password123");
+ await user.click(screen.getByRole("button", { name: /log in/i }));
+
+ expect(handleSubmit).toHaveBeenCalledWith({
+ email: "joel@example.com",
+ password: "password123",
+ });
+ });
+});
+```
+
+### Query Priority
+
+Use queries in this order (accessibility-first):
+
+```typescript
+// 1. Accessible to everyone
+screen.getByRole("button", { name: /submit/i });
+screen.getByLabelText(/email/i);
+screen.getByPlaceholderText(/search/i);
+screen.getByText(/welcome/i);
+screen.getByDisplayValue("current value");
+
+// 2. Semantic queries
+screen.getByAltText(/profile picture/i);
+screen.getByTitle(/close/i);
+
+// 3. Test IDs (last resort)
+screen.getByTestId("submit-button");
+```
+
+### Custom Render with Providers
+
+```typescript
+// test/utils.tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+function createTestQueryClient() {
+ return new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ mutations: { retry: false },
+ },
+ });
+}
+
+function AllProviders({ children }: { children: React.ReactNode }) {
+ const queryClient = createTestQueryClient();
+
+ return (
+ <QueryClientProvider client={queryClient}>
+ <ThemeProvider>
+ <AuthProvider>
+ {children}
+ </AuthProvider>
+ </ThemeProvider>
+ </QueryClientProvider>
+ );
+}
+
+export function renderWithProviders(ui: React.ReactElement) {
+ return render(ui, { wrapper: AllProviders });
+}
+
+// In tests
+import { renderWithProviders } from "@/test/utils";
+
+test("renders with all providers", () => {
+ renderWithProviders(<MyComponent />);
+});
+```
+
+### Testing Hooks
+
+```typescript
+import { renderHook, act } from "@testing-library/react";
+
+describe("useCounter", () => {
+ it("increments count", () => {
+ const { result } = renderHook(() => useCounter());
+
+ expect(result.current.count).toBe(0);
+
+ act(() => {
+ result.current.increment();
+ });
+
+ expect(result.current.count).toBe(1);
+ });
+
+ it("accepts initial value", () => {
+ const { result } = renderHook(() => useCounter(10));
+ expect(result.current.count).toBe(10);
+ });
+});
+```
+
+---
+
+## Snapshot Testing
+
+### When to Use
+
+**Good uses:**
+
+- Serialized output (JSON, HTML structure)
+- Regression prevention for stable UI
+- Generated code/config
+
+**Bad uses:**
+
+- Rapidly changing UI
+- Large component trees
+- Testing behavior (use assertions instead)
+
+### Effective Snapshot Tests
+
+```typescript
+// BAD - entire component snapshot (too big, too fragile)
+test("renders correctly", () => {
+ const { container } = render(<ComplexDashboard />);
+ expect(container).toMatchSnapshot();
+});
+
+// GOOD - focused snapshot on specific output
+test("generates correct CSS class names", () => {
+ const classes = generateClassNames({ variant: "primary", size: "large" });
+ expect(classes).toMatchInlineSnapshot(`"btn btn-primary btn-lg"`);
+});
+
+// GOOD - serialized data structures
+test("transforms API response correctly", () => {
+ const response = { id: "1", user_name: "joel", created_at: "2024-01-01" };
+ const transformed = transformUser(response);
+ expect(transformed).toMatchInlineSnapshot(`
+ {
+ "createdAt": "2024-01-01T00:00:00.000Z",
+ "id": "1",
+ "userName": "joel",
+ }
+ `);
+});
+```
+
+### Inline vs External Snapshots
+
+```typescript
+// Inline - for small, stable outputs
+expect(value).toMatchInlineSnapshot(`"expected"`);
+
+// External - for larger outputs (creates .snap file)
+expect(value).toMatchSnapshot();
+
+// Named snapshot - when multiple in one test
+expect(loading).toMatchSnapshot("loading state");
+expect(loaded).toMatchSnapshot("loaded state");
+```
+
+---
+
+## Coverage Strategies
+
+### What Coverage Tells You
+
+- **100% coverage**: Every line was executed (not that it's correct)
+- **Low coverage**: Untested code paths exist
+- **Coverage lies**: A test can hit all lines without testing behavior
+
+### Pragmatic Coverage Targets
+
+```javascript
+// jest.config.js
+module.exports = {
+ coverageThreshold: {
+ global: {
+ branches: 70,
+ functions: 70,
+ lines: 80,
+ statements: 80,
+ },
+ // Stricter for critical code
+ "./src/payment/**/*.ts": {
+ branches: 90,
+ functions: 90,
+ lines: 95,
+ },
+ // Looser for UI components
+ "./src/components/**/*.tsx": {
+ branches: 50,
+ functions: 50,
+ lines: 60,
+ },
+ },
+};
+```
+
+### Focus on Critical Paths
+
+Don't chase 100% coverage. Focus on:
+
+1. **Business logic** - calculations, validation, state machines
+2. **Edge cases** - error handling, empty states, boundaries
+3. **Integration points** - API calls, database operations
+4. **User flows** - checkout, authentication, onboarding
+
+```typescript
+// Worth testing thoroughly
+describe("calculateTax", () => {
+ it("handles different tax brackets");
+ it("rounds correctly");
+ it("handles zero income");
+ it("handles negative adjustments");
+ it("throws on invalid input");
+});
+
+// Not worth exhaustive testing
+describe("Footer", () => {
+ it("renders copyright year"); // One simple test is fine
+});
+```
+
+---
+
+## Common Pitfalls
+
+### Testing Implementation Details
+
+```typescript
+// BAD - testing internal state
+test("sets loading to true", () => {
+ const { result } = renderHook(() => useFetch("/api/data"));
+ expect(result.current.loading).toBe(true); // Implementation detail
+});
+
+// GOOD - testing observable behavior
+test("shows loading indicator while fetching", async () => {
+ render(<DataDisplay />);
+ expect(screen.getByRole("progressbar")).toBeInTheDocument();
+ await waitForElementToBeRemoved(() => screen.queryByRole("progressbar"));
+});
+```
+
+### Over-Mocking
+
+```typescript
+// BAD - mocking everything
+jest.mock("./utils");
+jest.mock("./api");
+jest.mock("./hooks");
+// What are you even testing at this point?
+
+// GOOD - mock only boundaries, test real code
+server.use(
+ http.get("/api/data", () => HttpResponse.json({ items: [] }))
+);
+render(<RealComponent />); // Uses real utils, hooks, etc.
+```
+
+### Brittle Selectors
+
+```typescript
+// BAD - implementation-dependent selectors
+screen.getByClassName("btn-primary");
+container.querySelector("div > span:first-child");
+screen.getByTestId("submit-btn"); // When there's a better option
+
+// GOOD - semantic, accessible selectors
+screen.getByRole("button", { name: /submit/i });
+screen.getByLabelText(/email address/i);
+screen.getByText(/welcome back/i);
+```
+
+### Not Testing Error Cases
+
+```typescript
+// BAD - only happy path
+test("creates user", async () => {
+ await createUser({ email: "test@example.com" });
+ expect(/* success case */);
+});
+
+// GOOD - test errors too
+test("handles duplicate email", async () => {
+ server.use(
+ http.post("/api/users", () => {
+ return HttpResponse.json(
+ { error: "Email already exists" },
+ { status: 409 }
+ );
+ })
+ );
+
+ render(<RegistrationForm />);
+ await user.type(screen.getByLabelText(/email/i), "existing@example.com");
+ await user.click(screen.getByRole("button", { name: /register/i }));
+
+ expect(await screen.findByText(/email already exists/i)).toBeInTheDocument();
+});
+```
+
+### Ignoring Act Warnings
+
+```typescript
+// BAD - ignoring the warning
+console.error = jest.fn(); // 🚩 Red flag
+
+// GOOD - fix the actual issue
+test("updates state", async () => {
+ render(<Counter />);
+
+ // Wrap state updates in act (or use userEvent which does it for you)
+ await userEvent.click(screen.getByRole("button"));
+
+ expect(screen.getByText("1")).toBeInTheDocument();
+});
+```
+
+---
+
+## Test Organization
+
+### File Structure
+
+```
+src/
+ components/
+ Button/
+ Button.tsx
+ Button.test.tsx # Co-located tests
+ features/
+ auth/
+ LoginForm.tsx
+ LoginForm.test.tsx
+ useAuth.ts
+ useAuth.test.ts
+ utils/
+ format.ts
+ format.test.ts
+test/
+ fixtures/ # Shared test data
+ users.ts
+ products.ts
+ mocks/ # MSW handlers, etc.
+ handlers.ts
+ server.ts
+ utils.tsx # Custom render, providers
+ setup.ts # Global test setup
+```
+
+### Describe Blocks
+
+```typescript
+describe("ShoppingCart", () => {
+ describe("when empty", () => {
+ it("shows empty message");
+ it("hides checkout button");
+ });
+
+ describe("with items", () => {
+ it("displays item count");
+ it("calculates total");
+ it("allows quantity changes");
+ });
+
+ describe("checkout", () => {
+ it("validates stock availability");
+ it("applies discount codes");
+ it("handles payment failure");
+ });
+});
+```
+
+### Naming Conventions
+
+```typescript
+// Describe the subject
+describe("calculateShipping", () => {});
+describe("LoginForm", () => {});
+describe("useAuth hook", () => {});
+
+// Test names should read like sentences
+it("returns free shipping for orders over $50");
+it("shows error message for invalid email");
+it("redirects to dashboard after login");
+
+// Group by behavior/state
+describe("when user is logged in", () => {});
+describe("with invalid input", () => {});
+describe("after timeout", () => {});
+```
+
+---
+
+## Adding New Patterns
+
+When you discover a new testing pattern:
+
+1. **Identify the problem**: What was hard to test?
+2. **Show the anti-pattern**: What doesn't work?
+3. **Demonstrate the solution**: Clear, minimal example
+4. **Note tradeoffs**: When to use/avoid
+
+```markdown
+### Pattern Name
+
+**Problem:** What testing challenge does this solve?
+
+\`\`\`typescript
+// BAD - why this approach fails
+// ...
+
+// GOOD - the pattern
+// ...
+\`\`\`
+
+**When to use / avoid:** Context for when this applies.
+```
diff --git a/knowledge/typescript-patterns.md b/knowledge/typescript-patterns.md
new file mode 100644
index 0000000..d4eefc8
--- /dev/null
+++ b/knowledge/typescript-patterns.md
@@ -0,0 +1,921 @@
+# TypeScript Patterns
+
+Advanced TypeScript patterns, type gymnastics, and gotchas. Searchable by concept.
+
+## How to Use This File
+
+1. **During development**: Search for patterns when writing complex types
+2. **Debugging type errors**: Check gotchas section
+3. **Code review**: Reference for validating type-level decisions
+4. **Learning**: Work through examples to level up type-fu
+
+---
+
+## Branded/Nominal Types
+
+### Problem: Primitive Type Confusion
+
+**Problem:** `userId` and `postId` are both strings, but mixing them is a bug.
+
+```typescript
+// BAD - compiles but is a runtime bug
+function getUser(userId: string) {
+ /* ... */
+}
+function getPost(postId: string) {
+ /* ... */
+}
+
+const userId = "user_123";
+const postId = "post_456";
+getUser(postId); // No error! Silent bug.
+```
+
+**Pattern:** Brand primitives to make them nominally distinct.
+
+```typescript
+// Branded type with unique symbol
+declare const brand: unique symbol;
+type Brand<T, B> = T & { [brand]: B };
+
+type UserId = Brand<string, "UserId">;
+type PostId = Brand<string, "PostId">;
+
+function getUser(userId: UserId) {
+ /* ... */
+}
+function getPost(postId: PostId) {
+ /* ... */
+}
+
+// Create branded values
+const userId = "user_123" as UserId;
+const postId = "post_456" as PostId;
+
+getUser(postId); // ERROR: Type 'PostId' is not assignable to type 'UserId'
+getUser(userId); // OK
+```
+
+### Branded Types with Validation
+
+```typescript
+type Email = Brand<string, "Email">;
+type PositiveInt = Brand<number, "PositiveInt">;
+
+// Smart constructor - validates then brands
+function toEmail(input: string): Email | null {
+ const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ return emailRegex.test(input) ? (input as Email) : null;
+}
+
+function toPositiveInt(input: number): PositiveInt | null {
+ return Number.isInteger(input) && input > 0 ? (input as PositiveInt) : null;
+}
+
+// Usage - parse at the boundary, trust the type inside
+function sendEmail(to: Email, subject: string) {
+ // `to` is guaranteed to be valid email
+}
+
+const email = toEmail(userInput);
+if (email) {
+ sendEmail(email, "Hello"); // Safe
+}
+```
+
+---
+
+## Type Predicates and Guards
+
+### Basic Type Predicates
+
+**Problem:** TypeScript doesn't narrow types in custom functions.
+
+```typescript
+// BAD - TypeScript doesn't know what's inside the if
+function isString(value: unknown) {
+ return typeof value === "string";
+}
+
+const x: unknown = "hello";
+if (isString(x)) {
+ x.toUpperCase(); // ERROR: Object is of type 'unknown'
+}
+
+// GOOD - Type predicate narrows the type
+function isString(value: unknown): value is string {
+ return typeof value === "string";
+}
+
+if (isString(x)) {
+ x.toUpperCase(); // OK - x is narrowed to string
+}
+```
+
+### Object Type Guards
+
+```typescript
+interface User {
+ id: string;
+ email: string;
+ name: string;
+}
+
+interface GuestUser {
+ sessionId: string;
+}
+
+type AnyUser = User | GuestUser;
+
+// Type guard using discriminant property
+function isRegisteredUser(user: AnyUser): user is User {
+ return "id" in user && "email" in user;
+}
+
+function sendNotification(user: AnyUser) {
+ if (isRegisteredUser(user)) {
+ // user is User here
+ sendEmail(user.email, "Hello!");
+ } else {
+ // user is GuestUser here
+ console.log(`Guest session: ${user.sessionId}`);
+ }
+}
+```
+
+### Assertion Functions
+
+```typescript
+// Assert something is true, throw if not
+function assertNonNull<T>(value: T): asserts value is NonNullable<T> {
+ if (value === null || value === undefined) {
+ throw new Error("Value is null or undefined");
+ }
+}
+
+function assertIsUser(value: unknown): asserts value is User {
+ if (!value || typeof value !== "object") {
+ throw new Error("Not a user object");
+ }
+ if (!("id" in value) || !("email" in value)) {
+ throw new Error("Missing required user fields");
+ }
+}
+
+// Usage - throws or narrows
+const data: unknown = await fetchData();
+assertIsUser(data);
+data.email; // OK - TypeScript knows it's User now
+```
+
+---
+
+## Discriminated Unions
+
+### The Pattern
+
+**Problem:** Need to handle multiple related but distinct cases safely.
+
+**Pattern:** Union of types with a common literal discriminant.
+
+```typescript
+// Each type has a literal `type` property
+type LoadingState = { type: "loading" };
+type ErrorState = { type: "error"; error: Error };
+type SuccessState<T> = { type: "success"; data: T };
+
+type AsyncState<T> = LoadingState | ErrorState | SuccessState<T>;
+
+function render(state: AsyncState<User>) {
+ switch (state.type) {
+ case "loading":
+ return <Spinner />;
+ case "error":
+ return <ErrorMessage error={state.error} />;
+ case "success":
+ return <UserProfile user={state.data} />;
+ }
+}
+```
+
+### Exhaustiveness Checking
+
+```typescript
+// Ensure all cases are handled
+function assertNever(value: never): never {
+ throw new Error(`Unhandled case: ${JSON.stringify(value)}`);
+}
+
+type Shape =
+ | { kind: "circle"; radius: number }
+ | { kind: "square"; side: number }
+ | { kind: "rectangle"; width: number; height: number };
+
+function area(shape: Shape): number {
+ switch (shape.kind) {
+ case "circle":
+ return Math.PI * shape.radius ** 2;
+ case "square":
+ return shape.side ** 2;
+ case "rectangle":
+ return shape.width * shape.height;
+ default:
+ // If you add a new shape and forget to handle it,
+ // TypeScript will error here
+ return assertNever(shape);
+ }
+}
+```
+
+### Discriminated Unions vs Optional Properties
+
+```typescript
+// BAD - Optional properties lead to impossible states
+interface User {
+ id: string;
+ email?: string; // Can be guest
+ guestSessionId?: string; // Or registered
+ // What if both are set? Or neither?
+}
+
+// GOOD - Impossible states are impossible
+type User =
+ | { type: "registered"; id: string; email: string }
+ | { type: "guest"; sessionId: string };
+
+// Now TypeScript enforces that you can't have email on guest
+// or sessionId on registered
+```
+
+---
+
+## Template Literal Types
+
+### Basic Template Literals
+
+```typescript
+// String literal unions
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+// Template literal from union
+type Endpoint = `/${string}`;
+type ApiRoute = `${HttpMethod} ${Endpoint}`;
+// "GET /users" | "POST /users" | etc.
+
+// Event names
+type EventName = "click" | "focus" | "blur";
+type EventHandler = `on${Capitalize<EventName>}`;
+// "onClick" | "onFocus" | "onBlur"
+```
+
+### Dynamic Key Patterns
+
+```typescript
+// CSS properties
+type CSSProperty = "margin" | "padding";
+type CSSDirection = "Top" | "Right" | "Bottom" | "Left";
+type CSSSpacing = `${CSSProperty}${CSSDirection}`;
+// "marginTop" | "marginRight" | ... | "paddingLeft"
+
+// Build objects from patterns
+type SpacingProps = {
+ [K in CSSSpacing]?: number;
+};
+
+const spacing: SpacingProps = {
+ marginTop: 10,
+ paddingLeft: 20,
+};
+```
+
+### String Manipulation Types
+
+```typescript
+// Built-in string manipulation
+type Greeting = "hello world";
+type Upper = Uppercase<Greeting>; // "HELLO WORLD"
+type Lower = Lowercase<Greeting>; // "hello world"
+type Cap = Capitalize<Greeting>; // "Hello world"
+type Uncap = Uncapitalize<"Hello">; // "hello"
+
+// Extract parts of template literals
+type ExtractRouteParams<T extends string> =
+ T extends `${string}:${infer Param}/${infer Rest}`
+ ? Param | ExtractRouteParams<`/${Rest}`>
+ : T extends `${string}:${infer Param}`
+ ? Param
+ : never;
+
+type Params = ExtractRouteParams<"/users/:userId/posts/:postId">;
+// "userId" | "postId"
+```
+
+---
+
+## Conditional Types
+
+### Basic Conditionals
+
+```typescript
+// T extends U ? X : Y
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<"hello">; // true
+type B = IsString<42>; // false
+type C = IsString<string>; // true
+
+// Extract array element type
+type ElementOf<T> = T extends (infer E)[] ? E : never;
+
+type D = ElementOf<string[]>; // string
+type E = ElementOf<number[]>; // number
+```
+
+### Distributive Conditional Types
+
+**Gotcha:** Conditionals distribute over unions.
+
+```typescript
+type ToArray<T> = T extends unknown ? T[] : never;
+
+// Distributes: "a" | "b" becomes "a"[] | "b"[]
+type Distributed = ToArray<"a" | "b">; // "a"[] | "b"[]
+
+// Prevent distribution with tuple wrapper
+type ToArrayNonDist<T> = [T] extends [unknown] ? T[] : never;
+type NonDistributed = ToArrayNonDist<"a" | "b">; // ("a" | "b")[]
+```
+
+### infer Keyword
+
+```typescript
+// Extract types from structures
+type GetReturnType<T> = T extends (...args: unknown[]) => infer R ? R : never;
+
+type FnReturn = GetReturnType<() => string>; // string
+
+// Extract Promise inner type
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+
+type Resolved = Awaited<Promise<Promise<string>>>; // string
+
+// Extract function parameters
+type Parameters<T> = T extends (...args: infer P) => unknown ? P : never;
+
+type Params = Parameters<(a: string, b: number) => void>; // [string, number]
+```
+
+---
+
+## Mapped Types
+
+### Basic Mapped Types
+
+```typescript
+// Transform all properties
+type Readonly<T> = {
+ readonly [K in keyof T]: T[K];
+};
+
+type Optional<T> = {
+ [K in keyof T]?: T[K];
+};
+
+type Nullable<T> = {
+ [K in keyof T]: T[K] | null;
+};
+
+// Usage
+interface User {
+ id: string;
+ name: string;
+}
+
+type ReadonlyUser = Readonly<User>;
+// { readonly id: string; readonly name: string }
+```
+
+### Key Remapping
+
+```typescript
+// Add prefix to all keys
+type Prefixed<T, P extends string> = {
+ [K in keyof T as `${P}${string & K}`]: T[K];
+};
+
+type User = { id: string; name: string };
+type ApiUser = Prefixed<User, "user_">;
+// { user_id: string; user_name: string }
+
+// Filter keys
+type OnlyStrings<T> = {
+ [K in keyof T as T[K] extends string ? K : never]: T[K];
+};
+
+type Mixed = { id: number; name: string; email: string };
+type StringsOnly = OnlyStrings<Mixed>;
+// { name: string; email: string }
+```
+
+### Practical Examples
+
+```typescript
+// Make all methods async
+type Async<T> = {
+ [K in keyof T]: T[K] extends (...args: infer A) => infer R
+ ? (...args: A) => Promise<R>
+ : T[K];
+};
+
+interface UserService {
+ getUser(id: string): User;
+ deleteUser(id: string): void;
+}
+
+type AsyncUserService = Async<UserService>;
+// {
+// getUser(id: string): Promise<User>;
+// deleteUser(id: string): Promise<void>;
+// }
+
+// Create getters
+type Getters<T> = {
+ [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+type UserGetters = Getters<User>;
+// { getId: () => string; getName: () => string }
+```
+
+---
+
+## const Assertions
+
+### Literal Inference
+
+**Problem:** TypeScript widens literals to general types.
+
+```typescript
+// BAD - widened to string[]
+const routes = ["home", "about", "contact"];
+// Type: string[]
+
+// GOOD - preserves literal types
+const routes = ["home", "about", "contact"] as const;
+// Type: readonly ["home", "about", "contact"]
+
+// Extract union from const array
+type Route = (typeof routes)[number];
+// "home" | "about" | "contact"
+```
+
+### Object Literals
+
+```typescript
+// BAD - widened
+const config = {
+ env: "production",
+ port: 3000,
+};
+// Type: { env: string; port: number }
+
+// GOOD - exact literal types
+const config = {
+ env: "production",
+ port: 3000,
+} as const;
+// Type: { readonly env: "production"; readonly port: 3000 }
+
+// Useful for discriminated unions
+const actions = {
+ increment: { type: "INCREMENT" },
+ decrement: { type: "DECREMENT" },
+ reset: { type: "RESET", payload: 0 },
+} as const;
+
+type Action = (typeof actions)[keyof typeof actions];
+// { readonly type: "INCREMENT" } | { readonly type: "DECREMENT" } | ...
+```
+
+### Function Arguments
+
+```typescript
+function route<T extends readonly string[]>(paths: T): T {
+ return paths;
+}
+
+// Without as const - loses literal types
+const bad = route(["a", "b"]); // string[]
+
+// With as const - preserves literals
+const good = route(["a", "b"] as const); // readonly ["a", "b"]
+```
+
+---
+
+## satisfies Operator
+
+### The Problem satisfies Solves
+
+**Problem:** Type annotations lose inference, but no annotation loses validation.
+
+```typescript
+// Annotation - validates but loses specific type
+const colors: Record<string, string> = {
+ red: "#ff0000",
+ green: "#00ff00",
+};
+colors.red; // string (lost the literal)
+colors.purple; // string (typo not caught)
+
+// No annotation - keeps type but no validation
+const colors = {
+ red: "#ff0000",
+ green: "#00ff00",
+};
+colors.red; // "#ff0000" (good!)
+colors.purple; // Error! (good!)
+// But: no guarantee it matches Record<string, string>
+
+// satisfies - validates AND preserves inference
+const colors = {
+ red: "#ff0000",
+ green: "#00ff00",
+} satisfies Record<string, string>;
+
+colors.red; // "#ff0000" (literal preserved!)
+colors.purple; // Error! (typo caught)
+```
+
+### Use Cases
+
+```typescript
+// Validate config while keeping literal types
+type Config = {
+ apiUrl: string;
+ features: string[];
+ debug: boolean;
+};
+
+const config = {
+ apiUrl: "https://api.example.com",
+ features: ["auth", "payments"],
+ debug: false,
+} satisfies Config;
+
+config.apiUrl; // "https://api.example.com" (literal!)
+config.features; // ["auth", "payments"] (tuple-like!)
+
+// Validate route config
+type RouteConfig = {
+ [path: string]: {
+ component: React.ComponentType;
+ auth?: boolean;
+ };
+};
+
+const routes = {
+ "/home": { component: Home },
+ "/dashboard": { component: Dashboard, auth: true },
+} satisfies RouteConfig;
+
+// routes["/home"] is known to exist
+// routes["/typo"] would error at this definition
+```
+
+---
+
+## Common Gotchas
+
+### any vs unknown
+
+```typescript
+// any - disables type checking (avoid!)
+const dangerous: any = "hello";
+dangerous.foo.bar.baz(); // No error - runtime crash
+
+// unknown - type-safe "any"
+const safe: unknown = "hello";
+safe.toUpperCase(); // Error! Must narrow first
+
+if (typeof safe === "string") {
+ safe.toUpperCase(); // OK after narrowing
+}
+
+// Use unknown for:
+// - User input
+// - API responses before validation
+// - Error catch blocks (catch (e: unknown))
+```
+
+### type vs interface
+
+```typescript
+// Interface - extendable, declaration merging
+interface User {
+ id: string;
+}
+interface User {
+ name: string;
+}
+// Merged: { id: string; name: string }
+
+// Type - final, more powerful
+type User = {
+ id: string;
+};
+// Cannot add more properties via declaration
+
+// Type can do things interface can't:
+type StringOrNumber = string | number; // Unions
+type Pair<T> = [T, T]; // Tuples
+type Handler = () => void; // Function types
+
+// Rule of thumb:
+// - Interface for objects you want extendable
+// - Type for everything else
+// - Be consistent in your codebase
+```
+
+### Excess Property Checking
+
+```typescript
+interface User {
+ id: string;
+ name: string;
+}
+
+// Direct assignment - excess property check
+const user: User = {
+ id: "1",
+ name: "Joel",
+ email: "joel@example.com", // Error! Excess property
+};
+
+// Via intermediate variable - no check!
+const obj = { id: "1", name: "Joel", email: "joel@example.com" };
+const user: User = obj; // No error!
+
+// This is why:
+// - Use satisfies for literal validation
+// - Or use strict type assertions
+```
+
+### Index Signatures vs Record
+
+```typescript
+// Index signature
+interface StringMap {
+ [key: string]: string;
+}
+
+// Record (utility type)
+type StringMap = Record<string, string>;
+
+// They're equivalent, but Record is:
+// - More concise
+// - Can constrain keys
+type HttpHeaders = Record<"content-type" | "authorization", string>;
+
+// Index signature quirk: allows any string key access
+const map: StringMap = { foo: "bar" };
+map.anything; // string (no error, but might be undefined!)
+
+// Better: use noUncheckedIndexedAccess in tsconfig
+// Then: map.anything is string | undefined
+```
+
+### Function Overloads
+
+```typescript
+// Overload signatures (what callers see)
+function parse(input: string): object;
+function parse(
+ input: string,
+ reviver: (k: string, v: unknown) => unknown,
+): object;
+
+// Implementation signature (must be compatible with all overloads)
+function parse(
+ input: string,
+ reviver?: (k: string, v: unknown) => unknown,
+): object {
+ return reviver ? JSON.parse(input, reviver) : JSON.parse(input);
+}
+
+// Gotcha: Implementation signature is not callable
+parse("{}"); // Uses first overload
+parse("{}", (k, v) => v); // Uses second overload
+```
+
+### Readonly vs const
+
+```typescript
+// const - compile-time only, reference is constant
+const arr = [1, 2, 3];
+arr.push(4); // Allowed! Array is mutable
+arr = []; // Error! Can't reassign const
+
+// Readonly - type-level immutability
+const arr: readonly number[] = [1, 2, 3];
+arr.push(4); // Error! Can't mutate
+arr[0] = 5; // Error! Can't mutate
+
+// ReadonlyArray vs readonly T[]
+type A = ReadonlyArray<number>; // Same as
+type B = readonly number[]; // This
+
+// Deep readonly
+type DeepReadonly<T> = {
+ readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
+```
+
+---
+
+## Utility Types Reference
+
+### Built-in Utilities
+
+```typescript
+// Partial - all properties optional
+type Partial<T> = { [K in keyof T]?: T[K] };
+
+// Required - all properties required
+type Required<T> = { [K in keyof T]-?: T[K] };
+
+// Readonly - all properties readonly
+type Readonly<T> = { readonly [K in keyof T]: T[K] };
+
+// Pick - select specific properties
+type Pick<T, K extends keyof T> = { [P in K]: T[P] };
+
+// Omit - exclude specific properties
+type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+// Record - object with specific key/value types
+type Record<K extends keyof any, T> = { [P in K]: T };
+
+// Exclude - remove types from union
+type Exclude<T, U> = T extends U ? never : T;
+
+// Extract - keep only matching types from union
+type Extract<T, U> = T extends U ? T : never;
+
+// NonNullable - remove null and undefined
+type NonNullable<T> = T extends null | undefined ? never : T;
+
+// ReturnType - get function return type
+type ReturnType<T> = T extends (...args: any) => infer R ? R : never;
+
+// Parameters - get function parameter types
+type Parameters<T> = T extends (...args: infer P) => any ? P : never;
+```
+
+### Custom Utility Types
+
+```typescript
+// Deep Partial
+type DeepPartial<T> = {
+ [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+// Make specific keys required
+type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+// Make specific keys optional
+type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// Get keys where value is of type V
+type KeysOfType<T, V> = {
+ [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+
+// Mutable - remove readonly
+type Mutable<T> = {
+ -readonly [K in keyof T]: T[K];
+};
+```
+
+---
+
+## Real-World Patterns
+
+### API Response Types
+
+```typescript
+// Generic API response wrapper
+type ApiResponse<T> =
+ | { success: true; data: T }
+ | { success: false; error: { code: string; message: string } };
+
+// Paginated response
+type Paginated<T> = {
+ items: T[];
+ total: number;
+ page: number;
+ pageSize: number;
+ hasMore: boolean;
+};
+
+// Usage
+async function fetchUsers(): Promise<ApiResponse<Paginated<User>>> {
+ const response = await fetch("/api/users");
+ return response.json();
+}
+
+const result = await fetchUsers();
+if (result.success) {
+ result.data.items; // User[]
+} else {
+ result.error.message; // string
+}
+```
+
+### Event Emitter Types
+
+```typescript
+type EventMap = {
+ userLogin: { userId: string; timestamp: Date };
+ userLogout: { userId: string };
+ error: { code: number; message: string };
+};
+
+class TypedEventEmitter<T extends Record<string, unknown>> {
+ private listeners = new Map<keyof T, Set<Function>>();
+
+ on<K extends keyof T>(event: K, handler: (payload: T[K]) => void) {
+ if (!this.listeners.has(event)) {
+ this.listeners.set(event, new Set());
+ }
+ this.listeners.get(event)!.add(handler);
+ }
+
+ emit<K extends keyof T>(event: K, payload: T[K]) {
+ this.listeners.get(event)?.forEach((handler) => handler(payload));
+ }
+}
+
+const emitter = new TypedEventEmitter<EventMap>();
+emitter.on("userLogin", ({ userId, timestamp }) => {
+ // userId: string, timestamp: Date - fully typed!
+});
+emitter.emit("userLogin", { userId: "123", timestamp: new Date() });
+```
+
+### Builder Pattern
+
+```typescript
+class QueryBuilder<T extends object = {}> {
+ private query: T = {} as T;
+
+ select<K extends string>(field: K): QueryBuilder<T & Record<K, true>> {
+ return this as unknown as QueryBuilder<T & Record<K, true>>;
+ }
+
+ where<K extends string, V>(
+ field: K,
+ value: V,
+ ): QueryBuilder<T & { where: Record<K, V> }> {
+ return this as unknown as QueryBuilder<T & { where: Record<K, V> }>;
+ }
+
+ build(): T {
+ return this.query;
+ }
+}
+
+const query = new QueryBuilder()
+ .select("id")
+ .select("name")
+ .where("status", "active")
+ .build();
+// Type: { id: true; name: true; where: { status: "active" } }
+```
+
+---
+
+## Adding New Patterns
+
+When you discover a new pattern:
+
+1. **Identify the problem**: What type-level challenge does it solve?
+2. **Show the anti-pattern**: What's the naive/wrong approach?
+3. **Demonstrate the solution**: Clear, minimal code
+4. **Note edge cases**: When it doesn't work or has gotchas
+
+```markdown
+### Pattern Name
+
+**Problem:** What challenge does this solve?
+
+\`\`\`typescript
+// BAD - why this doesn't work
+const bad = ...
+
+// GOOD - the pattern
+const good = ...
+\`\`\`
+
+**When to use / avoid:** Context for application.
+```
diff --git a/opencode.jsonc b/opencode.jsonc
index a559316..f3a5405 100644
--- a/opencode.jsonc
+++ b/opencode.jsonc
@@ -41,6 +41,8 @@
"external_directory": "allow",
// Only deny the truly catastrophic - everything else just runs
"bash": {
+ "git push": "allow",
+ "git push *": "allow",
"sudo *": "deny",
"rm -rf /": "deny",
"rm -rf /*": "deny",
@@ -78,6 +80,12 @@
"snyk": {
"type": "local",
"command": ["npx", "-y", "snyk@latest", "mcp", "-t", "stdio"]
+ },
+ // Kernel - cloud browser automation, Playwright execution, app deployment
+ // OAuth auth - run `opencode mcp auth kernel` to authenticate
+ "kernel": {
+ "type": "remote",
+ "url": "https://mcp.onkernel.com/mcp"
}
},
@@ -114,6 +122,45 @@
"*": "deny"
}
}
+ },
+ // Security agent - read-only vulnerability scanning with Snyk
+ "security": {
+ "model": "anthropic/claude-sonnet-4-5",
+ "temperature": 0.1, // Low temp for deterministic security analysis
+ "tools": {
+ "write": false,
+ "edit": false,
+ "patch": false
+ },
+ "description": "Security auditor - scans for vulnerabilities using Snyk tools (SCA, SAST, IaC, container). Read-only, reports findings without modification."
+ },
+ // Test writer agent - generates comprehensive test suites
+ "test-writer": {
+ "model": "anthropic/claude-sonnet-4-5",
+ "temperature": 0.2, // Slight creativity for test case generation
+ "permission": {
+ "write": {
+ "**/*.test.ts": "allow",
+ "**/*.spec.ts": "allow",
+ "**/*.test.tsx": "allow",
+ "**/*.spec.tsx": "allow",
+ "*": "deny"
+ }
+ },
+ "description": "Test specialist - generates comprehensive unit, integration, and e2e tests. Can only write to test files."
+ },
+ // Docs agent - documentation writer (cheaper model)
+ "docs": {
+ "model": "anthropic/claude-haiku-4-5", // Haiku for cost-effective docs
+ "temperature": 0.3, // More creativity for readable documentation
+ "permission": {
+ "write": {
+ "**/*.md": "allow",
+ "**/*.mdx": "allow",
+ "*": "deny"
+ }
+ },
+ "description": "Documentation writer - generates and updates markdown docs, READMEs, and guides. Can only write to .md/.mdx files."
}
}
}
diff --git a/package.json b/package.json
index 7adec44..9bb6b52 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,10 @@
{
"dependencies": {
- "@opencode-ai/plugin": "1.0.134"
+ "@opencode-ai/plugin": "0.0.0-dev-202512281622"
+ },
+ "devDependencies": {
+ "@types/node": "^20.19.26",
+ "bun-types": "^1.3.4",
+ "typescript": "^5.9.3"
}
-}
\ No newline at end of file
+}
diff --git a/plugin.bak/swarm.js b/plugin.bak/swarm.js
deleted file mode 120000
index eb2f3d8..0000000
--- a/plugin.bak/swarm.js
+++ /dev/null
@@ -1 +0,0 @@
-/Users/joel/Code/joelhooks/opencode-swarm-plugin/dist/index.js
\ No newline at end of file
diff --git a/plugin/swarm-cli.ts.bak b/plugin/swarm-cli.ts.bak
new file mode 100644
index 0000000..e9bcf16
--- /dev/null
+++ b/plugin/swarm-cli.ts.bak
@@ -0,0 +1,842 @@
+/**
+ * OpenCode Swarm Plugin Wrapper
+ *
+ * This is a thin wrapper that shells out to the `swarm` CLI for all tool execution.
+ * Generated by: swarm setup
+ *
+ * The plugin only depends on @opencode-ai/plugin (provided by OpenCode).
+ * All tool logic lives in the npm package - this just bridges to it.
+ *
+ * Environment variables:
+ * - OPENCODE_SESSION_ID: Passed to CLI for session state persistence
+ * - OPENCODE_MESSAGE_ID: Passed to CLI for context
+ * - OPENCODE_AGENT: Passed to CLI for context
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import { spawn } from "child_process";
+
+const SWARM_CLI = "swarm";
+
+// =============================================================================
+// CLI Execution Helper
+// =============================================================================
+
+/**
+ * Execute a swarm tool via CLI
+ *
+ * Spawns `swarm tool <name> --json '<args>'` and returns the result.
+ * Passes session context via environment variables.
+ */
+async function execTool(
+ name: string,
+ args: Record<string, unknown>,
+ ctx: { sessionID: string; messageID: string; agent: string },
+): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const hasArgs = Object.keys(args).length > 0;
+ const cliArgs = hasArgs
+ ? ["tool", name, "--json", JSON.stringify(args)]
+ : ["tool", name];
+
+ const proc = spawn(SWARM_CLI, cliArgs, {
+ stdio: ["ignore", "pipe", "pipe"],
+ env: {
+ ...process.env,
+ OPENCODE_SESSION_ID: ctx.sessionID,
+ OPENCODE_MESSAGE_ID: ctx.messageID,
+ OPENCODE_AGENT: ctx.agent,
+ },
+ });
+
+ let stdout = "";
+ let stderr = "";
+
+ proc.stdout.on("data", (data) => {
+ stdout += data;
+ });
+ proc.stderr.on("data", (data) => {
+ stderr += data;
+ });
+
+ proc.on("close", (code) => {
+ if (code === 0) {
+ // Success - return the JSON output
+ try {
+ const result = JSON.parse(stdout);
+ if (result.success && result.data !== undefined) {
+ // Unwrap the data for cleaner tool output
+ resolve(
+ typeof result.data === "string"
+ ? result.data
+ : JSON.stringify(result.data, null, 2),
+ );
+ } else if (!result.success && result.error) {
+ // Tool returned an error in JSON format
+ reject(new Error(result.error.message || "Tool execution failed"));
+ } else {
+ resolve(stdout);
+ }
+ } catch {
+ resolve(stdout);
+ }
+ } else if (code === 2) {
+ reject(new Error(`Unknown tool: ${name}`));
+ } else if (code === 3) {
+ reject(new Error(`Invalid JSON args: ${stderr}`));
+ } else {
+ // Tool returned error
+ try {
+ const result = JSON.parse(stdout);
+ if (!result.success && result.error) {
+ reject(
+ new Error(
+ result.error.message || `Tool failed with code ${code}`,
+ ),
+ );
+ } else {
+ reject(
+ new Error(stderr || stdout || `Tool failed with code ${code}`),
+ );
+ }
+ } catch {
+ reject(
+ new Error(stderr || stdout || `Tool failed with code ${code}`),
+ );
+ }
+ }
+ });
+
+ proc.on("error", (err) => {
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+ reject(
+ new Error(
+ `swarm CLI not found. Install with: npm install -g opencode-swarm-plugin`,
+ ),
+ );
+ } else {
+ reject(err);
+ }
+ });
+ });
+}
+
+// =============================================================================
+// Beads Tools
+// =============================================================================
+
+const beads_create = tool({
+ description: "Create a new bead with type-safe validation",
+ args: {
+ title: tool.schema.string().describe("Bead title"),
+ type: tool.schema
+ .enum(["bug", "feature", "task", "epic", "chore"])
+ .optional()
+ .describe("Issue type (default: task)"),
+ priority: tool.schema
+ .number()
+ .min(0)
+ .max(3)
+ .optional()
+ .describe("Priority 0-3 (default: 2)"),
+ description: tool.schema.string().optional().describe("Bead description"),
+ parent_id: tool.schema
+ .string()
+ .optional()
+ .describe("Parent bead ID for epic children"),
+ },
+ execute: (args, ctx) => execTool("beads_create", args, ctx),
+});
+
+const beads_create_epic = tool({
+ description: "Create epic with subtasks in one atomic operation",
+ args: {
+ epic_title: tool.schema.string().describe("Epic title"),
+ epic_description: tool.schema
+ .string()
+ .optional()
+ .describe("Epic description"),
+ subtasks: tool.schema
+ .array(
+ tool.schema.object({
+ title: tool.schema.string(),
+ priority: tool.schema.number().min(0).max(3).optional(),
+ files: tool.schema.array(tool.schema.string()).optional(),
+ }),
+ )
+ .describe("Subtasks to create under the epic"),
+ },
+ execute: (args, ctx) => execTool("beads_create_epic", args, ctx),
+});
+
+const beads_query = tool({
+ description: "Query beads with filters (replaces bd list, bd ready, bd wip)",
+ args: {
+ status: tool.schema
+ .enum(["open", "in_progress", "blocked", "closed"])
+ .optional()
+ .describe("Filter by status"),
+ type: tool.schema
+ .enum(["bug", "feature", "task", "epic", "chore"])
+ .optional()
+ .describe("Filter by type"),
+ ready: tool.schema
+ .boolean()
+ .optional()
+ .describe("Only show unblocked beads"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 20)"),
+ },
+ execute: (args, ctx) => execTool("beads_query", args, ctx),
+});
+
+const beads_update = tool({
+ description: "Update bead status/description",
+ args: {
+ id: tool.schema.string().describe("Bead ID"),
+ status: tool.schema
+ .enum(["open", "in_progress", "blocked", "closed"])
+ .optional()
+ .describe("New status"),
+ description: tool.schema.string().optional().describe("New description"),
+ priority: tool.schema
+ .number()
+ .min(0)
+ .max(3)
+ .optional()
+ .describe("New priority"),
+ },
+ execute: (args, ctx) => execTool("beads_update", args, ctx),
+});
+
+const beads_close = tool({
+ description: "Close a bead with reason",
+ args: {
+ id: tool.schema.string().describe("Bead ID"),
+ reason: tool.schema.string().describe("Completion reason"),
+ },
+ execute: (args, ctx) => execTool("beads_close", args, ctx),
+});
+
+const beads_start = tool({
+ description: "Mark a bead as in-progress",
+ args: {
+ id: tool.schema.string().describe("Bead ID"),
+ },
+ execute: (args, ctx) => execTool("beads_start", args, ctx),
+});
+
+const beads_ready = tool({
+ description: "Get the next ready bead (unblocked, highest priority)",
+ args: {},
+ execute: (args, ctx) => execTool("beads_ready", args, ctx),
+});
+
+const beads_sync = tool({
+ description: "Sync beads to git and push (MANDATORY at session end)",
+ args: {
+ auto_pull: tool.schema.boolean().optional().describe("Pull before sync"),
+ },
+ execute: (args, ctx) => execTool("beads_sync", args, ctx),
+});
+
+const beads_link_thread = tool({
+ description: "Add metadata linking bead to Agent Mail thread",
+ args: {
+ bead_id: tool.schema.string().describe("Bead ID"),
+ thread_id: tool.schema.string().describe("Agent Mail thread ID"),
+ },
+ execute: (args, ctx) => execTool("beads_link_thread", args, ctx),
+});
+
+// =============================================================================
+// Agent Mail Tools
+// =============================================================================
+
+const agentmail_init = tool({
+ description: "Initialize Agent Mail session",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to the project"),
+ agent_name: tool.schema.string().optional().describe("Custom agent name"),
+ task_description: tool.schema
+ .string()
+ .optional()
+ .describe("Task description"),
+ },
+ execute: (args, ctx) => execTool("agentmail_init", args, ctx),
+});
+
+const agentmail_send = tool({
+ description: "Send message to other agents",
+ args: {
+ to: tool.schema
+ .array(tool.schema.string())
+ .describe("Recipient agent names"),
+ subject: tool.schema.string().describe("Message subject"),
+ body: tool.schema.string().describe("Message body"),
+ thread_id: tool.schema
+ .string()
+ .optional()
+ .describe("Thread ID for grouping"),
+ importance: tool.schema
+ .enum(["low", "normal", "high", "urgent"])
+ .optional()
+ .describe("Message importance"),
+ ack_required: tool.schema
+ .boolean()
+ .optional()
+ .describe("Require acknowledgment"),
+ },
+ execute: (args, ctx) => execTool("agentmail_send", args, ctx),
+});
+
+const agentmail_inbox = tool({
+ description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, limit 5)",
+ args: {
+ limit: tool.schema
+ .number()
+ .max(5)
+ .optional()
+ .describe("Max messages (max 5)"),
+ urgent_only: tool.schema
+ .boolean()
+ .optional()
+ .describe("Only urgent messages"),
+ since_ts: tool.schema
+ .string()
+ .optional()
+ .describe("Messages since timestamp"),
+ },
+ execute: (args, ctx) => execTool("agentmail_inbox", args, ctx),
+});
+
+const agentmail_read_message = tool({
+ description: "Fetch ONE message body by ID",
+ args: {
+ message_id: tool.schema.number().describe("Message ID"),
+ },
+ execute: (args, ctx) => execTool("agentmail_read_message", args, ctx),
+});
+
+const agentmail_summarize_thread = tool({
+ description: "Summarize thread (PREFERRED over fetching all messages)",
+ args: {
+ thread_id: tool.schema.string().describe("Thread ID"),
+ include_examples: tool.schema
+ .boolean()
+ .optional()
+ .describe("Include example messages"),
+ },
+ execute: (args, ctx) => execTool("agentmail_summarize_thread", args, ctx),
+});
+
+const agentmail_reserve = tool({
+ description: "Reserve file paths for exclusive editing",
+ args: {
+ paths: tool.schema
+ .array(tool.schema.string())
+ .describe("File paths/patterns"),
+ ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+ exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+ reason: tool.schema.string().optional().describe("Reservation reason"),
+ },
+ execute: (args, ctx) => execTool("agentmail_reserve", args, ctx),
+});
+
+const agentmail_release = tool({
+ description: "Release file reservations",
+ args: {
+ paths: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Paths to release"),
+ reservation_ids: tool.schema
+ .array(tool.schema.number())
+ .optional()
+ .describe("Reservation IDs"),
+ },
+ execute: (args, ctx) => execTool("agentmail_release", args, ctx),
+});
+
+const agentmail_ack = tool({
+ description: "Acknowledge a message",
+ args: {
+ message_id: tool.schema.number().describe("Message ID"),
+ },
+ execute: (args, ctx) => execTool("agentmail_ack", args, ctx),
+});
+
+const agentmail_search = tool({
+ description: "Search messages by keyword",
+ args: {
+ query: tool.schema.string().describe("Search query"),
+ limit: tool.schema.number().optional().describe("Max results"),
+ },
+ execute: (args, ctx) => execTool("agentmail_search", args, ctx),
+});
+
+const agentmail_health = tool({
+ description: "Check if Agent Mail server is running",
+ args: {},
+ execute: (args, ctx) => execTool("agentmail_health", args, ctx),
+});
+
+// =============================================================================
+// Structured Tools
+// =============================================================================
+
+const structured_extract_json = tool({
+ description: "Extract JSON from markdown/text response",
+ args: {
+ text: tool.schema.string().describe("Text containing JSON"),
+ },
+ execute: (args, ctx) => execTool("structured_extract_json", args, ctx),
+});
+
+const structured_validate = tool({
+ description: "Validate agent response against a schema",
+ args: {
+ response: tool.schema.string().describe("Agent response to validate"),
+ schema_name: tool.schema
+ .enum(["evaluation", "task_decomposition", "bead_tree"])
+ .describe("Schema to validate against"),
+ max_retries: tool.schema
+ .number()
+ .min(1)
+ .max(5)
+ .optional()
+ .describe("Max retries"),
+ },
+ execute: (args, ctx) => execTool("structured_validate", args, ctx),
+});
+
+const structured_parse_evaluation = tool({
+ description: "Parse and validate evaluation response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_evaluation", args, ctx),
+});
+
+const structured_parse_decomposition = tool({
+ description: "Parse and validate task decomposition response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_decomposition", args, ctx),
+});
+
+const structured_parse_bead_tree = tool({
+ description: "Parse and validate bead tree response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_bead_tree", args, ctx),
+});
+
+// =============================================================================
+// Swarm Tools
+// =============================================================================
+
+const swarm_init = tool({
+ description: "Initialize swarm session and check tool availability",
+ args: {
+ project_path: tool.schema.string().optional().describe("Project path"),
+ },
+ execute: (args, ctx) => execTool("swarm_init", args, ctx),
+});
+
+const swarm_select_strategy = tool({
+ description: "Analyze task and recommend decomposition strategy",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to analyze"),
+ codebase_context: tool.schema
+ .string()
+ .optional()
+ .describe("Codebase context"),
+ },
+ execute: (args, ctx) => execTool("swarm_select_strategy", args, ctx),
+});
+
+const swarm_plan_prompt = tool({
+ description: "Generate strategy-specific decomposition prompt",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to decompose"),
+ strategy: tool.schema
+ .enum(["file-based", "feature-based", "risk-based", "auto"])
+ .optional()
+ .describe("Decomposition strategy"),
+ max_subtasks: tool.schema
+ .number()
+ .int()
+ .min(2)
+ .max(10)
+ .optional()
+ .describe("Max subtasks"),
+ context: tool.schema.string().optional().describe("Additional context"),
+ query_cass: tool.schema
+ .boolean()
+ .optional()
+ .describe("Query CASS for similar tasks"),
+ cass_limit: tool.schema
+ .number()
+ .int()
+ .min(1)
+ .max(10)
+ .optional()
+ .describe("CASS limit"),
+ },
+ execute: (args, ctx) => execTool("swarm_plan_prompt", args, ctx),
+});
+
+const swarm_decompose = tool({
+ description: "Generate decomposition prompt for breaking task into subtasks",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to decompose"),
+ max_subtasks: tool.schema
+ .number()
+ .int()
+ .min(2)
+ .max(10)
+ .optional()
+ .describe("Max subtasks"),
+ context: tool.schema.string().optional().describe("Additional context"),
+ query_cass: tool.schema.boolean().optional().describe("Query CASS"),
+ cass_limit: tool.schema
+ .number()
+ .int()
+ .min(1)
+ .max(10)
+ .optional()
+ .describe("CASS limit"),
+ },
+ execute: (args, ctx) => execTool("swarm_decompose", args, ctx),
+});
+
+const swarm_validate_decomposition = tool({
+ description: "Validate a decomposition response against BeadTreeSchema",
+ args: {
+ response: tool.schema.string().describe("Decomposition response"),
+ },
+ execute: (args, ctx) => execTool("swarm_validate_decomposition", args, ctx),
+});
+
+const swarm_status = tool({
+ description: "Get status of a swarm by epic ID",
+ args: {
+ epic_id: tool.schema.string().describe("Epic bead ID"),
+ project_key: tool.schema.string().describe("Project key"),
+ },
+ execute: (args, ctx) => execTool("swarm_status", args, ctx),
+});
+
+const swarm_progress = tool({
+ description: "Report progress on a subtask to coordinator",
+ args: {
+ project_key: tool.schema.string().describe("Project key"),
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Bead ID"),
+ status: tool.schema
+ .enum(["in_progress", "blocked", "completed", "failed"])
+ .describe("Status"),
+ message: tool.schema.string().optional().describe("Progress message"),
+ progress_percent: tool.schema
+ .number()
+ .min(0)
+ .max(100)
+ .optional()
+ .describe("Progress %"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_progress", args, ctx),
+});
+
+const swarm_complete = tool({
+ description:
+ "Mark subtask complete, release reservations, notify coordinator",
+ args: {
+ project_key: tool.schema.string().describe("Project key"),
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Bead ID"),
+ summary: tool.schema.string().describe("Completion summary"),
+ evaluation: tool.schema.string().optional().describe("Self-evaluation"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS scan"),
+ },
+ execute: (args, ctx) => execTool("swarm_complete", args, ctx),
+});
+
+const swarm_record_outcome = tool({
+ description: "Record subtask outcome for implicit feedback scoring",
+ args: {
+ bead_id: tool.schema.string().describe("Bead ID"),
+ duration_ms: tool.schema.number().int().min(0).describe("Duration in ms"),
+ error_count: tool.schema
+ .number()
+ .int()
+ .min(0)
+ .optional()
+ .describe("Error count"),
+ retry_count: tool.schema
+ .number()
+ .int()
+ .min(0)
+ .optional()
+ .describe("Retry count"),
+ success: tool.schema.boolean().describe("Whether task succeeded"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ criteria: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Evaluation criteria"),
+ strategy: tool.schema
+ .enum(["file-based", "feature-based", "risk-based"])
+ .optional()
+ .describe("Strategy used"),
+ },
+ execute: (args, ctx) => execTool("swarm_record_outcome", args, ctx),
+});
+
+const swarm_subtask_prompt = tool({
+ description: "Generate the prompt for a spawned subtask agent",
+ args: {
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Bead ID"),
+ epic_id: tool.schema.string().describe("Epic ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ subtask_description: tool.schema
+ .string()
+ .optional()
+ .describe("Description"),
+ files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+ shared_context: tool.schema.string().optional().describe("Shared context"),
+ },
+ execute: (args, ctx) => execTool("swarm_subtask_prompt", args, ctx),
+});
+
+const swarm_spawn_subtask = tool({
+ description: "Prepare a subtask for spawning with Task tool",
+ args: {
+ bead_id: tool.schema.string().describe("Bead ID"),
+ epic_id: tool.schema.string().describe("Epic ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ subtask_description: tool.schema
+ .string()
+ .optional()
+ .describe("Description"),
+ files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+ shared_context: tool.schema.string().optional().describe("Shared context"),
+ },
+ execute: (args, ctx) => execTool("swarm_spawn_subtask", args, ctx),
+});
+
+const swarm_complete_subtask = tool({
+ description: "Handle subtask completion after Task agent returns",
+ args: {
+ bead_id: tool.schema.string().describe("Bead ID"),
+ task_result: tool.schema.string().describe("Task result JSON"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_complete_subtask", args, ctx),
+});
+
+const swarm_evaluation_prompt = tool({
+ description: "Generate self-evaluation prompt for a completed subtask",
+ args: {
+ bead_id: tool.schema.string().describe("Bead ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_evaluation_prompt", args, ctx),
+});
+
+// =============================================================================
+// Skills Tools
+// =============================================================================
+
+const skills_list = tool({
+ description:
+ "List all available skills from global, project, and bundled sources",
+ args: {
+ source: tool.schema
+ .enum(["all", "global", "project", "bundled"])
+ .optional()
+ .describe("Filter by source (default: all)"),
+ },
+ execute: (args, ctx) => execTool("skills_list", args, ctx),
+});
+
+const skills_read = tool({
+ description: "Read a skill's full content including SKILL.md and references",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ },
+ execute: (args, ctx) => execTool("skills_read", args, ctx),
+});
+
+const skills_use = tool({
+ description:
+ "Get skill content formatted for injection into agent context. Use this when you need to apply a skill's knowledge to the current task.",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ context: tool.schema
+ .string()
+ .optional()
+ .describe("Optional context about how the skill will be used"),
+ },
+ execute: (args, ctx) => execTool("skills_use", args, ctx),
+});
+
+const skills_create = tool({
+ description: "Create a new skill with SKILL.md template",
+ args: {
+ name: tool.schema.string().describe("Skill name (kebab-case)"),
+ description: tool.schema.string().describe("Brief skill description"),
+ scope: tool.schema
+ .enum(["global", "project"])
+ .optional()
+ .describe("Where to create (default: project)"),
+ tags: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Skill tags for discovery"),
+ },
+ execute: (args, ctx) => execTool("skills_create", args, ctx),
+});
+
+const skills_update = tool({
+ description: "Update an existing skill's SKILL.md content",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ content: tool.schema.string().describe("New SKILL.md content"),
+ },
+ execute: (args, ctx) => execTool("skills_update", args, ctx),
+});
+
+const skills_delete = tool({
+ description: "Delete a skill (project skills only)",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ },
+ execute: (args, ctx) => execTool("skills_delete", args, ctx),
+});
+
+const skills_init = tool({
+ description: "Initialize skills directory in current project",
+ args: {
+ path: tool.schema
+ .string()
+ .optional()
+ .describe("Custom path (default: .opencode/skills)"),
+ },
+ execute: (args, ctx) => execTool("skills_init", args, ctx),
+});
+
+const skills_add_script = tool({
+ description: "Add an executable script to a skill",
+ args: {
+ skill_name: tool.schema.string().describe("Skill name"),
+ script_name: tool.schema.string().describe("Script filename"),
+ content: tool.schema.string().describe("Script content"),
+ executable: tool.schema
+ .boolean()
+ .optional()
+ .describe("Make executable (default: true)"),
+ },
+ execute: (args, ctx) => execTool("skills_add_script", args, ctx),
+});
+
+const skills_execute = tool({
+ description: "Execute a skill's script",
+ args: {
+ skill_name: tool.schema.string().describe("Skill name"),
+ script_name: tool.schema.string().describe("Script to execute"),
+ args: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Script arguments"),
+ },
+ execute: (args, ctx) => execTool("skills_execute", args, ctx),
+});
+
+// =============================================================================
+// Plugin Export
+// =============================================================================
+
+export const SwarmPlugin: Plugin = async (
+ _input: PluginInput,
+): Promise<Hooks> => {
+ return {
+ tool: {
+ // Beads
+ beads_create,
+ beads_create_epic,
+ beads_query,
+ beads_update,
+ beads_close,
+ beads_start,
+ beads_ready,
+ beads_sync,
+ beads_link_thread,
+ // Agent Mail
+ agentmail_init,
+ agentmail_send,
+ agentmail_inbox,
+ agentmail_read_message,
+ agentmail_summarize_thread,
+ agentmail_reserve,
+ agentmail_release,
+ agentmail_ack,
+ agentmail_search,
+ agentmail_health,
+ // Structured
+ structured_extract_json,
+ structured_validate,
+ structured_parse_evaluation,
+ structured_parse_decomposition,
+ structured_parse_bead_tree,
+ // Swarm
+ swarm_init,
+ swarm_select_strategy,
+ swarm_plan_prompt,
+ swarm_decompose,
+ swarm_validate_decomposition,
+ swarm_status,
+ swarm_progress,
+ swarm_complete,
+ swarm_record_outcome,
+ swarm_subtask_prompt,
+ swarm_spawn_subtask,
+ swarm_complete_subtask,
+ swarm_evaluation_prompt,
+ // Skills
+ skills_list,
+ skills_read,
+ skills_use,
+ skills_create,
+ skills_update,
+ skills_delete,
+ skills_init,
+ skills_add_script,
+ skills_execute,
+ },
+ };
+};
+
+export default SwarmPlugin;
diff --git a/plugin/swarm.js b/plugin/swarm.js
deleted file mode 120000
index 40f437a..0000000
--- a/plugin/swarm.js
+++ /dev/null
@@ -1 +0,0 @@
-/Users/joel/Code/joelhooks/opencode-swarm-plugin/dist/plugin.js
\ No newline at end of file
diff --git a/plugin/swarm.ts b/plugin/swarm.ts
new file mode 100644
index 0000000..dbb3379
--- /dev/null
+++ b/plugin/swarm.ts
@@ -0,0 +1,2993 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════════════════╗
+ * ║ ║
+ * ║ 🐝 OPENCODE SWARM PLUGIN WRAPPER 🐝 ║
+ * ║ ║
+ * ║ This file lives at: ~/.config/opencode/plugin/swarm.ts ║
+ * ║ Generated by: swarm setup ║
+ * ║ ║
+ * ╠═══════════════════════════════════════════════════════════════════════════╣
+ * ║ ║
+ * ║ ⚠️ CRITICAL: THIS FILE MUST BE 100% SELF-CONTAINED ⚠️ ║
+ * ║ ║
+ * ║ ❌ NEVER import from "opencode-swarm-plugin" npm package ║
+ * ║ ❌ NEVER import from any package with transitive deps (evalite, etc) ║
+ * ║ ❌ NEVER add dependencies that aren't provided by OpenCode ║
+ * ║ ║
+ * ║ ✅ ONLY import from: @opencode-ai/plugin, @opencode-ai/sdk, node:* ║
+ * ║ ✅ Shell out to `swarm` CLI for all tool execution ║
+ * ║ ✅ Inline any logic that would otherwise require imports ║
+ * ║ ║
+ * ║ WHY? The npm package has dependencies (evalite, etc) that aren't ║
+ * ║ available in OpenCode's plugin context. Importing causes: ║
+ * ║ "Cannot find module 'evalite/runner'" → trace trap → OpenCode crash ║
+ * ║ ║
+ * ║ PATTERN: Plugin wrapper is DUMB. CLI is SMART. ║
+ * ║ - Wrapper: thin shell, no logic, just bridges to CLI ║
+ * ║ - CLI: all the smarts, all the deps, runs in its own context ║
+ * ║ ║
+ * ╚═══════════════════════════════════════════════════════════════════════════╝
+ *
+ * Environment variables passed to CLI:
+ * - OPENCODE_SESSION_ID: Session state persistence
+ * - OPENCODE_MESSAGE_ID: Message context
+ * - OPENCODE_AGENT: Agent context
+ * - SWARM_PROJECT_DIR: Project directory (critical for database path)
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+import type { ToolPart } from "@opencode-ai/sdk";
+import { tool } from "@opencode-ai/plugin";
+import { spawn } from "child_process";
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// =============================================================================
+// Swarm Signature Detection (INLINED - do not import from opencode-swarm-plugin)
+// =============================================================================
+
+/**
+ * Subtask lifecycle status derived from events
+ */
+type SubtaskStatus = "created" | "spawned" | "in_progress" | "completed" | "closed";
+
+/**
+ * Subtask state projected from events
+ */
+interface SubtaskState {
+ id: string;
+ title: string;
+ status: SubtaskStatus;
+ files: string[];
+ worker?: string;
+ spawnedAt?: number;
+ completedAt?: number;
+}
+
+/**
+ * Epic state projected from events
+ */
+interface EpicState {
+ id: string;
+ title: string;
+ status: "open" | "in_progress" | "closed";
+ createdAt: number;
+}
+
+/**
+ * Complete swarm state projected from session events
+ */
+interface SwarmProjection {
+ isSwarm: boolean;
+ epic?: EpicState;
+ subtasks: Map<string, SubtaskState>;
+ projectPath?: string;
+ coordinatorName?: string;
+ lastEventAt?: number;
+ counts: {
+ total: number;
+ created: number;
+ spawned: number;
+ inProgress: number;
+ completed: number;
+ closed: number;
+ };
+}
+
+/**
+ * Tool call event extracted from session messages
+ */
+interface ToolCallEvent {
+ tool: string;
+ input: Record<string, unknown>;
+ output: string;
+ timestamp: number;
+}
+
+/** Parse epic ID from hive_create_epic output */
+function parseEpicId(output: string): string | undefined {
+ try {
+ const parsed = JSON.parse(output);
+ return parsed.epic?.id || parsed.id;
+ } catch {
+ return undefined;
+ }
+}
+
+/** Parse subtask IDs from hive_create_epic output */
+function parseSubtaskIds(output: string): string[] {
+ try {
+ const parsed = JSON.parse(output);
+ const subtasks = parsed.subtasks || parsed.epic?.subtasks || [];
+ return subtasks
+ .map((s: unknown) => {
+ if (typeof s === "object" && s !== null && "id" in s) {
+ return (s as { id: string }).id;
+ }
+ return undefined;
+ })
+ .filter((id: unknown): id is string => typeof id === "string");
+ } catch {
+ return [];
+ }
+}
+
+/**
+ * Project swarm state from session tool call events
+ */
+function projectSwarmState(events: ToolCallEvent[]): SwarmProjection {
+ const state: SwarmProjection = {
+ isSwarm: false,
+ subtasks: new Map(),
+ counts: { total: 0, created: 0, spawned: 0, inProgress: 0, completed: 0, closed: 0 },
+ };
+
+ let hasEpic = false;
+ let hasSpawn = false;
+
+ for (const event of events) {
+ state.lastEventAt = event.timestamp;
+
+ switch (event.tool) {
+ case "hive_create_epic": {
+ const epicId = parseEpicId(event.output);
+ const epicTitle = typeof event.input.epic_title === "string" ? event.input.epic_title : undefined;
+
+ if (epicId) {
+ state.epic = { id: epicId, title: epicTitle || "Unknown Epic", status: "open", createdAt: event.timestamp };
+ hasEpic = true;
+
+ const subtasks = event.input.subtasks;
+ if (Array.isArray(subtasks)) {
+ for (const subtask of subtasks) {
+ if (typeof subtask === "object" && subtask !== null) {
+ state.counts.created++;
+ state.counts.total++;
+ }
+ }
+ }
+
+ const subtaskIds = parseSubtaskIds(event.output);
+ for (const id of subtaskIds) {
+ if (!state.subtasks.has(id)) {
+ state.subtasks.set(id, { id, title: "Unknown", status: "created", files: [] });
+ state.counts.total++;
+ state.counts.created++;
+ }
+ }
+ }
+ break;
+ }
+
+ case "swarm_spawn_subtask": {
+ const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+ const title = typeof event.input.subtask_title === "string" ? event.input.subtask_title : "Unknown";
+ const files = Array.isArray(event.input.files) ? (event.input.files as string[]) : [];
+
+ if (beadId) {
+ hasSpawn = true;
+ const existing = state.subtasks.get(beadId);
+ if (existing) {
+ if (existing.status === "created") { state.counts.created--; state.counts.spawned++; }
+ existing.status = "spawned";
+ existing.title = title;
+ existing.files = files;
+ existing.spawnedAt = event.timestamp;
+ } else {
+ state.subtasks.set(beadId, { id: beadId, title, status: "spawned", files, spawnedAt: event.timestamp });
+ state.counts.total++;
+ state.counts.spawned++;
+ }
+
+ const epicId = typeof event.input.epic_id === "string" ? event.input.epic_id : undefined;
+ if (epicId && !state.epic) {
+ state.epic = { id: epicId, title: "Unknown Epic", status: "in_progress", createdAt: event.timestamp };
+ }
+ }
+ break;
+ }
+
+ case "hive_start": {
+ const id = typeof event.input.id === "string" ? event.input.id : undefined;
+ if (id) {
+ const subtask = state.subtasks.get(id);
+ if (subtask && subtask.status !== "completed" && subtask.status !== "closed") {
+ if (subtask.status === "created") state.counts.created--;
+ else if (subtask.status === "spawned") state.counts.spawned--;
+ subtask.status = "in_progress";
+ state.counts.inProgress++;
+ }
+ if (state.epic && state.epic.id === id) state.epic.status = "in_progress";
+ }
+ break;
+ }
+
+ case "swarm_complete": {
+ const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+ if (beadId) {
+ const subtask = state.subtasks.get(beadId);
+ if (subtask && subtask.status !== "closed") {
+ if (subtask.status === "created") state.counts.created--;
+ else if (subtask.status === "spawned") state.counts.spawned--;
+ else if (subtask.status === "in_progress") state.counts.inProgress--;
+ subtask.status = "completed";
+ subtask.completedAt = event.timestamp;
+ state.counts.completed++;
+ }
+ }
+ break;
+ }
+
+ case "hive_close": {
+ const id = typeof event.input.id === "string" ? event.input.id : undefined;
+ if (id) {
+ const subtask = state.subtasks.get(id);
+ if (subtask) {
+ if (subtask.status === "created") state.counts.created--;
+ else if (subtask.status === "spawned") state.counts.spawned--;
+ else if (subtask.status === "in_progress") state.counts.inProgress--;
+ else if (subtask.status === "completed") state.counts.completed--;
+ subtask.status = "closed";
+ state.counts.closed++;
+ }
+ if (state.epic && state.epic.id === id) state.epic.status = "closed";
+ }
+ break;
+ }
+
+ case "swarmmail_init": {
+ try {
+ const parsed = JSON.parse(event.output);
+ if (parsed.agent_name) state.coordinatorName = parsed.agent_name;
+ if (parsed.project_key) state.projectPath = parsed.project_key;
+ } catch { /* skip */ }
+ break;
+ }
+ }
+ }
+
+ state.isSwarm = hasEpic && hasSpawn;
+ return state;
+}
+
+/** Quick check for swarm signature without full projection */
+function hasSwarmSignature(events: ToolCallEvent[]): boolean {
+ let hasEpic = false;
+ let hasSpawn = false;
+ for (const event of events) {
+ if (event.tool === "hive_create_epic") hasEpic = true;
+ else if (event.tool === "swarm_spawn_subtask") hasSpawn = true;
+ if (hasEpic && hasSpawn) return true;
+ }
+ return false;
+}
+
+/** Check if swarm is still active (has pending work) */
+function isSwarmActive(projection: SwarmProjection): boolean {
+ if (!projection.isSwarm) return false;
+ return projection.counts.created > 0 || projection.counts.spawned > 0 ||
+ projection.counts.inProgress > 0 || projection.counts.completed > 0;
+}
+
+/** Get human-readable swarm status summary */
+function getSwarmSummary(projection: SwarmProjection): string {
+ if (!projection.isSwarm) return "No swarm detected";
+ const { counts, epic } = projection;
+ const parts: string[] = [];
+ if (epic) parts.push(`Epic: ${epic.id} - ${epic.title} [${epic.status}]`);
+ parts.push(`Subtasks: ${counts.total} total (${counts.spawned} spawned, ${counts.inProgress} in_progress, ${counts.completed} completed, ${counts.closed} closed)`);
+ parts.push(isSwarmActive(projection) ? "Status: ACTIVE - has pending work" : "Status: COMPLETE - all work closed");
+ return parts.join("\n");
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const SWARM_CLI = "swarm";
+
+// =============================================================================
+// File-based Logging (writes to ~/.config/swarm-tools/logs/)
+// =============================================================================
+
+const LOG_DIR = join(homedir(), ".config", "swarm-tools", "logs");
+const COMPACTION_LOG = join(LOG_DIR, "compaction.log");
+
+/**
+ * Ensure log directory exists
+ */
+function ensureLogDir(): void {
+ if (!existsSync(LOG_DIR)) {
+ mkdirSync(LOG_DIR, { recursive: true });
+ }
+}
+
+/**
+ * Log a compaction event to file (JSON lines format, compatible with `swarm log`)
+ *
+ * @param level - Log level (info, debug, warn, error)
+ * @param msg - Log message
+ * @param data - Additional structured data
+ */
+function logCompaction(
+ level: "info" | "debug" | "warn" | "error",
+ msg: string,
+ data?: Record<string, unknown>,
+): void {
+ try {
+ ensureLogDir();
+ const entry = JSON.stringify({
+ time: new Date().toISOString(),
+ level,
+ msg,
+ ...data,
+ });
+ appendFileSync(COMPACTION_LOG, entry + "\n");
+ } catch {
+ // Silently fail - logging should never break the plugin
+ }
+}
+
+/**
+ * Capture compaction event for evals via CLI
+ *
+ * Shells out to `swarm capture` command to avoid import issues.
+ * The CLI handles all the logic - plugin wrapper stays dumb.
+ *
+ * @param sessionID - Session ID
+ * @param epicID - Epic ID (or "unknown" if not detected)
+ * @param compactionType - Event type (detection_complete, prompt_generated, context_injected)
+ * @param payload - Event-specific data (full prompts, detection results, etc.)
+ */
+async function captureCompaction(
+ sessionID: string,
+ epicID: string,
+ compactionType: "detection_complete" | "prompt_generated" | "context_injected",
+ payload: any,
+): Promise<void> {
+ try {
+ // Shell out to CLI - no imports needed, version always matches
+ const args = [
+ "capture",
+ "--session", sessionID,
+ "--epic", epicID,
+ "--type", compactionType,
+ "--payload", JSON.stringify(payload),
+ ];
+
+ const proc = spawn(SWARM_CLI, args, {
+ env: { ...process.env, SWARM_PROJECT_DIR: projectDirectory },
+ stdio: ["ignore", "ignore", "ignore"], // Fire and forget
+ });
+
+ // Don't wait - capture is non-blocking
+ proc.unref();
+ } catch (err) {
+ // Non-fatal - capture failures shouldn't break compaction
+ logCompaction("warn", "compaction_capture_failed", {
+ session_id: sessionID,
+ compaction_type: compactionType,
+ error: err instanceof Error ? err.message : String(err),
+ });
+ }
+}
+
+// Module-level project directory - set during plugin initialization
+// This is CRITICAL: without it, the CLI uses process.cwd() which may be wrong
+let projectDirectory: string = process.cwd();
+
+// Module-level SDK client - set during plugin initialization
+// Used for scanning session messages during compaction
+let sdkClient: any = null;
+
+// =============================================================================
+// CLI Execution Helper
+// =============================================================================
+
+/**
+ * Execute a swarm tool via CLI
+ *
+ * Spawns `swarm tool <name> --json '<args>'` and returns the result.
+ * Passes session context via environment variables.
+ *
+ * IMPORTANT: Runs in projectDirectory (set by OpenCode) not process.cwd()
+ */
+async function execTool(
+ name: string,
+ args: Record<string, unknown>,
+ ctx: { sessionID: string; messageID: string; agent: string },
+): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const hasArgs = Object.keys(args).length > 0;
+ const cliArgs = hasArgs
+ ? ["tool", name, "--json", JSON.stringify(args)]
+ : ["tool", name];
+
+ const proc = spawn(SWARM_CLI, cliArgs, {
+ cwd: projectDirectory, // Run in project directory, not plugin directory
+ stdio: ["ignore", "pipe", "pipe"],
+ env: {
+ ...process.env,
+ OPENCODE_SESSION_ID: ctx.sessionID,
+ OPENCODE_MESSAGE_ID: ctx.messageID,
+ OPENCODE_AGENT: ctx.agent,
+ SWARM_PROJECT_DIR: projectDirectory, // Also pass as env var
+ },
+ });
+
+ let stdout = "";
+ let stderr = "";
+
+ proc.stdout.on("data", (data) => {
+ stdout += data;
+ });
+ proc.stderr.on("data", (data) => {
+ stderr += data;
+ });
+
+ proc.on("close", (code) => {
+ if (code === 0) {
+ // Success - return the JSON output
+ try {
+ const result = JSON.parse(stdout);
+ if (result.success && result.data !== undefined) {
+ // Unwrap the data for cleaner tool output
+ resolve(
+ typeof result.data === "string"
+ ? result.data
+ : JSON.stringify(result.data, null, 2),
+ );
+ } else if (!result.success && result.error) {
+ // Tool returned an error in JSON format
+ // Handle both string errors and object errors with .message
+ const errorMsg = typeof result.error === "string"
+ ? result.error
+ : (result.error.message || "Tool execution failed");
+ reject(new Error(errorMsg));
+ } else {
+ resolve(stdout);
+ }
+ } catch {
+ resolve(stdout);
+ }
+ } else if (code === 2) {
+ reject(new Error(`Unknown tool: ${name}`));
+ } else if (code === 3) {
+ reject(new Error(`Invalid JSON args: ${stderr}`));
+ } else {
+ // Tool returned error
+ try {
+ const result = JSON.parse(stdout);
+ if (!result.success && result.error) {
+ // Handle both string errors and object errors with .message
+ const errorMsg = typeof result.error === "string"
+ ? result.error
+ : (result.error.message || `Tool failed with code ${code}`);
+ reject(new Error(errorMsg));
+ } else {
+ reject(
+ new Error(stderr || stdout || `Tool failed with code ${code}`),
+ );
+ }
+ } catch {
+ reject(
+ new Error(stderr || stdout || `Tool failed with code ${code}`),
+ );
+ }
+ }
+ });
+
+ proc.on("error", (err) => {
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+ reject(
+ new Error(
+ `swarm CLI not found. Install with: npm install -g opencode-swarm-plugin`,
+ ),
+ );
+ } else {
+ reject(err);
+ }
+ });
+ });
+}
+
+// =============================================================================
+// Beads Tools
+// =============================================================================
+
+const hive_create = tool({
+ description: "Create a new bead with type-safe validation",
+ args: {
+ title: tool.schema.string().describe("Bead title"),
+ type: tool.schema
+ .enum(["bug", "feature", "task", "epic", "chore"])
+ .optional()
+ .describe("Issue type (default: task)"),
+ priority: tool.schema
+ .number()
+ .min(0)
+ .max(3)
+ .optional()
+ .describe("Priority 0-3 (default: 2)"),
+ description: tool.schema.string().optional().describe("Bead description"),
+ parent_id: tool.schema
+ .string()
+ .optional()
+ .describe("Parent bead ID for epic children"),
+ },
+ execute: (args, ctx) => execTool("hive_create", args, ctx),
+});
+
+const hive_create_epic = tool({
+ description: "Create epic with subtasks in one atomic operation",
+ args: {
+ epic_title: tool.schema.string().describe("Epic title"),
+ epic_description: tool.schema
+ .string()
+ .optional()
+ .describe("Epic description"),
+ subtasks: tool.schema
+ .array(
+ tool.schema.object({
+ title: tool.schema.string(),
+ priority: tool.schema.number().min(0).max(3).optional(),
+ files: tool.schema.array(tool.schema.string()).optional(),
+ }),
+ )
+ .describe("Subtasks to create under the epic"),
+ },
+ execute: (args, ctx) => execTool("hive_create_epic", args, ctx),
+});
+
+const hive_query = tool({
+ description: "Query beads with filters (replaces bd list, bd ready, bd wip)",
+ args: {
+ status: tool.schema
+ .enum(["open", "in_progress", "blocked", "closed"])
+ .optional()
+ .describe("Filter by status"),
+ type: tool.schema
+ .enum(["bug", "feature", "task", "epic", "chore"])
+ .optional()
+ .describe("Filter by type"),
+ ready: tool.schema
+ .boolean()
+ .optional()
+ .describe("Only show unblocked beads"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 20)"),
+ },
+ execute: (args, ctx) => execTool("hive_query", args, ctx),
+});
+
+const hive_update = tool({
+ description: "Update bead status/description",
+ args: {
+ id: tool.schema.string().describe("Cell ID"),
+ status: tool.schema
+ .enum(["open", "in_progress", "blocked", "closed"])
+ .optional()
+ .describe("New status"),
+ description: tool.schema.string().optional().describe("New description"),
+ priority: tool.schema
+ .number()
+ .min(0)
+ .max(3)
+ .optional()
+ .describe("New priority"),
+ },
+ execute: (args, ctx) => execTool("hive_update", args, ctx),
+});
+
+const hive_close = tool({
+ description: "Close a bead with reason",
+ args: {
+ id: tool.schema.string().describe("Cell ID"),
+ reason: tool.schema.string().describe("Completion reason"),
+ },
+ execute: (args, ctx) => execTool("hive_close", args, ctx),
+});
+
+const hive_start = tool({
+ description: "Mark a bead as in-progress",
+ args: {
+ id: tool.schema.string().describe("Cell ID"),
+ },
+ execute: (args, ctx) => execTool("hive_start", args, ctx),
+});
+
+const hive_ready = tool({
+ description: "Get the next ready bead (unblocked, highest priority)",
+ args: {},
+ execute: (args, ctx) => execTool("hive_ready", args, ctx),
+});
+
+const hive_sync = tool({
+ description: "Sync beads to git and push (MANDATORY at session end)",
+ args: {
+ auto_pull: tool.schema.boolean().optional().describe("Pull before sync"),
+ },
+ execute: (args, ctx) => execTool("hive_sync", args, ctx),
+});
+
+const hive_cells = tool({
+ description: `Query cells from the hive database with flexible filtering.
+
+USE THIS TOOL TO:
+- List all open cells: hive_cells()
+- Find cells by status: hive_cells({ status: "in_progress" })
+- Find cells by type: hive_cells({ type: "bug" })
+- Get a specific cell by partial ID: hive_cells({ id: "mjkmd" })
+- Get the next ready (unblocked) cell: hive_cells({ ready: true })
+- Combine filters: hive_cells({ status: "open", type: "task" })
+
+RETURNS: Array of cells with id, title, status, priority, type, parent_id, created_at, updated_at
+
+PREFER THIS OVER hive_query when you need to:
+- See what work is available
+- Check status of multiple cells
+- Find cells matching criteria
+- Look up a cell by partial ID`,
+ args: {
+ id: tool.schema.string().optional().describe("Partial or full cell ID to look up"),
+ status: tool.schema.enum(["open", "in_progress", "blocked", "closed"]).optional().describe("Filter by status"),
+ type: tool.schema.enum(["task", "bug", "feature", "epic", "chore"]).optional().describe("Filter by type"),
+ ready: tool.schema.boolean().optional().describe("If true, return only the next unblocked cell"),
+ limit: tool.schema.number().optional().describe("Max cells to return (default 20)"),
+ },
+ execute: (args, ctx) => execTool("hive_cells", args, ctx),
+});
+
+const beads_link_thread = tool({
+ description: "Add metadata linking bead to Agent Mail thread",
+ args: {
+ bead_id: tool.schema.string().describe("Cell ID"),
+ thread_id: tool.schema.string().describe("Agent Mail thread ID"),
+ },
+ execute: (args, ctx) => execTool("beads_link_thread", args, ctx),
+});
+
+// =============================================================================
+// Swarm Mail Tools (Embedded)
+// =============================================================================
+
+const swarmmail_init = tool({
+ description: "Initialize Swarm Mail session (REQUIRED FIRST)",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to the project"),
+ agent_name: tool.schema.string().optional().describe("Custom agent name"),
+ task_description: tool.schema
+ .string()
+ .optional()
+ .describe("Task description"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_init", args, ctx),
+});
+
+const swarmmail_send = tool({
+ description: "Send message to other agents via Swarm Mail",
+ args: {
+ to: tool.schema
+ .array(tool.schema.string())
+ .describe("Recipient agent names"),
+ subject: tool.schema.string().describe("Message subject"),
+ body: tool.schema.string().describe("Message body"),
+ thread_id: tool.schema
+ .string()
+ .optional()
+ .describe("Thread ID for grouping"),
+ importance: tool.schema
+ .enum(["low", "normal", "high", "urgent"])
+ .optional()
+ .describe("Message importance"),
+ ack_required: tool.schema
+ .boolean()
+ .optional()
+ .describe("Require acknowledgment"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_send", args, ctx),
+});
+
+const swarmmail_inbox = tool({
+ description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, max 5 messages)",
+ args: {
+ limit: tool.schema
+ .number()
+ .max(5)
+ .optional()
+ .describe("Max messages (max 5)"),
+ urgent_only: tool.schema
+ .boolean()
+ .optional()
+ .describe("Only urgent messages"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_inbox", args, ctx),
+});
+
+const swarmmail_read_message = tool({
+ description: "Fetch ONE message body by ID",
+ args: {
+ message_id: tool.schema.number().describe("Message ID"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_read_message", args, ctx),
+});
+
+const swarmmail_reserve = tool({
+ description: "Reserve file paths for exclusive editing",
+ args: {
+ paths: tool.schema
+ .array(tool.schema.string())
+ .describe("File paths/patterns"),
+ ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+ exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+ reason: tool.schema.string().optional().describe("Reservation reason"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_reserve", args, ctx),
+});
+
+const swarmmail_release = tool({
+ description: "Release file reservations",
+ args: {
+ paths: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Paths to release"),
+ reservation_ids: tool.schema
+ .array(tool.schema.number())
+ .optional()
+ .describe("Reservation IDs"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_release", args, ctx),
+});
+
+const swarmmail_ack = tool({
+ description: "Acknowledge a message",
+ args: {
+ message_id: tool.schema.number().describe("Message ID"),
+ },
+ execute: (args, ctx) => execTool("swarmmail_ack", args, ctx),
+});
+
+const swarmmail_health = tool({
+ description: "Check Swarm Mail database health",
+ args: {},
+ execute: (args, ctx) => execTool("swarmmail_health", args, ctx),
+});
+
+// =============================================================================
+// Structured Tools
+// =============================================================================
+
+const structured_extract_json = tool({
+ description: "Extract JSON from markdown/text response",
+ args: {
+ text: tool.schema.string().describe("Text containing JSON"),
+ },
+ execute: (args, ctx) => execTool("structured_extract_json", args, ctx),
+});
+
+const structured_validate = tool({
+ description: "Validate agent response against a schema",
+ args: {
+ response: tool.schema.string().describe("Agent response to validate"),
+ schema_name: tool.schema
+ .enum(["evaluation", "task_decomposition", "cell_tree"])
+ .describe("Schema to validate against"),
+ max_retries: tool.schema
+ .number()
+ .min(1)
+ .max(5)
+ .optional()
+ .describe("Max retries"),
+ },
+ execute: (args, ctx) => execTool("structured_validate", args, ctx),
+});
+
+const structured_parse_evaluation = tool({
+ description: "Parse and validate evaluation response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_evaluation", args, ctx),
+});
+
+const structured_parse_decomposition = tool({
+ description: "Parse and validate task decomposition response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_decomposition", args, ctx),
+});
+
+const structured_parse_cell_tree = tool({
+ description: "Parse and validate bead tree response",
+ args: {
+ response: tool.schema.string().describe("Agent response"),
+ },
+ execute: (args, ctx) => execTool("structured_parse_cell_tree", args, ctx),
+});
+
+// =============================================================================
+// Swarm Tools
+// =============================================================================
+
+const swarm_init = tool({
+ description: "Initialize swarm session and check tool availability",
+ args: {
+ project_path: tool.schema.string().optional().describe("Project path"),
+ isolation: tool.schema
+ .enum(["worktree", "reservation"])
+ .optional()
+ .describe(
+ "Isolation mode: 'worktree' for git worktree isolation, 'reservation' for file reservations (default)",
+ ),
+ },
+ execute: (args, ctx) => execTool("swarm_init", args, ctx),
+});
+
+const swarm_select_strategy = tool({
+ description: "Analyze task and recommend decomposition strategy",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to analyze"),
+ codebase_context: tool.schema
+ .string()
+ .optional()
+ .describe("Codebase context"),
+ },
+ execute: (args, ctx) => execTool("swarm_select_strategy", args, ctx),
+});
+
+const swarm_plan_prompt = tool({
+ description: "Generate strategy-specific decomposition prompt",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to decompose"),
+ strategy: tool.schema
+ .enum(["file-based", "feature-based", "risk-based", "auto"])
+ .optional()
+ .describe("Decomposition strategy"),
+ max_subtasks: tool.schema
+ .number()
+ .int()
+ .min(2)
+ .max(10)
+ .optional()
+ .describe("Max subtasks"),
+ context: tool.schema.string().optional().describe("Additional context"),
+ query_cass: tool.schema
+ .boolean()
+ .optional()
+ .describe("Query CASS for similar tasks"),
+ cass_limit: tool.schema
+ .number()
+ .int()
+ .min(1)
+ .max(10)
+ .optional()
+ .describe("CASS limit"),
+ },
+ execute: (args, ctx) => execTool("swarm_plan_prompt", args, ctx),
+});
+
+const swarm_decompose = tool({
+ description: "Generate decomposition prompt for breaking task into subtasks",
+ args: {
+ task: tool.schema.string().min(1).describe("Task to decompose"),
+ max_subtasks: tool.schema
+ .number()
+ .int()
+ .min(2)
+ .max(10)
+ .optional()
+ .describe("Max subtasks"),
+ context: tool.schema.string().optional().describe("Additional context"),
+ query_cass: tool.schema.boolean().optional().describe("Query CASS"),
+ cass_limit: tool.schema
+ .number()
+ .int()
+ .min(1)
+ .max(10)
+ .optional()
+ .describe("CASS limit"),
+ },
+ execute: (args, ctx) => execTool("swarm_decompose", args, ctx),
+});
+
+const swarm_validate_decomposition = tool({
+ description: "Validate a decomposition response against CellTreeSchema",
+ args: {
+ response: tool.schema.string().describe("Decomposition response"),
+ },
+ execute: (args, ctx) => execTool("swarm_validate_decomposition", args, ctx),
+});
+
+const swarm_status = tool({
+ description: "Get status of a swarm by epic ID",
+ args: {
+ epic_id: tool.schema.string().describe("Epic bead ID"),
+ project_key: tool.schema.string().describe("Project key"),
+ },
+ execute: (args, ctx) => execTool("swarm_status", args, ctx),
+});
+
+const swarm_progress = tool({
+ description: "Report progress on a subtask to coordinator",
+ args: {
+ project_key: tool.schema.string().describe("Project key"),
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Cell ID"),
+ status: tool.schema
+ .enum(["in_progress", "blocked", "completed", "failed"])
+ .describe("Status"),
+ message: tool.schema.string().optional().describe("Progress message"),
+ progress_percent: tool.schema
+ .number()
+ .min(0)
+ .max(100)
+ .optional()
+ .describe("Progress %"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_progress", args, ctx),
+});
+
+const swarm_complete = tool({
+ description:
+ "Mark subtask complete with Verification Gate. Runs UBS scan, typecheck, and tests before allowing completion.",
+ args: {
+ project_key: tool.schema.string().describe("Project key"),
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Cell ID"),
+ summary: tool.schema.string().describe("Completion summary"),
+ evaluation: tool.schema.string().optional().describe("Self-evaluation JSON"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified - will be verified"),
+ skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS scan"),
+ skip_verification: tool.schema
+ .boolean()
+ .optional()
+ .describe("Skip ALL verification (UBS, typecheck, tests)"),
+ skip_review: tool.schema
+ .boolean()
+ .optional()
+ .describe("Skip review gate check"),
+ },
+ execute: (args, ctx) => execTool("swarm_complete", args, ctx),
+});
+
+const swarm_record_outcome = tool({
+ description: "Record subtask outcome for implicit feedback scoring",
+ args: {
+ bead_id: tool.schema.string().describe("Cell ID"),
+ duration_ms: tool.schema.number().int().min(0).describe("Duration in ms"),
+ error_count: tool.schema
+ .number()
+ .int()
+ .min(0)
+ .optional()
+ .describe("Error count"),
+ retry_count: tool.schema
+ .number()
+ .int()
+ .min(0)
+ .optional()
+ .describe("Retry count"),
+ success: tool.schema.boolean().describe("Whether task succeeded"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ criteria: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Evaluation criteria"),
+ strategy: tool.schema
+ .enum(["file-based", "feature-based", "risk-based"])
+ .optional()
+ .describe("Strategy used"),
+ },
+ execute: (args, ctx) => execTool("swarm_record_outcome", args, ctx),
+});
+
+const swarm_subtask_prompt = tool({
+ description: "Generate the prompt for a spawned subtask agent",
+ args: {
+ agent_name: tool.schema.string().describe("Agent name"),
+ bead_id: tool.schema.string().describe("Cell ID"),
+ epic_id: tool.schema.string().describe("Epic ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ subtask_description: tool.schema
+ .string()
+ .optional()
+ .describe("Description"),
+ files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+ shared_context: tool.schema.string().optional().describe("Shared context"),
+ },
+ execute: (args, ctx) => execTool("swarm_subtask_prompt", args, ctx),
+});
+
+const swarm_spawn_subtask = tool({
+ description: "Prepare a subtask for spawning with Task tool",
+ args: {
+ bead_id: tool.schema.string().describe("Cell ID"),
+ epic_id: tool.schema.string().describe("Epic ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ subtask_description: tool.schema
+ .string()
+ .optional()
+ .describe("Description"),
+ files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+ shared_context: tool.schema.string().optional().describe("Shared context"),
+ },
+ execute: (args, ctx) => execTool("swarm_spawn_subtask", args, ctx),
+});
+
+const swarm_complete_subtask = tool({
+ description: "Handle subtask completion after Task agent returns",
+ args: {
+ bead_id: tool.schema.string().describe("Cell ID"),
+ task_result: tool.schema.string().describe("Task result JSON"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_complete_subtask", args, ctx),
+});
+
+const swarm_evaluation_prompt = tool({
+ description: "Generate self-evaluation prompt for a completed subtask",
+ args: {
+ bead_id: tool.schema.string().describe("Cell ID"),
+ subtask_title: tool.schema.string().describe("Subtask title"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .describe("Files modified"),
+ },
+ execute: (args, ctx) => execTool("swarm_evaluation_prompt", args, ctx),
+});
+
+const swarm_broadcast = tool({
+ description:
+ "Broadcast context update to all agents working on the same epic",
+ args: {
+ project_path: tool.schema.string().describe("Project path"),
+ agent_name: tool.schema.string().describe("Agent name"),
+ epic_id: tool.schema.string().describe("Epic ID"),
+ message: tool.schema.string().describe("Context update message"),
+ importance: tool.schema
+ .enum(["info", "warning", "blocker"])
+ .optional()
+ .describe("Priority level (default: info)"),
+ files_affected: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files this context relates to"),
+ },
+ execute: (args, ctx) => execTool("swarm_broadcast", args, ctx),
+});
+
+// =============================================================================
+// Worktree Isolation Tools
+// =============================================================================
+
+const swarm_worktree_create = tool({
+ description:
+ "Create a git worktree for isolated task execution. Worker operates in worktree, not main branch.",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to project root"),
+ task_id: tool.schema.string().describe("Task/bead ID (e.g., bd-abc123.1)"),
+ start_commit: tool.schema
+ .string()
+ .describe("Commit SHA to create worktree at (swarm start point)"),
+ },
+ execute: (args, ctx) => execTool("swarm_worktree_create", args, ctx),
+});
+
+const swarm_worktree_merge = tool({
+ description:
+ "Cherry-pick commits from worktree back to main branch. Call after worker completes.",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to project root"),
+ task_id: tool.schema.string().describe("Task/bead ID"),
+ start_commit: tool.schema
+ .string()
+ .optional()
+ .describe("Original start commit (to find new commits)"),
+ },
+ execute: (args, ctx) => execTool("swarm_worktree_merge", args, ctx),
+});
+
+const swarm_worktree_cleanup = tool({
+ description:
+ "Remove a worktree after completion or abort. Idempotent - safe to call multiple times.",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to project root"),
+ task_id: tool.schema.string().optional().describe("Task/bead ID to clean up"),
+ cleanup_all: tool.schema
+ .boolean()
+ .optional()
+ .describe("Remove all worktrees for this project"),
+ },
+ execute: (args, ctx) => execTool("swarm_worktree_cleanup", args, ctx),
+});
+
+const swarm_worktree_list = tool({
+ description: "List all active worktrees for a project",
+ args: {
+ project_path: tool.schema.string().describe("Absolute path to project root"),
+ },
+ execute: (args, ctx) => execTool("swarm_worktree_list", args, ctx),
+});
+
+// =============================================================================
+// Structured Review Tools
+// =============================================================================
+
+const swarm_review = tool({
+ description:
+ "Generate a review prompt for a completed subtask. Includes epic context, dependencies, and diff.",
+ args: {
+ project_key: tool.schema.string().describe("Project path"),
+ epic_id: tool.schema.string().describe("Epic bead ID"),
+ task_id: tool.schema.string().describe("Subtask bead ID to review"),
+ files_touched: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Files modified (will get diff for these)"),
+ },
+ execute: (args, ctx) => execTool("swarm_review", args, ctx),
+});
+
+const swarm_review_feedback = tool({
+ description:
+ "Send review feedback to a worker. Tracks attempts (max 3). Fails task after 3 rejections.",
+ args: {
+ project_key: tool.schema.string().describe("Project path"),
+ task_id: tool.schema.string().describe("Subtask bead ID"),
+ worker_id: tool.schema.string().describe("Worker agent name"),
+ status: tool.schema
+ .enum(["approved", "needs_changes"])
+ .describe("Review status"),
+ summary: tool.schema.string().optional().describe("Review summary"),
+ issues: tool.schema
+ .string()
+ .optional()
+ .describe("JSON array of ReviewIssue objects (for needs_changes)"),
+ },
+ execute: (args, ctx) => execTool("swarm_review_feedback", args, ctx),
+});
+
+// =============================================================================
+// Skills Tools
+// =============================================================================
+
+const skills_list = tool({
+ description:
+ "List all available skills from global, project, and bundled sources",
+ args: {
+ source: tool.schema
+ .enum(["all", "global", "project", "bundled"])
+ .optional()
+ .describe("Filter by source (default: all)"),
+ },
+ execute: (args, ctx) => execTool("skills_list", args, ctx),
+});
+
+const skills_read = tool({
+ description: "Read a skill's full content including SKILL.md and references",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ },
+ execute: (args, ctx) => execTool("skills_read", args, ctx),
+});
+
+const skills_use = tool({
+ description:
+ "Get skill content formatted for injection into agent context. Use this when you need to apply a skill's knowledge to the current task.",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ context: tool.schema
+ .string()
+ .optional()
+ .describe("Optional context about how the skill will be used"),
+ },
+ execute: (args, ctx) => execTool("skills_use", args, ctx),
+});
+
+const skills_create = tool({
+ description: "Create a new skill with SKILL.md template",
+ args: {
+ name: tool.schema.string().describe("Skill name (kebab-case)"),
+ description: tool.schema.string().describe("Brief skill description"),
+ scope: tool.schema
+ .enum(["global", "project"])
+ .optional()
+ .describe("Where to create (default: project)"),
+ tags: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Skill tags for discovery"),
+ },
+ execute: (args, ctx) => execTool("skills_create", args, ctx),
+});
+
+const skills_update = tool({
+ description: "Update an existing skill's SKILL.md content",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ content: tool.schema.string().describe("New SKILL.md content"),
+ },
+ execute: (args, ctx) => execTool("skills_update", args, ctx),
+});
+
+const skills_delete = tool({
+ description: "Delete a skill (project skills only)",
+ args: {
+ name: tool.schema.string().describe("Skill name"),
+ },
+ execute: (args, ctx) => execTool("skills_delete", args, ctx),
+});
+
+const skills_init = tool({
+ description: "Initialize skills directory in current project",
+ args: {
+ path: tool.schema
+ .string()
+ .optional()
+ .describe("Custom path (default: .opencode/skills)"),
+ },
+ execute: (args, ctx) => execTool("skills_init", args, ctx),
+});
+
+const skills_add_script = tool({
+ description: "Add an executable script to a skill",
+ args: {
+ skill_name: tool.schema.string().describe("Skill name"),
+ script_name: tool.schema.string().describe("Script filename"),
+ content: tool.schema.string().describe("Script content"),
+ executable: tool.schema
+ .boolean()
+ .optional()
+ .describe("Make executable (default: true)"),
+ },
+ execute: (args, ctx) => execTool("skills_add_script", args, ctx),
+});
+
+const skills_execute = tool({
+ description: "Execute a skill's script",
+ args: {
+ skill_name: tool.schema.string().describe("Skill name"),
+ script_name: tool.schema.string().describe("Script to execute"),
+ args: tool.schema
+ .array(tool.schema.string())
+ .optional()
+ .describe("Script arguments"),
+ },
+ execute: (args, ctx) => execTool("skills_execute", args, ctx),
+});
+
+// =============================================================================
+// Swarm Insights Tools
+// =============================================================================
+
+const swarm_get_strategy_insights = tool({
+ description: "Get strategy success rates for decomposition planning. Use this when planning task decomposition to see which strategies (file-based, feature-based, risk-based) have historically succeeded or failed. Returns success rates and recommendations based on past swarm outcomes.",
+ args: {
+ task: tool.schema.string().describe("Task description to analyze for strategy recommendation"),
+ },
+ execute: (args, ctx) => execTool("swarm_get_strategy_insights", args, ctx),
+});
+
+const swarm_get_file_insights = tool({
+ description: "Get file-specific gotchas for worker context. Use this when assigning files to workers to warn them about historical failure patterns. Queries past outcomes and semantic memory for file-specific learnings (edge cases, common bugs, performance traps).",
+ args: {
+ files: tool.schema.array(tool.schema.string()).describe("File paths to get insights for"),
+ },
+ execute: (args, ctx) => execTool("swarm_get_file_insights", args, ctx),
+});
+
+const swarm_get_pattern_insights = tool({
+ description: "Get common failure patterns across swarms. Use this during planning or when debugging stuck swarms to see recurring anti-patterns (type errors, timeouts, conflicts, test failures). Returns top 5 most frequent failure patterns with recommendations.",
+ args: {},
+ execute: (args, ctx) => execTool("swarm_get_pattern_insights", args, ctx),
+});
+
+// =============================================================================
+// CASS Tools (Cross-Agent Session Search)
+// =============================================================================
+
+const cass_search = tool({
+ description: "Search across all AI coding agent histories (Claude, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent). Query BEFORE solving problems from scratch - another agent may have already solved it. Returns matching sessions ranked by relevance.",
+ args: {
+ query: tool.schema.string().describe("Search query (e.g., 'authentication error Next.js')"),
+ agent: tool.schema
+ .string()
+ .optional()
+ .describe("Filter by agent name (e.g., 'claude', 'cursor')"),
+ days: tool.schema
+ .number()
+ .optional()
+ .describe("Only search sessions from last N days"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results to return (default: 5)"),
+ fields: tool.schema
+ .string()
+ .optional()
+ .describe("Field selection: 'minimal' for compact output (path, line, agent only)"),
+ },
+ execute: (args, ctx) => execTool("cass_search", args, ctx),
+});
+
+const cass_view = tool({
+ description: "View a specific conversation/session from search results. Use source_path from cass_search output.",
+ args: {
+ path: tool.schema
+ .string()
+ .describe("Path to session file (from cass_search results)"),
+ line: tool.schema
+ .number()
+ .optional()
+ .describe("Jump to specific line number"),
+ },
+ execute: (args, ctx) => execTool("cass_view", args, ctx),
+});
+
+const cass_expand = tool({
+ description: "Expand context around a specific line in a session. Shows messages before/after.",
+ args: {
+ path: tool.schema
+ .string()
+ .describe("Path to session file"),
+ line: tool.schema
+ .number()
+ .describe("Line number to expand around"),
+ context: tool.schema
+ .number()
+ .optional()
+ .describe("Number of lines before/after to show (default: 5)"),
+ },
+ execute: (args, ctx) => execTool("cass_expand", args, ctx),
+});
+
+const cass_health = tool({
+ description: "Check if cass index is healthy. Exit 0 = ready, Exit 1 = needs indexing. Run this before searching.",
+ args: {},
+ execute: (args, ctx) => execTool("cass_health", args, ctx),
+});
+
+const cass_index = tool({
+ description: "Build or rebuild the search index. Run this if health check fails or to pick up new sessions.",
+ args: {
+ full: tool.schema
+ .boolean()
+ .optional()
+ .describe("Force full rebuild (default: incremental)"),
+ },
+ execute: (args, ctx) => execTool("cass_index", args, ctx),
+});
+
+const cass_stats = tool({
+ description: "Show index statistics - how many sessions, messages, agents indexed.",
+ args: {},
+ execute: (args, ctx) => execTool("cass_stats", args, ctx),
+});
+
+// =============================================================================
+// Plugin Export
+// =============================================================================
+
+// =============================================================================
+// Compaction Hook - Swarm Recovery Context
+// =============================================================================
+
+/**
+ * Detection result with confidence level
+ */
+interface SwarmDetection {
+ detected: boolean;
+ confidence: "high" | "medium" | "low" | "none";
+ reasons: string[];
+}
+
+/**
+ * Structured state snapshot for LLM-powered compaction
+ *
+ * This is passed to the lite model to generate a continuation prompt
+ * with concrete data instead of just instructions.
+ */
+interface SwarmStateSnapshot {
+ sessionID: string;
+ detection: {
+ confidence: "high" | "medium" | "low" | "none";
+ reasons: string[];
+ };
+ epic?: {
+ id: string;
+ title: string;
+ status: string;
+ subtasks: Array<{
+ id: string;
+ title: string;
+ status: "open" | "in_progress" | "blocked" | "closed";
+ files: string[];
+ assignedTo?: string;
+ }>;
+ };
+ messages: Array<{
+ from: string;
+ to: string[];
+ subject: string;
+ body: string;
+ timestamp: number;
+ importance?: string;
+ }>;
+ reservations: Array<{
+ agent: string;
+ paths: string[];
+ exclusive: boolean;
+ expiresAt: number;
+ }>;
+}
+
+/**
+ * Query actual swarm state using spawn (like detectSwarm does)
+ *
+ * Returns structured snapshot of current state for LLM compaction.
+ * Shells out to swarm CLI to get real data.
+ */
+async function querySwarmState(sessionID: string): Promise<SwarmStateSnapshot> {
+ const startTime = Date.now();
+
+ logCompaction("debug", "query_swarm_state_start", {
+ session_id: sessionID,
+ project_directory: projectDirectory,
+ });
+
+ try {
+ // Query cells via swarm CLI
+ const cliStart = Date.now();
+ const cellsResult = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+ (resolve) => {
+ const proc = spawn(SWARM_CLI, ["tool", "hive_query"], {
+ cwd: projectDirectory,
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ let stdout = "";
+ let stderr = "";
+ proc.stdout.on("data", (d) => {
+ stdout += d;
+ });
+ proc.stderr.on("data", (d) => {
+ stderr += d;
+ });
+ proc.on("close", (exitCode) =>
+ resolve({ exitCode: exitCode ?? 1, stdout, stderr }),
+ );
+ },
+ );
+ const cliDuration = Date.now() - cliStart;
+
+ logCompaction("debug", "query_swarm_state_cli_complete", {
+ session_id: sessionID,
+ duration_ms: cliDuration,
+ exit_code: cellsResult.exitCode,
+ stdout_length: cellsResult.stdout.length,
+ stderr_length: cellsResult.stderr.length,
+ });
+
+ let cells: any[] = [];
+ if (cellsResult.exitCode === 0) {
+ try {
+ const parsed = JSON.parse(cellsResult.stdout);
+ // Handle wrapped response: { success: true, data: [...] }
+ cells = Array.isArray(parsed) ? parsed : (parsed?.data ?? []);
+ } catch (parseErr) {
+ logCompaction("error", "query_swarm_state_parse_failed", {
+ session_id: sessionID,
+ error: parseErr instanceof Error ? parseErr.message : String(parseErr),
+ stdout_preview: cellsResult.stdout.substring(0, 500),
+ });
+ }
+ }
+
+ logCompaction("debug", "query_swarm_state_cells_parsed", {
+ session_id: sessionID,
+ cell_count: cells.length,
+ cells: cells.map((c: any) => ({
+ id: c.id,
+ title: c.title,
+ type: c.type,
+ status: c.status,
+ parent_id: c.parent_id,
+ })),
+ });
+
+ // Find active epic (first unclosed epic with subtasks)
+ const openEpics = cells.filter(
+ (c: { type?: string; status: string }) =>
+ c.type === "epic" && c.status !== "closed",
+ );
+ const epic = openEpics[0];
+
+ logCompaction("debug", "query_swarm_state_epics", {
+ session_id: sessionID,
+ open_epic_count: openEpics.length,
+ selected_epic: epic ? { id: epic.id, title: epic.title, status: epic.status } : null,
+ });
+
+ // Get subtasks if we have an epic
+ const subtasks =
+ epic && epic.id
+ ? cells.filter(
+ (c: { parent_id?: string }) => c.parent_id === epic.id,
+ )
+ : [];
+
+ logCompaction("debug", "query_swarm_state_subtasks", {
+ session_id: sessionID,
+ subtask_count: subtasks.length,
+ subtasks: subtasks.map((s: any) => ({
+ id: s.id,
+ title: s.title,
+ status: s.status,
+ files: s.files,
+ })),
+ });
+
+ // TODO: Query swarm mail for messages and reservations
+ // For MVP, use empty arrays - the fallback chain handles this
+ const messages: SwarmStateSnapshot["messages"] = [];
+ const reservations: SwarmStateSnapshot["reservations"] = [];
+
+ // Run detection for confidence (already logged internally)
+ const detection = await detectSwarm();
+
+ const snapshot: SwarmStateSnapshot = {
+ sessionID,
+ detection: {
+ confidence: detection.confidence,
+ reasons: detection.reasons,
+ },
+ epic: epic
+ ? {
+ id: epic.id,
+ title: epic.title,
+ status: epic.status,
+ subtasks: subtasks.map((s: {
+ id: string;
+ title: string;
+ status: string;
+ files?: string[];
+ }) => ({
+ id: s.id,
+ title: s.title,
+ status: s.status as "open" | "in_progress" | "blocked" | "closed",
+ files: s.files || [],
+ })),
+ }
+ : undefined,
+ messages,
+ reservations,
+ };
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("debug", "query_swarm_state_complete", {
+ session_id: sessionID,
+ duration_ms: totalDuration,
+ has_epic: !!snapshot.epic,
+ epic_id: snapshot.epic?.id,
+ subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+ message_count: snapshot.messages.length,
+ reservation_count: snapshot.reservations.length,
+ });
+
+ return snapshot;
+ } catch (err) {
+ logCompaction("error", "query_swarm_state_exception", {
+ session_id: sessionID,
+ error: err instanceof Error ? err.message : String(err),
+ stack: err instanceof Error ? err.stack : undefined,
+ duration_ms: Date.now() - startTime,
+ });
+
+ // If query fails, return minimal snapshot
+ const detection = await detectSwarm();
+ return {
+ sessionID,
+ detection: {
+ confidence: detection.confidence,
+ reasons: detection.reasons,
+ },
+ messages: [],
+ reservations: [],
+ };
+ }
+}
+
+/**
+ * Generate compaction prompt using LLM
+ *
+ * Shells out to `opencode run -m <liteModel>` with structured state.
+ * Returns markdown continuation prompt or null on failure.
+ *
+ * Timeout: 30 seconds
+ */
+async function generateCompactionPrompt(
+ snapshot: SwarmStateSnapshot,
+): Promise<string | null> {
+ const startTime = Date.now();
+ const liteModel = process.env.OPENCODE_LITE_MODEL || "anthropic/claude-haiku-4-5";
+
+ logCompaction("debug", "generate_compaction_prompt_start", {
+ session_id: snapshot.sessionID,
+ lite_model: liteModel,
+ has_epic: !!snapshot.epic,
+ epic_id: snapshot.epic?.id,
+ subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+ snapshot_size: JSON.stringify(snapshot).length,
+ });
+
+ try {
+ const promptText = `You are generating a continuation prompt for a compacted swarm coordination session.
+
+Analyze this swarm state and generate a structured markdown prompt that will be given to the resumed session:
+
+${JSON.stringify(snapshot, null, 2)}
+
+Generate a prompt following this structure:
+
+┌─────────────────────────────────────────────────────────────┐
+│ │
+│ 🐝 YOU ARE THE COORDINATOR 🐝 │
+│ │
+│ NOT A WORKER. NOT AN IMPLEMENTER. │
+│ YOU ORCHESTRATE. │
+│ │
+└─────────────────────────────────────────────────────────────┘
+
+# 🐝 Swarm Continuation - [Epic Title or "Unknown"]
+
+**NON-NEGOTIABLE: YOU ARE THE COORDINATOR.** You resumed after context compaction.
+
+## Epic State
+
+**ID:** [epic ID or "Unknown"]
+**Title:** [epic title or "No active epic"]
+**Status:** [X/Y subtasks complete]
+**Project:** ${projectDirectory}
+
+## Subtask Status
+
+### ✅ Completed (N)
+[List completed subtasks with IDs]
+
+### 🚧 In Progress (N)
+[List in-progress subtasks with IDs, files, agents if known]
+
+### 🚫 Blocked (N)
+[List blocked subtasks]
+
+### ⏳ Pending (N)
+[List pending subtasks]
+
+## Next Actions (IMMEDIATE)
+
+[List 3-5 concrete actions with actual commands, using real IDs from the state]
+
+## 🎯 COORDINATOR MANDATES (NON-NEGOTIABLE)
+
+**YOU ARE THE COORDINATOR. NOT A WORKER.**
+
+### ⛔ FORBIDDEN - NEVER do these:
+- ❌ NEVER use \`edit\`, \`write\`, or \`bash\` for implementation - SPAWN A WORKER
+- ❌ NEVER fetch directly with \`repo-crawl_*\`, \`repo-autopsy_*\`, \`webfetch\`, \`fetch_fetch\` - SPAWN A RESEARCHER
+- ❌ NEVER use \`context7_*\` or \`pdf-brain_*\` directly - SPAWN A RESEARCHER
+- ❌ NEVER reserve files - Workers reserve files
+
+### ✅ ALWAYS do these:
+- ✅ ALWAYS check \`swarm_status\` and \`swarmmail_inbox\` first
+- ✅ ALWAYS use \`swarm_spawn_subtask\` for implementation work
+- ✅ ALWAYS use \`swarm_spawn_researcher\` for external data fetching
+- ✅ ALWAYS review worker output with \`swarm_review\` → \`swarm_review_feedback\`
+- ✅ ALWAYS monitor actively - Check messages every ~10 minutes
+- ✅ ALWAYS unblock aggressively - Resolve dependencies immediately
+
+**If you need external data:** Use \`swarm_spawn_researcher\` with a clear research task. The researcher will fetch, summarize, and return findings.
+
+**3-strike rule enforced:** Workers get 3 review attempts. After 3 rejections, escalate to human.
+
+Keep the prompt concise but actionable. Use actual data from the snapshot, not placeholders. Include the ASCII header and ALL coordinator mandates.`;
+
+ logCompaction("debug", "generate_compaction_prompt_calling_llm", {
+ session_id: snapshot.sessionID,
+ prompt_length: promptText.length,
+ model: liteModel,
+ command: `opencode run -m ${liteModel} -- <prompt>`,
+ });
+
+ const llmStart = Date.now();
+ const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+ (resolve, reject) => {
+ const proc = spawn("opencode", ["run", "-m", liteModel, "--", promptText], {
+ cwd: projectDirectory,
+ stdio: ["ignore", "pipe", "pipe"],
+ timeout: 30000, // 30 second timeout
+ });
+
+ let stdout = "";
+ let stderr = "";
+
+ proc.stdout.on("data", (d) => {
+ stdout += d;
+ });
+ proc.stderr.on("data", (d) => {
+ stderr += d;
+ });
+
+ proc.on("close", (exitCode) => {
+ resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+ });
+
+ proc.on("error", (err) => {
+ reject(err);
+ });
+
+ // Timeout handling
+ setTimeout(() => {
+ proc.kill("SIGTERM");
+ reject(new Error("LLM compaction timeout (30s)"));
+ }, 30000);
+ },
+ );
+ const llmDuration = Date.now() - llmStart;
+
+ logCompaction("debug", "generate_compaction_prompt_llm_complete", {
+ session_id: snapshot.sessionID,
+ duration_ms: llmDuration,
+ exit_code: result.exitCode,
+ stdout_length: result.stdout.length,
+ stderr_length: result.stderr.length,
+ stderr_preview: result.stderr.substring(0, 500),
+ stdout_preview: result.stdout.substring(0, 500),
+ });
+
+ if (result.exitCode !== 0) {
+ logCompaction("error", "generate_compaction_prompt_llm_failed", {
+ session_id: snapshot.sessionID,
+ exit_code: result.exitCode,
+ stderr: result.stderr,
+ stdout: result.stdout,
+ duration_ms: llmDuration,
+ });
+ return null;
+ }
+
+ // Extract the prompt from stdout (LLM may wrap in markdown)
+ const prompt = result.stdout.trim();
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("debug", "generate_compaction_prompt_success", {
+ session_id: snapshot.sessionID,
+ total_duration_ms: totalDuration,
+ llm_duration_ms: llmDuration,
+ prompt_length: prompt.length,
+ prompt_preview: prompt.substring(0, 500),
+ prompt_has_content: prompt.length > 0,
+ });
+
+ return prompt.length > 0 ? prompt : null;
+ } catch (err) {
+ const totalDuration = Date.now() - startTime;
+ logCompaction("error", "generate_compaction_prompt_exception", {
+ session_id: snapshot.sessionID,
+ error: err instanceof Error ? err.message : String(err),
+ stack: err instanceof Error ? err.stack : undefined,
+ duration_ms: totalDuration,
+ });
+ return null;
+ }
+}
+
+/**
+ * Session message scan result
+ */
+interface SessionScanResult {
+ messageCount: number;
+ toolCalls: Array<{
+ toolName: string;
+ args: Record<string, unknown>;
+ output?: string;
+ timestamp?: number;
+ }>;
+ swarmDetected: boolean;
+ reasons: string[];
+ /** Projected swarm state from event fold - ground truth from session events */
+ projection?: SwarmProjection;
+}
+
+/**
+ * Scan session messages for swarm tool calls
+ *
+ * Uses SDK client to fetch messages and look for swarm activity.
+ * This can detect swarm work even if no cells exist yet.
+ */
+async function scanSessionMessages(sessionID: string): Promise<SessionScanResult> {
+ const startTime = Date.now();
+ const result: SessionScanResult = {
+ messageCount: 0,
+ toolCalls: [],
+ swarmDetected: false,
+ reasons: [],
+ };
+
+ logCompaction("debug", "session_scan_start", {
+ session_id: sessionID,
+ has_sdk_client: !!sdkClient,
+ });
+
+ if (!sdkClient) {
+ logCompaction("warn", "session_scan_no_sdk_client", {
+ session_id: sessionID,
+ });
+ return result;
+ }
+
+ try {
+ // Fetch session messages
+ const messagesStart = Date.now();
+ const rawResponse = await sdkClient.session.messages({ path: { id: sessionID } });
+ const messagesDuration = Date.now() - messagesStart;
+
+ // Log the RAW response to understand its shape
+ logCompaction("debug", "session_scan_raw_response", {
+ session_id: sessionID,
+ response_type: typeof rawResponse,
+ is_array: Array.isArray(rawResponse),
+ is_null: rawResponse === null,
+ is_undefined: rawResponse === undefined,
+ keys: rawResponse && typeof rawResponse === 'object' ? Object.keys(rawResponse) : [],
+ raw_preview: JSON.stringify(rawResponse)?.slice(0, 500),
+ });
+
+ // The response might be wrapped - check common patterns
+ const messages = Array.isArray(rawResponse)
+ ? rawResponse
+ : rawResponse?.data
+ ? rawResponse.data
+ : rawResponse?.messages
+ ? rawResponse.messages
+ : rawResponse?.items
+ ? rawResponse.items
+ : [];
+
+ result.messageCount = messages?.length ?? 0;
+
+ logCompaction("debug", "session_scan_messages_fetched", {
+ session_id: sessionID,
+ duration_ms: messagesDuration,
+ message_count: result.messageCount,
+ extraction_method: Array.isArray(rawResponse) ? 'direct_array' : rawResponse?.data ? 'data_field' : rawResponse?.messages ? 'messages_field' : rawResponse?.items ? 'items_field' : 'fallback_empty',
+ });
+
+ if (!Array.isArray(messages) || messages.length === 0) {
+ logCompaction("debug", "session_scan_no_messages", {
+ session_id: sessionID,
+ });
+ return result;
+ }
+
+ // Swarm-related tool patterns
+ const swarmTools = [
+ // High confidence - active swarm coordination
+ "hive_create_epic",
+ "swarm_decompose",
+ "swarm_spawn_subtask",
+ "swarm_complete",
+ "swarmmail_init",
+ "swarmmail_reserve",
+ // Medium confidence - swarm activity
+ "hive_start",
+ "hive_close",
+ "swarm_status",
+ "swarm_progress",
+ "swarmmail_send",
+ // Low confidence - possible swarm
+ "hive_create",
+ "hive_query",
+ ];
+
+ const highConfidenceTools = new Set([
+ "hive_create_epic",
+ "swarm_decompose",
+ "swarm_spawn_subtask",
+ "swarmmail_init",
+ "swarmmail_reserve",
+ ]);
+
+ // Scan messages for tool calls
+ let swarmToolCount = 0;
+ let highConfidenceCount = 0;
+
+ // Debug: collect part types to understand message structure
+ const partTypeCounts: Record<string, number> = {};
+ let messagesWithParts = 0;
+ let messagesWithoutParts = 0;
+ let samplePartTypes: string[] = [];
+
+ for (const message of messages) {
+ if (!message.parts || !Array.isArray(message.parts)) {
+ messagesWithoutParts++;
+ continue;
+ }
+ messagesWithParts++;
+
+ for (const part of message.parts) {
+ const partType = part.type || "unknown";
+ partTypeCounts[partType] = (partTypeCounts[partType] || 0) + 1;
+
+ // Collect first 10 unique part types for debugging
+ if (samplePartTypes.length < 10 && !samplePartTypes.includes(partType)) {
+ samplePartTypes.push(partType);
+ }
+
+ // Check if this is a tool call part
+ // OpenCode SDK: ToolPart has type="tool", tool=<string name>, state={...}
+ if (part.type === "tool") {
+ const toolPart = part as ToolPart;
+ const toolName = toolPart.tool; // tool name is a string directly
+
+ if (toolName && swarmTools.includes(toolName)) {
+ swarmToolCount++;
+
+ if (highConfidenceTools.has(toolName)) {
+ highConfidenceCount++;
+ }
+
+ // Extract args/output/timestamp from state if available
+ const state = toolPart.state;
+ const args = state && "input" in state ? state.input : {};
+ const output = state && "output" in state ? state.output : undefined;
+ const timestamp = state && "time" in state && state.time && typeof state.time === "object" && "end" in state.time
+ ? (state.time as { end: number }).end
+ : Date.now();
+
+ result.toolCalls.push({
+ toolName,
+ args,
+ output,
+ timestamp,
+ });
+
+ logCompaction("debug", "session_scan_tool_found", {
+ session_id: sessionID,
+ tool_name: toolName,
+ is_high_confidence: highConfidenceTools.has(toolName),
+ });
+ }
+ }
+ }
+ }
+
+ // =======================================================================
+ // PROJECT SWARM STATE FROM EVENTS (deterministic, no heuristics)
+ // =======================================================================
+ // Convert tool calls to ToolCallEvent format for projection
+ const events: ToolCallEvent[] = result.toolCalls.map(tc => ({
+ tool: tc.toolName,
+ input: tc.args as Record<string, unknown>,
+ output: tc.output || "{}",
+ timestamp: tc.timestamp || Date.now(),
+ }));
+
+ // Project swarm state from events - this is the ground truth
+ const projection = projectSwarmState(events);
+ result.projection = projection;
+
+ // Use projection for swarm detection (deterministic)
+ if (projection.isSwarm) {
+ result.swarmDetected = true;
+ result.reasons.push(`Swarm signature detected: epic ${projection.epic?.id || "unknown"} with ${projection.counts.total} subtasks`);
+
+ if (isSwarmActive(projection)) {
+ result.reasons.push(`Swarm ACTIVE: ${projection.counts.spawned} spawned, ${projection.counts.inProgress} in_progress, ${projection.counts.completed} completed (not closed)`);
+ } else {
+ result.reasons.push(`Swarm COMPLETE: all ${projection.counts.closed} subtasks closed`);
+ }
+ } else if (highConfidenceCount > 0) {
+ // Fallback to heuristic detection if no signature but high-confidence tools found
+ result.swarmDetected = true;
+ result.reasons.push(`${highConfidenceCount} high-confidence swarm tools (${Array.from(new Set(result.toolCalls.filter(tc => highConfidenceTools.has(tc.toolName)).map(tc => tc.toolName))).join(", ")})`);
+ } else if (swarmToolCount > 0) {
+ result.swarmDetected = true;
+ result.reasons.push(`${swarmToolCount} swarm-related tools used`);
+ }
+
+ const totalDuration = Date.now() - startTime;
+
+ // Debug: log part type distribution to understand message structure
+ logCompaction("debug", "session_scan_part_types", {
+ session_id: sessionID,
+ messages_with_parts: messagesWithParts,
+ messages_without_parts: messagesWithoutParts,
+ part_type_counts: partTypeCounts,
+ sample_part_types: samplePartTypes,
+ });
+
+ logCompaction("info", "session_scan_complete", {
+ session_id: sessionID,
+ duration_ms: totalDuration,
+ message_count: result.messageCount,
+ tool_call_count: result.toolCalls.length,
+ swarm_tool_count: swarmToolCount,
+ high_confidence_count: highConfidenceCount,
+ swarm_detected: result.swarmDetected,
+ reasons: result.reasons,
+ unique_tools: Array.from(new Set(result.toolCalls.map(tc => tc.toolName))),
+ // Add projection summary
+ projection_summary: projection.isSwarm ? {
+ epic_id: projection.epic?.id,
+ epic_title: projection.epic?.title,
+ epic_status: projection.epic?.status,
+ is_active: isSwarmActive(projection),
+ counts: projection.counts,
+ } : null,
+ });
+
+ return result;
+ } catch (err) {
+ const totalDuration = Date.now() - startTime;
+ logCompaction("error", "session_scan_exception", {
+ session_id: sessionID,
+ error: err instanceof Error ? err.message : String(err),
+ stack: err instanceof Error ? err.stack : undefined,
+ duration_ms: totalDuration,
+ });
+ return result;
+ }
+}
+
+/**
+ * Check for swarm sign - evidence a swarm passed through
+ *
+ * Uses multiple signals with different confidence levels:
+ * - HIGH: in_progress cells (active work)
+ * - MEDIUM: Open subtasks, unclosed epics, recently updated cells
+ * - LOW: Any cells exist
+ *
+ * Philosophy: Err on the side of continuation.
+ * False positive = extra context (low cost)
+ * False negative = lost swarm (high cost)
+ */
+async function detectSwarm(): Promise<SwarmDetection> {
+ const startTime = Date.now();
+ const reasons: string[] = [];
+ let highConfidence = false;
+ let mediumConfidence = false;
+ let lowConfidence = false;
+
+ logCompaction("debug", "detect_swarm_start", {
+ project_directory: projectDirectory,
+ cwd: process.cwd(),
+ });
+
+ try {
+ const cliStart = Date.now();
+ const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+ (resolve) => {
+ // Use swarm tool to query beads
+ const proc = spawn(SWARM_CLI, ["tool", "hive_query"], {
+ cwd: projectDirectory,
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ let stdout = "";
+ let stderr = "";
+ proc.stdout.on("data", (d) => {
+ stdout += d;
+ });
+ proc.stderr.on("data", (d) => {
+ stderr += d;
+ });
+ proc.on("close", (exitCode) =>
+ resolve({ exitCode: exitCode ?? 1, stdout, stderr }),
+ );
+ },
+ );
+ const cliDuration = Date.now() - cliStart;
+
+ logCompaction("debug", "detect_swarm_cli_complete", {
+ duration_ms: cliDuration,
+ exit_code: result.exitCode,
+ stdout_length: result.stdout.length,
+ stderr_length: result.stderr.length,
+ stderr_preview: result.stderr.substring(0, 200),
+ });
+
+ if (result.exitCode !== 0) {
+ logCompaction("warn", "detect_swarm_cli_failed", {
+ exit_code: result.exitCode,
+ stderr: result.stderr,
+ });
+ return { detected: false, confidence: "none", reasons: ["hive_query failed"] };
+ }
+
+ let cells: any[];
+ try {
+ cells = JSON.parse(result.stdout);
+ } catch (parseErr) {
+ logCompaction("error", "detect_swarm_parse_failed", {
+ error: parseErr instanceof Error ? parseErr.message : String(parseErr),
+ stdout_preview: result.stdout.substring(0, 500),
+ });
+ return { detected: false, confidence: "none", reasons: ["hive_query parse failed"] };
+ }
+
+ if (!Array.isArray(cells) || cells.length === 0) {
+ logCompaction("debug", "detect_swarm_no_cells", {
+ is_array: Array.isArray(cells),
+ length: cells?.length ?? 0,
+ });
+ return { detected: false, confidence: "none", reasons: ["no cells found"] };
+ }
+
+ // Log ALL cells for debugging
+ logCompaction("debug", "detect_swarm_cells_found", {
+ total_cells: cells.length,
+ cells: cells.map((c: any) => ({
+ id: c.id,
+ title: c.title,
+ type: c.type,
+ status: c.status,
+ parent_id: c.parent_id,
+ updated_at: c.updated_at,
+ created_at: c.created_at,
+ })),
+ });
+
+ // HIGH: Any in_progress cells
+ const inProgress = cells.filter(
+ (c: { status: string }) => c.status === "in_progress"
+ );
+ if (inProgress.length > 0) {
+ highConfidence = true;
+ reasons.push(`${inProgress.length} cells in_progress`);
+ logCompaction("debug", "detect_swarm_in_progress", {
+ count: inProgress.length,
+ cells: inProgress.map((c: any) => ({ id: c.id, title: c.title })),
+ });
+ }
+
+ // MEDIUM: Open subtasks (cells with parent_id)
+ const subtasks = cells.filter(
+ (c: { status: string; parent_id?: string }) =>
+ c.status === "open" && c.parent_id
+ );
+ if (subtasks.length > 0) {
+ mediumConfidence = true;
+ reasons.push(`${subtasks.length} open subtasks`);
+ logCompaction("debug", "detect_swarm_open_subtasks", {
+ count: subtasks.length,
+ cells: subtasks.map((c: any) => ({ id: c.id, title: c.title, parent_id: c.parent_id })),
+ });
+ }
+
+ // MEDIUM: Unclosed epics
+ const openEpics = cells.filter(
+ (c: { status: string; type?: string }) =>
+ c.type === "epic" && c.status !== "closed"
+ );
+ if (openEpics.length > 0) {
+ mediumConfidence = true;
+ reasons.push(`${openEpics.length} unclosed epics`);
+ logCompaction("debug", "detect_swarm_open_epics", {
+ count: openEpics.length,
+ cells: openEpics.map((c: any) => ({ id: c.id, title: c.title, status: c.status })),
+ });
+ }
+
+ // MEDIUM: Recently updated cells (last hour)
+ const oneHourAgo = Date.now() - 60 * 60 * 1000;
+ const recentCells = cells.filter(
+ (c: { updated_at?: number }) => c.updated_at && c.updated_at > oneHourAgo
+ );
+ if (recentCells.length > 0) {
+ mediumConfidence = true;
+ reasons.push(`${recentCells.length} cells updated in last hour`);
+ logCompaction("debug", "detect_swarm_recent_cells", {
+ count: recentCells.length,
+ one_hour_ago: oneHourAgo,
+ cells: recentCells.map((c: any) => ({
+ id: c.id,
+ title: c.title,
+ updated_at: c.updated_at,
+ age_minutes: Math.round((Date.now() - c.updated_at) / 60000),
+ })),
+ });
+ }
+
+ // LOW: Any cells exist at all
+ if (cells.length > 0) {
+ lowConfidence = true;
+ reasons.push(`${cells.length} total cells in hive`);
+ }
+ } catch (err) {
+ // Detection failed, use fallback
+ lowConfidence = true;
+ reasons.push("Detection error, using fallback");
+ logCompaction("error", "detect_swarm_exception", {
+ error: err instanceof Error ? err.message : String(err),
+ stack: err instanceof Error ? err.stack : undefined,
+ });
+ }
+
+ // Determine overall confidence
+ let confidence: "high" | "medium" | "low" | "none";
+ if (highConfidence) {
+ confidence = "high";
+ } else if (mediumConfidence) {
+ confidence = "medium";
+ } else if (lowConfidence) {
+ confidence = "low";
+ } else {
+ confidence = "none";
+ }
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("debug", "detect_swarm_complete", {
+ duration_ms: totalDuration,
+ confidence,
+ detected: confidence !== "none",
+ reason_count: reasons.length,
+ reasons,
+ high_confidence: highConfidence,
+ medium_confidence: mediumConfidence,
+ low_confidence: lowConfidence,
+ });
+
+ return {
+ detected: confidence !== "none",
+ confidence,
+ reasons,
+ };
+}
+
+/**
+ * Swarm-aware compaction context
+ *
+ * Injected during compaction to keep the swarm cooking. The coordinator should
+ * wake up from compaction and immediately resume orchestration - spawning agents,
+ * monitoring progress, unblocking work.
+ */
+const SWARM_COMPACTION_CONTEXT = `## 🐝 SWARM ACTIVE - Keep Cooking
+
+You are the **COORDINATOR** of an active swarm. Context was compacted but the swarm is still running.
+
+**YOUR JOB:** Keep orchestrating. Spawn agents. Monitor progress. Unblock work. Ship it.
+
+### Preserve in Summary
+
+Extract from session context:
+
+1. **Epic & Subtasks** - IDs, titles, status, file assignments
+2. **What's Running** - Which agents are active, what they're working on
+3. **What's Blocked** - Blockers and what's needed to unblock
+4. **What's Done** - Completed work and any follow-ups needed
+5. **What's Next** - Pending subtasks ready to spawn
+
+### Summary Format
+
+\`\`\`
+## 🐝 Swarm State
+
+**Epic:** <bd-xxx> - <title>
+**Project:** <path>
+**Progress:** X/Y subtasks complete
+
+**Active:**
+- <bd-xxx>: <title> [in_progress] → <agent> working on <files>
+
+**Blocked:**
+- <bd-xxx>: <title> - BLOCKED: <reason>
+
+**Completed:**
+- <bd-xxx>: <title> ✓
+
+**Ready to Spawn:**
+- <bd-xxx>: <title> (files: <...>)
+\`\`\`
+
+### On Resume - IMMEDIATELY
+
+1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
+2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
+3. \`swarm_review(project_key, epic_id, task_id, files_touched)\` - Review any completed work
+4. \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\` - Approve or request changes
+5. **Spawn ready subtasks** - Don't wait, fire them off
+6. **Unblock blocked work** - Resolve dependencies, reassign if needed
+7. **Collect completed work** - Close done subtasks, verify quality
+
+### Keep the Swarm Cooking
+
+- **Spawn aggressively** - If a subtask is ready and unblocked, spawn an agent
+- **Monitor actively** - Check status, read messages, respond to blockers
+- **Close the loop** - When all subtasks done, verify and close the epic
+- **Don't stop** - The swarm runs until the epic is closed
+
+**You are not waiting for instructions. You are the coordinator. Coordinate.**
+`;
+
+/**
+ * Build dynamic swarm state section from snapshot
+ *
+ * This creates a concrete state summary with actual IDs and status
+ * to prepend to the static compaction context.
+ */
+function buildDynamicStateFromSnapshot(snapshot: SwarmStateSnapshot): string {
+ if (!snapshot.epic) {
+ return "";
+ }
+
+ const parts: string[] = [];
+
+ // Header with epic info
+ parts.push(`## 🐝 Current Swarm State\n`);
+ parts.push(`**Epic:** ${snapshot.epic.id} - ${snapshot.epic.title}`);
+ parts.push(`**Status:** ${snapshot.epic.status}`);
+ parts.push(`**Project:** ${projectDirectory}\n`);
+
+ // Subtask breakdown
+ const subtasks = snapshot.epic.subtasks || [];
+ const completed = subtasks.filter(s => s.status === "closed");
+ const inProgress = subtasks.filter(s => s.status === "in_progress");
+ const blocked = subtasks.filter(s => s.status === "blocked");
+ const pending = subtasks.filter(s => s.status === "open");
+
+ parts.push(`**Progress:** ${completed.length}/${subtasks.length} subtasks complete\n`);
+
+ // Immediate actions with real IDs
+ parts.push(`## 1️⃣ IMMEDIATE ACTIONS (Do These FIRST)\n`);
+ parts.push(`1. \`swarm_status(epic_id="${snapshot.epic.id}", project_key="${projectDirectory}")\` - Get current state`);
+ parts.push(`2. \`swarmmail_inbox(limit=5)\` - Check for worker messages`);
+
+ if (inProgress.length > 0) {
+ parts.push(`3. Review in-progress work when workers complete`);
+ }
+ if (pending.length > 0) {
+ const next = pending[0];
+ parts.push(`4. Spawn next subtask: \`swarm_spawn_subtask(bead_id="${next.id}", ...)\``);
+ }
+ if (blocked.length > 0) {
+ parts.push(`5. Unblock: ${blocked.map(s => s.id).join(", ")}`);
+ }
+ parts.push("");
+
+ // Detailed subtask status
+ if (inProgress.length > 0) {
+ parts.push(`### 🚧 In Progress (${inProgress.length})`);
+ for (const s of inProgress) {
+ const files = s.files?.length ? ` (${s.files.slice(0, 3).join(", ")}${s.files.length > 3 ? "..." : ""})` : "";
+ parts.push(`- ${s.id}: ${s.title}${files}`);
+ }
+ parts.push("");
+ }
+
+ if (blocked.length > 0) {
+ parts.push(`### 🚫 Blocked (${blocked.length})`);
+ for (const s of blocked) {
+ parts.push(`- ${s.id}: ${s.title}`);
+ }
+ parts.push("");
+ }
+
+ if (pending.length > 0) {
+ parts.push(`### ⏳ Ready to Spawn (${pending.length})`);
+ for (const s of pending.slice(0, 5)) { // Show first 5
+ const files = s.files?.length ? ` (${s.files.slice(0, 2).join(", ")}${s.files.length > 2 ? "..." : ""})` : "";
+ parts.push(`- ${s.id}: ${s.title}${files}`);
+ }
+ if (pending.length > 5) {
+ parts.push(`- ... and ${pending.length - 5} more`);
+ }
+ parts.push("");
+ }
+
+ if (completed.length > 0) {
+ parts.push(`### ✅ Completed (${completed.length})`);
+ for (const s of completed.slice(-3)) { // Show last 3
+ parts.push(`- ${s.id}: ${s.title} ✓`);
+ }
+ if (completed.length > 3) {
+ parts.push(`- ... and ${completed.length - 3} more`);
+ }
+ parts.push("");
+ }
+
+ parts.push("---\n");
+
+ return parts.join("\n");
+}
+
+/**
+ * Fallback detection prompt - tells the compactor what to look for
+ *
+ * Used when we can't definitively detect a swarm but want to be safe.
+ * The compactor can check the conversation context for these patterns.
+ */
+const SWARM_DETECTION_FALLBACK = `## 🐝 Swarm Detection - Check Your Context
+
+**IMPORTANT:** Before summarizing, check if this session involves an active swarm.
+
+Look for ANY of these patterns in the conversation:
+
+### Tool Calls (definite swarm sign)
+- \`swarm_decompose\`, \`swarm_spawn_subtask\`, \`swarm_status\`, \`swarm_complete\`
+- \`swarmmail_init\`, \`swarmmail_reserve\`, \`swarmmail_send\`
+- \`hive_create_epic\`, \`hive_start\`, \`hive_close\`
+
+### IDs and Names
+- Cell IDs: \`bd-xxx\`, \`bd-xxx.N\` (subtask format)
+- Agent names: BlueLake, RedMountain, GreenValley, etc.
+- Epic references: "epic", "subtask", "parent"
+
+### Coordination Language
+- "spawn", "worker", "coordinator"
+- "reserve", "reservation", "files"
+- "blocked", "unblock", "dependency"
+- "progress", "complete", "in_progress"
+
+### If You Find Swarm Evidence
+
+Include this in your summary:
+1. Epic ID and title
+2. Project path
+3. Subtask status (running/blocked/done/pending)
+4. Any blockers or issues
+5. What should happen next
+
+**Then tell the resumed session:**
+"This is an active swarm. Check swarm_status and swarmmail_inbox immediately."
+`;
+
+// Extended hooks type to include experimental compaction hook with new prompt API
+type CompactionOutput = {
+ context: string[];
+ prompt?: string; // NEW API from OpenCode PR #5907
+};
+
+type ExtendedHooks = Hooks & {
+ "experimental.session.compacting"?: (
+ input: { sessionID: string },
+ output: CompactionOutput,
+ ) => Promise<void>;
+};
+
+// NOTE: Only default export - named exports cause double registration!
+// OpenCode's plugin loader calls ALL exports as functions.
+const SwarmPlugin: Plugin = async (
+ input: PluginInput,
+): Promise<ExtendedHooks> => {
+ // CRITICAL: Set project directory from OpenCode input
+ // Without this, CLI uses wrong database path
+ projectDirectory = input.directory;
+
+ // Store SDK client for session message scanning during compaction
+ sdkClient = input.client;
+
+ return {
+ tool: {
+ // Beads
+ hive_create,
+ hive_create_epic,
+ hive_query,
+ hive_update,
+ hive_close,
+ hive_start,
+ hive_ready,
+ hive_cells,
+ hive_sync,
+ beads_link_thread,
+ // Swarm Mail (Embedded)
+ swarmmail_init,
+ swarmmail_send,
+ swarmmail_inbox,
+ swarmmail_read_message,
+ swarmmail_reserve,
+ swarmmail_release,
+ swarmmail_ack,
+ swarmmail_health,
+ // Structured
+ structured_extract_json,
+ structured_validate,
+ structured_parse_evaluation,
+ structured_parse_decomposition,
+ structured_parse_cell_tree,
+ // Swarm
+ swarm_init,
+ swarm_select_strategy,
+ swarm_plan_prompt,
+ swarm_decompose,
+ swarm_validate_decomposition,
+ swarm_status,
+ swarm_progress,
+ swarm_complete,
+ swarm_record_outcome,
+ swarm_subtask_prompt,
+ swarm_spawn_subtask,
+ swarm_complete_subtask,
+ swarm_evaluation_prompt,
+ swarm_broadcast,
+ // Worktree Isolation
+ swarm_worktree_create,
+ swarm_worktree_merge,
+ swarm_worktree_cleanup,
+ swarm_worktree_list,
+ // Structured Review
+ swarm_review,
+ swarm_review_feedback,
+ // Skills
+ skills_list,
+ skills_read,
+ skills_use,
+ skills_create,
+ skills_update,
+ skills_delete,
+ skills_init,
+ skills_add_script,
+ skills_execute,
+ // Swarm Insights
+ swarm_get_strategy_insights,
+ swarm_get_file_insights,
+ swarm_get_pattern_insights,
+ // CASS (Cross-Agent Session Search)
+ cass_search,
+ cass_view,
+ cass_expand,
+ cass_health,
+ cass_index,
+ cass_stats,
+ },
+
+ // Swarm-aware compaction hook with LLM-powered continuation prompts
+ // Three-level fallback chain: LLM → static context → detection fallback → none
+ "experimental.session.compacting": async (
+ input: { sessionID: string },
+ output: CompactionOutput,
+ ) => {
+ const startTime = Date.now();
+
+ // =======================================================================
+ // LOG: Compaction hook invoked - capture EVERYTHING we receive
+ // =======================================================================
+ logCompaction("info", "compaction_hook_invoked", {
+ session_id: input.sessionID,
+ project_directory: projectDirectory,
+ input_keys: Object.keys(input),
+ input_full: JSON.parse(JSON.stringify(input)), // Deep clone for logging
+ output_keys: Object.keys(output),
+ output_context_count: output.context?.length ?? 0,
+ output_has_prompt_field: "prompt" in output,
+ output_initial_state: {
+ context: output.context,
+ prompt: (output as any).prompt,
+ },
+ env: {
+ OPENCODE_SESSION_ID: process.env.OPENCODE_SESSION_ID,
+ OPENCODE_MESSAGE_ID: process.env.OPENCODE_MESSAGE_ID,
+ OPENCODE_AGENT: process.env.OPENCODE_AGENT,
+ OPENCODE_LITE_MODEL: process.env.OPENCODE_LITE_MODEL,
+ SWARM_PROJECT_DIR: process.env.SWARM_PROJECT_DIR,
+ },
+ cwd: process.cwd(),
+ timestamp: new Date().toISOString(),
+ });
+
+ // =======================================================================
+ // STEP 1: Scan session messages for swarm tool calls
+ // =======================================================================
+ const sessionScanStart = Date.now();
+ const sessionScan = await scanSessionMessages(input.sessionID);
+ const sessionScanDuration = Date.now() - sessionScanStart;
+
+ logCompaction("info", "session_scan_results", {
+ session_id: input.sessionID,
+ duration_ms: sessionScanDuration,
+ message_count: sessionScan.messageCount,
+ tool_call_count: sessionScan.toolCalls.length,
+ swarm_detected_from_messages: sessionScan.swarmDetected,
+ reasons: sessionScan.reasons,
+ });
+
+ // =======================================================================
+ // STEP 2: Detect swarm state from hive cells
+ // =======================================================================
+ const detectionStart = Date.now();
+ const detection = await detectSwarm();
+ const detectionDuration = Date.now() - detectionStart;
+
+ logCompaction("info", "swarm_detection_complete", {
+ session_id: input.sessionID,
+ duration_ms: detectionDuration,
+ detected: detection.detected,
+ confidence: detection.confidence,
+ reasons: detection.reasons,
+ reason_count: detection.reasons.length,
+ });
+
+ // =======================================================================
+ // STEP 3: Merge session scan with hive detection for final confidence
+ // =======================================================================
+ // If session messages show high-confidence swarm tools, boost confidence
+ if (sessionScan.swarmDetected && sessionScan.reasons.some(r => r.includes("high-confidence"))) {
+ if (detection.confidence === "none" || detection.confidence === "low") {
+ detection.confidence = "high";
+ detection.detected = true;
+ detection.reasons.push(...sessionScan.reasons);
+
+ logCompaction("info", "confidence_boost_from_session_scan", {
+ session_id: input.sessionID,
+ original_confidence: detection.confidence,
+ boosted_to: "high",
+ session_reasons: sessionScan.reasons,
+ });
+ }
+ } else if (sessionScan.swarmDetected) {
+ // Medium boost for any swarm tools found
+ if (detection.confidence === "none") {
+ detection.confidence = "medium";
+ detection.detected = true;
+ detection.reasons.push(...sessionScan.reasons);
+
+ logCompaction("info", "confidence_boost_from_session_scan", {
+ session_id: input.sessionID,
+ original_confidence: "none",
+ boosted_to: "medium",
+ session_reasons: sessionScan.reasons,
+ });
+ } else if (detection.confidence === "low") {
+ detection.confidence = "medium";
+ detection.reasons.push(...sessionScan.reasons);
+
+ logCompaction("info", "confidence_boost_from_session_scan", {
+ session_id: input.sessionID,
+ original_confidence: "low",
+ boosted_to: "medium",
+ session_reasons: sessionScan.reasons,
+ });
+ }
+ }
+
+ logCompaction("info", "final_swarm_detection", {
+ session_id: input.sessionID,
+ confidence: detection.confidence,
+ detected: detection.detected,
+ combined_reasons: detection.reasons,
+ message_scan_contributed: sessionScan.swarmDetected,
+ });
+
+ if (detection.confidence === "high" || detection.confidence === "medium") {
+ // Definite or probable swarm - try LLM-powered compaction
+ logCompaction("info", "swarm_detected_attempting_llm", {
+ session_id: input.sessionID,
+ confidence: detection.confidence,
+ reasons: detection.reasons,
+ has_projection: !!sessionScan.projection?.isSwarm,
+ });
+
+ // Hoist snapshot outside try block so it's available in fallback path
+ let snapshot: SwarmStateSnapshot | undefined;
+
+ try {
+ // =======================================================================
+ // PREFER PROJECTION (ground truth from events) OVER HIVE QUERY
+ // =======================================================================
+ // The projection is derived from session events - it's the source of truth.
+ // Hive query may show all cells closed even if swarm was active.
+
+ if (sessionScan.projection?.isSwarm) {
+ // Use projection as primary source - convert to snapshot format
+ const proj = sessionScan.projection;
+ snapshot = {
+ sessionID: input.sessionID,
+ detection: {
+ confidence: isSwarmActive(proj) ? "high" : "medium",
+ reasons: sessionScan.reasons,
+ },
+ epic: proj.epic ? {
+ id: proj.epic.id,
+ title: proj.epic.title,
+ status: proj.epic.status,
+ subtasks: Array.from(proj.subtasks.values()).map(s => ({
+ id: s.id,
+ title: s.title,
+ status: s.status as "open" | "in_progress" | "blocked" | "closed",
+ files: s.files,
+ })),
+ } : undefined,
+ messages: [],
+ reservations: [],
+ };
+
+ logCompaction("info", "using_projection_as_snapshot", {
+ session_id: input.sessionID,
+ epic_id: proj.epic?.id,
+ epic_title: proj.epic?.title,
+ subtask_count: proj.subtasks.size,
+ is_active: isSwarmActive(proj),
+ counts: proj.counts,
+ });
+ } else {
+ // Fallback to hive query (may be stale)
+ const queryStart = Date.now();
+ snapshot = await querySwarmState(input.sessionID);
+ const queryDuration = Date.now() - queryStart;
+
+ logCompaction("info", "fallback_to_hive_query", {
+ session_id: input.sessionID,
+ duration_ms: queryDuration,
+ reason: "no projection available or not a swarm",
+ });
+ }
+
+ logCompaction("info", "swarm_state_resolved", {
+ session_id: input.sessionID,
+ source: sessionScan.projection?.isSwarm ? "projection" : "hive_query",
+ has_epic: !!snapshot.epic,
+ epic_id: snapshot.epic?.id,
+ epic_title: snapshot.epic?.title,
+ epic_status: snapshot.epic?.status,
+ subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+ subtasks: snapshot.epic?.subtasks?.map(s => ({
+ id: s.id,
+ title: s.title,
+ status: s.status,
+ file_count: s.files?.length ?? 0,
+ })),
+ message_count: snapshot.messages?.length ?? 0,
+ reservation_count: snapshot.reservations?.length ?? 0,
+ detection_confidence: snapshot.detection.confidence,
+ detection_reasons: snapshot.detection.reasons,
+ });
+
+ // =======================================================================
+ // CAPTURE POINT 1: Detection complete - record confidence and reasons
+ // =======================================================================
+ await captureCompaction(
+ input.sessionID,
+ snapshot.epic?.id || "unknown",
+ "detection_complete",
+ {
+ confidence: snapshot.detection.confidence,
+ detected: detection.detected,
+ reasons: snapshot.detection.reasons,
+ session_scan_contributed: sessionScan.swarmDetected,
+ session_scan_reasons: sessionScan.reasons,
+ epic_id: snapshot.epic?.id,
+ epic_title: snapshot.epic?.title,
+ subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+ },
+ );
+
+ // Level 2: Generate prompt with LLM
+ const llmStart = Date.now();
+ const llmPrompt = await generateCompactionPrompt(snapshot);
+ const llmDuration = Date.now() - llmStart;
+
+ logCompaction("info", "llm_generation_complete", {
+ session_id: input.sessionID,
+ duration_ms: llmDuration,
+ success: !!llmPrompt,
+ prompt_length: llmPrompt?.length ?? 0,
+ prompt_preview: llmPrompt?.substring(0, 500),
+ });
+
+ // =======================================================================
+ // CAPTURE POINT 2: Prompt generated - record FULL prompt content
+ // =======================================================================
+ if (llmPrompt) {
+ await captureCompaction(
+ input.sessionID,
+ snapshot.epic?.id || "unknown",
+ "prompt_generated",
+ {
+ prompt_length: llmPrompt.length,
+ full_prompt: llmPrompt, // FULL content, not truncated
+ context_type: "llm_generated",
+ duration_ms: llmDuration,
+ },
+ );
+ }
+
+ if (llmPrompt) {
+ // SUCCESS: Use LLM-generated prompt
+ const header = `[Swarm compaction: LLM-generated, ${detection.reasons.join(", ")}]\n\n`;
+ const fullContent = header + llmPrompt;
+
+ // Progressive enhancement: use new API if available
+ if ("prompt" in output) {
+ output.prompt = fullContent;
+ logCompaction("info", "context_injected_via_prompt_api", {
+ session_id: input.sessionID,
+ content_length: fullContent.length,
+ method: "output.prompt",
+ });
+ } else {
+ output.context.push(fullContent);
+ logCompaction("info", "context_injected_via_context_array", {
+ session_id: input.sessionID,
+ content_length: fullContent.length,
+ method: "output.context.push",
+ context_count_after: output.context.length,
+ });
+ }
+
+ // =======================================================================
+ // CAPTURE POINT 3a: Context injected (LLM path) - record FULL content
+ // =======================================================================
+ await captureCompaction(
+ input.sessionID,
+ snapshot.epic?.id || "unknown",
+ "context_injected",
+ {
+ full_content: fullContent, // FULL content, not truncated
+ content_length: fullContent.length,
+ injection_method: "prompt" in output ? "output.prompt" : "output.context.push",
+ context_type: "llm_generated",
+ },
+ );
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("info", "compaction_complete_llm_success", {
+ session_id: input.sessionID,
+ total_duration_ms: totalDuration,
+ detection_duration_ms: detectionDuration,
+ query_duration_ms: queryDuration,
+ llm_duration_ms: llmDuration,
+ confidence: detection.confidence,
+ context_type: "llm_generated",
+ content_length: fullContent.length,
+ });
+ return;
+ }
+
+ // LLM failed, fall through to static prompt
+ logCompaction("warn", "llm_generation_returned_null", {
+ session_id: input.sessionID,
+ llm_duration_ms: llmDuration,
+ falling_back_to: "static_prompt",
+ });
+ } catch (err) {
+ // LLM failed, fall through to static prompt
+ logCompaction("error", "llm_generation_failed", {
+ session_id: input.sessionID,
+ error: err instanceof Error ? err.message : String(err),
+ error_stack: err instanceof Error ? err.stack : undefined,
+ falling_back_to: "static_prompt",
+ });
+ }
+
+ // Level 3: Fall back to static context WITH dynamic state from snapshot
+ const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
+
+ // Build dynamic state section if we have snapshot data
+ const dynamicState = snapshot ? buildDynamicStateFromSnapshot(snapshot) : "";
+ const staticContent = header + dynamicState + SWARM_COMPACTION_CONTEXT;
+ output.context.push(staticContent);
+
+ // =======================================================================
+ // CAPTURE POINT 3b: Context injected (static fallback) - record FULL content
+ // =======================================================================
+ await captureCompaction(
+ input.sessionID,
+ snapshot?.epic?.id || "unknown",
+ "context_injected",
+ {
+ full_content: staticContent,
+ content_length: staticContent.length,
+ injection_method: "output.context.push",
+ context_type: "static_with_dynamic_state",
+ has_dynamic_state: !!dynamicState,
+ epic_id: snapshot?.epic?.id,
+ subtask_count: snapshot?.epic?.subtasks?.length ?? 0,
+ },
+ );
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("info", "compaction_complete_static_fallback", {
+ session_id: input.sessionID,
+ total_duration_ms: totalDuration,
+ confidence: detection.confidence,
+ context_type: dynamicState ? "static_with_dynamic_state" : "static_swarm_context",
+ content_length: staticContent.length,
+ context_count_after: output.context.length,
+ has_dynamic_state: !!dynamicState,
+ epic_id: snapshot?.epic?.id,
+ subtask_count: snapshot?.epic?.subtasks?.length ?? 0,
+ });
+ } else if (detection.confidence === "low") {
+ // Level 4: Possible swarm - inject fallback detection prompt
+ const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
+ const fallbackContent = header + SWARM_DETECTION_FALLBACK;
+ output.context.push(fallbackContent);
+
+ // =======================================================================
+ // CAPTURE POINT 3c: Context injected (detection fallback) - record FULL content
+ // =======================================================================
+ await captureCompaction(
+ input.sessionID,
+ "unknown", // No snapshot for low confidence
+ "context_injected",
+ {
+ full_content: fallbackContent,
+ content_length: fallbackContent.length,
+ injection_method: "output.context.push",
+ context_type: "detection_fallback",
+ },
+ );
+
+ const totalDuration = Date.now() - startTime;
+ logCompaction("info", "compaction_complete_detection_fallback", {
+ session_id: input.sessionID,
+ total_duration_ms: totalDuration,
+ confidence: detection.confidence,
+ context_type: "detection_fallback",
+ content_length: fallbackContent.length,
+ context_count_after: output.context.length,
+ reasons: detection.reasons,
+ });
+ } else {
+ // Level 5: confidence === "none" - no injection, probably not a swarm
+ const totalDuration = Date.now() - startTime;
+ logCompaction("info", "compaction_complete_no_swarm", {
+ session_id: input.sessionID,
+ total_duration_ms: totalDuration,
+ confidence: detection.confidence,
+ context_type: "none",
+ reasons: detection.reasons,
+ context_count_unchanged: output.context.length,
+ });
+ }
+
+ // =======================================================================
+ // LOG: Final output state
+ // =======================================================================
+ logCompaction("debug", "compaction_hook_complete_final_state", {
+ session_id: input.sessionID,
+ output_context_count: output.context?.length ?? 0,
+ output_context_lengths: output.context?.map(c => c.length) ?? [],
+ output_has_prompt: !!(output as any).prompt,
+ output_prompt_length: (output as any).prompt?.length ?? 0,
+ total_duration_ms: Date.now() - startTime,
+ });
+ },
+ };
+};
+
+export default SwarmPlugin;
diff --git a/tool/bd-quick.ts b/tool/bd-quick.ts
index f19a983..fc9c4e2 100644
--- a/tool/bd-quick.ts
+++ b/tool/bd-quick.ts
@@ -1,37 +1,67 @@
-import { tool } from "@opencode-ai/plugin"
+import { execSync } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
/**
- * Quick beads operations - skip the verbose JSON parsing
+ * Quick bead operations - uses bd CLI
+ *
+ * These tools wrap the bd CLI for quick bead operations.
+ * The bd CLI must be installed and available in PATH.
*/
+function runBd(args: string): string {
+ try {
+ return execSync(`bd ${args}`, {
+ encoding: "utf-8",
+ stdio: ["pipe", "pipe", "pipe"],
+ }).trim();
+ } catch (e) {
+ if (e instanceof Error && "stderr" in e) {
+ throw new Error((e as { stderr: string }).stderr || e.message);
+ }
+ throw e;
+ }
+}
+
export const ready = tool({
description: "Get the next ready bead (unblocked, highest priority)",
args: {},
async execute() {
- const result = await Bun.$`bd ready --json | jq -r '.[0] | "\(.id): \(.title) (p\(.priority))"'`.text()
- return result.trim() || "No ready beads"
+ try {
+ const result = runBd("ready");
+ return result || "No ready beads";
+ } catch {
+ return "No ready beads";
+ }
},
-})
+});
export const wip = tool({
description: "List in-progress beads",
args: {},
async execute() {
- const result = await Bun.$`bd list --status in_progress --json | jq -r '.[] | "\(.id): \(.title)"'`.text()
- return result.trim() || "Nothing in progress"
+ try {
+ const result = runBd("wip");
+ return result || "Nothing in progress";
+ } catch {
+ return "Nothing in progress";
+ }
},
-})
+});
export const start = tool({
description: "Mark a bead as in-progress",
args: {
- id: tool.schema.string().describe("Bead ID (e.g., bd-a1b2)"),
+ id: tool.schema.string().describe("Bead ID (e.g., bd-a1b2c)"),
},
async execute({ id }) {
- await Bun.$`bd update ${id} --status in_progress --json`
- return `Started: ${id}`
+ try {
+ runBd(`start ${id}`);
+ return `Started: ${id}`;
+ } catch (e) {
+ return `Failed to start ${id}: ${e instanceof Error ? e.message : "unknown error"}`;
+ }
},
-})
+});
export const done = tool({
description: "Close a bead with reason",
@@ -40,30 +70,64 @@ export const done = tool({
reason: tool.schema.string().describe("Completion reason"),
},
async execute({ id, reason }) {
- await Bun.$`bd close ${id} --reason ${reason} --json`
- return `Closed: ${id}`
+ try {
+ // Escape quotes in reason
+ const escapedReason = reason.replace(/"/g, '\\"');
+ runBd(`done ${id} "${escapedReason}"`);
+ return `Closed ${id}: ${reason}`;
+ } catch (e) {
+ return `Failed to close ${id}: ${e instanceof Error ? e.message : "unknown error"}`;
+ }
},
-})
+});
export const create = tool({
description: "Create a new bead quickly",
args: {
title: tool.schema.string().describe("Bead title"),
- type: tool.schema.enum(["bug", "feature", "task", "epic", "chore"]).optional().describe("Issue type (default: task)"),
- priority: tool.schema.number().min(0).max(3).optional().describe("Priority 0-3 (default: 2)"),
+ type: tool.schema
+ .enum(["bug", "feature", "task", "epic", "chore"])
+ .optional()
+ .describe("Issue type (default: task)"),
+ priority: tool.schema
+ .number()
+ .min(0)
+ .max(3)
+ .optional()
+ .describe("Priority 0-3 (default: 2)"),
},
async execute({ title, type = "task", priority = 2 }) {
- const result = await Bun.$`bd create ${title} -t ${type} -p ${priority} --json | jq -r '.id'`.text()
- return `Created: ${result.trim()}`
+ try {
+ const escapedTitle = title.replace(/"/g, '\\"');
+ const result = runBd(
+ `create -t ${type} -p ${priority} "${escapedTitle}"`,
+ );
+ // Extract ID from output
+ const match = result.match(/bd-[a-z0-9]+/);
+ return match ? `Created: ${match[0]}` : `Created bead`;
+ } catch (e) {
+ return `Failed to create bead: ${e instanceof Error ? e.message : "unknown error"}`;
+ }
},
-})
+});
export const sync = tool({
description: "Sync beads to git and push",
args: {},
async execute() {
- await Bun.$`bd sync`
- await Bun.$`git push`
- return "Beads synced and pushed"
+ try {
+ runBd("sync");
+ } catch {
+ // Ignore sync failures
+ }
+
+ // Push to remote
+ try {
+ execSync("git push", { stdio: "ignore" });
+ } catch {
+ // Ignore push failures (might be offline, no remote, etc.)
+ }
+
+ return "Beads synced and pushed";
},
-})
+});
diff --git a/tool/cass.ts b/tool/cass.ts
new file mode 100644
index 0000000..250d203
--- /dev/null
+++ b/tool/cass.ts
@@ -0,0 +1,196 @@
+import { tool } from "@opencode-ai/plugin";
+import { $ } from "bun";
+import { statSync } from "fs";
+
+/**
+ * CASS - Coding Agent Session Search
+ *
+ * Unified search across all your AI coding agent histories:
+ * Claude Code, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent
+ *
+ * ALWAYS use --robot or --json flags - never launch bare cass (it opens TUI)
+ */
+
+const CASS_BIN = `${process.env.HOME}/.local/bin/cass`;
+
+async function runCass(args: string[], signal?: AbortSignal): Promise<string> {
+ try {
+ // Create AbortController for the shell command
+ const controller = new AbortController();
+ signal?.addEventListener("abort", () => controller.abort());
+
+ const result = await $`${CASS_BIN} ${args}`.text();
+ return result.trim();
+ } catch (e: any) {
+ // Handle abort
+ if (signal?.aborted) {
+ return "Operation cancelled";
+ }
+ // cass outputs errors to stderr but may still have useful stdout
+ const stderr = e.stderr?.toString() || "";
+ const stdout = e.stdout?.toString() || "";
+ if (stdout) return stdout.trim();
+ return `Error: ${stderr || e.message || e}`;
+ }
+}
+
+export const search = tool({
+ description:
+ "Search across all AI coding agent histories (Claude, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode). Query BEFORE solving problems from scratch - another agent may have already solved it.",
+ args: {
+ query: tool.schema.string().describe("Natural language search query"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 10)"),
+ agent: tool.schema
+ .string()
+ .optional()
+ .describe(
+ "Filter by agent: claude, codex, cursor, gemini, aider, chatgpt, cline, opencode, amp",
+ ),
+ days: tool.schema.number().optional().describe("Limit to last N days"),
+ fields: tool.schema
+ .string()
+ .optional()
+ .describe(
+ "Field selection: 'minimal' (path,line,agent), 'summary' (adds title,score), or comma-separated list",
+ ),
+ },
+ async execute({ query, limit, agent, days, fields }, ctx) {
+ const args = ["search", query, "--robot"];
+ if (limit) args.push("--limit", String(limit));
+ if (agent) args.push("--agent", agent);
+ if (days) args.push("--days", String(days));
+ if (fields) args.push("--fields", fields);
+
+ const output = await runCass(args, ctx?.abort);
+
+ // Parse and sort results by mtime (newest first)
+ try {
+ const lines = output.split("\n").filter((l) => l.trim());
+
+ // Try to parse as JSON lines
+ const results = lines
+ .map((line) => {
+ try {
+ return JSON.parse(line);
+ } catch {
+ return null;
+ }
+ })
+ .filter((r) => r !== null);
+
+ // If we have parseable JSON results, sort by mtime
+ if (results.length > 0) {
+ results.sort((a, b) => {
+ // Try mtime field first
+ const mtimeA = a.mtime || a.modified || 0;
+ const mtimeB = b.mtime || b.modified || 0;
+
+ if (mtimeA && mtimeB) {
+ return mtimeB - mtimeA;
+ }
+
+ // Fallback: get mtime from file path
+ if (a.path && b.path) {
+ try {
+ const statA = statSync(a.path);
+ const statB = statSync(b.path);
+ return statB.mtimeMs - statA.mtimeMs;
+ } catch {
+ // If stat fails, maintain original order
+ return 0;
+ }
+ }
+
+ return 0;
+ });
+
+ // Return sorted results as JSON lines
+ return results.map((r) => JSON.stringify(r)).join("\n");
+ }
+ } catch {
+ // If parsing fails, return original output
+ }
+
+ return output;
+ },
+});
+
+export const health = tool({
+ description:
+ "Check if cass index is healthy. Exit 0 = ready, Exit 1 = needs indexing. Run this before searching.",
+ args: {},
+ async execute(_args, ctx) {
+ return runCass(["health", "--json"], ctx?.abort);
+ },
+});
+
+export const index = tool({
+ description:
+ "Build or rebuild the search index. Run this if health check fails or to pick up new sessions.",
+ args: {
+ full: tool.schema
+ .boolean()
+ .optional()
+ .describe("Force full rebuild (slower but thorough)"),
+ },
+ async execute({ full }, ctx) {
+ const args = ["index", "--json"];
+ if (full) args.push("--full");
+ return runCass(args, ctx?.abort);
+ },
+});
+
+export const view = tool({
+ description:
+ "View a specific conversation/session from search results. Use source_path from search output.",
+ args: {
+ path: tool.schema
+ .string()
+ .describe("Path to session file (from search results)"),
+ line: tool.schema.number().optional().describe("Line number to focus on"),
+ },
+ async execute({ path, line }, ctx) {
+ const args = ["view", path, "--json"];
+ if (line) args.push("-n", String(line));
+ return runCass(args, ctx?.abort);
+ },
+});
+
+export const expand = tool({
+ description:
+ "Expand context around a specific line in a session. Shows messages before/after.",
+ args: {
+ path: tool.schema.string().describe("Path to session file"),
+ line: tool.schema.number().describe("Line number to expand around"),
+ context: tool.schema
+ .number()
+ .optional()
+ .describe("Number of messages before/after (default: 3)"),
+ },
+ async execute({ path, line, context }, ctx) {
+ const args = ["expand", path, "-n", String(line), "--json"];
+ if (context) args.push("-C", String(context));
+ return runCass(args, ctx?.abort);
+ },
+});
+
+export const stats = tool({
+ description:
+ "Show index statistics - how many sessions, messages, agents indexed.",
+ args: {},
+ async execute(_args, ctx) {
+ return runCass(["stats", "--json"], ctx?.abort);
+ },
+});
+
+export const capabilities = tool({
+ description:
+ "Discover cass features, supported agents, and API capabilities.",
+ args: {},
+ async execute(_args, ctx) {
+ return runCass(["capabilities", "--json"], ctx?.abort);
+ },
+});
diff --git a/tool/pdf-brain.ts b/tool/pdf-brain.ts
new file mode 100644
index 0000000..b642ede
--- /dev/null
+++ b/tool/pdf-brain.ts
@@ -0,0 +1,362 @@
+import { tool } from "@opencode-ai/plugin";
+import { existsSync } from "fs";
+import { join, basename, extname } from "path";
+import { spawn } from "child_process";
+
+/**
+ * PDF Brain - Local knowledge base with vector search
+ *
+ * Supports PDFs and Markdown files (local paths or URLs).
+ * Uses PGlite + pgvector for semantic search via Ollama embeddings.
+ * Stores in ~/Documents/.pdf-library/ for iCloud sync.
+ */
+
+const DEFAULT_TIMEOUT_MS = 30_000; // 30s default
+const EMBEDDING_TIMEOUT_MS = 120_000; // 2min for operations that generate embeddings
+
+async function runCli(
+ args: string[],
+ timeoutMs = DEFAULT_TIMEOUT_MS,
+ signal?: AbortSignal,
+): Promise<string> {
+ return new Promise((resolve) => {
+ const proc = spawn("pdf-brain", args, {
+ env: { ...process.env },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+
+ let stdout = "";
+ let stderr = "";
+ let killed = false;
+
+ const timeout = setTimeout(() => {
+ killed = true;
+ proc.kill("SIGTERM");
+ resolve(`Error: Command timed out after ${timeoutMs / 1000}s`);
+ }, timeoutMs);
+
+ // Handle abort signal
+ const abortListener = () => {
+ if (!killed) {
+ killed = true;
+ clearTimeout(timeout);
+ proc.kill("SIGTERM");
+ resolve("Operation cancelled");
+ }
+ };
+ signal?.addEventListener("abort", abortListener);
+
+ proc.stdout.on("data", (data) => {
+ stdout += data.toString();
+ });
+
+ proc.stderr.on("data", (data) => {
+ stderr += data.toString();
+ });
+
+ proc.on("close", (code) => {
+ clearTimeout(timeout);
+ signal?.removeEventListener("abort", abortListener);
+ if (killed) return;
+
+ if (code === 0) {
+ resolve(stdout.trim());
+ } else {
+ resolve(`Error (exit ${code}): ${stderr || stdout}`.trim());
+ }
+ });
+
+ proc.on("error", (err) => {
+ clearTimeout(timeout);
+ signal?.removeEventListener("abort", abortListener);
+ if (killed) return;
+ resolve(`Error: ${err.message}`);
+ });
+ });
+}
+
+function isUrl(str: string): boolean {
+ return str.startsWith("http://") || str.startsWith("https://");
+}
+
+function isValidFile(path: string): boolean {
+ const ext = extname(path).toLowerCase();
+ return ext === ".pdf" || ext === ".md" || ext === ".markdown";
+}
+
+export const add = tool({
+ description:
+ "Add a PDF or Markdown file to the library - extracts text, generates embeddings for semantic search. Supports local paths and URLs.",
+ args: {
+ path: tool.schema.string().describe("Path to file (PDF/Markdown) or URL"),
+ tags: tool.schema.string().optional().describe("Comma-separated tags"),
+ title: tool.schema
+ .string()
+ .optional()
+ .describe("Custom title (default: filename or frontmatter)"),
+ },
+ async execute({ path: filePath, tags, title }, ctx) {
+ // Handle URLs directly
+ if (isUrl(filePath)) {
+ const args = ["add", filePath];
+ if (tags) args.push("--tags", tags);
+ if (title) args.push("--title", title);
+ return runCli(args, EMBEDDING_TIMEOUT_MS, ctx?.abort);
+ }
+
+ // Resolve local path
+ const resolvedPath = filePath.startsWith("~")
+ ? filePath.replace("~", process.env.HOME || "")
+ : filePath.startsWith("/")
+ ? filePath
+ : join(process.cwd(), filePath);
+
+ if (!existsSync(resolvedPath)) {
+ return `File not found: ${resolvedPath}`;
+ }
+
+ if (!isValidFile(resolvedPath)) {
+ return "Unsupported file type. Use PDF or Markdown files.";
+ }
+
+ const args = ["add", resolvedPath];
+ if (tags) args.push("--tags", tags);
+ if (title) args.push("--title", title);
+
+ // Embedding generation can be slow
+ return runCli(args, EMBEDDING_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const search = tool({
+ description:
+ "Semantic search across all documents using vector similarity (requires Ollama)",
+ args: {
+ query: tool.schema.string().describe("Natural language search query"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 10)"),
+ tag: tool.schema.string().optional().describe("Filter by tag"),
+ fts: tool.schema
+ .boolean()
+ .optional()
+ .describe("Use full-text search only (skip embeddings)"),
+ expand: tool.schema
+ .number()
+ .optional()
+ .describe("Expand context around matches (max: 4000 chars)"),
+ },
+ async execute({ query, limit, tag, fts, expand }, ctx) {
+ const args = ["search", query];
+ if (limit) args.push("--limit", String(limit));
+ if (tag) args.push("--tag", tag);
+ if (fts) args.push("--fts");
+ if (expand) args.push("--expand", String(Math.min(expand, 4000)));
+
+ // Vector search needs Ollama for query embedding (unless fts-only)
+ return runCli(args, fts ? DEFAULT_TIMEOUT_MS : 60_000, ctx?.abort);
+ },
+});
+
+export const read = tool({
+ description: "Get document details and metadata",
+ args: {
+ query: tool.schema.string().describe("Document ID or title"),
+ },
+ async execute({ query }, ctx) {
+ return runCli(["read", query], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const list = tool({
+ description: "List all documents in the library",
+ args: {
+ tag: tool.schema.string().optional().describe("Filter by tag"),
+ },
+ async execute({ tag }, ctx) {
+ const args = ["list"];
+ if (tag) args.push("--tag", tag);
+ return runCli(args, DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const remove = tool({
+ description: "Remove a document from the library",
+ args: {
+ query: tool.schema.string().describe("Document ID or title to remove"),
+ },
+ async execute({ query }, ctx) {
+ return runCli(["remove", query], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const tag = tool({
+ description: "Set tags on a document",
+ args: {
+ query: tool.schema.string().describe("Document ID or title"),
+ tags: tool.schema.string().describe("Comma-separated tags to set"),
+ },
+ async execute({ query, tags }, ctx) {
+ return runCli(["tag", query, tags], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const stats = tool({
+ description: "Show library statistics (documents, chunks, embeddings)",
+ args: {},
+ async execute(_args, ctx) {
+ return runCli(["stats"], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const check = tool({
+ description: "Check if Ollama is ready for embedding generation",
+ args: {},
+ async execute(_args, ctx) {
+ return runCli(["check"], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const repair = tool({
+ description:
+ "Fix database integrity issues - removes orphaned chunks/embeddings",
+ args: {},
+ async execute(_args, ctx) {
+ return runCli(["repair"], DEFAULT_TIMEOUT_MS, ctx?.abort);
+ },
+});
+
+export const exportLib = tool({
+ description: "Export library database for backup or sharing",
+ args: {
+ output: tool.schema
+ .string()
+ .optional()
+ .describe("Output file path (default: ./pdf-brain-export.tar.gz)"),
+ },
+ async execute({ output }, ctx) {
+ const args = ["export"];
+ if (output) args.push("--output", output);
+ return runCli(args, 60_000, ctx?.abort);
+ },
+});
+
+export const importLib = tool({
+ description: "Import library database from export archive",
+ args: {
+ file: tool.schema.string().describe("Path to export archive"),
+ force: tool.schema
+ .boolean()
+ .optional()
+ .describe("Overwrite existing library"),
+ },
+ async execute({ file, force }, ctx) {
+ const args = ["import", file];
+ if (force) args.push("--force");
+ return runCli(args, 60_000, ctx?.abort);
+ },
+});
+
+export const migrate = tool({
+ description: "Database migration utilities",
+ args: {
+ check: tool.schema
+ .boolean()
+ .optional()
+ .describe("Check if migration is needed"),
+ importFile: tool.schema
+ .string()
+ .optional()
+ .describe("Import from SQL dump file"),
+ generateScript: tool.schema
+ .boolean()
+ .optional()
+ .describe("Generate export script for current database"),
+ },
+ async execute({ check, importFile, generateScript }, ctx) {
+ const args = ["migrate"];
+ if (check) args.push("--check");
+ if (importFile) args.push("--import", importFile);
+ if (generateScript) args.push("--generate-script");
+
+ // If no flags, just run migrate (shows help)
+ if (!check && !importFile && !generateScript) {
+ args.push("--check");
+ }
+
+ return runCli(args, 60_000, ctx?.abort);
+ },
+});
+
+export const batch_add = tool({
+ description: "Add multiple PDFs/Markdown files from a directory",
+ args: {
+ dir: tool.schema.string().describe("Directory containing documents"),
+ tags: tool.schema.string().optional().describe("Tags to apply to all"),
+ recursive: tool.schema
+ .boolean()
+ .optional()
+ .describe("Search subdirectories"),
+ },
+ async execute({ dir, tags, recursive = false }, ctx) {
+ const resolvedDir = dir.startsWith("~")
+ ? dir.replace("~", process.env.HOME || "")
+ : dir.startsWith("/")
+ ? dir
+ : join(process.cwd(), dir);
+
+ if (!existsSync(resolvedDir)) {
+ return `Directory not found: ${resolvedDir}`;
+ }
+
+ // Find documents
+ const { readdirSync } = await import("fs");
+
+ function findDocs(dir: string, recurse: boolean): string[] {
+ const results: string[] = [];
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory() && recurse) {
+ results.push(...findDocs(fullPath, true));
+ } else if (entry.isFile() && isValidFile(entry.name)) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+ }
+
+ const docList = findDocs(resolvedDir, recursive);
+
+ if (docList.length === 0) {
+ return `No PDF or Markdown files found in ${resolvedDir}`;
+ }
+
+ const results: string[] = [];
+
+ for (const docPath of docList) {
+ // Check for abort between iterations
+ if (ctx?.abort?.aborted) {
+ results.push("\n\nOperation cancelled - remaining files not processed");
+ break;
+ }
+
+ const title = basename(docPath, extname(docPath));
+ try {
+ const args = ["add", docPath];
+ if (tags) args.push("--tags", tags);
+
+ const result = await runCli(args, EMBEDDING_TIMEOUT_MS, ctx?.abort);
+ if (result.includes("✓") || result.includes("Already")) {
+ results.push(`✓ ${title}`);
+ } else {
+ results.push(`✗ ${title}: ${result.slice(0, 100)}`);
+ }
+ } catch (e) {
+ results.push(`✗ ${title}: ${e}`);
+ }
+ }
+
+ return `# Batch Add Results (${docList.length} documents)\n\n${results.join("\n")}`;
+ },
+});
diff --git a/tool/pdf-library.ts b/tool/pdf-library.ts
deleted file mode 100644
index 119f27a..0000000
--- a/tool/pdf-library.ts
+++ /dev/null
@@ -1,202 +0,0 @@
-import { tool } from "@opencode-ai/plugin";
-import { $ } from "bun";
-import { existsSync } from "fs";
-import { join, basename } from "path";
-
-/**
- * PDF Library - Local PDF knowledge base with vector search
- *
- * Uses PGlite + pgvector for semantic search via Ollama embeddings.
- * Stores in ~/Documents/.pdf-library/ for iCloud sync.
- *
- * Requires: pdf-library CLI built and available
- * Location: ~/Code/joelhooks/pdf-library
- */
-
-const PDF_LIBRARY_CLI = join(
- process.env.HOME || "~",
- "Code/joelhooks/pdf-library/dist/cli.js",
-);
-const LIBRARY_DIR = join(process.env.HOME || "~", "Documents", ".pdf-library");
-
-async function runCli(args: string[]): Promise<string> {
- try {
- const result = await $`bun ${PDF_LIBRARY_CLI} ${args}`.text();
- return result.trim();
- } catch (e: any) {
- return `Error: ${e.stderr || e.message || e}`;
- }
-}
-
-export const add = tool({
- description:
- "Add a PDF to the library - extracts text, generates embeddings for semantic search",
- args: {
- path: tool.schema.string().describe("Path to PDF file"),
- tags: tool.schema.string().optional().describe("Comma-separated tags"),
- title: tool.schema
- .string()
- .optional()
- .describe("Custom title (default: filename)"),
- },
- async execute({ path: pdfPath, tags, title }) {
- // Resolve path
- const resolvedPath = pdfPath.startsWith("~")
- ? pdfPath.replace("~", process.env.HOME || "")
- : pdfPath.startsWith("/")
- ? pdfPath
- : join(process.cwd(), pdfPath);
-
- if (!existsSync(resolvedPath)) {
- return `File not found: ${resolvedPath}`;
- }
-
- if (!resolvedPath.toLowerCase().endsWith(".pdf")) {
- return "Not a PDF file";
- }
-
- const args = ["add", resolvedPath];
- if (tags) args.push("--tags", tags);
- if (title) args.push("--title", title);
-
- return runCli(args);
- },
-});
-
-export const search = tool({
- description:
- "Semantic search across all PDFs using vector similarity (requires Ollama)",
- args: {
- query: tool.schema.string().describe("Natural language search query"),
- limit: tool.schema
- .number()
- .optional()
- .describe("Max results (default: 10)"),
- tag: tool.schema.string().optional().describe("Filter by tag"),
- fts: tool.schema
- .boolean()
- .optional()
- .describe("Use full-text search only (no embeddings)"),
- },
- async execute({ query, limit, tag, fts }) {
- const args = ["search", query];
- if (limit) args.push("--limit", String(limit));
- if (tag) args.push("--tag", tag);
- if (fts) args.push("--fts");
-
- return runCli(args);
- },
-});
-
-export const read = tool({
- description: "Get details about a specific PDF in the library",
- args: {
- query: tool.schema.string().describe("PDF ID or title"),
- },
- async execute({ query }) {
- return runCli(["get", query]);
- },
-});
-
-export const list = tool({
- description: "List all PDFs in the library",
- args: {
- tag: tool.schema.string().optional().describe("Filter by tag"),
- },
- async execute({ tag }) {
- const args = ["list"];
- if (tag) args.push("--tag", tag);
- return runCli(args);
- },
-});
-
-export const remove = tool({
- description: "Remove a PDF from the library",
- args: {
- query: tool.schema.string().describe("PDF ID or title to remove"),
- },
- async execute({ query }) {
- return runCli(["remove", query]);
- },
-});
-
-export const tag = tool({
- description: "Set tags on a PDF",
- args: {
- query: tool.schema.string().describe("PDF ID or title"),
- tags: tool.schema.string().describe("Comma-separated tags to set"),
- },
- async execute({ query, tags }) {
- return runCli(["tag", query, tags]);
- },
-});
-
-export const stats = tool({
- description: "Show library statistics (documents, chunks, embeddings)",
- args: {},
- async execute() {
- return runCli(["stats"]);
- },
-});
-
-export const check = tool({
- description: "Check if Ollama is ready for embedding generation",
- args: {},
- async execute() {
- return runCli(["check"]);
- },
-});
-
-export const batch_add = tool({
- description: "Add multiple PDFs from a directory",
- args: {
- dir: tool.schema.string().describe("Directory containing PDFs"),
- tags: tool.schema.string().optional().describe("Tags to apply to all"),
- recursive: tool.schema
- .boolean()
- .optional()
- .describe("Search subdirectories"),
- },
- async execute({ dir, tags, recursive = false }) {
- const resolvedDir = dir.startsWith("~")
- ? dir.replace("~", process.env.HOME || "")
- : dir.startsWith("/")
- ? dir
- : join(process.cwd(), dir);
-
- if (!existsSync(resolvedDir)) {
- return `Directory not found: ${resolvedDir}`;
- }
-
- // Find PDFs
- const depthArg = recursive ? "" : "-maxdepth 1";
- const pdfs =
- await $`find ${resolvedDir} ${depthArg} -name "*.pdf" -o -name "*.PDF" 2>/dev/null`.text();
- const pdfList = pdfs.trim().split("\n").filter(Boolean);
-
- if (pdfList.length === 0) {
- return `No PDFs found in ${resolvedDir}`;
- }
-
- const results: string[] = [];
-
- for (const pdfPath of pdfList) {
- const title = basename(pdfPath, ".pdf");
- try {
- const args = ["add", pdfPath];
- if (tags) args.push("--tags", tags);
-
- const result = await runCli(args);
- if (result.includes("✓") || result.includes("Already")) {
- results.push(`✓ ${title}`);
- } else {
- results.push(`✗ ${title}: ${result.slice(0, 100)}`);
- }
- } catch (e) {
- results.push(`✗ ${title}: ${e}`);
- }
- }
-
- return `# Batch Add Results (${pdfList.length} PDFs)\n\n${results.join("\n")}`;
- },
-});
diff --git a/tool/repo-autopsy.ts b/tool/repo-autopsy.ts
index fb62539..6fb2318 100644
--- a/tool/repo-autopsy.ts
+++ b/tool/repo-autopsy.ts
@@ -1,81 +1,129 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-import { existsSync } from "fs"
-import { join } from "path"
+import { tool } from "@opencode-ai/plugin";
+import { $ } from "bun";
+import { existsSync, statSync } from "fs";
+import { join } from "path";
+import { truncateOutput, MAX_OUTPUT } from "./tool-utils";
/**
* Clone a repo locally and perform deep analysis
* Uses the full local toolchain: rg, ast-grep, git, etc.
*/
-const AUTOPSY_DIR = join(process.env.HOME || "~", ".opencode-autopsy")
+const AUTOPSY_DIR = join(process.env.HOME || "~", ".opencode-autopsy");
-function parseRepoUrl(input: string): { owner: string; repo: string; url: string } | null {
+/** Cache duration in ms - skip fetch if repo was updated within this time */
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/** Track last fetch time per repo to avoid redundant fetches */
+const lastFetchTime: Map<string, number> = new Map();
+
+function parseRepoUrl(
+ input: string,
+): { owner: string; repo: string; url: string } | null {
// Handle: owner/repo, github.com/owner/repo, https://github.com/owner/repo, git@github.com:owner/repo
- let owner: string, repo: string
+ let owner: string, repo: string;
if (input.includes("git@")) {
- const match = input.match(/git@github\.com:([^\/]+)\/(.+?)(?:\.git)?$/)
- if (!match) return null
- owner = match[1]
- repo = match[2]
+ const match = input.match(/git@github\.com:([^\/]+)\/(.+?)(?:\.git)?$/);
+ if (!match) return null;
+ owner = match[1];
+ repo = match[2];
} else {
- const match = input.match(/(?:(?:https?:\/\/)?github\.com\/)?([^\/]+)\/([^\/\s]+)/i)
- if (!match) return null
- owner = match[1]
- repo = match[2].replace(/\.git$/, "")
+ const match = input.match(
+ /(?:(?:https?:\/\/)?github\.com\/)?([^\/]+)\/([^\/\s]+)/i,
+ );
+ if (!match) return null;
+ owner = match[1];
+ repo = match[2].replace(/\.git$/, "");
}
return {
owner,
repo,
url: `https://github.com/${owner}/${repo}.git`,
- }
+ };
}
-async function ensureRepo(repoInput: string): Promise<{ path: string; owner: string; repo: string } | string> {
- const parsed = parseRepoUrl(repoInput)
- if (!parsed) return "Invalid repo format. Use: owner/repo or GitHub URL"
+async function ensureRepo(
+ repoInput: string,
+ signal?: AbortSignal,
+ forceRefresh = false,
+): Promise<
+ { path: string; owner: string; repo: string; cached: boolean } | string
+> {
+ const parsed = parseRepoUrl(repoInput);
+ if (!parsed) return "Invalid repo format. Use: owner/repo or GitHub URL";
- const { owner, repo, url } = parsed
- const repoPath = join(AUTOPSY_DIR, owner, repo)
+ const { owner, repo, url } = parsed;
+ const repoPath = join(AUTOPSY_DIR, owner, repo);
+ const cacheKey = `${owner}/${repo}`;
+
+ // Check abort before starting
+ if (signal?.aborted) return "Operation cancelled";
// Ensure autopsy directory exists
- await $`mkdir -p ${AUTOPSY_DIR}/${owner}`.quiet()
+ await $`mkdir -p ${AUTOPSY_DIR}/${owner}`.quiet();
+
+ if (signal?.aborted) return "Operation cancelled";
if (existsSync(repoPath)) {
+ // Check if we can skip fetch (cache hit)
+ const lastFetch = lastFetchTime.get(cacheKey) || 0;
+ const timeSinceLastFetch = Date.now() - lastFetch;
+
+ if (!forceRefresh && timeSinceLastFetch < CACHE_TTL_MS) {
+ // Cache hit - skip fetch
+ return { path: repoPath, owner, repo, cached: true };
+ }
+
// Update existing repo
try {
- await $`git -C ${repoPath} fetch --all --prune`.quiet()
- await $`git -C ${repoPath} reset --hard origin/HEAD`.quiet()
+ await $`git -C ${repoPath} fetch --all --prune`.quiet();
+ if (signal?.aborted) return "Operation cancelled";
+ await $`git -C ${repoPath} reset --hard origin/HEAD`.quiet();
+ lastFetchTime.set(cacheKey, Date.now());
} catch {
// If fetch fails, re-clone
- await $`rm -rf ${repoPath}`.quiet()
- await $`git clone --depth 100 ${url} ${repoPath}`.quiet()
+ if (signal?.aborted) return "Operation cancelled";
+ await $`rm -rf ${repoPath}`.quiet();
+ await $`git clone --depth 100 ${url} ${repoPath}`.quiet();
+ lastFetchTime.set(cacheKey, Date.now());
}
} else {
// Clone fresh (shallow for speed, but enough history for blame)
- await $`git clone --depth 100 ${url} ${repoPath}`.quiet()
+ await $`git clone --depth 100 ${url} ${repoPath}`.quiet();
+ lastFetchTime.set(cacheKey, Date.now());
}
- return { path: repoPath, owner, repo }
+ if (signal?.aborted) return "Operation cancelled";
+
+ return { path: repoPath, owner, repo, cached: false };
}
export const clone = tool({
- description: "Clone/update a GitHub repo locally for deep analysis. Returns the local path.",
+ description:
+ "Clone/update a GitHub repo locally for deep analysis. Returns the local path.",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
+ refresh: tool.schema
+ .boolean()
+ .optional()
+ .describe("Force refresh even if cached"),
},
- async execute({ repo }) {
+ async execute({ repo, refresh = false }, ctx) {
try {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ const result = await ensureRepo(repo, ctx?.abort, refresh);
+ if (typeof result === "string") return result;
+
+ const cacheStatus = result.cached ? "📦 (cached)" : "🔄 (fetched)";
- // Get basic stats
- const fileCount = await $`find ${result.path} -type f -not -path '*/.git/*' | wc -l`.text()
- const languages = await $`find ${result.path} -type f -not -path '*/.git/*' | sed 's/.*\\.//' | sort | uniq -c | sort -rn | head -10`.text()
+ // Get basic stats in parallel for speed
+ const [fileCount, languages] = await Promise.all([
+ $`find ${result.path} -type f -not -path '*/.git/*' | wc -l`.text(),
+ $`find ${result.path} -type f -not -path '*/.git/*' | sed 's/.*\\.//' | sort | uniq -c | sort -rn | head -10`.text(),
+ ]);
- return `✓ Repo ready at: ${result.path}
+ return `✓ Repo ready at: ${result.path} ${cacheStatus}
Files: ${fileCount.trim()}
@@ -88,12 +136,12 @@ Use other repo-autopsy tools to analyze:
- repo-autopsy_ast - ast-grep patterns
- repo-autopsy_deps - dependency analysis
- repo-autopsy_hotspots - find complex/changed files
-- repo-autopsy_exports - map public API`
+- repo-autopsy_exports - map public API`;
} catch (e) {
- return `Failed to clone repo: ${e}`
+ return `Failed to clone repo: ${e}`;
}
},
-})
+});
export const structure = tool({
description: "Get detailed directory structure of cloned repo",
@@ -102,85 +150,106 @@ export const structure = tool({
path: tool.schema.string().optional().describe("Subpath to explore"),
depth: tool.schema.number().optional().describe("Max depth (default: 4)"),
},
- async execute({ repo, path = "", depth = 4 }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, path = "", depth = 4 }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
- const targetPath = path ? join(result.path, path) : result.path
+ const targetPath = path ? join(result.path, path) : result.path;
try {
// Use tree if available, fall back to find
- const tree = await $`tree -L ${depth} --dirsfirst -I '.git|node_modules|__pycache__|.venv|dist|build|.next' ${targetPath} 2>/dev/null || find ${targetPath} -maxdepth ${depth} -not -path '*/.git/*' -not -path '*/node_modules/*' | head -200`.text()
- return tree.trim()
+ const tree =
+ await $`tree -L ${depth} --dirsfirst -I '.git|node_modules|__pycache__|.venv|dist|build|.next' ${targetPath} 2>/dev/null || find ${targetPath} -maxdepth ${depth} -not -path '*/.git/*' -not -path '*/node_modules/*' | head -200`.text();
+ return tree.trim();
} catch (e) {
- return `Failed: ${e}`
+ return `Failed: ${e}`;
}
},
-})
+});
export const search = tool({
description: "Ripgrep search in cloned repo - full regex power",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
pattern: tool.schema.string().describe("Regex pattern to search"),
- fileGlob: tool.schema.string().optional().describe("File glob filter (e.g., '*.ts')"),
- context: tool.schema.number().optional().describe("Lines of context (default: 2)"),
- maxResults: tool.schema.number().optional().describe("Max results (default: 50)"),
+ fileGlob: tool.schema
+ .string()
+ .optional()
+ .describe("File glob filter (e.g., '*.ts')"),
+ context: tool.schema
+ .number()
+ .optional()
+ .describe("Lines of context (default: 2)"),
+ maxResults: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 50)"),
},
- async execute({ repo, pattern, fileGlob, context = 2, maxResults = 50 }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute(
+ { repo, pattern, fileGlob, context = 2, maxResults = 50 },
+ ctx,
+ ) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
- const globArg = fileGlob ? `--glob '${fileGlob}'` : ""
- const cmd = `rg '${pattern}' ${result.path} -C ${context} ${globArg} --max-count ${maxResults} -n --color never 2>/dev/null | head -500`
- const output = await $`sh -c ${cmd}`.text()
- return output.trim() || "No matches found"
+ const globArg = fileGlob ? `--glob '${fileGlob}'` : "";
+ const cmd = `rg '${pattern}' ${result.path} -C ${context} ${globArg} --max-count ${maxResults} -n --color never 2>/dev/null | head -500`;
+ const output = await $`sh -c ${cmd}`.text();
+ return truncateOutput(output.trim() || "No matches found");
} catch {
- return "No matches found"
+ return "No matches found";
}
},
-})
+});
export const ast = tool({
description: "AST-grep structural search in cloned repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
- pattern: tool.schema.string().describe("ast-grep pattern (e.g., 'function $NAME($$$ARGS) { $$$BODY }')"),
- lang: tool.schema.string().optional().describe("Language: ts, tsx, js, py, go, rust (default: auto)"),
+ pattern: tool.schema
+ .string()
+ .describe(
+ "ast-grep pattern (e.g., 'function $NAME($$$ARGS) { $$$BODY }')",
+ ),
+ lang: tool.schema
+ .string()
+ .optional()
+ .describe("Language: ts, tsx, js, py, go, rust (default: auto)"),
},
- async execute({ repo, pattern, lang }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, pattern, lang }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
- const langArg = lang ? `--lang ${lang}` : ""
- const output = await $`ast-grep --pattern ${pattern} ${langArg} ${result.path} 2>/dev/null | head -200`.text()
- return output.trim() || "No matches found"
+ const langArg = lang ? `--lang ${lang}` : "";
+ const output =
+ await $`ast-grep --pattern ${pattern} ${langArg} ${result.path} 2>/dev/null | head -200`.text();
+ return output.trim() || "No matches found";
} catch (e) {
- return `ast-grep failed (installed?): ${e}`
+ return `ast-grep failed (installed?): ${e}`;
}
},
-})
+});
export const deps = tool({
description: "Analyze dependencies in cloned repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
},
- async execute({ repo }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
- const outputs: string[] = []
+ const outputs: string[] = [];
// Node.js
- const pkgPath = join(result.path, "package.json")
+ const pkgPath = join(result.path, "package.json");
if (existsSync(pkgPath)) {
try {
- const pkg = await Bun.file(pkgPath).json()
- const deps = Object.keys(pkg.dependencies || {}).slice(0, 20)
- const devDeps = Object.keys(pkg.devDependencies || {}).slice(0, 15)
+ const pkg = await Bun.file(pkgPath).json();
+ const deps = Object.keys(pkg.dependencies || {}).slice(0, 20);
+ const devDeps = Object.keys(pkg.devDependencies || {}).slice(0, 15);
outputs.push(`## Node.js (package.json)
@@ -188,259 +257,293 @@ Dependencies (${Object.keys(pkg.dependencies || {}).length}):
${deps.join(", ")}${Object.keys(pkg.dependencies || {}).length > 20 ? " ..." : ""}
DevDependencies (${Object.keys(pkg.devDependencies || {}).length}):
-${devDeps.join(", ")}${Object.keys(pkg.devDependencies || {}).length > 15 ? " ..." : ""}`)
+${devDeps.join(", ")}${Object.keys(pkg.devDependencies || {}).length > 15 ? " ..." : ""}`);
} catch {}
}
// Python
- const pyprojectPath = join(result.path, "pyproject.toml")
- const requirementsPath = join(result.path, "requirements.txt")
+ const pyprojectPath = join(result.path, "pyproject.toml");
+ const requirementsPath = join(result.path, "requirements.txt");
if (existsSync(requirementsPath)) {
- const reqs = await Bun.file(requirementsPath).text()
- const deps = reqs.split("\n").filter(l => l.trim() && !l.startsWith("#")).slice(0, 20)
- outputs.push(`## Python (requirements.txt)\n${deps.join("\n")}`)
+ const reqs = await Bun.file(requirementsPath).text();
+ const deps = reqs
+ .split("\n")
+ .filter((l) => l.trim() && !l.startsWith("#"))
+ .slice(0, 20);
+ outputs.push(`## Python (requirements.txt)\n${deps.join("\n")}`);
} else if (existsSync(pyprojectPath)) {
- const content = await Bun.file(pyprojectPath).text()
- outputs.push(`## Python (pyproject.toml)\n${content.slice(0, 1500)}...`)
+ const content = await Bun.file(pyprojectPath).text();
+ outputs.push(`## Python (pyproject.toml)\n${content.slice(0, 1500)}...`);
}
// Go
- const goModPath = join(result.path, "go.mod")
+ const goModPath = join(result.path, "go.mod");
if (existsSync(goModPath)) {
- const content = await Bun.file(goModPath).text()
- outputs.push(`## Go (go.mod)\n${content.slice(0, 1500)}`)
+ const content = await Bun.file(goModPath).text();
+ outputs.push(`## Go (go.mod)\n${content.slice(0, 1500)}`);
}
// Rust
- const cargoPath = join(result.path, "Cargo.toml")
+ const cargoPath = join(result.path, "Cargo.toml");
if (existsSync(cargoPath)) {
- const content = await Bun.file(cargoPath).text()
- outputs.push(`## Rust (Cargo.toml)\n${content.slice(0, 1500)}`)
+ const content = await Bun.file(cargoPath).text();
+ outputs.push(`## Rust (Cargo.toml)\n${content.slice(0, 1500)}`);
}
- return outputs.length ? outputs.join("\n\n") : "No dependency files found"
+ return outputs.length ? outputs.join("\n\n") : "No dependency files found";
},
-})
+});
export const hotspots = tool({
- description: "Find code hotspots - most changed files, largest files, most complex",
+ description:
+ "Find code hotspots - most changed files, largest files, most complex",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
},
- async execute({ repo }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
-
- const outputs: string[] = []
-
- // Most changed files (churn)
- try {
- const churn = await $`git -C ${result.path} log --oneline --name-only --pretty=format: | sort | uniq -c | sort -rn | grep -v '^$' | head -15`.text()
- outputs.push(`## Most Changed Files (Git Churn)\n${churn.trim()}`)
- } catch {}
-
- // Largest files
- try {
- const largest = await $`fd -t f -E .git -E node_modules -E __pycache__ . ${result.path} --exec wc -l {} 2>/dev/null | sort -rn | head -15`.text()
- outputs.push(`## Largest Files (by lines)\n${largest.trim()}`)
- } catch {}
-
- // Files with most TODOs/FIXMEs
- try {
- const todos = await $`rg -c 'TODO|FIXME|HACK|XXX' ${result.path} --glob '!.git' 2>/dev/null | sort -t: -k2 -rn | head -10`.text()
- if (todos.trim()) {
- outputs.push(`## Most TODOs/FIXMEs\n${todos.trim()}`)
- }
- } catch {}
-
- // Recent activity
- try {
- const recent = await $`git -C ${result.path} log --oneline -20`.text()
- outputs.push(`## Recent Commits\n${recent.trim()}`)
- } catch {}
+ async execute({ repo }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
+
+ // Run all analyses in parallel for speed
+ const [churnResult, largestResult, todosResult, recentResult] =
+ await Promise.allSettled([
+ // Most changed files (churn)
+ $`git -C ${result.path} log --oneline --name-only --pretty=format: | sort | uniq -c | sort -rn | grep -v '^$' | head -15`.text(),
+ // Largest files
+ $`fd -t f -E .git -E node_modules -E __pycache__ . ${result.path} --exec wc -l {} 2>/dev/null | sort -rn | head -15`.text(),
+ // Files with most TODOs/FIXMEs
+ $`rg -c 'TODO|FIXME|HACK|XXX' ${result.path} --glob '!.git' 2>/dev/null | sort -t: -k2 -rn | head -10`.text(),
+ // Recent activity
+ $`git -C ${result.path} log --oneline -20`.text(),
+ ]);
+
+ const outputs: string[] = [];
+
+ if (churnResult.status === "fulfilled" && churnResult.value.trim()) {
+ outputs.push(
+ `## Most Changed Files (Git Churn)\n${churnResult.value.trim()}`,
+ );
+ }
+ if (largestResult.status === "fulfilled" && largestResult.value.trim()) {
+ outputs.push(
+ `## Largest Files (by lines)\n${largestResult.value.trim()}`,
+ );
+ }
+ if (todosResult.status === "fulfilled" && todosResult.value.trim()) {
+ outputs.push(`## Most TODOs/FIXMEs\n${todosResult.value.trim()}`);
+ }
+ if (recentResult.status === "fulfilled" && recentResult.value.trim()) {
+ outputs.push(`## Recent Commits\n${recentResult.value.trim()}`);
+ }
- return outputs.join("\n\n")
+ return truncateOutput(outputs.join("\n\n"));
},
-})
+});
export const stats = tool({
- description: "Code statistics - lines of code, languages, file counts (uses tokei)",
+ description:
+ "Code statistics - lines of code, languages, file counts (uses tokei)",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
},
- async execute({ repo }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
- const stats = await $`tokei ${result.path} --exclude .git --exclude node_modules --exclude vendor --exclude __pycache__ 2>/dev/null`.text()
- return stats.trim()
+ const stats =
+ await $`tokei ${result.path} --exclude .git --exclude node_modules --exclude vendor --exclude __pycache__ 2>/dev/null`.text();
+ return stats.trim();
} catch (e) {
- return `tokei failed: ${e}`
+ return `tokei failed: ${e}`;
}
},
-})
+});
export const secrets = tool({
description: "Scan for leaked secrets in repo (uses gitleaks)",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
},
- async execute({ repo }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
// gitleaks returns non-zero if it finds secrets, so we catch
- const output = await $`gitleaks detect --source ${result.path} --no-banner -v 2>&1`.text().catch(e => e.stdout || e.message)
-
+ const output =
+ await $`gitleaks detect --source ${result.path} --no-banner -v 2>&1`
+ .text()
+ .catch((e) => e.stdout || e.message);
+
if (output.includes("no leaks found")) {
- return "✓ No secrets detected"
+ return "✓ No secrets detected";
}
-
+
// Truncate if too long
if (output.length > 5000) {
- return output.slice(0, 5000) + "\n\n... (truncated)"
+ return output.slice(0, 5000) + "\n\n... (truncated)";
}
-
- return output.trim() || "Scan complete (check output)"
+
+ return output.trim() || "Scan complete (check output)";
} catch (e) {
- return `gitleaks failed: ${e}`
+ return `gitleaks failed: ${e}`;
}
},
-})
+});
export const find = tool({
description: "Fast file finding with fd (better than find)",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
pattern: tool.schema.string().describe("File name pattern (regex)"),
- type: tool.schema.enum(["f", "d", "l", "x"]).optional().describe("Type: f=file, d=dir, l=symlink, x=executable"),
- extension: tool.schema.string().optional().describe("Filter by extension (e.g., 'ts')"),
+ type: tool.schema
+ .enum(["f", "d", "l", "x"])
+ .optional()
+ .describe("Type: f=file, d=dir, l=symlink, x=executable"),
+ extension: tool.schema
+ .string()
+ .optional()
+ .describe("Filter by extension (e.g., 'ts')"),
},
- async execute({ repo, pattern, type, extension }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, pattern, type, extension }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
- const typeArg = type ? `-t ${type}` : ""
- const extArg = extension ? `-e ${extension}` : ""
- const output = await $`fd ${pattern} ${result.path} ${typeArg} ${extArg} -E .git -E node_modules 2>/dev/null | head -50`.text()
- return output.trim() || "No matches"
+ const typeArg = type ? `-t ${type}` : "";
+ const extArg = extension ? `-e ${extension}` : "";
+ const output =
+ await $`fd ${pattern} ${result.path} ${typeArg} ${extArg} -E .git -E node_modules 2>/dev/null | head -50`.text();
+ return output.trim() || "No matches";
} catch {
- return "No matches"
+ return "No matches";
}
},
-})
+});
export const exports_map = tool({
description: "Map public API - all exports from a repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
- entryPoint: tool.schema.string().optional().describe("Entry point to analyze (e.g., 'src/index.ts')"),
+ entryPoint: tool.schema
+ .string()
+ .optional()
+ .describe("Entry point to analyze (e.g., 'src/index.ts')"),
},
- async execute({ repo, entryPoint }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, entryPoint }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
- const outputs: string[] = []
+ const outputs: string[] = [];
// Find main entry points if not specified
if (!entryPoint) {
const possibleEntries = [
- "src/index.ts", "src/index.tsx", "src/index.js",
- "lib/index.ts", "lib/index.js",
- "index.ts", "index.js",
- "src/main.ts", "src/main.js",
+ "src/index.ts",
+ "src/index.tsx",
+ "src/index.js",
+ "lib/index.ts",
+ "lib/index.js",
+ "index.ts",
+ "index.js",
+ "src/main.ts",
+ "src/main.js",
"mod.ts", // Deno
- ]
+ ];
for (const entry of possibleEntries) {
if (existsSync(join(result.path, entry))) {
- entryPoint = entry
- break
+ entryPoint = entry;
+ break;
}
}
}
- // Find all exports
- try {
- const namedExports = await $`rg "^export (const|function|class|type|interface|enum|let|var) " ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' -o -N 2>/dev/null | sort | uniq -c | sort -rn | head -30`.text()
- if (namedExports.trim()) {
- outputs.push(`## Named Exports\n${namedExports.trim()}`)
- }
- } catch {}
-
- // Default exports
- try {
- const defaultExports = await $`rg "^export default" ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' -l 2>/dev/null | head -20`.text()
- if (defaultExports.trim()) {
- outputs.push(`## Files with Default Exports\n${defaultExports.trim()}`)
- }
- } catch {}
+ // Run all export searches in parallel
+ const [namedResult, defaultResult, reexportResult] =
+ await Promise.allSettled([
+ $`rg "^export (const|function|class|type|interface|enum|let|var) " ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' -o -N 2>/dev/null | sort | uniq -c | sort -rn | head -30`.text(),
+ $`rg "^export default" ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' -l 2>/dev/null | head -20`.text(),
+ $`rg "^export \\* from|^export \\{[^}]+\\} from" ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' 2>/dev/null | head -30`.text(),
+ ]);
- // Re-exports (barrel files)
- try {
- const reexports = await $`rg "^export \\* from|^export \\{[^}]+\\} from" ${result.path} --glob '*.ts' --glob '*.tsx' --glob '*.js' 2>/dev/null | head -30`.text()
- if (reexports.trim()) {
- outputs.push(`## Re-exports\n${reexports.trim()}`)
- }
- } catch {}
+ if (namedResult.status === "fulfilled" && namedResult.value.trim()) {
+ outputs.push(`## Named Exports\n${namedResult.value.trim()}`);
+ }
+ if (defaultResult.status === "fulfilled" && defaultResult.value.trim()) {
+ outputs.push(
+ `## Files with Default Exports\n${defaultResult.value.trim()}`,
+ );
+ }
+ if (reexportResult.status === "fulfilled" && reexportResult.value.trim()) {
+ outputs.push(`## Re-exports\n${reexportResult.value.trim()}`);
+ }
// Read entry point if found
if (entryPoint) {
- const entryPath = join(result.path, entryPoint)
+ const entryPath = join(result.path, entryPoint);
if (existsSync(entryPath)) {
- const content = await Bun.file(entryPath).text()
- outputs.unshift(`## Entry Point: ${entryPoint}\n\`\`\`typescript\n${content.slice(0, 2000)}${content.length > 2000 ? "\n// ... truncated" : ""}\n\`\`\``)
+ const content = await Bun.file(entryPath).text();
+ outputs.unshift(
+ `## Entry Point: ${entryPoint}\n\`\`\`typescript\n${content.slice(0, 2000)}${content.length > 2000 ? "\n// ... truncated" : ""}\n\`\`\``,
+ );
}
}
- return outputs.join("\n\n") || "No exports found"
+ return truncateOutput(outputs.join("\n\n") || "No exports found");
},
-})
+});
export const file = tool({
description: "Read a file from cloned repo with optional line range",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
path: tool.schema.string().describe("File path within repo"),
- startLine: tool.schema.number().optional().describe("Start line (1-indexed)"),
+ startLine: tool.schema
+ .number()
+ .optional()
+ .describe("Start line (1-indexed)"),
endLine: tool.schema.number().optional().describe("End line"),
},
- async execute({ repo, path, startLine, endLine }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, path, startLine, endLine }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
- const filePath = join(result.path, path)
+ const filePath = join(result.path, path);
if (!existsSync(filePath)) {
- return `File not found: ${path}`
+ return `File not found: ${path}`;
}
try {
- const content = await Bun.file(filePath).text()
- const lines = content.split("\n")
+ const content = await Bun.file(filePath).text();
+ const lines = content.split("\n");
if (startLine || endLine) {
- const start = (startLine || 1) - 1
- const end = endLine || lines.length
- const slice = lines.slice(start, end)
- return slice.map((l, i) => `${start + i + 1}: ${l}`).join("\n")
+ const start = (startLine || 1) - 1;
+ const end = endLine || lines.length;
+ const slice = lines.slice(start, end);
+ return slice.map((l, i) => `${start + i + 1}: ${l}`).join("\n");
}
// Add line numbers and truncate if needed
if (lines.length > 500) {
- return lines.slice(0, 500).map((l, i) => `${i + 1}: ${l}`).join("\n") + `\n\n... (${lines.length - 500} more lines)`
+ return (
+ lines
+ .slice(0, 500)
+ .map((l, i) => `${i + 1}: ${l}`)
+ .join("\n") + `\n\n... (${lines.length - 500} more lines)`
+ );
}
- return lines.map((l, i) => `${i + 1}: ${l}`).join("\n")
+ return lines.map((l, i) => `${i + 1}: ${l}`).join("\n");
} catch (e) {
- return `Failed to read file: ${e}`
+ return `Failed to read file: ${e}`;
}
},
-})
+});
export const blame = tool({
description: "Git blame for a file - who wrote what",
@@ -450,40 +553,44 @@ export const blame = tool({
startLine: tool.schema.number().optional().describe("Start line"),
endLine: tool.schema.number().optional().describe("End line"),
},
- async execute({ repo, path, startLine, endLine }) {
- const result = await ensureRepo(repo)
- if (typeof result === "string") return result
+ async execute({ repo, path, startLine, endLine }, ctx) {
+ const result = await ensureRepo(repo, ctx?.abort);
+ if (typeof result === "string") return result;
try {
- const lineRange = startLine && endLine ? `-L ${startLine},${endLine}` : ""
- const output = await $`git -C ${result.path} blame ${lineRange} --date=short ${path} 2>/dev/null | head -100`.text()
- return output.trim() || "No blame info"
+ const lineRange =
+ startLine && endLine ? `-L ${startLine},${endLine}` : "";
+ const output =
+ await $`git -C ${result.path} blame ${lineRange} --date=short ${path} 2>/dev/null | head -100`.text();
+ return output.trim() || "No blame info";
} catch (e) {
- return `Blame failed: ${e}`
+ return `Blame failed: ${e}`;
}
},
-})
+});
export const cleanup = tool({
description: "Remove a cloned repo from local autopsy cache",
args: {
- repo: tool.schema.string().describe("GitHub repo (owner/repo or URL) or 'all' to clear everything"),
+ repo: tool.schema
+ .string()
+ .describe("GitHub repo (owner/repo or URL) or 'all' to clear everything"),
},
- async execute({ repo }) {
+ async execute({ repo }, ctx) {
if (repo === "all") {
- await $`rm -rf ${AUTOPSY_DIR}`.quiet()
- return `Cleared all repos from ${AUTOPSY_DIR}`
+ await $`rm -rf ${AUTOPSY_DIR}`.quiet();
+ return `Cleared all repos from ${AUTOPSY_DIR}`;
}
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format"
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format";
- const repoPath = join(AUTOPSY_DIR, parsed.owner, parsed.repo)
+ const repoPath = join(AUTOPSY_DIR, parsed.owner, parsed.repo);
if (existsSync(repoPath)) {
- await $`rm -rf ${repoPath}`.quiet()
- return `Removed: ${repoPath}`
+ await $`rm -rf ${repoPath}`.quiet();
+ return `Removed: ${repoPath}`;
}
- return "Repo not in cache"
+ return "Repo not in cache";
},
-})
+});
diff --git a/tool/repo-crawl.ts b/tool/repo-crawl.ts
index 83d1c50..690cf39 100644
--- a/tool/repo-crawl.ts
+++ b/tool/repo-crawl.ts
@@ -1,64 +1,107 @@
-import { tool } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin";
+import { truncateOutput } from "./tool-utils";
/**
- * Crawl a GitHub repo - structure, key files, patterns
+ * Crawl a GitHub repo via GitHub API - no local clone needed
+ * Supports GITHUB_TOKEN env var for higher rate limits (5000/hr vs 60/hr)
*/
-const GITHUB_API = "https://api.github.com"
-const GITHUB_RAW = "https://raw.githubusercontent.com"
+const GITHUB_API = "https://api.github.com";
+const GITHUB_RAW = "https://raw.githubusercontent.com";
+
+/** Get auth headers if GITHUB_TOKEN is set */
+function getAuthHeaders(): Record<string, string> {
+ const headers: Record<string, string> = {
+ Accept: "application/vnd.github.v3+json",
+ "User-Agent": "opencode-repo-crawl",
+ };
+ const token = process.env.GITHUB_TOKEN;
+ if (token) {
+ headers.Authorization = `Bearer ${token}`;
+ }
+ return headers;
+}
-async function fetchGH(path: string) {
+async function fetchGH(path: string, signal?: AbortSignal) {
const res = await fetch(`${GITHUB_API}${path}`, {
- headers: {
- Accept: "application/vnd.github.v3+json",
- "User-Agent": "opencode-repo-crawl",
- },
- })
- if (!res.ok) throw new Error(`GitHub API error: ${res.status}`)
- return res.json()
+ headers: getAuthHeaders(),
+ signal,
+ });
+ if (!res.ok) {
+ if (res.status === 403) {
+ const remaining = res.headers.get("X-RateLimit-Remaining");
+ if (remaining === "0") {
+ const resetTime = res.headers.get("X-RateLimit-Reset");
+ const resetDate = resetTime
+ ? new Date(parseInt(resetTime) * 1000).toLocaleTimeString()
+ : "soon";
+ throw new Error(
+ `GitHub API rate limit exceeded. Resets at ${resetDate}. Set GITHUB_TOKEN for 5000 req/hr.`,
+ );
+ }
+ }
+ throw new Error(`GitHub API error: ${res.status}`);
+ }
+ return res.json();
}
-async function fetchRaw(owner: string, repo: string, path: string) {
- const res = await fetch(`${GITHUB_RAW}/${owner}/${repo}/main/${path}`)
+async function fetchRaw(
+ owner: string,
+ repo: string,
+ path: string,
+ signal?: AbortSignal,
+) {
+ const res = await fetch(`${GITHUB_RAW}/${owner}/${repo}/main/${path}`, {
+ headers: getAuthHeaders(),
+ signal,
+ });
if (!res.ok) {
// Try master branch
- const res2 = await fetch(`${GITHUB_RAW}/${owner}/${repo}/master/${path}`)
- if (!res2.ok) return null
- return res2.text()
+ const res2 = await fetch(`${GITHUB_RAW}/${owner}/${repo}/master/${path}`, {
+ headers: getAuthHeaders(),
+ signal,
+ });
+ if (!res2.ok) return null;
+ return res2.text();
}
- return res.text()
+ return res.text();
}
function parseRepoUrl(input: string): { owner: string; repo: string } | null {
// Handle: owner/repo, github.com/owner/repo, https://github.com/owner/repo
- const match = input.match(/(?:github\.com\/)?([^\/]+)\/([^\/\s]+)/i)
- if (!match) return null
- return { owner: match[1], repo: match[2].replace(/\.git$/, "") }
+ const match = input.match(/(?:github\.com\/)?([^\/]+)\/([^\/\s]+)/i);
+ if (!match) return null;
+ return { owner: match[1], repo: match[2].replace(/\.git$/, "") };
}
export const structure = tool({
- description: "Get repo structure - directories, key files, tech stack detection",
+ description:
+ "Get repo structure - directories, key files, tech stack detection",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
- depth: tool.schema.number().optional().describe("Max depth to crawl (default: 2)"),
+ depth: tool.schema
+ .number()
+ .optional()
+ .describe("Max depth to crawl (default: 2)"),
},
- async execute({ repo, depth = 2 }) {
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format. Use: owner/repo or GitHub URL"
+ async execute({ repo, depth = 2 }, ctx) {
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format. Use: owner/repo or GitHub URL";
- const { owner, repo: repoName } = parsed
+ const { owner, repo: repoName } = parsed;
+ const signal = ctx?.abort;
try {
- // Get repo info
- const repoInfo = await fetchGH(`/repos/${owner}/${repoName}`)
-
- // Get root contents
- const contents = await fetchGH(`/repos/${owner}/${repoName}/contents`)
+ // Get repo info and root contents in parallel
+ const [repoInfo, contents] = await Promise.all([
+ fetchGH(`/repos/${owner}/${repoName}`, signal),
+ fetchGH(`/repos/${owner}/${repoName}/contents`, signal),
+ ]);
// Categorize files
- const dirs: string[] = []
- const files: string[] = []
- const keyFiles: string[] = []
+ const dirs: string[] = [];
+ const files: string[] = [];
+ const keyFiles: string[] = [];
const KEY_PATTERNS = [
/^readme/i,
@@ -74,43 +117,64 @@ export const structure = tool({
/^setup\.py$/,
/^pom\.xml$/,
/^build\.gradle/,
- ]
+ ];
for (const item of contents) {
if (item.type === "dir") {
- dirs.push(item.name + "/")
+ dirs.push(item.name + "/");
} else {
- files.push(item.name)
+ files.push(item.name);
if (KEY_PATTERNS.some((p) => p.test(item.name))) {
- keyFiles.push(item.name)
+ keyFiles.push(item.name);
}
}
}
// Detect tech stack
- const stack: string[] = []
- if (files.includes("package.json")) stack.push("Node.js")
- if (files.some((f) => f.includes("tsconfig"))) stack.push("TypeScript")
- if (files.includes("Cargo.toml")) stack.push("Rust")
- if (files.includes("go.mod")) stack.push("Go")
- if (files.includes("pyproject.toml") || files.includes("setup.py") || files.includes("requirements.txt")) stack.push("Python")
- if (files.includes("pom.xml") || files.some((f) => f.includes("build.gradle"))) stack.push("Java/Kotlin")
- if (dirs.includes("src/")) stack.push("src/ structure")
- if (dirs.includes("lib/")) stack.push("lib/ structure")
- if (dirs.includes("app/")) stack.push("app/ structure (Next.js/Rails?)")
- if (dirs.includes("pages/")) stack.push("pages/ (Next.js Pages Router?)")
+ const stack: string[] = [];
+ if (files.includes("package.json")) stack.push("Node.js");
+ if (files.some((f) => f.includes("tsconfig"))) stack.push("TypeScript");
+ if (files.includes("Cargo.toml")) stack.push("Rust");
+ if (files.includes("go.mod")) stack.push("Go");
+ if (
+ files.includes("pyproject.toml") ||
+ files.includes("setup.py") ||
+ files.includes("requirements.txt")
+ )
+ stack.push("Python");
+ if (
+ files.includes("pom.xml") ||
+ files.some((f) => f.includes("build.gradle"))
+ )
+ stack.push("Java/Kotlin");
+ if (dirs.includes("src/")) stack.push("src/ structure");
+ if (dirs.includes("lib/")) stack.push("lib/ structure");
+ if (dirs.includes("app/")) stack.push("app/ structure (Next.js/Rails?)");
+ if (dirs.includes("pages/")) stack.push("pages/ (Next.js Pages Router?)");
// Get subdir contents for depth > 1
- let subdirs = ""
+ let subdirs = "";
if (depth > 1) {
- const importantDirs = ["src", "lib", "app", "packages", "examples", "core"]
+ const importantDirs = [
+ "src",
+ "lib",
+ "app",
+ "packages",
+ "examples",
+ "core",
+ ];
for (const dir of dirs) {
- const dirName = dir.replace("/", "")
+ const dirName = dir.replace("/", "");
if (importantDirs.includes(dirName)) {
try {
- const subContents = await fetchGH(`/repos/${owner}/${repoName}/contents/${dirName}`)
- const subItems = subContents.map((i: any) => (i.type === "dir" ? i.name + "/" : i.name))
- subdirs += `\n ${dir}\n ${subItems.slice(0, 15).join(", ")}${subContents.length > 15 ? ` (+${subContents.length - 15} more)` : ""}`
+ const subContents = await fetchGH(
+ `/repos/${owner}/${repoName}/contents/${dirName}`,
+ signal,
+ );
+ const subItems = subContents.map((i: any) =>
+ i.type === "dir" ? i.name + "/" : i.name,
+ );
+ subdirs += `\n ${dir}\n ${subItems.slice(0, 15).join(", ")}${subContents.length > 15 ? ` (+${subContents.length - 15} more)` : ""}`;
} catch {
// skip if error
}
@@ -133,146 +197,180 @@ Root files: ${files.slice(0, 10).join(", ")}${files.length > 10 ? ` (+${files.le
## Key Files
${keyFiles.join(", ") || "(none detected)"}
-${subdirs ? `\n## Important Subdirs${subdirs}` : ""}`
+${subdirs ? `\n## Important Subdirs${subdirs}` : ""}`;
} catch (e) {
- return `Failed to fetch repo: ${e}`
+ return `Failed to fetch repo: ${e}`;
}
},
-})
+});
export const readme = tool({
description: "Get repo README content",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
- maxLength: tool.schema.number().optional().describe("Max chars to return (default: 5000)"),
+ maxLength: tool.schema
+ .number()
+ .optional()
+ .describe("Max chars to return (default: 5000)"),
},
- async execute({ repo, maxLength = 5000 }) {
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format"
+ async execute({ repo, maxLength = 5000 }, ctx) {
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format";
- const { owner, repo: repoName } = parsed
+ const { owner, repo: repoName } = parsed;
+ const signal = ctx?.abort;
// Try common README names
- const names = ["README.md", "readme.md", "README", "README.rst", "README.txt"]
+ const names = [
+ "README.md",
+ "readme.md",
+ "README",
+ "README.rst",
+ "README.txt",
+ ];
for (const name of names) {
- const content = await fetchRaw(owner, repoName, name)
+ if (signal?.aborted) return "Operation cancelled";
+ const content = await fetchRaw(owner, repoName, name, signal);
if (content) {
- if (content.length > maxLength) {
- return content.slice(0, maxLength) + `\n\n... (truncated, ${content.length - maxLength} more chars)`
- }
- return content
+ return truncateOutput(content, maxLength);
}
}
- return "No README found"
+ return "No README found";
},
-})
+});
export const file = tool({
description: "Get a specific file from a GitHub repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
path: tool.schema.string().describe("File path within repo"),
- maxLength: tool.schema.number().optional().describe("Max chars to return (default: 10000)"),
+ maxLength: tool.schema
+ .number()
+ .optional()
+ .describe("Max chars to return (default: 10000)"),
},
- async execute({ repo, path, maxLength = 10000 }) {
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format"
+ async execute({ repo, path, maxLength = 10000 }, ctx) {
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format";
- const { owner, repo: repoName } = parsed
- const content = await fetchRaw(owner, repoName, path)
+ const { owner, repo: repoName } = parsed;
+ const content = await fetchRaw(owner, repoName, path, ctx?.abort);
- if (!content) return `File not found: ${path}`
+ if (!content) return `File not found: ${path}`;
- if (content.length > maxLength) {
- return content.slice(0, maxLength) + `\n\n... (truncated, ${content.length - maxLength} more chars)`
- }
- return content
+ return truncateOutput(content, maxLength);
},
-})
+});
export const tree = tool({
description: "Get directory tree of a path in a GitHub repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
- path: tool.schema.string().optional().describe("Directory path (default: root)"),
- maxDepth: tool.schema.number().optional().describe("Max depth (default: 3)"),
+ path: tool.schema
+ .string()
+ .optional()
+ .describe("Directory path (default: root)"),
+ maxDepth: tool.schema
+ .number()
+ .optional()
+ .describe("Max depth (default: 3)"),
},
- async execute({ repo, path = "", maxDepth = 3 }) {
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format"
+ async execute({ repo, path = "", maxDepth = 3 }, ctx) {
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format";
- const { owner, repo: repoName } = parsed
+ const { owner, repo: repoName } = parsed;
+ const signal = ctx?.abort;
- async function getTree(p: string, depth: number, prefix: string): Promise<string> {
- if (depth > maxDepth) return ""
+ async function getTree(
+ p: string,
+ depth: number,
+ prefix: string,
+ ): Promise<string> {
+ if (depth > maxDepth) return "";
+ if (signal?.aborted) return "";
try {
- const contents = await fetchGH(`/repos/${owner}/${repoName}/contents/${p}`)
- let result = ""
+ const contents = await fetchGH(
+ `/repos/${owner}/${repoName}/contents/${p}`,
+ signal,
+ );
+ let result = "";
// Sort: dirs first, then files
const sorted = contents.sort((a: any, b: any) => {
- if (a.type === b.type) return a.name.localeCompare(b.name)
- return a.type === "dir" ? -1 : 1
- })
+ if (a.type === b.type) return a.name.localeCompare(b.name);
+ return a.type === "dir" ? -1 : 1;
+ });
for (let i = 0; i < sorted.length && i < 50; i++) {
- const item = sorted[i]
- const isLast = i === Math.min(sorted.length, 50) - 1
- const connector = isLast ? "└── " : "├── "
- const newPrefix = prefix + (isLast ? " " : "│ ")
+ const item = sorted[i];
+ const isLast = i === Math.min(sorted.length, 50) - 1;
+ const connector = isLast ? "└── " : "├── ";
+ const newPrefix = prefix + (isLast ? " " : "│ ");
- result += `${prefix}${connector}${item.name}${item.type === "dir" ? "/" : ""}\n`
+ result += `${prefix}${connector}${item.name}${item.type === "dir" ? "/" : ""}\n`;
if (item.type === "dir" && depth < maxDepth) {
- result += await getTree(item.path, depth + 1, newPrefix)
+ result += await getTree(item.path, depth + 1, newPrefix);
}
}
if (sorted.length > 50) {
- result += `${prefix}... (+${sorted.length - 50} more)\n`
+ result += `${prefix}... (+${sorted.length - 50} more)\n`;
}
- return result
+ return result;
} catch {
- return ""
+ return "";
}
}
- const tree = await getTree(path, 1, "")
- return tree || "Empty or not found"
+ const tree = await getTree(path, 1, "");
+ return tree || "Empty or not found";
},
-})
+});
export const search = tool({
description: "Search for code in a GitHub repo",
args: {
repo: tool.schema.string().describe("GitHub repo (owner/repo or URL)"),
query: tool.schema.string().describe("Search query"),
- maxResults: tool.schema.number().optional().describe("Max results (default: 10)"),
+ maxResults: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 10)"),
},
- async execute({ repo, query, maxResults = 10 }) {
- const parsed = parseRepoUrl(repo)
- if (!parsed) return "Invalid repo format"
+ async execute({ repo, query, maxResults = 10 }, ctx) {
+ const parsed = parseRepoUrl(repo);
+ if (!parsed) return "Invalid repo format";
- const { owner, repo: repoName } = parsed
+ const { owner, repo: repoName } = parsed;
try {
- const searchQuery = encodeURIComponent(`${query} repo:${owner}/${repoName}`)
- const results = await fetchGH(`/search/code?q=${searchQuery}&per_page=${maxResults}`)
+ const searchQuery = encodeURIComponent(
+ `${query} repo:${owner}/${repoName}`,
+ );
+ const results = await fetchGH(
+ `/search/code?q=${searchQuery}&per_page=${maxResults}`,
+ ctx?.abort,
+ );
- if (!results.items?.length) return `No results for: ${query}`
+ if (!results.items?.length) return `No results for: ${query}`;
const formatted = results.items
.slice(0, maxResults)
.map((item: any) => `${item.path}`)
- .join("\n")
+ .join("\n");
- return `Found ${results.total_count} results (showing ${Math.min(maxResults, results.items.length)}):\n\n${formatted}`
+ return `Found ${results.total_count} results (showing ${Math.min(maxResults, results.items.length)}):\n\n${formatted}`;
} catch (e) {
- return `Search failed: ${e}`
+ if (e instanceof Error && e.name === "AbortError") {
+ return "Operation cancelled";
+ }
+ return `Search failed: ${e}`;
}
},
-})
+});
diff --git a/tool/semantic-memory.ts b/tool/semantic-memory.ts
new file mode 100644
index 0000000..3d18390
--- /dev/null
+++ b/tool/semantic-memory.ts
@@ -0,0 +1,190 @@
+import { tool } from "@opencode-ai/plugin";
+import { $ } from "bun";
+
+/**
+ * Semantic Memory - Local vector-based knowledge store
+ *
+ * Uses PGlite + pgvector + Ollama embeddings for semantic search.
+ * Configurable tool descriptions via environment variables
+ * (Qdrant MCP pattern) to customize agent behavior.
+ */
+
+// Rich descriptions that shape agent behavior (Qdrant MCP pattern)
+// Can be overridden via env vars for different contexts
+const STORE_DESCRIPTION =
+ process.env.TOOL_STORE_DESCRIPTION ||
+ "Persist important discoveries, decisions, and learnings for future sessions. Use for: architectural decisions, debugging breakthroughs, user preferences, project-specific patterns. Include context about WHY something matters.";
+const FIND_DESCRIPTION =
+ process.env.TOOL_FIND_DESCRIPTION ||
+ "Search your persistent memory for relevant context. Query BEFORE making architectural decisions, when hitting familiar-feeling bugs, or when you need project history. Returns semantically similar memories ranked by relevance.";
+
+async function runCli(args: string[], signal?: AbortSignal): Promise<string> {
+ try {
+ // Check abort before starting
+ if (signal?.aborted) return "Operation cancelled";
+
+ const result = await $`npx semantic-memory ${args}`.text();
+ return result.trim();
+ } catch (e: any) {
+ // Handle abort
+ if (signal?.aborted) {
+ return "Operation cancelled";
+ }
+ return `Error: ${e.stderr || e.message || e}`;
+ }
+}
+
+export const store = tool({
+ description: STORE_DESCRIPTION,
+ args: {
+ information: tool.schema.string().describe("The information to store"),
+ metadata: tool.schema
+ .string()
+ .optional()
+ .describe("Optional JSON metadata object"),
+ tags: tool.schema
+ .string()
+ .optional()
+ .describe("Comma-separated tags for categorization"),
+ collection: tool.schema
+ .string()
+ .optional()
+ .describe("Collection name (default: 'default')"),
+ },
+ async execute({ information, metadata, tags, collection }, ctx) {
+ const args = ["store", information];
+ if (metadata) args.push("--metadata", metadata);
+ if (tags) args.push("--tags", tags);
+ if (collection) args.push("--collection", collection);
+
+ return runCli(args, ctx?.abort);
+ },
+});
+
+export const find = tool({
+ description: FIND_DESCRIPTION,
+ args: {
+ query: tool.schema.string().describe("Natural language search query"),
+ limit: tool.schema
+ .number()
+ .optional()
+ .describe("Max results (default: 10)"),
+ collection: tool.schema
+ .string()
+ .optional()
+ .describe("Collection to search (default: 'default')"),
+ fts: tool.schema
+ .boolean()
+ .optional()
+ .describe("Use full-text search only (no embeddings)"),
+ expand: tool.schema
+ .boolean()
+ .optional()
+ .describe("Return full content instead of truncated preview"),
+ },
+ async execute({ query, limit, collection, fts, expand }, ctx) {
+ const args = ["find", query];
+ if (limit) args.push("--limit", String(limit));
+ if (collection) args.push("--collection", collection);
+ if (fts) args.push("--fts");
+ if (expand) args.push("--expand");
+
+ return runCli(args, ctx?.abort);
+ },
+});
+
+export const get = tool({
+ description:
+ "Get a specific memory by ID. Use when you need the full content of a memory from search results.",
+ args: {
+ id: tool.schema.string().describe("The memory ID to retrieve"),
+ },
+ async execute({ id }, ctx) {
+ return runCli(["get", id], ctx?.abort);
+ },
+});
+
+export const list = tool({
+ description: "List stored memories",
+ args: {
+ collection: tool.schema
+ .string()
+ .optional()
+ .describe("Collection to list (default: all)"),
+ },
+ async execute({ collection }, ctx) {
+ const args = ["list"];
+ if (collection) args.push("--collection", collection);
+ return runCli(args, ctx?.abort);
+ },
+});
+
+export const remove = tool({
+ description:
+ "Delete a memory by ID. Use when a memory is outdated, incorrect, or no longer relevant.",
+ args: {
+ id: tool.schema.string().describe("The memory ID to delete"),
+ },
+ async execute({ id }, ctx) {
+ return runCli(["delete", id], ctx?.abort);
+ },
+});
+
+export const stats = tool({
+ description: "Show memory statistics",
+ args: {},
+ async execute(_args, ctx) {
+ return runCli(["stats"], ctx?.abort);
+ },
+});
+
+export const check = tool({
+ description: "Check if Ollama is ready for embeddings",
+ args: {},
+ async execute(_args, ctx) {
+ return runCli(["check"], ctx?.abort);
+ },
+});
+
+export const validate = tool({
+ description:
+ "Validate/reinforce a memory to reset its decay timer. Use when you confirm a memory is still accurate and relevant. This refreshes the memory's relevance score in search results.",
+ args: {
+ id: tool.schema.string().describe("The memory ID to validate"),
+ },
+ async execute({ id }, ctx) {
+ return runCli(["validate", id], ctx?.abort);
+ },
+});
+
+export const migrate = tool({
+ description:
+ "Migrate database from PGlite 0.2.x to 0.3.x. Run with checkOnly=true first to see if migration is needed.",
+ args: {
+ checkOnly: tool.schema
+ .boolean()
+ .optional()
+ .describe("Only check if migration is needed, don't actually migrate"),
+ importFile: tool.schema
+ .string()
+ .optional()
+ .describe("Import a SQL dump file"),
+ generateScript: tool.schema
+ .boolean()
+ .optional()
+ .describe("Generate a migration helper script"),
+ noBackup: tool.schema
+ .boolean()
+ .optional()
+ .describe("Don't keep backup after migration"),
+ },
+ async execute({ checkOnly, importFile, generateScript, noBackup }, ctx) {
+ const args = ["migrate"];
+ if (checkOnly) args.push("--check");
+ if (importFile) args.push("--import", importFile);
+ if (generateScript) args.push("--generate-script");
+ if (noBackup) args.push("--no-backup");
+
+ return runCli(args, ctx?.abort);
+ },
+});
diff --git a/tool/tool-utils.ts b/tool/tool-utils.ts
new file mode 100644
index 0000000..9be700b
--- /dev/null
+++ b/tool/tool-utils.ts
@@ -0,0 +1,98 @@
+/**
+ * Maximum output length for tool responses (30K characters)
+ * OpenCode caps tool output at this limit to prevent context exhaustion
+ */
+export const MAX_OUTPUT = 30_000;
+
+/**
+ * Truncates tool output to a maximum length with a clear truncation message.
+ *
+ * @param output - The string output to potentially truncate
+ * @param maxLength - Maximum allowed length (default: MAX_OUTPUT)
+ * @returns Original string if under limit, otherwise truncated with notice
+ *
+ * @example
+ * ```ts
+ * const result = truncateOutput(largeString)
+ * // Returns: "content...[Output truncated at 30000 chars. 5000 chars omitted.]"
+ * ```
+ */
+export function truncateOutput(
+ output: string,
+ maxLength: number = MAX_OUTPUT,
+): string {
+ if (output.length <= maxLength) return output;
+
+ return (
+ output.slice(0, maxLength) +
+ `\n\n[Output truncated at ${maxLength} chars. ${output.length - maxLength} chars omitted.]`
+ );
+}
+
+/**
+ * Formats an unknown error into a consistent string representation.
+ * Handles Error objects, strings, and other types gracefully.
+ *
+ * @param error - The error to format (unknown type from catch blocks)
+ * @returns Formatted error string with stack trace when available
+ *
+ * @example
+ * ```ts
+ * try {
+ * await riskyOperation()
+ * } catch (error) {
+ * return formatError(error)
+ * }
+ * ```
+ */
+export function formatError(error: unknown): string {
+ if (error instanceof Error) {
+ const stackLines = error.stack?.split("\n").slice(0, 5).join("\n") || "";
+ return `${error.name}: ${error.message}${stackLines ? `\n\nStack trace (first 5 lines):\n${stackLines}` : ""}`;
+ }
+
+ if (typeof error === "string") {
+ return `Error: ${error}`;
+ }
+
+ if (error && typeof error === "object") {
+ try {
+ return `Error: ${JSON.stringify(error, null, 2)}`;
+ } catch {
+ return `Error: ${String(error)}`;
+ }
+ }
+
+ return `Unknown error: ${String(error)}`;
+}
+
+/**
+ * Wraps a promise with a timeout. Rejects if the promise doesn't resolve within the specified time.
+ *
+ * @param promise - The promise to wrap with a timeout
+ * @param ms - Timeout in milliseconds
+ * @returns Promise that resolves with the original value or rejects on timeout
+ * @throws {Error} "Operation timed out after {ms}ms" if timeout is reached
+ *
+ * @example
+ * ```ts
+ * try {
+ * const result = await withTimeout(fetchData(), 5000)
+ * } catch (error) {
+ * // Handle timeout or other errors
+ * }
+ * ```
+ */
+export async function withTimeout<T>(
+ promise: Promise<T>,
+ ms: number,
+): Promise<T> {
+ const timeout = new Promise<never>((_, reject) =>
+ setTimeout(
+ () => reject(new Error(`Operation timed out after ${ms}ms`)),
+ ms,
+ ),
+ );
+
+ return Promise.race([promise, timeout]);
+}
diff --git a/tool/ubs.ts b/tool/ubs.ts
new file mode 100644
index 0000000..4cbc183
--- /dev/null
+++ b/tool/ubs.ts
@@ -0,0 +1,104 @@
+import { tool } from "@opencode-ai/plugin";
+import { $ } from "bun";
+
+/**
+ * UBS - Ultimate Bug Scanner
+ *
+ * Multi-language bug scanner that catches what humans and AI miss:
+ * null safety, XSS, async/await bugs, memory leaks, type coercion issues.
+ *
+ * Supports: JavaScript/TypeScript, Python, C/C++, Rust, Go, Java, Ruby, Swift
+ *
+ * Run BEFORE committing to catch bugs early. Exit 0 = clean, Exit 1 = issues found.
+ */
+
+async function runUbs(args: string[]): Promise<string> {
+ try {
+ const result = await $`ubs ${args}`.text();
+ return result.trim();
+ } catch (e: any) {
+ // ubs exits non-zero when it finds issues - that's expected behavior
+ const stdout = e.stdout?.toString() || "";
+ const stderr = e.stderr?.toString() || "";
+ if (stdout) return stdout.trim();
+ if (stderr) return stderr.trim();
+ return `Error: ${e.message || e}`;
+ }
+}
+
+export const scan = tool({
+ description:
+ "Scan code for bugs: null safety, XSS, async/await issues, memory leaks, type coercion. Run BEFORE committing. Supports JS/TS, Python, C++, Rust, Go, Java, Ruby.",
+ args: {
+ path: tool.schema
+ .string()
+ .optional()
+ .describe("Path to scan (default: current directory)"),
+ only: tool.schema
+ .string()
+ .optional()
+ .describe(
+ "Restrict to languages: js,python,cpp,rust,golang,java,ruby,swift",
+ ),
+ staged: tool.schema
+ .boolean()
+ .optional()
+ .describe("Scan only files staged for commit"),
+ diff: tool.schema
+ .boolean()
+ .optional()
+ .describe("Scan only modified files (working tree vs HEAD)"),
+ failOnWarning: tool.schema
+ .boolean()
+ .optional()
+ .describe("Exit non-zero if warnings exist (default for CI)"),
+ },
+ async execute({ path, only, staged, diff, failOnWarning }) {
+ const args: string[] = [];
+ if (staged) args.push("--staged");
+ if (diff) args.push("--diff");
+ if (only) args.push(`--only=${only}`);
+ if (failOnWarning) args.push("--fail-on-warning");
+ args.push(path || ".");
+ return runUbs(args);
+ },
+});
+
+export const scan_json = tool({
+ description:
+ "Scan code for bugs with JSON output. Better for parsing results programmatically.",
+ args: {
+ path: tool.schema
+ .string()
+ .optional()
+ .describe("Path to scan (default: current directory)"),
+ only: tool.schema
+ .string()
+ .optional()
+ .describe(
+ "Restrict to languages: js,python,cpp,rust,golang,java,ruby,swift",
+ ),
+ },
+ async execute({ path, only }) {
+ const args = ["--format=json", "--ci"];
+ if (only) args.push(`--only=${only}`);
+ args.push(path || ".");
+ return runUbs(args);
+ },
+});
+
+export const doctor = tool({
+ description:
+ "Check UBS health: validate modules, dependencies, and configuration.",
+ args: {
+ fix: tool.schema
+ .boolean()
+ .optional()
+ .describe("Automatically download or refresh cached modules"),
+ },
+ async execute({ fix }) {
+ const args = ["doctor"];
+ if (fix) args.push("--fix");
+ return runUbs(args);
+ },
+});
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..68b76a9
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,14 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "lib": ["ES2015", "ES2022"],
+ "module": "ESNext",
+ "moduleResolution": "node",
+ "types": ["bun-types", "@types/node"],
+ "noEmit": true,
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "allowSyntheticDefaultImports": true
+ },
+ "include": ["tool/**/*.ts", "plugin/**/*.ts"]
+}