Most of this website is written by AI agents. I plan, they build, and I review. After a few months of that I noticed a pattern in my release notes: the same class of bug kept coming back. A new handler outlived the server's 15-second write timeout and nginx answered 502. I fixed it in v0.17.1, again in v0.17.2, again in v0.35.1 and once more in v0.37.7. Each time the agent that planned the handler also reviewed it, in the same session, with the same assumption: "this call is fast."

That is exactly the problem Google's Elephant-Goldfish Model (EGM) goes after. Google open-sourced it on 22 October 2026 as a plugin for Claude Code, Codex, Antigravity and a few other agent harnesses. I read the repository, the announcement, Dave Rensin's original essay and the better write-ups, then ran it against a real change to this site. This note is the tutorial I wanted when I started: what EGM is, how to use it step by step, what it found in my own setup, and where it falls short.

The idea in one paragraph

A long agent session slowly absorbs your assumptions. After two hours of "the edge already routes that path", the agent stops questioning it. EGM splits the work into three roles:

  • The Elephant is a long-running, context-rich session. It holds the project memory and the decisions, and it writes a design document. It writes no code.
  • The Goldfish are fresh sessions with no memory. Each one gets only the design document and the files it links to, and reviews it. If a Goldfish cannot understand the plan from the document alone, the document is not done.
  • You make the trade-offs, decide which findings matter and approve the design before anything is built.

Rensin sums it up in two lines from his essay: "Design is the new code" and "Feed the Elephant; test it against the Goldfish." Despite the name, EGM is not an AI model. It is Markdown: skills, reviewer personas and review rubrics, Apache 2.0, and the README says plainly that it is "not an officially supported Google product".

What is in the box

The plugin has three layers.

Seven skills (the commands you run):

  • egm-brainstorm: explore an idea under a no-code rule; a six-lens Goldfish swarm challenges it; output concepts_brief.md.
  • egm-draft: turn the brief or your notes into a design doc, one section at a time, pausing for your approval after each.
  • egm-review: the Goldfish protocol, five stages (below).
  • egm-review-loop: the dispatcher that runs a group of reviewers in parallel; egm-review uses it.
  • egm-resolve: work through findings; each one is classified as propose fix or contest, and only approved edits are applied.
  • egm-bootstrap: write a README.md per directory, bottom-up, for codebases with no docs (Rensin calls these READMEs "peanuts and hay" for the Elephant).
  • egm-drift-report: compare design docs and READMEs against the current code and flag what diverged.

Nine personas in agents/: zoom-out, comprehension, design critic, structural, style, implementation readiness, codebase details, a synthesizer that fans reviewers out and merges their findings, and a bootstrap orchestrator.

Document standards in resources/document_standards/: the rubrics the reviewers apply. Two of them are worth quoting because they changed how I write plans. The feature spec standard has an Alternatives Rule: a spec "fails this standard if it proposes a single path without proving that other viable designs were considered and rejected". The implementation readiness standard has a Zero-Decision Rule: the plan must leave "zero design or architectural choices to the implementer".

The five review stages

egm-review runs these in order, each with fresh subagents:

  1. Initial Zoom Out: is this the simplest design? YAGNI, reuse of existing code.
  2. Comprehension Test: a naive reader paraphrases the design back. If the paraphrase is wrong, the doc is ambiguous. This stage deliberately gets no rubric.
  3. Critic Review: design critic, structural and style reviewers in parallel: failure modes, scale limits, missing alternatives.
  4. Intermediate Zoom Out: re-checks whatever the previous stages made you add, so fixes do not bloat the design.
  5. Implementation Readiness: are file paths, signatures and test cases specific enough to transcribe into code?

Findings are graded 🔴 Blocker, 🟡 Major or 🟢 Nit and merged into a consolidated report with a traceability matrix. Two rules in the skill stood out to me. First, reports go to files, never into the chat ("chat dump prohibition"). Second, if the harness cannot create a fresh subagent, the review stops: "a review in the same context is not a Goldfish review."

Tutorial: install and run it

1. Install the whole plugin

