Zoo 3.2 asks better questions

Zoo 3.2 is available now. In the previous announcement, I said scripted reviews would likely be the focus of 3.2; well, here we are.

Before we get into the changes, I’ve also settled on four principles for Zoo:

1. Agents review and fix their shit before you have to deal with it.
2. Designed for easy reviews.
3. Collaboration with a high level of autonomy.
4. High quality at a reasonable cost.

See Zoo’s README for more details on each one.

Scripted reviews and the scout

Load-bearing holistic review gates can now be leveraged by everyone, in a testament to… What? You’re absolutely right; got carried away. Sorry.

LLMs work best when they have constraints, so your project should have dozens or hundreds of narrow rules for all sorts of important things.

And so, you got a super specific rule like, when you change Bar in foo.go, it has to frubernate a new widget.

How do you enforce that?

You could write a linter script. Sometimes it can flag violations fully deterministically. Often, though, it can only flag suspicious places, and LLM judgement is required to check each one for actual violations.

Also, turns out, LLMs give more reliable reviews if forced to answer a list of specific questions. These can range from wide ideas (“Is a simpler design possible?”) to those narrow rules you’re trying to enforce.

See where this is going?

Run a linter script (I call it “scout”). Have it produce a list of questions, some with code pointers (foo.go:25: Ensure this change frubernates a new widget or adopts an existing one). Feed that to the LLM and require a substantiated OK/FAIL/NA answer to each one.

That’s a scripted review.

Some questions can be very generic (Does a new document duplicate an existing one that could be extended instead?), but still only added when the change touches a certain type of file.

I’ve played with other ways to arrange these reviews (say, providing focused context for each question in an attempt to save tokens, or grouping questions into ones for fast/smart agents), but each was worse.

The new Zoo Tweak Reviews skill creates or updates your project’s scout. It comes with a reference design and instructions for turning project rules into checks and questions.

Final uber-review

The new 3.1 uber-reviews are a huge success in my book. They consistently caught missed aspects and edge cases, and helped improve the specs prior to implementation.

3.2 offers final uber-reviews on task completion. In a way, it’s not a typical review at all. I found myself using Zoo Ensure Safe Deploy skill manually for end-of-task reviews more and more often, and it has proven to really be the perfect prompt for that “gate”. (LLMs are teaching me their language. Cannot help it.)

So 3.2 accepts the reality and introduces a final uber-review, which runs Zoo Ensure Safe Deploy in the agents of your choice. Which should always include Codex. (When implementing in Codex, I ask it to do Claude and Codex.)

Because of how late the final review runs, all its findings require user approval before fixing, and it also offers wider and narrower fix suggestions now.

Mind you, Zoo Ensure Safe Deploy is NOT only focused on regressions and deployment; in practice, it finds every single edge case that the change fails to handle.

Uber-reviews are now sticky too; you can say “with uberreview” in your prompt, and Zoo automatically runs spec and final uber-reviews. (Never in a loop, though; that’d be a waste of tokens.)

De-Claude-ification

Now that Claude has started recognizing AGENTS.md, hopefully it’s a matter of time until it can also read .agents/skills. I’ve also gained enough cross-agent experience to conclusively say that I want .claude/skills to be a symlink to .agents/skills — so that’s what Zoo is doing now.

Personal overrides

Zoo 3.2 introduces $ZOO_LOCAL_MD for user-local customizations. Use it to customize uber-review setup on your machine (which agents should it run for which reviews?), and do other user-specific stuff (say I told my cli agents to put ticket numbers into cmux terminal badges).

I could just tell Zoo to read ~/.config/zoo.md, but that cannot be customized per-project, and what if you don’t want to give your Zoo full access to your machine.

I could use gitignore’d .zoo/zoo.local.md, but you’d have to reproduce it in each repository copy or worktree.

So it’s an env var. You can set it globally to ~/.config/zoo.md, or you can use something like direnv to set it per-project to a local file. I have all my repo copies under a single parent folder, and I’ve put my .envrc in there.

Tweaks

• Zoo Undo Change skill asks an LLM to restore the exact code from before so that an unwanted change leaves no accidental diff.
• Report format tweaks, including more consistent screenshot inclusion across agents.
• Updated terse writing style skill.

Installation

Ask your agent to install the skills from the Zoo repo, then run Zoo Init and Zoo Tweak Reviews. Use Zoo Upgrade Spec if upgrading from an older version to upgrade in-progress task files.