Thore CimbalandClaude Fable 5
e36ed337a7
Tracer bullet of the migration design (Gate 4, slice 1): pinned v0.1.1 baseline under docs/sources/upstream/ with provenance note, the Karpathy block moved verbatim to docs/sources/regelwerk/ (standing rule mapped onto the sources read-only mechanism), AGENTS.md assembled from the byte-true upstream sections plus the project section 6 (group rules condensed from the old CLAUDE.md), CLAUDE.md reduced to the upstream pointer, WORKFLOW.md and all four templates copied, schema.yaml extended (issue milestone/priority/status columns, component type, wiki area vision - all flagged in the header), validate.py and gen_status.py forked with marked extensions, pruefe_upstream_drift.py added, STATUS.md generated, CI gains the offline validate job, README directory link defused. Verified: validate 0 errors 0 warnings (the three pre-existing directory-link errors are gone), gen_status --check current, drift check 0 findings, baseline byte-identical to the reference checkout (10/10 files), four negative tests fire (WIP limit 3x in-progress, waiting without wartegrund, component slug mismatch, single-byte drift in WORKFLOW.md). gen_status needs Python >= 3.10 locally (write_text newline) - noted for the design AAR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
104 lines
5.1 KiB
Markdown
104 lines
5.1 KiB
Markdown
# 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.
|