opencode-thrum-pro 0.1.0

package/assets/skills/writing-durable-markdown/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: writing-durable-markdown
+description: "Use when creating or editing ANY markdown file - CLAUDE.md, a role preamble, a SKILL.md, a runbook, project state, State.md, a spec, a plan, a README, or docs. Fires on adding a rule, writing a note, correcting a wrong claim, recording a lesson, or documenting an incident. Enforces state-the-rule-and-stop, because narrative in a loaded file costs tokens at every wake and leaves contradictions nobody can untangle."
+---
+
+# Writing or editing ANY markdown file — state the rule and stop
+
+Not what was done. Not why it was wrong. Not what the previous version said. Not
+what not to do. Not the incident. **Just the rule, in the imperative.**
+
+## Before you save: measure
+
+```bash
+git diff --numstat -- <file>
+```
+
+**More than ~5 added lines for one rule means you wrote a story.** Cut it.
+
+## The three costs
+
+**1. Tokens, paid at every wake, by everyone.** `CLAUDE.md`, role preambles and
+state files are injected into every agent's context at every wake. A 40-line
+explanation is not paid once by the author — it is paid by every agent, every
+session, forever. Inside a session it is worse than linear: injected text is
+re-read on every later turn.
+
+**2. Contradiction.** Stories assert facts. Three stories about one rule disagree
+about its scope, whether it still applies, and which version is current. **An
+agent cannot tell which sentence is authoritative, so it obeys both.** Prose rots
+silently — a test goes red when it drifts, a paragraph never does.
+
+**3. Abandonment.** Past a certain size nobody can audit the file for
+contradictions, so nobody tries, and the contradictions become permanent.
+**The bloat is what makes the file unfixable** — every story added removes
+someone's ability to fix the story before it.
+
+## A correction replaces; it does not accumulate
+
+Delete the wrong text and write the right rule in its place. A correction left
+*beside* what it corrects leaves two claims and no way to rank them. Corrections
+are always longer than what they replace, so this is the main way these files
+grow.
+
+## Where the story goes
+
+`thrum memory` — retrieved on demand by the agent who needs it, instead of
+injected into everyone. Keep the rule in the doc; leave at most a one-line
+pointer.
+
+## Exempt from the cap
+
+Tables, CLI output, command strings, file paths, enumerated vocabularies. **Never
+truncate those to hit a line count.** The cap stops narrative; it does not
+shorten data.
+
+## Shipped content carries no internal particulars
+
+No issue IDs, no dates, no agent names, no measurements in customer-facing files.
+The tracker references the change; the change never references the tracker.
+
+## A skill is generic — never specific to the repo you edit from
+
+Write the rule so it holds for any repo running the skill. No repo names, config
+keys, box names, agent names, or paths particular to the repo you happen to be in.
+Repo-specific values live in that repo's config or memory; the skill names them by
+role, not by literal.

package/dist/hooks/block-sync-cd.d.ts

@@ -0,0 +1,9 @@
+/** Returns true if the command must be blocked. Exported for testing. */
+export declare function isBlockedCommand(command: string): boolean;
+export declare function blockSyncCdHook(): (input: {
+    tool: string;
+    sessionID: string;
+    callID: string;
+}, output: {
+    args: Record<string, any>;
+}) => Promise<void>;

package/dist/hooks/block-sync-cd.js

