@brainervirus/workit-core 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/scripts/analyze-release-scope.ts

@@ -6,6 +6,7 @@
 // them; merge-backs and the release's own manifest sync never do.
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
+import BUNDLED_DEPS_JSON from "./bundled-deps.json" with { type: "json" };
 
 export const RELEASE_PACKAGES = [
   "workit-core",
@@ -15,8 +16,90 @@ export const RELEASE_PACKAGES = [
   "workit-cursor",
   "workit-codex",
   "workit-pi",
+  "workit-claude-code",
 ] as const;
 
+type ReleasePackage = (typeof RELEASE_PACKAGES)[number];
+
+/**
+ * Sources a package's published dist/ inlines from OUTSIDE its own directory.
+ * Every adapter build is a no-external `bun build`, so whatever it imports
+ * from another workspace package is copied into its bundle: a runtime
+ * dependency on that package does not reach the shipped code. A change in
+ * these sources must therefore republish the bundling package too. Verified
+ * against the build entries' metafiles by
+ * test/workit-core/bundled-sources.test.ts.
+ */
+const CORE = "packages/workit-core/"; // sources, skills, templates and package.json
+// Cursor and Codex inline the MCP transport and its declared dependencies.
+const MCP = ["packages/workit-mcp/src/", "packages/workit-mcp/package.json"];
+// The bundled CLI inlines its sources, package.json (`workit --version`) and
+// its third-party dependencies.
+const CLI = ["packages/workit-cli/src/", "packages/workit-cli/package.json"];
+export const BUNDLED_SOURCES: Partial<Record<ReleasePackage, readonly string[]>> = {
+  "workit-mcp": [CORE],
+  "workit-cli": [CORE],
+  "workit-opencode": [CORE],
+  "workit-cursor": [CORE, ...MCP],
+  "workit-codex": [CORE, ...MCP],
+  "workit-pi": [CORE],
+  "workit-claude-code": [CORE, ...CLI],
+};
+
+/**
+ * Third-party packages each dist/ inlines, as bun.lock `packages` keys
+ * (`zod`, or `@opencode-ai/plugin/zod` for a nested copy). A lockfile change
+ * republishes a package only when one of these resolves to a different
+ * version, so dev-tooling bumps never release. Kept in sync with the bundle
+ * metafiles by test/workit-core/bundled-sources.test.ts.
+ */
+export const BUNDLED_DEPS = BUNDLED_DEPS_JSON as Partial<Record<ReleasePackage, string[]>>;
+
+const LOCKFILE = "bun.lock";
+
+/** `packages` key → resolved `name@version` from a bun.lock text (JSONC). */
+export const lockResolutions = (text: string): Map<string, string> => {
+  // bun.lock is JSON with trailing commas.
+  const parsed = JSON.parse(text.replace(/,(\s*[}\]])/g, "$1")) as {
+    packages?: Record<string, unknown>;
+  };
+  const resolved = new Map<string, string>();
+  for (const [key, entry] of Object.entries(parsed.packages ?? {}))
+    if (Array.isArray(entry) && typeof entry[0] === "string") resolved.set(key, entry[0]);
+  return resolved;
+};
+
+const lockAt = (root: string, rev: string): Map<string, string> | null => {
+  try {
+    return lockResolutions(
+      execFileSync("git", ["show", `${rev}:${LOCKFILE}`], {
+        cwd: root,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+      }),
+    );
+  } catch {
+    return null;
+  }
+};
+
+/** Packages whose inlined third-party resolutions differ between two revisions. */
+export const lockChangedPackages = (root: string, from: string, to: string): ReleasePackage[] => {
+  const before = lockAt(root, from);
+  const after = lockAt(root, to);
+  if (before === null && after === null) return [];
+  return RELEASE_PACKAGES.filter((pkg) =>
+    (BUNDLED_DEPS[pkg] ?? []).some((key) => before?.get(key) !== after?.get(key)),
+  );
+};
+
+/** Every repository path whose change alters `pkg`'s published payload. */
+export const payloadPaths = (pkg: ReleasePackage): string[] => [
+  `packages/${pkg}/`,
+  ...(BUNDLED_SOURCES[pkg] ?? []),
+];
+
 /** The release pipeline's own version-sync commit: never a release trigger. */
 const RELEASE_SYNC = /^chore\(release\): sync manifests\b/;
 
