DeepBook V3 is a decentralized order book on Sui. This file is the canonical entry point for coding agents; AGENTS.md contains only a portable pointer here so every agent has one repository-guidance source.
- Source and tests own executable behavior.
- Tracked decision records own settled design choices and revisit conditions.
.claude/rules/owns editing and workflow directives scoped by path or task.- Package documentation owns public explanations of current behavior.
- When sources disagree, verify against source and tests, then fix or record the lower-authority drift rather than copying another version of the fact.
Use repository-relative pointers instead of copying facts between context files. Local Markdown links are for navigable documents; backticks are for source paths, commands, and identifiers.
Context surfaces use four roles:
- Entrypoint:
CLAUDE.mdowns repository-wide directives and routes readers to narrower context;AGENTS.mdonly points here. - Directive:
.claude/rules/*.mdowns what contributors must do for a path or task; it points to facts, decisions, and evidence instead of copying them. - Workflow:
.claude/skills/*/SKILL.mdowns an executable procedure, its trigger, and its output contract; it does not become a second home for repository facts. - Domain owner: Source, tests, package documentation, registers, and evidence own component behavior, decisions, state, and measurements. An area hub may route to narrower owners within its domain.
Authority pointers flow from entrypoints, directives, workflows, and consumers toward the owning surface. Owners do not point back to an entrypoint merely to say they are routed. Related-reading links may be reciprocal only when they are navigational and do not establish precedence.
packages/contains Sui Move packages.vendor/contains pinned third-party Move source; Testnet Pyth provenance and Mainnet Pyth provenance own their source and publication records.crates/contains the DeepBook indexer, server, and schema crates.scripts/contains protocol package-upgrade transactions and SDK examples..claude/rules/contains scoped contributor guidance..claude/skills/contains specialist workflows; the stacked pull-request workflow applies to every pull request, and the others run only when their trigger matches or the user invokes them.
Read context in this order: start here, load the matching path-scoped and task-triggered directives, load a matching skill when the task calls for it, then follow only the owner pointers needed for the work.
Do not assume a scoped rule is already in context. Claude Code may inject a rule through its paths: frontmatter, while Codex and other agents may not; before editing a matching file, open the rule yourself if it was not injected. Manual-trigger rules must always be read when the task matches.
| Files or surface | Required guidance |
|---|---|
packages/**/*.move, packages/**/Move.toml, packages/**/Published.toml |
Sui Move instructions |
packages/{predict,predict_orders,predict_math,propbook,account}/**/*.move |
Predict contract rules and Sui Move instructions |
packages/**/tests/** |
Unit-test rules |
packages/predict/{harness,devtools,simulations}/** |
Predict harness rules |
packages/predict/deployment/** |
Predict deployment rules |
crates/{server,schema,indexer}/** |
Indexer rules |
scripts/** |
Scripts rules |
| Task | Required guidance |
|---|---|
| Code review or review of uncommitted changes | Code-review rules; for an explicitly approved deep Predict audit, use the Predict audit skill |
| Add or build a Predict harness strategy | Harness-strategy workflow and Predict harness rules |
| Create, change, run, publish, deploy, migrate, resume, audit, or verify a Predict deployment | Predict deployment rules, plus Sui Move instructions when package manifests are involved |
| Wrap up a session | Wrap-up workflow |
| Open, split, or restack a pull request | Stacked pull-request workflow |
| Request Codex-gated pull-request approval | Auto-approval contract |
Before proposing or changing Predict protocol behavior, follow the Predict development-system authority order and lifecycle, which routes settled mechanisms, tail-state policies, open work, measurements, and public disclosure to their owners.
The Predict protocol documentation explains current public behavior; it does not outrank source, tests, or the development-system authority order. Treat design and research documents as leads to verify against current source, git history, and tests rather than executable truth.
Treat .claude/predict-design/, .claude/predict-review/, and .redesign/ as ignored personal scratch. Nothing another contributor needs to continue the work may live only there.
- Build a package:
sui move build --path packages/<package>. - Test a package:
sui move test --path packages/<package> --gas-limit 100000000000 --package-size 64. The high gas limit is required because Sui 1.66+ lowered the default test gas budget.--package-size 64raises the test VM's package arena from its 10 MB default, which the Predict test package exceeds, and needs Sui 1.79.1 or later. - Build Predict with warnings denied:
sui move build --path packages/predict --warnings-are-errors. - After changing Predict pricing, pool or vault accounting, oracle math, or public protocol flows, run the full Predict suite:
sui move test --path packages/predict --gas-limit 100000000000 --package-size 64. - After changing Predict's order-flow primitives, the pricing math, or anything the companion calls, also run
packages/predict_math,packages/predict_orders, andpackages/sessionswith the same flags. CI additionally builds and tests the Mainnet dependency graph,predict_maththroughsessions, with--build-env mainnet(.github/workflows/move_test.yml). - Format Move before opening a pull request:
pnpm install --frozen-lockfile && pnpm format:move; do not usebunxornpxbecause CI uses the repository-pinned formatter dependency.
Run every sui move build and sui move test in the main session, not in a subagent. Preserve the command's real exit code with ${PIPESTATUS[0]} when a pipeline is unavoidable, or inspect the output for error and Test result:; never pipe a build or test through tail, which reports tail's status.
- Build the server:
cargo build -p deepbook-server. - Test the server:
cargo test -p deepbook-server.
- Lint:
pnpm run lint. - Format:
pnpm run prettier:fix.
- State material assumptions and unresolved choices before implementation; do not hide ambiguity or silently select among meaningfully different interpretations.
- Prefer the minimum change that satisfies the request; do not add speculative features, abstractions, configurability, or unrelated refactors.
- Keep edits surgical, preserve established local style, and remove only imports, variables, functions, or files made obsolete by the requested change.
- Define verifiable acceptance before coding and run the smallest relevant check first, expanding to the required package or integration suite as the affected behavior demands.
- Protocol behavior changes require tests in the owning package; complex tests use short scenario comments and explain non-obvious expected-value arithmetic.
- Update nearby comments and the owning public documentation when behavior changes; tests and documentation land with the code (tests in the same pull request, documentation in the same pull request or the docs pull request stacked directly on it) rather than as deferred follow-up work.
- Expected values and generated fixtures must be independent of the implementation under test; follow the unit-test rules for the full contract.
- Predict source is organized by domain subsystem and Predict tests mirror those source folders except for shared helpers and broad flow tests; the Predict contract rules own the detailed layout.
Route durable information to one owner instead of appending it wherever it was discovered:
| Information | Owner |
|---|---|
| General or path-specific contributor directive | The matching file under .claude/rules/ |
| Component behavior or interface fact | Source, tests, or the owning package README |
| Settled Predict mechanism decision or rejected direction | Predict design decisions |
| Settled Predict response to a degenerate or adversarial state | Predict response-policy register |
| Unresolved Predict finding or experiment plan | Predict open-items register |
| Predict measurement | A dated record under packages/predict/predeploy/evidence/, following the predeploy lifecycle |
| Public Predict explanation or risk | Predict protocol documentation |
| Raw working notes or generated audit output | Ignored scratch only; extract durable results before another contributor needs them |
When context moves, update the owner, replace consumer text that still needs the behavior with a direct pointer, delete the remaining copies, and update a router only if the owner would otherwise be unreachable. Land those changes together so the repository never represents two authoritative versions.
Before changing repository guidance, check the owning file for an existing rule, name the failure the new directive prevents, and point to source, tests, decisions, or evidence instead of restating their details. When the user asks to wrap up, follow the proposal gate in the wrap-up workflow.
Context prose uses one physical line per paragraph, list item, and blockquote. YAML frontmatter, fenced code, and tables are exempt.
Open every pull request as a two-layer stack, code first and then docs and setup, following the stacked pull-request workflow, unless the change touches only one layer or the user asks for a single pull request. Before creating a branch for a pull request or stack, ask the user for the branch name once; a stack's docs layer appends -docs to it. Use the repository's pull-request template. Write the summary, motivation, decisions, scope, tests, and risk in plain engineering language that a contributor can understand without access to private repositories or internal context. Include a DBU identifier in the branch name or pull-request title when the work has a Linear ticket; mechanical documentation and configuration chores may be unticketed.