roger-roger 0.1.2 → 0.1.4

package/README.md

@@ -57,6 +57,7 @@ A missing key is not fatal. Speech falls back to the computer's built-in voice (
 `roger-roger install` asks, in the terminal:
 
 - which agents should have the skill (every one it finds is ticked)
+- whether to tell your agents to always use it: a marked block in each agent's global instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`, `~/.gemini/GEMINI.md`), which uninstall takes out again
 - whether to register with Herdr, if it's installed
 - how to reach you: Slack, sound, speech, in any combination
 - Slack: it connects it for you (see above), and where messages go (your DMs, or a channel)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roger-roger",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Bring yourself back to the conversation: your coding agents reach you by Slack, a sound or a spoken line when they finish, get stuck, or need a decision, and you answer from your phone.",
   "type": "module",
   "bin": {

package/skills/roger-roger/SKILL.md

@@ -261,7 +261,7 @@ Judge it by what happens if you are wrong, not by whether it feels routine. A fo
 ## Other commands
 
 - `install`: the interactive setup, for the user to run in a terminal (section 1). `install --yes` asks nothing: it links the skill for every agent on the machine and registers with Herdr, and prints what it did.
-- `uninstall`: takes it out again, for the user to run in a terminal (`npx roger-roger@latest uninstall`): hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the global command. `--yes` removes all of that without asking (`--slack-cli` adds the Slack CLI). Never run it for the user unasked.
+- `uninstall`: takes it out again, for the user to run in a terminal (`npx roger-roger@latest uninstall`): the standing instruction `install` put in the agents' global files (a marked block in `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`), hooks, skill links, the Herdr plugin, the daemon and the tray, settings and tokens, the global command. `--yes` removes all of that without asking (`--slack-cli` adds the Slack CLI). Never run it for the user unasked.
 - `help [command]`: the commands, and one command's flags.
 - `status`: current config, whether the tokens are present, the daemon, running sessions, and every valid option value.
 - `slack-setup [status|install-cli|login|create]`: the Slack steps `install` runs, one at a time, for repairing a connection by hand. `create` again is safe: it updates the same app, which is what to do after the manifest changed or when a scope is missing.

package/skills/roger-roger/herdr-plugin.toml

@@ -6,7 +6,7 @@
 
 id = "roger-roger"
 name = "roger-roger"
-version = "0.1.2"
+version = "0.1.4"
 min_herdr_version = "0.9.0"
 description = "Slack, a sound or a spoken line from the agents in your panes, and questions you answer from your phone"
 platforms = ["linux", "macos", "windows"]

package/skills/roger-roger/scripts/help.mjs

@@ -10,8 +10,8 @@ export const TAGLINE = "Bring yourself back to the conversation: your agents rea
 /** Every command: where it belongs, how it is called, what it does, and (for the busy ones) its flags. */
 export const COMMANDS = [
   // ---- setting up
-  { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done"]] },
-  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"]] },
+  { section: "Setting up", name: "install", usage: "[--yes]", summary: "Set everything up in the terminal: the command on your PATH, the skill for every agent and a standing instruction to use it, Herdr, Slack, the sound and the voice, hooks, tray. Run it again to change anything. --yes asks nothing and only links the skill.", flags: [["--yes", "no questions: link the skill for every agent on the machine and register with Herdr, then print what was done. Nothing is written to CLAUDE.md or AGENTS.md"]] },
+  { section: "Setting up", name: "uninstall", usage: "[--yes]", summary: "Take it out again: the standing instruction, hooks, links, Herdr, the daemon and the tray, settings and tokens, the global command.", flags: [["--yes", "no questions: remove everything except the Slack CLI, then print what was done"], ["--slack-cli", "with --yes, remove the Slack CLI and its login as well"]] },
   { section: "Setting up", name: "status", usage: "", summary: "Settings, whether the tokens are there, the daemon, who is running, and every valid option value." },
   {
     section: "Setting up", name: "setup", usage: "[flags]", summary: "Change any setting; the rest are kept.",
@@ -180,7 +180,7 @@ export function helpText(command = "", { columns = process.stdout.columns || 100
   for (const line of wrap(TAGLINE, cols - 2)) out.push(`  ${c.dim(line)}`);
   out.push("");
   out.push(`  ${c.bold("Usage")}`);
-  out.push(...table([["roger-roger <command> [flags]", "every command prints one JSON object"], ["roger-roger help <command>", "that command's flags"]], {
+  out.push(...table([["roger-roger <command> [flags]", "every command prints one JSON object"], ["roger-roger help <command>", "that command's flags"], ["roger-roger --version", "which copy this is"]], {
     indent: 4, columns: cols, c, maxLeft: 30, left: (l) => c.cyan("roger-roger") + " " + c.dim(l.slice("roger-roger ".length)),
   }));
   const sections = [...new Set(COMMANDS.map((x) => x.section))];

package/skills/roger-roger/scripts/install.mjs

@@ -95,6 +95,81 @@ export function applyLink(link, target, plan, fsx = fs, now = new Date()) {
   return { ...plan, done: true };
 }
 
+// ---------------------------------------------------------------- the agents' standing instructions
+
+/** Each agent's global instructions file: what it reads at the start of every session, everywhere. */
+export const INSTRUCTION_FILES = [
+  { id: "claude", label: "Claude Code", dir: [".claude"], file: "CLAUDE.md" },
+  { id: "codex", label: "Codex", dir: [".codex"], file: "AGENTS.md" },
+  { id: "opencode", label: "OpenCode", dir: [".config", "opencode"], file: "AGENTS.md" },
+  { id: "gemini", label: "Gemini CLI", dir: [".gemini"], file: "GEMINI.md" },
+];
+
+const MARK_START = "<!-- roger-roger:start -->";
+const MARK_END = "<!-- roger-roger:end -->";
+
+/** The standing instruction, between marks so it can be replaced or removed without touching anything else. */
+export const INSTRUCTIONS = [
+  MARK_START,
+  "- Always use the `roger-roger` skill (the `roger-roger` command, or `node <skill-dir>/scripts/roger-roger.mjs`): at the end of every turn, whatever its size, send a notification as the last action before the final reply, and use `ask` when blocked on a decision. Don't skip it because the task seemed quick or the user seems to be at the keyboard. Pass `--session` (three to six words about the work) and `--agent-model` on every call. If the skill isn't available, say so once.",
+  MARK_END,
+].join("\n");
+
+/** Where each agent's file is, whether that agent is here, and whether the block is already in it. */
+export function instructionFiles(home = os.homedir(), fsx = fs) {
+  return INSTRUCTION_FILES.map((a) => {
+    const root = path.join(home, ...a.dir);
+    const file = path.join(root, a.file);
+    let text = "";
+    try {
+      text = fsx.readFileSync(file, "utf8");
+    } catch {}
+    return { ...a, root, path: file, present: fsx.existsSync(root), has: text.includes(MARK_START) };
+  });
+}
+
+const BLOCK = new RegExp(`\\n?${MARK_START}[\\s\\S]*?${MARK_END}\\n?`);
+
+/** The text with the block in it, replacing an older one or added at the end. */
+export function withInstructions(text) {
+  const body = String(text ?? "");
+  if (body.includes(MARK_START) && body.includes(MARK_END)) return body.replace(BLOCK, `\n${INSTRUCTIONS}\n`).replace(/^\n/, "");
+  if (!body.trim()) return `${INSTRUCTIONS}\n`;
+  return `${body.replace(/\s*$/, "")}\n\n${INSTRUCTIONS}\n`;
+}
+
+/** The text without the block; anything else in it is left exactly as it was. */
+export function withoutInstructions(text) {
+  const body = String(text ?? "");
+  if (!body.includes(MARK_START)) return body;
+  return body.replace(BLOCK, "\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "").replace(/\n+$/, "\n");
+}
+
+export function addInstructions(file, fsx = fs) {
+  let text = "";
+  try {
+    text = fsx.readFileSync(file, "utf8");
+  } catch {}
+  const had = text.includes(MARK_START);
+  fsx.mkdirSync(path.dirname(file), { recursive: true });
+  fsx.writeFileSync(file, withInstructions(text), "utf8");
+  return { file, updated: had, added: !had };
+}
+
+export function removeInstructions(file, fsx = fs) {
+  let text;
+  try {
+    text = fsx.readFileSync(file, "utf8");
+  } catch {
+    return { file, removed: false };
+  }
+  if (!text.includes(MARK_START)) return { file, removed: false };
+  const rest = withoutInstructions(text);
+  if (rest.trim()) fsx.writeFileSync(file, rest, "utf8");
+  else fsx.rmSync(file, { force: true }); // ours was all there was
+  return { file, removed: true };
+}
+
 // ---------------------------------------------------------------- the global copy
 
 /**
@@ -115,23 +190,37 @@ export function globalCopy(env = process.env) {
     const root = (r.stdout ?? "").trim();
     if (r.status !== 0 || !root) return null;
     const pkg = path.join(root, "roger-roger");
-    return { root, dir: path.join(pkg, "skills", "roger-roger"), present: fs.existsSync(path.join(pkg, "package.json")) };
+    let version = "";
+    try {
+      version = JSON.parse(fs.readFileSync(path.join(pkg, "package.json"), "utf8")).version ?? "";
+    } catch {}
+    return { root, dir: path.join(pkg, "skills", "roger-roger"), present: Boolean(version), version };
   } catch {
     return null;
   }
 }
 
+/** a < b for dotted versions; anything unparseable counts as older. */
+export function olderThan(a, b) {
+  const parse = (v) => String(v ?? "").split(".").map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
+  return false;
+}
+
 /**
  * Which copy of the skill everything should point at, and whether to offer a global install:
  * the copy this runs from, unless that is a passing one (npx's cache, say) and there is no global
- * copy yet. A global copy that exists beside a checkout or a skills.sh copy is left alone: whoever
+ * copy yet, or the global copy is older than this one (`npx roger-roger@latest install` after an
+ * update). A global copy that is as new as a checkout or a skills.sh copy is left alone: whoever
  * runs this copy meant this copy.
  */
-export function pickTarget(running, global) {
+export function pickTarget(running, global, runningVersion = VERSION) {
   if (!global) return { target: running, offer: false, reason: "npm was not found" };
   if (norm(running) === norm(global.dir)) return { target: running, offer: false, reason: "global" };
-  if (global.present) return { target: running, offer: false, reason: "a global copy exists, but this one was run" };
-  return { target: running, offer: true, reason: "no global copy yet" };
+  if (!global.present) return { target: running, offer: true, reason: "no global copy yet" };
+  if (runningVersion && olderThan(global.version, runningVersion)) return { target: running, offer: true, reason: "update", from: global.version, to: runningVersion };
+  return { target: running, offer: false, reason: "a global copy exists, but this one was run" };
 }
 
 /** `npm install -g roger-roger@latest`. Throws with npm's last words when it fails. */
@@ -422,9 +511,11 @@ export async function runInstall(args, { script, hooks, input = process.stdin, o
     if (pick.reason === "global") {
       ui.done("The roger-roger command is on your PATH", global.dir);
     } else if (pick.offer) {
-      const yes = await ui.confirm({ message: "Put the roger-roger command on your PATH?", hint: "npm install -g roger-roger, so you and your agents can run it from anywhere" });
+      const yes = await ui.confirm(pick.reason === "update"
+        ? { message: `Update the roger-roger command from ${pick.from} to ${pick.to}?`, hint: "npm install -g roger-roger@latest; the old one would keep answering" }
+        : { message: "Put the roger-roger command on your PATH?", hint: "npm install -g roger-roger, so you and your agents can run it from anywhere" });
       if (yes) {
-        const done = await attempt(ui, "Installing globally", () => ui.run("Installing roger-roger with npm", () => installGlobally(env), { done: () => ({ text: "The roger-roger command is on your PATH", detail: global.dir }) }), { skipLabel: "Carry on with this copy" });
+        const done = await attempt(ui, pick.reason === "update" ? "Updating" : "Installing globally", () => ui.run(`${pick.reason === "update" ? "Updating" : "Installing"} roger-roger with npm`, () => installGlobally(env), { done: () => ({ text: `The roger-roger command is on your PATH${pick.to ? `, at ${pick.to}` : ""}`, detail: global.dir }) }), { skipLabel: "Carry on with this copy" });
         if (done !== null && fs.existsSync(path.join(global.dir, "scripts", "roger-roger.mjs"))) {
           target = global.dir;
           hookScript = path.join(global.dir, "scripts", "roger-roger.mjs");
@@ -462,6 +553,38 @@ export async function runInstall(args, { script, hooks, input = process.stdin, o
       }
     }
 
+    // ---- the standing instruction, so agents use it without being told each time
+    const instructionTargets = instructionFiles(home).filter((f) => f.present);
+    if (instructionTargets.length) {
+      const already = instructionTargets.filter((f) => f.has);
+      const yes = await ui.confirm({
+        message: already.length === instructionTargets.length ? "Keep telling your agents to always use roger-roger?" : "Tell your agents to always use roger-roger?",
+        yes: "Yes (recommended)",
+        hint: `a marked block in ${instructionTargets.map((f) => `~/${[...f.dir, f.file].join("/")}`).join(", ")}`,
+        initial: true,
+      });
+      if (yes) {
+        for (const f of instructionTargets) {
+          try {
+            const r = addInstructions(f.path);
+            ui.done(`${f.label}: ${r.added ? "instructions added" : "instructions refreshed"}`, f.path);
+            summary.push(`instructions: ${f.label}`);
+          } catch (e) {
+            ui.failed(`${f.label}: could not write ${f.path}`, e.message);
+          }
+        }
+      } else if (already.length) {
+        for (const f of already) {
+          try {
+            removeInstructions(f.path);
+            ui.done(`${f.label}: instructions removed`, f.path);
+          } catch (e) {
+            ui.failed(`${f.label}: could not change ${f.path}`, e.message);
+          }
+        }
+      }
+    }
+
     // ---- herdr
     let herdrDone = false;
     if (herdr) {
@@ -732,6 +855,7 @@ export async function uninstallFindings({ home = os.homedir(), env = process.env
   const global = globalCopy(env);
   return {
     links: skillFootprint(home),
+    instructions: instructionFiles(home).filter((f) => f.has),
     herdr: herdr && herdrHasPlugin(herdr) ? herdr : null,
     hookAgents,
     home: [rogerRogerHome(env), path.join(home, ".attention")].filter((d) => fs.existsSync(d)),
@@ -743,7 +867,15 @@ export async function uninstallFindings({ home = os.homedir(), env = process.env
 /** Everything but the Slack CLI, with no questions. Returns what was done. */
 export async function quietUninstall({ home = os.homedir(), env = process.env, hooks = null, script = "", slackCli = false } = {}) {
   const found = await uninstallFindings({ home, env, hooks, script });
-  const done = { daemonStopped: await stopDaemon(env), hooks: [], links: [], herdr: null, home: [], slackCli: false, global: null };
+  const done = { daemonStopped: await stopDaemon(env), hooks: [], links: [], instructions: [], herdr: null, home: [], slackCli: false, global: null };
+  for (const f of found.instructions) {
+    try {
+      removeInstructions(f.path);
+      done.instructions.push(f.path);
+    } catch (e) {
+      done.instructions.push({ file: f.path, error: e.message });
+    }
+  }
   for (const name of found.hookAgents) {
     try {
       hooks.agents[name].uninstall();
@@ -797,6 +929,7 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
     const labels = { claude: "Claude Code", opencode: "OpenCode", codex: "Codex" };
     const choices = [];
     if (found.links.length) choices.push({ value: "links", label: "The skill, for agents", hint: found.links.map((a) => a.label).join(", "), checked: true });
+    if (found.instructions.length) choices.push({ value: "instructions", label: "The standing instruction", hint: found.instructions.map((f) => `~/${[...f.dir, f.file].join("/")}`).join(", "), checked: true });
     if (found.hookAgents.length) choices.push({ value: "hooks", label: "Terminal-question hooks", hint: found.hookAgents.map((n) => labels[n] ?? n).join(", "), checked: true });
     if (found.herdr) choices.push({ value: "herdr", label: "The Herdr plugin", hint: "herdr plugin unlink", checked: true });
     if (found.home.length) choices.push({ value: "home", label: "Settings, Slack tokens, state", hint: found.home.join(", "), checked: true });
@@ -830,6 +963,17 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
         }
       }
     }
+    if (what.includes("instructions")) {
+      for (const f of found.instructions) {
+        try {
+          removeInstructions(f.path);
+          ui.done(`${f.label}: instruction removed`, f.path);
+          removed.push(`instructions: ${f.label}`);
+        } catch (e) {
+          ui.failed(`${f.label}: could not change ${f.path}`, e.message);
+        }
+      }
+    }
     if (what.includes("herdr")) {
       const r = herdrUnlink(found.herdr);
       if (r.ok) {
@@ -873,7 +1017,7 @@ export async function runUninstall(args, { script, hooks, input = process.stdin,
       "",
       ...removed.map((s) => `${c.green("•")} ${s}`),
       "",
-      c.dim("Lines about roger-roger in your own CLAUDE.md or AGENTS.md are yours, so they were left alone."),
+      c.dim("Only the marked roger-roger block was taken out of your CLAUDE.md or AGENTS.md; anything you wrote yourself is still there."),
       `Back any time: ${c.cyan("npx roger-roger@latest install")}`,
     ]);
     return 0;

package/skills/roger-roger/scripts/roger-roger.mjs

@@ -10,7 +10,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import {
-  DEFAULTS, DUCK_MODES, KINDS, METHODS, ON_EXPIRE, SPEECH_MODES, WHEN_MODES,
+  DEFAULTS, DUCK_MODES, KINDS, METHODS, ON_EXPIRE, SPEECH_MODES, VERSION, WHEN_MODES,
   applySetup, rogerRogerHome, configPath, listArg, listSounds, loadConfig, migrateLegacyHome, parseArgs,
   readSlackCredentials, saveConfig, slackAppToken, slackToken,
 } from "./lib.mjs";
@@ -324,6 +324,10 @@ const AGENTS = {
 
 /** `help`, `help <command>`, `--help`, or a command that doesn't exist: the overview, or one command's page. */
 function help(command, args) {
+  if (["--version", "-v", "-V", "version"].includes(command)) {
+    process.stdout.write(`${VERSION || "unversioned copy"}\n`);
+    return;
+  }
   const wanted = command === "help" ? args._[0] : "";
   const unknown = command && !["help", "--help", "-h", undefined].includes(command);
   if (unknown) process.stderr.write(`roger-roger: unknown command "${command}"\n`);