A self-improving RLM agent for coding workflows and long-running autonomous tasks.
AGENTS.md
Development rules for Prime Agent (Rust) on PrimeIntellect-ai/prime-agent, branch main.
Every contributor (human or agent) must read this before working on this repo.
Repository
- Never set git identity for commits to this repo's history. Agents must not set
user.name/user.email(config or-c) orGIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL/GIT_COMMITTER_NAME/GIT_COMMITTER_EMAILfor commits that land in this repository. Those commits carry the identity of the ambient git config. If such a commit fails for a missing identity, report it instead of adding config. Allowed: the*_DATEvariables (the golden corpus pins them for reproducibility), throwaway temp repos created by tests, and the release automation's bot identity. - Never add
Co-authored-bytrailers — not in commit messages, not in squash suggestions, not as attribution for work merged from branches. A PR's commits carry one identity: the ambient git config's. Fabricated or hand-written trailers (including noreply forms) misattribute commits to unrelated GitHub accounts. - The repo is PrimeIntellect-ai/prime-agent; the Rust implementation lives on the
mainbranch. - PRs go to the org repo with base
main:gh pr create --repo PrimeIntellect-ai/prime-agent --base main. - CI runs on the org's billing:
.github/workflows/continuous.ymlonmainpushes andrelease.ymlon version tags. - Parity ground truth is unchanged: a read-only checkout of the TS implementation (this
repo at tag
v0.9.8, the last TS release before the Rust port merged tomain). Clone it to~/prime-agent, the conventional location the parity scripts and code fall back to; tooling that honors an override readsPA_TS_REFERENCE.
Style and structure
- Workspace crates are prefixed
pa-. The hard ownership rules: one owned area per crate, pa-types is the only shared crate, cycle-free dependency direction, minimal public APIs, no god-modules. The dependency direction is pinned in the Crates table below; each crate's README.md states its scope, non-goals, and public API surface. - Prefer private modules with an explicitly exported public crate API. Internals are
pub(crate). - Aim for files under 2,000 lines, tests included. The 2,000-2,100 range is a soft review signal, not a merge limit: when adding to an already-large file, consider splitting by responsibility rather than growing it further. Move related tests and docs with extracted code.
- Name modules for what they own, not
utilsorcommon. Follow existing structure: incrates/pa-core/src/kernel/manager/,mod.rsconnectsexecution.rs,requests.rs, andteardown.rs; put a new kernel-manager concern beside them. Incrates/pa-core/src/cron/store/,mod.rsconnectsheartbeat.rs,jobs.rs, andsession_artifacts.rs; keep storage work there rather than growing the scheduler. - Inline format args: always prefer
format!("{x}")over positional. - Collapse if statements per clippy::collapsible_if.
- Prefer method references over closures per clippy::redundant_closure_for_method_calls.
- Make
matchstatements exhaustive; avoid wildcard arms. - New traits need doc comments explaining their role and how implementations are expected to behave.
- No opaque positional
bool/Optionparameters (foo(false)is unreadable). Prefer enums, named methods, or newtypes. If you must pass an opaque literal by position, use an exact/*param_name*/comment matching the callee signature. - Prefer native RPITIT trait methods with explicit
Sendbounds (fn foo(&self) -> impl Future<Output = T> + Send;) over#[async_trait]or#[allow(async_fn_in_trait)]. Implementations may useasync fnwhen they satisfy the contract. - No single-use helper methods. Do not create a helper referenced only once.
- Instrument async work at the definition (
#[tracing::instrument(...)]), not with.instrument(...)at call sites. Check whether the callee is already instrumented first.
Change hygiene
- One logical change per PR. Fixes ride with the change that introduced them when possible; a PR that mixes a feature with unrelated lint fixes or refactors hides both from review.
- If you change dependencies (
Cargo.toml), regenerate/commitCargo.lockin the same change. A new dependency is an architectural change: state in the PR why the existing crates cannot host the functionality, andmake denymust stay clean for it. - If a change starts forcing edits across many crate internals, stop and fix the boundary instead.
- Do not commit scripts or tools that no workflow, Makefile target, or other code runs (one-off review, parity, or reproduction scripts). Put their results in the PR body as a one-off run with its command and result, not as coverage.
- Do not commit evidence logs, reports, generated outputs, or local venvs and caches that no code or test reads.
Tests
- Prefer whole-object equality comparisons over field-by-field checks.
- Do not add tests for statically defined values.
- Do not add negative tests for logic that was removed.
- Bug fixes need a regression test that fails without the fix.
- Keep test code in proportion to the change: one discriminating test per behavior change, not several that pin the same behavior or re-check behavior the PR does not change.
- A new test file must be run by something: a runner, glob, loop, or run-time path in
.github/workflows/or the Makefile. A name missing from those files can still be reached by a glob or a built path, so check those before calling a test unrun. - Verifiers over self-assessment: tmux user-level tests, differential tests against the TS binary on PATH, golden corpora replayed against real captured data. No lane merges without its verifier passing, rerun by the reviewer where feasible.
- Tests must wait for observable readiness, not fixed sleeps or retry-to-green loops. If a test must be disabled, give a reason at the test. Use isolated ports and temporary paths, and restore shared state. Run focused tests when changing their behavior.
Lint discipline
- Zero-warning posture: the merge gates run fmt + clippy + tests at
-D warnings, so awarnlint is a merge blocker. Keep the enabled set deliberate and selective; enable a new lint family only with every current site fixed in the same change. - Explain lint exceptions next to the
#[allow(...)]or workspace configuration; keep exceptions narrow. Advisory ignores indeny.tomlneed a reason and review date.
Performance and the critical path
The UI critical path is paint-latency-critical. First paint, and every frame the user waits on, must never block on network, disk sync, or background bookkeeping. The launch benchmarks measure this surface (cold/warm ready, first paint); a merge that regresses them undoes the product's core claim.
Rules:
- Nothing user-visible awaits the network. Any HTTP/socket call on a render path (telemetry, catalog fetch, update check) runs on a background worker; the paint path hands the work off and returns immediately. Delivery semantics (timeout, retry, ordering) live with the worker, not the caller.
- Telemetry is fire-and-forget from user-facing code.
pa-telemetry's background worker owns delivery end to end; no startup, session create, tab open, or first-render path may hold a flush or await a sink. - Fire-and-forget boundaries need a red-first test: a hanging sink (one that never replies) must not delay paint. The test fails if any await on the critical path reaches the worker's delivery.
- Tests that mock a sink or run offline cannot prove the above (the benchmark's mock hides the POST). The regression test with a hanging sink is the required verifier.
Example (the #3288 regression this rule exists to prevent): the
telemetry startup flush was awaited on the interactive launch path, so
the analytics POST — a real HTTPS round-trip, ~157 ms — ran before the
first frame. Every CI check passed because tests set DO_NOT_TRACK=1 and
the benchmark mocked the provider offline; only real-network launches
paid the cost. The fix moved the flush to the background worker and
added the_startup_flush_never_blocks_the_first_frame (a hanging sink
must not delay paint) as the permanent guard. Any change touching the
launch path must keep that test red-first.
Merge gates
cargo fmt --all --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspacemust pass before every merge. Runmake check— the local mirror of the same gates; CI runs on the org's billing (.github/workflows/continuous.ymlonmainpushes;release.ymlon version tags). The PR-only codebase-health check reports growth past 2,000 lines as review guidance; it never blocks a merge.- PRs that change shipped paths need a
.changes/<branch-slug>.mdfragment (one user-facing bullet; see.changes/README.md) or theno-changeloglabel; the changelog-fragment check enforces it. - Parity-diff evidence is a merge gate (the port's definition, not optional polish): every PR
that touches a user-visible surface must include a "parity-diff evidence" section in its
description showing the TS-binary comparison for what it changed: (1) rendered output —
frame-diff vs the TS binary;
(2) interactive behavior — the same input handled identically (keys, mouse, timing);
(3) wire parity — byte-compare the TS daemon's traffic for protocol changes; (4) user-visible
invariants — every user action produces the same visible reaction as TS (
/compactshows started+completed;/modelshows the selector; a refinement shows its decoration). A feature that "works" but was never diffed against the TS binary does not pass review. If TS shows it, Rust shows it identically; if Rust shows something TS does not, that is also a parity bug. - PRs must state ownership compliance (crate README scope/non-goals/public API, dependency
direction) and classify the change: internals, new
pubsurface, or a new dependency/cross-crate re-export. The latter two are architectural changes — an innocent-lookingpub useis a very simple way to break encapsulation. - The compiled fallback model catalog
crates/pa-ai/src/models_generated.rsis hand-maintained Rust mirroring the TSpackages/ai/src/models.generated.tsobject literal — edit it by hand, exactly like its TS source (there is no generator). The parity fixturecrates/pa-models/tests/fixtures/catalog.v1.jsonrefreshes withscripts/generate-catalog-fixture.py. Bulk data files are exempt from the size guidance.
Adoption telemetry
Every user-visible feature ships its adoption telemetry event in the same PR as the feature:
the event name + properties join the versioned schema (pa-telemetry), and a
seam emits it from day one. Telemetry properties never carry prompt, session, or file content
(primitives only; see pa-telemetry); delivery is fire-and-forget from user-facing code
(see Performance and the critical path).
Branding
The product is Prime Agent - we are not a pi fork. Scrub "pi"/"pi-mono"/"pi-ai"/ "Prime Intellect"-style naming from all user-visible surfaces (docs, READMEs, CLI help text, error messages, splash/onboarding strings, keybinding hints, TUI labels, and code comments that quote user-facing strings); brand everything Prime Agent. Audit with a repo-wide grep and classify every hit (user-visible vs wire-internal vs comment) before scrubbing, and list the preserved wire identifiers in the PR body so the reviewer can verify none were wrongly scrubbed.
EXPLICIT EXCEPTION: wire-protocol identifiers that must stay byte-compatible with the TS product (e.g. the PI_PACKAGE_DIR env var, settings keys, provider IDs like prime-inference, harness _meta namespaces like ai.primeintellect.prime-agent, lockfile names) stay until/unless the TS side renames them — PARITY BEATS BRANDING ON THE WIRE.
Surface contract (must not change)
- Tools exposed to the model:
bash,edit,python_repl(internal helpers:rename,stdout). - RLM kernel API in the persistent Python REPL:
rlm.spawn/find_models/collect/list_subagents/delete_subagent/create_session/progress_note,rlm.harnessCRUD,agent_message.send,agent_observe,compact,goal,refine,attach_image, skills (markdown + Python) per the skill contract in the base system prompt. - System prompt structure: layered — cache-stable static layer files (core harness description with the full API surface, mandatory usage rules, opinionated guidelines, per-model additions from the model-prompts TOML rule map) followed by one dynamic tail (packages, project context, skills inventory, MCP servers, environment, session role); the harness digest stays a separate
[harness-digest]user message.prime-agent promptdumps the assembled prompt with its layer breakdown. - CLI shape:
prime-agentwith the same commands/flags as the TS product; headless modes (RPC/daemon/session-worker) with identical behavior.
Crates
One owned area per crate; pa-types is the only shared vocabulary crate.
Dependencies flow from the composition root toward lower crates, never back upward.
The table summarizes each crate's current direct workspace dependencies:
| Crate | Purpose | Direct workspace dependencies |
|---|---|---|
pa-types |
Shared wire and domain types | none |
pa-telemetry |
Events and sinks | none |
pa-agent |
Provider-independent agent loop | none |
pa-ai |
Providers, model registry, streaming | pa-types |
pa-models |
Live model catalog and transport | pa-ai, pa-types |
pa-core |
Session engine, tools, skills, kernel, settings | pa-types, pa-ai, pa-models, pa-agent, pa-telemetry |
pa-daemon |
Supervisor, workers, wire protocol | pa-types, pa-core, pa-agent, pa-ai, pa-telemetry, pa-models |
pa-tui |
Terminal UI, daemon-wire client | pa-types |
pa-cli |
prime-agent binary, composition root |
pa-types, pa-core, pa-ai, pa-agent, pa-daemon, pa-tui, pa-telemetry |
pa-perf |
Performance corpora + pty bench harness (dev/CI tooling, never shipped) | pa-types, pa-core, pa-daemon |
Layering rules:
- Dependencies only point from higher crates to lower crates shown above. No cycles or
reverse edges. The leaf crates are peers; add only the dependencies needed for their work.
Shared wire/domain vocabulary belongs in
pa-types, not in a higher crate or a duplicate. pa-tuirenders from wire types and events; it does not link the session engine.pa-cliis a composition root: it wires crates together and contains no business logic.
Reliability model
- The daemon is a supervisor: it spawns one worker process per active session instead of hosting sessions in-process. Workers are supervised, restarted with backoff, and sessions persist on disk (append-only JSONL, same layout as
~/.prime/agent/sessions) so reattach works even if the supervisor restarts. - No stubs, no
todo!(), no swallowed errors (anyhowbubbling to UI is fine).
References
- Cursor Bugbot's PR review rules (
.cursor/BUGBOT.md) mirror the standards in this file - update both whenever either changes.