Imported from bnomei/condor (AGENTS.md). Install upstream with npx skills add bnomei/condor. Copyright stays with the author.

Repository Agent Instructions

Mission

Keep Condor's facade small, ownership direct, evidence local, and candidates private beside their mature family. Fit each change to one owner and one route.

Instruction composition

• System and user instructions take precedence. Read the nearest collocated guide first; it adds constraints but never relaxes root architecture, consumer-contract, safety, or validation rules.
• Resolve guide/source/test conflicts against the current source and owning manifest; escalate unresolved ownership rather than adding a compatibility edge or another route.
• Keep instructions factual and executable: name an owner, boundary, and an existing command or source anchor.

Public consumer contract

• The published Cargo package is condor-for-games; its Rust library name is condor ([lib] name = "condor"). Consumer documentation and examples should therefore use a dependency alias such as condor = { package = "condor-for-games", ... } (or cargo add condor-for-games --rename condor) and imports such as use condor::{AStar, Grid, Pathfinder};.
• Treat root src/ as the curated consumer facade and its small set of root-owned public contracts. Do not put algorithm implementations there or tell consumers to import owner crates directly.
• Keep runtime algorithms and private not-yet-ready candidates beside their mature family in the owning crate. They use the normal family test/capture routes; do not create an experiment crate, feature, fixture, or harness route for a candidate.
• When changing the consumer surface, keep README.md, crate-level rustdoc in src/lib.rs, and caller examples aligned with the actual manifest features and public imports.

Ownership routing

Read the nearest collocated AGENTS.md before changing a package or its source. Those guides add local constraints; this root guide remains the shared validation and public-contract policy.

• docs/ is ignored local ideation space. Do not stage it or make compiled source, catalogs, or tests depend on a docs/... path.
• Generated evidence belongs below ignored target/condor/; do not recreate a tracked artifacts/ tree or treat generated output as a test input.
• Root fixture ownership is retired. Runtime crates must not embed or path-load repository corpus files; harness owns conformance corpora and bench owns benchmark-only packs.
• The architecture guard is a contract, not a compatibility escape hatch. Do not add upward facade dependencies or broaden an allowed edge to make a change compile.

Guide maintenance

Keep this guide to repository policy. Collocated guides use Mission, Scope, Do, Do not, Validation, Related, and Escalate when; review them against their manifest, source, test aggregator, and Justfile route when ownership changes.

Do

• Put code, fixtures, capture output, and presentation work with the routed owner.
• Prefer existing narrow routes and source-backed contracts; synchronize public changes across the manifest, rustdoc, README, examples, and product tests.

Do not

• Do not create a separate experiment package or route for a private candidate, restore tracked artifacts//root fixtures, or depend on committed docs/.
• Do not broaden the architecture guard, add an upward edge, or hide an ownership conflict behind a facade dependency.

Rust Hygiene

Before handing work back, agents must run these commands from the repository root:

• cargo fmt --all
• cargo clippy --all-targets --all-features -- -D warnings

Agents must not leave outstanding rustfmt or clippy issues behind. If either command reports a problem, fix it before concluding the task. If a clean run is blocked by unrelated breakage, report the blocker explicitly instead of claiming the repository is clean.

Resource-safe validation

Condor has many integration-test targets and a few intentionally expensive oracle differentials. Do not run broad test, Clippy, or Criterion commands on every edit.

• Use the checked-in Justfile recipes rather than recreating commands by hand: just test-fast <target>, just clippy-target <target>, and just format-check are the normal edit-loop tier.
• Before handoff, run the relevant nextest targets plus the required formatting and Clippy gates. The full --all-targets Clippy gate belongs at the final validation boundary, not the edit loop.
• The exhaustive any-angle oracle tests are ignored by default. Run one only when exact differential evidence is required: just test-oracle <test-name>.
• Benchmarks are evidence collection, not normal validation. Never use plain cargo bench; select the owning lane, for example just bench-any-angle -- <Criterion args>. Compile a single lane without taking measurements with just bench-compile-one <lane>; only just bench-compile-all builds every benchmark binary.
• Test targets are intentionally grouped by work domain: grid_core, any_angle, grid_preprocessing, continuous, navmesh, replanning, benchmark_metadata, product_surface, story, mapf, and the explicit navmesh_oracles route. Keep new tests in the narrowest matching owner target rather than adding an auto-discovered root. Stress evidence is opt-in: just test-story-stress.
• just test-all, just test-full, and just ci exist only as fail-fast guard entrypoints. Never call them: a workspace-wide run includes benchmark capture and stress binaries and can run for hours or days. Always select the owning package, integration-test target, or one named oracle/stress route. When doctests are relevant, run only the owning package's checked-in docs recipe.

Background-agent validation protocol

Before running validation, identify the one existing integration-test target that owns the change. Do not add a new test target when an existing domain target applies; any-angle work belongs in any_angle.

For a normal edit loop, run only the narrowest checked-in recipe:

1. just format-check
2. just test-fast <owning-target>, except a focused any-angle module uses just test-any-angle-case <module-or-test-substring>
3. just clippy-target <owning-target>

If that target contains capture or stress tests and no narrow checked-in recipe exists, stop and report the missing validation recipe. Do not replace it with a broad raw Cargo or nextest command. For a focused any-angle module, use just test-any-angle-case <module-or-test-substring> rather than just test-fast any_angle; the latter is final-suite validation for that domain. Prepared-graph promotion slices and dense graph-growth evidence are opt-in through test-any-angle-prepared-growth and test-prepared-any-angle-promotion-parity.

Never run any of the following, even when a task asks for a “full” or “all” test suite; translate that request to the complete set of scoped owner routes:

• just test-all, just test-full, or just ci (all fail immediately with this warning);
• a whole domain target other than the declared owning target;
• cargo test or cargo nextest run without a target and filter;
• benchmark-capture integration tests;
• Criterion measurement commands or plain cargo bench.

Exact oracle tests are opt-in evidence, not normal validation. Run exactly one named test through just test-oracle <test-name> only when the task explicitly requires exact differential evidence.

Cargo uses the shared repository target/ directory. Before starting a Cargo or nextest command, check whether another task is already compiling or testing. If Cargo reports a build-directory lock, do not start another Cargo command, retry in a loop, or use a different target directory: report that the lane is busy and wait for direction.

A completion report must list every command actually run, its exit result, and the target name. “Done” is invalid until the changes are present in this checkout and either committed or explicitly reported as uncommitted. At the final handoff boundary, retain the Rust Hygiene requirements above; do not run the full Clippy gate repeatedly during the edit loop.

Related

CONTRIBUTING.md defines contributor-facing ownership and dependency rules; Cargo.toml defines package/features, Justfile supported validation, and source, fixtures, and tests define behavior.

Escalate when

A change would cross an ownership boundary, change a public compatibility path, add a dependency edge or target, move an authoritative corpus, or lacks a narrow checked-in validation route.