reviewer-harness 1.9.0 → 1.14.0

package/README.md

@@ -1,7 +1,7 @@
 # reviewer-harness
 
 ```
-Four runtimes in the editor, each with files of its own,
+Eight 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:
@@ -12,97 +12,99 @@ One sync to bind them all,
 and in your codebase, protect them.
 ```
 
-![version](https://img.shields.io/badge/version-1.0.0-blue)
+![version](https://img.shields.io/badge/version-1.14.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)
+![runtimes](https://img.shields.io/badge/runtimes-8-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.
+**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, Cline, Freebuff, GitHub Copilot CLI, Antigravity, and Qoder** — so the AI that codes for you stops breaking what already works. No API key. No dependencies. Just Node.js and your rules.
 
-## Overview
+## Introduction
 
-AI coding assistants are powerful, but anyone who vibe-codes with them daily runs into the same crises:
+AI coding assistants are powerful, but anyone who vibe-codes with them daily runs into the same four 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.
+3. **The fragmentation crisis.** Every AI runtime wants its own instruction file (`CLAUDE.md`, `.opencode/instructions.md`, `GEMINI.md`, `.clinerules`, and more). 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.
+**reviewer-harness solves all four 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)
+### What it is — and what it is not
 
-**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.
+- **It is** the layer that prepares everything the AI reads before it starts coding: your rules, your skills, your project memory.
+- **It is not** the AI model. It never calls an API, never sends your code anywhere, and never needs an API key.
+- **It is not** a framework or a library you import. It is a small CLI that writes instruction files into your project, then gets out of the way.
 
-## What is this?
+### Who it is for
 
-The harness is **not the AI model** — it is what prepares everything the AI reads before it starts coding:
+Anyone who codes with an AI assistant and is tired of re-explaining the same rules, re-fixing the same breakage, and re-teaching the same project every session. It was built by a student vibe-coder for daily use across eight different AI CLIs — and it works just as well if you only use one.
 
-```
-harness.config.json          ← your master spec (ONE file)
-        │  validate()        ← quality checks + secret scanning
-        ▼
-lib/adapters/*.js            ← adapters: opencode, claude, gemini, cline,
-                               freebuff, copilot, antigravity
-        │  renderInstructions()
-        ▼
-.opencode/instructions.md    ← OpenCode
-CLAUDE.md                    ← Claude Code
-GEMINI.md                    ← Gemini CLI
-.clinerules                  ← Cline
-.agents/skills/<skill>/SKILL.md  ← Freebuff, Antigravity (project skills)
-.github/skills/<skill>/SKILL.md  ← GitHub Copilot CLI (project skills)
-```
+## Requirements
 
-Change the rules in **one** place (`harness.config.json`), and `sync` propagates them to every runtime.
+- **Node.js 18 or newer.** Check yours with `node --version`. No other dependencies — the harness has zero npm dependencies.
+- **Any OS:** Windows, macOS, or Linux.
+- **No account, no API key, no sign-up.** Everything runs locally on your machine.
 
-## Quickstart
+## Installation
 
-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 7 runtimes).
+Pick one method. All six install the same tool; the first three need nothing but Node.js.
 
-### 1. Modular Skills (zero-install via npx)
+### Method A — npx (zero-install, recommended)
 
-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:
+No install at all. Run the harness straight from the npm registry, one command at a time:
 
 ```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
+npx reviewer-harness status
 ```
 
-> Prefer a global CLI? Install once with `npm install -g reviewer-harness` and run `reviewer-harness skills add <name>` anywhere.
+The first run downloads the package (a few seconds); later runs reuse the cache. Use this method if you just want to try it, or if you use the harness occasionally.
 
-### 2. Full Harness Synchronization (7 runtimes)
+### Method B — pnpm dlx (zero-install)
 
-`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` — plus Agent Skills bundles (`.agents/skills/<skill>/SKILL.md` for Freebuff and Antigravity, `.github/skills/<skill>/SKILL.md` for GitHub Copilot CLI), so your skills follow you even when you switch CLIs.
+The same idea, for pnpm users:
 
 ```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
+pnpm dlx reviewer-harness status
+```
+
+### Method C — Install globally (recommended for daily use)
 
-# Using pnpm (zero-install)
-pnpm dlx reviewer-harness init
+Install once, then run `reviewer-harness` anywhere, in any project:
 
-# Or install globally
+```bash
 npm install -g reviewer-harness
-reviewer-harness init
+reviewer-harness status
+```
+
+To update to the newest version later, run the same install command again:
+
+```bash
+npm install -g reviewer-harness@latest
+```
+
+> **Seeing an old version after updating?** `npx` can serve a cached copy. Run `npx --yes reviewer-harness@latest status` once to refresh the cache, or use the global install above.
+
+### Method D — Direct git clone (source checkout)
 
-# Direct git clone
+Clone the repo and run the CLI from source — useful if you want to read or hack on the code:
+
+```bash
 git clone https://github.com/xcell321/reviewer-harness.git
-cd reviewer-harness && node bin/cli.js init --target ../my-project
+cd reviewer-harness
+node bin/cli.js status
 ```
 
-### 3. Standalone one-liner installers
+From a source checkout, every command in this README works as `node bin/cli.js <command>` instead of `reviewer-harness <command>`.
+
+### Method E — Standalone one-liner installers
+
+A single command that installs the harness for you — no npm needed beyond Node.js:
 
 ```bash
 # Linux / macOS
@@ -112,9 +114,9 @@ curl -fsSL https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/
 irm https://raw.githubusercontent.com/xcell321/reviewer-harness/main/bin/install.ps1 | iex
 ```
 
-### 4. Running via Docker (zero local Node.js required)
+### Method F — Docker (zero local Node.js required)
 
-For zero-dependency execution without installing Node.js on your machine:
+Run the harness without installing Node.js on your machine at all:
 
 ```bash
 git clone https://github.com/xcell321/reviewer-harness.git
@@ -126,100 +128,214 @@ docker compose run --rm reviewer-harness init
 docker compose run --rm reviewer-harness sync
 ```
 
-## Sandboxing and security notice
+### Verify your installation
 
-reviewer-harness executes locally and is fully transparent:
+After any method, run this — you should see the harness name, version, and your runtimes:
 
-- **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.
+```bash
+reviewer-harness status
+```
 
-## The Sync Engine (safe by design)
+Expected output (version number varies):
 
-Guardrails that run before any file is written:
+```
+Harness : reviewer-harness v1.14.0
+Target  : /path/to/your/project
+Runtimes:
+  - opencode → .opencode/instructions.md
+  - claude → CLAUDE.md
+  - gemini → GEMINI.md
+  - cline → .clinerules
+  - freebuff → .agents/skills/<skill>/SKILL.md
+  - copilot → .github/skills/<skill>/SKILL.md
+  - antigravity → .agents/skills/<skill>/SKILL.md
+  - qoder → .qoder/skills/<skill>/SKILL.md
+Skills  : safe-editing, no-hallucination, ...
+```
 
-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)
+If you see `Config file not found`, you are in a folder without a harness config yet — run `init` (next section).
 