@@ -0,0 +1,71 @@
+// tool.execute.before hook: protect the a-sync JSONL worktree from destruction.
+//
+// .git/thrum-sync/a-sync/ is a detached git worktree living INSIDE .git/.
+// It holds the append-only JSONL event log for thrum message sync.
+//
+// DANGER: If you check out a different branch in that worktree, git replaces
+// its contents — but since it lives inside .git/, this DESTROYS the git object
+// store, refs, and config. The entire repo and ALL worktrees are wiped.
+//
+// This happened once and required significant effort to recover.
+//
+// Faithful port of claude-plugin/scripts/block-sync-worktree-cd.sh (4 patterns
+// + command-position anchor). OpenCode contract: throwing inside
+// tool.execute.before ABORTS the tool call (the bash command never runs) —
+// verified against sst/opencode plugin dispatch (raw `yield*`, no catch).
+//
+// Blocked:
+//   1. cd/pushd/chdir into the a-sync worktree (prevents arbitrary commands there)
+//   2. git -C <a-sync-path> with branch-changing commands (checkout, switch,
+//      reset, merge, rebase, pull) — these change HEAD without cd
+//   3. git --work-tree=<a-sync-path> with branch-changing commands
+//   4. git --git-dir=<a-sync-path> with branch-changing commands
+//
+// Allowed:
+//   git -C <a-sync-path> add/commit/push/status/rm/log/diff — safe operations
+//   ls/cat/grep/rm on absolute paths — no CWD change
+// Matches the literal sync-worktree path. Mirrors SYNC_PATTERN in the bash hook.
+const SYNC = String.raw `\.git/thrum-sync/a-sync`;
+// Command-position anchor: line start or immediately after a shell separator
+// (;, &&, ||), then optional whitespace. This matches `cd`/`git` only when they
+// are the actual command — NOT when those words appear inside a quoted argument
+// preceded by a bare space (the D5 false-positive: `bd remember "... cd
+// .git/thrum-sync/a-sync ..."` must NOT be denied). Match op-shape, not the mere
+// presence of the path string.
+const CMDPOS = String.raw `(^|;|&&|\|\|)\s*`;
+// Branch-changing git subcommands that mutate HEAD / working tree.
+const BRANCH_CHANGING = String.raw `(checkout|switch|reset|merge|rebase|pull)\b`;
+// The `m` flag makes `^` in CMDPOS match the start of each line, mirroring the
+// line-by-line behavior of `echo "$command" | grep -E` in the bash hook.
+const PATTERNS = [
+    // 1. cd/pushd/chdir into the a-sync worktree (command-position only)
+    new RegExp(String.raw `${CMDPOS}(cd|pushd|chdir)\s+['"]?[^\s]*${SYNC}`, "m"),
+    // 2. git -C <a-sync-path> with a branch-changing command
+    new RegExp(String.raw `${CMDPOS}git\s+-C\s+['"]?[^\s]*${SYNC}['"]?\s+${BRANCH_CHANGING}`, "m"),
+    // 3. git --work-tree=<a-sync-path> ... branch-changing command
+    new RegExp(String.raw `${CMDPOS}git\s+--work-tree[= ]['"]?[^\s]*${SYNC}['"]?\s+.*${BRANCH_CHANGING}`, "m"),
+    // 4. git --git-dir=<a-sync-path> ... branch-changing command
+    new RegExp(String.raw `${CMDPOS}git\s+--git-dir[= ]['"]?[^\s]*${SYNC}['"]?\s+.*${BRANCH_CHANGING}`, "m"),
+];
+const DENY_MESSAGE = "BLOCKED: branch-changing git operations on (or cd into) the " +
+    ".git/thrum-sync/a-sync/ worktree are forbidden. That worktree lives INSIDE " +
+    ".git/ — checking out a different branch there DESTROYS the entire git object " +
+    "store, wiping the repo and all worktrees. Use absolute paths with safe " +
+    "operations (ls, grep, rm, git -C ... add/commit/push) instead.";
+/** Returns true if the command must be blocked. Exported for testing. */
+export function isBlockedCommand(command) {
+    if (!command)
+        return false;
+    return PATTERNS.some((re) => re.test(command));
+}
+export function blockSyncCdHook() {
+    return async (input, output) => {
+        if (input.tool !== "bash")
+            return;
+        const cmd = String(output.args?.command ?? "");
+        if (isBlockedCommand(cmd)) {
+            // Throwing aborts the tool call in OpenCode (tool.execute.before contract).
+            throw new Error(DENY_MESSAGE);
+        }
+    };
+}

package/dist/hooks/block-sync-cd.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/block-sync-cd.test.js

