[gjermundgaraba]

Description

With agents being gooder, we need much less guidance and stuff in AGENTS.md. Saves context, and makes it less likely for information to go stale.

🤖: Streamlines the AGENTS.md files so they carry only guidance an agent cannot infer from the code, the Makefiles, generated-file headers, or the adjacent READMEs, and verifies every remaining fact against the tree.

What changed, in order:

• Streamlined all nine files and cut docs/6-ibc-cli/tools/AGENTS.md from 224 lines to a short procedure. Removed cli/internal/config/AGENTS.md (code-ordering rules) and the cli/CLAUDE.md symlink, which made Claude Code skip the root file for sessions started in cli/.
• Retargeted the refgen notices on the generated pages and in refgen.py from "after changing cli/, proto/ or gen/ before opening a PR" to "when changing commands, configuration, APIs, or cited behavior". REFERENCE.md now states that --plan and --report do not run citation checks.
• Reviewed the result with four agents (two Claude Code, two Codex) against the Claude Code best-practices page and OpenAI's "rethinking skills and prompts" post, then applied the decisions: test imperatives replaced with facts, compile-enforced rules cut, README pointers mapped to named sections, proto regeneration wording aligned.
• Closed the gaps the reviews found. The root file now points at nested area files, because Codex only loads AGENTS.md from the repository root down to the working directory. Added the rules that are silent when wrong: make codegen-mocks (CI does not regenerate mocks), make -C e2e check-matrix (the test target does not run it), the TEST_POSTGRES gate, the default E2E_MODE=fast skipping Besu-requiring tests, and permission to run the Docker-backed tests without asking. Deleted the unreferenced cli/CONTEXT.md glossary.
• Trimming pass, reviewed by two further agents plus an adversarial pass over their reviews: deleted cli/cmd/ibc/AGENTS.md (both rules are stated in main.go), cut the module inventory, the server codegen paragraph, helper names visible in the providers, and the setup sequence shown in the e2e README. Fixed the e2e README sentence on provider requirements that one cut line had been patching.

Most critical to review: AGENTS.md, cli/AGENTS.md, docs/6-ibc-cli/tools/AGENTS.md, e2e/AGENTS.md, cli/internal/store/AGENTS.md.

Two follow-ups surfaced by the reviews are not in this PR: the verify-codegen path filter does not cover hand edits to generated store files on pull request runs, and no workflow runs make lint-license.

closes: n/a (agent guidance cleanup, no tracking issue)

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

• Linked to GitHub issue with discussion and accepted design, OR link to spec that describes this work. (n/a: no issue, documentation-only cleanup)
• Include changelog entry when appropriate (e.g. chores should be omitted from changelog). (n/a: agent guidance and notice text only, no user-facing change)
• Wrote unit and e2e tests if relevant. (n/a: no code behavior change; make lint-license passes)
• Updated documentation (docs/) if anything is changed.
• Added godoc comments if relevant. (n/a: no Go API change)
• Self-reviewed Files changed in the GitHub PR explorer.
• Provide a conventional commit message to follow the repository standards.

🤖 Generated with Claude Code

[github-actions]

Vulnerable dependencies

0 advisories across 0 libraries need attention, 3 accepted.

Accepted

Listed in .govulncheck-ignore with a reason.

github.com/cosmos/evm

In use: v0.7.3 — reached from e2e

Advisory	CVE	Fixed in	Summary
GO-2025-3684	—	no fix yet	Cosmos EVM Allows Partial Precompile State Writes in github.com/cosmos/evm

github.com/pion/dtls/v2

In use: v2.2.12 — reached from cli

Advisory	CVE	Fixed in	Summary
GO-2026-4479	CVE-2026-26014	no fix yet	Usage of random nonce generation with AES GCM ciphers risks leaking the authentication key in github.com/pion/dtls

golang.org/x/crypto

In use: v0.57.0 — reached from cli, e2e

Advisory	CVE	Fixed in	Summary
GO-2026-5932	—	no fix yet	The golang.org/x/crypto/openpgp package is unmaintained, unsafe by design, and has known security issues

_{From make vulncheck-json on this run: logs.}

[greptile-apps]

Confidence Score: 4/5

[Low impact] The changes reach repository agent guidance and documentation workflows, not application runtime behavior.

The PR appears safe to merge, with a non-blocking correction to the PostgreSQL test guidance.

Findings

1.  Docker failures described as skips ▶

Summary

Streamlines agent guidance and narrows reference regeneration instructions to changes that affect the documented surface.

• Agents start with shared rules and keep only guidance each area needs.
• CLI reference pages get updated when their documented behavior changes.
• E2E contributors can find test rules and hidden checks in linked guidance.

Acknowledged follow-ups: gjermundgaraba explicitly deferred the generated-store path-filter gap and the absence of a make lint-license workflow. Neither is introduced by this PR.

_{Reviews (1) · Last reviewed commit: "little cleanly" · Reviewed by Greptile}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 43.19%. Comparing base (03fb552) to head (729c170).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1595   +/-   ##
=======================================
  Coverage   43.19%   43.19%           
=======================================
  Files         145      145           
  Lines       15606    15606           
=======================================
  Hits         6741     6741           
  Misses       8332     8332           
  Partials      533      533           

Flag	Coverage Δ
cli	43.19% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[evanorti]

LGTM