-## Validate + Secret Scanning
+## Quick start — your first project in 5 minutes
 
-`validate` inspects the config before it becomes instructions:
+This is the full flow, start to finish. Run the commands inside your project folder.
 
-- 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
+**Step 1 — Create the master config.** One time per project:
 
-## This repo governs itself
+```bash
+reviewer-harness init
+```
 
-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/` and the skill bundles in `.agents/skills/` and `.github/skills/` 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.
+Expected output:
 
-## Local Memory (graph-style, Obsidian-ready)
+```
+Config created: /path/to/your/project/harness.config.json
+```
 
-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):
+This creates `harness.config.json` — the one file that holds your rules, your problem statement, and your enabled skills. Open it and edit the `rules` and `problem` fields to describe your project. (Running `init` again never overwrites an existing config.)
+
+**Step 2 — Check the config.** Before anything gets written, validate it:
 
+```bash
+reviewer-harness validate
 ```
-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
+
+Expected output when everything is fine:
+
+```
+✓ Config is clean — no problems, no secrets.
 ```
 
-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.
+`validate` checks for empty or duplicate rules and scans the config for leaked API keys and tokens — secrets must never be synced into instruction files (they would leak into Git).
+
+**Step 3 — Add the skills you want.** Pick from the 22 bundled skills (full list below):
+
+```bash
+reviewer-harness skills add safe-editing
+reviewer-harness skills add no-hallucination
+reviewer-harness skills add debug-first
+```
+
+Each `skills add` copies the skill into your project and enables it in the config. See what is available first with `reviewer-harness skills list`.
+
+**Step 4 — Preview the sync.** See exactly what would change, without writing anything:
+
+```bash
+reviewer-harness sync --dry-run
+```
+
+**Step 5 — Sync.** Write the instruction files for every runtime:
+
+```bash
+reviewer-harness sync
+```
+
+Before overwriting any existing instruction file, sync saves a `.bak` backup copy. Files that would not change are left untouched — running sync twice in a row writes nothing the second time.
+
+**Step 6 — Open your AI tool.** That is it. Open the project in Claude Code, OpenCode, Gemini CLI, Cline, or any of the other runtimes, and the AI reads your rules, your skills, and your problem statement before it writes a single line.
+
+**Step 7 — Repeat when rules change.** Edit `harness.config.json`, then run `validate` and `sync` again. One file changes, every runtime follows.
+
+## How to use
+
+### Two ways to use it
 
-## Skills
+**Modular Mode — one skill, zero setup.** Copy a single skill straight into any project, no config needed. The skill lands in `./skills/` as a playbook your AI can follow:
 
-Reusable playbooks, enabled per project:
+```bash
+# Browse the bundled skills first
+npx reviewer-harness skills list
 
