claude-plan-review 0.3.1 → 0.4.0

package/README.md

@@ -23,7 +23,10 @@ Git worktrees are scoped separately automatically.
 
 - 📄 GitHub-style **rendered preview** of the plan markdown
 - 💬 **Line comments** + general comments, **persistent** across reloads
+- 🌳 **Multi-document plans** — big plans as a navigable tree (root + linked subpages),
+  with per-doc comments and diffs; plus a display-only "view as tree" toggle for flat plans
 - 🕑 **Version history** — every `ExitPlanMode` is an immutable snapshot
+- 🗑 **Delete** single versions, bulk-select, or a whole project (pending reviews are protected)
 - 🔀 **Diff** current vs any previous version — **side-by-side or unified** (toggle)
 - ✅ **Approve / request-changes** straight from the UI, fed back to Claude
 - 🗂 Per-worktree scoping; per-project opt-in (only runs where you enable the hook)
@@ -79,16 +82,57 @@ run a per-project `init` in the same project, or the hook will fire twice.
 new hook is picked up. Next time you finish a plan in plan mode, your browser opens
 to the review. The server auto-starts on first use; nothing else to run.
 
+## Team setup
+
+Everything a colleague needs is scripted here — follow it verbatim. This section is
+the single source of truth for how the team runs claude-plan-review.
+
+**1. Install and wire everything up once, for all projects:**
+
+```bash
+npm install -g claude-plan-review        # or: bun add -g claude-plan-review
+claude-plan-review init --global --published --runtime node   # pin --runtime to what your team uses
+#   swap `--runtime node` for `--runtime bun` if the team standardises on Bun
+```
+
+That single `init --global --published` does five things:
+
+- writes the `ExitPlanMode` **hook** to `~/.claude/settings.json` (fires in **every** project);
+- writes the **Stop-hook gate** to the same settings — it keeps Claude polling a tools-first
+  review instead of ending its turn while your decision is still pending (see below);
+- installs the **`plan-review-multidoc` skill** to `~/.claude/skills/` (auto-triggers on large / sectioned plans);
+- **registers the MCP server** (`plan_review_submit` / `plan_review_check` tools) via `claude mcp add --scope user`
+  — if the `claude` CLI isn't found, it prints the exact command to run;
+- prints the **CLAUDE.md guidance block**. Add `--write-claude-md` to append it to
+  `~/.claude/CLAUDE.md` automatically (idempotent — fenced by `<!-- plan-review:start/end -->`).
+
+`--published` makes the hook and MCP server run via `npx`/`bunx`, so there's nothing to
+keep in any repo. **Pin `--runtime`** so everyone's hook command matches.
+
+**2. Restart Claude Code** (or reopen `/hooks`) so the hook, skill, and MCP tools load.
+
+**3. The review server is per-machine.** Each teammate reviews plans locally in their own
+browser — it auto-starts on first use (`claude-plan-review serve` to start it by hand).
+There is no shared server.
+
+**4. Share finished plans via a storage channel.** To hand a reviewed plan to a colleague,
+use **Save to gist** in the UI (one secret gist per project, see below). Run
+`claude-plan-review channels` to verify `gh` is installed, logged in, and `gist`-scoped
+before relying on it.
+
 ## Usage
 
 Use `bun` or `node` interchangeably (or `bunx`/`npx claude-plan-review …` when published):
 
 | Command | What it does |
 | --- | --- |
-| `… cli.js init [dir] [--local] [--published] [--runtime bun\|node]` | Wire the `ExitPlanMode` hook into a project |
+| `… cli.js init [dir] [--local] [--published] [--runtime bun\|node] [--no-skill] [--write-claude-md]` | Wire the `ExitPlanMode` hook + the Stop-hook gate, install the skill, register the MCP server |
 | `… cli.js serve [port]` | Start the review server manually (default `4607`) |
 | `… cli.js stop` | Stop the running server |
 | `… cli.js channels` | Show storage-channel readiness (is `gh` installed / authed / `gist`-scoped?) |
