When running in Codex or ChatGPT Work, first read Codex integration.
In Claude Code or Cowork, read ${CLAUDE_PLUGIN_ROOT}/docs/claude.md first.
Reviews and validates a design document through specialized reviewer personas.
A Goldfish runs in a fresh context with no conversation history. Spawn each
subagent with your harness's subagent tool (Antigravity: invoke_subagent; Claude Code: Agent; Codex: spawn_agent). Each subagent is defined in agents/<file>.md, and its
frontmatter name (for example egm-zoom-out) is the subagent type to request
where your harness registers named subagents. Otherwise spawn a general-purpose
subagent and tell it to read that persona file first. Pass the prompt verbatim
and wait for the report. If your harness cannot nest subagents,
use direct dispatch instead of the synthesizer. See docs/harnesses.md.
If your harness has no subagent tool, stop and tell the user: a review in the same context is not a Goldfish review.
presenting large proposals, drafts, summaries, or plans directly in the chat
pane. You MUST write them to the working directory (or your harness's
artifact directory, if it has one) using your file-writing tool and then
tell the user in chat the file path and ask for review. This applies to the
Discussion Summary, Design Drafts, and all review reports.
summaries, and communications in simple, direct, jargon-free plain English.
Explain technical mechanisms directly. Do not summarize away substance or
rely on buzzwords. Do not use ungrounded promotional adjectives (e.g.,
seamless, robust, blazingly fast) or decorative adverbs (e.g.,
seamlessly, effortlessly, literally, drastically, obviously).
directive is to stress-test ideas, strategies, and opinions. Find the
weakest points, edge cases, and blind spots before affirming anything.
"brilliant," or "smart." Compliments without substance are noise.
missing, or risky before highlighting its merits.
conclusion is asserted, do not validate it reflexively.
outline: What is the user not seeing? What is the strongest
counter-argument? Is the opposing view justified?
objective scrutiny.
validating adjectives like "brilliant," "great," "smart," "correct,"
"perfect," "excellent," or "spot-on" when referring to the user's inputs,
corrections, or decisions.
apologize," "I am sorry," "Forgive me") when challenged or corrected.
Instead, outline the corrected technical logic or trade-offs directly.
such as ask_question, if your harness has one, or plain chat) MUST contain
strictly one question (len(questions) == 1), be the sole tool call in the
turn, and provide clear, action-oriented options without (Recommended)
prefixes.
TargetFile: Absolute or relative path to the design document.GoldfishContext (Optional): Reading list to establish the systembaseline. If omitted, it holds only the linked files that Step 1.3 adds.
Step (Optional): Specific pipeline preset or stage to run (e.g.interactive, uninterrupted, feature_spec, implementation, or an
individual stage 5, 6, 7, 8, 9). If omitted, the user is prompted.
TargetFile is provided. If missing:analyze its structure and discover the semantic split.
use structured question tools such as ask_question, as providing an
arbitrary file path is an open-ended text input, not a choice between
fixed options) and end your turn.
TargetFile is provided, verify if GoldfishContext is provided (anempty list counts as provided, as does the user explicitly stating in their
prompt to proceed with no additional context). If missing:
optional, but can establish baseline knowledge for reviewers.
automatically, and that other links and URLs need approval.
additional context files. Do NOT use structured question tools for
open-ended file paths.
after the Step 2 preset is chosen and right before the first stage that
takes GoldfishContext (any stage but Stage 6), in any flow includinguninterrupted. Read TargetFile, skip anchor-only links (#...), drop
the #fragment from other links, and resolve each relative link against
the design document's folder. Add each link whose real path (after
following symbolic links) stays inside the working directory toGoldfishContext, skipping files that do not exist. If any link resolves
outside the working directory or is a URL, list those links in chat as
regular text, ask which to include, and end your turn; if no one can
answer, as in a headless run, leave them all out and keep going. Add only
approved ones and tell the user which were left out. Some reviewers cannot
open URLs, so save the raw page of each URL in GoldfishContext as a new
file in the working directory (or your harness's artifact directory) and
pass its absolute path instead. If a page cannot be saved, ask the user for
a local copy and end your turn; if no one can answer, as in a headless run,
leave it out, tell the user, and keep going. PassGoldfishContext to every stage except Stage 6, which reads the document
alone; tell any synthesizer to give these files to each reviewer.
Step parameter was explicitly provided during invocation (e.g.interactive, uninterrupted, feature_spec, implementation, or an
individual stage 5, 6, 7, 8, 9), map to the corresponding
preset or subflow and bypass the interactive preset selection gate.
Step was omitted), you MUST present the CuratedPipeline Presets single-select gate to the user (using a structured
question tool such as ask_question if your harness has one, or plain
chat).
(len(questions) == 1). Multi-question payloads are strictly forbidden.
You MUST yield execution immediately upon invocation.
is_multi_select MUST be false. Combinatorial multi-selectchecklists are strictly prohibited to protect topological dependencies
(5 → 6 → 7 → 8 → 9).
(Recommended) prefix).
```json
{
"questions": [
{
"question": "Select the review execution mode for this document:",
"options": [
"Interactive review with all review rubrics (step-by-step, check in after each review)",
"Consolidated report with all review rubrics (runs full flow without stopping)",
"Feature spec only (evaluate design without considering implementation)",
"Implementation plan only (evaluate design for implementation readiness)"
],
"ismultiselect": false
}
]
}
```
Interactive review with all review rubrics: Proceed toStep 3 to discover the semantic split, then execute Stages 5, 6, 7, 8,
and 9 sequentially with interactive checkpoint gates between stages.
Consolidated report with all review rubrics: Proceed toStep 3 to discover the semantic split, then execute all five stages
without pausing for checkpoints, consolidating findings intoconsolidated_review_report.md.
Feature spec only: **Bypass Step 3 semantic splitdiscovery entirely**. Set FeatureRange = 1..End, set `DetailedRange =
N/A`, and execute Stages 5, 6, 7, and 8 with checkpoints. Cleanly halt
review after Stage 8 before Stage 9.
Implementation plan only: Proceed to Step 3 to discoverthe semantic split, confirm DetailedRange, and jump directly to Stage
9 (Implementation Readiness Test).
Feature spec only) was selected,skip this step completely. Set FeatureRange to cover the entire
document (lines 1 through End) and proceed directly to Step 4.
TargetFile to inspect its structure and linecount.
Detailed Implementation Plan (or standard synonyms: ## Implementation
Plan, ## Work Breakdown, ## Implementation Steps`).
identified at line $L$:
FeatureRange = 1..(L-1).DetailedRange = L..End.`"Discovered semantic boundary at line L. FeatureRange: 1..(L-1),
DetailedRange: L..End."`
conflicting headers or non-standard structures exist:
as ask_question with len(questions) == 1, or plain chat)
proposing the most likely split line as Option 0, with Option 1
allowing custom line ranges via write-in.
high-level feature specification:
FeatureRange = 1..End and DetailedRange = N/A.Once the semantic split and execution preset are confirmed:
FeatureRange and DetailedRangeare bound.
6 → Stage 7 → Stage 8 → Stage 9 sequentially.
Uninterrupted Full Flow.
then cleanly halt.
Readiness Test).
All interactive review stages conclude with an explicit single-select gate
(using a structured question tool such as ask_question withlen(questions) == 1, is_multi_select: false, sole tool call in turn, or
plain chat):
Proceed to next stage: Stage [N+1] ([Next Stage Name])(or Conclude review and begin detailed implementation planning for
Stage 8 terminal).
when edits are complete to re-run)`.
Pause Review (save progress and exit).Proceed to next stage: Stage [N+1] ([Next Stage Name])(or Conclude review and finalize document for Stage 9 terminal).
fixes, and apply approved edits)`.
chat when edits are complete to re-run)`.
Pause Review (save progress and exit).egm-resolve in the primaryElephant context window on the target range (FeatureRange orDetailedRange), passing the parsed findings from critic_report.md orimplementation_readiness_report.md.
FIX vs CONTEST), writes goldfishreviewreport.md`, and executes
approved edits on TargetFile via file editing tools.
TargetFile torecalculate line bounds, and either advance to the next stage or re-run
the stage audit (enforcing max 1 re-audit limit).
manual document edits, and yields execution immediately.
edits are complete:
TargetFile to recalculate line shifts.re-audit. If manual doc updates are requested again after a
re-audit, inform the author that the cap is reached, document
residual findings as accepted trade-offs, auto-bind Option 0, and
advance to the next stage.
Pause Review):artifacts.
sequence without interactive checkpoint pauses between steps. For each
stage, write the individual report file to the working directory (or your
harness's artifact directory, if it has one). Pass GoldfishContext to
every step except Step 6.
egm-synthesizer (or directsubagent) with Reviewers: [egm-zoom-out, egm-inventive-catalyst] onfull file → write zoom_out_report.md.
egm-comprehensionsubagent directly (not the synthesizer) on FeatureRange &DetailedRange → write its complete result tocomprehension_report.md.
egm-synthesizer (or directsubagents) with Reviewers: [egm-design, egm-structural, egm-style] onFeatureRange → write critic_report.md.
egm-synthesizer (or directsubagent) with Reviewers: [egm-zoom-out] on full file → writeintermediate_zoom_out_report.md.
egm-synthesizer (ordirect subagents) with `Reviewers: [egm-implementation-readiness,
egm-codebase-details, egm-style] on DetailedRange` → writeimplementation_readiness_report.md.
Major, 🟢 Nit).
items.
consolidated_review_report.md usingyour file-writing tool.
consolidated_review_report.md (give its path).
egm-synthesizer (or thespecialized egm-zoom-out subagent at agents/zoom_out.md) on full file
applying resources/document_standards/zoom-out-standard.md. When running
as Step 8 (Intermediate Zoom Out), include zoom_out_report.md path in
context and focus on additions/mitigations from Comprehension and Critic
stages. When running as Step 5, also
spawn egm-inventive-catalyst in parallel and write both intozoom_out_report.md.
In both Stage 5 and Stage 8, pass GoldfishContext.
zoom_out_report.md (Stage 5) orintermediate_zoom_out_report.md (Stage 8) using your file-writing tool.
the report file (give its path).
Gate Protocol:
Findings written to zoomoutreport.md. How would you like to
proceed?", Option 0: "Proceed to next stage: Stage 6 (Comprehension
Test)"`.
Zoom Out) completed. High-level architecture verified. How would you
like to proceed?", Option 0: "Conclude review and begin detailed
implementation planning"`.
Zoom Out) completed. Findings written to
intermediatezoomout_report.md. How would you like to proceed?"`,
Option 0: `"Proceed to next stage: Stage 9 (Implementation Readiness
Test)"`.
notify me in chat when edits are complete to re-run)"` and Option 2:"Pause Review (save progress and exit)".
egm-comprehension subagentat agents/comprehension.md on FeatureRange & DetailedRange with no
document standard. Do not use the synthesizer: its report keeps only
findings, and the author must see the paraphrase. The test is self-containment,
not detail. Do not apply re-implementation-standard.md: it asks for
code-level detail, which the Zoom Out standard forbids in FeatureRange.
comprehension_report.md using your file-writing tool. Start with the two
paraphrase headings verbatim, then the findings. Keep the paraphrase when
there are no findings.
comprehension_report.md (give its path).
comprehension_report.md. How would you like to proceed?"`
"Proceed to next stage: Stage 7 (Critic Review)"when edits are complete to re-run)"`
"Pause Review (save progress and exit)"egm-review-loop in-thread onFeatureRange with reviewers [egm-design, egm-structural, egm-style],
standards `{"egm-design": "feature-spec-standard", "egm-structural":
"feature-spec-standard"}, and GoldfishContext`.
critic_report.md (give its path).
critic_report.md. How would you like to proceed?"`
Review)"`
fixes, and apply approved edits)"`
when edits are complete to re-run)"`
"Pause Review (save progress and exit)"egm-resolve in the primary Elephant context on FeatureRange,passing findings from critic_report.md (orgoldfish_review_report.md).
TargetFile using file editingtools.
TargetFile to recalculate linebounds, and advance to Stage 8 (or re-run Stage 7, max 1 re-audit).
egm-review-loop in-thread onDetailedRange with reviewers `[egm-implementation-readiness,
egm-codebase-details, egm-style]` and standards
`{"egm-implementation-readiness": "implementation-readiness-standard",
"egm-codebase-details": "implementation-readiness-standard"}`, andGoldfishContext.
implementation_readiness_report.md (give its path).
written to implementationreadinessreport.md. How would you like to
proceed?"`
"Conclude review and finalize document"fixes, and apply approved edits)"`
when edits are complete to re-run)"`
"Pause Review (save progress and exit)"egm-resolve in the primary Elephant context on DetailedRange,passing findings from implementation_readiness_report.md (orgoldfish_review_report.md).
TargetFile using file editingtools.
TargetFile to recalculate linebounds, and conclude the review session (or re-run Stage 9, max 1
re-audit).