reviewer-harness 1.1.0 → 1.2.0

package/README.md

@@ -176,7 +176,9 @@ Reusable playbooks, enabled per project:
 - `skills add <name>` — install into the project and enable it in the config
 - `skills remove <name>` — disable it
 
-Bundled: `safe-editing`, `no-hallucination`, `debug-first`, `explain-bisaya`. Enabled skills render below the rules in every instruction file.
+Bundled: `safe-editing`, `no-hallucination`, `debug-first`, `explain-bisaya`. Enabled skills render below the rules in every instruction file — and sync also generates a **slash command** for each one (`.opencode/commands/<name>.md` and `.claude/commands/<name>.md`), so every enabled skill appears in the `/` menu of OpenCode and Claude, ready to invoke on a specific task: `/safe-editing`, `/no-hallucination`, and so on.
+
+**Every project, instantly:** want the skills in the `/` menu of *every* project, with no per-project setup? Run `reviewer-harness global` once — it installs all bundled skills as slash commands into the global OpenCode (`~/.config/opencode/commands`) and Claude (`~/.claude/commands`) folders. From then on, they are in the `/` menu of any project you open. (Project rules still come from `sync` inside a project.)
 
 ## Sub-agents and Slash Commands
 
@@ -190,20 +192,37 @@ One master definition in the harness, generated into each runtime's format:
 
 ## Command reference
 
-Requires Node.js 18+ (no dependencies). Every command accepts `--target <dir>` (default: the current directory).
+Requires Node.js 18+ (no dependencies). Run these inside your project — every command works on the current directory unless you add `--target <dir>`.
+
+**Start & everyday**
+
+```bash
+reviewer-harness init            # one-time: create the master config
+reviewer-harness validate        # check the config (quality + secret scan)
+reviewer-harness sync --dry-run  # preview the changes, writes nothing
+reviewer-harness sync            # apply the rules to every runtime
+reviewer-harness status          # show the config + target files
+```
+
+**Skills, agents, commands**
+
+```bash
+reviewer-harness skills list
+reviewer-harness skills add safe-editing
+reviewer-harness skills remove safe-editing
+reviewer-harness agents add reviewer
+reviewer-harness commands add review
+```
+
+**Local memory**
 
 ```bash
-node bin/cli.js init --target ./my-project
-node bin/cli.js validate --target ./my-project
-node bin/cli.js sync --dry-run --target ./my-project
-node bin/cli.js sync --target ./my-project
-node bin/cli.js memory init --target ./my-project
-node bin/cli.js skills add safe-editing --target ./my-project
-node bin/cli.js agents add reviewer --target ./my-project
-node bin/cli.js commands add review --target ./my-project
+reviewer-harness memory init     # start the memory/ vault
+reviewer-harness memory list     # list notes + their links
+reviewer-harness memory index    # rebuild INDEX.md + graph.json
 ```
 
-Installed globally or via npx (see Quickstart), the same commands run as `reviewer-harness <command>`.
+Running from a source checkout instead? The same commands work as `node bin/cli.js <command>`.
 
 ## File map
 

package/bin/cli.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 // reviewer-harness — CLI: sync engine, guardrail validation, local memory,
 // skills, sub-agents, and slash commands.
-// Commands: status | sync | init | validate | memory | skills | agents | commands
+// Commands: status | sync | init | validate | memory | skills | agents | commands | global
 
 import { parseArgs } from "node:util";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { loadConfig } from "../lib/config.js";
 import { adapters, supportedRuntimes } from "../lib/adapters/index.js";
-import { sync } from "../lib/sync.js";
+import { sync, writeSafe } from "../lib/sync.js";
 import { initProject } from "../lib/init.js";
 import { initMemory, buildIndex, readNotes, memoryDir } from "../lib/memory.js";
 import { validateConfig } from "../lib/validate.js";
-import { listBundledSkills, addSkill, removeSkill } from "../lib/skills.js";
+import { listBundledSkills, addSkill, removeSkill, loadBundledSkills, skillCommandContent } from "../lib/skills.js";
 import { listBundledAgents, addAgent } from "../lib/agents.js";
 import { listBundledCommands, addCommand } from "../lib/commands.js";
 
