Skip to content

docs: add CONVENTIONS.md structure & taste guide #323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Troublor wants to merge 1 commit into
base: main
Choose a base branch
from
+220 −3
Draft

docs: add CONVENTIONS.md structure & taste guide #323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/claude.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ jobs:
PR NUMBER: ${{ github.event.pull_request.number }}

You are a documentation impact checker for the MegaETH specification.
Your ONLY job is to determine if this PR's code changes require updates to docs/ or agent files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, .claude/skills/*/SKILL.md).
Your ONLY job is to determine if this PR's code changes require updates to docs/ or agent files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, CONVENTIONS.md, .claude/skills/*/SKILL.md).

Follow the doc-impact-check skill instructions in .claude/skills/doc-impact-check/SKILL.md.

Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/doc-audit.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:
FRESHNESS_WINDOW: ${{ github.event.inputs.freshness_window || '14d' }}

You are a documentation auditor for the MegaETH specification.
Your scope includes docs/ (both docs/spec/ and docs/mega-evme/) AND agent instruction files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, .claude/skills/*/SKILL.md).
Your scope includes docs/ (both docs/spec/ and docs/mega-evme/) AND agent instruction files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, CONVENTIONS.md, .claude/skills/*/SKILL.md).
Agent files contain code paths, spec progressions, system contract tables, and other references that can go stale.
Run all three audit dimensions and file a single GitHub issue with findings.

Expand All @@ -54,7 +54,7 @@ jobs:
## Step 3: Run correctness check

Follow the doc-correctness skill in .claude/skills/doc-correctness/SKILL.md.
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md PLUS all agent files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, .claude/skills/*/SKILL.md).
Scope: all pages in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md PLUS all agent files (AGENTS.md, CLAUDE.md, docs/AGENTS.md, bin/mega-evme/AGENTS.md, REVIEW.md, CONVENTIONS.md, .claude/skills/*/SKILL.md).
For agent files, verify code-related claims: spec progression lists, system contract tables, source layout descriptions, code path references, unstable spec markers, code-to-doc mapping tables in skills.
Produce the Correctness section of the report.

Expand Down
2 changes: 2 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ Progression: `EQUIVALENCE` → `MINI_REX` → `REX` → `REX1` → `REX2` → `R

### Core Source Layout (`crates/mega-evm/src/`)

For the cross-cutting structure and taste conventions — where logic belongs, file-role conventions, when to add a new file vs. extend an existing one, composition idioms, smells to avoid, and the known-deviations backlog — see [`CONVENTIONS.md`](CONVENTIONS.md).

- **`evm/`** — Core mega-evm logic: spec definitions, context, factory, execution pipeline, modified opcodes (LOG, SELFDESTRUCT), host hooks, precompiles.
This module collects all our modifications and customizations of EVM's behavior for mega-evm based on the revm.
- **`block/`** — Block execution: executor, factory, hardfork-to-spec mapping, limit enforcement, and the canonical per-chain hardfork schedules.
Expand Down
Loading
Loading