feat!: builder 2 — the builder soul, agent-led setup and peer messaging

.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "builder",
+  "interface": { "displayName": "builder" },
+  "plugins": [
+    {
+      "name": "builder",
+      "source": { "source": "url", "url": "./" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Developer Tools"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "builder",
-  "description": "Operational tools for running AI coding agents at scale — recurring monitoring of Claude subscription usage limits (weekly/5h burn rate), session/context load with compaction picks, ctx-wire token savings, and per-repo codebase-memory graphs (kept fresh) so agents query structure instead of grep-reading",
+  "description": "Builder habits for coding agents: guided setup, decisions with reasons, proof before done, and nothing sent without your yes.",
   "version": "0.1.4",
   "author": {
     "name": "Lutherwaves"
@@ -10,18 +10,18 @@
   "license": "MIT",
   "keywords": [
     "claude-code",
-    "usage-limits",
-    "burn-rate",
-    "rate-limit",
-    "cctop",
-    "ctx-wire",
-    "context",
-    "compaction",
-    "monitoring",
-    "agent-ops",
-    "codebase-memory",
+    "soul",
+    "onboarding",
+    "shaping",
+    "rulings",
+    "peer-messaging",
+    "fleet",
+    "usage-budget",
+    "harness",
     "code-graph",
-    "indexing",
-    "skills"
+    "codex",
+    "cursor",
+    "opencode",
+    "agent-skills"
   ]
 }

.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "builder",
+  "version": "0.1.4",
+  "description": "Builder habits for coding agents: guided setup, decisions with reasons, proof before done, and nothing sent without your yes.",
+  "author": { "name": "Lutherwaves" },
+  "homepage": "https://github.com/Lutherwaves/builder",
+  "repository": "https://github.com/Lutherwaves/builder",
+  "license": "MIT",
+  "keywords": ["claude-code","soul","onboarding","shaping","rulings","peer-messaging","fleet","usage-budget","harness","code-graph","codex","cursor","opencode","agent-skills"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "builder",
+    "shortDescription": "Guided setup, decisions with reasons, proof before done",
+    "developerName": "Lutherwaves",
+    "category": "Developer Tools",
+    "capabilities": ["Interactive", "Read", "Write"]
+  }
+}

.cursor-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "builder",
+  "displayName": "builder",
+  "version": "0.1.4",
+  "description": "Builder habits for coding agents: guided setup, decisions with reasons, proof before done, and nothing sent without your yes.",
+  "author": { "name": "Lutherwaves" },
+  "homepage": "https://github.com/Lutherwaves/builder",
+  "repository": "https://github.com/Lutherwaves/builder",
+  "license": "MIT",
+  "keywords": ["claude-code","soul","onboarding","shaping","rulings","peer-messaging","fleet","usage-budget","harness","code-graph","codex","cursor","opencode","agent-skills"],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks-cursor.json"
+}

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,5 +19,5 @@ labels: bug
 
 - OS:
 - Claude Code version:
-- `cctop` / `ctx-wire` present? (`command -v cctop ctx-wire`)
+- `matchblox` present? (`command -v matchblox`)
 - `bash scripts/validate.sh` result:

.github/workflows/validate.yml

@@ -2,6 +2,7 @@ name: validate
 
 on:
   pull_request:
+    types: [opened, synchronize, reopened, edited]
   push:
     branches: [main]
 
@@ -13,5 +14,44 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Check the pull request title and every commit subject
+        if: github.event_name == 'pull_request'
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          rc=0
+          printf '%s\n' "$PR_TITLE" | bash scripts/check-subjects.sh > "$RUNNER_TEMP/bad.txt" || rc=1
+          git log "$BASE_SHA..$HEAD_SHA" --format=%s | bash scripts/check-subjects.sh >> "$RUNNER_TEMP/bad.txt" || rc=1
+          if [ "$rc" -ne 0 ]; then
+            echo "Not Conventional Commits (type(scope)?: outcome):"
+            cat "$RUNNER_TEMP/bad.txt"
+            exit 1
+          fi
       - name: Validate plugin manifests, skills, and scripts
-        run: bash scripts/validate.sh
+        env:
+          DENYLIST_SECRET: ${{ secrets.BUILDER_DENYLIST }}
+        run: |
+          if [ -n "$DENYLIST_SECRET" ]; then
+            printf '%s\n' "$DENYLIST_SECRET" > "$RUNNER_TEMP/deny.txt"
+            export BUILDER_DENYLIST="$RUNNER_TEMP/deny.txt"
+          fi
+          bash scripts/validate.sh
+
+  validate-tests:
+    # The tests of the guards above: the scrub, the skill shape and the subject check.
+    # A guard whose test never runs is a wish (tenet 9). About 5 minutes; runs beside `validate`.
+    # An edit of the title or body changes no code, so it does not run these tests again.
+    if: github.event.action != 'edited'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - name: Test the validator's guards
+        run: bash tests/test_validate.sh

.gitignore

@@ -1,4 +1,2 @@
 __pycache__/
 *.pyc
-usage.json
-ctxwire-last.json

.opencode/plugins/builder.js

@@ -0,0 +1,224 @@
+/**
+ * builder plugin for OpenCode.
+ *
+ * V1 (opencode 1.x): named export BuilderPlugin. The config hook registers the
+ * skills directory. experimental.chat.messages.transform injects the builder
+ * soul once into the first user message of a top-level session.
+ *
+ * V2 (opencode 2.x): default export { id, server, setup }. setup() registers
+ * every skill with ctx.skill.transform and injects the soul with
+ * ctx.session.hook("context").
+ *
+ * No dependencies. The only exports are BuilderPlugin and the default object: older 1.x hosts call each export.
+ */
+
+import path from "path";
+import fs from "fs";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "../..");
+const skillsDir = path.join(root, "skills");
+const MARKER = "builder root:";
+
+// Test seam: tests set globalThis.__builderSpawn. It is not an export, because opencode 1.x calls every export as a plugin factory.
+const spawn = (...args) =>
+  (typeof globalThis.__builderSpawn === "function" ? globalThis.__builderSpawn : spawnSync)(...args);
+
+const readSoul = () => {
+  try {
+    return fs.readFileSync(path.join(skillsDir, "builder", "soul-compact.md"), "utf8");
+  } catch {
+    return null;
+  }
+};
+
+const runHook = () => {
+  try {
+    const result = spawn(
+      "python3",
+      [path.join(root, "hooks", "session_start.py"), "--harness", "opencode", "--format", "text"],
+      { timeout: 1000, encoding: "utf8" },
+    );
+    if (result && !result.error && result.status === 0 && typeof result.stdout === "string" && result.stdout.trim()) {
+      return result.stdout;
+    }
+  } catch {
+    // fall through to the soul
+  }
+  return readSoul();
+};
+
+// sessionID -> bootstrap text. The hook fires on every agent step, so run python once per session.
+const CACHE_MAX = 512;
+const _bootstrapCache = new Map();
+
+const bound = (cache) => {
+  if (cache.size < CACHE_MAX) return;
+  let toDrop = Math.ceil(CACHE_MAX / 4);
+  for (const key of cache.keys()) {
+    if (toDrop-- <= 0) break;
+    cache.delete(key);
+  }
+};
+
+const getBootstrap = (sessionID) => {
+  if (sessionID && _bootstrapCache.has(sessionID)) return _bootstrapCache.get(sessionID);
+  const text = runHook();
+  if (sessionID) {
+    bound(_bootstrapCache);
+    _bootstrapCache.set(sessionID, text);
+  }
+  return text;
+};
+
+// A session with a parentID is a subagent session: it does not get the bootstrap.
+const _childSessionCache = new Map();
+
+const isChildSession = async (fetchSession, sessionID) => {
+  if (!sessionID) return false;
+  if (_childSessionCache.has(sessionID)) return _childSessionCache.get(sessionID);
+
+  let isChild = false;
+  try {
+    const result = await fetchSession(sessionID);
+    // V1 returns an SDK envelope, V2 a direct session record.
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+      throw new Error("Session lookup returned no usable record");
+    }
+    if (result.error != null || result.response?.ok === false) {
+      throw new Error("Session lookup was unsuccessful");
+    }
+    const session = "data" in result ? result.data : result;
+    if (!session || typeof session !== "object" || Array.isArray(session) || session.id !== sessionID) {
+      throw new Error("Session lookup returned an invalid session identity");
+    }
+    if (session.parentID !== undefined && (typeof session.parentID !== "string" || session.parentID.length === 0)) {
+      throw new Error("Session lookup returned an invalid parent identity");
+    }
+    isChild = session.parentID !== undefined;
+  } catch (err) {
+    // Fail open and do not cache, so a transient failure can recover on the next step.
+    console.error("[builder] session lookup failed, treating session as top-level:", err);
+    return false;
+  }
+  bound(_childSessionCache);
+  _childSessionCache.set(sessionID, isChild);
+  return isChild;
+};
+
+const extractFrontmatter = (content) => {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+  const frontmatter = {};
+  let lastKey = null;
+  for (const rawLine of match[1].split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+    const colonIdx = line.indexOf(":");
+    if (colonIdx > 0 && !/^\s/.test(line)) {
+      lastKey = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim();
+      frontmatter[lastKey] = /^(>[+-]?|\|[+-]?)$/.test(value) ? "" : value;
+    } else if (lastKey !== null && line.trim() !== "") {
+      frontmatter[lastKey] = `${frontmatter[lastKey]} ${line.trim()}`.trim();
+    }
+  }
+  for (const key of Object.keys(frontmatter)) {
+    frontmatter[key] = frontmatter[key].replace(/^(["'])([\s\S]*)\1$/, "$2");
+  }
+  return { frontmatter, body: match[2] };
+};
+
+export const BuilderPlugin = async ({ client }) => ({
+  config: async (config) => {
+    // V2: skills is a flat array and setup() registers them.
+    if (Array.isArray(config.skills)) return;
+    config.skills = config.skills || {};
+    config.skills.paths = config.skills.paths || [];
+    if (!config.skills.paths.includes(skillsDir)) config.skills.paths.push(skillsDir);
+  },
+
+  "experimental.chat.messages.transform": async (_input, output) => {
+    if (!output.messages.length) return;
+    const firstUser = output.messages.find((m) => m.info.role === "user");
+    if (!firstUser || !firstUser.parts.length) return;
+    if (firstUser.parts.some((p) => p.type === "text" && p.text.includes(MARKER))) return;
+    // V1 passes no input to this hook, so take the sessionID from the message.
+    const sessionID = firstUser.info.sessionID;
+    if (client && (await isChildSession((id) => client.session.get({ path: { id } }), sessionID))) return;
+    const bootstrap = getBootstrap(sessionID);
+    if (!bootstrap) return;
+    firstUser.parts.unshift({ ...firstUser.parts[0], type: "text", text: bootstrap });
+  },
+});
+
+async function setup(ctx) {
+  // V1 also calls default.setup, with a ctx that lacks the skill and session domains.
+  if (!ctx || !ctx.skill || typeof ctx.skill.transform !== "function" || !ctx.session || typeof ctx.session.hook !== "function") {
+    return;
+  }
+
+  try {
+    const skills = [];
+    if (fs.existsSync(skillsDir)) {
+      for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+        const skillPath = path.join(skillsDir, entry.name, "SKILL.md");
+        if (!fs.existsSync(skillPath)) continue;
+        const { frontmatter, body } = extractFrontmatter(fs.readFileSync(skillPath, "utf8"));
+        skills.push({
+          id: entry.name,
+          name: frontmatter.name || entry.name,
+          ...(frontmatter.description ? { description: frontmatter.description } : {}),
+          path: skillPath,
+          content: body,
+        });
+      }
+    }
+    await ctx.skill.transform((draft) => {
+      // A throw escaping this callback disables the whole plugin, so contain each skill.
+      for (const skill of skills) {
+        try {
+          draft.add(skill);
+        } catch (err) {
+          console.error(`[builder] skill "${skill.id}" rejected by host, skipping:`, err);
+        }
+      }
+    });
+  } catch (err) {
+    console.error("[builder] skill registration failed:", err);
+  }
+
+  try {
+    await ctx.session.hook("context", async (event) => {
+      try {
+        if (!event.messages || !event.messages.length) return;
+        const firstUser = event.messages.find((m) => m.role === "user");
+        if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
+        if (firstUser?.content.some((p) => p.type === "text" && p.text && p.text.includes(MARKER))) return;
+        if (
+          typeof ctx.session.get === "function" &&
+          (await isChildSession((id) => ctx.session.get({ sessionID: id }), event.sessionID))
+        ) return;
+        const bootstrap = getBootstrap(event.sessionID);
+        if (!bootstrap) return;
+        if (firstUser) {
+          firstUser.content.unshift({ type: "text", text: bootstrap });
+        } else {
+          event.messages.push({ role: "user", content: [{ type: "text", text: bootstrap }] });
+        }
+      } catch (err) {
+        console.error("[builder] context hook failed:", err);
+      }
+    });
+  } catch (err) {
+    console.error("[builder] session hook registration failed:", err);
+  }
+}
+
+export default {
+  id: "builder",
+  server: BuilderPlugin,
+  setup,
+};