# AGENTS.md — Canonical Agent Instructions

Canonical instruction set for any coding agent working in this repository
(Claude Code, GPT-OSS harnesses, others). `CLAUDE.md` points here.
This file is loaded into every session — keep it short. Process details
live in `WORKFLOW.md`; read that when a task begins, not preemptively.

Tradeoff: these rules bias toward caution over speed. For trivial tasks,
use judgment — but say so.

## 1. Operating Rules

### Think before coding
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### Simplicity first
- Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked. No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
- Test: "Would a senior engineer call this overcomplicated?" If yes, simplify.
- Before writing new code, stop at the first rung that holds:
  needed at all? → codebase already has it? → stdlib? → platform-native?
  → installed dependency? → one line? → only then: the minimum that works.
  (Ladder after ponytail, MIT.)
- Never cut, at any rung: trust-boundary validation, data-loss handling,
  security, accessibility.
- Lazy about the solution, never about reading the code first.

### Surgical changes
- Touch only what you must. Match existing style, even if you'd differ.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- If you notice unrelated dead code, mention it — don't delete it.
- Remove imports/variables/functions that YOUR changes made unused;
  leave pre-existing dead code alone unless asked.
- Every changed line must trace directly to the request.

### Goal-driven execution
- Transform tasks into verifiable goals:
  "fix the bug" → "write a test that reproduces it, then make it pass".
- For multi-step work, state a brief plan: step → verify, step → verify.
- A task is well-defined only if it names all four:
  **files, action, verify, done.** Missing one? The task is too vague — say so.

### Verification before completion
- Never claim something works without evidence: a test run, command
  output, a rendered result. "Should work" is not a status.
- Report every task/slice with exactly one status:
  `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`.
- Uncertainty is reported, never swallowed. Flag your shakiest calls.

## 2. Project Initialization (Gate 0)

At session start, read `PROJECT.md`. If it does not exist, initialization
is your first task: before anything else, ask the Gate 0 questions defined
in `WORKFLOW.md` — response language, size-S gate exception (yes/no),
one-line project purpose, audience — write the answers to `PROJECT.md`,
and have `validate.py` accept it. Never guess these answers; ask.

## 3. Workflow

For anything beyond a trivial change, read `WORKFLOW.md` and follow its
gates. At task start, propose a size class (S/M/L); the human confirms
(possibly batched later). **Never advance past a gate without explicit
human approval** — sole exception: size-S tasks, and only if `PROJECT.md`
explicitly grants that exception.

## 4. Repository Map

| Path | Purpose |
|---|---|
| `WORKFLOW.md` | Gate 0 (init) + Gates 1–5, size classes, debugging path, session handoff, refinement ritual |
| `PROJECT.md` | Per-project answers from Gate 0: language, size-S exception, purpose, audience |
| `STATUS.md` | Generated overview: open issues, active designs, recent ADRs — do not edit by hand |
| `schema.yaml` | Frontmatter schema — single source of truth for artifact structure |
| `docs/adr/` | Architecture Decision Records — binding; never edited, only superseded |
| `docs/design/` | One design doc per undertaking; completed ones move to `done/` |
| `docs/aar/` | Standalone After Action Reviews (incidents, major deviations only) |
| `docs/issues/` | In-repo issues, one file each; status lives in frontmatter |
| `docs/wiki/` | Wiki areas as folders, created on demand — rules in `docs/wiki/index.md` |
| `docs/sources/` | Immutable original sources; wiki pages cite them — read-only for agents |
| `scripts/` | Deterministic tooling: `validate.py`, `gen_status.py` |

Before proposing options (Gate 2), read the relevant ADRs and AARs first —
past decisions and learnings are input, not trivia.

## 5. Artifact Rules

- All artifacts are standard Markdown with YAML frontmatter conforming to
  `schema.yaml`. Standard links only (`[text](path.md)`), no wikilinks.
  Diagrams as Mermaid. This keeps every artifact portable across LLMs,
  GitLab, and Obsidian.
- Never invent frontmatter fields or status values. `validate.py` is
  authoritative; if it rejects your artifact, fix the artifact, not the
  validator.
- Deterministic jobs (status generation, validation, link checks) are done
  by scripts, not by you. If a deterministic job lacks a script, propose
  one instead of doing it by inference.

<!-- projektabschnitt -->

## 6. Gruppenregeln (Projekt axion1337.chat)

