instruction-review

Reviews a project's instruction file (CLAUDE.md or AGENTS.md) against recent work and proposes a minimal, evidence-backed diff, without applying it.

Group: Project hygiene
Kind: Action
Writes: The instruction file
Asks before: Applying the diff

When it runs

When you ask to improve or review the project's instructions, or invoke it by name. With --prune it cuts instead of adding; use that when the default model changes and about every six months.

improve CLAUDE.md
review the project instructions
what should go in CLAUDE.md

What it does

Reads the sources: the instruction file (AGENTS.md when CLAUDE.md only imports @AGENTS.md; rules never go beside the import), any project context file the repository documents, the active plan, and recent git history and diffs.
Keeps only durable rules, ones supported by repeated work, a concrete defect or an explicit correction from you. It leaves out facts the code already shows, one-off debugging history, rules already in the developer-os core rules or your global instructions, and unsupported preferences.
Flags stale entries. Lines that are stale or contradict the code are proposed for removal, each with its reason. The file stays under 100 lines; overflow moves to project docs behind a one-line pointer.
Checks the history. Before proposing a line it searches the file's history for its key phrase (git log -p -S). A change that reverses an earlier commit shows that commit and asks whether to reverse it. A mistake made at least twice that a lint rule, test or script can catch is proposed as that check, not as a line.
Proposes a minimal diff with three bullets linking each proposal to its evidence and naming removed duplication. With nothing durable to add, it says exactly NO CHANGES.
Prunes, in --prune mode. Every non-blank line that is not a heading gets one verdict: DELETE (discoverable from the code, duplicated, stale, contradicted, or a hedge that changes no behavior), REWRITE (a real rule that is vague or contradicts another line, with the new text) or KEEP. Every DELETE and REWRITE names its source. Truthfulness rules (requiring evidence, forbidding unverified claims, requiring failures to be reported) are never deleted. Checks it could not run are listed under NOT RUN, and their lines stay KEEP.

Example output

instruction-review --prune

| line | text | verdict | reason / source |
|---|---|---|---|
| 14 | Verify twice before committing. | DELETE | hedge; core rules "Before committing, run the validation" |
| 22 | Use pnpm. | REWRITE → "Use pnpm (pnpm-lock.yaml)." | contradicts line 31 "npm install" |
| 31 | Run npm install after pulling. | DELETE | contradicts line 22; package manager is pnpm (pnpm-lock.yaml) |
NOT RUN: `make e2e` (line 40) not executed
Totals: DELETE 2 · REWRITE 1 · ADD 0 · KEEP 37

Boundaries

Stops when

The proposed diff (or the prune table and diff) and its evidence are shown, or after NO CHANGES. It applies the diff only after you approve it, then reports the changed file. Inside the developer-os repository, a change to the plugin's core rules also adds its row to the rules history, in the same approved diff.

Never

Apply a change to the instruction file before you approve the diff.
DELETE a truthfulness rule.
Mark a line DELETE or REWRITE without naming its source.

docs-sync proposes the "Likely agent mistakes here" section and checks the rest of the docs.
session-retro proposes rule candidates at the end of a session.
Decisions, including the rules history.