Imported from byte5ai/omadia (AGENTS.md). Install upstream with npx skills add byte5ai/omadia. Copyright stays with the author.

AGENTS.md — Mandatory Reading for Every LLM Agent Touching This Repo

Du bist ein Agent, der an diesem Repo arbeitet. Dieses Dokument ist nicht optional. Lies es vollständig, bevor du Code, Config, Secrets, Skills oder Docs änderst.

Das Projekt wird von mehreren parallelen Agents weiterentwickelt (Claude Code in verschiedenen Chats, manchmal mehrere gleichzeitig). Ohne disziplinierte Dokumentation verlieren wir innerhalb von Stunden den Überblick, welcher Zustand produktionswirksam ist. Das ist bereits passiert — siehe docs/CHANGELOG.md Eintrag 2026-04-19 — crashloop durch verpasste Schema-Sync.

Kernregel: Dokumentieren ist Teil der Aufgabe, nicht ein Nice-to-have

Jede Änderung an Code, Schema, Secrets, Skills, Agent-Configs, Dockerfile, fly.toml, Deploy-Pipeline oder Architektur muss im gleichen Arbeitsschritt dokumentiert werden — bevor die Aufgabe als erledigt gilt.

Ohne Doku-Update ist eine Änderung nicht fertig, selbst wenn der Build grün und das Deploy live ist.

Was wo dokumentiert wird (Entscheidungs-Baum)

Wenn die Zuordnung unklar ist: lieber in CHANGELOG notieren als gar nicht — später konsolidieren.

Einstiegsreihenfolge für eine neue Session

1. AGENTS.md (dieses Dokument)
2. docs/README.md — Index aller Docs
3. docs/middleware-agent-handoff.md — Architektur + Tech-Stack + Commands
4. docs/CHANGELOG.md — zuletzt passierte Änderungen (bremst vor Fehlern, die andere schon hatten)
5. Spezifisches Doc für den aktuellen Task (Security, Graph, Frontend, …)

Ohne mindestens Punkte 1–3 darf kein Code geändert werden.

Task-Routing: welches Werkzeug für welche Aufgabengröße

