---
name: atrinik-guidance-maintenance
description: Synchronize Atrinik agent and contributor guidance after contract changes or during drift reviews.
---

# Maintain Atrinik agent guidance

For an audit, stay read-only and report evidenced drift. For requested changes,
use an owned [source worktree](../../references/atrinik-workspace/docs/SOURCE_DELIVERY.md). An audit alone
does not authorize initialization, synchronization, cleanup or external writes.

## Gather evidence

1. Inspect `git status --short`, `./atrinik manifest validate`, and `./atrinik
   status --json`. Preserve dirty checkouts, report unavailable ones, and
   remember root Git status omits ignored repositories.
2. Review recent/path-specific history. Verify behavior against code, CLI
   `--help`, the manifest, CI, and relevant README/architecture sections.
3. Map affected components to physical checkouts; read each nearest
   `AGENTS.md` and relevant skill. Exclude generated/preserved copies below
   `workspace/` and `build/` from the authoritative inventory.
4. Record path, owner, lines, evidence, and status: current, stale, missing,
   duplicated, or unverifiable. Include `docs/COORDINATOR_AUTH.md` and its
   composition/skill consumers when the shared host auth contract changes.

## Correct ownership and drift

- Keep root `AGENTS.md` below 150 lines; put the overview, folder map, routing,
  universal safety, and exact contributor commands there.
- Put component architecture/validation in the nearest nested guide, never in
  the wrapper. Put repetitive non-obvious procedures in skills; use only
  `name` and a trigger-optimized `description` in frontmatter, and align the
  concise imperative body with `agents/openai.yaml`.
- Put operator behavior in `README.md`, lifecycle/trust invariants in
  `docs/ARCHITECTURE.md`, and contributor checks in `CONTRIBUTING.md`.
- Remove stale duplication and link to its owner. Keep ordinary source entry
  separate from retained-resource protocols; specialist checks load only when
  the affected mechanism needs them. Do not turn a historical incident into a
  universal preflight. Edit only evidenced drift or the requested policy and
  synchronize only surfaces sharing the contract. For skill additions/removals,
  update inventory regressions and UI metadata. Load
  `atrinik-multi-repo-workspace` when the cross-checkout contract itself changes.
- When recovery wording changes, preserve the distinction in
  [local recovery](https://github.com/atrinik/atrinik/blob/476cf9dad436ce7b5fb89113c46014fcca3b8f77/docs/LOCAL_RECOVERY.md): an authorized, bounded
  local blocker repair requires fresh task identity and ownership, exclusive
  coordination, a no-live-process fence, and evidence preservation. It grants
  no external write or live-resource authority. Keep actual collisions,
  ambiguous ownership, secrets, cleanup, merge, and deployment restrictions.

## Validate

```sh
python3 -m coverage run -m unittest discover -v
python3 -m coverage report --show-missing
python3 -m compileall -q atrinik atrinik_workspace tests
python3 -m atrinik_workspace.guidance_inventory --check
./atrinik manifest validate
git diff --check
```

Run the active Codex `skill-creator` validator for changed skills. For substantial
routing or recovery changes, independently exercise realistic task scenarios:
ordinary source work, isolated helper repair, same-owner interrupted edits,
missing or damaged local metadata, a live process fence, an actual resource
collision, and missing external acceptance. Use temporary fixtures; do not
mutate live resources to test guidance. Add ShellCheck,
actionlint, or builds when relevant; supply-chain is optional. Never claim
coverage for unread checkouts.

## Report

```text
Guidance audit
Scope: repositories and revision/range reviewed
History/direction: evidence-backed themes
Inventory: path | owner | lines | status
Changes:
- path — correction and reason
Validation:
- command — pass, fail, or not run with reason
Gaps:
- inaccessible/unverified contract, or none
```

For a no-change audit, write `Changes: none` and cite supporting evidence.