The Problem

Developers often need a lightweight, AI‑driven workflow that lets them draft architectural decisions and then have an independent reviewer surface hidden assumptions. Existing tools either lock you into a single vendor or require complex orchestration. This repo delivers a plug‑in that works across several assistants (Claude, Codex, Antigravity) and keeps the design and review stages separate, reducing cognitive load during specification.

What This Does

The plugin contains Elephant and Goldfish agents.

  • Elephant (.claude-plugin/agents/codebase_details.md, .cursor-plugin/agents/codebase_details.md) gathers context, drafts a specification, and writes concepts_brief.md.
  • Goldfish agents (.claude-plugin/agents/design_critic.md, .cursor-plugin/agents/design_critic.md) read the draft and the project source without the conversation history, flaging assumptions and blind spots.

The workflow is triggered by commands such as /egm-brainstorm, /egm-draft, and /egm-review. The plugin files live under .claude-plugin, .cursor-plugin, or .codex-plugin, and are packaged into distributions/claude/.claude-plugin.

How It Is Wired

Execution starts when an assistant loads the plugin. The runtime reads plugin.json in the chosen sub‑folder (e.g., .claude-plugin/plugin.json) and registers each markdown file as an agent.

  1. Entry Point – The assistant’s plugin loader calls the install handler defined implicitly by the presence of plugin.json.
  2. Agent Dispatch – Commands such as /egm-draft map to the agent file agents/draft.md (not shown but generated from the skill definition). The agent’s prompt section invokes the assistant’s LLM and writes output files (design_draft.md).
  3. Review Flow – The design_critic.md agent is invoked automatically by the /egm-review command. It reads the draft from the filesystem, parses it, and returns findings.
  4. Side Effects – Only filesystem writes occur (concepts_brief.md, design_draft.md). No network calls happen in the plugin itself; any external interaction is handled by the assistant’s own API layer.

The import graph shows 33 internal modules with only two import edges, confirming a flat dependency structure. The most connected modules are test helpers (tests/unit/test_harnesses, tests/unit/test_copilot_adapter), which do not affect runtime logic.

How To Use It

  1. Install ``bash agy plugin install https://github.com/moses-y/elephant-goldfish-model ` or for Claude `bash claude plugin marketplace add google/elephant-goldfish-model claude plugin install egm@egm ``
  2. Configure – No additional config files are required beyond the plugin’s own plugin.json.
  3. Run – In an assistant session, invoke the desired skill: ``text /egm-draft ` The assistant writes design_draft.md in the current project root. To review, run `text /egm-review design_draft.md ``

Real‑World Use

A team working on a micro‑service can use the plugin to draft a new API endpoint:

/egm-brainstorm Add pagination to the user list endpoint.

The Elephant agent collects existing route definitions, drafts a spec, and writes concepts_brief.md. The Goldfish agent then reviews the spec, flags missing error handling, and returns a concise report that developers can act on before coding.

Code Health & Issues

  • High – Commit a lockfile beside pyproject.toml – No lockfile; risk of transitive changes.
  • High – Replace wildcard CORS origin – site/scripts/verify-analytics.mjs uses access-control-allow-origin: '*'.
  • Medium – Gate pull requests on a dependency vulnerability scan – .github/workflows lack dependency-review-action.
  • Low – Set timeout‑minutes on workflow jobs – deploy-site.yml has no timeout-minutes.
  • High – Deep nesting – Tests contain functions with 8‑level indentation, hard to follow.
  • Medium – Duplicated code blocks – Several helper snippets repeat across adapters/opencode/install.py, scripts/prepare_release.py, and component Astro files.
  • Medium – Broad exception handling – scripts/prepare_release.py swallows all Exception types.
  • Medium – High branching density – tests/integration/cursor_child_reads.py has 32 branch points in 91 lines.

The Bottom Line

Elephant‑Goldfish Model gives teams a lightweight, cross‑assistant design‑review workflow that separates drafting from reviewing. The core logic lives in human‑readable Markdown agent files, keeping the codebase minimal and maintainable. The main gaps are missing lockfiles and CORS configuration, but the overall architecture is sound for use in CI‑driven design reviews. Developers who need a quick, AI‑augmented design loop should adopt it, provided they address the identified high‑severity issues.