# Agent Instruction Hygiene

This document is the long-term reference for keeping always-loaded agent instruction files small, navigable and stable. It applies to local and remote `AGENTS.md`, `CLAUDE.md`-style aliases and any repo-level instruction file that is automatically injected into an agent context.

## Size Budget

`AGENTS.md` is an index, not a knowledge base. The hard size budget for any local or remote `AGENTS.md` is 10 KiB, measured as bytes with `wc -c AGENTS.md`.

When an `AGENTS.md` is already over 10 KiB, do not append more detailed rules to it. Split first, then add only a one-line index entry back to `AGENTS.md`.

When editing an `AGENTS.md` would push it over 10 KiB, route the new content to a skill or a `docs/reference/*.md` document and keep `AGENTS.md` as a short pointer.

If loading or printing `AGENTS.md` triggers CLI output dump or context blow-up, treat that as a visibility bug and an instruction-hygiene bug. The fix is to split the file, not to increase output limits or ask agents to read around the dump.

## What Belongs In AGENTS.md

Keep only always-needed routing information in `AGENTS.md`:

- Project identity and source-of-truth boundaries.
- P0 one-line rules that prevent immediate damage.
- Links to the authoritative long-term reference document for each domain.
- Skill names that must be loaded for common workflows.
- Short warnings about secrets, destructive commands, target workspaces and build bans.

Do not put long examples, command transcripts, JSON output, issue timelines, architecture essays, provider-specific debugging logs or one-off incident analysis in `AGENTS.md`.

## Where Overflow Content Goes

Use this routing order when splitting content out of `AGENTS.md`:

- Reusable workflow behavior belongs in a skill `SKILL.md`, for example `$dad-dev`, `$unidesk-cicd`, `$unidesk-gh`, `$unidesk-trans`, `$unidesk-otel`, `$unidesk-webdev` or `$unidesk-ymalops`.
- Stable project constraints, workspace rules, architecture boundaries and validation criteria belong in `docs/reference/*.md`.
- CLI shape, output style, route syntax and operator ergonomics belong in `docs/reference/cli.md` unless a narrower reference already owns them.
- Deployment hygiene, fixed repo boundaries and source-of-truth rules belong in `docs/reference/devops-hygiene.md`.
- Node/lane-specific HWLAB rules belong in `docs/reference/hwlab.md` and the target repo's own reference docs.
- AgentRun source-truth and deployment-lane rules belong in `docs/reference/agentrun.md`.
- Platform-infra and YAML-first operations belong in `docs/reference/platform-infra.md` and `docs/reference/yaml-first-ops.md`.
- Process notes, temporary findings and dated investigation logs belong in GitHub issues, PR comments or process notes; they must be distilled before entering long-term reference.

If a rule is both reusable across projects and specific to UniDesk's current directories or services, put the reusable workflow in the skill and put UniDesk-specific paths, lane names and validation boundaries in `docs/reference/*.md`, then cross-reference both.

## Split Procedure

When an agent sees a local or remote `AGENTS.md` over 10 KiB:

1. Identify the detailed section being changed or expanded.
2. Move the detailed content to the owning skill or `docs/reference/*.md` document.
3. Replace the original section with one concise bullet and a link to the authoritative location.
4. Preserve P0 damage-prevention warnings in `AGENTS.md`, but compress them to one-line routing rules.
5. Do not create a single giant overflow archive as the normal solution. A temporary migration note is acceptable only if it immediately points to the domain documents that must absorb it.
6. Do not add tests, guards or preflight checks just to enforce the size budget unless the user explicitly asks. The default control is documentation hygiene plus concise review.

For large legacy files, split incrementally by domain. Each new edit should leave the touched domain smaller and better referenced than before.

## Cross-Reference Requirements

Every `AGENTS.md` index entry that points out of the file must name the authoritative target. Prefer direct paths such as `docs/reference/hwlab.md` or skill names such as `$unidesk-cicd`.

Avoid duplicated full rules between `AGENTS.md`, skills and long-term reference docs. `AGENTS.md` may summarize; the reference owns the detail. If two references conflict, update the narrower domain reference and keep only one authoritative version.

## Secrets And Output Hygiene

Instruction files must not contain secrets, full API keys, full DSNs, base64 payloads, bearer tokens, SSH private keys or copy-pastable credentials.

Do not paste large CLI output, OTel trace dumps, JSON arrays or browser transcripts into `AGENTS.md`. If a large output demonstrates a durable rule, summarize the rule and link to the issue or reference that owns the conclusion.

## Current UniDesk Routing Map

The current top-level routing map is:

- CLI behavior and output: `docs/reference/cli.md`.
- YAML-first configuration: `docs/reference/yaml-first-ops.md` and `$unidesk-ymalops`.
- Platform infrastructure: `docs/reference/platform-infra.md` and `$unidesk-sub2api` when Sub2API is involved.
- Distributed field repair: `$dad-dev` plus `docs/reference/devops-hygiene.md`.
- CI/CD and rollout: `$unidesk-cicd` plus `docs/reference/cli.md`.
- GitHub issue and PR writes: `$unidesk-gh`.
- Trans/remote patch transport: `$unidesk-trans` plus `docs/reference/cli.md`.
- Web UI, Workbench and web-probe: `$unidesk-webdev`.
- OpenTelemetry and Tempo: `$unidesk-otel` plus `docs/reference/observability.md`.
- HWLAB node/lane operation: `docs/reference/hwlab.md`.
- AgentRun: `docs/reference/agentrun.md`.
- Master/D601 development environment: `docs/reference/dev-environment.md`.
- Secretary work: `docs/reference/secretary-reference.md`.