USER.md beantwortet, wer die Instanz bedient, SOUL.md, wie sie klingt. Womit sie
arbeitet, beantwortet niemand: welches Harness läuft, welche Skills publiziert sind, welche
MCP-Server erreichbar sind, welche Connectoren dranhängen, wohin publish veröffentlicht, wo
CI läuft.
Das sind über Wochen konstante Werte — und trotzdem erfragt oder errät sie jede Session neu,
weil nichts sie festhält.
Vorschlag
Ein drittes Root-Dokument der Session-Ebene, ENVIRONMENT.md, mit ENVIRONMENT.md.template
als Abschnittsvorgabe. Von CLAUDE.md importiert (Claude Code), von AGENTS.md über die
Namenstabelle und einen eigenen Abschnitt erreicht (übrige Harnesses).
Drei Abgrenzungen gegen die bestehende Personalization Plane:
Optional. Fehlt die Datei, ist das ein gültiger Endzustand. doctor meldet environment: absent (optional), niemals FAIL — ein FAIL würde sie durch die Hintertür
verpflichtend machen. Genau ein Fall wird gemeldet, als WARN: ein umbenanntes, nie
ausgefülltes Template.
Gitignored. Zwei Clones sind zwei Umgebungen. Eine committete Fassung gäbe dem zweiten
Clone Antworten, die falsch sind statt zu fehlen.
Kontext, keine Autorität. Beschreibt, was da ist, nicht, was erlaubt ist. Ein gelisteter
Remote autorisiert kein git push (Invariante 5), ein gelisteter MCP-Server öffnet kein
Gate, nichts darin ist eine Quelle nach Invariante 3. Keine Geheimnisse.
Akzeptanzkriterien
ENVIRONMENT.md.template liegt im Root und wird von dist export ausgeliefert; die
ausgefüllte Fassung nie.
.gitignore ignoriert ENVIRONMENT.md, aber nichtENVIRONMENT.md.template; docs verify prüft beide Hälften.
doctor hat einen environment-Check: absent → OK, ausgefüllt → OK, Sentinel → WARN. Nie FAIL.
CLAUDE.md importiert die Datei; AGENTS.md trägt Namenstabellen-Zeile und Abschnitt.
bootstrap.md und setup-instance.md bieten das Anlegen an, als optionalen Schritt.
Tests für alle drei doctor-Ausgänge, den dist export-Split und die Ignore-Kanarien.
MINOR-Bump (neue Fähigkeit, rückwärtskompatibel) plus Changelog-Eintrag.
## Ausgangslage
`USER.md` beantwortet, **wer** die Instanz bedient, `SOUL.md`, **wie** sie klingt. Womit sie
arbeitet, beantwortet niemand: welches Harness läuft, welche Skills publiziert sind, welche
MCP-Server erreichbar sind, welche Connectoren dranhängen, wohin `publish` veröffentlicht, wo
CI läuft.
Das sind über Wochen konstante Werte — und trotzdem erfragt oder errät sie jede Session neu,
weil nichts sie festhält.
## Vorschlag
Ein drittes Root-Dokument der Session-Ebene, `ENVIRONMENT.md`, mit `ENVIRONMENT.md.template`
als Abschnittsvorgabe. Von `CLAUDE.md` importiert (Claude Code), von `AGENTS.md` über die
Namenstabelle und einen eigenen Abschnitt erreicht (übrige Harnesses).
Drei Abgrenzungen gegen die bestehende Personalization Plane:
- **Optional.** Fehlt die Datei, ist das ein gültiger Endzustand. `doctor` meldet
`environment: absent (optional)`, niemals `FAIL` — ein `FAIL` würde sie durch die Hintertür
verpflichtend machen. Genau ein Fall wird gemeldet, als `WARN`: ein umbenanntes, nie
ausgefülltes Template.
- **Gitignored.** Zwei Clones sind zwei Umgebungen. Eine committete Fassung gäbe dem zweiten
Clone Antworten, die falsch sind statt zu fehlen.
- **Kontext, keine Autorität.** Beschreibt, was da ist, nicht, was erlaubt ist. Ein gelisteter
Remote autorisiert kein `git push` (Invariante 5), ein gelisteter MCP-Server öffnet kein
Gate, nichts darin ist eine Quelle nach Invariante 3. Keine Geheimnisse.
## Akzeptanzkriterien
- [ ] `ENVIRONMENT.md.template` liegt im Root und wird von `dist export` ausgeliefert; die
ausgefüllte Fassung nie.
- [ ] `.gitignore` ignoriert `ENVIRONMENT.md`, aber **nicht** `ENVIRONMENT.md.template`;
`docs verify` prüft beide Hälften.
- [ ] `doctor` hat einen `environment`-Check: absent → `OK`, ausgefüllt → `OK`, Sentinel →
`WARN`. Nie `FAIL`.
- [ ] `CLAUDE.md` importiert die Datei; `AGENTS.md` trägt Namenstabellen-Zeile und Abschnitt.
- [ ] `bootstrap.md` und `setup-instance.md` bieten das Anlegen an, als optionalen Schritt.
- [ ] Tests für alle drei `doctor`-Ausgänge, den `dist export`-Split und die Ignore-Kanarien.
- [ ] MINOR-Bump (neue Fähigkeit, rückwärtskompatibel) plus Changelog-Eintrag.
ENVIRONMENT.md.template im Root, von dist export ausgeliefert (ROOT_FILES); die
ausgefüllte Fassung nie — sie ist zusätzlich gitignored, also doppelt ausgeschlossen.
.gitignore ignoriert /ENVIRONMENT.md, nicht das .template. Beide Hälften prüft docs verify: ENVIRONMENT.md in REQUIRED_IGNORE_CANARIES, ENVIRONMENT.md.template in REQUIRED_TRACKED_PATHS. Das nachlässige ENVIRONMENT.md* würde beide schlucken — genau
das fängt der Kanarienvogel ab.
CLAUDE.md importiert @ENVIRONMENT.md; AGENTS.md hat Namenstabellen-Zeile und einen
eigenen Abschnitt „Environment" (nötig, weil die übrigen Harnesses CLAUDE.md nicht lesen).
bootstrap.md Schritt 5, setup-instance.md Schritt 9 — beide optional, beide mit der
Regel „eintragen was ablesbar ist, einmal fragen, weiß ich nicht akzeptieren, leeren
Abschnitt löschen statt raten".
Tests: drei doctor-Ausgänge, der dist export-Split, die Ignore-Kanarien.
MINOR-Bump plus Changelog-Eintrag.
Entscheidung, die im Issue noch offen war: Import statt Link in CLAUDE.md. Was hier steht,
wird nebenbei gebraucht — beim Griff zum richtigen MCP-Server, mitten in einer Aufgabe. Eine
Session, die erst nachschlagen müsste, fragt stattdessen wieder den Nutzer, und genau das sind
die Kosten, die die Datei beseitigt. Dass ein unaufgelöster Import folgenlos bleibt, war schon
vorher so (USER.md/SOUL.md vor dem Setup); hier wird es zum Dauerzustand statt zum Übergang.
Nicht gebaut, bewusst: kein wikitool environment-Kommando zum Anlegen oder Abfragen. Die
Datei wird von Menschen und Agenten gelesen und selten geschrieben; ein Kommando dafür wäre
Maschinerie ohne Abnehmer. Das Template und zwei Instruktionsschritte reichen.
Verifiziert: 730 Tests grün, docs verify, instructions verify, lint --fail-on-error,
und der CI-Smoke-Test (Export → frische Instanz → doctor/verify/lint/migrate status)
läuft durch; doctor meldet dort environment: absent (optional).
Umgesetzt in `a243a4a`, Stack **1.8.0**.
Alle Akzeptanzkriterien erfüllt:
- `ENVIRONMENT.md.template` im Root, von `dist export` ausgeliefert (`ROOT_FILES`); die
ausgefüllte Fassung nie — sie ist zusätzlich gitignored, also doppelt ausgeschlossen.
- `.gitignore` ignoriert `/ENVIRONMENT.md`, nicht das `.template`. Beide Hälften prüft
`docs verify`: `ENVIRONMENT.md` in `REQUIRED_IGNORE_CANARIES`, `ENVIRONMENT.md.template` in
`REQUIRED_TRACKED_PATHS`. Das nachlässige `ENVIRONMENT.md*` würde beide schlucken — genau
das fängt der Kanarienvogel ab.
- `doctor.check_environment()`: absent → `OK`, ausgefüllt → `OK`, Sentinel → `WARN`. Nie
`FAIL`.
- `CLAUDE.md` importiert `@ENVIRONMENT.md`; `AGENTS.md` hat Namenstabellen-Zeile und einen
eigenen Abschnitt „Environment" (nötig, weil die übrigen Harnesses `CLAUDE.md` nicht lesen).
- `bootstrap.md` Schritt 5, `setup-instance.md` Schritt 9 — beide optional, beide mit der
Regel „eintragen was ablesbar ist, einmal fragen, `weiß ich nicht` akzeptieren, leeren
Abschnitt löschen statt raten".
- Tests: drei `doctor`-Ausgänge, der `dist export`-Split, die Ignore-Kanarien.
- MINOR-Bump plus Changelog-Eintrag.
**Entscheidung, die im Issue noch offen war: Import statt Link in `CLAUDE.md`.** Was hier steht,
wird nebenbei gebraucht — beim Griff zum richtigen MCP-Server, mitten in einer Aufgabe. Eine
Session, die erst nachschlagen müsste, fragt stattdessen wieder den Nutzer, und genau das sind
die Kosten, die die Datei beseitigt. Dass ein unaufgelöster Import folgenlos bleibt, war schon
vorher so (`USER.md`/`SOUL.md` vor dem Setup); hier wird es zum Dauerzustand statt zum Übergang.
**Nicht gebaut, bewusst:** kein `wikitool environment`-Kommando zum Anlegen oder Abfragen. Die
Datei wird von Menschen und Agenten gelesen und selten geschrieben; ein Kommando dafür wäre
Maschinerie ohne Abnehmer. Das Template und zwei Instruktionsschritte reichen.
**Verifiziert:** 730 Tests grün, `docs verify`, `instructions verify`, `lint --fail-on-error`,
und der CI-Smoke-Test (Export → frische Instanz → `doctor`/`verify`/`lint`/`migrate status`)
läuft durch; `doctor` meldet dort `environment: absent (optional)`.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Ausgangslage
USER.mdbeantwortet, wer die Instanz bedient,SOUL.md, wie sie klingt. Womit siearbeitet, beantwortet niemand: welches Harness läuft, welche Skills publiziert sind, welche
MCP-Server erreichbar sind, welche Connectoren dranhängen, wohin
publishveröffentlicht, woCI läuft.
Das sind über Wochen konstante Werte — und trotzdem erfragt oder errät sie jede Session neu,
weil nichts sie festhält.
Vorschlag
Ein drittes Root-Dokument der Session-Ebene,
ENVIRONMENT.md, mitENVIRONMENT.md.templateals Abschnittsvorgabe. Von
CLAUDE.mdimportiert (Claude Code), vonAGENTS.mdüber dieNamenstabelle und einen eigenen Abschnitt erreicht (übrige Harnesses).
Drei Abgrenzungen gegen die bestehende Personalization Plane:
doctormeldetenvironment: absent (optional), niemalsFAIL— einFAILwürde sie durch die Hintertürverpflichtend machen. Genau ein Fall wird gemeldet, als
WARN: ein umbenanntes, nieausgefülltes Template.
Clone Antworten, die falsch sind statt zu fehlen.
Remote autorisiert kein
git push(Invariante 5), ein gelisteter MCP-Server öffnet keinGate, nichts darin ist eine Quelle nach Invariante 3. Keine Geheimnisse.
Akzeptanzkriterien
ENVIRONMENT.md.templateliegt im Root und wird vondist exportausgeliefert; dieausgefüllte Fassung nie.
.gitignoreignoriertENVIRONMENT.md, aber nichtENVIRONMENT.md.template;docs verifyprüft beide Hälften.doctorhat einenenvironment-Check: absent →OK, ausgefüllt →OK, Sentinel →WARN. NieFAIL.CLAUDE.mdimportiert die Datei;AGENTS.mdträgt Namenstabellen-Zeile und Abschnitt.bootstrap.mdundsetup-instance.mdbieten das Anlegen an, als optionalen Schritt.doctor-Ausgänge, dendist export-Split und die Ignore-Kanarien.Umgesetzt in
a243a4a, Stack 1.8.0.Alle Akzeptanzkriterien erfüllt:
ENVIRONMENT.md.templateim Root, vondist exportausgeliefert (ROOT_FILES); dieausgefüllte Fassung nie — sie ist zusätzlich gitignored, also doppelt ausgeschlossen.
.gitignoreignoriert/ENVIRONMENT.md, nicht das.template. Beide Hälften prüftdocs verify:ENVIRONMENT.mdinREQUIRED_IGNORE_CANARIES,ENVIRONMENT.md.templateinREQUIRED_TRACKED_PATHS. Das nachlässigeENVIRONMENT.md*würde beide schlucken — genaudas fängt der Kanarienvogel ab.
doctor.check_environment(): absent →OK, ausgefüllt →OK, Sentinel →WARN. NieFAIL.CLAUDE.mdimportiert@ENVIRONMENT.md;AGENTS.mdhat Namenstabellen-Zeile und eineneigenen Abschnitt „Environment" (nötig, weil die übrigen Harnesses
CLAUDE.mdnicht lesen).bootstrap.mdSchritt 5,setup-instance.mdSchritt 9 — beide optional, beide mit derRegel „eintragen was ablesbar ist, einmal fragen,
weiß ich nichtakzeptieren, leerenAbschnitt löschen statt raten".
doctor-Ausgänge, derdist export-Split, die Ignore-Kanarien.Entscheidung, die im Issue noch offen war: Import statt Link in
CLAUDE.md. Was hier steht,wird nebenbei gebraucht — beim Griff zum richtigen MCP-Server, mitten in einer Aufgabe. Eine
Session, die erst nachschlagen müsste, fragt stattdessen wieder den Nutzer, und genau das sind
die Kosten, die die Datei beseitigt. Dass ein unaufgelöster Import folgenlos bleibt, war schon
vorher so (
USER.md/SOUL.mdvor dem Setup); hier wird es zum Dauerzustand statt zum Übergang.Nicht gebaut, bewusst: kein
wikitool environment-Kommando zum Anlegen oder Abfragen. DieDatei wird von Menschen und Agenten gelesen und selten geschrieben; ein Kommando dafür wäre
Maschinerie ohne Abnehmer. Das Template und zwei Instruktionsschritte reichen.
Verifiziert: 730 Tests grün,
docs verify,instructions verify,lint --fail-on-error,und der CI-Smoke-Test (Export → frische Instanz →
doctor/verify/lint/migrate status)läuft durch;
doctormeldet dortenvironment: absent (optional).