Common workflow guidance for AI agents working in the Optimism monorepo. Language-specific details are in go-dev.md and rust-dev.md. For end-to-end testing, see acceptance-tests.md.
All tool versions are pinned in mise.toml at the repo root. Always access tools through mise — never install or invoke system-global versions directly. Check mise.toml for current pinned versions when you need to know what's available.
If mise reports the repo isn't trusted, ask the user to run mise trust — never trust it automatically.
Run mise install to install all pinned tools (just, gotestsum, forge, etc.). AI agent shells typically do not have mise activated, so prefix commands with mise exec -- to ensure tools are on PATH:
mise exec -- just <target>The repo uses Just as its build system. Shared justfile infrastructure lives in justfiles/. Each component has its own justfile — run just --list in any directory to see available targets.
After running language-specific commit checks (lint, test):
-
Run affected tests broadly — don't just test the package/crate you changed. Test packages that depend on it too.
-
Rebase on
develop— this is the default branch, notmain:git fetch origin develop git rebase origin/develop
-
Follow PR guidelines — see
docs/handbook/pr-guidelines.md.
Some tests require CI-only environment variables and are skipped locally. Check the test code for environment variable guards if a test behaves differently than expected.