Dieses Repo steuert die Gruppe `axion1337.chat`. Die Abschnitte 1–5
oben sind neckbeard v0.1.1 und bleiben byte-treu (Baseline:
`docs/sources/upstream/neckbeard-v0.1.1/`, Prüfung:
`scripts/pruefe_upstream_drift.py`); §1 ist destilliert aus den
wortgleich archivierten
[Karpathy-Guidelines](docs/sources/regelwerk/karpathy-guidelines.md).
**Änderungen an dieser Datei nur mit sorb abgestimmt.** Dieser
Abschnitt gilt für jede Session in allen Repos der Gruppe;
Komponenten-Repos tragen nur Projektspezifika plus einen Pointer
hierher ([ADR-0013](docs/adr/0013-gruppenregeln-kanonisch-mit-pruefung.md)).
Ohne Lab-Zugang: dieses Repo ist als Push-Mirror unter
`https://rohana.axion1337.de/sorb/management` lesbar — pushen dorthin ist tabu.

### Quelle der Wahrheit & Mirror-Topologie

- `git.lab/axion1337.chat/*` ist kanonisch; Gitea/rohana wird per
  Push-Mirror beliefert und bleibt Flux-Quelle, Registry und
  Release-Download ([ADR-0001](docs/adr/0001-gitlab-kanonisch-push-mirror.md),
  [ADR-0004](docs/adr/0004-site-to-site-vpn-hetzner-lab.md)). Die
  Flux-Quelle **nicht auf git.lab „geradeziehen"** — die Produktion darf
  nicht an der Lab-Verfügbarkeit hängen.
- **Nie direkt zu Gitea pushen** (der Mirror überschreibt per Force).
  Landet doch ein Commit dort: Kanonisierungs-Verfahren in
  [verfahren/deploy-uebergabe.md](docs/wiki/deployment/deploy-uebergabe.md).
- Einzige bewusste Ausnahme: der TURN-Rotations-CronJob schreibt nach
  Gitea; der tägliche CI-Job `canonize_rotation` holt es zurück. Seine
  rote Pipeline **ist** der Alarm — es gibt bewusst keinen zweiten Meldeweg.

### Issues & Board

- `docs/issues/` ist kanonisch für den Management-Scope
  ([ADR-0012](docs/adr/0012-issues-im-repo-gitlab-als-spiegel.md));
  GitLab ist bespiegelte Ansicht. Jedes Issue trägt genau einen
  Meilenstein (M1–M5) und genau eine Priorität — das Schema erzwingt
  beides. Zeitkritisches trägt ein `due`-Datum, nicht „bald".
- **WIP-Limit 2** (Validator-Regel). Die Zusage-Status `next` und
  `in-progress` vergibt **nur sorb**; Sessions bilden ab (`waiting` mit
  `wartegrund`, Erledigtes `done` mit Begründung im Issue-Commit),
  sagen aber nichts zu.
- **ADR-Pflicht** bei Architektur-/Prozessentscheidungen und **jeder
  dauerhaften Ausnahme von einer Regel** — eine Ausnahme nur zu
  dokumentieren statt sie zu entscheiden, ist ein Fehler.

### Secrets & Credentials

- Token-/Secret-Werte **niemals anzeigen, loggen oder in Dateien
  echoen** — anzeigen = Exposure = Rotation. Referenz nur über
  Dateipfade (z. B. `~/.config/gitlab-lab/token`) oder maskierte
  CI-Variablen. Die Trennung ist „Credential vs. Config":
  nicht-geheime Konfiguration wird normal committet.

### Commit-Konventionen

- Nachrichten auf Englisch, Conventional-Stil; der Betreff sagt *was*,
  der Rumpf *warum*.
- Autor- **und** Committer-Datum auf 12:00:00 UTC des laufenden Tages.
- **Kanonische Identität** (gilt für alle Repos der Gruppe): Autor
  `Thore Cimbal <cfx@riot.8shield.net>`, dazu ein Trailer
  `Co-Authored-By: <Modell> <noreply@anthropic.com>` — Agenten-Sessions
  committen also **nicht** unter eigener Identität, sondern kenntlich als
  Beitrag. Ausnahme: der `turn-secret-rotation`-Bot committet maschinell,
  eine Zuschreibung an einen Menschen wäre dort falsch (ADR-0009).
- Historien-Rewrites nur mit alt→neu-Zuordnung
  ([ADR-0009](docs/adr/0009-commit-konventionen-und-historien-anonymisierung.md),
  Tabelle: [shared/commit-zuordnung-2026-08-07.md](docs/sources/migration/commit-zuordnung-2026-08-07.md)).
- ⚠️ Das schützt nur die Git-Historie; Plattform-Zeitstempel (Push,
  Issues, Pipelines, Pakete) tragen die echte Uhrzeit (ADR-0009).

### Redlichkeit

- Verifiziert (Messung/Konsole) klar von Vermutung trennen;
  Korrelation ≠ Kausalität — ein plausibler Verdacht ist kein Befund.
- Config-Dateien chirurgisch editieren, **nie re-dumpen**; vor dem Push
  validieren (`docker compose config`, YAML-Parse).
- Fehlschläge und übersprungene Schritte benennen, nicht glätten —
  „fertig" heißt verifiziert (deckungsgleich mit §1).