-- `skills list` — see the bundled skills
-- `skills add <name>` — install into the project and enable it in the config
-- `skills remove <name>` — disable it
+# Add individual skills to this project
+npx reviewer-harness skills add safe-editing
+npx reviewer-harness skills add no-hallucination
+```
+
+**Full Harness Mode — one config, every runtime.** `init` creates your master config, `validate` checks it, and `sync` generates the native instruction file for every runtime you enable. This is the mode the Quick start above walks through, and the mode this README documents in detail.
+
+### Skills — reusable playbooks
 
-Bundled: `safe-editing`, `no-hallucination`, `debug-first`, `explain-bisaya`, `clone`, `rea`. 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.
+A skill is a playbook: a short, checkable set of rules for one job (safe editing, API security, UI taste, debugging, and so on), distilled from real, reputable sources — not generic advice. Every rule cites its source.
 
-**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.)
+```bash
+reviewer-harness skills list            # see all 22 bundled skills (+ which are enabled)
+reviewer-harness skills add <name>      # install into the project and enable it in the config
+reviewer-harness skills remove <name>   # disable it in the config and remove it
+```
+
+All 22 bundled skills (v1.14.0):
+
+| Skill | What it does |
+|---|---|
+| `safe-editing` | Surgical editing — the smallest possible diff, no collateral damage. |
+| `no-hallucination` | Make sure every library, function, and API actually exists before using it. |
+| `debug-first` | Root-cause debugging — reproduce first, fix the cause, not the symptom. |
+| `explain-bisaya` | After each task, explain the changes in simple Bisaya (Cebuano). |
+| `clone` | Fully clone a website's design — layout, components, animations, borders — while replacing all text and assets with your own. |
+| `rea` | Reverse-engineer a shipped app, binary, or website with REA: inspect it without source code, get evidence for how a feature works, and rebuild it as your own code. |
+| `api-security` | 14 API security rules — apply to every backend endpoint you build or review. |
+| `ux-edge-states` | 10 UX states beyond the happy path — empty, loading, error, offline, success. |
+| `owasp-top10` | OWASP Top 10 web security risks — the industry standard check before shipping. |
+| `backend-performance` | 10 backend performance rules from nodebestpractices and system-design-primer. |
+| `devops-basics` | 12 DevOps rules from nodebestpractices — Docker, graceful shutdown, health checks, logging. |
+| `motion-design` | Animation principles from GSAP (GreenSock) — easing, sequencing, stagger, performance. |
+| `frontend-performance` | Frontend performance rules from the Front-End Checklist — animations, resource hints, budgets, lazy loading. |
+| `system-design` | 68 system design rules from system-design-primer — CAP tradeoffs, load balancing, scaling. |
+| `nodejs-quality` | 62 Node.js quality rules from nodebestpractices — errors, structure, testing, production, security. |
+| `audit-team` | Run an 8-agent parallel audit — 5 skill specialists plus 3 area agents — report-only, no edits. |
+| `ub-mode` | Uncle Bob mode — Clean Code discipline from Robert C. Martin: TDD first, CRAP < 10. |
+| `design-taste-frontend` | Anti-slop design taste from Leonxlnx/taste-skill — layout, palettes, type, heroes, copy ban lists. |
+| `ui-ux-pro-max` | Full UI/UX audit from nextlevelbuilder/ui-ux-pro-max-skill — 224 checkable guidelines across 10 categories. |
+| `vengeance-ui` | Modern animated React components from VengeanceUI — 79 copy-paste components across 9 families. |
+| `brainstorming` | Find out what you actually want — and why — before anything gets built. Design doc first, approval first. |
+| `writing-plans` | Turn an approved spec into a bite-sized TDD implementation plan. |
+
+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.
 
 **A built-in pairing:** the `/safe-editing` command always carries the `no-hallucination` playbook inside it as a companion section — one call, both disciplines, so the AI that edits can never invent the code it edits with.
 
-## Sub-agents and Slash Commands
+**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, plus skill bundles for Freebuff, Copilot CLI, Antigravity, and Qoder. From then on, they are in the `/` menu of any project you open. (Project rules still come from `sync` inside a project.) Add `--dry-run` first to preview what it would install.
 
-One master definition in the harness, generated into each runtime's format:
+### The sync engine — what happens when you run `sync`
 
-- `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)
+```
+harness.config.json          ← your master spec (ONE file)
+        │  validate()        ← quality checks + secret scanning
+        ▼
+lib/adapters/*.js            ← adapters: opencode, claude, gemini, cline,
+                               freebuff, copilot, antigravity, qoder
+        │  renderInstructions()
+        ▼
+.opencode/instructions.md    ← OpenCode
+CLAUDE.md                    ← Claude Code
+GEMINI.md                    ← Gemini CLI
+.clinerules                  ← Cline
+.agents/skills/<skill>/SKILL.md  ← Freebuff, Antigravity (project skills)
+.github/skills/<skill>/SKILL.md  ← GitHub Copilot CLI (project skills)
+.qoder/skills/<skill>/SKILL.md   ← Qoder (project skills)
+.opencode/commands/<name>.md + .claude/commands/<name>.md  ← slash command per skill
+```
 
