# AGENTS — Nika engine

This public repository owns the Nika engine and canonical agent plugin under
`.agents/plugins/nika/`. The current user request defines scope and authorized
actions. Preserve concurrent work and establish the checkout, branch, HEAD and
staged changes before editing; do not switch a shared checkout for discovery.

## Find the relevant contract

| Work | Read when needed |
|---|---|
| Product overview and documentation | `README.md`, `llms.txt` |
| Workflow authoring or static findings | `.agents/plugins/nika/skills/nika-authoring/SKILL.md` |
| Run diagnosis, migration or operations | Corresponding skill under `.agents/plugins/nika/skills/` |
| Rust API, layer or architecture change | `docs/architecture/forward-compat-invariants.md`, `docs/architecture/crate-layer-registry.md`, affected crate spec and ADR |
| Admit a crate | `CONTRIBUTING.md`, `docs/adr/adr-003-12-gate-admission.md`, `.claude/skills/crate-admit/SKILL.md` |
| Release readiness or future direction | `ROADMAP.md`, `CHANGELOG.md`, `DIAMOND.md`; long-horizon details in `docs/architecture/VISION_2040_intelligence-layer.md` |
| Contribution history or session handling | `.claude/rules/INDEX.md` |

Read the material needed for the requested change, not the whole table.
The historical `.claude/` directory contains shared contributor guidance;
client adapters do not choose a model or override the user's mandate.

## Preserve the engine contracts

- `brouillon` is read-only legacy reference: use `git show brouillon:path`.
  Never check it out or copy legacy defects into the current implementation.
- No `.unwrap()` or `.expect(` in production `src/`, and no
  `#[allow(dead_code)]`. Propagate errors with `?` and follow workspace lints.
- Split files beyond 2,500 LOC; crates beyond 25,000 production LOC are rejected,
  with no exception (ADR-154). The hygiene dashboard warns above 1,500 LOC per
  file and 15,000 per crate without blocking: plan a descent there.
  Public error enums are `#[non_exhaustive]`; every I/O sits behind a kernel
  trait. Dependency layers and response compatibility follow the architecture
  invariants, not an improvised alternative.
- A verdict must cover its claim or narrow it. A waiver that calls a check
  undecidable must name the decidable sub-question considered and why it does
  not apply. See `crates/nika-check/src/lib.rs` and
  `docs/plans/2026-07-28-verdict-coverage.md` for the concrete failures.
- Crate admission still requires all 12 ADR-003 gates in the same PR; this
  entry does not relax them or apply admission ceremony to ordinary edits.

## Complete and verify the requested work

Use `rust-toolchain.toml`, package manifests and the relevant CI targets.
Default local unit checks are `cargo test -p <package> --lib --locked`;
select hermetic integration tests or doctests when the changed contract lives
there. Inspect test effects first: Keychain, credentials and provider suites
are not interchangeable with disposable local fixtures. Run authorized local
checks, repair failures caused by the change and rerun affected checks without
asking for approval at every iteration.

For Rust changes, run appropriate clippy targets and `cargo fmt --all -- --check`.
Use `bash scripts/hygiene/check-all.sh` for required repository hygiene and the
affected plugin/onboarding tests when changing emitted guidance. Keep existing
hooks. Do not use `--no-verify` or claim unexecuted checks passed. Broaden testing
when consumers, failures or remaining uncertainty justify it.

A new or changed `pub` item in an admitted crate also updates that crate's
`public-api.txt`. The pre-push gate does not run that diff. The `public-api`
workflow does, and on a failure it uploads its own rendering of every crate
as the `public-api-actual` artifact: take the crate's file from there rather
than from a local build with another toolchain.

Report the changed behavior, exact checks and limitations. Completion includes
the requested integration or execution when authorized; a first implementation
is not the stopping point. Pause only at a concrete unresolved decision or
missing authority, while finishing independent work. Never force-push, erase
another session's work or add unrelated files to the index.

## Ownership and publication

The plugin kit is canonical here. The marketplace repository mirrors released
tags using its `mirror.json`; edits reach it through its release sync, not a
hand-edited mirror. `nika init` embeds the kit: ship referenced resources with
its entrypoint and validate emitted artifacts. A model name does not establish
capabilities; keep prompts portable and preserve provider/user choices.

Stage explicit paths and inspect the staged diff before committing. One logical
change per commit, subject `type(scope): lowercase description`, trailer:
`Co-Authored-By: Nika 🦋 <nika@supernovae.studio>`. Use `git commit -s` for the author-matching DCO sign-off required by `CONTRIBUTING.md`. Publication follows existing
authorization and repository policy; do not ask again for an authorized push.

Keep private plans, research, private workspace paths, tokens and production
`.env` values out of this public repository. Optional private tooling may help
locally but is not required by contributors. Fall back to repository search
when an optional tool is unavailable. Report security issues using `SECURITY.md`.

Live counts are generated by `scripts/refresh-status.sh` and parity-checked in
`.claude/CLAUDE.md`; do not hand-copy them into instructions. Recorded counts
are evidence at their recorded revision, not the current checkout's test result.