@primitive.ai/prim 0.1.0-alpha.51 → 0.1.0-alpha.53

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prim
-description: Use the prim CLI for Primitive’s decision graph. MUST INVOKE before finishing any coding, planning, specification, or review task where the user or agent chose between plausible approaches or established or changed a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction—even when Primitive was not mentioned. Also invoke for Primitive setup, reading decisions, conflict gates, reconcile, rationale confirmations, linking, and team presence. SKIP routine implementation that merely follows an existing decision, temporary tactics, and unrelated uses of “decision.”
+description: Use the prim CLI for Primitive’s decision graph. MUST INVOKE before finishing any coding, planning, specification, or review task where the user or agent chose between plausible approaches or established or changed a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction—even when Primitive was not mentioned. Also invoke for Primitive setup, reading decisions, conflict gates, reconcile, rationale confirmations, linking, and team presence. SKIP — do not invoke even to check — when the task shows no fork that should guide future work, for example temporary tactics (a change that is explicitly temporary or to-be-reverted); routine implementation that merely follows an existing decision or a convention already visible in the code or repo instructions; or the word “decision” merely naming code, data, or UI. Such signals need no graph lookup to rule out.
 ---
 
 # Working with the prim CLI
@@ -80,7 +80,7 @@ Confirmations are author-targeted and rare by design; answering keeps the graph'
 
 Capture is automatic for low-level choices made while coding in an active repo. Use the deliberate CLI path for higher-order decisions that emerge in conversation: goals, priorities, principles, invariants, constraints, defaults, commitments, durable tradeoffs, and exceptions.
 
-A decision worth deliberately recording is a genuine **fork in the road**: the user or agent encountered multiple plausible paths, selected one, and that selection should inform future work. Record the chosen behavior, direction, constraint, or tradeoff—not routine implementation needed to finish the task or follow an existing convention. A teammate working elsewhere should benefit from knowing it.
+A decision worth deliberately recording is a genuine **fork in the road**: the user or agent encountered multiple plausible paths, selected one, and that selection should inform future work. Record the chosen behavior, direction, constraint, or tradeoff—not routine implementation needed to finish the task or follow an existing convention. Small design choices made in-flight while implementing—such as edge-case handling, parameter defaults, retry or timeout values, log levels, naming, or the shape of an internal data structure—are implementation details even when you chose between alternatives: never deliberately record them or spend a rationale question on them; passive capture already covers coding activity. A teammate working elsewhere should benefit from knowing it.
 
 ### Ground the rationale in real sources
 
@@ -91,8 +91,10 @@ Record only rationale supported by those sources. Do not mistake the implementat
 For proactively identified decisions in an active repo, let confidence in the rationale determine the interaction:
 
 - **Clear and well-supported** — record the decision and rationale silently at the natural task boundary.
-- **Plausible but uncertain** — at the task boundary, state the proposed rationale and ask for lightweight confirmation: “I understand the reason for choosing X to be Y. Is that right?” Record after confirmation or correction.
-- **No supported rationale** — at the task boundary, ask one focused question: “What made you choose X over the other path?” Record after the answer.
+- **Plausible but uncertain** — at the task boundary, state the proposed rationale and ask for lightweight confirmation: “I understand the reason for choosing X to be Y. Is that right?” Record in the same turn with the rationale omitted; add it once confirmed or corrected.
+- **No supported rationale** — at the task boundary, ask one focused question: “What made you choose X over the other path?” Record in the same turn with the rationale omitted; add it when the answer arrives.
+
+In both cases the question is a courtesy, not a gate: never make the record wait on an answer, and never fabricate a rationale to fill the gap. An unanswered question with no record is the only wrong outcome.
 
 These questions share the interruption budget below; never ask separate questions for the decision and its rationale. If both are uncertain, combine them into one concise prompt. An explicit request to “add this decision to Primitive” still records immediately with the information supplied—do not delay it to demand rationale.
 
@@ -124,7 +126,7 @@ When the user asks to record a decision—for example, “add this decision to P
 
 ### Clear decisions: record without interrupting
 
