create-egregore 0.19.33 → 0.20.1

package/runtime/prime/bin/pi-product-workflows.mjs

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+
+const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+function resultCode(result) {
+  return Number(result?.code ?? result?.status ?? 0);
+}
+
+function commandFailure(label, result) {
+  const detail = String(result?.stderr || result?.stdout || "").replace(ANSI, "").trim();
+  return new Error(detail ? `${label}: ${detail}` : `${label} failed`);
+}
+
+async function checkedExec(pi, command, args, options = {}, label = command) {
+  const result = await pi.exec(command, args, options);
+  if (resultCode(result) !== 0) throw commandFailure(label, result);
+  return String(result.stdout || "");
+}
+
+function readJson(file, fallback = {}) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function cleanArgs(value) {
+  return String(value || "").trim();
+}
+
+function walkMarkdown(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkMarkdown(full, files);
+    else if (entry.isFile() && entry.name.endsWith(".md")) files.push(full);
+  }
+  return files;
+}
+
+function inferArtifactType(file) {
+  const normalized = file.replaceAll("\\", "/");
+  if (normalized.includes("/memory/quests/")) return "quest";
+  if (normalized.includes("/memory/handoffs/")) return "handoff";
+  return "document";
+}
+
+function matchingFiles(root, type, query) {
+  const base = type === "quest"
+    ? join(root, "memory", "quests")
+    : type === "handoff"
+      ? join(root, "memory", "handoffs")
+      : join(root, "memory");
+  const needle = query.toLowerCase().replace(/\.md$/, "");
+  return walkMarkdown(base)
+    .filter((file) => basename(file, ".md").toLowerCase().includes(needle))
+    .sort((a, b) => b.localeCompare(a));
+}
+
+export function parseViewRequest(root, rawArgs) {
+  const raw = cleanArgs(rawArgs);
+  if (!raw) return { kind: "choose" };
+
+  const fast = /(?:^|\s)--(?:fast|floor)(?:\s|$)/.test(raw);
+  const compose = /(?:^|\s)--compose(?:\s|$)/.test(raw);
+  const cleaned = raw.replace(/(?:^|\s)--(?:fast|floor|compose)(?=\s|$)/g, " ").trim();
+  const surface = cleaned.toLowerCase();
+  if (["activity", "board", "network"].includes(surface)) {
+    return { kind: "native", type: surface, source: "", fast: true };
+  }
+
+  const explicit = cleaned.match(/^(quest|handoff|document)\s+(.+)$/i);
+  const type = explicit?.[1]?.toLowerCase();
+  const target = (explicit?.[2] || cleaned).replace(/^@/, "").trim();
+  const direct = resolve(root, target);
+  if (existsSync(direct)) {
+    const inferred = type || inferArtifactType(direct);
+    if (inferred === "document" && (!fast || compose)) {
+      return { kind: "model", reason: "document-composition", raw };
+    }
+    return { kind: "native", type: inferred, source: direct, fast };
+  }
+
+  if (type) {
+    const matches = matchingFiles(root, type, target);
+    if (matches.length === 1 && (type !== "document" || fast)) {
+      return { kind: "native", type, source: matches[0], fast };
+    }
+    if (matches.length > 1) return { kind: "choose-file", type, matches, fast };
+  }
+
+  return { kind: "model", reason: "resolve-or-synthesize", raw };
+}
+
+function rendererCommand(root) {
+  const local = join(root, "packages", "egregore-artifacts", "bin", "cli.js");
+  const react = join(root, "packages", "egregore-artifacts", "node_modules", "react");
+  if (existsSync(local) && existsSync(react)) return { command: "node", prefix: [local] };
+  return { command: "npx", prefix: ["-y", "egregore-artifacts@latest"] };
+}
+
+function artifactPath(output) {
+  const clean = String(output || "").replace(ANSI, "");
+  const matches = clean.match(/(?:\/[^\s'\"]+|[A-Za-z]:\\[^\r\n'\"]+)\.html/g);
+  return matches?.at(-1) || "";
+}
+
+export async function renderView(pi, root, request, signal) {
+  const renderer = rendererCommand(root);
+  const args = [...renderer.prefix, request.type];
+  if (request.source) args.push(request.source);
+  const output = await checkedExec(
+    pi,
+    renderer.command,
+    args,
+    { signal, timeout: 120000 },
+    "Artifact render",
+  );
+  const file = artifactPath(output);
+  let text = "✓ Artifact opened in browser";
+  if (file) text += `\n  File: ${file}`;
+
+  if (request.type === "board") {
+    const config = readJson(join(root, "egregore.json"));
+    if (config.slug && config.mode !== "local" && config.api_url) {
+      text += `\n◆ https://egregore.xyz/view/${config.slug}/board   (stable — refresh for latest)`;
+    }
+  }
+  return { text, file, type: request.type };
+}
+
+export async function renderGreeting(pi, root, signal, startScript = "pi-session-start.sh") {
+  const script = join(root, "bin", startScript);
+  if (!existsSync(script)) throw new Error("Egregore startup renderer is missing");
+  return checkedExec(pi, "bash", [script, "--card"], { signal, timeout: 45000 }, "Egregore startup");
+}
+
+// Raw JSON from the most recent activity-data.sh run, so follow-up focus
+// turns can receive the data inline instead of re-running the script inside
+// a harness surface that may cap command time (Prime's kernel kills execs at
+// ~5s, truncating the 10-20s data script to a partial fragment).
+let lastActivityData = "";
+export function lastActivityJson() {
+  return lastActivityData;
+}
+
+// Stable on-disk copy of the same data. Focus turns point the model at this
+// path instead of an inline excerpt: a file read is one fast kernel call,
+// never truncated, and removes any reason to re-run the data script.
+export function activityDataPath(root) {
+  return join(root, ".egregore", "activity-data.json");
+}
+
+function persistActivityData(root, json) {
+  try {
+    mkdirSync(join(root, ".egregore"), { recursive: true });
+    writeFileSync(activityDataPath(root), json);
+  } catch {
+    // Cache only — rendering proceeds from memory when the disk write fails.
+  }
+}
+
+export async function renderActivity(pi, root, signal, options = {}) {
+  if (options.sync !== false) {
+    await checkedExec(
+      pi,
+      "bash",
+      [join(root, "bin", "agent.sh"), "sync"],
+      { signal, timeout: 120000 },
+      "Memory sync",
+    );
+  }
+
+  const state = readJson(join(root, ".egregore-state.json"));
+  let handle = state.github_username || state.name || "";
+  if (!handle) {
+    handle = (await checkedExec(
+      pi,
+      "git",
+      ["-C", root, "config", "user.name"],
+      { signal, timeout: 5000 },
+      "Identity lookup",
+    )).trim();
+  }
+
+  const json = await checkedExec(
+    pi,
+    "bash",
+    [join(root, "bin", "activity-data.sh"), handle],
+    { signal, timeout: 120000 },
+    "Activity refresh",
+  );
+  lastActivityData = String(json || "");
+  persistActivityData(root, lastActivityData);
+  const temp = mkdtempSync(join(tmpdir(), "egregore-pi-activity-"));
+  const input = join(temp, "activity.json");
+  try {
+    writeFileSync(input, json);
+    return await checkedExec(
+      pi,
+      "node",
+      [join(root, "bin", "codex-skill-render.mjs"), "activity-card", input],
+      { signal, timeout: 10000 },
+      "Activity render",
+    );
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function section(title, body) {
+  const value = cleanArgs(body) || "- None recorded.";
+  return `## ${title}\n\n${value}`;
+}
+
+export function buildHandoffDocument(params, author, date = new Date().toISOString().slice(0, 10)) {
+  const topic = cleanArgs(params.topic);
+  const recipient = cleanArgs(params.recipient);
+  const lines = [
+    "---",
+    "capture_schema: egregore-capture/v1",
+    "capture_mode: addressed",
+    "kind: addressed",
+    `from: ${author}`,
+  ];
+  if (recipient) lines.push(`addressed_to: ${recipient}`);
+  lines.push(
+    `date: ${date}`,
+    `topic: ${topic}`,
+    "intent: action",
+    "---",
+    "",
+    `# Handoff: ${topic}`,
+    "",
+    section("Briefing", params.briefing),
+    "",
+    section("Key Decisions", params.key_decisions),
+    "",
+    section("Current State", params.current_state),
+    "",
+    section("Open Threads", params.open_threads),
+    "",
+    section("Next Steps", params.next_steps),
+    "",
+    section("Entry Points", params.entry_points),
+    "",
+  );
+  return lines.join("\n");
+}
+
+export async function createHandoff(pi, root, params, signal) {
+  const state = readJson(join(root, ".egregore-state.json"));
+  const author = state.github_username || state.name || "egregore";
+  const temp = mkdtempSync(join(tmpdir(), "egregore-pi-handoff-"));
+  const body = join(temp, "handoff.md");
+  const recipient = cleanArgs(params.recipient);
+  const runnerArgs = [
+    "--author", author,
+    "--topic", cleanArgs(params.topic),
+    "--content-mode", "supplied",
+  ];
+  if (recipient) runnerArgs.push("--recipient", recipient);
+  writeFileSync(body, buildHandoffDocument(params, author));
+
+  try {
+    const shell = 'tmp="$1"; body="$2"; runner="$3"; shift 3; TMPDIR="$tmp" bash "$runner" --mode addressed "$@" < "$body"';
+    await checkedExec(
+      pi,
+      "bash",
+      ["-c", shell, "egregore-pi-handoff", temp, body, join(root, "bin", "capture-run.sh"), ...runnerArgs],
+      { signal, timeout: 180000 },
+      "Handoff",
+    );
+    const resultFile = join(temp, "handoff-run-result.json");
+    if (!existsSync(resultFile)) throw new Error("Handoff completed without a result receipt");
+    const result = readJson(resultFile);
+    const card = await checkedExec(
+      pi,
+      "node",
+      [join(root, "bin", "codex-skill-render.mjs"), "handoff-card", resultFile],
+      { signal, timeout: 10000 },
+      "Handoff receipt",
+    );
+    return {
+      text: card.trim(),
+      path: result.file ? `memory/${result.file}` : "",
+      url: result.artifactUrl || "",
+    };
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+export async function captureSessionEnd(pi, root, sessionFile, signal, runtime = "pi") {
+  const sessionIdFile = join(root, ".egregore-session-id");
+  if (!existsSync(sessionIdFile)) return false;
+  const sessionId = cleanArgs(readFileSync(sessionIdFile, "utf8"));
+  if (!sessionId) return false;
+
+  const temp = mkdtempSync(join(tmpdir(), "egregore-pi-session-end-"));
+  const input = join(temp, "session-end.json");
+  writeFileSync(input, JSON.stringify({
+    session_id: sessionId,
+    transcript_path: cleanArgs(sessionFile),
+    runtime,
+  }));
+
+  try {
+    const shell = 'bash "$1" < "$2"';
+    await checkedExec(
+      pi,
+      "bash",
+      ["-c", shell, "egregore-pi-session-end", join(root, "bin", "session-log.sh"), input],
+      { signal, timeout: 10000 },
+      "Session capture",
+    );
+    return true;
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+export async function publishScroll(pi, root, params, signal) {
+  const source = resolve(root, String(params.source || "").replace(/^@/, ""));
+  if (!existsSync(source)) throw new Error(`Scroll source not found: ${relative(root, source)}`);
+  const html = readFileSync(source, "utf8");
+  if (/__[A-Z][A-Z0-9_]*__/.test(html)) throw new Error("Scroll still contains unresolved placeholders");
+
+  const config = readJson(join(root, "egregore.json"));
+  let url = "";
+  if (config.mode !== "local" && config.api_url) {
+    const output = await checkedExec(
+      pi,
+      "bash",
+      [
+        join(root, "bin", "publish-artifact.sh"),
+        "document",
+        source,
+        "--raw-html",
+        "--id",
+        cleanArgs(params.slug),
+        "--title",
+        cleanArgs(params.title),
+        "--author",
+        cleanArgs(params.author),
+        "--description",
+        cleanArgs(params.description),
+      ],
+      { signal, timeout: 180000 },
+      "Scroll publish",
+    );
+    url = String(output).match(/https:\/\/[^\s]+/)?.[0] || "";
+    if (!url) throw new Error("Scroll publish did not return a stable URL");
+    const opener = process.platform === "darwin" ? "open" : "xdg-open";
+    await checkedExec(pi, opener, [url], { signal, timeout: 10000 }, "Open scroll");
+  } else {
+    const opener = process.platform === "darwin" ? "open" : "xdg-open";
+    await checkedExec(pi, opener, [source], { signal, timeout: 10000 }, "Open scroll");
+  }
+
+  const version = cleanArgs(params.version) || "v1";
+  const destination = url || source;
+  return {
+    text: `✓ Scroll ${version} opened\n  ${url ? "URL" : "File"}: ${destination}`,
+    path: source,
+    url,
+    version,
+  };
+}
+
+export function workflowPrompt(name, args, extra = "", spec = { runtimeName: "Pi", specPath: ".pi/APPEND_SYSTEM.md" }) {
+  const userArgs = cleanArgs(args);
+  return [
+    `Run the Egregore /${name} workflow now.`,
+    `Read .codex/skills/${name}/SKILL.md completely and adapt Codex-specific wording to ${spec.runtimeName} using ${spec.specPath}.`,
+    "Work quietly: do not narrate progress, expose raw command output, or repeat tool results.",
+    "Use the fewest targeted reads and commands that preserve the workflow contract.",
+    userArgs ? `User arguments: ${userArgs}` : "",
+    extra,
+  ].filter(Boolean).join("\n");
+}

package/runtime/prime/bin/prime-render-spec.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Derive Prime Agent's project-local system appendix from the generated Codex
+// protocol. CLAUDE.md remains canonical:
+// CLAUDE.md -> AGENTS.md -> .prime/agent/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Prime.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = path.join(ROOT, "AGENTS.md");
+const OUTPUT = path.join(ROOT, ".prime", "agent", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".prime", "agent", "spec-manifest.json");
+const CODEX_BEGIN = "<!-- BEGIN GENERATED EGREGORE CODEX SPEC";
+const CODEX_END = "<!-- END GENERATED EGREGORE CODEX SPEC -->";
+
+function hash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function extractSpec(source) {
+  const begin = source.indexOf(CODEX_BEGIN);
+  const contentStart = source.indexOf("\n", begin);
+  const end = source.indexOf(CODEX_END, contentStart);
+  if (begin < 0 || contentStart < 0 || end < 0) {
+    throw new Error("AGENTS.md does not contain the generated Codex spec");
+  }
+  return source.slice(contentStart + 1, end).trim();
+}
+
+function replaceSection(markdown, heading, body) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
+}
+
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
+function adapt(sourceSpec) {
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec — a missing anchor no-ops silently and drops Prime-specific
+  // wording (see the tool_call gate incident). Fail the render loudly instead.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Prime Agent"],
+    ["Codex-native", "Prime-native"],
+    ["Codex sessions", "Prime Agent sessions"],
+    ["On Codex", "On Prime Agent"],
+    ["Codex has no", "Prime Agent has no built-in"],
+    ["bin/codex-session-start.sh", "bin/prime-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".prime/agent/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded from the project-local extension)"],
+    ["If this Codex build does not support hooks", "If Prime Agent project extensions are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.prime/agent/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`prime-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
+    .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
+    .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
+
+  text = replaceSection(text, "Egregore on Prime Agent", `You are Prime Agent running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Prime Agent resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of \`CLAUDE.md\`, the behavioral source of truth. Prime Agent loads it through \`.prime/agent/APPEND_SYSTEM.md\`. Egregore workflows are shared from \`.codex/skills/\` through the Agent Skills standard (via \`.agents/skills\` and project settings) and exposed as familiar slash commands by \`.prime/agent/extensions/egregore.ts\`.
+
+Your subagent mechanism (\`rlm(...)\`) spawns Prime Agent child sessions, not Egregore Loom lanes. Ignore Loom routing preambles inside shared skills: run those workflows inline.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Prime Agent extension renders the Egregore startup card (identity, handoffs, team activity) inside the session via \`bin/prime-session-start.sh\`. This works for direct \`prime-agent\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Prime Agent, run \`bash bin/prime-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Prime Agent slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.prime/agent/extensions/egregore.ts\`; the duplicate \`/skill:name\` listings are disabled so each workflow appears once. Natural-language requests work normally — and are the route for any workflow whose name collides with a Prime Agent built-in: **say "update egregore" rather than typing \`/update\`**, which is Prime Agent's own self-updater. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Prime Agent, run referenced \`bin/\` scripts through the IPython kernel (or the bash tool when active), use ordinary shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no UI question surface is available.
+
+The \`egregore\` Python-backed skill exposes the mechanics as kernel functions — \`import egregore\`, then \`egregore.search(query)\`, \`egregore.activity()\`, \`egregore.handoff(to, topic, body)\`, \`egregore.save(message, topic)\`, \`egregore.branch(topic)\`, \`egregore.notify_plan(recipient, message)\`. Prefer these over re-deriving \`bin/\` CLI usage by reading scripts. \`notify_plan\` is proposal-only: approval and dispatch always pass through the explicit human Send / Edit / Cancel checkpoint.
+
+"Get the latest changes" inside a session means \`/reload\` — it re-reads instructions, context files, skills, and extensions from disk. Never \`git pull\`, \`git reset\`, or \`git checkout\` the working branch to pick up updates. When pivoting topics inside a worktree that carries unmerged branch work, create the new branch from the current HEAD, not \`origin/develop\` — branching from origin/develop in such a worktree removes the unmerged files from disk.
+
+Kernel shell escapes can be time-capped by the harness. Egregore \`bin/\` scripts that sync git state or query the connected graph legitimately run 10–120 seconds: run them with a generous timeout (a \`%%bash\` cell, or the longest limit the harness exposes). If a command dies suspiciously fast (~5s) with partial output, treat it as a timeout — rerun once with a longer limit or render the workflow's designed one-line fallback. Never debug data plumbing inside a product workflow. Connected mode works normally here: graph reads and \`bin/search.sh\` enrichment use the instance's configured credentials, and when graph data is degraded say so in one plain line rather than narrating connectivity theories.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Prime Agent\n\nThis file is generated by \`bin/prime-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
+}
+
+const check = process.argv.includes("--check");
+const source = fs.readFileSync(SOURCE, "utf8");
+const sourceSpec = extractSpec(source);
+const rendered = adapt(sourceSpec);
+const manifest = `${JSON.stringify({
+  generatedBy: "bin/prime-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Prime Agent APPEND_SYSTEM delivery from .prime/agent/",
+    "Prime Agent tool_call branch gate incl. ipython classification",
+    "Prime Agent slash-command extension over shared portable skills",
+    "rlm() subagents are not Loom lanes; Loom preambles run inline",
+  ],
+}, null, 2)}\n`;
+
+if (check) {
+  const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
+  if (currentOutput !== rendered || currentManifest !== manifest) {
+    console.error("prime spec out of date — run: node bin/prime-render-spec.mjs");
+    process.exit(1);
+  }
+  console.log("prime spec up to date");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`prime spec rendered: .prime/agent/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

package/runtime/prime/bin/prime-session-start.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -o pipefail
+
+# Prime Agent's project extension invokes this during session_start so direct
+# `prime-agent` launches and launcher-managed sessions share the same greeting.
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "${1:---card}" in
+  --card|card)
+    exec bash "$SCRIPT_DIR/bin/codex-session-start.sh" --card
+    ;;
+  --prompt|prompt)
+    cat <<'EOF'
+You are Prime Agent running inside Egregore. The project extension renders the
+startup card during session_start. Project instructions are in
+.prime/agent/APPEND_SYSTEM.md, Egregore workflows are registered as slash
+commands, and portable skill bodies live in .codex/skills.
+EOF
+    ;;
+  *)
+    echo "usage: bin/prime-session-start.sh [--card|--prompt]" >&2
+    exit 2
+    ;;
+esac