From Zero to Verifiable Spec-Driven AI Coding in Five Steps

Prerequisites: Harness Subagent Isolation and the Spec Target

Before installing plugins or running interactive commands, you need to understand the runtime environment this workflow demands. The Elephant-Goldfish Model is not a standalone agent; it is an orchestration pattern that relies entirely on your host harness providing programmatic subagent isolation.

In practice, this means your execution harness must expose primitives like invoke_subagent to spin up ephemeral child agents with wiped memories. Supported environments include agy CLI (version 1.4.10 or newer), Claude Code / Claude Cowork, and OpenAI Codex CLI. If your harness cannot spawn a fresh, clean execution frame, the review step simply runs inside the parent conversation thread. As I discussed in Five ways multi-agent coding breaks at context handoffs, running reviews in-thread causes total context contamination: the reviewing model inherits the designer's conversational history, accepts implicit shortcuts, and nods along with the initial reasoning.

The target outcome of this workflow is an explicit markdown specification—typically concepts_brief.md or a feature specification file under your documentation tree. A specification must survive adversarial, zero-history inspection before implementation begins. You are not generating production application code during this cycle. The end state is achieved only when the stateless reviewer validates that every architecture trade-off, API boundary, and failure mode is documented in black and white, followed by your explicit human approval. If a requirement is not written down, it does not exist.

Step 1: Installing the Full Plugin Tree Across Supported Harnesses

Installation mechanics depend on your runtime, but the requirement across all environments remains consistent: you must install the entire repository tree, not an isolated subset of prompt files.

For the Antigravity CLI, install the package from the repository URL:

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

If you are operating in Claude Code, add the marketplace source and install the package:

claude plugin marketplace add google/elephant-goldfish-model
claude plugin install egm@egm

For OpenAI Codex CLI, register the marketplace entry and add the plugin:

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

The table below summarizes harness support and command dispatch mechanics:

Harness Environment	Installation Command	Command Prefix Behavior	Subagent Isolation Mechanism
agy CLI (>= 1.4.10)	agy plugin install https://github.com/google/elephant-goldfish-model	Auto-resolves unprefixed or uses /egm:	Native invoke_subagent child contexts
agy CLI (1.4.8)	agy plugin install https://github.com/google/elephant-goldfish-model	Requires explicit /egm: prefix	Native invoke_subagent child contexts
Claude Code	claude plugin marketplace add ... && claude plugin install egm@egm	Requires explicit /egm: prefix	Ephemeral tool invocation forks
Codex CLI	codex plugin marketplace add ... && codex plugin add egm@egm	Uses skill picker / /egm: prefix	Sandboxed subagent forks
Antigravity IDE	Unsupported	Unsupported	None (lacks subagent tool primitive)

Selective directory extraction breaks because the review loops dynamically locate reviewer personas in agents/ and quality rubrics in resources/document_standards/. Always clone or install the full plugin tree rather than cherry-picking individual prompts into a project-local skill directory.

Step 2: Scoping Architecture Trade-offs with /egm-brainstorm

With the full plugin tree installed, initiate the stateful design phase. In this step, the primary agent adopts the role of the Elephant: an accumulator of intent, domain trade-offs, and system boundaries. Run the brainstorming command directly from your harness prompt:

/egm-brainstorm Add webhook delivery to this project.

If you are using agy CLI version 1.4.8, remember that issue #196 requires typing /egm:egm-brainstorm, whereas agy CLI version 1.4.10 automatically resolves the unprefixed command via issue #220.

sequenceDiagram
    autonumber
    actor User as User
    participant Elephant as Stateful Elephant Agent (/egm-brainstorm)
    participant Buffer as Draft Specification Buffer (concepts_brief.md)

    User->>Elephant: Run brainstorm command with feature goal
    activate Elephant
    Elephant->>User: Elicit system constraints, dependencies, and trade-offs
    User->>Elephant: Clarify architectural requirements and boundaries
    Elephant->>Buffer: Write initial architecture and decision log
    Elephant-->>User: Present synthesized trade-offs for review
    deactivate Elephant

During this sequence, the Elephant agent questions you on dependency constraints, execution environments, and throughput expectations. As the operator, your job is not to let the agent run on autopilot, but to govern technical boundaries. Keep human evaluation at the center of every architectural fork.