@@ -56,11 +139,15 @@ const subjectLevel = (commit: string): Level | null => {
 // combined diff drops files identical to either parent — e.g. hotfix-branch
 // back-merges), and -z returns raw NUL-delimited paths so spaces/non-ASCII
 // are never C-quoted. NUL is fine in captured output, never in argv.
-const commitsSince = (root: string, from: string): { message: string; files: string[] }[] => {
+const commitsSince = (
+  root: string,
+  from: string,
+): { hash: string; message: string; files: string[] }[] => {
   const hashes = g(root, ["log", "--reverse", "--format=%H", `${from}..HEAD`])
     .split("\n")
     .filter(Boolean);
   return hashes.map((h) => ({
+    hash: h,
     message: g(root, ["show", "-s", "--format=%B", h]),
     files: g(root, ["diff-tree", "--no-commit-id", "--name-only", "-r", "-m", "--root", "-z", h])
       .split("\0")
@@ -80,20 +167,24 @@ export function analyzeReleaseScope(root = process.cwd()): {
   const levels: Level[] = [];
   const pkgs = new Set<string>();
   let payloadOnly = false;
-  for (const { message, files } of commits) {
+  for (const { hash, message, files } of commits) {
     const subject = (message.split("\n")[0] ?? "").trim();
     if (RELEASE_SYNC.test(subject)) continue;
     const touched = files.filter((f) =>
-      RELEASE_PACKAGES.some((p) => f.startsWith(`packages/${p}/`)),
+      RELEASE_PACKAGES.some((p) => payloadPaths(p).some((prefix) => f.startsWith(prefix))),
     );
-    if (touched.length === 0) continue;
+    // A lockfile edit counts only for packages whose inlined deps moved.
+    const relocked = files.includes(LOCKFILE) ? lockChangedPackages(root, `${hash}^`, hash) : [];
+    if (touched.length === 0 && relocked.length === 0) continue;
     const lvl = subjectLevel(message);
     if (lvl) levels.push(lvl);
     else if (!subject.startsWith("Merge ")) payloadOnly = true;
-    for (const f of touched) {
-      const pkg = RELEASE_PACKAGES.find((p) => f.startsWith(`packages/${p}/`));
-      if (pkg) pkgs.add(pkg);
-    }
+    for (const pkg of RELEASE_PACKAGES)
+      if (
+        relocked.includes(pkg) ||
+        touched.some((f) => payloadPaths(pkg).some((prefix) => f.startsWith(prefix)))
+      )
+        pkgs.add(pkg);
   }
   if (levels.length === 0) return { level: payloadOnly ? "patch" : null, productPkgs: [...pkgs] };
   const level = levels.reduce<Level>(

package/scripts/bundled-deps.json

@@ -0,0 +1,133 @@
+{
+  "workit-mcp": [
+    "@modelcontextprotocol/sdk",
+    "@openclaw/fs-safe",
+    "ajv",
+    "ajv-formats",
+    "fast-deep-equal",
+    "fast-uri",
+    "json-schema-traverse",
+    "zod",
+    "zod-to-json-schema"
+  ],
+  "workit-cli": [
+    "@alcalzone/ansi-tokenize",
+    "@inkjs/ui",
+    "@openclaw/fs-safe",
+    "ansi-escapes",
+    "ansi-regex",
+    "ansi-styles",
+    "auto-bind",
+    "chalk",
+    "cli-boxes",
+    "cli-cursor",
+    "cli-truncate",
+    "code-excerpt",
+    "convert-to-spaces",
+    "deepmerge",
+    "environment",
+    "es-toolkit",
+    "escape-string-regexp",
+    "figures",
+    "get-east-asian-width",
+    "indent-string",
+    "ink",
+    "is-fullwidth-code-point",
+    "is-in-ci",
+    "is-unicode-supported",
+    "patch-console",
+    "react",
+    "react-devtools-core",
+    "react-reconciler",
+    "restore-cursor",
+    "restore-cursor/onetime",
+    "restore-cursor/onetime/mimic-fn",
+    "scheduler",
+    "signal-exit",
+    "slice-ansi",
+    "stack-utils",
+    "string-width",
+    "strip-ansi",
+    "terminal-size",
+    "widest-line",
+    "wrap-ansi",
+    "ws",
+    "yoga-layout",
+    "zod"
+  ],
+  "workit-opencode": [
+    "@openclaw/fs-safe",
+    "@opencode-ai/plugin",
+    "@opencode-ai/plugin/zod",
+    "@opencode/plugin",
+    "zod"
+  ],
+  "workit-cursor": [
+    "@modelcontextprotocol/sdk",
+    "@openclaw/fs-safe",
+    "ajv",
+    "ajv-formats",
+    "fast-deep-equal",
+    "fast-uri",
+    "json-schema-traverse",
+    "zod",
+    "zod-to-json-schema"
+  ],
+  "workit-codex": [
+    "@modelcontextprotocol/sdk",
+    "@openclaw/fs-safe",
+    "ajv",
+    "ajv-formats",
+    "fast-deep-equal",
+    "fast-uri",
+    "json-schema-traverse",
+    "zod",
+    "zod-to-json-schema"
+  ],
+  "workit-pi": ["@openclaw/fs-safe", "zod"],
+  "workit-claude-code": [
+    "@alcalzone/ansi-tokenize",
+    "@inkjs/ui",
+    "@openclaw/fs-safe",
+    "ansi-escapes",
+    "ansi-regex",
+    "ansi-styles",
+    "auto-bind",
+    "chalk",
+    "cli-boxes",
+    "cli-cursor",
+    "cli-truncate",
+    "code-excerpt",
+    "convert-to-spaces",
+    "deepmerge",
+    "environment",
+    "es-toolkit",
+    "escape-string-regexp",
+    "figures",
+    "get-east-asian-width",
+    "indent-string",
+    "ink",
+    "is-fullwidth-code-point",
+    "is-in-ci",
+    "is-unicode-supported",
+    "patch-console",
+    "react",
+    "react-devtools-core",
+    "react-reconciler",
+    "restore-cursor",
+    "restore-cursor/onetime",
+    "restore-cursor/onetime/mimic-fn",
+    "scheduler",
+    "signal-exit",
+    "slice-ansi",
+    "stack-utils",
+    "string-width",
+    "strip-ansi",
+    "terminal-size",
+    "widest-line",
+    "wrap-ansi",
+    "ws",
+    "yoga-layout",
+    "zod"
+  ]
+}

package/scripts/publish-changed-packages.ts

@@ -4,7 +4,12 @@
 // package so release logs answer "what shipped?" without leaving the terminal.
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
-import { latestTag, RELEASE_PACKAGES } from "./analyze-release-scope";
+import {
+  latestTag,
+  lockChangedPackages,
+  payloadPaths,
+  RELEASE_PACKAGES,
+} from "./analyze-release-scope";
 
 const git = (root: string, args: string[]): string =>
   execFileSync("git", args, { cwd: root, encoding: "utf8" }).trim();
@@ -12,8 +17,13 @@ const git = (root: string, args: string[]): string =>
 export function changedPackages(root: string, fromTag: string): string[] {
   // Committed state only: <tag>..HEAD, never the working tree — unreviewed
   // local edits must not decide what ships.
+  // Plus packages whose inlined third-party deps resolve differently in the
+  // lockfile (BUNDLED_DEPS); a dev-tooling-only lockfile bump changes none.
+  const relocked = new Set<string>(lockChangedPackages(root, fromTag, "HEAD"));
   return RELEASE_PACKAGES.filter((pkg) => {
-    const out = git(root, ["diff", "--name-only", `${fromTag}..HEAD`, "--", `packages/${pkg}`]);
+    if (relocked.has(pkg)) return true;
+    // Own directory plus any sources bundled into its dist/ (BUNDLED_SOURCES).
+    const out = git(root, ["diff", "--name-only", `${fromTag}..HEAD`, "--", ...payloadPaths(pkg)]);
     return out !== "";
   });
 }
@@ -38,20 +48,15 @@ export function publishChanged(opts: {
       execFileSync(cmd, args, { cwd: o.cwd, encoding: "utf8", stdio: "inherit" }));
   const tag =
     opts.fromTag !== undefined ? (opts.fromTag === "" ? null : opts.fromTag) : latestTag(root);
-  if (tag === null) {
-    // First-ever release: everything ships.
-    const published: string[] = [];
-    for (const pkg of RELEASE_PACKAGES) {
-      const cwd = resolve(root, "packages", pkg);
-      if (!dryRun) run("npm", ["publish", "--access", "public"], { cwd });
-      published.push(pkg);
-      console.log(`published ${pkg} @ ${cwd}`);
-    }
-    return { published, skipped: [], tag: null };
-  }
-  const changed = new Set(changedPackages(root, tag));
+  // First-ever release: everything ships.
+  const changed =
+    tag === null ? new Set<string>(RELEASE_PACKAGES) : new Set(changedPackages(root, tag));
   const published: string[] = [];
   const skipped: string[] = [];
+  const failed: Array<{ pkg: string; error: string }> = [];
+  // Every changed package is attempted even after a failure: one package that
+  // cannot publish (e.g. a first publish of a new npm name the token does not
+  // cover) must not leave the others unreleased. Failures throw at the end.
   for (const pkg of RELEASE_PACKAGES) {
     if (!changed.has(pkg)) {
       skipped.push(pkg);
@@ -62,12 +67,19 @@ export function publishChanged(opts: {
     try {
       if (!dryRun) run("npm", ["publish", "--access", "public"], { cwd });
     } catch (e) {
-      console.log(`publish failed ${pkg}: ${e instanceof Error ? e.message : String(e)}`);
-      throw e;
+      const error = e instanceof Error ? e.message : String(e);
+      failed.push({ pkg, error });
+      console.log(`publish failed ${pkg}: ${error}`);
+      continue;
     }
     published.push(pkg);
     console.log(`published ${pkg} @ ${cwd}`);
   }
+  if (failed.length > 0) {
+    const summary = `publish failed for ${failed.length} package(s): ${failed.map((f) => f.pkg).join(", ")}; published: ${published.join(", ") || "none"}. A first publish of a new @brainervirus package needs an npm token allowed to create packages in the scope.`;
+    console.log(summary);
+    throw new Error(summary);
+  }
   return { published, skipped, tag };
 }
 

package/scripts/rewrite-workspace-deps.ts

@@ -25,14 +25,19 @@ for (const pkg of [
   "workit-cursor",
   "workit-codex",
   "workit-pi",
+  "workit-claude-code",
 ]) {
   const file = resolve(root, `packages/${pkg}/package.json`);
   const data = JSON.parse(readFileSync(file, "utf8"));
-  const deps = data.dependencies;
-  if (!deps) continue;
-  for (const name of Object.keys(deps)) {
-    if (name.startsWith("@brainervirus/")) deps[name] = `^${core.version}`;
-  }
+  // devDependencies too: the Claude Code plugin bundles core and the CLI into
+  // dist/, so they are build-time only, but a published manifest must still
+  // never carry workspace:*.
+  const groups = [data.dependencies, data.devDependencies].filter(Boolean);
+  if (groups.length === 0) continue;
+  for (const deps of groups)
+    for (const name of Object.keys(deps)) {
+      if (name.startsWith("@brainervirus/")) deps[name] = `^${core.version}`;
+    }
   writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
 }
 // The root marketplace index carries no release version; only the package
@@ -40,6 +45,7 @@ for (const pkg of [
 for (const file of [
   resolve(root, "packages/workit-cursor/.cursor-plugin/plugin.json"),
   resolve(root, "packages/workit-codex/.codex-plugin/plugin.json"),
+  resolve(root, "packages/workit-claude-code/.claude-plugin/plugin.json"),
 ]) {
   const data = JSON.parse(readFileSync(file, "utf8"));
   data.version = core.version;

package/scripts/sync-release-manifests.ts

@@ -9,7 +9,7 @@ import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-const SYNC_MANIFEST_PATHS = [
+export const SYNC_MANIFEST_PATHS = [
   "package.json",
   "packages/workit-core/package.json",
   "packages/workit-mcp/package.json",
@@ -18,9 +18,13 @@ const SYNC_MANIFEST_PATHS = [
   "packages/workit-cursor/package.json",
   "packages/workit-codex/package.json",
   "packages/workit-pi/package.json",
+  "packages/workit-claude-code/package.json",
   // Kept in lockstep with packages/workit-core/package.json by contract test.
   "packages/workit-cursor/.cursor-plugin/plugin.json",
   "packages/workit-codex/.codex-plugin/plugin.json",
+  // Claude Code reads the plugin version from here (the marketplace entry
+  // carries none), so it must track the published npm version.
+  "packages/workit-claude-code/.claude-plugin/plugin.json",
 ];
 
 export type ManifestSyncResult = { version: string; changed: string[] };

package/src/core/detect-hosts.ts

@@ -9,6 +9,7 @@ import { planUninstall, type UninstallPaths } from "./uninstall";
 import {
   findHostExecutable,
   installedHostApp,
+  isClaudeWorkitInstalled,
   isCodexWorkitInstalled,
   isPiWorkitInstalled,
   type HostId,
@@ -24,7 +25,7 @@ export type HostDetection = {
 
 export type DetectHostsOptions = UninstallPaths;
 
-const HOSTS: HostId[] = ["opencode", "cursor", "codex", "pi"];
+const HOSTS: HostId[] = ["opencode", "cursor", "codex", "pi", "claude-code"];
 
 /** Hosts the setup wizard configures through their native install paths. */
 export const WIZARD_HOSTS: HostId[] = [...HOSTS];
@@ -40,6 +41,7 @@ export function emptyDetection(): Record<HostId, HostDetection> {
     cursor: { detected: false, configured: false },
     codex: { detected: false, configured: false },
     pi: { detected: false, configured: false },
+    "claude-code": { detected: false, configured: false },
   };
 }
 
@@ -52,8 +54,10 @@ export function detectHosts(options: DetectHostsOptions = {}): Record<HostId, Ho
   const configuredByHost = new Map(plan.hosts.map((h) => [h.host, h.installed]));
   const found = emptyDetection();
   for (const host of HOSTS) {
+    // Claude Code ships as the `claude` CLI (the desktop app embeds it).
+    const executable = host === "claude-code" ? "claude" : host;
     const detected =
-      findHostExecutable(host, { home, env }) !== null || installedHostApp(host, home, env);
+      findHostExecutable(executable, { home, env }) !== null || installedHostApp(host, home, env);
     found[host] = {
       detected,
       configured:
@@ -61,7 +65,9 @@ export function detectHosts(options: DetectHostsOptions = {}): Record<HostId, Ho
           ? isCodexWorkitInstalled(home, env) || (configuredByHost.get(host) ?? false)
           : host === "pi"
             ? isPiWorkitInstalled(home, env) || (configuredByHost.get(host) ?? false)
-            : (configuredByHost.get(host) ?? false),
+            : host === "claude-code"
+              ? isClaudeWorkitInstalled(home, env)
+              : (configuredByHost.get(host) ?? false),
     };
   }
   return found;

package/src/core/doctor.ts

@@ -33,6 +33,11 @@ import {
   isWorkitPlugin,
 } from "./registration";
 import { readWorkspacesResult, resolveWorkspaceFrom } from "./workspaces";
+import {
+  CLAUDE_MARKETPLACE_NAME,
+  claudeWorkitInstalls,
+  type ClaudeWorkitInstall,
+} from "./host-install";
 import { validateCursorSkills, WORKIT_METHOD_SKILLS } from "./skill-manifests";
 import {
   classifyHostGeneration,
@@ -53,6 +58,7 @@ export type DoctorCheckId =
   | "runtime"
   | "versions"
   | "codex_pin"
+  | "claude_plugin"
   | "assets"
   | "launcher"
   | "utility"
@@ -1737,10 +1743,65 @@ const checkWorkspaceLock = (res: Resolved): DoctorCheck => {
   };
 };
 
+const CLAUDE_PLUGIN_PACKAGE = "@brainervirus/workit-claude-code";
+
+const versionBehind = (version: string, latest: string): boolean =>
+  version !== latest && semverAtLeast(latest, version);
+
+/**
+ * Claude Code installs the marketplace plugin as a snapshot of the published
+ * package (auto-update is off by default), so an install can lag the release.
+ * It warns only when a newer plugin version is actually published: a plugin
+ * older than this CLI is normal when no plugin payload changed since (the
+ * plugin is republished only when its own or its bundled sources change).
+ * The plugin keeps working; the fix is one native update. A `--plugin-dir`
+ * local pin is per-session, never recorded, and never checked here.
+ */
+const checkClaudePlugin = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
+  // Only installs Claude loads here: user scope, plus this project's.
+  const installs = claudeWorkitInstalls(res.home, res.env, res.cwd);
+  if (installs.length === 0)
+    return {
+      id: "claude_plugin",
+      status: "pass",
+      detail: "no Workit Claude Code plugin install recorded — skipping",
+    };
+  const fix = (install: ClaudeWorkitInstall) =>
+    `claude plugin marketplace update ${CLAUDE_MARKETPLACE_NAME} && ${
+      install.projectPath ? `cd ${JSON.stringify(install.projectPath)} && ` : ""
+    }claude plugin update ${install.id}${install.scope === "user" ? "" : ` --scope ${install.scope}`}`;
+  const latest = registryLatestVersion(res, CLAUDE_PLUGIN_PACKAGE);
+  const problems: string[] = [];
+  let repair: string | undefined;
+  for (const install of installs) {
+    const label = `${install.id} ${install.version ?? "(unknown version)"}${install.scope === "user" ? "" : ` (${install.scope} scope)`}`;
+    if (latest && install.version && versionBehind(install.version, latest)) {
+      problems.push(`stale_install: ${label} is behind published ${latest}`);
+      repair ??= fix(install);
+    }
+  }
+  const registryProbed = latest !== null && !res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
+  if (problems.length === 0)
+    return {
+      id: "claude_plugin",
+      status: "pass",
+      detail: `Claude Code plugin ${installs.map((i) => `${i.id} ${i.version ?? "?"}`).join(", ")} is current`,
+      registryProbed,
+    };
+  return {
+    id: "claude_plugin",
+    status: "warn",
+    detail: problems.join("; "),
+    fix: repair,
+    registryProbed,
+  };
+};
+
 const RUN_CHECKS: Array<(res: Resolved) => DoctorCheck> = [
   checkRuntime,
   checkVersions,
   checkCodexPin,
+  checkClaudePlugin,
   checkAssets,
   checkLauncher,
   checkUtility,

package/src/core/host-install.ts

@@ -11,7 +11,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 
-export type HostId = "opencode" | "cursor" | "codex" | "pi";
+export type HostId = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
 
 /** A reviewed argv vector. Arguments are never composed into a shell string. */
 export type HostInstallCommand = {
@@ -89,6 +89,12 @@ export type HostInstallOptions = {
 
 const MARKETPLACE = "https://github.com/BrainerVirus/workit.git";
 const CODEX_MARKETPLACE_NAME = "workflow-toolkit";
+/** Claude Code reads the git-hosted marketplace at the repo root
+ * (`.claude-plugin/marketplace.json`, name `workit`); its entry installs the
+ * published npm package. */
+export const CLAUDE_MARKETPLACE_REPO = "BrainerVirus/workit";
+export const CLAUDE_MARKETPLACE_NAME = "workit";
+export const CLAUDE_PLUGIN_ID = `workit@${CLAUDE_MARKETPLACE_NAME}`;
 const validPackageVersion = (value: string): boolean =>
   value === "latest" || /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 
@@ -224,6 +230,109 @@ export const isCodexWorkitInstalled = (
   return false;
 };
 
+/** Claude Code's config root (`CLAUDE_CONFIG_DIR`, default `~/.claude`). */
+export const claudeConfigDir = (home: string, env: NodeJS.ProcessEnv = process.env): string =>
+  env.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude");
+
+export type ClaudeInstallScope = "user" | "project" | "local";
+
+export type ClaudeWorkitInstall = {
+  id: string;
+  version: string | null;
+  installPath: string;
+  scope: ClaudeInstallScope;
+  /** The project a project/local-scope install belongs to; null for user scope. */
+  projectPath: string | null;
+};
+
+const CLAUDE_SCOPES = new Set<string>(["user", "project", "local"]);
+
+/** A project/local install applies to `cwd` when cwd is inside its project. */
+const appliesTo = (install: ClaudeWorkitInstall, cwd: string | null): boolean => {
+  if (install.scope === "user") return true;
+  if (cwd === null || install.projectPath === null) return false;
+  const relative = path.relative(path.resolve(install.projectPath), path.resolve(cwd));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+const isCanonicalClaudePlugin = (root: string): boolean => {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(path.join(root, ".claude-plugin", "plugin.json"), "utf8"),
+    ) as { name?: string; repository?: string | { url?: string } };
+    const repository =
+      typeof manifest.repository === "string" ? manifest.repository : manifest.repository?.url;
+    return (
+      manifest.name === "workit" &&
+      repository?.replace(/\.git$/, "").toLowerCase() === "https://github.com/brainervirus/workit"
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Workit installs recorded in Claude Code's plugin registry
+ * (`<config>/plugins/installed_plugins.json`, v2: `{plugins: {"name@market":
+ * [{installPath, version}]}}`). Only entries whose install directory carries
+ * the canonical Workit manifest count, whatever marketplace they came from.
+ * Only installs that apply here count: user scope always, project/local
+ * scope only when `cwd` is inside the recorded project (`cwd: null` keeps
+ * user scope only). A `--plugin-dir` pin is per-session and never recorded.
+ */
+export const claudeWorkitInstalls = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string | null = process.cwd(),
+): ClaudeWorkitInstall[] => {
+  const file = path.join(claudeConfigDir(home, env), "plugins", "installed_plugins.json");
+  let registry: unknown;
+  try {
+    registry = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const plugins =
+    registry && typeof registry === "object" && "plugins" in registry ? registry.plugins : null;
+  if (!plugins || typeof plugins !== "object") return [];
+  const found: ClaudeWorkitInstall[] = [];
+  for (const [id, entries] of Object.entries(plugins as Record<string, unknown>)) {
+    if (!id.startsWith("workit@") || !Array.isArray(entries)) continue;
+    for (const entry of entries as Array<{
+      installPath?: unknown;
+      version?: unknown;
+      scope?: unknown;
+      projectPath?: unknown;
+    }>) {
+      if (typeof entry?.installPath !== "string" || !isCanonicalClaudePlugin(entry.installPath))
+        continue;
+      // Older registries omit scope; Claude's default install scope is user.
+      const scope = entry.scope === undefined ? "user" : String(entry.scope);
+      if (!CLAUDE_SCOPES.has(scope)) continue; // e.g. managed: not ours to change
+      const install: ClaudeWorkitInstall = {
+        id,
+        installPath: entry.installPath,
+        version:
+          typeof entry.version === "string" && /^\d+\.\d+\.\d+/.test(entry.version)
+            ? entry.version
+            : null,
+        scope: scope as ClaudeInstallScope,
+        projectPath:
+          scope !== "user" && typeof entry.projectPath === "string" ? entry.projectPath : null,
+      };
+      if (appliesTo(install, cwd)) found.push(install);
+    }
+  }
+  return found;
+};
+
+/** A Workit install Claude Code loads for this user (any project). */
+export const isClaudeWorkitInstalled = (
+  home: string,
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string | null = process.cwd(),
+): boolean => claudeWorkitInstalls(home, env, cwd).length > 0;
+
 export function installedHostApp(
   host: HostId,
   home: string,
@@ -297,6 +406,39 @@ export function planHostInstall(
       },
     ];
   }
+  if (host === "claude-code") {
+    if (!upgrading && isClaudeWorkitInstalled(home, env, null)) return [];
+    const base = hostCommand("claude", [], { home, cwd, env });
+    return [
+      nodePrerequisite({ home, cwd, env }),
+      {
+        ...base,
+        args: [...base.args, "plugin", "marketplace", "list", "--json"],
+        purpose: "Check whether the Workit Claude Code marketplace is already registered",
+      },
+      upgrading
+        ? {
+            ...base,
+            args: [...base.args, "plugin", "marketplace", "update", CLAUDE_MARKETPLACE_NAME],
+            purpose: "Refresh the Workit Claude Code marketplace",
+          }
+        : {
+            ...base,
+            args: [...base.args, "plugin", "marketplace", "add", CLAUDE_MARKETPLACE_REPO],
+            purpose: "Register the Workit Claude Code marketplace",
+            skipWhenOutputIncludes: `"name": "${CLAUDE_MARKETPLACE_NAME}"`,
+          },
+      {
+        ...base,
+        args: upgrading
+          ? [...base.args, "plugin", "update", CLAUDE_PLUGIN_ID]
+          : [...base.args, "plugin", "install", CLAUDE_PLUGIN_ID, "--scope", "user"],
+        purpose: upgrading
+          ? "Update the Workit Claude Code plugin"
+          : "Install the Workit Claude Code plugin",
+      },
+    ];
+  }
   if (host === "pi") {
     if (!upgrading && isPiWorkitInstalled(home, env)) return [];
     const base = hostCommand("pi", [], { home, cwd, env });
@@ -440,6 +582,7 @@ export function runHostCommand(
       const env: NodeJS.ProcessEnv = { ...process.env, ...context.env, HOME: home };
       env.CODEX_HOME = context.env?.CODEX_HOME ?? path.join(home, ".codex");
       env.PI_CODING_AGENT_DIR = context.env?.PI_CODING_AGENT_DIR ?? path.join(home, ".pi", "agent");
+      env.CLAUDE_CONFIG_DIR = context.env?.CLAUDE_CONFIG_DIR ?? path.join(home, ".claude");
       env.XDG_CONFIG_HOME = context.env?.XDG_CONFIG_HOME ?? path.join(home, ".config");
       return env;
     })(),

package/src/core/setup.ts

@@ -52,6 +52,8 @@ import { writeFileExclusive } from "./safe-write";
 import {
   isCodexWorkitInstalled,
   isPiWorkitInstalled,
+  isClaudeWorkitInstalled,
+  claudeConfigDir,
   planHostInstall,
   runHostInstall,
   type HostCommandRunner,
@@ -385,25 +387,27 @@ export function buildSetupPreview(
           mutations.push({ type: "install-adapter", platform, path: paths.cursorPluginDir });
           mutations.push({ type: "register-platform", platform, path: paths.cursorSettings });
           mutations.push({ type: "register-platform", platform, path: paths.cursorMcp });
-        } else if (platform === "codex" || platform === "pi") {
+        } else if (platform === "codex" || platform === "pi" || platform === "claude-code") {
           const commands = planHostInstall(platform, { home: paths.home, cwd: paths.cwd, env });
           if (commands.length > 0) {
             mutations.push({
               type: "install-host",
               platform,
               path:
-                platform === "codex"
-                  ? path.join(
-                      env.CODEX_HOME ?? path.join(paths.home, ".codex"),
-                      "plugins",
-                      "cache",
-                      "workflow-toolkit",
-                      "workit",
-                    )
-                  : path.join(
-                      env.PI_CODING_AGENT_DIR ?? path.join(paths.home, ".pi", "agent"),
-                      "settings.json",
-                    ),
+                platform === "claude-code"
+                  ? claudeInstallRecord(paths.home, env)
+                  : platform === "codex"
+                    ? path.join(
+                        env.CODEX_HOME ?? path.join(paths.home, ".codex"),
+                        "plugins",
+                        "cache",
+                        "workflow-toolkit",
+                        "workit",
+                      )
+                    : path.join(
+                        env.PI_CODING_AGENT_DIR ?? path.join(paths.home, ".pi", "agent"),
+                        "settings.json",
+                      ),
               commands,
             });
           }
@@ -446,6 +450,10 @@ export function buildSetupPreview(
 // Apply (Task 14: WZ-09, WZ-10, WZ-13-WZ-15; CA-08, CA-13, CA-14, CA-31).
 // ---------------------------------------------------------------------------
 
+/** The Claude Code plugin registry a Workit install is recorded in. */
+const claudeInstallRecord = (home: string, env: NodeJS.ProcessEnv): string =>
+  path.join(claudeConfigDir(home, env), "plugins", "installed_plugins.json");
+
 export type Platform = "opencode" | "cursor";
 
 export type SetupResultStatus = "Installed" | "Configured" | "Skipped" | "Failed";
@@ -1250,7 +1258,9 @@ export function applySetupPreview(
                   res.env.PI_CODING_AGENT_DIR ?? path.join(res.home, ".pi", "agent"),
                   "settings.json",
                 )
-              : "";
+              : mutation.platform === "claude-code"
+                ? claudeInstallRecord(res.home, res.env)
+                : "";
       if (mutation.path !== expectedPath) {
         entries.push({
           platform: mutation.platform,
@@ -1292,7 +1302,9 @@ export function applySetupPreview(
           ? isCodexWorkitInstalled(res.home, res.env)
           : mutation.platform === "pi"
             ? isPiWorkitInstalled(res.home, res.env)
-            : true;
+            : mutation.platform === "claude-code"
+              ? isClaudeWorkitInstalled(res.home, res.env, null)
+              : true;
       if (!verified) {
         entries.push({
           platform: mutation.platform,

package/src/core/support-matrix.ts

@@ -16,5 +16,9 @@ export const SUPPORT_MATRIX = {
   // an installed CLI drifts ahead so a fresh install never silently outruns
   // the qualification pin.
   codex: { cli: "0.153.4", desktopPackage: "26.901.20858", bundledCodexCli: "0.153.0-alpha.5" },
+  // Claude Code is a qualification host too: CI runs `claude plugin validate
+  // --strict` with exactly this CLI, and the hook output schema fixture
+  // (test/fixtures/claude-code-schemas) was transcribed from this binary.
+  claudeCode: { cli: "2.1.288" },
   os: ["ubuntu-latest", "macos-latest", "windows-latest"],
 } as const;

package/src/core/uninstall.ts

@@ -10,12 +10,28 @@ import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "n
 import os from "node:os";
 import path from "node:path";
 import { isWorkitPlugin } from "./registration";
+import {
+  claudeWorkitInstalls,
+  findHostExecutable,
+  runHostCommand,
+  type HostCommandRunner,
+} from "./host-install";
 
-export type UninstallHost = "opencode" | "cursor" | "codex" | "pi";
+export type UninstallHost = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
 
 export type UninstallAction =
   | { kind: "edit-json-remove"; path: string; detail: string }
-  | { kind: "remove-dir"; path: string; detail: string };
+  | { kind: "remove-dir"; path: string; detail: string }
+  /** A host-native uninstall (Claude Code owns its plugin cache and registry). */
+  | {
+      kind: "host-command";
+      path: string;
+      detail: string;
+      command: "claude";
+      args: string[];
+      /** The project a project/local-scope uninstall must run from; null for user scope. */
+      cwd: string | null;
+    };
 
 export type UninstallHostPlan = {
   host: UninstallHost;
@@ -49,6 +65,10 @@ export type UninstallPaths = {
   cursorSettings?: string;
   cursorMcp?: string;
   cursorPluginDir?: string;
+  /** Injectable host-command runner for host-native uninstall actions. */
+  runHostCommand?: HostCommandRunner;
+  /** Project directory for Claude Code project/local-scope installs (default: process cwd). */
+  cwd?: string;
 };
 
 type ResolvedUninstall = {
@@ -321,7 +341,32 @@ export function planUninstall(paths: UninstallPaths = {}): UninstallPlan {
       : [],
   };
 
-  return { hosts: [opencode, cursor, codex, pi] };
+  // Claude Code: one native `claude plugin uninstall <id> --scope <scope>`
+  // per recorded Workit install that applies here (user scope, plus this
+  // project's project/local scope, run from that project). A --plugin-dir
+  // pin is never recorded.
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const claudeInstalls = claudeWorkitInstalls(
+    home,
+    paths.env ?? process.env,
+    paths.cwd ?? process.cwd(),
+  );
+  const claude: UninstallHostPlan = {
+    host: "claude-code",
+    installed: claudeInstalls.length > 0,
+    actions: claudeInstalls.map((install) => ({
+      kind: "host-command" as const,
+      path: install.installPath,
+      detail: `claude plugin uninstall ${install.id} --scope ${install.scope}${
+        install.projectPath ? ` (in ${install.projectPath})` : ""
+      }`,
+      command: "claude" as const,
+      args: ["plugin", "uninstall", install.id, "--scope", install.scope],
+      cwd: install.projectPath,
+    })),
+  };
+
+  return { hosts: [opencode, cursor, codex, pi, claude] };
 }
 
 // CA-14 traversal guard: rm -rf is permitted ONLY on the exact resolved
@@ -390,6 +435,60 @@ const applyEditJsonRemove = (
   return { status: "removed" };
 };
 
+const CLAUDE_PLUGIN_ID = /^workit@[A-Za-z0-9._-]+$/;
+
+/** Runs a reviewed `claude plugin uninstall workit@<marketplace>`; any other
+ *  argv is refused, so a tampered plan cannot run an arbitrary command. */
+const applyClaudeUninstall = (
+  action: Extract<UninstallAction, { kind: "host-command" }>,
+  paths: UninstallPaths,
+): { status: UninstallResultStatus; detail?: string } => {
+  const [verb, sub, id, flag, scope, ...rest] = action.args;
+  const projectScoped = scope === "project" || scope === "local";
+  if (
+    action.command !== "claude" ||
+    verb !== "plugin" ||
+    sub !== "uninstall" ||
+    !CLAUDE_PLUGIN_ID.test(id ?? "") ||
+    flag !== "--scope" ||
+    !(scope === "user" || projectScoped) ||
+    rest.length > 0 ||
+    // user scope runs anywhere; project/local only from their project.
+    (projectScoped ? typeof action.cwd !== "string" : action.cwd !== null)
+  )
+    return {
+      status: "failed",
+      detail: `refusing unreviewed host command: ${action.args.join(" ")}`,
+    };
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const env = paths.env ?? process.env;
+  const recorded = claudeWorkitInstalls(home, env, action.cwd).some(
+    (install) =>
+      install.id === id &&
+      install.scope === scope &&
+      (install.projectPath === null
+        ? action.cwd === null
+        : path.resolve(install.projectPath) === path.resolve(action.cwd ?? "")),
+  );
+  if (!recorded)
+    return { status: "skipped", detail: `${id} (${scope} scope) is no longer installed` };
+  const executable = findHostExecutable("claude", { home, env });
+  if (!executable && !paths.runHostCommand)
+    return { status: "failed", detail: "claude executable was not found on PATH" };
+  const step = {
+    command: executable ?? "claude",
+    args: action.args,
+    ...(action.cwd === null ? {} : { cwd: action.cwd }),
+    purpose: `Uninstall the Workit Claude Code plugin ${id} (${scope} scope)`,
+  };
+  const result = paths.runHostCommand
+    ? paths.runHostCommand(step)
+    : runHostCommand(step, { home, env });
+  return result.exitCode === 0
+    ? { status: "removed", detail: action.detail }
+    : { status: "failed", detail: result.stderr || `exit ${result.exitCode}` };
+};
+
 /** Applies ONLY the reviewed plan actions with the given path options. Each
  *  planned action yields exactly one result entry; malformed host JSON fails
  *  its own action untouched while the remaining actions proceed (CA-13). */
@@ -400,7 +499,11 @@ export function applyUninstall(plan: UninstallPlan, paths: UninstallPaths = {}):
     for (const action of hostPlan.actions) {
       let status: UninstallResultStatus;
       let detail: string | undefined;
-      if (action.kind === "remove-dir") {
+      if (action.kind === "host-command") {
+        const outcome = applyClaudeUninstall(action, paths);
+        status = outcome.status;
+        detail = outcome.detail;
+      } else if (action.kind === "remove-dir") {
         // Resolve before comparing so ".."/symlink tricks can never widen the rm.
         const resolved = path.resolve(action.path);
         const allowed =

package/src/hooks/handle.ts

@@ -12,6 +12,20 @@ const NONE: HookDecision = { kind: "none" };
 /** Sessions already offered unfinished tasks in this process. */
 const offered = new Set<string>();
 
+/** The Workit plugin's worktree-isolated implementer is the one Claude Code
+ * subagent that writes. Claude namespaces plugin agents, so only the exact
+ * `workit:implementer` is ours: a bare or other-plugin `implementer` is not. */
+const CLAUDE_WORKTREE_IMPLEMENTER = "workit:implementer";
+
+const subagentStartText = (
+  host: HookInput["host"],
+  descriptor: HostDescriptor,
+  event: Extract<HookInput["event"], { kind: "subagent.start" }>,
+): string =>
+  host === "claude_code" && event.agentType === CLAUDE_WORKTREE_IMPLEMENTER
+    ? `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) working in its own git worktree: it may edit and commit there, within its brief's scope. Before the first commit, switch to a policy-compliant branch (\`git switch -c <type>/<slug>\`, e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never push, open a PR, or merge unless the brief asks for it.`
+    : `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`;
+
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
   const { descriptor } = deps;
   const event = input.event;
@@ -36,10 +50,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     case "shell.pre":
       return usable(descriptor.shellPolicy.deny) ? shellPolicy(input.cwd, event.command) : NONE;
     case "subagent.start":
-      return {
-        kind: "context",
-        text: `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`,
-      };
+      return { kind: "context", text: subagentStartText(input.host, descriptor, event) };
     case "compact.pre":
       return {
         kind: "notice",