# Golden Principles For Agent Legibility

These principles keep future agent runs predictable and reduce drift.

## 1. Prefer Local Explicitness Over Hidden Coupling

- Keep command behavior explicit in handlers.
- Avoid implicit side effects that are not documented or tested.

## 2. Keep Source-Of-Truth Close To Code

- User-facing command behavior lives in code + tests + `internal/cmd/help.go`.
- Agent-facing repository behavior lives in `AGENTS.md` + this `docs/` map.
- Do not move critical behavior guidance into external chat/doc systems only.

## 3. Maintain Progressive Disclosure

- `AGENTS.md` should stay short and map-like.
- Place details in focused docs under `docs/`.
- Link between docs instead of repeating long instructions.

## 4. Enforce With Commands, Not Memory

- Use `make legibility-check` to ensure critical docs and structure exist.
- Use `make verify` before claiming a change is complete.

## 5. Protect Existing Contracts

- Preserve command names, flag semantics, and error contracts unless explicitly changing them.
- If a contract changes, update tests and docs in the same change.

## 6. Fight Entropy Incrementally

- Clean up small inconsistencies when touching nearby code.
- Prefer frequent, scoped fixes over large delayed refactors.