@@ -30,21 +31,27 @@ const dryRun = values["dry-run"];
 function help() {
   console.log(`reviewer-harness — your own AI harness
 
-Usage:
-  node bin/cli.js status [--target <dir>]              Show the config + target files
-  node bin/cli.js sync [--dry-run] [--target <dir>]    Sync the rules to every runtime
-  node bin/cli.js init [--target <dir>]                Create harness.config.json in a project
-  node bin/cli.js validate [--target <dir>]            Check the config: quality + secret scanning
-  node bin/cli.js memory init [--target <dir>]         Start the local memory (memory/ folder)
-  node bin/cli.js memory index [--target <dir>]        Rebuild the memory INDEX.md + graph.json
-  node bin/cli.js memory list [--target <dir>]         List memory notes + their links
-  node bin/cli.js skills list [--target <dir>]         List bundled skills (+ which are enabled)
-  node bin/cli.js skills add <name> [--target <dir>]   Install + enable a skill in the project
-  node bin/cli.js skills remove <name> [--target <dir>] Disable + remove a skill
-  node bin/cli.js agents list                          List bundled sub-agents
-  node bin/cli.js agents add <name> [--target <dir>]   Install a sub-agent (OpenCode + Claude)
-  node bin/cli.js commands list                        List bundled slash commands
-  node bin/cli.js commands add <name> [--target <dir>] Install a slash command (OpenCode + Claude)
+Usage (run inside your project):
+  reviewer-harness init                     Create harness.config.json (one-time setup)
+  reviewer-harness validate                 Check the config: quality + secret scanning
+  reviewer-harness sync [--dry-run]         Sync the rules to every runtime (--dry-run = preview only)
+  reviewer-harness status                   Show the config + target files
+
+  reviewer-harness skills list              List bundled skills (+ which are enabled)
+  reviewer-harness skills add <name>        Install + enable a skill in the project
+  reviewer-harness skills remove <name>     Disable + remove a skill
+  reviewer-harness agents list              List bundled sub-agents
+  reviewer-harness agents add <name>        Install a sub-agent (OpenCode + Claude)
+  reviewer-harness commands list            List bundled slash commands
+  reviewer-harness commands add <name>      Install a slash command (OpenCode + Claude)
+
+  reviewer-harness global [--dry-run]       Install EVERY bundled skill as a slash command for ALL projects (global OpenCode + Claude "/" menus)
+
+  reviewer-harness memory init              Start the local memory (memory/ folder)
+  reviewer-harness memory index             Rebuild the memory INDEX.md + graph.json
+  reviewer-harness memory list              List memory notes + their links
+
+Every command accepts --target <dir> (default: the current directory).
 `);
 }
 
