Skip to content

chore: require protocol logo and anvil-fork test pattern in /add-protocol#1292

Merged
suisuss merged 1 commit into
stagingfrom
feat/KEEP-577-add-protocol-iteration
May 19, 2026
Merged

chore: require protocol logo and anvil-fork test pattern in /add-protocol#1292
suisuss merged 1 commit into
stagingfrom
feat/KEEP-577-add-protocol-iteration

Conversation

@suisuss
Copy link
Copy Markdown

@suisuss suisuss commented May 19, 2026

Summary

Two rules added to .claude/commands/add-protocol.md, abstracted from the patterns shipping in PR #1287 (Frax Ether V2). Both surfaced as gaps when running the slash command end-to-end for the first time.

Net diff: +29 / -19 in the slash command.

Rule 1: Logo is mandatory

Every protocol must ship with a real logo at public/protocols/{slug}.png. Placeholders, AI-generated stand-ins, and default-icon fallbacks are not acceptable.

  • Phase 1.1 now requires identifying the logo source during research (preferred order: brand page > GitHub assets/ or logos/ folder > npm package logo field > scraped favicon).
  • Phase 3 artifact line changes from "skip if not provided" to REQUIRED.
  • Phase 4.1 is a new first verify step that checks the file exists at the path the plugin's icon field references.
  • Bail-out condition added: "no real logo obtainable from any of the listed sources - stop and surface to the user".
  • DONE list and success criteria both name the logo as a precondition.

Rule 2: Anvil-fork test pattern for mainnet-only protocols

For protocols with no real testnet deployment, integration tests run against a local anvil mainnet fork at http://localhost:8545, not a paid mainnet RPC.

  • Phase 1.2 adds a HARD RULE forbidding fabricated chain entries: never add Sepolia (or any other chain) to contract.addresses unless the protocol is genuinely deployed there. The chain selector auto-exposes any chain in the map.
  • Phase 1.2 adds a "Testnet-contract status" research step that drives the Phase 3 pattern selection.
  • Phase 3 integration test selection becomes Pattern A (real testnet) / Pattern B (mainnet-only anvil fork) / Pattern C (public-RPC fallback). Pattern B explicitly says "do NOT default the test at a paid mainnet RPC; the anvil fork is free, deterministic, requires no secret, and is the supported substitute for the missing testnet".
  • Pattern B adds two extra artifacts modeled on what shipped in PR feat: KEEP-578 add Frax Ether V2 protocol plugin #1287:
    • scripts/{slug}-fork-test.ts - tsx smoke test using an anvil-funded account, prints PASS/FAIL.
    • docs/plugins/{slug}.md ## Testing Without Risking Real ETH section + ## Why no testnet entry in the plugin subsection (the second so future maintainers don't re-litigate the "just add Sepolia" instinct).
  • Phase 4.6 verify requires the anvil-fork run to pass.
  • Bail-out condition added: "anvil cannot be run locally - surface; do not silently fall back to a paid RPC".

Test plan

  • Manual: re-read the rendered slash command in Claude Code to confirm the <objective>, <process>, and <success_criteria> blocks still parse.
  • Manual: spot-check that the @-include references in the unchanged <context> block still resolve to real files.
  • Manual: invoke /add-protocol <Some Mainnet-Only Protocol> and confirm the orchestrator routes through the new Pattern B path and surfaces the logo-source question in the Phase 2 report.

…ocol

Two rules abstracted from the Frax Ether V2 plugin (PR #1287, which set
up both patterns by hand as the canonical examples).

LOGO IS MANDATORY

Every protocol ships with a real logo at public/protocols/{slug}.png.
Phase 1.1 now requires identifying the logo source during research
(brand page > GitHub assets > npm package logo field > scraped
favicon, in that order of preference). Phase 3 changes the artifact
line from "skip if not provided" to REQUIRED, with explicit ban on
placeholders, AI-generated, and default-icon fallbacks. Phase 4.1 is
a new first verify step that checks the file exists. Bail-out
condition added: "no real logo obtainable - stop and ask".

ANVIL FORK FOR MAINNET-ONLY PROTOCOLS

Phase 1.2 adds a HARD RULE forbidding fabricated chain entries: never
add Sepolia (or any other chain) to contract.addresses unless the
protocol is genuinely deployed there. The chain selector
auto-exposes any chain in the map, so a fake entry breaks workflows
at runtime.

Phase 3 integration test selection becomes Pattern A (real testnet) /
Pattern B (mainnet-only anvil fork) / Pattern C (public-RPC fallback).
Pattern B explicitly says "do NOT default the test at a paid mainnet
RPC: the anvil fork is free, deterministic, requires no secret, and
is the supported substitute for the missing testnet".

Pattern B adds two artifacts modeled on what shipped in PR #1287:
- scripts/{slug}-fork-test.ts (tsx smoke test, anvil-funded account,
  PASS/FAIL output)
- docs/plugins/{slug}.md "## Testing Without Risking Real ETH"
  section walking through the Docker foundry anvil command, the
  fork-test script, and CHAIN_ETH_MAINNET_PRIMARY_RPC override for
  the dev server
- docs/plugins/{slug}.md "## Why no testnet entry in the plugin"
  subsection naming the testnets checked

Phase 4.6 verify requires the anvil-fork run to pass. Bail-out added
for "anvil cannot be run locally".

Net: +29 / -19 in the slash command.
@suisuss suisuss merged commit 726d9a4 into staging May 19, 2026
32 checks passed
@suisuss suisuss deleted the feat/KEEP-577-add-protocol-iteration branch May 19, 2026 04:54
@github-actions
Copy link
Copy Markdown

🧹 PR Environment Cleaned Up

The PR environment has been successfully deleted.

Deleted Resources:

  • Namespace: pr-1292
  • All Helm releases (Keeperhub, Scheduler, Event services)
  • PostgreSQL Database (including data)
  • LocalStack, Redis
  • All associated secrets and configs

All resources have been cleaned up and will no longer incur costs.

@github-actions
Copy link
Copy Markdown

ℹ️ No PR Environment to Clean Up

No PR environment was found for this PR. This is expected if:

  • The PR never had the deploy-pr-environment label
  • The environment was already cleaned up
  • The deployment never completed successfully

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant