sorb/management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8f3bdc31a1876f19da9c6d8d2660cece792f2ad8
management/AGENTS.md
T
Thore CimbalandClaude Fable 5 92b448fe30 feat: slice 3 - wiki, sources and AARs in their neckbeard homes 
Gate 4, slice 3: verfahren/, hosts/, vision/ and shared/ moved via git
mv - six AARs to docs/aar/ (four harvested by the 2026-08-09 retro,
two open), procedures and host knowledge to docs/wiki/ (admin,
deployment, architecture, new area vision), the retro protocol and the
commit mapping table to docs/sources/ (protokolle/, migration/). New:
the wiki index linking every page, and the mirror-topology page
carrying the why-two-places reasoning verbatim from the old CLAUDE.md
(F-013 preserved). All moved-path references retargeted; the link
checker drove the sweep to zero.

pruefe_prosa.py added (pattern C+D): SHA citations resolve via repo,
mapping table, optional component clones or a curated exemption list
(documented dead Gitea-force-push commits, a vendor-repo tag, an
Authentik uid that is hex but no git SHA, the external neckbeard
reference); wiki task prose without an issue reference errors, with a
visible pragma for deliberate checklists; the dead-tracker denylist
now covers every mirrored repo's retired Gitea tracker (F-005) - two
links re-verified against live GitLab titles and retargeted, five
defused into honest historical citations.

Verified: validate 0/0, gen_status --check current, drift 0. Demo on
the pre-migration state fires 6 findings (3 orphaned SHAs, 3 task
blocks); on the current tree exactly the 3 F-004 task blocks remain -
they turn green in slice 4 when the issues exist, which is why
pruefe_prosa joins CI only then.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 12:00:00 +00:00

180 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 Autor-Identität. 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).
Reference in New Issue View Git Blame Copy Permalink