pi-auto-review

Event-driven project review for Pi — automatically scans for problems after work completes, writes findings to TODO.md, and optionally auto-fixes them.

The Point

This extension is invisible to the agent. No commands, no skills, no markers, no branding. Reviews trigger automatically when configured conditions are met — the agent just receives a follow-up message and does the work.

Install

pi install /path/to/pi-auto-review

How It Works

Ralph loop done → review → TODO.md → fix → re-review → fix → re-review (clean) → ✅

1. Work completes (Ralph loop done, agent finishes, session starts)
2. Review triggers automatically — scans for problems, writes TODO.md
3. If autoFix: true — agent fixes items, then re-reviews
4. Fix loop continues until project is clean or max rounds hit
5. Convergence check — if fixes cause MORE problems, bail immediately

The fix loop is bounded

• maxFixRounds (default 3) — hard cap
• Divergence detection — if a re-review finds MORE items than before, stops immediately
• Clean exit — 0 items → done right away

Triggers

Trigger	Default	Description
onRalphDone	true	Auto-review when a Ralph loop completes
onAgentEnd	false	Auto-review after any agent finishes (after minTurns)
onSessionStart	false	Auto-review when a session starts

Configuration

Add to .pi/settings.json (project) or ~/.pi/agent/settings.json (global):

{
  "autoReview": {
    "enabled": true,
    "todoPath": "TODO.md",
    "autoFix": false,
    "maxFixRounds": 3,
    "onRalphDone": true,
    "onAgentEnd": false,
    "onSessionStart": false,
    "minTurns": 3,
    "cooldownMs": 120000,
    "scope": "full",
    "excludePatterns": ["node_modules", ".git", "dist", "build", "coverage"]
  }
}

Settings Reference

Setting	Type	Default	Description
enabled	boolean	true	Master toggle — disable without uninstalling
todoPath	string	"TODO.md"	Path to the todo file
autoFix	boolean	false	After building the todo, go fix the problems
maxFixRounds	number	3	Max review→fix→re-review loops
onRalphDone	boolean	true	Auto-review when Ralph loop completes
onAgentEnd	boolean	false	Auto-review after agent finishes
onSessionStart	boolean	false	Auto-review on session start
minTurns	number	3	Minimum turns before onAgentEnd fires
cooldownMs	number	120000	Minimum ms between auto-reviews
scope	"full"|"staged"|"diff"	"full"	Review scope
excludePatterns	string[]	["node_modules", ...]	Directories to skip
prompt	string|null	null	Custom first-review prompt
rereviewPrompt	string|null	null	Custom re-review prompt. Placeholders: {round}, {maxRounds}, {previousItems}, {focusAreas}
fixInstruction	string|null	null	Custom instruction appended when autoFix is on
focusAreas	string[]|null	null	Override default list of things to look for

Fix-Only Philosophy

Auto-review finds what's broken, not what's missing:

• ✅ Build errors, type errors, lint failures
• ✅ Failing tests, missing tests
• ✅ Security vulnerabilities, hardcoded secrets
• ✅ Broken imports, dead code
• ✅ FIXME/HACK markers (bugs, not ideas)
• ✅ Debug leftovers (console.log in prod)
• ❌ Feature requests ("add dark mode")
• ❌ Architecture proposals ("should use microservices")
• ❌ Nice-to-haves ("consider using X pattern")

Custom Prompts

All prompts are customizable. Use null or omit to keep defaults.

{
  "autoReview": {
    "prompt": "Focus on TypeScript strict mode errors and security issues in the API routes.",
    "rereviewPrompt": "Check round {round}/{maxRounds}. Previously found {previousItems} issues.",
    "fixInstruction": "Fix each item, then run the test suite to verify.",
    "focusAreas": [
      "Type errors in src/api/",
      "Security issues (hardcoded secrets, eval usage)",
      "Failing tests"
    ]
  }
}

Note: format instructions (TODO.md markers, _Items found: N_) are always appended, even with custom prompts. This ensures the fix loop's item counting works correctly.

Cooldown

2-minute cooldown by default (cooldownMs: 120000). Prevents review spam when multiple events fire close together.

License

MIT