@@ -0,0 +1,61 @@
+// Regression tests for the a-sync worktree guard (block-sync-cd.ts).
+// Mirrors claude-plugin/scripts/block-sync-worktree-cd_test.sh so the OpenCode
+// port stays behavior-faithful to the reference bash hook.
+//
+// Run: npm test  (builds, then `node --test dist`)
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { isBlockedCommand, blockSyncCdHook } from "./block-sync-cd.js";
+const ASYNC = ".git/thrum-sync/a-sync";
+// DENY: branch-changing ops on / cd into the a-sync worktree.
+const DENY = [
+    ["cd into a-sync", `cd ${ASYNC}`],
+    ["pushd into a-sync", `pushd ${ASYNC}`],
+    ["cd after &&", `git status && cd ${ASYNC}`],
+    ["cd after ;", `echo hi; cd ${ASYNC}`],
+    ["git -C a-sync checkout", `git -C ${ASYNC} checkout main`],
+    ["git -C a-sync switch", `git -C ${ASYNC} switch main`],
+    ["git -C a-sync reset --hard", `git -C ${ASYNC} reset --hard`],
+    ["git -C a-sync merge", `git -C ${ASYNC} merge main`],
+    ["git -C a-sync rebase", `git -C ${ASYNC} rebase main`],
+    ["git -C a-sync pull", `git -C ${ASYNC} pull`],
+    ["git --work-tree= checkout", `git --work-tree=${ASYNC} checkout main`],
+    ["git --git-dir= checkout", `git --git-dir=${ASYNC} checkout main`],
+];
+// ALLOW: safe ops on a-sync, non-command-position mentions, unrelated commands.
+const ALLOW = [
+    ["bare git status", "git status"],
+    ["git -C a-sync add", `git -C ${ASYNC} add .`],
+    ["git -C a-sync status", `git -C ${ASYNC} status`],
+    ["git -C a-sync commit", `git -C ${ASYNC} commit -m x`],
+    ["git -C a-sync push", `git -C ${ASYNC} push`],
+    ["git -C a-sync log (not branch-changing)", `git -C ${ASYNC} log --oneline`],
+    ["ls the path", `ls ${ASYNC}/`],
+    // D5 false-positive guard: cd inside a quoted argument (bare space before it),
+    // not at command position -> must be ALLOWED.
+    ["quoted cd inside bd remember", `bd remember "note: do not cd ${ASYNC} directly"`],
+];
+for (const [name, cmd] of DENY) {
+    test(`DENY: ${name}`, () => {
+        assert.equal(isBlockedCommand(cmd), true, `expected blocked: ${cmd}`);
+    });
+}
+for (const [name, cmd] of ALLOW) {
+    test(`ALLOW: ${name}`, () => {
+        assert.equal(isBlockedCommand(cmd), false, `expected allowed: ${cmd}`);
+    });
+}
+// Contract: the hook THROWS on a blocked bash command (OpenCode aborts the
+// tool call on throw) and resolves for allowed / non-bash tools.
+test("hook throws on blocked bash command", async () => {
+    const hook = blockSyncCdHook();
+    await assert.rejects(() => hook({ tool: "bash", sessionID: "s", callID: "c" }, { args: { command: `git -C ${ASYNC} checkout main` } }));
+});
+test("hook resolves on allowed bash command", async () => {
+    const hook = blockSyncCdHook();
+    await assert.doesNotReject(() => hook({ tool: "bash", sessionID: "s", callID: "c" }, { args: { command: `git -C ${ASYNC} add .` } }));
+});
+test("hook ignores non-bash tools", async () => {
+    const hook = blockSyncCdHook();
+    await assert.doesNotReject(() => hook({ tool: "read", sessionID: "s", callID: "c" }, { args: { command: `cd ${ASYNC}` } }));
+});

package/dist/hooks/shell-env.d.ts

@@ -0,0 +1,8 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function shellEnvHook(ctx: PluginInput): (input: {
+    cwd: string;
+    sessionID?: string;
+    callID?: string;
+}, output: {
+    env: Record<string, string>;
+}) => Promise<void>;

package/dist/hooks/shell-env.js