-## Command reference
+Change the rules in **one** place (`harness.config.json`), and `sync` propagates them to every runtime.
 
-Requires Node.js 18+ (no dependencies). Run these inside your project — every command works on the current directory unless you add `--target <dir>`.
+Four guardrails 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, sync writes a `.bak` copy first.
+4. **IDEMPOTENT** — if nothing changed, sync touches nothing. Safe to run repeatedly.
+
+### Validate + secret scanning
 
-**Start & everyday**
+`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.
 
 ```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**
+### Sub-agents and slash commands
+
+One master definition in the harness, generated into each runtime's format:
 
 ```bash
-reviewer-harness skills list
-reviewer-harness skills add safe-editing
-reviewer-harness skills remove safe-editing
+reviewer-harness agents list
 reviewer-harness agents add reviewer
+reviewer-harness commands list
 reviewer-harness commands add review
 ```
 
-**Local memory**
+- `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)
+
+### Local memory — the AI remembers your project
+
+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):
 
 ```bash
 reviewer-harness memory init     # start the memory/ vault
@@ -227,22 +343,105 @@ reviewer-harness memory list     # list notes + their links
 reviewer-harness memory index    # rebuild INDEX.md + graph.json
 ```
 
+What it creates:
+
+```
+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.
+
+### 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/` and the skill bundles in `.agents/skills/`, `.github/skills/`, and `.qoder/skills/` 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.
+
+## 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 (Installation, Method F).
+
+## 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
+
+| Command | What it does |
+|---|---|
+| `reviewer-harness init` | One-time: create `harness.config.json` in the project (never overwrites an existing one) |
+| `reviewer-harness validate` | Check the config: rule quality + secret scanning |
+| `reviewer-harness sync --dry-run` | Preview the sync: shows what would change, writes nothing |
+| `reviewer-harness sync` | Apply the rules to every enabled runtime (with `.bak` backups) |
+| `reviewer-harness status` | Show the config: name, version, runtimes, target files, enabled skills |
+
+### Skills, agents, commands
+
+| Command | What it does |
+|---|---|
+| `reviewer-harness skills list` | List all 22 bundled skills (+ which are enabled) |
+| `reviewer-harness skills add <name>` | Install a skill into the project and enable it in the config |
+| `reviewer-harness skills remove <name>` | Disable a skill and remove it |
+| `reviewer-harness agents list` | List the bundled sub-agents |
+| `reviewer-harness agents add <name>` | Install a sub-agent (OpenCode + Claude) |
+| `reviewer-harness commands list` | List the bundled slash commands |
+| `reviewer-harness commands add <name>` | Install a slash command (OpenCode + Claude) |
+| `reviewer-harness global [--dry-run]` | Install EVERY bundled skill for ALL projects (global `/` menus + skill bundles) |
+
+### Local memory
+
+| Command | What it does |
+|---|---|
+| `reviewer-harness memory init` | Start the local memory vault (`memory/` folder) |
+| `reviewer-harness memory list` | List memory 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/cli.js` — commands: `status`, `sync`, `init`, `validate`, `memory`, `skills`, `agents`, `commands`, `global`
 - `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/frontmatter.js` — frontmatter parser (normalizes CRLF line endings, fixed in v1.14.0)
 - `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, freebuff, copilot, antigravity)
