@primitive.ai/prim 0.1.0-alpha.22 → 0.1.0-alpha.24

package/README.md

@@ -24,6 +24,15 @@ npx @primitive.ai/prim
 
 ## Quick Start
 
+One command does the whole install — auth, session hooks, daemon, git hooks,
+skill, and the welcome:
+
+```bash
+prim setup                 # add --agent codex for Codex, --no-daemon to skip the daemon
+```
+
+Or run the steps individually:
+
 ```bash
 # 1. Authenticate via browser (WorkOS OAuth)
 prim auth login
@@ -38,10 +47,26 @@ prim daemon start
 prim hooks install
 ```
 
-An AI coding agent can drive the entire setup itself — see [`setup.md`](./setup.md).
+`prim claude install` also writes a scoped `Bash(npx --yes @primitive.ai/prim@latest:*)`
+allow-rule into `.claude/settings.json`, so an agent's prim calls don't stall on a
+permission prompt.
+
+An AI coding agent can drive the setup itself — see [`setup.md`](./setup.md).
 
 ## Commands
 
+### Setup
+
+```bash
+prim setup                   # Run the whole install in one shot
+prim setup --agent codex     # Same, for OpenAI Codex
+prim setup --no-daemon       # Skip the companion daemon
+```
+
+Orchestrates auth → session hooks → daemon → git hooks → skill → welcome,
+re-running each underlying command so every step behaves exactly as if run by
+hand (including the browser login). Idempotent — safe to re-run.
+
 ### Auth
 
 ```bash
@@ -83,16 +108,23 @@ prim daemon start      # start (stop / restart / status)
 Read and respond to the decision graph.
 
 ```bash
-prim decisions recent              # Recent decisions feed
-prim decisions show <id>           # Drill into one decision
-prim decisions cascade <id>        # Blast radius of a decision
-prim decisions check --files <…>   # Active decisions referencing files (warn-only)
-prim decisions confirm <id>        # Answer a rationale-confirmation prompt
+prim decisions recent                    # Recent decisions feed
+prim decisions show <id>                 # Drill into one decision
+prim decisions cascade <id>              # Blast radius of a decision
+prim decisions check --files <…>         # Active decisions referencing files (warn-only)
+prim decisions confirm <id>              # Answer a rationale-confirmation prompt
+prim decisions create --intent <…>       # Author a decision directly (flags-only)
+prim decisions link <child> --on <parent>    # Relate: <child> depends on <parent>
+prim decisions unlink <child> --on <parent>  # Remove that dependency
 ```
 
 `<id>` accepts a full decision ID or its short ID. STDOUT is machine-readable
 JSON; human-readable status goes to STDERR.
 
+`link` / `unlink` curate the dependency edges the automatic linker would otherwise
+own — `<child>` depends on `<parent>`. Both are idempotent and refuse any link that
+would create a cycle (exit 2); an unresolved id exits 4.
+
 ### Reconcile
 
 ```bash

package/SKILL.md

@@ -9,7 +9,7 @@ description: Use the prim CLI for Primitive's decision graph — passive decisio
 
 ## Mental model
 
-As your team codes, prim passively captures the **decisions** you make -- which library, which pattern, which config value -- into a queryable graph, and links them: a decision can depend on earlier decisions and reference the files it touched. When a later change conflicts with a load-bearing prior decision, prim **gates** the edit and surfaces the decision for review.
+As your team codes, prim passively captures the **decisions** you make -- which library, which pattern, which config value -- into a queryable graph, and links them: a decision can depend on earlier decisions (auto-linked from shared files, or related by hand — see *Relate decisions*) and reference the files it touched. When a later change conflicts with a load-bearing prior decision, prim **gates** the edit and surfaces the decision for review.
 
 You never invoke capture. It runs automatically through the session hooks installed by `npx --yes @primitive.ai/prim claude install` (Claude Code) or `npx --yes @primitive.ai/prim codex install` (Codex). Your job is to **respond** to the gate, **read** the graph before load-bearing edits, and **answer** the occasional rationale confirmation.
 