@@ -0,0 +1,22 @@
+import fs from "fs";
+import path from "path";
+export function shellEnvHook(ctx) {
+    return async (input, output) => {
+        const dirs = [input.cwd, ctx.directory, ctx.worktree].filter(Boolean);
+        for (const dir of dirs) {
+            const identityPath = path.join(dir, ".thrum", "identity.json");
+            try {
+                const raw = fs.readFileSync(identityPath, "utf8");
+                const identity = JSON.parse(raw);
+                output.env.THRUM_NAME = identity.agent_id ?? "";
+                output.env.THRUM_ROLE = identity.role ?? "";
+                output.env.THRUM_MODULE = identity.module ?? "";
+                output.env.THRUM_HOME = dir;
+                return;
+            }
+            catch {
+                // No identity file in this dir, try next
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,25 @@
+import { installAssets } from "./installer.js";
+import { shellEnvHook } from "./hooks/shell-env.js";
+import { blockSyncCdHook } from "./hooks/block-sync-cd.js";
+const TOOL_MAPPING = `
+## Thrum Plugin — Tool Mapping for OpenCode
+
+When Thrum skills reference Claude Code tool names, use these OpenCode equivalents:
+- TodoWrite → todowrite
+- Task (subagents) → @mention syntax (e.g., @explore, @general)
+- Skill tool → OpenCode's native skill tool
+- Agent tool → @mention syntax for subagents
+- Read, Write, Edit, Bash → your native tools (same names, lowercase)
+`.trim();
+const server = async (ctx) => {
+    await installAssets(ctx);
+    return {
+        "shell.env": shellEnvHook(ctx),
+        "tool.execute.before": blockSyncCdHook(),
+        "experimental.chat.system.transform": async (_input, output) => {
+            ;
+            (output.system ||= []).push(TOOL_MAPPING);
+        },
+    };
+};
+export default { id: "opencode-thrum", server };

package/dist/installer.d.ts

@@ -0,0 +1,2 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export declare function installAssets(ctx: PluginInput): Promise<void>;

package/dist/installer.js

@@ -0,0 +1,86 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ASSETS_DIR = path.resolve(__dirname, "..", "assets");
+const VERSION_FILE = ".thrum-plugin-version";
+function getPluginVersion() {
+    const pkgPath = path.resolve(__dirname, "..", "package.json");
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function getConfigDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg)
+        return path.join(xdg, "opencode");
+    return path.join(os.homedir(), ".config", "opencode");
+}
+function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export async function installAssets(ctx) {
+    const configDir = getConfigDir();
+    const skillsDir = path.join(configDir, "skills");
+    const commandsDir = path.join(configDir, "commands");
+    const versionPath = path.join(skillsDir, "thrum", VERSION_FILE);
+    const currentVersion = getPluginVersion();
+    // Check if already installed at this version
+    try {
+        const installed = fs.readFileSync(versionPath, "utf8").trim();
+        if (installed === currentVersion)
+            return;
+    }
+    catch {
+        // Not installed yet
+    }
+    const log = (msg) => ctx.client.app.log({
+        body: { service: "opencode-thrum", level: "info", message: msg },
+    });
+    // Copy each skill subdirectory
+    const assetsSkillsDir = path.join(ASSETS_DIR, "skills");
+    if (fs.existsSync(assetsSkillsDir)) {
+        for (const entry of fs.readdirSync(assetsSkillsDir, {
+            withFileTypes: true,
+        })) {
+            if (!entry.isDirectory())
+                continue;
+            const src = path.join(assetsSkillsDir, entry.name);
+            const dest = path.join(skillsDir, entry.name);
+            copyDirRecursive(src, dest);
+            await log(`Installed skill: ${entry.name}`);
+        }
+    }
+    // Copy commands
+    const assetsCommandsDir = path.join(ASSETS_DIR, "commands");
+    if (fs.existsSync(assetsCommandsDir)) {
+        fs.mkdirSync(commandsDir, { recursive: true });
+        let count = 0;
+        for (const entry of fs.readdirSync(assetsCommandsDir)) {
+            if (!entry.endsWith(".md"))
+                continue;
+            fs.copyFileSync(path.join(assetsCommandsDir, entry), path.join(commandsDir, entry));
+            count++;
+        }
+        await log(`Installed ${count} commands`);
+    }
+    // Write version marker
+    fs.mkdirSync(path.dirname(versionPath), { recursive: true });
+    fs.writeFileSync(versionPath, currentVersion);
+    await log(`opencode-thrum v${currentVersion} assets installed`);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opencode-thrum-pro",
+  "version": "0.1.0",
+  "description": "Thrum multi-agent coordination plugin for Open Code",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "npm run build && node --test dist",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "thrum",
+    "multi-agent",
+    "coordination"
+  ],
+  "author": "Leon Letto",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonletto/thrum-pro.git",
+    "directory": "opencode-plugin"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.0",
+    "@types/node": "^25.5.2",
+    "typescript": "^5.3.0"
+  }
+}