Bevor eine Aufgabe begonnen wird: welche Größenordnung hat sie, und passt eines der vorhandenen scripts/*.workflow.mjs-Pipelines besser als Ad-hoc-Arbeit in der aktuellen Session?

Alle Skripte in scripts/*.workflow.mjs laufen über das Workflow-Tool (Workflow({ scriptPath: "scripts/<name>.workflow.mjs", args: {...} })), nicht als eigenständige Node-Prozesse. Keines von ihnen pusht oder merged selbstständig nach GitHub — "PR erstellen" bzw. "mergen" bleibt immer ein expliziter, von einer Top-Level-Session oder einem Menschen ausgelöster Schritt.

Review-Kriterien referenzieren statt duplizieren:

• Plugin-Contract (PluginContext, 10-Punkte-Package-Checklist): middleware/assets/boilerplate/{agent-integration,agent-pure-llm}/CLAUDE.md — das ist die kanonische Quelle; docs/harness-platform/ ist nur lokales, gitignored Scratch und darf nicht als Referenz zitiert werden.
• i18n-Regeln für Frontend-Komponenten: web-ui/CLAUDE.md.

Bekannte offene Baustelle beim Testen: middleware/test/builder/builderPreviewRoutes.test.ts:735 — dokumentierte Cross-File-Test-Pollution (Test ist isoliert grün, im vollen npm run test-Lauf liefert er 404 statt 401 wegen State-Leak aus einer anderen Testdatei). Bevor Build-/Test-Caching (z. B. Turborepo) für die 28 middleware/packages/@omadia/*-Packages eingeführt wird, sollte diese Bug-Klasse behoben werden — sonst wird nur unzuverlässiges Grün schneller ausgeliefert.

Working in a multi-session repo

Convention (enforced): the main clone never receives commits. Every change — even a single-line typo fix — lands in a worktree. This is branch-agnostic: an agent whose HEAD got switched to main by a parallel session is caught here too, not just one that created a feature branch in the wrong tree. Enforced by the .hooks/pre-commit hook shipped via the engineering-standards skill.

git worktree add ../<repo>-<feature> -b <branch> main   # create with new branch
git worktree add ../<repo>-<feature> <existing-branch>  # or attach existing
# work in ../<repo>-<feature>/
git worktree remove ../<repo>-<feature>                 # remove the tree
git branch -D <feature>                                 # remove the branch ref (after merge or discard)
git worktree list                                       # inspect

Build artefacts (target/, node_modules/, etc.) live per worktree — first build per tree is full cost, subsequent builds are independent.

Bypass levels (in increasing persistence):

Drift signals (for any unusual main-tree work that is allowed)

• Run git branch --show-current before each commit and confirm it matches what you intended.
• Treat git status anomalies as drift signals: directories you didn't touch showing as ??, unexpected M on files you didn't edit. Don't commit through that — git reflog | head -20 first to see who moved your HEAD.
• Don't reach for git reset --hard reflexively; another session may have uncommitted work in the shared tree. Inspect git stash list and git diff --stat first.

Parallele Arbeit — Kollisionen vermeiden

• Fly-Deploys sind nicht atomar. Wenn ein anderer Agent gerade deployt, abwarten (30-60s), sonst trittst du ihm auf den Zeh.
• Secrets-Rotation synchronisieren. Nicht unangekündigt Secrets überschreiben — ein Agent deployt einen Proxy-Token-Rename, ein anderer Agent hält noch den alten im Skill. Kommuniziere solche Änderungen im CHANGELOG, bevor du die fly secrets set-Kommandos tippst.
• Git-Workflow ernst nehmen. Das Repo liegt seit 2026-05 öffentlich auf github.com/byte5ai/omadia. Keine direkten Pushes auf main (lokal vom .hooks/pre-push-Guard blockiert, serverseitig von Branch Protection). Alle Änderungen über Feature-Branch + PR. Conventional-Commits-Konvention gilt (siehe unten). Niemals zwei große Änderungen in einem Commit mischen — kleine, verifizierbare Schritte sind weiterhin Pflicht.

Anti-Pattern, die wir schon bezahlt haben

• Doc-less Schema-Änderung: v20-Build hat CLAUDE_AGENT_ID aus dem Zod-Schema entfernt, das Deployment enthielt aber noch das alte Config-Verhalten — Crashloop. Fix: Schema-Änderungen ab jetzt immer zusammen mit CHANGELOG-Eintrag + .env.example-Update.
• Token in Agent-Config-YAML: Bearer-Tokens dürfen nie im System-Prompt einer Agent-Config landen. Policy: Credentials gehören ausschließlich in den Deployment-Vault — siehe docs/security-architecture.md §1.
• Build-Artefakt vergessen: tsc kopiert keine .sql-Files. Fix via middleware/scripts/copy-build-assets.mjs. Generell: Non-TS-Assets brauchen immer einen expliziten Build-Schritt.

Git Workflow & Engineering Standards

Diese Regeln gelten für alle AI-Agenten (Claude, Codex, Copilot, …) und für menschliche Contributors gleichermaßen. Source of truth: byte5ai/engineering-standards. Status dieses Repos: .github/engineering-standards.yml (status: applied).

• Niemals direkt auf main pushen. Feature-Branch + PR. Lokal blockt .hooks/pre-push, serverseitig Branch Protection.
• Branch-Naming: feat/<desc>, fix/<desc>, refactor/<desc>, docs/<desc>, chore/<desc>, test/<desc>, ci/<desc>, perf/<desc>, release/vX.Y, dev/vX.Y.devN.
• Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:, ci:, perf:, release:, dev:. Subject < 70 Zeichen, Body erklärt das Warum (das Was steht im Diff).
• Keine Co-Authored-By:-Trailer für Claude, Codex, Copilot oder andere KI-Agenten. Commits werden unter der konfigurierten Git-Identität erstellt, ohne Model-Attribution-Footer. Auch nicht als empfohlenes Format in Templates oder Hilfetexten auftauchen lassen.
• Niemals force-push auf geteilte Branches (besonders main).
• Niemals Secrets committen (.env, API-Keys, Tokens). Bei Treffer: rotiert das betroffene Secret sofort.
• Niemals --no-verify. Wenn ein Hook fehlschlägt, erst die Ursache fixen.

Pre-push-Hook aktivieren

Der Hook ist in .hooks/pre-push versioniert. Aktivierung pro Working-Tree:

git config core.hooksPath .hooks   # erledigt auch script/setup

Override für Notfälle (sehr selten gerechtfertigt):

ALLOW_PUSH_TO_MAIN=1 git push origin main

PR-Regeln

• PR-Titel < 70 Zeichen, Conventional-Prefix.
• Eine logische Änderung pro PR — kein "While I'm at it…"-Stacking.
• CI muss grün sein vor Merge. Status-Checks (middleware, web-ui, schema, audit) sind Required.
• Squash-Merge ist Default; der PR-Titel wird zur Commit-Subject-Zeile.

Meta

Dieses Dokument wird selbst im CHANGELOG geführt, wenn sich die Regeln ändern. Kein stilles Ändern der Regeln ohne Doku.

— Stand 2026-05-17, byte5