@@ -77,6 +77,25 @@ npx --yes @primitive.ai/prim decisions create --intent "Adopt prosemirror-collab
 
 Only `--intent` is required. Optional: `--kind` (change|exploration|task_execution|unclear, default change), `--rationale`, `--area`, `--decided`, `--alternatives` (comma-separated), `--confidence` (high|medium|low, default high), `--reversibility` (high|low, default high), and `--files` (comma-separated repo-relative paths the decision governs — pass these to make the conflict gate fire on later edits to those files, same path form as `decisions check`). STDOUT is the created identity `{ decisionId, shortId, createdAt }`; STDERR prints `[prim] created dec_<short>.` — pass that `dec_<short>` straight into `decisions show` / `cascade` / `confirm`. Author on the user's behalf only when they ask for a decision to be recorded; don't narrate your own routine edits into the graph (the hooks already do that).
 
+## Relate decisions (link / unlink)
+
+prim links decisions automatically when their files overlap, but that heuristic misses real connections and occasionally invents wrong ones. When the user asks you to **relate two existing decisions** — "B depends on A", "these are connected", wiring up two orphans — or to **cut a wrong link**, do it by hand:
+
+```
+npx --yes @primitive.ai/prim decisions link <child> --on <parent>      # record that <child> depends on <parent>
+npx --yes @primitive.ai/prim decisions unlink <child> --on <parent>    # remove that dependency
+```
+
+Direction is **`<child>` depends on `<parent>`** — the parent is the prerequisite. Read the echoed verdict to confirm you got the arrow right: `[prim] <child> now depends on <parent>.` After linking, `decisions show <child>` lists `<parent>` upstream and `decisions cascade <parent>` shows `<child>` in its downstream blast radius; after unlinking they drop. Both ids accept `dec_<short>` or a full id and may be any two decisions in your org, regardless of status.
+
+Safe to run repeatedly:
+
+- **Idempotent** — re-linking an existing edge (or unlinking a missing one) is a no-op that still exits 0 (`already_linked` / `not_linked`).
+- **Acyclic** — a self-loop, or any link that would close a dependency cycle, is refused with exit 2 (with the offending chain when it's short enough to render); the graph stays a DAG.
+- **Exit codes** (treat non-zero as actionable): `0` success or no-op; `2` a refused link (self-loop, cycle, or an ambiguous short id — retry with the full id); `4` an id that doesn't resolve. After a non-zero exit, branch on the exit code and the `[prim]` STDERR verdict, **not** on STDOUT keys: only the exit-0 outcomes carry the full `{ outcome, childId, childShortId, parentId, parentShortId }`; a refused link prints a smaller `{ outcome, … }`, and an unresolved id (exit 4) prints nothing to STDOUT.
+
+Like authoring, relate only what the user asks for — don't invent relationships they didn't state.
+
 ## Presence
 
 With the daemon running (`npx --yes @primitive.ai/prim daemon start`), `npx --yes @primitive.ai/prim daemon status` includes the live online count in its STDOUT JSON (when presence is fresh); Claude Code surfaces it in the statusline as `team: N online`. Your captured decisions are attributed to your agent automatically -- no flag required.

package/dist/index.js

@@ -401,6 +401,7 @@ var REGISTRATIONS = [
   makeRegistration("SessionStart", "*", SESSION_START_BIN),
   makeRegistration("SessionEnd", "*", SESSION_END_BIN)
 ];
+var PRIM_PERMISSION_RULE = "Bash(npx --yes @primitive.ai/prim@latest:*)";
 function settingsPathFor(scope) {
   return scope === "user" ? USER_SCOPE_PATH : projectScopePath();
 }
@@ -463,12 +464,36 @@ function applyStatusLine(settings) {
     }
   };
 }