+- `lib/adapters/` — registry + one adapter per runtime (opencode, claude, gemini, cline, freebuff, copilot, antigravity, qoder)
 - `skills/` — bundled skills · `agents/` — bundled sub-agents · `commands/` — bundled slash commands
+- `docs/superpowers/specs/` — design docs for releases and big changes
+
+## Troubleshooting
+
+**`Error: Config file not found: .../harness.config.json`**
+You are in a folder without a harness config. Run `reviewer-harness init` there first, or point at the right folder with `--target <dir>`.
+
+**`Skill "X" is enabled in the config but has no file in skills/`**
+The config enables a skill whose file is missing from the project's `skills/` folder. Fix it with `reviewer-harness skills add X` (re-installs the file), or remove it with `reviewer-harness skills remove X`.
+
+**`validate` reports a secret / sync refuses to run**
+A value in your config looks like an API key or token. Remove the secret from `harness.config.json` — secrets must never be synced into instruction files. Use your runtime's own secret storage instead.
+
+**`status` shows an old version after updating**
+Your shell or `npx` is serving a cached copy. Run `npx --yes reviewer-harness@latest status` once to refresh the cache, or reinstall globally with `npm install -g reviewer-harness@latest`.
+
+**Windows line endings (CRLF)**
+Skill files with Windows (`\r\n`) line endings used to lose their frontmatter on sync. Fixed in v1.14.0 — the parser normalizes line endings, so CRLF and LF files sync identically. No manual conversion needed anymore.
+
+**Sync changed nothing, but I edited the config**
+Check that you edited the config in the same folder you are syncing (`--target` defaults to the current directory), and that `validate` passes — sync refuses to run on a broken config.
 
 ## How it was built (the lessons)
 
