AGENTS.md · 0xPlaygrounds/rig

Sections

1. First Principles
2. Fast Loop
3. Efficient Investigation
4. Repository Shape
5. WASM Compatibility
6. Error Handling
7. Documentation
8. Release Documents Are Generated
9. Provider Changes
10. Vector Store Changes
11. Style
12. Cassette Regression Tests
13. Verification

First lines (shown under the repo's MIT license)

# AGENTS.md

Operational instructions for AI coding agents working in Rig. Contributor
policy and PR etiquette live in [CONTRIBUTING.md](CONTRIBUTING.md); verification,
review, and publication in [DEVELOPING.md](DEVELOPING.md); test conventions and
commands in [tests/README.md](tests/README.md).
This file states rules, not APIs: read the code and manifests for names,
signatures, module paths, and feature flags.

## First Principles

- Read the existing implementation before changing code.
- Keep changes scoped to the user's request.
- Prefer existing Rig traits, builders, modules, and error types over new abstractions.
- Do not add TODOs, stubs, placeholder implementations, speculative APIs, or backwards compatibility shims.
- Do not make commits, comments, stage changes, push branches, or open PRs unless the user explicitly asks.
- Do not discard user changes.

## Fast Loop

- Iterate with `cargo nextest run --locked --profile local -p <crate> [filter]`;
  leave workspace-wide and facade `--all-features` runs to CI.
- Before pushing, run `cargo xtask verify --affected --base origin/main`: every
  test of the changed packages and of the packages depending on them.
- Keep incremental compilation on.

## Efficient Investigation

- Reuse instructions and unchanged source already in context. Read the relevant
  sections of linked documents, not every document for every task.
- Use the repository map below to narrow searches to the owning crate or test
  target. Read complete relevant constructs; widen only when needed.
- Check actual signatures and existing test conventions before writing examples
  or smoke programs, rather than discovering APIs through compiler errors.
- Keep commands and edits on the intended worktree. Confirm the language server
  indexes it before trusting references; empty results outside its workspace
  are not proof of no callers. Inspect native/WASM branches explicitly.
- Request only decision-relevant output. Recover missing diagnostic context from
  truncated output rather than dumping or fetching the entire log again.

## Repository Shape

- Root facade crate: `rig` (re-exports the core crate, exposes companion crates behind feature flags)
- Core crate: `crates/rig-core`
- Companion provider, vector-store, memory, and integration crates: `crates/rig-*`
- Derive macros: `crates/rig-derive`
- The rig coding agent: its core `crates/rig-harness` (on `crates/rig-ecs` and `crates/rig-tools`), its plugin crates `plugins/rig-*`, their shared test support `test-support/rig-harness-test-support`, and `test-support/rig-defaults-test-support` (the default plugins for tests, and the test that each can be left out); all but the two test-support crates are published
- The plugin corpus `corpus/*`: plugins written against the harness's public API that shaped and prove the kernel, one per module (`src/<plugin>.rs` with its tests in `src/<plugin>/tests.rs`) of a few `publish = false` packages named `corpus-<directory>` (`shared`, which the others build on; `base`; one per held-out series; `library`, programs with no Bevy), so their tests link nine binaries, not one per plugin. CI builds, lints and tests every one, so a kernel change that breaks one fails CI
- Verification planner and source-tree checks: `xtask/`
- Workspace example packages: `examples/*`; per-crate examples: `crates/<crate>/examples/`
- Root integration test targets: `tests/*.rs`
- Record/replay home: `crates/rig-cassette` — the engine (`src/`), the provider cassette corpus (`fixtures/cassettes/<provider>/`), the effect-log golden corpus (`fixtures/effects/`), every cassette-backed provider target (`tests/<provider>.rs` with `tests/providers/<provider>/` and the shared drivers in `tests/common/`), the cache-prefix guard, and the effect-bus verification target `verify`. Corpora and `tests/` are excluded from the published package.
- Live-only provider test modules stay in the facade: `tests/providers/<provider>/`, driven by `tests/<provider>.rs`
- External-service integration tests: `tests/integrations/`
- Unpublished vector-store test runner: `test-support/service-tests`

Check the root manifest and facade source before documenting or changing
exposed features, integrations, or module paths. When adding or exposing a
companion crate, update the root dependency, feature, facade re-export,
examples, README, and crate docs as applicable.

## WASM Compatibility

Rig supports WebAssembly targets. Use Rig's WASM-compatible `WasmSend`/`WasmSync`
alias bounds instead of raw `Send` and `Sync`, and its WASM-compatible boxed
future alias for boxed futures. When an error type stores boxed errors, gate
the `Send + Sync` bound on `target_family = "wasm"` the way existing error
types do.

## Error Handling

- Do not use `String` as an error type for new fallible APIs;
- Workspace clippy lints forbid `unwrap`, `expect`, `todo`, and `unimplemented`.
- Tests are linted too: `indexing_slicing` and `panic_in_result_fn` apply in test code, so index with `.get(..)`, and do not assert in a test that returns `Result`.
- Prefer `?` and meaningful error conversions.

## Documentation

- Keep examples current with actual APIs, model constants, module paths, and feature flags; mark examples `no_run` when they require external credentials or services.
- Do not document integrations, features, model constants, or crate paths without checking the code and manifests.
- Keep root README, crate READMEs, and crate-level Rust docs consistent when changing public-facing behavior.

## Release Documents Are Generated

- Never edit `CHANGELOG.md`, `crates/*/CHANGELOG.md`, `MIGRATING.md`, or `docs/migrations/`. CI rejects the PR.
- Put changelog bullets and migration notes in the PR description under `## Changelog` and `## Migration`, following the PR template. When the user asks to "update the changelog" or "add a migration note", that is what it means. The repository squash-merges, so those sections become the merge commit body.
- These files are regenerated on the release PR by `scripts/release-notes.sh` and the editorial pass in `scripts/release-notes-prompt.md`. Only touch them when the user explicitly says the branch is a release PR.

## Provider Changes

Before implementing or modifying a provider, study the closest existing
provider implementation and mirror it. Providers whose wire format is a
dialect of an existing one (OpenAI-chat-compatible, Anthropic-compatible) MUST
reuse the shared generic completion model for that dialect and express their
differences through its extension hooks — never a hand-rolled completion
model, request struct, or message conversion.

## Vector Store Changes

Vector stores should live in companion crates. Implement both the scored-document and the
id-only search methods, use an appropriate backend-specific filter type,
return the vector-store error enum's variants instead of ad hoc string
errors, and use the WASM-compatible bounds.

## Style

- Module docs state the module's purpose in at most three paragraphs and include
  one short example when there is a public entry point. No headers, tables,
  history, or rhetorical phrasing.
- Item docs state the contract, inputs, outputs, errors, and caller invariants.
  Allow one sentence of non-obvious rationale. No issue numbers, bug narratives,
  or comparisons with other providers.
- Inline comments explain a non-obvious why in one or two sentences. Delete
  restated code, control-flow narration, and design discussions.
- Use short sentences and no em-dashes. Keep true `# Safety` and `# Panics`
  sections. Doc examples must compile with current APIs; use `no_run` for
  credentials, network access, or services.
- Move needed design rationale to the crate's CONTRACT.md or README, checking
  for and merging existing coverage rather than duplicating it.
- Follow local naming, module layout, and test patterns.
- Test modules are sibling files, never inline blocks: write
  `#[cfg(test)] mod tests;` and put the body in `foo/tests.rs` (for `foo.rs`)
  or `tests.rs` beside `mod.rs`/`lib.rs`. `cargo xtask check-test-layout`
  enforces this in CI.
- Avoid unrelated refactors.
- Prefer the cleanest implementation.
- Break things if the result is better.

## Cassette Regression Tests

Provider regressions should usually include cassette-backed tests. Follow
[tests/README.md](tests/README.md#cassette-provider-tests) for replay/record
commands and fixture safety review; never record or rewrite fixtures merely
to make verification pass.

## Verification

Follow [DEVELOPING.md](DEVELOPING.md) for check selection, independent review,
and authorized publication. Run the smallest useful local check; docs-only
edits get diff and link review, not Rust builds. Keep progress reports outside
the repository and never claim merge readiness with required checks pending.