+function applyPermissions(settings) {
+  const permissions = settings.permissions ?? {};
+  const allow = permissions.allow ?? [];
+  if (allow.includes(PRIM_PERMISSION_RULE)) {
+    return settings;
+  }
+  return {
+    ...settings,
+    permissions: { ...permissions, allow: [...allow, PRIM_PERMISSION_RULE] }
+  };
+}
+function removePrimPermission(settings) {
+  const permissions = settings.permissions;
+  if (!permissions?.allow?.includes(PRIM_PERMISSION_RULE)) {
+    return settings;
+  }
+  const allow = permissions.allow.filter((rule) => rule !== PRIM_PERMISSION_RULE);
+  const nextPermissions = {
+    ...permissions,
+    allow: allow.length > 0 ? allow : void 0
+  };
+  const hasOtherPerms = Object.values(nextPermissions).some((v) => v !== void 0);
+  return { ...settings, permissions: hasOtherPerms ? nextPermissions : void 0 };
+}
 function applyInstall(settings, options = {}) {
   const hooks = { ...settings.hooks ?? {} };
   for (const reg of REGISTRATIONS) {
     hooks[reg.event] = ensureRegistration(hooks[reg.event] ?? [], reg, options.force ?? false);
   }
-  return applyStatusLine({ ...settings, hooks });
+  return applyPermissions(applyStatusLine({ ...settings, hooks }));
 }
 function applyUninstall(settings) {
   const source = settings.hooks ?? {};
@@ -486,7 +511,7 @@ function applyUninstall(settings) {
   if (isPrimStatusLine(next)) {
     next.statusLine = void 0;
   }
-  return next;
+  return removePrimPermission(next);
 }
 function captureInstalled(settings) {
   return CAPTURE_EVENTS.some(
@@ -1228,6 +1253,9 @@ async function fetchRecent(args, deps = defaultDeps2) {
       RECENT_TIMEOUT_MS
     );
     const result = { decisions: res.decisions };
+    if (res.viewerHasDecisions !== void 0) {
+      result.viewerHasDecisions = res.viewerHasDecisions;
+    }
     if (res.unavailable !== void 0) {
       result.unavailable = res.unavailable;
     }
@@ -1414,8 +1442,85 @@ function formatCreateJson(outcome) {
   return JSON.stringify(outcome, null, 2);
 }
 
-// src/decisions/show.ts
+// src/decisions/link.ts
+var RELATE_TIMEOUT_MS = 1e4;
+var defaultDeps5 = { getClient };
 var NOT_FOUND_RE3 = /not found/i;
+var AMBIGUOUS_RE2 = /ambiguous/i;
+var CYCLE_RE = /cycle/i;
+var LinkNotFoundError = class extends Error {
+  constructor(which) {
+    super(`Decision not found: ${which}`);
+    this.name = "LinkNotFoundError";
+  }
+};
+function isRelateRejection(outcome) {
+  return outcome.outcome === "self_loop" || outcome.outcome === "would_cycle" || outcome.outcome === "ambiguous";
+}
+function foldRelateError(err) {
+  if (err instanceof Error) {
+    if (NOT_FOUND_RE3.test(err.message)) {
+      throw new LinkNotFoundError(err.message.includes("parent") ? "parent" : "child");
+    }
+    if (AMBIGUOUS_RE2.test(err.message)) {
+      return { outcome: "ambiguous", which: err.message.includes("(parent)") ? "parent" : "child" };
+    }
+    if (CYCLE_RE.test(err.message)) {
+      return { outcome: "would_cycle", detail: err.message };
+    }
+    if (/itself/i.test(err.message)) {
+      return { outcome: "self_loop" };
+    }
+  }
+  throw err;
+}
+async function relate(path, request, deps) {
+  const client = deps.getClient();
+  try {
+    const outcome = await client.post(path, request, {
+      signal: AbortSignal.timeout(RELATE_TIMEOUT_MS)
+    });
+    return { request, outcome };
+  } catch (err) {
+    return { request, outcome: foldRelateError(err) };
+  }
+}
+function fetchLink(child, parent, deps = defaultDeps5) {
+  return relate("/api/cli/decisions/link", { child, parent }, deps);
+}
+function fetchUnlink(child, parent, deps = defaultDeps5) {
+  return relate("/api/cli/decisions/unlink", { child, parent }, deps);
+}
+function endpointRef(outcome, side) {
+  return side === "child" ? renderIdentifier({ shortId: outcome.childShortId, id: outcome.childId }) : renderIdentifier({ shortId: outcome.parentShortId, id: outcome.parentId });
+}
+function formatRelateHuman(result) {
+  const { request, outcome } = result;
+  switch (outcome.outcome) {
+    case "linked":
+      return `[prim] ${endpointRef(outcome, "child")} now depends on ${endpointRef(outcome, "parent")}.`;
+    case "already_linked":
+      return `[prim] ${endpointRef(outcome, "child")} already depends on ${endpointRef(outcome, "parent")}; nothing to change.`;
+    case "unlinked":
+      return `[prim] ${endpointRef(outcome, "child")} no longer depends on ${endpointRef(outcome, "parent")}.`;
+    case "not_linked":
+      return `[prim] ${endpointRef(outcome, "child")} did not depend on ${endpointRef(outcome, "parent")}; nothing to change.`;
+    case "self_loop":
+      return "[prim] a decision cannot depend on itself.";
+    case "would_cycle":
+      return `[prim] refusing to link \u2014 ${outcome.detail}.`;
+    default: {
+      const typed = outcome.which === "parent" ? request.parent : request.child;
+      return `[prim] the ${outcome.which} id "${typed}" is ambiguous in this organization \u2014 retry with the full decision id.`;
+    }
+  }
+}
+function formatRelateJson(result) {
+  return JSON.stringify(result.outcome, null, 2);
+}
+
+// src/decisions/show.ts
+var NOT_FOUND_RE4 = /not found/i;
 function colorStatus(status) {
   if (status === "under_review") {
     return color(status, "orange");
@@ -1426,14 +1531,14 @@ function colorStatus(status) {
   return color(status, "gray");
 }
 var SHOW_TIMEOUT_MS = 1e4;
-var defaultDeps5 = { getClient };
+var defaultDeps6 = { getClient };
 var DecisionNotFoundError = class extends Error {
   constructor(idOrShortId) {
     super(`Decision not found: ${idOrShortId}`);
     this.name = "DecisionNotFoundError";
   }
 };
-async function fetchShow(idOrShortId, deps = defaultDeps5) {
+async function fetchShow(idOrShortId, deps = defaultDeps6) {
   const params = new URLSearchParams({ id: idOrShortId });
   const client = deps.getClient();
   try {
@@ -1444,7 +1549,7 @@ async function fetchShow(idOrShortId, deps = defaultDeps5) {
       SHOW_TIMEOUT_MS
     );
   } catch (err) {
-    if (err instanceof Error && NOT_FOUND_RE3.test(err.message)) {
+    if (err instanceof Error && NOT_FOUND_RE4.test(err.message)) {
       throw new DecisionNotFoundError(idOrShortId);
     }
     throw err;
@@ -1654,6 +1759,40 @@ function registerDecisionsCommands(program2) {
       throw err;
     }
   });
+  decisions.command("link <child>").description("Record that <child> depends on <parent> (adds a dependency edge)").requiredOption("--on <parent>", "The decision <child> depends on").action(async (child, opts) => {
+    try {
+      const result = await fetchLink(child, opts.on);
+      console.error(formatRelateHuman(result));
+      console.log(formatRelateJson(result));
+      if (isRelateRejection(result.outcome)) {
+        process.exitCode = EXIT_USAGE;
+      }
+    } catch (err) {
+      if (err instanceof LinkNotFoundError) {
+        console.error(`[prim] ${err.message}`);
+        process.exitCode = EXIT_NOT_FOUND;
+        return;
+      }
+      throw err;
+    }
+  });
+  decisions.command("unlink <child>").description("Remove <child>'s recorded dependency on <parent>").requiredOption("--on <parent>", "The decision <child> no longer depends on").action(async (child, opts) => {
+    try {
+      const result = await fetchUnlink(child, opts.on);
+      console.error(formatRelateHuman(result));
+      console.log(formatRelateJson(result));
+      if (isRelateRejection(result.outcome)) {
+        process.exitCode = EXIT_USAGE;
+      }
+    } catch (err) {
+      if (err instanceof LinkNotFoundError) {
+        console.error(`[prim] ${err.message}`);
+        process.exitCode = EXIT_NOT_FOUND;
+        return;
+      }
+      throw err;
+    }
+  });
 }
 
 // src/commands/hooks.ts
@@ -2117,6 +2256,82 @@ function registerSessionCommands(program2) {
   });
 }
 
+// src/commands/setup.ts
+import { spawnSync } from "child_process";
+var EXIT_INCOMPLETE = 1;
+function planSetupSteps(opts) {
+  const scopeArgs = opts.scope === "user" ? ["--scope", "user"] : [];
+  const steps = [
+    {
+      key: "session",
+      label: opts.agent === "codex" ? "Codex integration" : "Claude Code integration",
+      args: [opts.agent, "install", ...scopeArgs],
+      required: true
+    }
+  ];
+  if (opts.daemon) {
+    steps.push({
+      key: "daemon",
+      label: "Companion daemon",
+      args: ["daemon", "start"],
+      required: false
+    });
+  }
+  steps.push({ key: "hooks", label: "Git hooks", args: ["hooks", "install"], required: true });
+  steps.push({ key: "skill", label: "Agent skill", args: ["skill", "install"], required: true });
+  return steps;
+}
+function registerSetupCommand(program2) {
+  program2.command("setup").description(
+    "Install everything in one shot (auth, session + git hooks, daemon, skill, welcome)"
+  ).option("--agent <agent>", "claude or codex", "claude").option("--scope <scope>", "project or user (session integration)", "project").option("--no-daemon", "skip starting the companion daemon").action((opts) => {
+    const agent = opts.agent === "codex" ? "codex" : "claude";
+    const scope = opts.scope === "user" ? "user" : "project";
+    const self = process.argv[1];
+    const run = (args, capture = false) => {
+      const r = spawnSync(process.execPath, [self, ...args], {
+        stdio: capture ? ["inherit", "pipe", "inherit"] : "inherit",
+        encoding: "utf-8"
+      });
+      return { code: r.status ?? 1, stdout: capture ? r.stdout ?? "" : "" };
+    };
+    const results = {};
+    const note = (msg) => {
+      process.stderr.write(`[prim] ${msg}
+`);
+    };
+    const isAuthed = (json) => {
+      try {
+        return JSON.parse(json || "{}").authenticated === true;
+      } catch {
+        return false;
+      }
+    };
+    if (isAuthed(run(["auth", "status", "--json"], true).stdout)) {
+      note("auth \xB7 already authenticated");
+      results.auth = "ok";
+    } else {
+      note("auth \xB7 opening browser to authenticate\u2026");
+      run(["auth", "login"]);
+      results.auth = isAuthed(run(["auth", "status", "--json"], true).stdout) ? "ok" : "failed";
+    }
+    for (const step of planSetupSteps({ agent, daemon: opts.daemon, scope })) {
+      note(`${step.label} \xB7 installing\u2026`);
+      const { code } = run(step.args);
+      results[step.key] = code === 0 ? "ok" : step.required ? "failed" : "skipped";
+    }
+    note("welcome");
+    run(["welcome"]);
+    results.welcome = "ok";
+    const failed = Object.entries(results).filter(([, v]) => v === "failed").map(([k]) => k);
+    const trail = Object.entries(results).map(([k, v]) => `${k}:${v}`).join(" \xB7 ");
+    note(
+      `setup ${failed.length === 0 ? "complete" : `incomplete (failed: ${failed.join(", ")})`} \u2014 ${trail}`
+    );
+    process.exit(failed.length === 0 ? 0 : EXIT_INCOMPLETE);
+  });
+}
+
 // src/commands/skill.ts
 import {
   closeSync as closeSync2,
@@ -2347,14 +2562,32 @@ var REVERSE_PROMPT_LINES = [
   "to focus on those goals?"
 ];
 var REVERSE_PROMPT = REVERSE_PROMPT_LINES.join(" ");
+var CALLOUT_TITLE = "Your turn";
+var CALLOUT_INDENT = "  ";
+function ruledQuestion(lines) {
+  const prefix = `\u250C\u2500 ${CALLOUT_TITLE} `;
+  const width = Math.max(
+    `${prefix}\u2510`.length,
+    ...lines.map((line) => CALLOUT_INDENT.length + line.length + 1)
+  );
+  const top = `${prefix}${"\u2500".repeat(width - prefix.length - 1)}\u2510`;
+  const bottom = `\u2514${"\u2500".repeat(top.length - 2)}\u2518`;
+  return [
+    color(top, "green"),
+    ...lines.map((line) => `${CALLOUT_INDENT}${line}`),
+    color(bottom, "green")
+  ];
+}
 function welcomeStateFromRecent(result) {
   if (result.unavailable !== void 0) {
     return { org: "unknown" };
   }
-  if (result.decisions.length === 0) {
-    return { org: "empty" };
+  const recent = result.decisions.slice(0, RECENT_LIMIT);
+  const viewerHasDecisions = result.viewerHasDecisions ?? result.decisions.length > 0;
+  if (!viewerHasDecisions) {
+    return { org: "seed", recent };
   }
-  return { org: "active", recent: result.decisions.slice(0, RECENT_LIMIT) };
+  return { org: "active", recent };
 }
 function formatWelcome(state) {
   const cmd = (command, desc) => `  ${dim(command.padEnd(CMD_GUTTER))}${desc}`;
@@ -2385,14 +2618,15 @@ function formatWelcome(state) {
       cmd("prim decisions check --files <files>", "what governs files you're about to change"),
       cmd("prim --help", "everything else")
     ];
-  } else if (state.org === "empty") {
+  } else if (state.org === "seed") {
+    const teamContext = state.recent.length > 0 ? [bold("Recent team decisions"), ...state.recent.map(formatRecentRow), ""] : [];
     body = [
+      ...teamContext,
       bold("Let's seed your decision graph"),
-      "Your team has no decisions recorded yet. Tell me, in your own words:",
-      "",
-      ...REVERSE_PROMPT_LINES.map((line) => `  ${line}`),
+      "You haven't recorded a decision yet \u2014 answer this and I'll record",
+      "each goal as a decision:",
       "",
-      "Share your answer and I'll record each goal as a decision."
+      ...ruledQuestion(REVERSE_PROMPT_LINES)
     ];
   } else {
     body = [
@@ -2402,14 +2636,20 @@ function formatWelcome(state) {
       cmd("prim --help", "everything else")
     ];
   }
-  return [...head, ...body, "", dim("App: https://app.getprimitive.ai")].join("\n");
+  const footer = state.org === "seed" ? [] : ["", dim("App: https://app.getprimitive.ai")];
+  return [...head, ...body, ...footer].join("\n");
 }
 function welcomeJson(state) {
   if (state.org === "active") {
     return { welcomed: true, org: "active", recent: state.recent };
   }
-  if (state.org === "empty") {
-    return { welcomed: true, org: "empty", reversePrompt: REVERSE_PROMPT };
+  if (state.org === "seed") {
+    return {
+      welcomed: true,
+      org: "seed",
+      reversePrompt: REVERSE_PROMPT,
+      recent: state.recent
+    };
   }
   return { welcomed: true, org: "unknown" };
 }
@@ -2444,6 +2684,7 @@ registerDaemonCommands(program);
 registerReconcileCommands(program);
 registerStatuslineCommands(program);
 registerWelcomeCommand(program);
+registerSetupCommand(program);
 process.on("unhandledRejection", (err) => {
   const msg = err instanceof Error ? err.message : String(err);
   console.error(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitive.ai/prim",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "CLI for Primitive's decision graph — passive decision capture, conflict gate, and team presence",
   "type": "module",
   "license": "MIT",