Here is an operational technique I rely on during the design phase: deliberately leave one critical operational requirement out of your explicit verbal answers. For instance, when designing webhook delivery, discuss payload shapes and signature verification, but intentionally leave out retry backoff policies and idempotency keys.

If you maintain a shared conversational thread without isolation, a standard downstream agent will guess or paper over the omission because it shares your train of thought. By leaving this gap in the Elephant's draft buffer, you construct a deliberate test: when the stateless Goldfish reviewer inspects concepts_brief.md in the next phase, it should immediately flag the missing retry mechanics as an undefined edge case.

Step 3: Compiling the Draft Specification into concepts_brief.md

Once you have shaped the architecture during brainstorming, you compile the conversational context into a formal document using the drafting command:

/egm-draft

The Elephant agent aggregates the raw conversational exchanges into a structured markdown document, typically emitted as concepts_brief.md or placed within your repository's design directory under docs/designs/. This transition marks the boundary where ephemeral chat history turns into a durable contract.

At this exact juncture, context engineering requires strict hygiene. The Elephant designer naturally accumulates broad awareness of your environment, but future review agents will inherit none of it. Every external contract, schema, and codebase file must be explicitly cataloged in the draft specification. If your feature touches an existing database model, an internal queuing library, or an external third-party webhook signature scheme, you must instruct the Elephant to cite the exact file paths and type definitions inside the document. In The Codebase Is an Environment, Not an Autoregressive Window, I noted that treating an assistant as a self-contained window instead of anchoring it to tangible repository structures guarantees drift. In EGM, an uncited dependency does not merely degrade fidelity; it becomes completely invisible to the reviewer.

Drafting also forces you to manage context budget inflation. When the Elephant attempts to synthesize full file implementations, verbose logs, and multi-turn discussions into a single draft, the prompt context balloons rapidly. In large repositories, this bloat strains the primary agent's output window and degrades reasoning precision. Structure your spec into compartmentalized sections: explicit interfaces, state transition invariants, error-handling guarantees, and concrete codebase paths. Keep code blocks limited to minimal interface signatures rather than complete function bodies. By enforcing lean, modular specification chunks, you conserve token budgets while ensuring that subsequent review forks receive dense, actionable grounding rather than sprawling conversational noise.

Step 4: Stress-Testing the Spec via Stateless Subagent Review Loops

With the draft specification written, you initiate the adversarial review phase using the review command:

/egm-review design_draft.md

In supported environments like agy CLI or Claude Code, this command triggers /egm-review-loop to launch ephemeral Goldfish subagents via the harness's invoke_subagent tool. Mechanically, the harness executes a clean context fork. The subagent receives the draft document (concepts_brief.md or your target design file), the explicitly referenced codebase files, and the evaluation rubrics located in resources/document_standards/. The entire parent conversation—the dozens of back-and-forth turns between you and the Elephant—is discarded.

flowchart TD
    subgraph ElephantContext["Elephant State (Accumulated Memory)"]
        direction TB
        E["Stateful Designer Agent"]
        T["Conversational History & Trade-offs"]
        E --- T
    end

    E -->|compiles| Spec["Draft Artifact: concepts_brief.md"]

    subgraph Fork["invoke_subagent Primitive"]
        direction TB
        F1["Zero-History Context Fork A"]
        F2["Zero-History Context Fork B"]
    end

    Spec --> F1
    Spec --> F2

    subgraph Standards["resources/document_standards/"]
        R1["Architecture Rubric"]
        R2["Edge-Case Standards"]
    end

    R1 --> F1
    R2 --> F2

    subgraph GoldfishContext["Stateless Goldfish Reviewers"]
        G1["Goldfish Subagent 1"]
        G2["Goldfish Subagent 2"]
    end

    F1 --> G1
    F2 --> G2

    G1 -->|critique| Feedback["Prioritized Gap Report"]
    G2 -->|critique| Feedback
    Feedback -->|reconcile| E

This context isolation is designed to eliminate cognitive inertia. When an agent spends forty turns building an architecture with you, it develops sycophancy: it assumes you both understand the implicit boundaries. A fresh Goldfish subagent has no memory of those exchanges. If your webhook spec mentions event delivery but never specifies payload signing algorithms, timeout ceilings, or retry backoff curves, the stateless reviewer identifies those missing definitions immediately because it cannot infer them from conversation history.

