Review AI-Generated Biff Code Before the Agent Applies Fixes
The AI-written Biff code passes every test but ignores how the project is structured. What does the creator’s review skill check before the agent is allowed to fix anything?
- Biff’s review skill records convention violations and their locations in a dated checklist.
- The default workflow asks a person to verify that checklist before repairs begin.
- Auto mode skips the wait, but leaves the originally violated items unchecked for later human sign-off.
Inspect the findings before the agent changes the code
Biff’s new review workflow produces a file you can inspect before accepting a round of fixes. In his October 25 announcement of Biff 2.0.4, creator Jacob O’Bryant described turning the conventions he developed while reviewing AI-generated Biff code into a set of agent skills.
The biff-code-review instructions create a numbered checklist under .biff/review/, grouped by date. Rules without violations are checked off. A failed rule stays unchecked and gets a list of file names and line numbers.
The agent then gives the developer the path and asks them to verify the findings. You can add missed violations before repairs start. After handing over the checklist, the agent is instructed to preserve it; the user controls sign-off. That preserves the original findings for comparison with the code changes. It is an instruction to the agent, not a filesystem lock.
The checklist targets Biff conventions
The review looks for decisions that conflict with Biff’s project structure and programming patterns. The published rules file gives concrete criteria rather than asking for an undefined “clean code” pass.
| Code under review | What the Biff rules require |
|---|---|
| Dependencies between module namespaces | Modules must not require each other. Functions shared by multiple modules belong under lib. |
| Database access inside biff.fx state functions | State functions must be pure and use effect handlers for database operations, with an exception for reads from immutable databases such as XTDB or Datomic. |
| Queries requesting all attributes | Avoid [:*] in biff.graph queries when the needed attributes can be enumerated. |
These are Biff conventions, not universal restrictions on Clojure. Copying the checklist into another framework would require deciding which rules actually match that framework’s design.
The starter README also describes a separate biff-code-quality skill for running tests and lint checks and addressing failures. Completing a convention review does not establish that those checks passed.
Update the task dependency, then sync the project files
For an existing Biff project, the announced path is to update biff.tasks to 2.0.4 and run clj -M:run dev. The development command syncs the skills into the local project. The changelog records copying documentation into .biff/ and skills into .agents/, followed by the 2.0.4 review-skill update.
A new starter project requires Java 21 or later and Clojure. Once the files are present, check that your coding agent actually discovers the project’s .agents/skills/ directory. File delivery alone does not establish that an agent loaded or followed the instructions.
The review scope has a defined order: uncommitted changes first; otherwise, commits on the current branch that are not on main or master. If neither provides a target, the instructions tell the agent to ask what to review. Do not expect every invocation to audit the entire repository.
Auto skips the pause; fix resumes the latest review
Use the default flow when you need to inspect findings before repairs. Adding auto tells the agent to proceed from the newly created checklist directly to fixes. The originally violated items remain unchecked so a person can sign them off or request further changes afterward.
The fix argument instead directs the agent to the most recent review file and its outstanding findings. That gives a follow-up round a concrete target without rebuilding the list from a conversation.
For a team that wants a human checkpoint, the useful sequence is to read the findings, add omissions, and then authorize the repairs. The artifact to inspect is the checklist and its corresponding code changes, rather than the agent’s completion message alone.