Skip to content

AGENTS.md

Latest commit

 

History

History
48 lines (44 loc) · 2.89 KB

AGENTS.md

File metadata and controls

48 lines (44 loc) · 2.89 KB
Raw

AGENTS.md

Guidance for AI agents (and humans) working in this repository. The Context Graph Protocol is a Rust workspace: protocol types, host, reference providers (ripgrep, tree-sitter, trace, refprov), an MCP bridge and server, and a conformance suite. README.md and CONTRIBUTING.md are the authoritative sources for the details.

Standing decisions — apply without asking

Each directive below is a Steering Context Record in docs/scr/; the SCR is canonical — it carries the rationale, exceptions, and enforcement status. This block is the compiled summary that every agent — Claude Code (via CLAUDE.md's @AGENTS.md import) and Stella (which reads AGENTS.md directly) — loads at session start. The corpus is identical across the macanderson org repos.

  • SCR-001 — Tests/builds (inner loop): Never compile or run the full test suite while developing. Build and test only the crates/packages/modules touched by the change (plus direct dependents on interface changes). The full suite is CI's job. Here: cargo test -p <crate> [filter], never bare cargo test / cargo test --workspace.
  • SCR-002 — Architecture decisions: Do not ask. Choose the most durable option — the one that can't be questioned in 10 years as the right move. Cheap-and-easy only wins when it is also the excellent durable choice. Record every such decision as an ADR in docs/adr/; the ADR replaces the question.
  • SCR-003 — Definition of done: An issue closes only when every DoD checklist item is satisfied and verified. Reference-grade includes tests, code comments, docs, and CI — not just the implementation. A PR that advances an issue without finishing it links it with Refs #N rather than Closes #N: Refs does not close, so the merge gate does not hold that PR against the issue's DoD. A PR may carry both, and is gated only on what it closes. A PR that closes nothing is waived by a label, and which one is a claim: no-issue for a trivial change, closes-nothing for a substantial one that closes no issue by design.
  • SCR-004 — Fix over file: Fix what you notice in the PR you are making; two unrelated fixes in one PR is fine. File an issue only when a fix cannot responsibly ride the PR (a maintainer decision, a rig or spend, or work larger than the session), and only when fixing it moves stability, reliability, maintainability, innovation, efficiency, or performance. Apply ONLY the triage label.
  • SCR-005 — Triage separation of duties: Never apply priority (P0–P3) or size labels — a dedicated triage agent owns sizing and priority; a guard workflow strips creator-applied priorities.