However, I take issue with the headline promise that context isolation completely cures alignment failures. The architecture has a glaring blind spot: a goldfish reviewer evaluates specifications purely within the vacuum of the provided context. If the Elephant agent omits a critical database locking mechanism, an external service quota, or an interacting microservice contract from the draft document, the stateless reviewer has no way of knowing that dependency exists. It cannot catch cross-system integration flaws that were never referenced. The Goldfish will happily rubber-stamp an internally coherent specification that fails catastrophic integration constraints in production. In Agent Memory Is an Indexing Problem, Not a Cognitive Subconscious, I argued that agents cannot reason about structures outside their retrieval index; EGM's stateless isolation guarantees objective review of what is written, but provides zero protection against what was forgotten.

Step 5: Detecting Code Divergence with Architectural Drift Reporting

Once your stateless Goldfish reviewers approve the document and you grant final human sign-off, you transition from design to implementation. EGM deliberately leaves code generation to your primary harness and your direct oversight. When bootstrapping a fresh codebase or scaffolding a new feature branch from concepts_brief.md, the primary agent constructs files aligned with the interfaces and boundary invariants documented in the spec.

The hardest operational challenge in spec-driven development is what happens after day one. In active repositories, emergency patches, quick hotfixes, and rapid follow-up commits routinely bypass formal design sessions. An engineer adjusts an endpoint return shape or alters an error code directly in the source tree to unblock a release. Without active governance, the specification silently rusts. If the Elephant agent later returns to design an adjacent subsystem, it will anchor its context to an obsolete document, propagating outdated assumptions back into the architecture.

To prevent this decay, EGM provides codebase bootstrapping and architectural drift reporting to measure divergence between active code and your documented design contracts. Architectural drift reporting must become a continuous verification habit rather than an optional post-mortem. You can run drift reporting directly through your harness to compare active file ASTs and type interfaces against the specifications stored in your design directory.

You can verify this detection loop through a straightforward outside check:

1. Open an implementation file generated from your spec and intentionally modify an established public interface—such as changing a webhook payload field from a string to an array or renaming a status enum.
2. Trigger EGM's architectural drift reporting within your harness.
3. You should see the harness parse the discrepancy, flagging the exact file, line number, and schema mismatch against the baseline in concepts_brief.md.

This confirmation proves your harness treats the specification as an active contract rather than static documentation.

Where the Spec Loop Breaks Down and What to Automate Next

Adopting EGM exposes concrete friction points that every operator must plan for before mandating it across a team. The first failure mode is context budget inflation during multi-lens Goldfish swarms. When you invoke reviewer swarms against non-trivial projects, the harness spawns multiple parallel child contexts. If your draft specification references expansive source files, each subagent ingests those references independently. Across frontier models, concurrent context ingestion rapidly drains API rate-limit pools and inflates inference costs, causing review loops to stall mid-turn on large repositories.

Platform-level review caps present a second operational barrier. In desktop environments like ChatGPT Desktop—which runs through a dedicated plugin identifier—or enterprise workspaces importing plugins via administrative paths, platform throttling and cloud review quotas frequently intercept high-concurrency subagent creation. If the host platform throttles parallel forks, your review loop either degrades to a sequential crawl or fails entirely.

Finally, developer ceremony fatigue is the human breaking point. EGM stops being effective the moment developers try to force every minor edit through its formal lifecycle. When an engineer needs to update an internal error string or tweak a CSS class, forcing interactive brainstorming and isolated reviewer critique introduces unnecessary friction. Teams quickly abandon tools that demand excessive ceremony for routine work.

To make this architecture sustainable in production, treat design specifications as version-controlled code artifacts governed by automated CI checks. The immediate next step is integrating architectural drift reporting directly into your pull request pipeline, failing merges whenever interface signatures diverge from docs/designs/ without a corresponding spec update. From there, automate spec-gated implementation triggers: once the Goldfish review passes and human approval is logged, automatically kick off the harness implementation agent with the finalized spec as its sole grounding prompt. Automated gating keeps the specification honest without requiring manual administrative overhead on every commit.

Resources

• GitHub - google/elephant-goldfish-model: Open-source plugin for designing and reviewing software with agents · GitHub
• raw.githubusercontent.com
• raw.githubusercontent.com