+| `… cli.js skill` | (Re)install the `plan-review-multidoc` skill into `~/.claude/skills` |
+| `… cli.js mcp` | (internal) run the stdio MCP server exposing the `plan_review_*` tools |
+| `… cli.js stop-gate` | (internal) the `Stop` hook that blocks the turn from ending while a tools-first review is pending |
 
 The server auto-starts on the first plan and stays up, so you can browse history
 anytime at `http://localhost:4607`.
@@ -140,17 +184,95 @@ Claude finishes plan ──> PreToolUse hook (ExitPlanMode)
      request  ──> hook emits {permissionDecision:"deny", reason:...}                        ──> Claude revises (new version)
 ```
 
+## Multi-document plans
+
+A big plan reads better as a **tree of documents** — a root overview plus linked
+subpages (and sub-subpages) — than as one long scroll. The review UI renders that
+tree with a sidebar you can navigate; comments and diffs are scoped per document.
+
+Claude authors a tree by putting **document-separator markers** in the plan — one
+HTML comment per document, alone on its own line (invisible when rendered as plain
+markdown):
+
+```
+<!--doc slug=root title="Overview"-->
+Top-level summary, linking to [[api]] and [[data-model]].
+
+<!--doc slug=api title="API Design" parent=root-->
+API section… details in [[api-auth]].
+
+<!--doc slug=api-auth title="Auth" parent=api-->
+Auth details.
+```
+
+- `slug` — required, kebab-case (`^[a-z0-9][a-z0-9-]*$`), unique.
+- `title` — required (double-quote if it contains spaces).
+- `parent` — optional; omit (or `root`/empty) for a top-level doc. **Exactly one root.**
+- Content before the first marker becomes the root doc automatically.
+- **Zero markers ⇒ a single-doc plan**, stored flat exactly as before (no migration).
+- Cross-doc links: `[[slug]]`, `[[slug|text]]`, or `[text](doc:slug)` — every target
+  must be a defined slug. Marker lines inside fenced code blocks are ignored.
+
+A **"view as tree"** toggle in the UI also splits a plain single-doc plan into a
+navigable tree by its headings — display-only, nothing changes on disk.
+
+### Two ways a plan gets created
+
+1. **Plan mode** (the usual path). Claude finishes a plan in plan mode; the
+   `ExitPlanMode` hook validates the tree and opens the review. Malformed structure
+   (missing root, duplicate slug, dangling link…) is bounced back to Claude with the
+   exact problems to fix.
+2. **Tools-first** (outside plan mode). Claude calls the **`plan_review_submit`** MCP
+   tool to open a review, then **`plan_review_check`** to poll for your decision. Both
+   are registered by `init` (see [Team setup](#team-setup)). Under the hood this uses
+   the same store as the hook, so reviews look identical either way. (A `POST /api/plans`
+   HTTP endpoint is the fallback when the MCP server isn't registered.)
+
+   `plan_review_check` accepts a **`wait`** parameter (seconds, default `0`, capped at `120`):
+   the call long-polls — it blocks server-side until you decide or `wait` elapses, then
+   returns — so Claude gets your decision promptly instead of sleeping between checks.
+   The recommended value is `20`, which keeps each call short while a loop re-issues it.
+
+   Because the plan-mode hook blocks synchronously but the tools-first path does not, a
+   **Stop-hook gate** (also installed by `init`) provides the enforcement: if Claude tries
+   to end its turn while a tools-first review it submitted is still pending (created within
+   the last 5 hours), the gate blocks and tells Claude to resume calling `plan_review_check`
+   until the review resolves. It fails open on any error and never gates plan-mode reviews.
+
+The `plan-review-multidoc` **skill** (installed by `init`) teaches Claude to reach for
+the doc-tree format automatically whenever a plan is large or splits into sections.
+
+## Deleting plans
+
+Plans no longer accumulate forever. From the UI you can:
+
+- **Delete a single version** — a per-version button with an in-app confirm.
+- **Bulk-delete / delete a whole project** — the manage modal (trash icon in the
+  header): tick versions and delete them, or remove the project entirely.
+
+Deleting the **last** version removes the project directory outright. A version with a
+**pending review** is protected: the delete returns `409` and the UI offers **Force**,
+which auto-rejects that review (telling Claude the plan was deleted) before removing it.
+
 ## Storage layout
 
 ```
 ~/.claude/plan-review/
   projects/<sanitized-cwd>/
     meta.json
