# AGENTS.md
> Canonical AI policy for this repo.
## Project
Lifeloop is the provider-neutral lifecycle abstraction and normalizer for AI
harnesses: lifecycle events, capability manifests, callback envelopes, payload
delivery metadata, and receipts without importing CCD.
## Boundary
Lifeloop owns:
- harness identity, aliases, adapter manifests, lifecycle event vocabulary,
hook timing normalization, and integration modes;
- capability negotiation, lifecycle receipts, payload placement/delivery
metadata, lifecycle telemetry, failure classes, retry posture, and extension
dispatch as a lifecycle mechanism.
Lifeloop does not own:
- CCD continuity semantics; memory, recall, promotion, compaction, or
governance; recursive inference policy; prompt semantics above placement
metadata; model selection; tool or skill abstraction; or a universal IDE.
For the full boundary decision on harness concepts, see
[`docs/harness-concept-boundary.md`](docs/harness-concept-boundary.md). The
single rule is: *Lifeloop normalizes lifecycle reach. It does not normalize
meaning.*
For deep work, read `README.md`, `docs/product-thesis.md`,
`docs/harness-concept-boundary.md`, `docs/release-gates.md`, and relevant
`docs/decisions/`.
## Org-wide policy (nantobv-shared)
The bullets in this section are the org-wide floor for AI agents working on
any nantobv project. They are vendored verbatim from
[`nantobv/.github/AGENTS.shared.md`](https://github.com/nantobv/.github/blob/main/AGENTS.shared.md);
refresh the local copy with
[`scripts/sync-agents-shared.sh`](https://github.com/nantobv/.github/blob/main/scripts/sync-agents-shared.sh).
Project-specific rules live in each repo's own `AGENTS.md` sections outside
this block.
**Planning and approval**
- Read the repo's `AGENTS.md`, `README.md`, and the documents they point at
before deep implementation work.
- For non-trivial changes, propose the plan (files you expect to touch and
why, approach, rationale) and wait for approval before writing code. Plan
mode satisfies this; a dedicated planning skill or brainstorming ceremony
is not required.
- Show diffs and wait for approval before committing or pushing, unless the
user has invoked a publish workflow (e.g. `cpprrm`) that explicitly
authorizes commit/push for the current task and no stronger repo or
security gate applies.
**Git hygiene**
- Run `git status` and `git diff --minimal` before any commit.
- Stage explicit paths. Never use `git add .`.
- Keep unrelated local files out of commits, including local `.ccd.toml` and
harness work directories unless the task explicitly targets them.
**Validation and evidence**
- Run the smallest deterministic check that proves the change. Repo-specific
gates (`make verify`, `cargo test`, `go test ./...`, etc.) are defined in
each repo's Testing section and take precedence over this floor.
- Before claiming work is complete, fixed, or passing, run the relevant
verification command and cite the actual output. Do not assert success
without evidence.
- If you skip validation, state the reason explicitly.
**Safety**
- No secrets in tracked files, docs, workflows, fixtures, diagnostics, or
generated outputs.
- Do not overwrite user changes or reset the worktree without explicit
approval.
- Do not flip repository visibility or licensing policy without an explicit
decision from the operator.
- Treat external services and model calls as opt-in unless a repo policy or
explicit user request grants narrow approval.
- Prefer deterministic behavior, explicit metadata, and small reversible
changes.
**Source files**
- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and other model-instruction source
files are user-owned and maintainer-authored. Tooling in this org does not
overwrite or render replacement bodies for them except for explicit
maintainer-requested edits to those files.
**External review (standing grant)**
- Every nantobv repo that vendors this block grants standing approval to
invoke the bundled `claude-adversarial-review` skill on the selected local
diff when the user explicitly asks for that skill. Treat the explicit
request as the approval; do not ask for a second confirmation.
- The approval is narrow: it applies only to the selected repo diff, only to
the `claude-adversarial-review` skill, and only with that skill's
read-only tool permissions. It does not approve sending secrets, unrelated
files, whole-home context, or data to other external services.
- After an adversarial review returns, evaluate findings on their merits.
Address real correctness, maintainability, or contract-honesty issues with
proportionate changes. Do not add broad machinery, process, or abstraction
solely to satisfy a speculative review point.
## Engineering Rules
- Keep the library contract first; the CLI is an adapter/inspection surface.
- Prefer deterministic, machine-readable, fail-closed behavior.
- Keep client semantics out of core types. CCD, RLM, Reforge, Fixity, and
other clients attach through public contracts.
- Do not add CCD, RLM, Reforge, or Fixity dependencies to core Lifeloop.
- Add dependencies conservatively; protocol/adapter boundaries stay auditable.
- Compatibility shims are acceptable only as explicit tombstones with removal
criteria, not as hidden old implementations.
## Contract Changes
Public contract changes require tests and docs in the same change: events,
capabilities, manifests, callback/dispatch/payload envelopes, placement
metadata, receipts, failure classes, and retry posture.
Keep `tests/wire_contract.rs` (current JSON shape) aligned with
`tests/spec_alignment.rs` (target vocabulary in
`docs/specs/lifecycle-contract/body.md`).
For wire-affecting changes, update both tests in the same commit. If code and
spec disagree, the spec is the goal; file a tombstone and move toward it.
Use `docs/playbooks/wire-contract-review.md` for contract review and
`docs/playbooks/schema-bump.md` when a schema bump is required.
## Workflow
- AI-authored commits include a `Co-Authored-By:` trailer naming the model and harness.
- `cpprrm` authorizes commit, push, PR, review follow-up, and merge according
to that skill. Do not add an extra diff-approval gate unless repo-local
policy explicitly requires it.
## Automation
Dev automations live in harness-neutral surfaces so every harness and bare CI
run the same checks.
- `scripts/` — reusable shell logic.
- `Makefile` — named workflows: `make verify`, `make wire-check`,
`make lockfile-check`, `make commit`, `make bump-schema`.
- `lefthook.yml`, `docs/playbooks/`, and `.cargo/config.toml` — hooks,
checklists, and cargo aliases.
Add no logic to harness configs (`.claude/`, `.codex/`, etc.); logic must be
reachable from `make`, `git`, and CI without a harness.
## Testing
- Prefer `make verify` for repo-wide validation.
- For public contracts, add serialization tests that pin wire names.
- Foreign plugin manifest fixtures live under
`tests/fixtures/foreign_manifests/`; they must be synthetic, host-neutral,
client-neutral, and marked with `provenance.kind = "synthetic"`.
## Release
Release cut: move changelog entries from `Unreleased`; confirm `Cargo.toml`
and `Cargo.lock`; run `scripts/check-wire-contract.sh`, `make verify`, and
`cargo publish --dry-run`; commit with explicit paths and AI co-author trailer;
push `main`; create/push `vX.Y.Z`; create the GitHub release; run
`cargo publish` only after dry-run passes.
## Pituitary
Pituitary is an advisory lexical governance gate during rollout. Its config is
`.pituitary/pituitary.toml`; local equivalent: `pituitary index --rebuild &&
pituitary check-terminology`.
Treat findings as terminology-drift signals to review, not as a hard release
blocker unless the project deliberately flips the CI jobs to fail-closed.
## Source Files
The nantobv-shared block above covers the general "model-instruction source
files are user-owned" rule. Lifeloop adds two project-specific scope clauses:
- The Lifeloop list extends to `HERMES.md` and `OPENCLAW.md` beyond the
standard `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`. See
[`docs/decisions/source-files-are-user-owned.md`](docs/decisions/source-files-are-user-owned.md).
- Target host integration asset paths that Lifeloop may render or manage
(`.claude/settings.json`, `.codex/config.toml`, `.codex/hooks.json`) remain
in scope and live in `src/host_assets.rs` plus `src/host_assets/`.