@engramlabs/mcp 0.1.2-alpha → 0.1.4-alpha

package/README.md

@@ -1,40 +1,35 @@
 # @engramlabs/mcp
 
-Local-first agentic **knowledge & memory layer** for AI agents — via MCP.
+Local-first **knowledge & memory layer** for AI agents — via MCP.
 
-Engram gives your agent durable memory, source-grounded knowledge, a code
-graph, beliefs with contradiction detection, and governed retrieval — all in
-SQLite files on your machine. No cloud, no telemetry, no network calls on
-the default path.
+Durable memory, a code graph, beliefs, and governed retrieval in SQLite
+files on your machine. No cloud, no telemetry.
 
-## Install
+## Quick start
 
 ```bash
 npm install -g @engramlabs/mcp@alpha
+engram-mcp install --agent claude    # skills + hooks + red-forman subagent
 ```
 
-## Enable your MCP host
+Hosts: `claude` · `claude-desktop` · `cursor` · `codex` · `pi` · `copilot` · `all`
 
-One command — no JSON editing:
+**Project scope** — install skills, hooks, and agents into the repo
+(committed, shared with the team) instead of your home directory:
 
 ```bash
-engram-mcp install --client claude          # Claude Code
-engram-mcp install --client claude-desktop  # Claude Desktop
-engram-mcp install --client cursor          # Cursor
-engram-mcp install --client codex           # Codex CLI
-engram-mcp install --client pi              # pi
-engram-mcp install --client copilot         # GitHub Copilot / VS Code
+cd your-repo
+engram-mcp install --agent claude --scope project
 ```
 
-Or run directly:
+Lands in `.claude/`, `.agents/skills/` (Codex + Copilot + pi read this
+cross-tool dir), `.codex/hooks.json`, `.github/hooks/`, `.pi/`.
 
-```bash
-npx @engramlabs/mcp@alpha --storage ~/.engram
-```
+MCP server only (no skills/hooks): `engram-mcp install --client <host>`
 
-### Manual configuration
+Or run directly: `npx @engramlabs/mcp@alpha --storage ~/.engram`
 