In Claude Code (2.1.271 or later; the plugin's docs require it so reviewers can be started without your CLAUDE.md):

claude plugin marketplace add google/elephant-goldfish-model
claude plugin install egm@egm
# only where your setup needs activation:
claude plugin enable egm@egm

In Codex:

codex plugin marketplace add google/elephant-goldfish-model
codex plugin add egm@egm

In Antigravity: agy plugin install https://github.com/google/elephant-goldfish-model.

Install the full plugin, not just the skills/ folder: the skills read the personas and standards at runtime. Then start a new session; plugins load at session start. In Claude Code and agy the commands take the /egm: prefix, in Codex you pick the skill from the picker.

2. Brainstorm (optional, for fuzzy ideas)

/egm:egm-brainstorm Add webhook delivery to this project.

The agent asks questions, refuses to write code, and spawns six Goldfish to attack the idea (for webhooks: what happens when a delivery fails, or an event arrives twice?). The agreed direction lands in concepts_brief.md.

3. Draft the design

/egm:egm-draft

The Elephant writes design_draft.md section by section: overview, problem, goals and non-goals, open questions, critical user journeys (given/when/then), technical plan, alternatives, non-functional requirements, and a Detailed Implementation Plan naming every file to create or modify. It pauses after each section. Approved designs go to docs/designs/<feature>.md.

4. Review with the Goldfish

/egm:egm-review docs/designs/<feature>.md

You pick a preset: interactive (stop after each stage), consolidated (all five stages, one report), feature spec only, or implementation plan only. The skill splits the doc at the ## Detailed Implementation Plan heading: stages 1 to 4 review the part above it, stage 5 the part below. Expect a lot of output. Rensin estimates that about 30% of Goldfish suggestions are worth acting on; that is normal, not a failure.

5. Resolve, then get a human

Choose Resolve findings with agent at a checkpoint (or run egm-resolve) and accept or contest each finding. Each stage allows one re-audit, after which leftovers are recorded as accepted trade-offs. Then open a pull request so a person reviews the design. EGM "does not replace human oversight, but encourages it."

6. Implement, and watch for drift

Only now does a coding agent build, from the approved doc. If the output is far off, Rensin's advice is to fix the doc and restart, not to argue with the session. Run /egm:egm-drift-report weekly to catch code that moved away from its design.

Skip all of this for a one-line fix. Google's own guide says so.

A real-world example: the agents behind this site

Here is what this repository already had before EGM, and how it maps:

  • CLAUDE.md, loaded into every session, is the Elephant's memory: stack, hard rules and a decision log.
  • site-coordinator is an entry agent that reads CLAUDE.md, splits a request and routes it. It is the closest thing to the Elephant and to EGM's synthesizer.
  • Four specialists implement: site-frontend-engineer, site-seo-specialist, site-security-engineer and site-deployer.
  • Four project skills (site-spec, site-ops, site-seo, site-security) and seven rules (.claude/rules/: mock first, motion, English naming, no secrets, git workflow, gRPC catalog, security) act as rubrics.

What it already does well: the rules are concrete checks ("a new admin endpoint adds its gRPC catalog row", "every href goes through Site.safeUrl"), the coordinator is a natural fan-out point, and every agent must report what it verified and with which command.

What EGM made obvious it lacks:

  • No zero-context review. Every plan is reviewed by its author, in the same context. That is how the 502 came back four times.
  • Decisions are written after the fact. A design lives only in the chat until the feature ships; then a summary bullet goes into CLAUDE.md. There is no reviewable design before code.
  • An ever-growing Elephant. On 3 November 2026 CLAUDE.md has 74 decision bullets and about 61 KB, roughly 15,000 tokens loaded into every session, and it names 107 code paths that nothing checks. Its structure has already broken once: one release's bullet was pasted into the middle of another's sentence.
  • One model for everything. All agents run on the session's model, so even a fresh reviewer shares the author's habits.

The run: letting the Goldfish review my own setup

To test EGM honestly I let it review a change to this very setup. Playing the Elephant, I wrote docs/designs/goldfish-review-stage.md in EGM's own template. The design had three parts: a zero-context reviewer agent, a design-first step in the coordinator, and a make drift script that checks every path named in CLAUDE.md. Then, in a fresh session:

/egm:egm-review docs/designs/goldfish-review-stage.md uninterrupted

uninterrupted is the consolidated preset: all five stages, no checkpoints, one final report. It took about ten minutes and ran nine reviewer subagents: zoom-out twice, comprehension once, three critics and three readiness reviewers. They wrote six report files into the repo root.

One practical note first: I tried to run it headless with claude -p and it failed at once ("OAuth session expired"), because a child process does not get the interactive session's login. Run it in a normal session.

What came back

Before deduplication the stages produced 3 Blockers, 31 Majors and 42 Nits. The consolidated report merged them into 3 Blockers, 9 Majors and 6 groups of Nits, each traced back to the raw findings. The verdict was blunt: "Not ready to implement." The core idea held up in every stage. The details did not.

The findings that mattered:

  • 🔴 The coordinator cannot write files. My design had site-coordinator write the design doc, but its tools line is Bash, Read, Grep, Glob, Agent, Skill: no Write, no Edit. I had worked with that agent for weeks and never noticed. The reviewer checked the actual file.
  • 🔴 make drift would fail on its first run. CLAUDE.md contains ` backend/db/apply.sh --schema-only ` five times. My extractor would treat the whole command as a path and report it missing. It also has five brace lists with an empty option that my "expand braces" step did not define. The Zoom Out reviewer's advice was to cut the drift check from this design altogether.
  • 🔴 No Risks section. The feature-spec standard requires one, and I had skipped it.
  • 🟡 My Goldfish was not a goldfish. I wrote that the reviewer's "only input is the prompt", but a normal Claude Code subagent still loads CLAUDE.md, all 15,000 tokens of the Elephant's memory. The fix is omitClaudeMd: true in the agent's frontmatter, which is exactly what EGM's own reviewer personas set. I had nearly made the same mistake while running this experiment. When the headless run failed, my first idea was to imitate the stages with ordinary subagents. They would have read my CLAUDE.md.
  • 🟡 The motivating bug is not covered by any rule. My whole argument was the 502 that shipped four times, yet no rule file mentions the write timeout. A reviewer that uses my rules as its rubric would miss it too. The fix belongs in .claude/rules/site-security.md.
  • 🟡 The "feature or fix" threshold was still an Open Question, but the coordinator step relied on it as if settled. One criterion, "more than 3 files", cannot even be known before the design exists.
  • 🟡 The comprehension test caught an undefined loop. I said what happens before I approve, but not on rejection or after edits, and the coordinator would show me only the findings, not the paraphrase. The paraphrase is how you check the reviewer understood you at all.

The Comprehension reviewer's paraphrase was accurate, so the doc passed the basic "can a stranger follow this" test. Its six Majors were all places where I had relied on things I knew and never wrote down, such as what "Elephant" means, who writes the report, and what "fixing drift" in a history bullet would mean.

What I did with it

I applied all 12 action items in one revision. The drift check moved to "Future Improvements" with the three traps the reviewers found. The reviewer became read-only through its tools rather than by instruction. The coordinator gained Write/Edit, limited to docs/designs/. The 502 lesson became a rule. The reviewers also rejected five of their own suggestions in Stage 8 (for example a permission hook for secret files), with reasons. That is the Intermediate Zoom Out stage doing its job: keeping review fixes from bloating the design.

Signal versus noise: most of the 42 Nits were wording ("fresh eyes", arrows in prose, a stray footer). Of the 76 raw items, roughly a quarter changed the design, close to Rensin's "about 30%". Three of those were bugs I would otherwise have found only while implementing, and one (the missing Write tool) I would have found as a confusing failure in the middle of a session.

What I am changing (and what you can steal)

The reviewed design adds the missing Goldfish half to my setup without making the plugin a dependency:

  • A site-goldfish-reviewer agent with tools: Read, Grep, Glob and omitClaudeMd: true: it gets a design doc path and nothing else, reads that doc, the files it links and every rule in .claude/rules/, and returns a paraphrase plus 🔴/🟡/🟢 findings, which the coordinator saves to docs/designs/reviews/. My rules become its rubric, which also gives it the security lens EGM's default personas do not have.
  • Design first, for features only: a fixed trigger list (new endpoint or RPC, new page or admin tab, migration, new third-party host, new agent, skill or rule). When one matches, the coordinator writes docs/designs/<feature>.md, runs the reviewer, shows me the paraphrase and the 🔴/🟡 findings, and routes the work only after I approve. Bug fixes keep today's flow.
  • A new rule for long-running handlers (extend the write deadline or run async), so the bug that started all this is finally something a reviewer can check.
  • The CLAUDE.md drift check waits for its own design, because the review showed it was harder than it looked.

Generic lessons that apply to any agent setup:

  1. Turn your rules into rubrics. A Goldfish with nothing to check against produces opinions. Mine checks against seven rule files.
  2. Add a security reviewer. EGM ships with none. If your design touches auth, tokens or user input, write a persona for it (a custom reviewer is just a Markdown file with a name and a description).
  3. Check that your Goldfish is really a goldfish. In Claude Code a subagent loads CLAUDE.md unless its frontmatter says omitClaudeMd: true. And isolation covers context, not the filesystem: a Goldfish with Read and Grep can read any file in the repo. Tell it which files are off limits (.env, deploy secrets) and keep them out of its scope.
  4. Use a different model for reviewers when you can. A fresh context removes your transcript, not the model's blind spots. In Claude Code an agent's frontmatter can set model.
  5. Keep the Elephant lean. If your CLAUDE.md is a changelog, every session pays for it. Move history to design docs and keep the memory to rules and current decisions.

Caveats

  • Not official, not measured. "Thousands of Googlers use it" is Google's own claim; neither the repo nor the announcement publishes a productivity number.
  • Independence is partial. By default the Claude Code reviewers inherit the session's model. Digital Applied puts it well: fresh context reduces transcript carry-over, not model-level weakness.
  • It costs tokens and time. A full cycle is a six-lens brainstorm, a sectioned draft, five review stages and a human PR. Reviews spawn many subagents; one tester hit rate limits on Claude Cowork.
  • Docs become a second codebase. A docs/designs/ folder nobody reads is worse than none. Drift reports help only if someone runs them.
  • It needs subagents. Harnesses without fresh-context delegation cannot run a Goldfish review at all, by design.

My take: the ceremony is too heavy for most of what I ship, but the core move is cheap and it works. Write the plan down, hand it to someone with no memory of your conversation, and listen when they cannot follow it.

Sources

Update, 4 November 2026

A day after publishing this note I ran the Goldfish on what I had built from it, and fixed what it found. Two points above are now out of date: the design is implemented, and the "One model for everything" gap and the "drift check waits" item no longer hold as written.

The Goldfish reviewed its own design. I ran site-goldfish-reviewer on the design doc that created it: no blockers, 6 majors, 6 nits. The majors were the kind I could not see myself. The doc said "Implemented" while none of its checks had been run. Isolation rested on one frontmatter key and a model's word that it had not read CLAUDE.md. Failure cases were missing (a malformed report, approving with blockers open, reviews overwriting each other). "Changed endpoint" was too vague to apply. The coordinator's write access was limited only by a sentence in its prompt. And the long-handler rule had never been tested.

What changed

  • Reviewers run on a pinned model. Both pin Opus instead of whatever the session runs. If my session already runs Opus, they are the same model; I accept that.
  • A second reviewer for security. site-goldfish-security runs next to the first when a design touches auth, tokens, user input, a secret field, a new or changed endpoint, a new origin or a long-running handler. It has a severity scale and a fixed finding format. Some of its structure is adopted from agents in another private repository of mine.
  • Isolation is tested, not assumed. I planted a unique line in CLAUDE.md and ran both reviewers: it appeared in neither report. A permission rule refused a read of an .env test file, and a search for its contents returned nothing. The security reviewer also noticed that the repo had no .gitignore at all. It does now.
  • What the test cannot prove. Keeping CLAUDE.md out of the reviewers' searches is an instruction, not a hard block, and a file read that is never echoed would pass the marker test.
  • The Elephant is lean now. CLAUDE.md went from 409 lines (61 KB) to 79 lines (9.7 KB). The 66 per-release bullets moved unchanged into docs/history/, grouped by area, and what is still in force stays in a short "Current rules" list. A script checked that all 344 original lines are still there. That move had its own design, and the Goldfish reviewed it twice (one blocker and ten majors, then one blocker and six majors) before I touched a file.

The drift checker is built. make drift is a small Node script, also run by make test. It fails when a path or a link in CLAUDE.md no longer exists, or when the file passes 140 lines or 15,000 bytes. The traps that made me cut it from the first design were the first things I wrote tests for: commands with arguments, brace lists with an empty option, and shorthand paths. The Goldfish reviewed this design too and found a blocker I had missed: git's file list still shows a file renamed with a plain mv until it is staged, so the very case the tool exists for would have passed. Run on the old 409-line CLAUDE.md, it flags a reference to blog.html that had gone stale. Its limit: it checks that names exist, not that the sentence around them is still true, and a name that exists twice (such as README.md) passes while one copy remains.

The lesson I would add: run the reviewer on its own setup first. It found more in the reviewer's design than I did.

Read also