@@ -64,7 +71,16 @@ function cmdSync() {
   const results = sync({ targetDir, dryRun });
   if (dryRun) console.log("(dry-run: nothing was written)\n");
   for (const r of results) {
-    if (r.skipped) {
+    if (r.skillCommands) {
+      const written = r.skillCommands.filter((f) => f.written).length;
+      const pending = r.skillCommands.filter((f) => f.dryRun && f.changed).length;
+      const unchanged = r.skillCommands.filter((f) => f.unchanged || (f.dryRun && !f.changed)).length;
+      if (dryRun) {
+        console.log(`- skill commands: ${pending} would be written/updated, ${unchanged} unchanged (they appear in the "/" menu of OpenCode and Claude)`);
+      } else {
+        console.log(`- skill commands: ${written} written ✓, ${unchanged} unchanged (one per skill, in the "/" menu of OpenCode and Claude)`);
+      }
+    } else if (r.skipped) {
       console.log(`- ${r.runtime}: SKIP — ${r.skipped}`);
     } else if (r.dryRun) {
       console.log(`- ${r.runtime} → ${r.file}: ${r.changed ? "WOULD WRITE (changes pending)" : "no changes"}`);
@@ -192,6 +208,30 @@ function cmdCommands() {
   }
 }
 
+function cmdGlobal() {
+  const skills = loadBundledSkills();
+  const targets = [
+    { runtime: "OpenCode", dir: join(homedir(), ".config", "opencode", "commands") },
+    { runtime: "Claude", dir: join(homedir(), ".claude", "commands") },
+  ];
+  if (dryRun) console.log("(dry-run: nothing was written)\n");
+  for (const { runtime, dir } of targets) {
+    let written = 0, unchanged = 0, pending = 0;
+    for (const skill of skills) {
+      const outcome = writeSafe(join(dir, `${skill.name}.md`), skillCommandContent(skill), dryRun);
+      if (outcome.written) written++;
+      else if (outcome.dryRun && outcome.changed) pending++;
+      else unchanged++;
+    }
+    if (dryRun) console.log(`- ${runtime} (global): ${pending} would be written/updated, ${unchanged} unchanged → ${dir}`);
+    else console.log(`- ${runtime} (global): ${written} written ✓, ${unchanged} unchanged → ${dir}`);
+  }
+  console.log(
+    `\nDone: ${skills.map((s) => "/" + s.name).join(", ")} are now in the "/" menu of EVERY project.` +
+      `\n(Per-project rules still come from "sync" inside a project.)`
+  );
+}
+
 async function main() {
   if (!command || command === "status") cmdStatus();
   else if (command === "sync") cmdSync();
@@ -201,6 +241,7 @@ async function main() {
   else if (command === "skills") cmdSkills();
   else if (command === "agents") cmdAgents();
   else if (command === "commands") cmdCommands();
+  else if (command === "global") cmdGlobal();
   else help();
 }
 

package/lib/skills.js

@@ -1,8 +1,7 @@
 // lib/skills.js — LESSON 4: SKILLS SYSTEM.
 //
-// Rules are short laws. SKILLS are deeper playbooks for specific work
-// (like sauron's `add`): reusable instruction bundles you enable
-// per project.
+// Rules are short laws. SKILLS are deeper playbooks for specific work:
+// reusable instruction bundles you enable per project.
 //
 //   skills/<name>.md   — bundled in the harness (the "store")
 //   <project>/skills/  — the installed copy in your project
@@ -27,6 +26,26 @@ import { parseFrontmatter } from "./frontmatter.js";
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const BUNDLED_DIR = join(ROOT, "skills");
 
+// The bundled skills in full (name + description + body) — used by
+// the "global" command, which installs them as slash commands for
+// every project on the machine.
+export function loadBundledSkills() {
+  if (!existsSync(BUNDLED_DIR)) return [];
+  return readdirSync(BUNDLED_DIR)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .map((file) => {
+      const { data, body } = parseFrontmatter(
+        readFileSync(join(BUNDLED_DIR, file), "utf8")
+      );
+      return {
+        name: file.replace(/\.md$/, ""),
+        description: data.description ?? "",
+        body: body.trim(),
+      };
+    });
+}
+
 export function listBundledSkills() {
   if (!existsSync(BUNDLED_DIR)) return [];
   return readdirSync(BUNDLED_DIR)
@@ -101,19 +120,36 @@ export function removeSkill(name, targetDir) {
   return { wasEnabled, removedFile };
 }
 
-// Read the enabled skills' contents so sync can render them.
-// Enabled but no file? That's a clear error, not a silent skip:
-// a strict harness never guesses.
-export function loadSkillSections(targetDir, config) {
-  const sections = [];
+// Read the enabled skills in full (name + description + body) so sync
+// can render them into the instruction files AND generate a slash
+// command for each one.
+export function loadSkills(targetDir, config) {
+  const skills = [];
   for (const name of config.skills ?? []) {
     const file = join(targetDir, "skills", `${name}.md`);
     if (!existsSync(file))
       throw new Error(
         `Skill "${name}" is enabled in the config but has no file in skills/ — run "skills add ${name}".`
       );
-    const { body } = parseFrontmatter(readFileSync(file, "utf8"));
-    sections.push(body.trim());
+    const { data, body } = parseFrontmatter(readFileSync(file, "utf8"));
+    skills.push({ name, description: data.description ?? "", body: body.trim() });
   }
-  return sections;
+  return skills;
+}
+
+// Enabled but no file? loadSkills throws a clear error, never a
+// silent skip: a strict harness never guesses.
+export function loadSkillSections(targetDir, config) {
+  return loadSkills(targetDir, config).map((s) => s.body);
+}
+
+// The slash-command file generated for a skill, so the skill shows up
+// in the runtime's "/" menu (OpenCode and Claude list the files in
+// their commands folders). Invoking /<skill> hands the playbook to
+// the AI together with whatever the user types after it.
+export function skillCommandContent(skill) {
+  return (
+    `---\ndescription: ${skill.description}\n---\n\n` +
+    `${skill.body}\n\nApply this playbook to the following: $ARGUMENTS\n`
+  );
 }

package/lib/sync.js

@@ -8,6 +8,10 @@
 //   3. BACKUP   — before overwriting an existing file, make a .bak copy
 //   4. SKIP     — if nothing changed, touch nothing (idempotent)
 //
+// Sync also generates one SLASH COMMAND per enabled skill (into the
+// OpenCode and Claude commands folders), so every skill appears in
+// the runtime's "/" menu and can be invoked on demand.
+//
 // This is the harness's first guardrail: the harness itself cannot
 // destroy your files — the same protection it gives you against an
 // AI breaking your code.
@@ -23,7 +27,33 @@ import { join, dirname } from "node:path";
 import { loadConfig } from "./config.js";
 import { adapters, supportedRuntimes } from "./adapters/index.js";
 import { validateConfig } from "./validate.js";
-import { loadSkillSections } from "./skills.js";
+import { loadSkills, skillCommandContent } from "./skills.js";
+
+// Write one file the safe way. Returns what happened:
+// dry-run → { dryRun: true, changed } · no change → { unchanged: true }
+// changed → { written: true, backup } (with a .bak copy when the
+// file already existed). Every real write is verified by reading
+// the file back.
+export function writeSafe(abs, content, dryRun) {
+  if (dryRun) {
+    const existing = existsSync(abs) ? readFileSync(abs, "utf8") : null;
+    return { dryRun: true, changed: existing !== content };
+  }
+  mkdirSync(dirname(abs), { recursive: true });
+  if (existsSync(abs)) {
+    const old = readFileSync(abs, "utf8");
+    if (old === content) return { unchanged: true };
+    copyFileSync(abs, abs + ".bak");
+    writeFileSync(abs, content);
+    if (readFileSync(abs, "utf8") !== content)
+      throw new Error(`Failed to write ${abs}`);
+    return { written: true, backup: true };
+  }
+  writeFileSync(abs, content);
+  if (readFileSync(abs, "utf8") !== content)
+    throw new Error(`Failed to write ${abs}`);
+  return { written: true, backup: false };
+}
 
 export function sync({ targetDir, dryRun = false }) {
   const config = loadConfig(targetDir);
@@ -39,8 +69,11 @@ export function sync({ targetDir, dryRun = false }) {
     );
   }
 
-  // LESSON 4: attach the enabled skills — the adapters render them.
-  config.skillSections = loadSkillSections(targetDir, config);
+  // LESSON 4: attach the enabled skills — the adapters render them
+  // into the instruction files, and each one also becomes a slash
+  // command below.
+  const skills = loadSkills(targetDir, config);
+  config.skillSections = skills.map((s) => s.body);
 
   const results = [];
 
@@ -54,38 +87,22 @@ export function sync({ targetDir, dryRun = false }) {
     }
 
     const rel = adapter.targetFile();
-    const abs = join(targetDir, rel);
-    const content = adapter.renderInstructions(config);
-
-    // DRY-RUN: read only, never write. "Look before you agree."
-    if (dryRun) {
-      const existing = existsSync(abs) ? readFileSync(abs, "utf8") : null;
-      results.push({ runtime: name, file: rel, dryRun: true, changed: existing !== content });
-      continue;
-    }
-
-    mkdirSync(dirname(abs), { recursive: true });
+    const outcome = writeSafe(join(targetDir, rel), adapter.renderInstructions(config), dryRun);
+    results.push({ runtime: name, file: rel, ...outcome });
+  }
 
-    if (existsSync(abs)) {
-      const old = readFileSync(abs, "utf8");
-      // Nothing changed? Touch nothing — sync is idempotent.
-      if (old === content) {
-        results.push({ runtime: name, file: rel, unchanged: true });
-        continue;
+  // SLASH COMMANDS: one per enabled skill, for the two runtimes whose
+  // "/" menu lists command files (OpenCode and Claude).
+  if (skills.length) {
+    const files = [];
+    for (const skill of skills) {
+      const content = skillCommandContent(skill);
+      for (const dir of [".opencode/commands", ".claude/commands"]) {
+        const rel = `${dir}/${skill.name}.md`;
+        files.push({ file: rel, ...writeSafe(join(targetDir, rel), content, dryRun) });
       }
-      // About to overwrite? BACK UP first — protection against loss.
-      copyFileSync(abs, abs + ".bak");
-      writeFileSync(abs, content);
-      results.push({ runtime: name, file: rel, written: true, backup: true });
-    } else {
-      writeFileSync(abs, content);
-      results.push({ runtime: name, file: rel, written: true, backup: false });
-    }
-
-    // Verify the write actually landed (read it back).
-    if (!dryRun && readFileSync(abs, "utf8") !== content) {
-      throw new Error(`Failed to write ${abs}`);
     }
+    results.push({ skillCommands: files });
   }
 
   return results;

package/package.json

@@ -23,7 +23,7 @@
     "url": "https://github.com/xcell321/reviewer-harness.git"
   },
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "files": [
     "bin",
     "lib",