-When the user clearly makes a durable fork-in-the-road decision without explicitly asking to record it, record it at the next natural task boundary without asking a redundant confirmation question **when passive capture is active**. In an inactive repo, present it and obtain the per-create approval above. Preserve the user's meaning and stated rationale; do not strengthen, broaden, or embellish it. Prefer the governing position over the implementation activity that revealed it.
+When the user clearly makes a durable fork-in-the-road decision without explicitly asking to record it, record it at the next natural task boundary without asking a redundant confirmation question **when passive capture is active**. An explicit ratification of a direction—“agreed,” “ship it that way,” or any equivalent affirmation—is such a decision even when the ratified option was your own proposal: the ratification is the approval, so record it and do not ask whether to record. That rule is general: in an active repository, never ask permission to record — the only question the budget permits is the single rationale question, and only when no rationale was stated. In an inactive repo, present it and obtain the per-create approval above. Preserve the user's meaning and stated rationale; do not strengthen, broaden, or embellish it. Prefer the governing position over the implementation activity that revealed it.
 
 Examples that qualify:
 

package/dist/{chunk-UJEQX52M.js → chunk-ROL7SDXX.js}

@@ -8,11 +8,15 @@ import {
 // src/commands/skill.ts
 import { randomUUID } from "crypto";
 import {
+  constants as constants2,
   closeSync as closeSync2,
   existsSync as existsSync2,
+  fstatSync as fstatSync2,
   fsyncSync,
+  lstatSync as lstatSync2,
   openSync as openSync2,
   readFileSync as readFileSync2,
+  readSync as readSync2,
   renameSync,
   rmSync as rmSync2,
   writeFileSync
@@ -21,6 +25,7 @@ import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { createPatch } from "diff";
+import { parse as parseYaml2 } from "yaml";
 
 // src/output.ts
 function printJson(data) {
@@ -322,6 +327,74 @@ function statusClaudePlugin(cwd, opts) {
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 var SKILL_BEGIN = "<!-- BEGIN PRIM SKILL v1 -->";
 var SKILL_END = "<!-- END PRIM SKILL v1 -->";
+var CODEX_GUIDANCE_LIMIT_BYTES = 1024 * 1024;
+var CODEX_DEFAULT_PROJECT_GUIDANCE_BYTES = 32 * 1024;
+var SKILL_BEGIN_BUFFER = Buffer.from(SKILL_BEGIN);
+var SKILL_END_BUFFER = Buffer.from(SKILL_END);
+function readCodexGuidance(path) {
+  try {
+    const entry = lstatSync2(path);
+    if (entry.isSymbolicLink() || !entry.isFile()) return null;
+    const fd = openSync2(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
+    try {
+      const opened = fstatSync2(fd);
+      if (!opened.isFile() || opened.size > CODEX_GUIDANCE_LIMIT_BYTES) return null;
+      const bytes = Buffer.allocUnsafe(CODEX_GUIDANCE_LIMIT_BYTES + 1);
+      let length = 0;
+      while (length < bytes.length) {
+        const read = readSync2(fd, bytes, length, bytes.length - length, length);
+        if (read === 0) break;
+        length += read;
+      }
+      return length > CODEX_GUIDANCE_LIMIT_BYTES ? null : bytes.subarray(0, length);
+    } finally {
+      closeSync2(fd);
+    }
+  } catch (error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? void 0 : null;
+  }
+}
+function effectiveCodexGuidance(scope) {
+  const override = readCodexGuidance(join2(scope, "AGENTS.override.md"));
+  if (override === null) return null;
+  if (override !== void 0 && override.toString("utf8").trim().length > 0) return override;
+  const base = readCodexGuidance(join2(scope, "AGENTS.md"));
+  return base ?? null;
+}
+function hasUsablePrimBlock(content, visibleBytes) {
+  const begin = content.indexOf(SKILL_BEGIN_BUFFER);
+  const end = content.indexOf(SKILL_END_BUFFER);
+  if (begin === -1 || end <= begin + SKILL_BEGIN_BUFFER.length || end + SKILL_END_BUFFER.length > visibleBytes || content.indexOf(SKILL_BEGIN_BUFFER, begin + SKILL_BEGIN_BUFFER.length) !== -1 || content.indexOf(SKILL_END_BUFFER, end + SKILL_END_BUFFER.length) !== -1) {
+    return false;
+  }
+  const block = content.subarray(begin + SKILL_BEGIN_BUFFER.length, end).toString("utf8").trim();
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/u.exec(block);
+  if (!match || match[2].trim().length === 0) return false;
+  try {
+    const metadata = parseYaml2(match[1]);
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) return false;
+    const fields = metadata;
+    return fields.name === "prim" && typeof fields.description === "string" && fields.description.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+function hasUsableCodexGuidance(projectRoot) {
+  try {
+    const codexHome = process.env.CODEX_HOME?.trim() ? resolve2(process.env.CODEX_HOME) : join2(homedir2(), ".codex");
+    const scopes = [
+      { path: codexHome, visibleBytes: CODEX_GUIDANCE_LIMIT_BYTES },
+      { path: projectRoot, visibleBytes: CODEX_DEFAULT_PROJECT_GUIDANCE_BYTES }
+    ];
+    return scopes.some(({ path, visibleBytes }) => {
+      const guidance = effectiveCodexGuidance(path);
+      return guidance !== null && hasUsablePrimBlock(guidance, visibleBytes);
+    });
+  } catch {
+    return false;
+  }
+}
 var TARGET_CANDIDATES = [
   "CLAUDE.md",
   "AGENTS.md",
@@ -516,5 +589,6 @@ function registerSkillCommands(program) {
 export {
   printJson,
   refreshClaudePlugins,
+  hasUsableCodexGuidance,
   registerSkillCommands
 };

package/dist/hooks/session-start.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
+  hasUsableCodexGuidance,
   refreshClaudePlugins
-} from "../chunk-UJEQX52M.js";
+} from "../chunk-ROL7SDXX.js";
 import {
   buildHookOutput,
   handoffHookOutput
@@ -65,7 +66,14 @@ function reauthNoticeFields(agent) {
 
 // src/hooks/session-start-core.ts
 var DAEMON_TIMEOUT_MS = 250;
-var PRIM_SKILL_REMINDER = "Primitive is active in this repository. When this task chooses between plausible approaches or establishes or changes a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction, invoke the `prim` skill before finishing. Never invoke `prim` for routine implementation that merely follows an existing decision made before this task or for temporary tactics; they never qualify, including for evaluation. When a direct request replaces one lasting default with another but supplies no rationale, complete the work, invoke the skill, and ask one concise rationale question at the task boundary, even if the user requested only implementation or recording fails.";
+var PRIM_TRIGGER = "When this task chooses between plausible approaches or establishes or changes a lasting goal, priority, constraint, invariant, default, commitment, tradeoff, exception, or shared instruction";
+var PRIM_EXCLUSIONS = "Never invoke `prim` for routine implementation that merely follows an existing decision made before this task or for temporary tactics; they never qualify, including for evaluation.";
+function primReminder(action, rationaleAction) {
+  return `Primitive is active in this repository. ${PRIM_TRIGGER}, ${action} before finishing. ${PRIM_EXCLUSIONS} When a direct request replaces one lasting default with another but supplies no rationale, complete the work, ${rationaleAction}, and ask one concise rationale question at the task boundary, even if the user requested only implementation or recording fails.`;
+}
+var PRIM_SKILL_REMINDER = primReminder("invoke the `prim` skill", "invoke the skill");
+var CODEX_PRIM_ACTION = "follow the installed Prim workflow and use the `prim` CLI";
+var CODEX_PRIM_REMINDER = primReminder(CODEX_PRIM_ACTION, CODEX_PRIM_ACTION);
 async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.timeout(FEEDBACK_DEADLINE_MS)) {
   let envelope;
   try {
@@ -119,13 +127,15 @@ async function processSessionStart(raw, agent, feedbackSignal = AbortSignal.time
       { callerEnv: getSiteUrl() },
       { timeoutMs: DAEMON_TIMEOUT_MS }
     );
-    if (snapshot && !snapshot.presenceStale && typeof snapshot.onlineCount === "number") {
-      return {
-        output: buildHookOutput({
-          additionalContext: `[prim] team: ${snapshot.onlineCount} online`
-        })
-      };
+    const presence = snapshot && !snapshot.presenceStale && typeof snapshot.onlineCount === "number" ? `[prim] team: ${snapshot.onlineCount} online` : void 0;
+    let proactive = false;
+    try {
+      const projectRoot = gitToplevel(cwd);
+      proactive = projectRoot !== null && isRepoActiveForCapture(cwd) && hasUsableCodexGuidance(projectRoot);
+    } catch {
     }
+    const additionalContext = [proactive ? CODEX_PRIM_REMINDER : void 0, presence].filter((value) => value !== void 0).join("\n\n");
+    return { output: buildHookOutput({ additionalContext }) };
   }
   if (agent === "claude_code") {
     const additionalContext = active && skillState.installed > 0 ? PRIM_SKILL_REMINDER : void 0;

package/dist/index.js

@@ -25,7 +25,7 @@ import {
 import {
   printJson,
   registerSkillCommands
-} from "./chunk-UJEQX52M.js";
+} from "./chunk-ROL7SDXX.js";
 import {
   fetchFeedbackCapability
 } from "./chunk-WELBNODJ.js";

package/package.json

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