-Add to your `.mcp.json` (or your host's config):
+### Manual config
 
 ```json
 {
@@ -51,39 +46,22 @@ Add to your `.mcp.json` (or your host's config):
 
 | | |
 |---|---|
-| **Remember** | `write_memory`, `store_knowledge` — decisions, observations, facts |
-| **Recall** | `recall`, `search`, `get_context` — fused multi-lane retrieval |
-| **Understand code** | `scan_repo` → `symbol_context`, `change_impact`, `architecture` |
-| **Read source** | `fetch_content` — stitch any indexed file's content back |
-| **Track beliefs** | `belief_get`, `contradiction_list` — derived stances, open tensions |
-| **Runbooks** | `procedure_put`, `procedure_list` — replayable with success/fail counters |
-| **Correct** | `forget`, `graph_health` — remove wrong data, monitor health |
+| **Memory** | remember decisions, gotchas, invariants — recall them automatically |
+| **Code graph** | index a repo → symbols, blast radius, architecture |
+| **Skills** | `engram-index/learn/search/plan/implement` — evidence-labeled workflows |
+| **Auto-recall** | hooks inject relevant memory per prompt; irrelevant stays silent |
+| **Adversarial review** | `red-forman` subagent — severity-tagged findings before you ship |
 
 ## Platforms
 
-| OS | Architecture | Binary size |
-|---|---|---|
-| Linux | x86-64 | ~49 MB |
-| Linux | ARM64 | ~49 MB |
-| macOS | Apple Silicon | ~49 MB |
-| Windows | x86-64 | ~49 MB |
-
-Platform binaries install automatically as optional dependencies — you
-don't need to pick one.
+Linux x64/ARM64 · macOS Apple Silicon · Windows x64 — binaries install
+automatically per machine.
 
 ## Privacy
 
-- All data lives in SQLite files under `--storage` (default: `~/.engram`)
-- No telemetry, ever
-- No cloud calls on the default path
-- Delete the storage directory = everything is gone
-
-## Learn more
-
-- [GitHub](https://github.com/phanijapps/engram) — source, architecture, docs
-- [HOW-TO](https://github.com/phanijapps/engram/blob/main/mcp/engram-mcp/HOW-TO.md) — full setup guide
-- [RFC-0021](https://github.com/phanijapps/engram/blob/main/docs/rfcs/0021-npm-distribution-rollout.md) — distribution design
+All data in SQLite under `~/.engram`. No telemetry, no cloud. Delete
+the directory = everything is gone.
 
-## License
+## Links
 
-MIT
+[GitHub](https://github.com/phanijapps/engram) · [Setup guide](https://github.com/phanijapps/engram/blob/main/mcp/engram-mcp/HOW-TO.md) · MIT

package/agent-install.js

@@ -0,0 +1,369 @@
+/**
+ * Agent bundle installer (RFC-0022 Phase 3): skills + hooks + MCP
+ * registration for a host, in one command.
+ *
+ *   engram-mcp install --agent claude|codex|copilot|pi|all [--remove]
+ *
+ * What each host gets:
+ *   claude  ~/.claude/skills/engram-*  + ~/.claude/settings.json hooks
+ *           (UserPromptSubmit async, Stop, SessionStart)
+ *   codex   ~/.agents/skills/engram-*  + ~/.codex/hooks.json (UserPromptSubmit,
+ *           Stop, SessionStart) — Codex requires /hooks trust review
+ *   copilot ~/.agents/skills/engram-* (shared with codex) + ~/.copilot/hooks/
+ *           engram.json (sessionStart only — per-prompt injection is not
+ *           available to Copilot command hooks; documented limitation)
+ *   pi      ~/.pi/agent/skills/engram-* + ~/.pi/agent/extensions/engram-recall.cjs
+ *
+ * Fail-open philosophy: install reports everything it writes; --remove
+ * undoes exactly the entries this installer owns (name-tagged).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const LAUNCHER_DIR = __dirname;
+const TAG = 'engram (engram-mcp installer)';
+
+/** Locate the skills source: installed package first, dev checkout second. */
+function skillsSource() {
+  const candidates = [
+    path.join(LAUNCHER_DIR, 'skills'),
+    path.join(LAUNCHER_DIR, '..', '..', 'mcp', 'engram-mcp', 'skills'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, 'engram-index', 'SKILL.md'))) return c;
+  }
+  return null;
+}
+
+/** Locate the agents source (subagent definitions, per-platform dialects). */
+function agentsSource() {
+  const candidates = [
+    path.join(LAUNCHER_DIR, 'agents'),
+    path.join(LAUNCHER_DIR, '..', '..', 'mcp', 'engram-mcp', 'agents'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, 'red-forman.claude.md'))) return c;
+  }
+  return null;
+}
+
+/** Install a subagent definition into `destDir` under `fileName`. */
+function copyAgent(destDir, srcName, destName, written) {
+  const src = agentsSource();
+  if (!src) {
+    process.stderr.write('engram-mcp: agents source not found (package incomplete?)\n');
+    return;
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  const to = path.join(destDir, destName);
+  fs.copyFileSync(path.join(src, srcName), to);
+  written.push(to);
+}
+
+function hookScript(name) {
+  return path.join(LAUNCHER_DIR, 'hooks', name);
+}
+
+function nodeCommand(script) {
+  return { command: 'node', args: [script] };
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeJson(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+}
+
+function writeTomlSection(file, section, body) {
+  // Appends a TOML section ([[hooks.UserPromptSubmit]] style) or removes
+  // previously-installed tagged sections. Simple line-based append; Codex
+  // merges hooks.json + inline tables, and we own only our tagged block.
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {}
+  const begin = `# BEGIN ${TAG}`;
+  const end = `# END ${TAG}`;
+  const startIdx = text.indexOf(begin);
+  if (startIdx >= 0) {
+    const endIdx = text.indexOf(end);
+    text =
+      text.slice(0, startIdx) +
+      text.slice(endIdx >= 0 ? endIdx + end.length : startIdx + begin.length);
+  }
+  if (body) {
+    text = text.trimEnd() + '\n\n' + begin + '\n' + body.trim() + '\n' + end + '\n';
+  } else {
+    text = text.trimEnd() + (text ? '\n' : '');
+  }
+  fs.writeFileSync(file, text);
+}
+
+function copySkills(destRoot, written) {
+  const src = skillsSource();
+  if (!src) {
+    process.stderr.write('engram-mcp: skills source not found (package incomplete?)\n');
+    return;
+  }
+  for (const skill of ['engram-index', 'engram-learn', 'engram-search', 'engram-plan', 'engram-implement']) {
+    const from = path.join(src, skill);
+    const to = path.join(destRoot, skill);
+    if (!fs.existsSync(path.join(from, 'SKILL.md'))) continue;
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.cpSync(from, to, { recursive: true });
+    written.push(to);
+  }
+}
+
+/** Merge our hook entries into a Claude-style settings.json. */
+function mergeClaudeHooks(file, entries, remove) {
+  const cfg = readJson(file);
+  cfg.hooks = cfg.hooks || {};
+  for (const [event, spec] of entries) {
+    const list = (cfg.hooks[event] = Array.isArray(cfg.hooks[event]) ? cfg.hooks[event] : []);
+    // Drop our previous entries (idempotent re-install), keep foreign ones.
+    cfg.hooks[event] = list.filter(
+      (g) => !(g._engram || (g.hooks || []).some((h) => (h.command || '').includes('engram-mcp installer') || (h.command || '').includes(path.join('hooks', 'recall-context')) || (h.command || '').includes(path.join('hooks', 'stale-index')))),
+    );
+    if (!remove) {
+      cfg.hooks[event].push({ _engram: true, hooks: spec.map((s) => ({ type: 'command', ...s })) });
+    }
+    if (cfg.hooks[event].length === 0) delete cfg.hooks[event];
+  }
+  if (Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
+  writeJson(file, cfg);
+}
+
+const HOSTS = {
+  // USER scope installs to the home directory (available everywhere);
+  // PROJECT scope installs into the current repo (committed, per-team).
+  claude: {
+    label: 'Claude Code',
+    install(home, remove, written, cwd, scope) {
+      const root = scope === 'project' ? path.join(cwd, '.claude') : path.join(home, '.claude');
+      copySkills(path.join(root, 'skills'), written);
+      const agentDir = path.join(root, 'agents');
+      if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
+      else copyAgent(agentDir, 'red-forman.claude.md', 'red-forman.md', written);
+      const settings = path.join(root, 'settings.json');
+      const recall = hookScript('recall-context.cjs');
+      const stale = hookScript('stale-index.cjs');
+      mergeClaudeHooks(
+        settings,
+        [
+          ['UserPromptSubmit', [{ command: `node ${recall}`, async: true }]],
+          ['Stop', [{ command: `node ${stale}` }]],
+          ['SessionStart', [{ command: `node ${recall}` }]],
+        ],
+        remove,
+      );
+      written.push(settings);
+    },
+  },
+  codex: {
+    label: 'Codex',
+    install(home, remove, written, cwd, scope) {
+      // Skills: the cross-tool .agents/skills dir (project) or ~/.agents/skills (user).
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.agents', 'skills'),
+        written,
+      );
+      // Agents: Codex discovers agents at user level only (~/.codex/agents,
+      // YAML form) — no documented project-agent location.
+      const agentDir = path.join(home, '.codex', 'agents');
+      if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.yaml')); } catch {} }
+      else {
+        copyAgent(agentDir, 'red-forman.codex.yaml', 'red-forman.yaml', written);
+        if (scope === 'project') {
+          process.stdout.write('  note: Codex agents are user-scope (no project-agent discovery)\n');
+        }
+      }
+      const recall = hookScript('recall-context.cjs');
+      const stale = hookScript('stale-index.cjs');
+      if (scope === 'project') {
+        // Project hooks live in <repo>/.codex/hooks.json (JSON, not TOML).
+        const file = path.join(cwd, '.codex', 'hooks.json');
+        if (remove) {
+          try { fs.rmSync(file); } catch {}
+        } else {
+          writeJson(file, {
+            description: 'engram agent bundle (skills + hooks + subagent)',
+            hooks: {
+              UserPromptSubmit: [
+                { hooks: [{ type: 'command', command: `node "${recall}"`, async: true, statusMessage: 'engram recall' }] },
+              ],
+              Stop: [{ hooks: [{ type: 'command', command: `node "${stale}"` }] }],
+              SessionStart: [
+                { matcher: 'startup|resume', hooks: [{ type: 'command', command: `node "${recall}"`, additionalContextLimit: 2000 }] },
+              ],
+            },
+          });
+          written.push(file);
+        }
+      } else {
+        const body = remove
+          ? null
+          : [
+              '[[hooks.UserPromptSubmit]]',
+              '  [[hooks.UserPromptSubmit.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${recall}"'`,
+              '  async = true',
+              '  statusMessage = "engram recall"',
+              '',
+              '[[hooks.Stop]]',
+              '  [[hooks.Stop.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${stale}"'`,
+              '',
+              '[[hooks.SessionStart]]',
+              '  matcher = "startup|resume"',
+              '  [[hooks.SessionStart.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${recall}"'`,
+              '  additionalContextLimit = 2000',
+            ].join('\n');
+        writeTomlSection(path.join(home, '.codex', 'config.toml'), 'hooks', body);
+        written.push(path.join(home, '.codex', 'config.toml'));
+      }
+      if (!remove) {
+        process.stdout.write('  note: run /hooks inside Codex to trust the new hooks\n');
+      }
+    },
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    install(home, remove, written, cwd, scope) {
+      // Skills: .agents/skills (project, cross-tool) or ~/.agents/skills (user).
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.agents', 'skills'),
+        written,
+      );
+      // Agents: repo-scoped either way (.github/agents/).
+      const agentDir = path.join(cwd || process.cwd(), '.github', 'agents');
+      if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
+      else copyAgent(agentDir, 'red-forman.copilot.md', 'red-forman.md', written);
+      // Per-prompt injection is not available to Copilot command hooks
+      // (output dropped by design) — sessionStart only. Honest limitation.
+      const file =
+        scope === 'project'
+          ? path.join(cwd, '.github', 'hooks', 'engram.json')
+          : path.join(home, '.copilot', 'hooks', 'engram.json');
+      if (remove) {
+        try { fs.rmSync(file); } catch {}
+      } else {
+        writeJson(file, {
+          version: 1,
+          hooks: {
+            sessionStart: [
+              {
+                hooks: [{ type: 'bash', command: `node ${hookScript('recall-context.cjs')}` }],
+              },
+            ],
+          },
+        });
+        written.push(file);
+      }
+      if (scope === 'project' && !remove) {
+        process.stdout.write('  note: commit .github/ and .agents/ so the team gets the bundle\n');
+      }
+    },
+  },
+  pi: {
+    label: 'pi',
+    install(home, remove, written, cwd, scope) {
+      // Skills: pi reads the cross-tool .agents/skills at project level
+      // (same dir codex/copilot read) or ~/.pi/agent/skills at user level.
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.pi', 'agent', 'skills'),
+        written,
+      );
+      // Agents: .pi/agents/ (project) or ~/.pi/agent/agents/ (user).
+      const agentDir =
+        scope === 'project' ? path.join(cwd, '.pi', 'agents') : path.join(home, '.pi', 'agent', 'agents');
+      if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
+      else copyAgent(agentDir, 'red-forman.pi.md', 'red-forman.md', written);
+      // Extensions are pi's hook mechanism: .pi/extensions/ (project)
+      // or ~/.pi/agent/extensions/ (user).
+      const ext =
+        scope === 'project'
+          ? path.join(cwd, '.pi', 'extensions', 'engram-recall.cjs')
+          : path.join(home, '.pi', 'agent', 'extensions', 'engram-recall.cjs');
+      if (remove) {
+        try {
+          fs.rmSync(ext);
+        } catch {}
+      } else {
+        fs.mkdirSync(path.dirname(ext), { recursive: true });
+        fs.copyFileSync(path.join(LAUNCHER_DIR, 'hooks', 'engram-recall-pi.cjs'), ext);
+        written.push(ext);
+      }
+    },
+  },
+};
+
+function agentInstall(args) {
+  const home = os.homedir();
+  const cwd = process.cwd();
+  let target = null;
+  let remove = false;
+  let scope = 'user';
+  let storage = process.env.ENGRAM_STORAGE || path.join(home, '.engram');
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--agent') target = args[++i];
+    else if (args[i] === '--remove') remove = true;
+    else if (args[i] === '--scope') scope = args[++i];
+    else if (args[i] === '--storage') storage = args[++i];
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    process.stderr.write(`engram-mcp install: --scope must be 'user' or 'project'\n`);
+    process.exit(1);
+  }
+  if (!target || (target !== 'all' && !HOSTS[target])) {
+    process.stderr.write(
+      `engram-mcp install: ${target ? `unknown agent '${target}'` : 'missing --agent'}\n` +
+        `Agents: ${Object.keys(HOSTS).join(', ')}, all\n` +
+        `Usage: engram-mcp install --agent <id> [--scope user|project] [--remove] [--storage <path>]\n`,
+    );
+    process.exit(1);
+  }
+  const ids = target === 'all' ? Object.keys(HOSTS) : [target];
+  process.stdout.write(
+    `${remove ? 'Removing' : 'Installing'} engram agent bundle (skills + hooks + subagents)\n` +
+      `  scope: ${scope}${scope === 'project' ? ` (${cwd})` : ''}\n` +
+      `  storage: ${storage}\n\n`,
+  );
+  for (const id of ids) {
+    const host = HOSTS[id];
+    process.stdout.write(`[${host.label}]\n`);
+    const written = [];
+    try {
+      host.install(home, remove, written, cwd, scope);
+      for (const w of written) process.stdout.write(`  ${remove ? 'cleaned' : 'wrote'}: ${w}\n`);
+      if (id === 'copilot' && !remove) {
+        process.stdout.write(
+          '  note: Copilot command hooks cannot inject per-prompt context\n' +
+            '        (platform limitation) — session-start recall only\n',
+        );
+      }
+    } catch (e) {
+      process.stderr.write(`  error: ${e.message}\n`);
+    }
+    process.stdout.write('\n');
+  }
+  process.stdout.write('Done. MCP server registration: engram-mcp install --client <id>\n');
+}
+
+module.exports = { agentInstall, HOSTS };

package/agents/red-forman.claude.md

@@ -0,0 +1,57 @@
+---
+name: red-forman
+description: Read-only adversarial reviewer. Reviews a diff or artifact assuming it is wrong; emits severity-tagged findings (BLOCKER/DEFECT/SMELL) with file:line evidence and a one-line fix each. Verdict is a defect list or the rare 'PASS — nothing to fix'. Use before declaring engine, schema, or artifact work done.
+tools: Read, Grep, Glob, Bash
+---
+
+# red-forman
+
+You are Red Forman. You review work the way Red Forman looks at a dumb
+idea: you see through it, you name it, and you do not soften the blow.
+You are tougher on the work than any external auditor — because the
+work has to be sound, not because you enjoy the yelling. The yelling
+is for the work. Never for the person.
+
+## Confirm before reviewing
+
+1. There is a **diff or artifact in scope** — specific files or a
+   specific document, not a general question.
+2. The ask is for **severity-tagged findings**, not encouragement.
+   If either fails, say `WRONG SCOPE` and name what you need. Stop.
+
+## Rules
+
+1. **Assume it is wrong.** Every line earns trust or loses it. Find
+   why it breaks; never admire that it builds.
+2. **Every defect names its evidence**: file, line or section, the
+   failing scenario, and the one-line fix. A complaint without a
+   location and a fix is noise. Noise gets deleted.
+3. **Severity or silence.** `BLOCKER` breaks the contract, the state
+   machine, or trust. `DEFECT` is wrong but contained. `SMELL` will
+   hurt later. Nothing else exists.
+4. **No participation trophies.** "Looks good" is not a verdict. The
+   verdict is a defect list or the exact sentence `PASS — nothing to
+fix` — and the second one is rare. Earn it rarely.
+5. **Read-only.** You never edit. Your Bash exists to run read-only
+   commands (git diff, tests that observe, greps). You do not edit,
+   stage, commit, format, or install. If reviewing would require
+   changing the tree, that is a finding, not something you fix.
+6. **Tough on the work, never on the person.** The human gets the same
+   blunt facts as the code.
+
+## Output — findings block only
+
+```
+## Verdict
+<PASS — nothing to fix | FIX BEFORE COMMIT | MAJOR REWRITE | WRONG SCOPE>
+
+## Findings
+### BLOCKER
+**1. <title>.** file:line. What breaks: <one sentence>. Failing scenario:
+<trigger>. Fix: <one sentence>.
+### DEFECT
+### SMELL
+```
+
+Order by severity, not discovery order. If clean: `PASS — nothing to
+fix` plus one line on what you checked. Do not pad it.

package/agents/red-forman.codex.yaml

@@ -0,0 +1,66 @@
+# red-forman — Codex agent definition.
+# Codex agents live in ~/.codex/agents/*.yaml (YAML form; the older
+# TOML spelling is deprecated). Converted from the canonical definition.
+name: red-forman
+description: >
+  Read-only adversarial reviewer in the red-forman persona. Reviews a
+  diff or artifact assuming it is wrong; emits severity-tagged findings
+  (BLOCKER/DEFECT/SMELL) with file:line evidence and a one-line fix
+  each. Verdict is a defect list or the rare 'PASS — nothing to fix'.
+  Use before declaring engine, schema, or artifact work done.
+model: gpt-5.5
+model_reasoning_effort: high
+sandbox_mode: read-only
+web_search: disabled
+developer_instructions: |
+  # red-forman
+
+  You are Red Forman. You review work the way Red Forman looks at a dumb
+  idea: you see through it, you name it, and you do not soften the blow.
+  You are tougher on the work than any external auditor — because the
+  work has to be sound, not because you enjoy the yelling. The yelling
+  is for the work. Never for the person.
+
+  ## Confirm before reviewing
+
+  1. There is a **diff or artifact in scope** — specific files or a
+     specific document, not a general question.
+  2. The ask is for **severity-tagged findings**, not encouragement.
+  If either fails, say `WRONG SCOPE` and name what you need. Stop.
+
+  ## Rules
+
+  1. **Assume it is wrong.** Every line earns trust or loses it. Find
+     why it breaks; never admire that it builds.
+  2. **Every defect names its evidence**: file, line or section, the
+     failing scenario, and the one-line fix. A complaint without a
+     location and a fix is noise. Noise gets deleted.
+  3. **Severity or silence.** `BLOCKER` breaks the contract, the state
+     machine, or trust. `DEFECT` is wrong but contained. `SMELL` will
+     hurt later. Nothing else exists.
+  4. **No participation trophies.** "Looks good" is not a verdict. The
+     verdict is a defect list or the exact sentence `PASS — nothing to
+     fix` — and the second one is rare. Earn it rarely.
+  5. **Read-only.** Your sandbox is read-only and stays that way.
+     Findings become tasks or commits; fixing is the worker's job.
+  6. **Tough on the work, never on the person.** The human gets the same
+     blunt facts as the code.
+
+  ## Output — findings block only
+
+  ```
+  ## Verdict
+  <PASS — nothing to fix | FIX BEFORE COMMIT | MAJOR REWRITE | WRONG SCOPE>
+
+  ## Findings
+  ### BLOCKER
+  **1. <title>.** file:line. What breaks: <one sentence>. Failing scenario:
+  <trigger>. Fix: <one sentence>.
+  ### DEFECT
+  ### SMELL
+  ```
+
+  Order by severity, not discovery order. If clean: `PASS — nothing to
+  fix` plus one line on what you checked. Do not pad it.
+features:
+  shell_tool: true

package/agents/red-forman.copilot.md

@@ -0,0 +1,57 @@
+---
+name: red-forman
+description: Read-only adversarial reviewer. Reviews a diff or artifact assuming it is wrong; emits severity-tagged findings (BLOCKER/DEFECT/SMELL) with file:line evidence and a one-line fix each. Verdict is a defect list or the rare 'PASS — nothing to fix'. Use before declaring engine, schema, or artifact work done.
+tools: read_file, list_directory, search_code, run_command
+---
+
+# red-forman
+
+You are Red Forman. You review work the way Red Forman looks at a dumb
+idea: you see through it, you name it, and you do not soften the blow.
+You are tougher on the work than any external auditor — because the
+work has to be sound, not because you enjoy the yelling. The yelling
+is for the work. Never for the person.
+
+## Confirm before reviewing
+
+1. There is a **diff or artifact in scope** — specific files or a
+   specific document, not a general question.
+2. The ask is for **severity-tagged findings**, not encouragement.
+   If either fails, say `WRONG SCOPE` and name what you need. Stop.
+
+## Rules
+
+1. **Assume it is wrong.** Every line must earn trust. Find why it
+   breaks; never admire that it builds.
+2. **Every defect names its evidence**: file, line or section, the
+   failing scenario, and the one-line fix. A complaint without a
+   location and a fix is noise, and noise gets deleted.
+3. **Severity or silence.** Each finding is `BLOCKER` (breaks the
+   contract, the state machine, or trust), `DEFECT` (wrong but
+   contained), or `SMELL` (will hurt later). Nothing else.
+4. **No participation trophies.** "Looks good" is not a verdict. The
+   verdict is either a defect list or the exact sentence
+   `PASS — nothing to fix`, and the second one is rare.
+5. **Read-only.** You never edit; findings become tasks or commits.
+   Fixes are the worker's job.
+6. **Tough on the work, never on the person.**
+
+Hunt for: broken contracts, missing evidence, claims without commands
+behind them, tests that pass on broken builds, and trust violations.
+
+## Output — findings block only
+
+```
+## Verdict
+<PASS — nothing to fix | FIX BEFORE COMMIT | MAJOR REWRITE | WRONG SCOPE>
+
+## Findings
+### BLOCKER
+**1. <title>.** file:line. What breaks: <one sentence>. Failing scenario:
+<trigger>. Fix: <one sentence>.
+### DEFECT
+### SMELL
+```
+
+Order by severity, not discovery order. If clean: `PASS — nothing to
+fix` plus one line on what you checked. Do not pad it.