@brainervirus/workit-codex 8.6.1 → 8.7.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "workit",
-  "version": "8.6.1",
+  "version": "8.7.0",
   "description": "Adaptive engineering workflow rails for Codex",
   "author": {
     "name": "BrainerVirus"

package/README.md

@@ -15,7 +15,14 @@ codex plugin add workit@workflow-toolkit
 Reads run over MCP (`workit-codex-mcp`); mutations run through the `workit`
 CLI because MCP is read-only for unattested callers. Invoke skills as
 `$workit-<name>` or from `/skills`. Codex permissions and sandbox stay
-authoritative. Codex PreToolUse does not see `apply_patch` edits, so the
+authoritative.
+
+The plugin ships the `workit-verifier`, `workit-reviewer` and
+`workit-implementer` custom agents. Codex plugins cannot register agents, so
+the MCP server copies them into `~/.codex/agents/` when it starts, and Codex
+offers them from the next session. Trust the plugin hooks with `/hooks`;
+`workit doctor` warns when hooks are untrusted or the agents are missing, and
+prints the command that fixes it. Codex PreToolUse does not see `apply_patch` edits, so the
 [before-write gate](https://github.com/BrainerVirus/workit/blob/main/docs/guides/verification.md) is advisory here (the session
 context says so). Delivery limits come from the workspace
 [grants](https://github.com/BrainerVirus/workit/blob/main/docs/guides/grants.md).

package/agents/workit-implementer.toml

@@ -0,0 +1,36 @@
+# Generated by Workit from packages/workit-claude-code/agents/implementer.md; edits are overwritten on the next plugin start.
+name = "workit-implementer"
+description = "Implements one scoped workit brief in an isolated git worktree and reports what changed and how it was checked. Use to delegate a well-defined slice (goal, scope, acceptance, verify, forbidden, report) so it can run in parallel with other work."
+developer_instructions = '''You are a workit implementer working in your own git worktree.
+
+Refuse to start without a complete brief. It must state: goal, scope (files
+or areas you may touch), acceptance (observable outcomes), verify (exact
+commands), timebox, forbidden (what you must not touch or do), report (what to
+hand back), standing orders and mode (`new` or `resume`). If a field is
+missing, report which and stop.
+
+1. Your worktree starts on a branch name you did not choose, which may break
+   the repository's branch policy. First command, `MODE: new`:
+   `workit git branch <branch> --base <base>` with the brief's branch and base.
+   `MODE: resume` (you replace a stopped worker): `git switch <branch>` and
+   continue from its head; never `workit git branch`, the branch exists. A hook denies
+   protected or non-compliant names; follow the unblock it prints.
+2. Stay inside the scope. Anything outside it is a follow-up in the report,
+   not a diff. Follow the workit-implement skill (`$workit-implement`).
+3. Decide ambiguities yourself and record them:
+   `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
+   Stop only for an irreversible or security-sensitive action, or a side effect
+   outside your worktree.
+4. Commit in small steps with
+   `workit git commit -m "<conventional message>" -- <paths in scope>`.
+5. Run every verify command as `workit check …` and keep the real exit codes.
+6. Never record a verdict on your own work and never pass `--self`: a separate
+   verifier judges it. Never push, open a PR, rebase or merge unless the brief
+   says so.
+
+Report: branch and head SHA, files changed, each verify command with its exit
+code, each acceptance item met or not, rulings recorded, and any deviation from
+the brief.
+
+Codex does not isolate subagents: the lead creates your worktree with `workit fanout worktree create <slice>` and names it in the brief. Work only there, never in the lead's checkout.
+'''

package/agents/workit-reviewer.toml

@@ -0,0 +1,29 @@
+# Generated by Workit from packages/workit-claude-code/agents/reviewer.md; edits are overwritten on the next plugin start.
+name = "workit-reviewer"
+description = "Fresh-context reviewer for a workit branch or PR - spec fidelity and standards as separate axes, test quality and blast radius - that records findings and a non-author verdict. Use for independent review of a diff, branch or PR."
+sandbox_mode = "read-only"
+developer_instructions = '''You are the workit reviewer. Review the real candidate, never the author's
+description of it. Follow the workit-review skill (`$workit-review`).
+
+1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
+   for a PR, `workit pr status --json` for checks and unresolved threads.
+2. Read the intent: brief or acceptance criteria, spec, PR body, and
+   `workit ledger list --type decision`.
+3. Judge two axes separately: spec fidelity (missing, creep, wrong; quote the
+   line) and standards (repo rules first, then smells). Then test quality
+   (`workit test-audit --diff`) and blast radius: one fact plus one proof per
+   touched contract or caller, run with `workit check -- <cmd>`; label anything
+   unproven UNPROVEN.
+4. Each finding: file:line, severity (blocker, major, minor, nit), evidence
+   (hunk, test or command output), concrete fix.
+5. Record the verdict:
+   `workit ledger verdict verified|failed|blocked --kind review --branch <b> --session <id> --how "<what you read and ran>"`,
+   with the session the SubagentStart hook gave you
+   (`verified` with `--kind review`: no blocker or major finding left).
+   Record a design choice you had to make as `workit ledger ruling`.
+
+Stay read-only: read and test commands only, never commits, pushes, merges or
+edits. If the ledger refuses you as an author, report that instead of a verdict.
+
+Codex runs you in a read-only sandbox. `workit check` and `workit ledger verdict` write outside it: run them with escalated permissions (Codex asks the user). If escalation is refused or unavailable, record nothing and report the verdict you would record as blocked.
+'''

package/agents/workit-verifier.toml

@@ -0,0 +1,35 @@
+# Generated by Workit from packages/workit-claude-code/agents/verifier.md; edits are overwritten on the next plugin start.
+name = "workit-verifier"
+description = "Independently verifies a workit candidate (branch, commit or PR) on its real surface and records a SHA-keyed verdict in the ledger. Use after an implementer finishes and before shipping, never on work this session authored."
+sandbox_mode = "read-only"
+developer_instructions = '''You are the workit verifier. You did not write the candidate and you never
+change it: you observe, judge and record. Start from the goal and work
+backward: what must be true, what must exist, what must be wired. The author's
+summary is a claim, not evidence; assume the goal is not met until you observe
+it.
+
+1. Pin the candidate in its own checkout (`cd` into the worker's worktree, or
+   pass `--cwd`): `git rev-parse HEAD` and `git status --short`. A dirty tree
+   or a moving HEAD is itself a finding, and the ledger refuses a verdict on it.
+2. Read the brief: goal, acceptance (Given/When/Then), verify commands.
+3. Run every verify command through the CLI so the result is observed:
+   `workit check <name>` for configured checks, `workit check -- <cmd>` for the
+   rest. Never substitute an easier command.
+4. Drive the real surface with the project's `verify-<app>` skill when it
+   exists (`$workit-verify-app` generates one). Tests alone are unit evidence.
+5. Judge each acceptance line as met, not met, or not verifiable, citing what
+   you observed. Label every claim measured, inferred or guess.
+6. Record the verdict, then report it:
+   `workit ledger verdict verified|tests-verified|type-check-only|failed|blocked --branch <b> --kind live|unit --session <id> --how "<what you ran and saw>"`,
+   with the session the SubagentStart hook gave you (you share the lead's
+   `WORKIT_SESSION_ID`, which authored the work).
+   `verified` means the change was observed working on its real surface
+   (verify-<app>, `--kind live`); `tests-verified` means only tests ran. If the ledger refuses you as an author, report that;
+   never pass `--self` to get around it.
+
+Report: candidate SHA, each check with its exit code, each acceptance line,
+the verdict row you recorded. Do not fix anything you find: a failing check is
+a verdict, not a task.
+
+Codex runs you in a read-only sandbox. `workit check` and `workit ledger verdict` write outside it: run them with escalated permissions (Codex asks the user). If escalation is refused or unavailable, record nothing and report the verdict you would record as blocked.
+'''

package/dist/launch-mcp.js

@@ -6621,8 +6621,9 @@ var require_dist = __commonJS(function(exports, module) {
 });
 
 // packages/workit-codex/scripts/launch-mcp.ts
-import { existsSync as existsSync9, realpathSync as realpathSync7, statSync as statSync3 } from "node:fs";
-import path21 from "node:path";
+import { existsSync as existsSync10, realpathSync as realpathSync7, statSync as statSync3 } from "node:fs";
+import path22 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // packages/workit-core/src/core.ts
 import { spawnSync as spawnSync14 } from "node:child_process";
@@ -28197,6 +28198,110 @@ var codexCapabilities = (host, availability = {}) => capabilitiesFor(codexDescri
 if (false)
   ;
 
+// packages/workit-codex/scripts/agents.ts
+import {
+  existsSync as existsSync9,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync5,
+  readFileSync as readFileSync7,
+  renameSync as renameSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import os5 from "node:os";
+import path21 from "node:path";
+var CODEX_AGENT_MARKER = "# Generated by Workit";
+var codexHomeOfInstall = (pluginRoot) => {
+  const parts = path21.resolve(pluginRoot).split(path21.sep);
+  const cache = parts.length - 4;
+  return cache >= 2 && parts[cache] === "cache" && parts[cache - 1] === "plugins" ? parts.slice(0, cache - 1).join(path21.sep) || path21.sep : null;
+};
+var codexHomeFor = (pluginRoot, env) => codexHomeOfInstall(pluginRoot) ?? (env.CODEX_HOME || path21.join(env.HOME || os5.homedir(), ".codex"));
+var MARKER_VERSION = /^# Generated by Workit (\d+\.\d+\.\d+)\b/;
+var agentMarkerVersion = (text) => MARKER_VERSION.exec(text)?.[1] ?? null;
+var stampCodexAgent = (content, version) => version && content.startsWith(CODEX_AGENT_MARKER) && !agentMarkerVersion(content) ? `${CODEX_AGENT_MARKER} ${version}${content.slice(CODEX_AGENT_MARKER.length)}` : content;
+var versionAtLeast = (version, min) => {
+  const a = version.split(".").map(Number);
+  const b = min.split(".").map(Number);
+  for (let i = 0;i < 3; i++)
+    if (a[i] !== b[i])
+      return a[i] > b[i];
+  return true;
+};
+var pluginVersion = (pluginRoot) => {
+  try {
+    const version = JSON.parse(readFileSync7(path21.join(pluginRoot, "package.json"), "utf8")).version;
+    return typeof version === "string" && /^\d+\.\d+\.\d+/.test(version) ? version.match(/^\d+\.\d+\.\d+/)[0] : null;
+  } catch {
+    return null;
+  }
+};
+var lstatOrNull = (file) => {
+  try {
+    return lstatSync3(file);
+  } catch {
+    return null;
+  }
+};
+var installCodexAgents = (pluginRoot, codexHome) => {
+  const source = path21.join(pluginRoot, "agents");
+  if (!existsSync9(source))
+    return [];
+  const version = pluginVersion(pluginRoot);
+  const target = path21.join(codexHome, "agents");
+  const results = [];
+  for (const file of readdirSync5(source).filter((name) => name.endsWith(".toml")).toSorted()) {
+    const content = stampCodexAgent(readFileSync7(path21.join(source, file), "utf8"), version);
+    const dest = path21.join(target, file);
+    const stat = lstatOrNull(dest);
+    if (stat?.isSymbolicLink()) {
+      results.push({ file: dest, action: "skipped-symlink" });
+      continue;
+    }
+    if (!stat) {
+      mkdirSync3(target, { recursive: true });
+      try {
+        writeFileSync3(dest, content, { flag: "wx" });
+        results.push({ file: dest, action: "installed" });
+      } catch (error) {
+        if (error.code !== "EEXIST")
+          throw error;
+        results.push({ file: dest, action: "kept-user-file" });
+      }
+      continue;
+    }
+    if (!stat.isFile()) {
+      results.push({ file: dest, action: "kept-user-file" });
+      continue;
+    }
+    const current = readFileSync7(dest, "utf8");
+    if (current === content) {
+      results.push({ file: dest, action: "current" });
+      continue;
+    }
+    if (!current.startsWith(CODEX_AGENT_MARKER)) {
+      results.push({ file: dest, action: "kept-user-file" });
+      continue;
+    }
+    const written = agentMarkerVersion(current);
+    if (written && (!version || !versionAtLeast(version, written))) {
+      results.push({ file: dest, action: "kept-newer-version" });
+      continue;
+    }
+    const temp = path21.join(target, `.${file}.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync3(temp, content, { flag: "wx" });
+    try {
+      renameSync2(temp, dest);
+    } catch (error) {
+      rmSync2(temp, { force: true });
+      throw error;
+    }
+    results.push({ file: dest, action: "updated" });
+  }
+  return results;
+};
+
 // packages/workit-codex/scripts/launch-mcp.ts
 var codexQualification = (host) => host === "codex_cli" ? { surface: host, cli: SUPPORT_MATRIX.codex.cli } : {
   surface: host,
@@ -28206,8 +28311,8 @@ var codexQualification = (host) => host === "codex_cli" ? { surface: host, cli:
 var resolveCodexWorkspaceRoot = (pluginRoot, env) => {
   const explicit = env.WORKFLOW_WORKSPACE_ROOT;
   const inherited = env.PWD;
-  const candidate = explicit ?? (inherited && path21.resolve(inherited) !== path21.resolve(pluginRoot) ? inherited : undefined);
-  if (!candidate || !path21.isAbsolute(candidate) || !existsSync9(candidate))
+  const candidate = explicit ?? (inherited && path22.resolve(inherited) !== path22.resolve(pluginRoot) ? inherited : undefined);
+  if (!candidate || !path22.isAbsolute(candidate) || !existsSync10(candidate))
     return null;
   try {
     if (!statSync3(candidate).isDirectory())
@@ -28246,10 +28351,33 @@ var codexContextProvider = (host = detectCodexSurface(process.env), root) => ({
     };
   }
 });
-if (__require.main == __require.module)
+var pluginRoot = () => path22.resolve(path22.dirname(fileURLToPath3(import.meta.url)), "..");
+var syncCodexAgents = (root) => {
+  const codexHome = codexHomeOfInstall(root);
+  if (!codexHome)
+    return;
+  try {
+    installCodexAgents(root, codexHome);
+  } catch {}
+};
+if (__require.main == __require.module) {
+  if (process.argv.includes("--install-agents")) {
+    const root = pluginRoot();
+    const results = installCodexAgents(root, codexHomeFor(root, process.env));
+    for (const r of results)
+      process.stdout.write(`${r.action} ${r.file}
+`);
+    if (results.length === 0)
+      process.stdout.write(`no agents bundled in ${root}
+`);
+    process.exit(0);
+  }
+  syncCodexAgents(pluginRoot());
   await runStdioServer(detectCodexSurface(process.env), codexContextProvider());
+}
 export {
   codexContextProvider,
   codexQualification,
-  resolveCodexWorkspaceRoot
+  resolveCodexWorkspaceRoot,
+  syncCodexAgents
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@brainervirus/workit-codex",
-  "version": "8.6.1",
+  "version": "8.7.0",
   "private": false,
-  "description": "Workit Codex CLI/desktop plugin — shared MCP transport, hooks, and sixteen method skills",
+  "description": "Workit Codex CLI/desktop plugin — shared MCP transport, hooks, method skills, and verifier/reviewer/implementer agents",
   "keywords": [
     "agentic-coding",
     "ai-agents",
@@ -27,7 +27,8 @@
     ".codex-plugin/",
     ".mcp.json",
     "hooks/hooks.json",
-    "skills/"
+    "skills/",
+    "agents/"
   ],
   "type": "module",
   "main": "./dist/launch-mcp.js",
@@ -38,8 +39,8 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^8.6.1",
-    "@brainervirus/workit-mcp": "^8.6.1"
+    "@brainervirus/workit-core": "^8.7.0",
+    "@brainervirus/workit-mcp": "^8.7.0"
   },
   "engines": {
     "node": ">=24"