reviewer-harness 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edsiel Ursal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# reviewer-harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```
+Four runtimes in the editor, each with files of its own,
+Scattered rules in every corner, never quite in sync,
+An AI that means well — but breaks what already works,
+And forgets your whole project the moment the session ends:
+
+One config to guard them all,
+One harness to remind them,
+One sync to bind them all,
+and in your codebase, protect them.
+```
+
+![version](https://img.shields.io/badge/version-1.0.0-blue)
+![License](https://img.shields.io/badge/License-MIT-yellowgreen)
+![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
+![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+![runtimes](https://img.shields.io/badge/runtimes-4-purple)
+![status](https://img.shields.io/badge/status-Free%20%26%20Open%20Source-green)
+
+**reviewer-harness** is a personal AI agent harness: one master config that syncs guardrail rules, reusable skills, and a local project memory to **Claude Code, OpenCode, Gemini CLI, and Cline** — so the AI that codes for you stops breaking what already works. No API key. No dependencies. Just Node.js and your rules.
+
+## Overview
+
+AI coding assistants are powerful, but anyone who vibe-codes with them daily runs into the same crises:
+
+1. **The "you broke my code" crisis.** You ask the AI to add one feature, and it rewrites a file that was already working — deleting or altering parts you never asked it to touch. The fix becomes the bug.
+
+2. **The hallucination crisis.** The AI confidently imports packages that don't exist, calls functions it invented, and presents output that only *looks* correct — until you run it.
+
+3. **The fragmentation crisis.** Every AI runtime wants its own instruction file (`CLAUDE.md`, `.opencode/instructions.md`, `GEMINI.md`, `.clinerules`). Keeping the same rules in sync across all of them by hand is tedious and error-prone.
+
+4. **The amnesia crisis.** Every new session, the AI forgets your project: the decisions you made, the files that must never be touched, the gotchas you already paid for once.
+
+**reviewer-harness solves this with One Master Config.** You define your rules, your problem statement, and your skills once — in a single `harness.config.json` — and the harness validates them (including scanning for leaked secrets) and syncs them deterministically to every runtime. A local, graph-style memory gives the AI something to read before it codes, and to write to when it learns.
+
+## The problem (why this harness exists)
+
+**An AI with no guardrails.** You cannot control the model — but you *can* control **the rules it must follow**. That is the harness. The problem statement lives in `harness.config.json` (the `problem` field) and is synced along with everything else — it appears in every runtime file, so every AI knows not just the rules, but *why* they exist.
+
+## What is this?
+
+The harness is **not the AI model** — it is what prepares everything the AI reads before it starts coding:
+
+```
+harness.config.json          ← your master spec (ONE file)
+        │  validate()        ← quality checks + secret scanning
+        ▼
+lib/adapters/*.js            ← adapters: opencode, claude, gemini, cline
+        │  renderInstructions()
+        ▼
+.opencode/instructions.md    ← OpenCode
+CLAUDE.md                    ← Claude Code
+GEMINI.md                    ← Gemini CLI
+.clinerules                  ← Cline
+```
+
+Change the rules in **one** place (`harness.config.json`), and `sync` propagates them to every runtime.
+
+## Quickstart
+
+You can use reviewer-harness in two ways: **Modular Mode** (zero-install: add individual skills to any project, no setup) or **Full Harness Mode** (one master config synced across all 4 runtimes).
+
+### 1. Modular Skills (zero-install via npx)
+
+Copy a single skill straight into your current project — no install, no config needed. The skill lands in `./skills/` as a playbook your AI can follow:
+
+```bash
+# Browse the bundled skills first
+npx reviewer-harness skills list
+
+# Add individual skills to this project
+npx reviewer-harness skills add safe-editing
+npx reviewer-harness skills add no-hallucination
+```
+
+> Prefer a global CLI? Install once with `npm install -g reviewer-harness` and run `reviewer-harness skills add <name>` anywhere.
+
+### 2. Full Harness Synchronization (4 runtimes)
+
+`init` creates your master config, `validate` checks it (including secret scanning), and `sync` generates the native instruction file for every runtime you enable: `.opencode/instructions.md`, `CLAUDE.md`, `GEMINI.md`, and `.clinerules`.
+
+```bash
+# Using npx (zero-install, recommended)
+npx reviewer-harness init
+npx reviewer-harness sync --dry-run   # preview: writes nothing
+npx reviewer-harness sync             # writes, with .bak backups
+
+# Using pnpm (zero-install)
+pnpm dlx reviewer-harness init
+
+# Or install globally
+npm install -g reviewer-harness
+reviewer-harness init
+
+# Direct git clone
+git clone https://github.com/xcell321/reviewer-harness.git
+cd reviewer-harness && node bin/cli.js init --target ../my-project
+```
+
+### 3. Standalone one-liner installers
+
+```bash
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/install.sh | bash
+
+# Windows PowerShell
+irm https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/install.ps1 | iex
+```
+
+### 4. Running via Docker (zero local Node.js required)
+
+For zero-dependency execution without installing Node.js on your machine:
+
+```bash
+git clone https://github.com/xcell321/reviewer-harness.git
+cd reviewer-harness
+
+# Check status / start the harness in the mounted workspace
+docker compose run --rm reviewer-harness status
+docker compose run --rm reviewer-harness init
+docker compose run --rm reviewer-harness sync
+```
+
+## Sandboxing and security notice
+
+reviewer-harness executes locally and is fully transparent:
+
+- **Zero telemetry, zero network.** The tool reads and writes files in your project only. It sends no code or prompts to external servers, and it never needs an API key.
+- **Non-destructive backups.** Before modifying any existing instruction file, sync creates a `.bak` copy; files that would not change are skipped.
+- **Inspect before applying.** Run `sync --dry-run` to see exactly what would change — it writes nothing.
+- **Secrets are blocked, not leaked.** `validate` (and sync itself) scans the config for API keys and tokens and refuses to sync if one is found.
+- **Prefer a hard sandbox?** Run it in the Docker container above.
+
+## The Sync Engine (safe by design)
+
+Guardrails that run before any file is written:
+
+1. **VALIDATE GATE** — if the spec is broken or contains a secret, sync refuses to run
+2. **DRY-RUN** — `sync --dry-run`: preview only, writes nothing
+3. **BACKUP** — before overwriting an existing file, write a `.bak` copy first
+4. **IDEMPOTENT** — if nothing changed, touch nothing (safe to run repeatedly)
+
+## Validate + Secret Scanning
+
+`validate` inspects the config before it becomes instructions:
+
+- No empty rules, no duplicates
+- Secret scanning — API keys and tokens must never be synced (they would leak into Git!)
+- `sync` itself refuses to proceed when validation reports errors
+
+## This repo governs itself
+
+reviewer-harness eats its own cooking: the instruction files at this repo's root — `.opencode/instructions.md`, `CLAUDE.md`, `GEMINI.md`, `.clinerules` — plus the agents and commands in `.opencode/` and `.claude/` are **generated by reviewer-harness itself** from its own `harness.config.json`. Open this repo in any AI coding tool and the tool follows the harness's own rules while working on the harness. To refresh them after editing the config, just run `node bin/cli.js sync` here.
+
+## Local Memory (graph-style, Obsidian-ready)
+
+AI models have no memory — every session, they forget your project. The harness keeps a `memory/` folder (inspired by Graphify's knowledge graph and Obsidian's vault, but lightweight and fully local):
+
+```
+memory/
+  project.md     — notes (plain markdown, Obsidian-style)
+  decisions.md   — [[wiki links]] connect the notes
+  INDEX.md       — generated: the AI reads this first
+  graph.json     — generated: nodes = notes, edges = links
+```
+
+One of the rules orders the AI to read the memory first, and to write what it learns as a note with [[links]]. `sync` also refreshes the index. Open `memory/` in Obsidian to see the graph view.
+
+## Skills
+
+Reusable playbooks, enabled per project:
+
+- `skills list` — see the bundled skills
+- `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 — 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
+
+One master definition in the harness, generated into each runtime's format:
+
+- `agents add planner|reviewer|debugger` → `.opencode/agents/` + `.claude/agents/`
+  - **planner** (Tigplano) — plans before coding
+  - **reviewer** (Bantay) — hunts breakage and hallucinated code in diffs
+  - **debugger** (Tig-ayo) — root-cause debugging, never symptom-patching
+- `commands add review|explain` → `.opencode/commands/` + `.claude/commands/` (type `/review` or `/explain` in your runtime)
+
+## Command reference
+
+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
+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
+```
+
+Running from a source checkout instead? The same commands work as `node bin/cli.js <command>`.
+
+## File map
+
+- `bin/cli.js` — commands: `status`, `sync`, `init`, `validate`, `memory`, `skills`, `agents`, `commands`
+- `bin/install.sh` / `bin/install.ps1` — one-liner installers (Linux/macOS, Windows)
+- `Dockerfile` / `docker-compose.yml` — run the harness with zero local Node.js
+- `lib/config.js` — loads and validates the structure of the master spec
+- `lib/validate.js` — rule quality checks + secret scanning
+- `lib/sync.js` — THE SYNC ENGINE: validate gate, dry-run, backup, idempotent writes
+- `lib/init.js` — creates the harness.config.json template in a new project
+- `lib/memory.js` — local memory: notes vault, graph builder, index generator
+- `lib/skills.js` — skills system: bundled store, install/enable, section rendering
+- `lib/agents.js` / `lib/commands.js` — one source → OpenCode + Claude formats
+- `lib/adapters/` — registry + one adapter per runtime (opencode, claude, gemini, cline)
+- `skills/` — bundled skills · `agents/` — bundled sub-agents · `commands/` — bundled slash commands
+
+## How it was built (the lessons)
+
+1. ✅ Scaffold — CLI + master config + adapter pattern
+2. ✅ Sync engine — dry-run, .bak backup, idempotent
+3. ✅ Guardrails — `validate` command + secret scanning + sync gate
+4. ✅ Skills system — `skills add/list/remove`
+5. ✅ Sub-agents and slash commands — `agents add`, `commands add`
+6. ✅ Polish and publish — v1.0.0, LICENSE, publish-ready for GitHub/npx
+7. ✅ v1.1.0 — all-English repo, validate-and-report rule, self-governing repo, modular skills, one-liner installers, Docker
+
+## Contributing & Security
+
+- Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
+- Found a security issue? See [SECURITY.md](SECURITY.md)
+
+## Author & credits
+
+Created and maintained by **Edsiel Ursal** ([@xcell321](https://github.com/xcell321)) — designed and built together with **Muse**, Meta's AI assistant, as pair programmer and mentor. Every feature in this repo was planned, coded, tested, and documented in that collaboration: Edsiel directed the vision and made every call; Muse helped write and verify the code.
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/agents/debugger.md

@@ -0,0 +1,13 @@
+---
+name: debugger
+description: The Fixer — root-cause debugging specialist, never patches over symptoms.
+---
+
+You are the Fixer, the debugging specialist.
+
+1. Reproduce the error first — capture the exact command and the full error message.
+2. Read the stack trace down to the first line that is yours (not the library's).
+3. Form a hypothesis, then prove it with logs or a small test — never guess at a fix.
+4. Fix the cause with the smallest change possible.
+5. Verify: re-run the reproduction — is the error really gone? Did anything else break?
+6. If the bug is worth remembering, write it as a note in memory/ with [[links]].

package/agents/planner.md

@@ -0,0 +1,12 @@
+---
+name: planner
+description: The Planner — breaks a task into small steps before any code is written.
+---
+
+You are the Planner. Before a single line of code is written:
+
+1. Read memory/INDEX.md and the related notes — what does the project already know?
+2. Break the task into small steps, in the right order.
+3. Identify the risky files (heavily connected ones, or anything listed under "do not touch" in the memory).
+4. State how each step will be verified (test, run, check).
+5. Present the plan and wait for approval before coding.

package/agents/reviewer.md

@@ -0,0 +1,12 @@
+---
+name: reviewer
+description: Bantay, the Watcher — reviews changes against the rules, hunting breakage and invented code.
+---
+
+You are Bantay, the reviewer. Your job: catch breakage before it gets committed.
+
+1. Look at the diff of the latest changes.
+2. Check it against the project's rules: was anything changed that was never asked for? Was a file rewritten instead of edited?
+3. Hunt for hallucination: imports that are not in package.json, functions or APIs that appear nowhere in the codebase or docs.
+4. Check the memory was respected: was anything under "do not touch" violated?
+5. Report as a list: **VIOLATION** (must fix) and **WARNING** (worth a look). If it is clean, say clearly that it is clean — never invent a problem.

package/bin/cli.js

@@ -0,0 +1,251 @@
+#!/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 | 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, 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, loadBundledSkills, skillCommandContent } from "../lib/skills.js";
+import { listBundledAgents, addAgent } from "../lib/agents.js";
+import { listBundledCommands, addCommand } from "../lib/commands.js";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    "dry-run": { type: "boolean", default: false },
+    target: { type: "string", default: process.cwd() },
+  },
+});
+const [command, sub, arg] = positionals;
+const targetDir = values.target;
+const dryRun = values["dry-run"];
+
+function help() {
+  console.log(`reviewer-harness — your own AI harness
+
+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).
+`);
+}
+
+function cmdStatus() {
+  const config = loadConfig(targetDir);
+  console.log(`Harness : ${config.name} v${config.version}`);
+  console.log(`Target  : ${targetDir}`);
+  console.log(`Runtimes:`);
+  for (const name of config.runtimes) {
+    const adapter = adapters[name];
+    console.log(`  - ${name} → ${adapter ? adapter.targetFile() : "(no adapter!)"}`);
+  }
+  console.log(`Skills  : ${config.skills?.length ? config.skills.join(", ") : "(none)"}`);
+}
+
+function cmdSync() {
+  const results = sync({ targetDir, dryRun });
+  if (dryRun) console.log("(dry-run: nothing was written)\n");
+  for (const r of results) {
+    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"}`);
+    } else if (r.unchanged) {
+      console.log(`- ${r.runtime} → ${r.file}: no changes, skipped ✓`);
+    } else {
+      console.log(`- ${r.runtime} → ${r.file}: WRITTEN ✓${r.backup ? " (.bak backup made)" : ""}`);
+    }
+  }
+  // If the project has a local memory, refresh its index as part of
+  // sync — so the graph the AI reads is always current.
+  if (!dryRun && existsSync(memoryDir(targetDir))) {
+    const stats = buildIndex(targetDir);
+    console.log(`- memory: index refreshed (${stats.notes} notes, ${stats.edges} links) ✓`);
+  }
+}
+
+function cmdMemory() {
+  if (sub === "init") {
+    const r = initMemory(targetDir);
+    console.log(
+      r.created.length
+        ? `Local memory created: ${r.dir} (${r.created.join(", ")})`
+        : `Local memory already exists: ${r.dir} (nothing overwritten)`
+    );
+    console.log(`Index: ${r.notes} notes, ${r.edges} links. Open the folder in Obsidian for the graph view.`);
+  } else if (sub === "index") {
+    if (!existsSync(memoryDir(targetDir)))
+      throw new Error(`No memory/ in ${targetDir} — run "memory init" first.`);
+    const stats = buildIndex(targetDir);
+    console.log(`Index rebuilt: ${stats.notes} notes, ${stats.edges} links, ${stats.dangling} dangling links.`);
+  } else if (sub === "list") {
+    const notes = readNotes(targetDir);
+    if (!notes.length) {
+      console.log(`No memory notes in ${join(targetDir, "memory")} — run "memory init" first.`);
+      return;
+    }
+    for (const n of notes) {
+      console.log(`- [[${n.id}]] ${n.title}${n.links.length ? ` → ${n.links.join(", ")}` : ""}`);
+    }
+  } else {
+    console.log(`Usage: memory <init|index|list> [--target <dir>]`);
+  }
+}
+
+function cmdInit() {
+  const { created, file } = initProject(targetDir);
+  console.log(created ? `Config created: ${file}` : `Already exists: ${file} (not overwritten)`);
+}
+
+function cmdValidate() {
+  const config = loadConfig(targetDir);
+  const { errors, warnings, ok } = validateConfig(config, {
+    knownRuntimes: supportedRuntimes,
+  });
+  for (const e of errors) console.log(`✗ ${e}`);
+  for (const w of warnings) console.log(`⚠ ${w}`);
+  if (ok && !warnings.length) console.log(`✓ Config is clean — no problems, no secrets.`);
+  else if (ok) console.log(`✓ No errors (${warnings.length} warning(s)).`);
+  else {
+    console.log(`\n✗ ${errors.length} error(s) — fix them before syncing.`);
+    process.exitCode = 1;
+  }
+}
+
+function cmdSkills() {
+  if (sub === "list") {
+    let enabled = [];
+    try {
+      enabled = loadConfig(targetDir).skills ?? [];
+    } catch {
+      /* no config in the target — just list the bundled skills */
+    }
+    for (const s of listBundledSkills()) {
+      console.log(`- ${s.name}${enabled.includes(s.name) ? " ✓ enabled" : ""} — ${s.description}`);
+    }
+  } else if (sub === "add" && arg) {
+    const r = addSkill(arg, targetDir);
+    if (r.noConfig) {
+      console.log(
+        `Skill "${arg}" copied → ${r.file}\n` +
+          `(No harness.config.json here, so it is not enabled in a harness — it is yours as a standalone playbook.\n` +
+          `Run "init" in this project if you want the full harness to sync it to every runtime.)`
+      );
+    } else {
+      console.log(
+        r.alreadyEnabled
+          ? `Skill "${arg}" is already enabled (file refreshed). Run "sync" to apply.`
+          : `Skill "${arg}" installed → ${r.file}\nEnabled in the config. Run "sync" to apply it to the runtimes.`
+      );
+    }
+  } else if (sub === "remove" && arg) {
+    const r = removeSkill(arg, targetDir);
+    console.log(
+      r.wasEnabled
+        ? `Skill "${arg}" disabled${r.removedFile ? " and its file removed" : ""}. Run "sync" to update the runtimes.`
+        : `Skill "${arg}" was not enabled.`
+    );
+  } else {
+    console.log(`Usage: skills <list|add <name>|remove <name>> [--target <dir>]`);
+  }
+}
+
+function cmdAgents() {
+  if (sub === "list") {
+    for (const a of listBundledAgents()) console.log(`- ${a.name} — ${a.description}`);
+  } else if (sub === "add" && arg) {
+    const r = addAgent(arg, targetDir);
+    console.log(`Agent "${arg}" installed:`);
+    for (const f of r.written) console.log(`  → ${f}`);
+  } else {
+    console.log(`Usage: agents <list|add <name>> [--target <dir>]`);
+  }
+}
+
+function cmdCommands() {
+  if (sub === "list") {
+    for (const c of listBundledCommands()) console.log(`- /${c.name} — ${c.description}`);
+  } else if (sub === "add" && arg) {
+    const r = addCommand(arg, targetDir);
+    console.log(`Command "/${arg}" installed:`);
+    for (const f of r.written) console.log(`  → ${f}`);
+  } else {
+    console.log(`Usage: commands <list|add <name>> [--target <dir>]`);
+  }
+}
+
+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();
+  else if (command === "init") cmdInit();
+  else if (command === "validate") cmdValidate();
+  else if (command === "memory") cmdMemory();
+  else if (command === "skills") cmdSkills();
+  else if (command === "agents") cmdAgents();
+  else if (command === "commands") cmdCommands();
+  else if (command === "global") cmdGlobal();
+  else help();
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/bin/install.ps1

