pesi: a Claude Code plugin that enforces the path from design to merge

The problem

An AI coding agent chooses each next move by likelihood, so the same request can take a different path on each run. One session writes the tests first, the next skips them, and a third calls the work finished without a review. Instructions in a prompt or a skill make the right path more likely, but nothing guarantees it.

pesi’s aim is to make the results more deterministic by taking the process out of the model’s hands. The path is written down as data: three nested state machines, for the project as a whole, for each phase, and for the test-first loop, each with a table of the moves it allows. The pesi program checks that table before it is used: no state allows two different moves for the same event, and every state can be reached. The hooks ask the program before the AI acts. The AI still writes the code, but which step comes next, and whether the work may move on, is decided by the same rules every time.

What pesi does

pesi makes the AI follow one path: design, interrogate, plan, build, review, merge. Each stage checks its own thing, and work that fails a check can’t move on. The stations can only block or allow; you or the AI push the work forward.

Design in. Write DESIGN.md by hand, paste a design from elsewhere for pesi to restructure, or approve a plan in Claude Code’s plan mode.
The grill. A fresh session with no memory of how the design was written questions it one item at a time: inputs and outputs, failure modes and their severity, load, dependencies, documentation, and logging and tracing.
The plan. The design must be committed before a plan can be written. You accept the plan yourself; it’s the one step pesi won’t take for you.
Building. One fresh helper AI per task, run in parallel where tasks are independent. Test-first tasks are split between three roles that can’t do each other’s jobs: one writes the failing test, one makes it pass, one repairs a broken test without changing what it checks. An optional mutation-testing step, yellow, then plants deliberate bugs in the finished change to see whether its tests notice. It is in alpha, and it reports but never blocks.
Review. A panel of reviewers, each looking at one concern: correctness, security, test coverage, simplicity, or arguing against the change. Findings are tied to the exact commit reviewed.
Merge. Blocked unless the review covers the current code, no critical findings are open, every task is ticked off, the docs build and the logging check passes.

How it’s built

The skills guide the AI; the hooks and the pesi program block it when it skips a step.

Skills: about 35 reference guides the AI pulls in when they apply, from security and error handling to SQL, pipelines and incident write-ups.
Hooks: small scripts Claude Code runs before or after the AI’s actions. These do the actual blocking.
The pesi program: a compiled Go tool that remembers where the project is in the path and refuses moves that skip a stage.

pesi runs on Claude Code today. Support for Pi, a second AI coding tool with the same kind of hooks, is planned.

If a Claude Code setting has disabled hooks, every gate stops working at once. pesi detects that, warns loudly and refuses to continue rather than pretend you’re protected.