EGM-Lite: Rapid Ad-Hoc Engineering Protocol¶
- Author: Jonathan Njeunje (@njeunje)
- Status: Proposed
- Date: 2026-11-10
Overview¶
EGM-Lite (/egm-lite) adapts the Elephant-Goldfish Model (EGM) for small, rapid iterations,
specification revisions, code refactors, and bug fixes without requiring a full multi-document lifecycle. It enforces
a decoupled 5-phase state machine with explicit Elephant and Goldfish persona switching:
Phase 1: Critique Pause (Elephant (Critic)), Phase 2: Lightweight Execution Checklist
(Elephant (Planner)) followed by a Spec Review (Goldfish (Specification Reviewer via
Subagent)) that the user can skip, Phase 3: Scope-Contained Execution (Elephant (Builder)),
Phase 4: Adversarial Diff Review (Goldfish (Reviewer via Subagent)), and Phase 5:
Post-Review Resolution Gate (Elephant (Resolver)).
The Problem¶
Executing the full EGM lifecycle (/egm-brainstorm -> /egm-draft -> /egm-review) for small
changes introduces unnecessary process overhead. Conversely, unconstrained agent execution defaults
to:
- Ungrounded code edits without verifying upstream contracts.
- Speculative abstractions and out-of-scope refactoring (YAGNI).
- Self-validation masking edge cases and regressions.
EGM-Lite provides an on-rails middle ground with isolated verification gates and fast turnaround.
Non-Goals¶
- Replace the full EGM design lifecycle for architectural changes.
- Perform a same-context review when an isolated reviewer is unavailable.
- Expand implementation beyond the approved checklist or make review mandatory.
System Architecture & Decoupled State Machine¶
Transitions between phases occur strictly upon explicit user command triggers and asynchronous subagent completion:
- Code References & IDE Navigation: All phases link referenced local files, symbols, and line ranges using clickable links, and cite external contracts via symbol or definition queries.
- Plain-English
> **BLUF:**Blockquotes: Phases that require a> **BLUF:**open with a concise single-paragraph blockquote (followed by---) stating the plain-English takeaway and recommended action without raw IDs, code literals, or line links. - Decoupled Phase Triggers: Transitions occur strictly on user commands.
Phase 1 leads only to the checklist. From the checklist, developers can fast-path to
Phase 3 (
exec) without a spec review and review the result afterwards. The Phase 2B spec review and the Phase 4 diff review (review/goldfish) are Goldfish reviews that the user can skip; neither is mandatory. - Adaptive Gating: Phase 2A checks the checklist against fixed complexity criteria and recommends the spec review for non-trivial changes or direct execution for routine ones. The developer chooses; the recommendation never adds a mandatory step.
- Command Routing & State Advisory:
reviewandgoldfishare aliases bound to the most recently completed phase. After Phase 2A or Phase 5 spec triage they start the Phase 2B spec review. After Phase 3 or Phase 5 diff triage, or with no task in progress on an existing diff, they start the Phase 4 diff review. An out-of-order command (a review with nothing to review, or a spec review before a checklist exists) returns a> **BLUF:**state advisory that names the valid next command. - Subagent Integrity Guard: Phases 2B and 4 require an isolated, fresh-context subagent
tool (
invoke_subagent). In single-agent environments without subagent capabilities, the protocol halts and informs the developer rather than executing a biased, same-context self-review. - Non-Sycophantic Posture: All phases lead with technical risks, trade-offs, or defects and forbid flattering adjectives or polite apologies.
flowchart TD
Start(["/egm-lite <task>"]) --> CritiquePause
CritiquePause["Phase 1: Critique Pause<br/><i>(Elephant Critic)</i>"]
CritiquePause -->|"checklist"| ChecklistPhase
subgraph SpecStage ["Specification & Planning (Adaptive Gating)"]
direction TB
ChecklistPhase["Phase 2A: Checklist<br/><i>(Elephant Planner)</i>"]
SpecReview["Phase 2B: Spec Review<br/><i>(Goldfish Subagent)</i>"]
SpecResolution["Phase 5: Spec Triage<br/><i>(Elephant Resolver)</i>"]
ChecklistPhase -->|"review / goldfish"| SpecReview
SpecReview -->|"Findings / LGTM"| SpecResolution
SpecResolution -->|"checklist"| ChecklistPhase
SpecResolution -->|"review / goldfish"| SpecReview
end
subgraph DiffStage ["Implementation & Diff Review"]
direction TB
ExecPhase["Phase 3: Scope-Contained Execution<br/><i>(Elephant Builder)</i>"]
DiffReview["Phase 4: Adversarial Diff Review<br/><i>(Goldfish Subagent)</i>"]
DiffResolution["Phase 5: Diff Triage<br/><i>(Elephant Resolver)</i>"]
ExecPhase -->|"review / goldfish"| DiffReview
DiffReview -->|"Findings / LGTM"| DiffResolution
DiffResolution -->|"exec"| ExecPhase
end
ChecklistPhase -->|"exec / Proceed"| ExecPhase
SpecResolution -->|"exec / Proceed"| ExecPhase
DiffResolution -->|"checklist"| ChecklistPhase
DiffResolution -->|"LGTM, or all findings contested"| Done(["Complete"])
ExecPhase -->|"no review requested"| Done
ExistingDiff(["review / goldfish on an existing diff"]) --> DiffReviewPhase 1: Critique Pause (/egm-lite)¶
- Persona: Elephant (Critic) — Adversarial, skeptical. It works with the full conversation context, so it is an Elephant; the zero-context Goldfish reviews run in Phases 2B and 4.
- Grounding & BLUF: Probes target files, direct callers or tests, any existing directory
README.mdor user-cited doc, and repository definitions before proposing solutions, leading with a> **BLUF:**on whether the approach is ready forchecklistor blocked. - Contract Tracking: Tags assumptions as
[⚠️ UNVERIFIED](untested contracts) or[⏳ ACK](scheduled for empirical test). - Alternatives Considered: When multiple viable approaches exist, documents trade-offs in
egm_lite_alternatives.md(led by a> **BLUF:**on the recommended option and trade-off) and links the artifact in chat without inline discussion (omitting it for trivial or single-path tasks). - Completion Gate: Halts execution; awaits the
checklistcommand. Anexec,revieworgoldfishcommand at this point returns a state advisory directing the user to generate a checklist first.
Phase 2: Lightweight Execution Checklist & Spec Review¶
Phase 2A: Checklist Generation (checklist)¶
- Persona: Elephant (Planner) — Structured, methodical.
- Artifact Generation: Writes or updates
egm_lite_checklist.mdstructured into three canonical sections:- Targets & Tasks: Ordered checklist items as GFM checkboxes (
- [ ]) linking exact file paths and line ranges or tooling commands with brief rationales. - Pre-Review Exclusions: Explicitly agreed scope boundaries suppressed from review.
- Accepted CONTEST Rationales: Settled false-positive findings retained across iteration loops to prevent redundant review flags.
- Targets & Tasks: Ordered checklist items as GFM checkboxes (
- Spec Gating (Adaptive Gating): Evaluates the checklist against fixed complexity criteria
(two or more production code files, async/concurrency, public APIs, or
[⚠️ UNVERIFIED]/[⏳ ACK]tags) and opens the gate with a> **BLUF:**that recommends the spec review (goldfishorreview) for non-trivial tasks, or says direct execution (exec) is reasonable for routine fixes and doc-only edits. - Completion Gate: Offers both commands in every case and halts execution until the user
types
goldfish/reviewor clicks Proceed / typesexec.
Phase 2B: Stateless Spec Review (goldfish / review)¶
- Persona: Goldfish (Specification Reviewer via Subagent) — Isolated, zero-context auditor.
- Subagent Isolation: Spawns an isolated subagent (role "Goldfish Specification
Reviewer") and injects the full markdown content of
egm_lite_checklist.mdinto its prompt. On a re-review from Phase 5, first updates the checklist with the agreed revisions. If no fresh-context subagent tool is available, stops and offersexec/ Proceed on the checklist instead. - Spec Review Rubric: Enforces a strictly binary output contract (
[✅ LGTM]on zero findings) across four dimensions, skipping pre-review exclusions and acceptedCONTESTrationales and forbidding AST or code-diff checks, since nothing is implemented yet:- Scope Containment & YAGNI: Targets stay within the task and add no unrequested abstractions.
- Contract & Invariant Tagging: External dependencies and untested boundaries carry
[⚠️ UNVERIFIED]or[⏳ ACK]. - Edge Cases & Failure Modes: Error handling, timeouts, and boundary conditions are mapped.
- Test Plan Actionability: Test targets or empirical validation steps are concrete and runnable.
- Completion Gate: Halts execution after spawning the subagent and awaits its asynchronous response.
Phase 3: Scope-Contained Execution (exec)¶
- Persona: Elephant (Builder) — Focused implementer.
- Artifact Initialization: After a completed checklist or a verified specification (from
Phase 2A, Phase 2B, or a Phase 5 spec LGTM), reads
egm_lite_checklist.mddirectly without re-creating it. On the fast path from Phase 5 with agreed revisions or fixes, first creates or updatesegm_lite_checklist.mdbefore modifying any file or running commands. - Boundary Enforcement: Applies any inline comments left on
egm_lite_checklist.mdand executes only approved items and targets in the checklist, across code, specifications, or design documents; zero speculative logic. - Code Standards: Adds inline comments on non-obvious or complex logic blocks.
- Test Verification & Self-Repair: Runs local tests covering affected targets with autonomous monotonic convergence (not applicable, or a linter, for doc-only edits).
- Checklist Progress: Updates
egm_lite_checklist.mdmarking completed tasks with- [x]after test verification passes, leading with a> **BLUF:**on escalation halts, autonomous self-repairs, or multi-file summaries while omitting it on clean single-target runs. - Completion Gate: Prompts for
revieworgoldfishand halts execution with a strict negative constraint forbidding subsequent phases until triggered. The diff review is a Goldfish review that the user can skip: the gate recommends it whenever Phase 3 edited files, and the user can end the task without it.
Phase 4: Adversarial Diff Review (review / goldfish)¶
- Persona: Goldfish (Reviewer via Subagent) — Isolated, zero-context auditor.
- Entry: Runs after Phase 3 or Phase 5 diff triage, or with no task in progress on an existing diff (workspace changes, or a diff or pull request the user supplies). With nothing to review it returns a state advisory.
- Subagent Isolation: Evaluates the clean VCS diff against the checklist in a fresh subagent
context, spawned as "Goldfish Reviewer" (
invoke_subagent,Agent, orspawn_agent, stopping if no fresh-context subagent tool is available), with zero conversational bias, skipping pre-review exclusions and acceptedCONTESTrationales recorded in the checklist and suppressing stylistic nitpicks. - Diff Review Rubric: Enforces a strictly binary output contract (findings only vs.
explicit
[✅ LGTM]on zero findings) across five dimensions. For doc-only diffs, the first three are replaced by checks for factual consistency against the approved checklist, clarity, link hygiene, and markdown line length:- Thread & State Safety: Race conditions, deadlocks, async mutations.
- Boundary Conditions: Null checks, off-by-one, unhandled errors.
- Test Coverage & Regression Audit: Unit test coverage of all new branches.
- YAGNI Audit: Pruning unneeded abstractions.
- Contract & Tag Audit: Verification that
[⚠️ UNVERIFIED]and[⏳ ACK]tags are tested and removed.
- Completion Gate: Halts execution after spawning the subagent and awaits its asynchronous response.
Phase 5: Unified Post-Review Resolution Gate (Subagent Response)¶
- Persona: Elephant (Resolver) — Contextual triage.
- Response Routing: Uses the phase that spawned the review (Phase 2B or Phase 4, identified by the subagent role) to decide whether it is handling a spec review or a diff review response.
- Strict Non-Mutating Triage: The Elephant Resolver operates strictly in
read-only presentation mode and is forbidden from modifying application source files
during triage. Approved fixes are staged into
egm_lite_checklist.mdto be executed under a subsequentexecorchecklistturn. - Finding Triage (
PROPOSE FIXvs.CONTEST): Cross-references subagent findings against the codebase or spec without making code edits or running VCS mutations, opening with a> **BLUF:**led by[🛠️ X FIX | 🛡️ Y CONTEST]before presenting numbered and priority-tagged items ([X] [PY], e.g.,[1] [P0],[2] [P0],[3] [P3]) in a structured bullet list or compact comparison table sorted within each group in descending severity order (P0>P1>P2>P3, regardless of tier gaps), groupingPROPOSE FIXpatches ahead of codebase-backedCONTESTfalse alarms (bypassed by default). - Completion & Synchronization Gate:
- Pre-Implementation (Spec Review): A clean pass, or the user confirming that all findings
are contested or dismissed, stamps the checklist
Verified [✅ LGTM]and prompts forexec/ Proceed. It never closes the task. Remaining findings prompt forchecklistto revise,execto implement, orgoldfish/reviewto re-review. - Post-Implementation (Diff Review): A clean pass, or the user confirming that all
findings are contested or dismissed, opens with a
> **BLUF:**led by[✅ LGTM]and summarizes modified files and passing tests; otherwise promptschecklist(or fast-pathexec) if flaws remain.
- Pre-Implementation (Spec Review): A clean pass, or the user confirming that all findings
are contested or dismissed, stamps the checklist
Implementation Files¶
The EGM-Lite capability is implemented across the following package files:
| File Path | Type | Purpose & Reason for Existence |
|---|---|---|
skills/egm-lite/SKILL.md |
Skill Definition | Implements the decoupled 5-phase state machine with Adaptive Gating (/egm-lite -> checklist -> spec review (the user can skip it) -> exec -> review -> resolution). |
skills/egm-lite/agents/openai.yaml |
Host Metadata | Declares extension interface, display names, and brand styling for OpenAI/Codex. |
skills/egm-lite/assets/icon.svg |
Vector Artwork | Self-contained 24x24 dual-facet icon (Spark) adhering to the EGM design system. |
skills/egm-lite/TEST.md |
Unit Tests | Verification test scenarios testing decoupled phase gating and persona switching. |
skills/egm-lite/test_scenarios.yaml |
Evaluation Benchmark | Benchmark test suite evaluating model adherence to the 5-phase EGM-Lite protocol. |
Verification Plan¶
The EGM-Lite protocol is validated through deterministic behavioral evaluation
suites (skills/egm-lite/test_scenarios.yaml), protocol checklists
(skills/egm-lite/TEST.md), and unit tests (pytest tests/unit).
Verification enforces six core behavioral invariants:
- State Machine & Pause Gating (Phases 1 & 2): Asserts that mutating operations
pause for user confirmation (
checklist, thenexecor Proceed),egm_lite_checklist.mdis initialized with GFM checkboxes, and competing architectures are recorded inegm_lite_alternatives.md. - Scope-Contained Execution & Convergence (Phase 3): Verifies that code edits
stay strictly within approved checklist items, local tests execute with
autonomous monotonic convergence, and completed tasks are marked
- [x]. - Fresh-Context Subagent Isolation (Phase 4): Enforces true context separation
via a fresh-context subagent tool (
invoke_subagent), refusing same-context Goldfish reviews and skipping user-agreed pre-review exclusions. - Binary Review Contract (Phase 4): Asserts that any defect strictly suppresses
LGTM and outputs prioritized findings (
P0–P3), while clean passes lead with an explicit> **BLUF:**with[✅ LGTM]. - Post-Review Triage & Synchronization (Phase 5): Validates presentation-only
triage (
[🛠️ X FIX | 🛡️ Y CONTEST]), persistence ofCONTESTrationales in the checklist, and loop closure. - Adaptive Gating & Command Routing (Phases 2A, 2B & 5): Asserts that Phase 2A
offers both
execandgoldfish/reviewwith a recommendation for non-trivial changes, the spec review subagent receives the checklist and the Spec Review Rubric, a spec LGTM prompts forexecwithout closing the task, and an out-of-order command returns a state advisory.
Test Execution¶
# Run unit tests, packaging validation, and harness discovery
pytest tests/unit
# Validate markdown link integrity
pytest tests/unit/test_link_integrity.py
References¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 el/elephant-goldfish-model