@@ -0,0 +1,30 @@
+# reviewer-harness installer (Windows PowerShell)
+#
+# Installs the reviewer-harness CLI globally from GitHub, so you can
+# run `reviewer-harness` in any project. The only requirement is
+# Node.js 18+ (the harness itself has zero dependencies).
+#
+# Usage:
+#   irm https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/install.ps1 | iex
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+    Write-Host "reviewer-harness needs Node.js 18 or newer."
+    Write-Host "Install it first: https://nodejs.org"
+    exit 1
+}
+
+$major = [int](node -p "process.versions.node.split('.')[0]")
+if ($major -lt 18) {
+    Write-Host "reviewer-harness needs Node.js 18 or newer (you have $(node -v))."
+    exit 1
+}
+
+Write-Host "Installing reviewer-harness globally from GitHub..."
+npm install -g reviewer-harness
+
+Write-Host ""
+Write-Host "Done. Try it in any project:"
+Write-Host "  reviewer-harness init     # create a master config"
+Write-Host "  reviewer-harness sync     # sync the rules to every runtime"

package/bin/install.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# reviewer-harness installer (Linux / macOS)
+#
+# Installs the reviewer-harness CLI globally from GitHub, so you can
+# run `reviewer-harness` in any project. The only requirement is
+# Node.js 18+ (the harness itself has zero dependencies).
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/install.sh | bash
+
+set -euo pipefail
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "reviewer-harness needs Node.js 18 or newer."
+  echo "Install it first: https://nodejs.org"
+  exit 1
+fi
+
+NODE_MAJOR="$(node -p "process.versions.node.split('.')[0]")"
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  echo "reviewer-harness needs Node.js 18 or newer (you have $(node -v))."
+  exit 1
+fi
+
+echo "Installing reviewer-harness globally from GitHub..."
+npm install -g reviewer-harness
+
+echo ""
+echo "Done. Try it in any project:"
+echo "  reviewer-harness init     # create a master config"
+echo "  reviewer-harness sync     # sync the rules to every runtime"

package/commands/explain.md

@@ -0,0 +1,12 @@
+---
+name: explain
+description: Explain code or a change in simple Bisaya (Cebuano).
+---
+
+Explain the following in simple Bisaya (Cebuano): $ARGUMENTS
+
+Rules for the explanation:
+- One sentence per idea; avoid heavy jargon.
+- If you use an English technical term, define it first in one sentence.
+- If it is code: what it does, its inputs, its outputs, and where it is used in the project.
+- If it is a change (diff): what changed, in which files, and why.

package/commands/review.md

@@ -0,0 +1,16 @@
+---
+name: review
+description: Review the latest changes against the harness rules and the memory.
+---
+
+Review the latest changes in this project (git diff, or the files most recently edited).
+
+Check:
+1. Was anything changed that was never asked for, or a file rewritten instead of edited?
+2. Is there an import, function, or API that exists nowhere in the codebase or package.json (hallucination)?
+3. Was anything in memory/ violated (decisions, or "do not touch" areas)?
+4. Were the tests/lint run after the change?
+
+Focus: $ARGUMENTS
+
+Report as VIOLATION / WARNING. If it is clean, say it is clean.