# Rules for agents

Coding agents directed by a developer are the main users of gpu-engine. Instead of hiding the architecture behind presets, the package expects the agent to pick explicit layers in `net`, run `gpu-engine loop` on dev, log each try and let `promote` enforce the test-set boundary.

## The five operating rules

Every scaffolded `AGENTS.md` and the shipped skill carry these five rules (SPEC section 12):

- Tune on dev.
- Read scores from the promoted report, never from memory.
- Make one change per try.
- Log every try, kept or dropped.
- Never open the test set.

Run every try with `gpu-engine loop --log "<the one change>"`, inspect the dev table, then keep or revert the change and record that decision with `gpu-engine loop --mark kept` or `gpu-engine loop --mark dropped`. Never edit `tries.jsonl`, `reads.jsonl`, `data.lock.json`, `report.json`, `gate.json`, `MODEL_CARD.md` or `RESULTS.md` by hand.

The harness enforces the test-set boundary with static scans, a guarded file module, counted reads, output muting during test scoring, outgoing text screening and optional level 3 encryption (`gpu-engine promote --seal`). Read the full invariants on [Evaluate and promote](https://gpu-engine.dev/docs/build/evaluate-and-promote).

## Scaffolded files and shipped skill

- `gpu-engine new <name> --head tag|pooled|retrieve` writes an `AGENTS.md` in the new model package that points to the model's `SPEC.md`, repeats the five rules and copies `skills/gpu-engine/SKILL.md` into the package.
- The packed `gpu-engine` package ships `skills/gpu-engine/SKILL.md` (starting layer layouts per head, tuning guidance, how to read `tries.jsonl` and `report.json`, and the five rules), its Markdown docs (`docs/*.md`), `llms.txt` and `SPEC.md`.

## Plain-Markdown endpoints on this site

Agents can read the documentation directly as Markdown:

| Endpoint | Returns |
| --- | --- |
| [`/llms.txt`](https://gpu-engine.dev/llms.txt) | Index of every page on the site |
| [`/llms-full.txt`](https://gpu-engine.dev/llms-full.txt) | All docs pages concatenated into one Markdown document |
| `/raw/<page>.md` | Plain Markdown source for a single page |

Every absolute link in those outputs uses `https://gpu-engine.dev`.

Whenever a page covers unimplemented later-version behaviour or software-adapter-only WebGPU measurements, its Markdown body opens with a note linking to `/docs/start/status`, so agents reading raw Markdown get the same status signal as browser readers.

Source: SPEC sections 2 and 12.

<!-- vitehub-docs:section-links -->
## In this section

- [What is gpu-engine](https://gpu-engine.dev/raw/docs/start.md)
- [Quick start](https://gpu-engine.dev/raw/docs/start/quick-start.md)
- [Rules for agents](https://gpu-engine.dev/raw/docs/start/agents.md) (this page)
- [Status](https://gpu-engine.dev/raw/docs/start/status.md)

Next: [Status](https://gpu-engine.dev/raw/docs/start/status.md)

All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