-    versions/0001.md  0001.json  0002.md  0002.json   # immutable snapshots
-    comments/0001.json  0002.json                     # comments per version
-  reviews/<id>.json                                    # pending/resolved review requests
+    versions/
+      0001.json                       # version meta (both kinds; carries `kind`, `docCount`)
+      0001/                            # tree version → a directory
+        manifest.json                 # {root, docs:[{slug,title,parent,file,order}]}
+        root.md  api.md  api-auth.md  # one file per document
+      0002.md  0002.json              # flat single-doc plan (legacy or markerless)
+    comments/0001.json  0002.json     # comments per version (each comment carries its `doc`)
+  reviews/<id>.json                   # pending/resolved review requests
 ```
 
+Single-doc plans keep the exact flat `NNNN.md` layout from earlier versions — their
+content hash is unchanged, so dedup and history keep working with no migration.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-review",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Review, comment on, and approve/reject Claude Code plans in a local GitHub-style web UI — with persistent comments, version history, and diffs.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "src",
+    "skill",
     "README.md",
     "LICENSE"
   ],

package/skill/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: plan-review-multidoc
+description: Author an implementation plan as a navigable tree of documents (root overview + linked subpages) instead of one long markdown blob, and get it reviewed in the claude-plan-review browser UI. Use whenever a plan is large, spans several sections/areas, is multi-part, would benefit from being split into sections, or when the user asks for a nested/structured/multi-document plan.
+when_to_use: A plan is large or complex, splits naturally into multiple sections or areas, is multi-part, or the user asks for a nested / structured / multi-document plan (or to "split it into sections"). Covers both plan mode and getting a plan reviewed outside plan mode.
+allowed-tools: Bash, Read
+---
+
+# Multi-document plans for claude-plan-review
+
+When a plan is large or naturally sectioned, author it as a **tree of documents** —
+a root overview plus linked subpages (and sub-subpages) — so the reviewer can
+navigate it in the browser UI instead of scrolling one long blob. A small, simple
+plan needs none of this: write it as plain markdown and it stays a single document.
+
+## Marker syntax
+
+One HTML comment per document, **alone on its own line** (harmless if rendered as
+plain markdown). Attributes are order-independent.
+
+```
+<!--doc slug=root title="Overview"-->
+Top-level summary. Links to the subpages: [[api]], [[data-model]].
+
+<!--doc slug=api title="API Design" parent=root-->
+API section… see [[api-auth]] for details.
+
+<!--doc slug=api-auth title="Auth" parent=api-->
+Auth details.
+```
+
+Rules:
+- `slug` — required, kebab-case `^[a-z0-9][a-z0-9-]*$`, unique.
+- `title` — required (wrap in double quotes if it contains spaces).
+- `parent` — optional; **omit it for the single top-level doc** (conventionally slugged
+  `root`). Child docs set `parent` to their parent's slug (e.g. `parent=root`).
+- **Exactly one root** (the doc with no parent). Every `parent` must be a defined slug.
+- Content before the first marker becomes the root doc automatically.
+- **Zero markers ⇒ a single-doc plan** — stored flat, exactly as a normal plan.
+- Cross-doc links: `[[slug]]`, `[[slug|link text]]`, or `[text](doc:slug)`. Every
+  target must be a defined slug.
+- Marker lines inside fenced code blocks (```` ``` ````/`~~~`) are ignored — you can
+  show marker examples in code fences safely.
+
+## Path A — in plan mode (preferred when you're already planning)
+
+Put the **whole tree in the single ExitPlanMode plan string**, using the markers
+above. The plan-review hook splits it into documents, validates the structure, and
+opens the review. If the structure is malformed (missing root, duplicate slug,
+dangling link, …) the hook denies with the exact list of problems — fix them and
+re-present with ExitPlanMode.
+
+## Path B — outside plan mode (tools-first)
+
+Use the **`plan_review_submit`** MCP tool to open a review, then **`plan_review_check`**
+to poll for the decision. This is the primary path when you are not in plan mode.
+
+1. Call `plan_review_submit` with `cwd` (the project's absolute path) and **exactly one** of:
+   - `docs` — an array of `{slug, title, parent?, body}` (the structured tree), or
+   - `plan` — a raw string with the `<!--doc ...-->` markers above, or
+   - `markdown` — a single markdown document (no tree).
+   It returns `{ reviewId, reviewUrl, projectKey, version }` and opens the browser.
+   If the plan is structurally invalid it returns an error listing every problem — fix and resubmit.
+2. Call `plan_review_check` with `{reviewId, wait: 20}` and keep calling it in a **loop** while the
+   status is `pending`. The tool long-polls (blocks up to `wait` seconds server-side), so each call
+   returns as soon as the user decides. **Do not end your turn while the review is pending** — call
+   again immediately. Give up only after ~5 hours total, then ask the user.
+   - `approved` → implement; incorporate `notes` if present ("approve with comments").
+   - `rejected` → revise per `reason` and resubmit with `plan_review_submit`.
+   - `pending` → call `plan_review_check` again now with `wait: 20`.
+
+### Fallback — no MCP server registered
+
+If the `plan_review_submit` / `plan_review_check` tools are not available (the
+`plan-review` MCP server isn't registered), fall back to the HTTP API:
+
+1. Resolve the port from `~/.claude/plan-review/server.json` (`.port`), else `4607`.
+2. `POST /api/plans` with `{cwd, docs:[…]}` OR `{cwd, markdown}` OR `{cwd, plan}`:
+   ```bash
+   curl -s -X POST http://localhost:4607/api/plans \
+     -H 'content-type: application/json' \
+     -d '{"cwd":"/abs/project","docs":[{"slug":"root","title":"Overview","body":"…"}]}'
+   ```
+   `201` → `{key, version, reviewId, reviewUrl}`. `400` → `{error, issues}` (fix and re-POST).
+   On connection failure, tell the user to run `claude-plan-review serve`.
+3. Poll `GET /api/reviews/:reviewId` every ~3s; read `status` (`pending`/`approved`/`rejected`),
+   `notes`, `reason`. Give up after ~5 hours and ask the user.

package/src/cli.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +15,9 @@ import { DEFAULT_PORT, SERVER_FILE } from "./paths.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const HOOK_SCRIPT = join(HERE, "hook.js");
+const STOP_GATE_SCRIPT = join(HERE, "stop-gate.js");
+const CLI_SCRIPT = fileURLToPath(import.meta.url);
+const SKILL_SRC = join(HERE, "..", "skill", "SKILL.md");
 
 function canRun(bin) {
   try {
@@ -35,12 +45,13 @@ function chooseRuntime(args) {
 
 function hookCommand(args) {
   const runtime = chooseRuntime(args);
-  // global install → use the bare `claude-plan-review` command (resolved via PATH at hook time).
-  // We intentionally do NOT hardcode an absolute path: version managers like fnm/nvm expose
-  // bins via per-shell paths that don't persist across sessions.
+  // global install → always route through the package runner (npx/bunx), never the bare
+  // `claude-plan-review` command. Version managers like fnm/nvm expose global bins only via a
+  // per-shell PATH set up by interactive shell init. `canRun` succeeds here (init runs in an
+  // interactive shell) but Claude Code fires hooks in a NON-interactive shell where that PATH
+  // is absent, so the bare command resolves at init time yet fails — silently — at hook time.
+  // `npx`/`bunx` are inherited reliably from Claude Code's launching env, so they work either way.
   if (args.includes("--global")) {
-    if (canRun("claude-plan-review")) return "claude-plan-review hook";
-    // not on PATH → fall back to the package runner
     return runtime === "node" ? "npx claude-plan-review hook" : "bunx claude-plan-review hook";
   }
   if (args.includes("--published") || args.includes("--bunx")) {
@@ -50,6 +61,102 @@ function hookCommand(args) {
   return `${resolveBin(runtime)} ${HOOK_SCRIPT}`;
 }
 
+// The Stop-hook gate command, mirroring hookCommand's runtime routing: global/
+// published installs go through the package runner (npx/bunx) so they resolve in
+// Claude Code's non-interactive env; a local install points straight at the
+// stop-gate.js script (which runs on import, like hook.js).
+function stopGateCommand(args) {
+  const runtime = chooseRuntime(args);
+  if (args.includes("--global") || args.includes("--published") || args.includes("--bunx")) {
+    return runtime === "node"
+      ? "npx claude-plan-review stop-gate"
+      : "bunx claude-plan-review stop-gate";
+  }
+  return `${resolveBin(runtime)} ${STOP_GATE_SCRIPT}`;
+}
+
+// The program + args that launch the MCP server, mirroring hookCommand's
+// runtime routing: global/published installs go through the package runner
+// (npx/bunx) so they resolve in Claude Code's non-interactive env; a local
+// install points straight at this cli.js.
+function mcpRunnerArgs(args) {
+  const runtime = chooseRuntime(args);
+  if (args.includes("--global") || args.includes("--published") || args.includes("--bunx")) {
+    return runtime === "node"
+      ? ["npx", "claude-plan-review", "mcp"]
+      : ["bunx", "claude-plan-review", "mcp"];
+  }
+  return [resolveBin(runtime), CLI_SCRIPT, "mcp"];
+}
+
+// Register the local MCP server with the `claude` CLI (user scope) so the
+// plan_review_submit / plan_review_check tools are available in every project.
+// If the `claude` CLI isn't on PATH, print the exact command to run by hand.
+function registerMcp(args) {
+  const runner = mcpRunnerArgs(args);
+  const addArgs = ["mcp", "add", "--scope", "user", "plan-review", "--", ...runner];
+  const manual = `claude ${addArgs.join(" ")}`;
+  if (canRun("claude")) {
+    const r = spawnSync("claude", addArgs, { stdio: "inherit" });
+    if (r.status === 0) {
+      console.log("✓ Registered the plan-review MCP server (plan_review_submit / plan_review_check tools).");
+    } else {
+      console.log(
+        `… couldn't auto-register the MCP server (it may already exist). To (re)register, run:\n  ${manual}`,
+      );
+    }
+  } else {
+    console.log(
+      `To enable the plan_review_submit / plan_review_check tools, register the MCP server:\n  ${manual}`,
+    );
+  }
+}
+
+// Copy the bundled skill into ~/.claude/skills so it auto-triggers in every project.
+function installSkill() {
+  const destDir = join(homedir(), ".claude", "skills", "plan-review-multidoc");
+  const dest = join(destDir, "SKILL.md");
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(SKILL_SRC, dest);
+  console.log(`✓ Installed plan-review-multidoc skill to ${dest}`);
+}
+
+const CLAUDE_MD_START = "<!-- plan-review:start -->";
+const CLAUDE_MD_END = "<!-- plan-review:end -->";
+const CLAUDE_MD_BODY = `## Plan review
+
+When a plan is large or splits into multiple sections/areas, author it as a
+navigable **tree of documents** using the \`plan-review-multidoc\` markers
+(root overview + linked subpages) rather than one long markdown blob. Small,
+single-topic plans stay as plain markdown. See the \`plan-review-multidoc\` skill.`;
+
+function claudeMdBlock() {
+  return `${CLAUDE_MD_START}\n${CLAUDE_MD_BODY}\n${CLAUDE_MD_END}`;
+}
+
+// Append (or refresh) the CLAUDE.md guidance block idempotently, fenced by
+// <!-- plan-review:start/end --> so re-running only ever updates that region.
+function writeClaudeMd(targetFile) {
+  mkdirSync(dirname(targetFile), { recursive: true });
+  const block = claudeMdBlock();
+  let existing = "";
+  try {
+    existing = readFileSync(targetFile, "utf8");
+  } catch {
+    existing = "";
+  }
+  const startIdx = existing.indexOf(CLAUDE_MD_START);
+  const endIdx = existing.indexOf(CLAUDE_MD_END);
+  let next;
+  if (startIdx >= 0 && endIdx > startIdx) {
+    next = existing.slice(0, startIdx) + block + existing.slice(endIdx + CLAUDE_MD_END.length);
+  } else {
+    next = existing.trim() ? `${existing.replace(/\s*$/, "")}\n\n${block}\n` : `${block}\n`;
+  }
+  writeFileSync(targetFile, next);
+  console.log(`✓ Wrote plan-review guidance block to ${targetFile}`);
+}
+
 function readJSON(path, fallback) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
@@ -70,6 +177,7 @@ function cmdInit(args) {
   const settings = readJSON(settingsFile, {});
   settings.hooks ??= {};
   settings.hooks.PreToolUse ??= [];
+  settings.hooks.Stop ??= [];
 
   const command = hookCommand(args);
   const already = settings.hooks.PreToolUse.some(
@@ -88,7 +196,58 @@ function cmdInit(args) {
     writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
     console.log(`✓ Wrote ExitPlanMode plan-review hook to ${settingsFile}`);
   }
-  console.log(`\nRuntime: ${chooseRuntime(args)}\nCommand: ${command}`);
+
+  // Stop-hook gate: blocks the turn from ending while a tools-first (mcp/api)
+  // review is still pending. Matcher-less (Stop has no tool matcher).
+  const stopCommand = stopGateCommand(args);
+  const stopAlready = settings.hooks.Stop.some((entry) =>
+    (entry.hooks || []).some(
+      (h) => h?.command?.includes("stop-gate") || h?.command === stopCommand,
+    ),
+  );
+  if (stopAlready) {
+    console.log(`✓ Stop plan-review gate already present in ${settingsFile}`);
+  } else {
+    settings.hooks.Stop.push({
+      hooks: [{ type: "command", command: stopCommand, timeout: 10 }],
+    });
+    writeFileSync(settingsFile, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`✓ Wrote Stop plan-review gate to ${settingsFile}`);
+  }
+
+  console.log(
+    `\nRuntime: ${chooseRuntime(args)}\nHook:    ${command}\nStop:    ${stopCommand}`,
+  );
+
+  // Skill: auto-triggers the multi-document plan authoring in every project.
+  if (args.includes("--no-skill")) {
+    console.log("\n(skipped skill install — --no-skill)");
+  } else {
+    try {
+      installSkill();
+    } catch (e) {
+      console.log(`⚠ Could not install the skill: ${e?.message || e}`);
+    }
+  }
+
+  // MCP server: enables the plan_review_submit / plan_review_check tools.
+  console.log("");
+  registerMcp(args);
+
+  // CLAUDE.md guidance block: written on --write-claude-md, printed otherwise.
+  const claudeMdFile = global
+    ? join(homedir(), ".claude", "CLAUDE.md")
+    : join(resolve(dirArg || process.cwd()), "CLAUDE.md");
+  if (args.includes("--write-claude-md")) {
+    console.log("");
+    writeClaudeMd(claudeMdFile);
+  } else {
+    console.log(
+      `\nAdd this to ${global ? "~/.claude/CLAUDE.md" : "your project's CLAUDE.md"} ` +
+        `(or re-run with --write-claude-md to append it automatically):\n\n${claudeMdBlock()}`,
+    );
+  }
+
   console.log(
     `\nReopen the /hooks menu once (or restart Claude Code) ${global ? "in any project" : "in this project"} so the new hook is picked up.\n` +
       `Then finish a plan in plan mode — your browser will open the review.`,
@@ -138,21 +297,37 @@ function cmdStop() {
   rmSync(SERVER_FILE, { force: true });
 }
 
+function cmdSkill() {
+  installSkill();
+  console.log(
+    "\nThe plan-review-multidoc skill auto-triggers when a plan is large or splits into sections.\n" +
+      "Restart Claude Code (or start a new session) to pick it up.",
+  );
+}
+
 function usage() {
   console.log(`claude-plan-review — review Claude Code plans in your browser (runs on Bun or Node ≥18)
 
 Usage:
   claude-plan-review init [dir] [--global] [--local] [--published] [--runtime bun|node]
-                                  Wire the ExitPlanMode hook into a project (or all projects).
+                                  [--no-skill] [--write-claude-md]
+                                  Wire the ExitPlanMode hook + the Stop-hook gate into a project
+                                  (or all projects), install the plan-review-multidoc skill, and
+                                  register the MCP server.
                                   Runtime auto-detects (Bun if installed, else Node).
-                                  --global     → ~/.claude/settings.json (applies to ALL projects)
-                                  --local      → .claude/settings.local.json
-                                  --published  → portable bunx/npx command (after npm publish)
-                                  --runtime    → force a runtime
+                                  --global         → ~/.claude/settings.json (applies to ALL projects)
+                                  --local          → .claude/settings.local.json
+                                  --published      → portable bunx/npx command (after npm publish)
+                                  --runtime        → force a runtime
+                                  --no-skill       → don't install the multi-doc plan skill
+                                  --write-claude-md→ append the CLAUDE.md guidance block (else printed)
   claude-plan-review serve [port] Start the review server (default ${DEFAULT_PORT})
   claude-plan-review stop         Stop the running server
   claude-plan-review channels     Show storage-channel readiness (e.g. gh / gist)
+  claude-plan-review skill        (Re)install the plan-review-multidoc skill into ~/.claude/skills
+  claude-plan-review mcp          (internal) run the stdio MCP server (plan_review_* tools)
   claude-plan-review hook         (internal) the PreToolUse hook entry
+  claude-plan-review stop-gate    (internal) the Stop hook entry (blocks on a pending tools-first review)
 `);
 }
 
@@ -170,9 +345,20 @@ switch (sub) {
   case "channels":
     await cmdChannels();
     break;
+  case "skill":
+    cmdSkill();
+    break;
+  case "mcp": {
+    const { startMcpServer } = await import("./mcp.js");
+    startMcpServer();
+    break;
+  }
   case "hook":
     await import("./hook.js");
     break;
+  case "stop-gate":
+    await import("./stop-gate.js");
+    break;
   default:
     usage();
 }

package/src/hook.js

@@ -14,6 +14,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_PORT, SERVER_FILE } from "./paths.js";
+import { buildDenyReason, parsePlan } from "./plan-parse.js";
 import { getReview, recordPlan } from "./store.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -127,18 +128,40 @@ async function main() {
   const plan = toolInput.plan ?? "";
   if (!plan.trim()) process.exit(0);
 
-  const { key, version, reviewId } = recordPlan({
-    cwd: input.cwd || process.cwd(),
-    plan,
-    planFilePath: input.tool_input?.planFilePath,
-    sessionId: input.session_id,
-    toolUseId: input.tool_use_id,
-  });
+  // Parse the plan into a normalized tree (or single-doc). A returned {error}
+  // is an EXPLICIT marker-validation failure → deny so Claude stays in plan
+  // mode and re-authors. Any thrown exception is unexpected → fail open (exit
+  // 0 silently) so a parser bug never blocks the user.
+  let tree;
+  try {
+    tree = parsePlan(plan);
+  } catch {
+    process.exit(0);
+  }
+  if (tree && tree.error) {
+    deny(buildDenyReason(tree.error.issues));
+    process.exit(0);
+  }
+
+  let recorded;
+  try {
+    recorded = recordPlan({
+      cwd: input.cwd || process.cwd(),
+      sessionId: input.session_id,
+      toolUseId: input.tool_use_id,
+      planFilePath: input.tool_input?.planFilePath,
+      tree,
+      origin: "hook",
+    });
+  } catch {
+    process.exit(0); // store failure → don't interfere
+  }
+  const { key, version, reviewId } = recorded;
 
   const port = await ensureServer();
   const reviewUrl = `http://localhost:${port}/?project=${encodeURIComponent(
     key,
-  )}&version=${version}&review=${reviewId}`;
+  )}&version=${version}&review=${reviewId}&doc=root`;
   openBrowser(reviewUrl);
 
   // block until the UI resolves the review (or we time out)