solidity-agentic-stack CLAUDE.md

Agentic Stack for Solidity — CLAUDE.md

The Rule

Agents write. Tools verify. Humans sign.

• The agent may propose and write code. It never declares code correct — only the toolchain can.
• The toolchain (forge, slither, aderyn) is the authority. A green suite is the definition of done.
• The agent never broadcasts a transaction, never touches a private key, and never edits .env.

---

Commands

# Build
forge build

# Format (check only — CI gate)
forge fmt --check

# Format (auto-fix)
forge fmt

# Unit + fuzz tests (default profile)
forge test

# Invariant tests only
forge test --match-contract VaultInvariant

# CI profile (higher fuzz/invariant runs)
FOUNDRY_PROFILE=ci forge test

# Coverage
forge coverage --report lcov

# Slither static analysis
slither .

# Aderyn static analysis
aderyn .

# Full definition-of-done gate
forge fmt --check && forge build && FOUNDRY_PROFILE=ci forge test && slither . && aderyn .

# Red team agent (requires ANTHROPIC_API_KEY)
python scripts/redteam.py --dry-run   # print findings, no GitHub Issues
python scripts/redteam.py             # print findings + file GitHub Issues

# Fix agent — patch a specific security issue (requires ANTHROPIC_API_KEY)
python scripts/fix.py --issue 42 --dry-run   # apply fix locally, skip PR
python scripts/fix.py --issue 42             # fix + forge test + open PR

---

Invariants — The Constitution

These invariants MUST hold at all times. Never weaken an invariant to make a test pass. If an invariant breaks, the protocol is broken — fix the code, not the test.

ID	Statement
INV-1	address(vault).balance == vault.totalDeposits()
INV-2	ghost_totalDeposited - ghost_totalWithdrawn == vault.totalDeposits()

---

Hard Rules

Code quality

• CEI everywhere. Checks → Effects → Interactions. No exceptions.
• Custom errors only. No require strings. Never revert with a bare string.
• Named imports. import {Foo} from "bar/Foo.sol" — no wildcard imports.
• Full NatSpec on every public/external function and error.
• No tx.origin auth, no block.timestamp as randomness, no unbounded loops.