@@ -253,6 +452,7 @@ Running from a source checkout instead? The same commands work as `node bin/cli.
 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
+8. ✅ v1.14.0 — the working peak: 22 skills (audit-team + ub-mode, design-taste-frontend, ui-ux-pro-max, vengeance-ui, brainstorming, writing-plans), Qoder as 8th runtime, system-design, nodejs-quality, all fix rounds verified WORKS, CRLF frontmatter fix (Windows sync without manual LF conversion)
 
 ## Contributing & Security
 

package/bin/cli.js

@@ -45,7 +45,7 @@ Usage (run inside your project):
   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 for ALL projects (OpenCode + Claude "/" menus; Freebuff, Copilot CLI, Antigravity skill bundles)
+  reviewer-harness global [--dry-run]       Install EVERY bundled skill for ALL projects (OpenCode + Claude "/" menus; Freebuff, Copilot CLI, Antigravity, Qoder skill bundles)
 
   reviewer-harness memory init              Start the local memory (memory/ folder)
   reviewer-harness memory index             Rebuild the memory INDEX.md + graph.json
@@ -232,6 +232,7 @@ function cmdGlobal() {
     { runtime: "Freebuff", dir: join(homedir(), ".agents", "skills"), bundle: true },
     { runtime: "Copilot CLI", dir: join(homedir(), ".copilot", "skills"), bundle: true },
     { runtime: "Antigravity", dir: join(homedir(), ".gemini", "config", "skills"), bundle: true },
+    { runtime: "Qoder", dir: join(homedir(), ".qoder", "skills"), bundle: true },
   ];
   if (dryRun) console.log("(dry-run: nothing was written)\n");
   for (const { runtime, dir, bundle } of targets) {
@@ -252,7 +253,7 @@ function cmdGlobal() {
   }
   console.log(
     `\nDone: ${skills.map((s) => "/" + s.name).join(", ")} are now available in EVERY project.` +
-      `\n(OpenCode + Claude: "/" menu commands. Freebuff, Copilot CLI, Antigravity: Agent Skills bundles.)` +
+      `\n(OpenCode + Claude: "/" menu commands. Freebuff, Copilot CLI, Antigravity, Qoder: Agent Skills bundles.)` +
       `\n(Per-project rules still come from "sync" inside a project.)`
   );
 }

package/lib/adapters/index.js

@@ -12,6 +12,7 @@ import * as cline from "./cline.js";
 import * as freebuff from "./freebuff.js";
 import * as copilot from "./copilot.js";
 import * as antigravity from "./antigravity.js";
+import * as qoder from "./qoder.js";
 
 export const adapters = {
   opencode,
@@ -21,6 +22,7 @@ export const adapters = {
   freebuff,
   copilot,
   antigravity,
+  qoder,
 };
 
 export const supportedRuntimes = Object.keys(adapters);

package/lib/adapters/qoder.js

@@ -0,0 +1,16 @@
+// lib/adapters/qoder.js — ADAPTER for Qoder (Alibaba's agentic coding CLI/IDE).
+//
+// Qoder follows the Agent Skills open standard (agentskills.io):
+// skills are folders containing a SKILL.md with `name` + `description`
+// frontmatter. Personal skills live at `~/.qoder/skills/<name>/SKILL.md`;
+// project skills live at `<project>/.qoder/skills/<name>/SKILL.md`.
+// This adapter covers the project side (used by `sync`); the personal
+// side is covered by the `global` command.
+//
+// Qoder has no single instruction file like CLAUDE.md, so this
+// adapter is skills-only: it exports skillBundleDir() instead of
+// targetFile()/renderInstructions().
+
+export function skillBundleDir() {
+  return ".qoder/skills";
+}