pi-diffwarden 0.26.1

package/README.md

@@ -0,0 +1,846 @@
+# Diffwarden
+
+[![version](https://img.shields.io/badge/version-0.26.1-blue.svg)](CHANGELOG.md)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Independent PR guardian skill. You tell your coding agent "use diffwarden on this PR" and it reviews the pull request like a careful senior engineer: reads the diff, CI checks, and review comments; finds bugs and risks; fixes safe ones; verifies; and stops before doing anything dangerous.
+
+It never auto-merges, never force-pushes, and never weakens your tests or CI to make a check go green.
+
+## Contents
+
+- [Command reference](#command-reference)
+- [Workspace review (no git required)](#workspace-review-no-git-required)
+- [Review uncommitted changes (no PR)](#review-uncommitted-changes-no-pr)
+- [Auto-detected mode (code vs plan)](#auto-detected-mode-code-vs-plan)
+- [Web-augmented review (opt-in)](#web-augmented-review-opt-in)
+- [Loop until merge-ready (c5/5)](#loop-until-merge-ready-c55)
+- [Optional orchestration](#optional-orchestration)
+- [What it actually does](#what-it-actually-does)
+- [Is this for me?](#is-this-for-me)
+- [Prerequisites (do this first)](#prerequisites-do-this-first)
+- [Pi Agent](#pi-agent)
+- [Install](#install)
+- [Slash commands](#slash-commands)
+- [Codex CLI](#codex-cli)
+- [Your first run (step by step)](#your-first-run-step-by-step)
+- [Modes / flags](#modes--flags)
+- [Common recipes](#common-recipes)
+- [What it will and won't do](#what-it-will-and-wont-do)
+- [Core loop](#core-loop)
+- [Troubleshooting / FAQ](#troubleshooting--faq)
+- [Contributing](#contributing)
+- [Files](#files)
+- [Version](#version)
+
+## Command reference
+
+Invoke with `/diffwarden` (or the optional `/dw` alias). v0.26.1 uses five primary commands: `review`, `loop`, `status`, `comment`, and `help`. Target arg: `workspace` (current folder, git not required), a local target (`local`, `staged`), a PR (`#123`, full URL, or omit for current-branch PR), or a plan/docs file (`path/to/file.md`). Natural-language prompts still work — see [Slash commands](#slash-commands).
+
+**What works out of the box:** once the skill is installed (see [Install](#install)), `/diffwarden` registers in **Claude Code** automatically (it matches the skill name). The shorthand `/dw` needs command files in Claude Code/Cursor. **Codex CLI is different** — see [Codex CLI](#codex-cli): use `$diffwarden` or `/skills`, not `/dw` or `/diffwarden`.
+
+| Command | What it does |
+|---------|--------------|
+| `/diffwarden review [<target>]` | Read-only review + fix plan. No edits, commits, or push. Lean output by default. |
+| `/diffwarden loop [<target>]` | Review → fix safe issues → verify → rescore until `c5/5`. Local edits only unless `--commit` or `--push`. |
+| `/diffwarden status [<target>]` | Score/snapshot only (checks, confidence, blockers). |
+| `/diffwarden comment [<pr>]` | Short PR review comment. Asks for explicit approval before posting. PR-only. |
+| `/diffwarden help` | List commands. Bare `/diffwarden` = help. Use `/dw help --verbose` for advanced flags. |
+
+**Targets:**
+
+| Target | Meaning |
+|--------|---------|
+| `workspace` | Current folder — git not required (see [Workspace review](#workspace-review-no-git-required)) |
+| `local` / `staged` | Git working tree or staged changes, no PR |
+| `#123`, PR URL, or omitted | GitHub PR (current branch when omitted) |
+| `path/to/file.md` | Plan, docs, guides, tutorials (see [Auto-detected mode](#auto-detected-mode-code-vs-plan)) |
+
+| Flag | Effect |
+|------|--------|
+| `--mvp` | Stop loop at `c4/5` when only P3/info remains. |
+| `--verbose` | Full detailed report (iterations, verification, changed files, risks, …). Off by default. |
+| `--orchestrate` | Split review and fix across configured models (see [Optional orchestration](#optional-orchestration)). Off by default. |
+| `--commit` | Commit verified changes (git modes only, after verification). |
+| `--push` | Commit + push verified changes (PR mode only, after PR head recheck). |
+| `--security` | Security-focused review (auth, injection, SSRF, secrets, path traversal, crypto, data loss). |
+| `--as-code` / `--as-plan` | Force code or plan/document mode for `review`/`loop`. |
+| `--web` / `--research` | Opt into [web-augmented review](#web-augmented-review-opt-in). Per-finding consent. |
+| `--reply` / `--resolve` | Reply on or resolve PR review threads (explicit approval required). |
+| `--dry-run` | Review only; no edits (= `review`). |
+| `--max N` | Loop iterations (default `3`, hard max `5`). |
+
+**Compatibility aliases** (still work; not shown in short help):
+
+| Alias | Equivalent |
+|-------|------------|
+| `fix` | `loop` |
+| `prepare` | `loop --push` |
+| `security` | `review --security` |
+| `review-plan <file>` | `review <file> --as-plan` |
+| `fix-plan <file>` | `loop <file> --as-plan` |
+
+```text
+/dw review workspace
+/dw loop workspace
+/dw loop #123 --commit
+/dw loop #123 --push
+/dw comment #123
+/dw status
+/dw help
+/dw help --verbose
+```
+
+## Workspace review (no git required)
+
+Use `workspace` to review the current folder when there is no git repo, no branch, detached HEAD, or no open PR. Diffwarden discovers files, detects the stack, and reviews high-signal code/config/tests/docs — no PR detection, no CI, no GitHub comments.
+
+```text
+/dw review workspace          # read-only workspace review
+/dw loop workspace            # review + fix safe issues (backs up before editing)
+/dw status workspace          # score only
+```
+
+Auto-fallback: when no explicit PR target is given and git/branch/PR is missing, Diffwarden falls back to workspace mode instead of blocking.
+
+`loop workspace` creates a reversible baseline in `.diffwarden/backups/<timestamp>/` before the first edit. Workspace mode does not commit, push, or post PR comments. `--push` and `--commit` are rejected for `workspace`.
+
+## Review uncommitted changes (no PR)
+
+Pass a local target instead of a PR to review your working tree before you
+commit or open a PR. No GitHub access, no CI, no review threads — just the diff,
+your project context, and the same review pipeline.
+
+| Target | Diff scope |
+|--------|------------|
+| `local` / `worktree` | All changes vs `HEAD` **plus** untracked files (gitignored excluded). |
+| `staged` | Staged changes only (`git diff --cached`). |
+
+```text
+/dw review local          # read-only review of everything uncommitted
+/dw review staged         # review only what you've git add-ed
+/dw loop local            # review + apply safe fixes (no commit/push unless --commit)
+/dw review local --security   # security-focused pass on uncommitted changes
+```
+
+Valid with `review`, `loop`, and `status`. Everything that defines a
+review still runs — classification, severity, confidence score, fix loop,
+verification, security checklist. What's skipped (no PR exists): PR detection,
+CI, review/issue comments, `comment`, and push. `loop local` edits the working tree only unless you pass `--commit`. `comment` and `--push` are rejected with a local target.
+
+## Auto-detected mode (code vs plan)
+
+`review` and `loop` work on **either** code or a plan/docs file.
+Diffwarden classifies the *target* and runs the matching mode — you do
+not pick a separate subcommand.
+
+| Target | Detected mode |
+|--------|---------------|
+| `workspace` | code (folder scan, git optional) |
+| `#123`, `123`, full PR URL, `current`, or omitted | code |
+| `local`, `staged`, `worktree` | code |
+| a single prose `.md` plan/docs file | document/plan |
+| `--as-code` flag | code (forced) |
+| `--as-plan` flag | plan (forced) |
+| **mixed** signals (e.g. a PR *and* a `.md` plan) | **asks you; default code** |
+
+```text
+/dw review #123            # PR review
+/dw review                 # current branch PR or git-local/workspace fallback
+/dw review workspace       # folder review, no git required
+/dw review docs/plan.md    # document/plan review
+/dw review docs/plan.md --as-code   # force code review of the file
+/dw loop #123              # PR fix loop
+/dw loop docs/plan.md      # revise document in place (backs up to <file>.orig)
+/dw loop docs/plan.md --as-plan     # explicit document mode
+```
+
+`--as-code` / `--as-plan` override the detector; on a mix of signals Diffwarden
+**asks first** (defaulting to code only if you don't choose) — it never silently
+guesses. Document mode never touches a PR or git: `review` is read-only;
+`loop` revises only the target document (backing up to `<file>.orig`) and
+never commits or pushes unless you pass `--commit` in a git context. `comment` is PR-only.
+
+> The older `review-plan` / `fix-plan` names still work as **hidden back-compat
+> aliases** (equivalent to `review` / `loop <file> --as-plan`), but `review` /
+> `loop` on a `.md` file is the way to invoke document mode now.
+
+## Web-augmented review (opt-in)
+
+Off by default. Diffwarden grounds its findings against your repo and the diff —
+**never the internet** — unless you turn this on with `--web` (alias
+`--research`). Even then it never searches silently: on an **uncertain** finding
+it asks first and waits for your `y`.
+
+Two gates, both required:
+
+1. **You pass `--web`.** Without it, Diffwarden never touches the network for a
+   review. (The only other network call is the help-path version check.)
+2. **Per finding, it asks and waits:**
+
+   ```text
+   I am unsure about <finding>. Search the web to verify? [y/N]
+   Query (redacted): "<minimal finding descriptor>"
+   ```
+
+   Default is **No**. Anything but `y` skips the search and keeps the finding
+   `local-only`. No batch-approve, no assuming consent from the flag.
+
+**When it offers a search:** only on genuine uncertainty — a low-confidence
+finding, something time-sensitive (a CVE, a security advisory, a deprecation, a
+current best practice or idiomatic pattern), or when you asked for a
+deep/verbose review. High-confidence, locally-provable findings are never sent
+out.
+
+**What leaves your machine:** the **minimal finding descriptor only** — the
+abstract shape of the issue (e.g. "Express open-redirect via unvalidated user
+input"). Never your code, diff, secrets, tokens, file paths, or internal names.
+The exact redacted query is shown in the prompt — what you approve is what's
+sent. A web search is egress to a third party that may be logged or indexed;
+that's why it's gated, redacted, and minimized.
+
+**Output:** every finding is marked `web-verified` (a consented search grounded
+it; URL cited) or `local-only` (the default). Web grounding **never** raises
+severity on its own and never bypasses a safety cap — severity and the
+confidence score stay Diffwarden's own judgment.
+
+Valid on `review`, `loop`, and `review --security` (code targets, including
+`local` / `staged` / `workspace`), and compatible with `--dry-run`.
+Rejected on `status` (snapshot only) and on document mode (`--as-plan`
+or a `.md` docs target) — document critique grounds against your repo, not the web.
+
+```text
+/dw review #123 --web      # asks [y/N] before grounding any uncertain finding
+/dw loop --web --security  # security run reads raw; web grounding still per-finding gated
+```
+
+## Loop until merge-ready (c5/5)
+
+`loop` is the primary review-fix-verify command. Each iteration: collect evidence → classify top blocker → compute confidence → fix safe scoped issue → verify → rescore. Stops at **c5/5**, `--mvp` at **c4/5**, or a safety stop.
+
+### Lean output (default)
+
+Loop prints one line per iteration, then final `Status:` and `Level:` lines — no long evidence blocks unless `--verbose`:
+
+```text
+c2/5 P1 src/auth.ts:44 — missing ownership check
+c3/5 P2 tests missing for changed branch
+c4/5 mvp-ready — only P3/info remains
+c5/5 clean
+
+Status: ready
+Level: 5/5
+```
+
+Every final review ends with `Status:` then `Level:`. Review output is also lean by default:
+
+```text
+Findings:
+- P1 src/auth.ts:44 — missing ownership check
+- P2 tests/auth.test.ts — missing coverage for denied update
+
+Status: not-ready
+Level: 2/5
+```
+
+Use `--verbose` for the full report (iterations, verification, changed files, risks, next action, how to test).
+
+### Commands
+
+| Goal | Command |
+|------|---------|
+| Loop locally (no commit/push) | `/dw loop` or `/dw loop --max 5` |
+| Loop + commit | `/dw loop --commit` |
+| Loop + commit + push (PR only) | `/dw loop --push` or `/dw loop #123 --push` |
+| Check score only | `/dw status` |
+| Stop at MVP (c4/5) | `/dw loop --mvp` |
+| Post short PR comment | `/dw comment #123` |
+
+Natural language: `Use diffwarden on the current PR --max-iterations 5`
+
+Default **3** iterations; hard max **5** unless you explicitly ask for more in chat.
+
+### What c5/5 means
+
+All must be true (scope-dependent — PR vs local vs workspace):
+
+- Required CI checks pass (PR mode) or grounded local verification passes
+- No actionable findings remain
+- No open P0/P1/security issue
+- PR description adequate (PR mode) or document/workspace ready
+
+Score is recomputed from evidence every iteration. **c5/5 does not auto-merge** — you merge.
+
+### Confidence scale (short)
+
+| Score | Meaning |
+|-------|---------|
+| `c5/5` | Clean / merge-ready (loop stops) |
+| `c4/5` | MVP-ready — only P3 / informational items left (`--mvp` stops here) |
+| `c3/5` | P2 issues or missing targeted test / verification |
+| `c2/5` | P1 issue or failing required check |
+| `c1/5` | P0, security, or hard build failure |
+
+Safety caps: unresolved P0/security → max `1/5`; failing required check → max `2/5`;
+needs-user-decision → max `3/5` until you decide.
+
+### Evidence-based findings
+
+- Actionable findings need **anchor + quote** — not model guesswork.
+- Anchors: `file:line`, check name, PR field, or comment/thread id.
+- Fix plans: only diff/read files; verify commands must exist in manifests.
+- Verification is built into `loop` (no `--verify` flag on `review`).
+- `--verbose` loop adds structured `verify: pass|fail|skipped` reporting.
+
+### When it stops before c5/5
+
+| Reason | What to do |
+|--------|------------|
+| Hit `--max 5` | Run again: `/dw loop --max 5` |
+| `--mvp` and c4/5 | Done for MVP — merge or continue without `--mvp` |
+| Needs user decision (API, product, migration…) | Answer in chat, re-run |
+| Same finding repeats | Agent stops — fix root cause manually |
+| CI still pending | Wait for green, then `/dw status` |
+| Dirty unrelated files | Clean worktree or stash first |
+
+### Example workflow
+
+```text
+/dw status
+/dw loop --max 5
+/dw loop #123 --push
+/dw comment #123
+```
+
+## Optional orchestration
+
+Diffwarden can optionally split review and fix work across different models using
+`--orchestrate`. This is off by default. See
+[docs/orchestration.md](docs/orchestration.md).
+
+## What it actually does
+
+This repo is **not an app**. It is one markdown playbook (`skills/diffwarden/SKILL.md`) that teaches an AI coding agent (Claude Code, Copilot CLI, Cursor, etc.) a safe, repeatable way to babysit a pull request.
+
+Given a PR, the agent:
+
+1. Checks your environment is safe to work in (git repo, logged into GitHub, right branch).
+2. Reads everything: the diff, CI status, inline review comments, bot comments.
+3. Sorts findings into: must-fix now, FYI, already fixed, or "ask the human".
+   Actionable items need anchor + quote (file/line, check, PR field, or comment).
+4. Ranks by severity (P0 security/data-loss down to P3 polish).
+5. Writes a small fix plan, applies safe fixes, and runs discovered tests/linters
+   to prove they work (`loop` only — `review` is read-only).
+6. Optionally posts the review on GitHub or commits fixes — only if you allow it.
+7. Loops until the PR is merge-ready, blocked, or it needs your decision.
+
+## Is this for me?
+
+Use it if you want to:
+
+- check a PR before merging it
+- get failing CI checks fixed safely
+- review a teammate's PR and leave comments on GitHub
+- do a focused security pass on changed code
+
+Don't use it for: deploying to production, auto-merging, rewriting git history, or large refactors unrelated to the PR.
+
+## Prerequisites (do this first)
+
+You need a coding agent that can read skills and run shell commands. Examples: Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi Agent. The installer targets Claude Code, Codex, Cursor, and Pi directly; any other skill-loading agent works via manual copy ([Install](#install) Option C/D).
+
+**For PR review** you also need `git`, GitHub CLI (`gh`), and a logged-in GitHub session:
+
+```bash
+git --version
+gh --version
+gh auth status        # should say "Logged in to github.com"
+gh auth login         # run this if it doesn't
+```
+
+**For workspace or document review** git and `gh` are optional. Diffwarden falls back to workspace mode when git/branch/PR is unavailable.
+
+Optional: export `GH_TOKEN` (or `GITHUB_TOKEN`) for CI/automation when `gh auth
+login` is not available. Diffwarden tries `gh auth status` first; if you are
+logged in, it ignores env tokens for that session so `gh` uses your user. With
+no active user, it validates env tokens with `gh api user`. It never searches
+files or config for tokens.
+
+## Pi Agent
+
+Diffwarden can be used with Pi Agent three ways: installer/manual skill copy, prompt templates, or optional Pi package extension.
+
+Diffwarden core behavior stays agent-neutral. The extension only adds native `/dw` and `/diffwarden` commands that forward to `/skill:diffwarden`, plus bundled skill discovery.
+
+### Pi package extension
+
+> Security: Pi extensions run with full local permissions. Review `extensions/diffwarden/index.ts` before installing.
+
+```bash
+pi install npm:pi-diffwarden@0.26.1      # global
+pi install -l npm:pi-diffwarden@0.26.1   # project
+
+# Git source also works:
+pi install git:github.com/jperocho/diffwarden@v0.26.1
+```
+
+The package loads `extensions/diffwarden/index.ts`, which discovers `skills/diffwarden/SKILL.md` from this repo. Restart Pi Agent or run `/reload` after installing.
+
+### Manual install
+
+Copy the Diffwarden skill into one of Pi Agent's skill locations:
+
+```bash
+# project scope, loaded after the project is trusted
+mkdir -p .pi/skills/diffwarden
+cp skills/diffwarden/SKILL.md .pi/skills/diffwarden/SKILL.md
+
+# global scope
+mkdir -p ~/.pi/agent/skills/diffwarden
+cp skills/diffwarden/SKILL.md ~/.pi/agent/skills/diffwarden/SKILL.md
+```
+
+Pi also discovers skills from `.agents/skills/` and `~/.agents/skills/`, so the Codex-compatible install path works in Pi too.
+
+Optional `/dw` and `/diffwarden` aliases can be installed as Pi prompt templates when you do not use the extension package:
+
+```bash
+# project scope
+mkdir -p .pi/prompts
+cp skills/diffwarden/prompts/dw.md .pi/prompts/dw.md
+cp skills/diffwarden/prompts/diffwarden.md .pi/prompts/diffwarden.md
+
+# global scope
+mkdir -p ~/.pi/agent/prompts
+cp skills/diffwarden/prompts/dw.md ~/.pi/agent/prompts/dw.md
+cp skills/diffwarden/prompts/diffwarden.md ~/.pi/agent/prompts/diffwarden.md
+```
+
+The prompt templates must pass arguments through with `$ARGUMENTS` so `/dw loop workspace` expands to a Diffwarden invocation with `loop workspace` intact.
+
+Restart Pi Agent or run `/reload` after installing. Without prompt templates or the extension, invoke the skill with `/skill:diffwarden` or plain chat.
+
+### Installer
+
+```bash
+./install.sh --pi --project
+./install.sh --pi --global
+./install.sh --pi --pi-root ~/.pi/agent --global
+./install.sh --pi --pi-root ./.pi --project
+./install.sh --pi --dry-run
+```
+
+### Usage
+
+```text
+/dw review workspace
+/dw loop workspace
+/dw review
+/dw loop
+/diffwarden review
+/diffwarden loop
+/skill:diffwarden loop workspace
+```
+
+### Extension behavior
+
+The extension registers native `/dw` and `/diffwarden` commands, offers basic argument completions, and sends `/skill:diffwarden <args>` to the agent. It does not add tool interception, auto-merge, auto-push, file writes, or background processes.
+
+## Install
+
+**Global install is recommended** — Diffwarden is a reusable reviewer/fixer that should be available in every workspace. Project install is still supported for team/repo-specific distribution.
+
+There is **no `npx`/skills.sh step** — that loader proved flaky, so Diffwarden
+installs with its own script or a plain copy. Both place the same files:
+
+- the skill itself → `<root>/.claude/skills/diffwarden/SKILL.md` (Claude Code),
+  `<root>/.agents/skills/diffwarden/SKILL.md` (Codex), and/or
+  `<root>/.cursor/skills/diffwarden/SKILL.md` (Cursor),
+- the optional `/dw` and `/diffwarden` slash-command files → `<root>/.claude/commands/`
+  and/or `<root>/.cursor/commands/` (Claude Code and Cursor only — Codex does not
+  use command files; see [Codex CLI](#codex-cli)),
+
+where `<root>` is your project folder (project scope) or `$HOME` (global scope).
+
+**Option A — installer (recommended).** It detects which agents you have, asks
+where to install (global recommended), copies the skill + command files into the right places,
+skips files already up to date, and never overwrites a changed file without
+asking.
+
+> **Security — inspect before you run.** Diffwarden is a safety tool; don't
+> pipe a script straight into a shell on its word. Download it, read it, then
+> run it. The installer pins to a release tag, uses HTTPS only, never uses
+> `sudo`, and only writes under `.claude/`, `.cursor/`, `.agents/`, Pi roots
+> (`skills/` + `prompts/` only), and optional `~/.config/diffwarden/` when you
+> confirm orchestration defaults.
+
+```bash
+# Recommended: download → read → run
+curl -fsSLO https://raw.githubusercontent.com/jperocho/diffwarden/v0.26.1/install.sh
+less install.sh        # read it first
+bash install.sh        # interactive: detects agents, asks scope, confirms
+
+# Or run it straight from a clone (no network):
+git clone https://github.com/jperocho/diffwarden
+cd diffwarden && ./install.sh
+```
+
+Useful flags (see `./install.sh --help`):
+
+```bash
+./install.sh --dry-run            # show the plan, write nothing
+./install.sh --claude --project   # Claude Code, current repo only
+./install.sh --codex --global     # Codex, all projects on this machine
+./install.sh --cursor --global    # Cursor, all projects on this machine
+./install.sh --pi --global        # Pi Agent, all projects on this machine
+./install.sh --yes                # non-interactive (accept detected defaults)
+./install.sh --force              # overwrite differing files without prompting
+```
+
+**Option B — manual copy.** Do exactly what the installer does, by hand. Pick a
+`<root>` (`.` for this project, `~` for global) and the matching agent location:
+
+```bash
+# Claude Code, project scope
+mkdir -p .claude/skills/diffwarden .claude/commands
+cp skills/diffwarden/SKILL.md          .claude/skills/diffwarden/SKILL.md
+cp skills/diffwarden/commands/dw.md    .claude/commands/
+cp skills/diffwarden/commands/diffwarden.md .claude/commands/
+
+# Codex, project or global scope (same skill path; invoke with $diffwarden)
+mkdir -p .agents/skills/diffwarden
+cp skills/diffwarden/SKILL.md          .agents/skills/diffwarden/SKILL.md
+# global: mkdir -p ~/.agents/skills/diffwarden && cp ... ~/.agents/skills/diffwarden/
+
+# Cursor, project scope — same files under .cursor/
+mkdir -p .cursor/skills/diffwarden .cursor/commands
+cp skills/diffwarden/SKILL.md          .cursor/skills/diffwarden/SKILL.md
+cp skills/diffwarden/commands/dw.md    .cursor/commands/
+cp skills/diffwarden/commands/diffwarden.md .cursor/commands/
+```
+
+For global Claude Code/Cursor scope, swap the leading `.` for `~`. For global
+Codex skills, use `~/.agents/skills/diffwarden/SKILL.md`.
+
+Claude Code and Codex load skills at session start — restart (or `/clear` in
+Codex) after installing. Codex invocation details: [Codex CLI](#codex-cli).
+
+**Optional — caveman mode for token savings.** Diffwarden runs long review loops
+(diffs, CI logs, threads), so it pairs well with the [`caveman`](https://github.com/JuliusBrussee/caveman)
+skill, which compresses agent output ~75% with no loss of technical substance. If
+`caveman` is loaded, Diffwarden runs in caveman mode automatically; if not, it prints
+a one-time install tip and continues normally.
+
+Caveman activation differs by agent:
+
+- **Claude Code / Codex / Gemini** — hook-driven, auto-activates per session once installed.
+- **Cursor / Windsurf / Cline / Copilot** — no hook system; activation is a static
+  rule file. For Cursor, install the rule into `.cursor/rules/`:
+
+  ```bash
+  npx skills add JuliusBrussee/caveman -a cursor --with-init
+  ```
+
+  > **Caution for this repo only:** `--with-init` also writes repo-root `AGENTS.md`,
+  > which in this project is a symlink to `CLAUDE.md`. Running it here would modify
+  > project instructions. Instead, copy just the Cursor rule by hand:
+  >
+  > ```bash
+  > mkdir -p .cursor/rules
+  > cp ~/.claude/plugins/marketplaces/caveman/src/rules/caveman-activate.md \
+  >    .cursor/rules/caveman.mdc
+  > echo ".cursor/rules/caveman.mdc" >> .gitignore   # keep out of the distributable
+  > ```
+
+Cursor reads only `.cursor/` and repo-root `AGENTS.md`; it never reads Claude's
+`~/.claude` install, so the two stay isolated.
+
+**Option C — other agents / custom skill folder.** Copy the skill wherever your
+agent loads skills from:
+
+```bash
+mkdir -p ~/.config/agent-skills/diffwarden
+cp skills/diffwarden/SKILL.md ~/.config/agent-skills/diffwarden/SKILL.md
+```
+
+**Option D — no skill loader.** Paste the contents of `skills/diffwarden/SKILL.md` into your agent's context before you give it the PR task.
+
+## Slash commands
+
+Examples and natural-language form. Full command table: [Command reference](#command-reference).
+
+```text
+/diffwarden review #123
+/diffwarden loop
+/diffwarden loop #123 --push
+/diffwarden comment #123
+/dw status
+/dw loop workspace
+/dw help
+```
+
+Natural-language equivalents:
+
+```text
+Use diffwarden on the current PR --dry-run
+Use diffwarden on PR https://github.com/owner/repo/pull/123 --no-push
+```
+
+## Codex CLI
+
+Codex installs and runs Diffwarden as a **skill**, not as custom slash commands.
+The grammar is the same; only the prefix changes.
+
+### Supported
+
+| How | Example |
+| --- | --- |
+| Skill install path | `.agents/skills/diffwarden/SKILL.md` or `~/.agents/skills/diffwarden/SKILL.md` |
+| Explicit invocation | `$diffwarden review`, `$diffwarden loop workspace` |
+| Skill picker | `/skills` → choose **diffwarden** |
+| Plain chat | Works when the task matches the skill description (implicit load) |
+
+After install, restart Codex or run `/clear` so it rescans skills.
+
+### Not supported (and why)
+
+| What you might expect | Why it does not work |
+| --- | --- |
+| `/diffwarden`, `/dw` in the `/` menu | Codex `/` commands are **built-in only** (`/skills`, `/review`, `/model`, …). Custom slash commands from skill or command files are not loaded. OpenAI directs skill use through `$skill-name` instead ([codex#11817](https://github.com/openai/codex/issues/11817)). |
+| `/prompts:diffwarden`, `/prompts:dw` | **Custom prompts** in `~/.codex/prompts/` were [deprecated](https://developers.openai.com/codex/custom-prompts) and **removed in the March 2026 Codex release** (0.117 series). OpenAI consolidated on Agent Skills as the standard; overlapping prompt-slash machinery was dropped ([codex#15941](https://github.com/openai/codex/issues/15941)). |
+| `.codex/commands/` or `.codex/skills/` | Legacy paths. Current Codex reads skills from `.agents/skills` / `~/.agents/skills` per [customization docs](https://developers.openai.com/codex/concepts/customization). |
+
+There is no `/dw` shorthand on Codex unless you add a separate skill named `dw`.
+Use `$diffwarden` — same subcommands and flags as the [command reference](#command-reference).
+
+```text
+$diffwarden review
+$diffwarden loop workspace
+$diffwarden loop #123 --push
+$diffwarden comment #123
+$diffwarden status
+/skills                    # pick diffwarden from the menu
+```
+
+## Your first run (step by step)
+
+1. `cd` into your repo and switch to the PR's branch.
+2. Confirm you're set up:
+
+   ```bash
+   gh auth status
+   gh pr view            # should show the current PR
+   ```
+
+3. In your agent, type:
+
+   ```text
+   /diffwarden review
+   ```
+
+   Or the long form:
+
+   ```text
+   Use diffwarden on the current PR --dry-run
+   ```
+
+   Both mean **review and plan only — change nothing.** Best way to start: zero risk.
+
+4. Read the report. It lists findings, severity, and a fix plan.
+5. When ready to let it act:
+
+   ```text
+   /diffwarden loop
+   ```
+
+   Or with explicit push on a PR:
+
+   ```text
+   /diffwarden loop #123 --push
+   ```
+
+If you omit the PR number/URL, it detects the PR from your current branch.
+
+## Modes / flags
+
+Add these after the command. Combine freely. Short help shows primary flags; use `/dw help --verbose` for the full list.
+
+| Flag | What it does |
+|------|--------------|
+| `--mvp` | Stop loop at `c4/5` when only P3/info remains. |
+| `--verbose` | Full detailed report instead of lean output. |
+| `--orchestrate` | Optional reviewer/fixer model split ([docs/orchestration.md](docs/orchestration.md)). |
+| `--commit` | Commit verified changes (git modes, after verification). |
+| `--push` | Commit + push verified changes (PR mode only, after head recheck). |
+| `--as-code` / `--as-plan` | Force code or document mode, overriding the [target detector](#auto-detected-mode-code-vs-plan). |
+| `--dry-run` | Review and plan only. No edits, commits, pushes, or comments. **Start here.** |
+| `--security` | Prioritize security: auth, injection, SSRF, secrets, path traversal, crypto, data loss. |
+| `--reply` / `--resolve` | Reply on or resolve PR review threads (explicit OK each run). |
+| `--web` / `--research` | Opt into [web-augmented review](#web-augmented-review-opt-in). Per-finding consent. |
+| `--max N` | Loop iterations. Default `3`; hard max `5`. |
+
+## Common recipes
+
+**Review your own PR before merge (safe, read-only):**
+
+```text
+/diffwarden review
+```
+
+**Review a teammate's PR and post a short comment:**
+
+```text
+/diffwarden comment #123
+```
+
+Posts a `COMMENT`-type review with inline P-level notes after your approval. It will **not** approve or request changes — that decision stays yours.
+
+**Security-focused pass:**
+
+```text
+/diffwarden review #123 --security
+```
+
+**Review a folder with no git repo:**
+
+```text
+/dw review workspace
+/dw loop workspace
+```
+
+**Address review feedback and reply on threads:**
+
+```text
+/diffwarden loop #123 --reply --resolve
+```
+
+**Let it fix safe issues locally, but don't push:**
+
+```text
+/diffwarden loop
+```
+
+**Loop until merge-ready and push (PR):**
+
+```text
+/diffwarden loop #123 --push
+```
+
+## What it will and won't do
+
+**Will:**
+
+- Read diffs, checks, and comments.
+- Fix safe, in-scope issues and run tests to verify.
+- Reply on reviewer comment threads (with `--reply` + your OK).
+- Resolve fixed threads (with `--resolve` + your OK).
+- Post short comment-only reviews (with `comment` + your OK).
+- Commit/push **only** when you pass `--commit` or `--push`.
+
+**Won't (the safety promise):**
+
+- No auto-merge.
+- No force-push, no `git reset --hard`, no history rewrite.
+- No blind push — it checks the PR head didn't change first.
+- No approving or requesting changes on a PR.
+- No resolving human review comments without your explicit approval.
+- No weakening CI, tests, lint, branch protection, auth, secrets, or infra config to make checks pass.
+
+**Stops and asks** on: dirty unrelated files, ambiguous risk, the PR head changing mid-run, protected branches, or a loop that isn't converging.
+
+## Core loop
+
+```text
+preflight -> detect PR -> collect evidence -> classify -> plan fixes -> apply safe fixes -> verify -> optional commit/push -> optional thread replies/resolve -> optional post-review -> re-check -> report
+```
+
+## Troubleshooting / FAQ
+
+**" `/dw` doesn't show in the `/` menu."** For Claude Code/Cursor, the command files weren't installed; copy `dw.md` / `diffwarden.md` into `.claude/commands/`, `~/.claude/commands/`, `.cursor/commands/`, or `~/.cursor/commands/`, then restart. For Pi Agent, install prompt templates or the Pi package extension, then run `/reload`. For **Codex CLI**, `/dw` and `/diffwarden` are **not supported** — the `/` menu is built-in commands only. Install the skill to `.agents/skills/diffwarden/` (or `~/.agents/skills/diffwarden/`), restart or `/clear`, then use `$diffwarden review ...` or `/skills`. See [Codex CLI](#codex-cli) for why `/prompts:dw` also no longer works on Codex ≥ 0.117.
+
+**"Caveman mode doesn't activate in Cursor."** Cursor has no hook system, so caveman
+needs a static rule file at `.cursor/rules/caveman.mdc` (see [Install](#install)).
+Check with `ls .cursor/rules/caveman.mdc`. Absent → caveman is inactive and Diffwarden
+shows the install tip instead of compact output.
+
+**"It says I'm not authenticated."** Run `gh auth login`, then `gh auth status`
+to confirm. For CI with no `gh` user, export a valid `GH_TOKEN`. If you are
+logged in via `gh` but a stale `GH_TOKEN` is set, Diffwarden unsets it so your
+user login wins.
+
+**"It can't find a PR."** Make sure you're on the PR's branch, or pass the number/URL explicitly: `... on PR 123`.
+
+**"It refuses to run on `main`/`master`."** By design. Switch to the PR's feature branch first.
+
+**"It won't fix my failing CI by editing the workflow."** Also by design — it never weakens CI/tests to go green. Fix the real cause.
+
+**"Will it merge my PR?"** No. Never. You merge.
+
+**"Can it review a PR from a fork?"** It can review and (with `comment`) post findings. It usually can't push fixes to a fork branch, so omit `--push` / treat fixes as suggestions.
+
+**"It stopped early."** It hit a safety stop (dirty worktree, ambiguous risk, head changed, max iterations). Read the report — it says why and what to do next.
+
+## Contributing
+
+Contributions welcome — fork, branch, PR.
+
+```bash
+# 1. Fork on GitHub, then:
+git clone https://github.com/<you>/diffwarden
+cd diffwarden
+git checkout -b my-change
+
+# 2. Make the change. Before pushing, run the same checks CI runs:
+bash -n install.sh          # shell syntax
+shellcheck install.sh       # shell lint
+node -e 'JSON.parse(require("fs").readFileSync("package.json","utf8"))'
+npm pack --dry-run
+./install.sh --pi --pi-root /tmp/pi-agent --project --dry-run
+# Optional local Pi smoke, when pi is installed:
+pi -e ./extensions/diffwarden/index.ts --help
+# if you bumped the version, confirm it matches in every file (see below)
+
+# 3. Push to your fork and open a PR against main.
+git push -u origin my-change
+```
+
+**Branch protection on `main`.** `main` is protected by repository rulesets —
+plan your PR around them:
+
+- **No direct pushes to `main`** — every change lands through a pull request,
+  including the maintainer's. Pushing to `main` is rejected.
+- **1 approving review required** before merge.
+- **CI must pass** (`bash -n` + `shellcheck` on `install.sh`, Pi installer
+  dry-runs, Pi package static checks, `npm pack --dry-run`, plus a version-sync
+  check). This is enforced for everyone — the maintainer can't merge red CI.
+- **Squash merge only** — keeps `main` linear. Your PR's commits are squashed
+  into one on merge, so a clean PR title is the commit message.
+- **No force-push, no branch deletion** on `main`.
+
+The maintainer may merge without a second reviewer (solo project) but is still
+held to "PR required" and "CI green" — same as everyone else.
+
+**Touching the skill or its version?** `SKILL.md` is the source of truth; if you
+change it, update `README.md` and `CHANGELOG.md` to match. The version string is
+duplicated across six places and must stay in sync (CI fails otherwise) — see
+[`CLAUDE.md`](CLAUDE.md) for the exact list and the project's editing rules.
+
+## Files
+
+- `skills/diffwarden/SKILL.md` — the skill/playbook (the actual product).
+- `skills/diffwarden/commands/` — optional `/dw` `/diffwarden` slash files for Claude Code and Cursor.
+- `skills/diffwarden/prompts/` — Pi Agent prompt templates for `/dw` and `/diffwarden`.
+- `extensions/diffwarden/index.ts` — optional Pi extension command wrapper and resource discovery.
+- `package.json` — Pi/npm package manifest for installing the extension from npm, git, or local paths.
+- `docs/orchestration.md` — optional model orchestration guide.
+- `install.sh` — installer that detects agents and copies the skill + command files into place.
+- `.github/workflows/ci.yml` — CI: shellchecks `install.sh` and enforces version sync.
+- `README.md` — this guide.
+- `CHANGELOG.md` — release notes.
+- `CLAUDE.md` / `AGENTS.md` — agent guidance (`AGENTS.md` symlinks `CLAUDE.md`).
+- `LICENSE` — MIT.
+- `.gitignore` — local/editor/cache exclusions.
+
+## Version
+
+Current version: `v0.26.1`