From d7a0cf7457a149bc58357c063d3f552fcdfb3127 Mon Sep 17 00:00:00 2001
From: Tarik Moussa <tarik.moussa95@gmail.com>
Date: Wed, 3 Jun 2026 23:57:21 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20template-improvements=20=E2=80=94=20Pfl?=
 =?UTF-8?q?ichtlekt=C3=BCre,=20Rollen-Aktivierung,=20Out-of-Scope-Regel?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Basierend auf Retro der F-06/07-Sessions:
- Pflichtlektüre-Block (AGENTS.md, CONVENTIONS.md, STATE.md) im Template
- Rollen-Aktivierungssatz + Link zur Rollendatei
- Out-of-Scope-Findings-Regel (trivial beheben vs. blockieren)
- "Tests zuerst, dann committen" explizit
- "Nicht selbst mergen" — Review-Gate-Hinweis für Worker
- Swarm-Kontext-Sektion für automatisierten Dispatch
- ROADMAP: Session-Prompt muss VOR Worker-Dispatch existieren (Invariante)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 ROADMAP.md                  | 12 +++++++++---
 session-prompts/TEMPLATE.md | 17 +++++++++++++++++
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 073ab6f..3389ac2 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -18,10 +18,16 @@ nur daraus.
 Ready-Set = { Items mit Status 🔲, deren Prereqs ALLE ✅ sind }
 ```
 1. Ready-Set bilden (Board unten lesen).
-2. Ein Item ziehen; Modell aus `docs/roles/model-routing.md` setzen.
-3. Session-Prompt aus `session-prompts/` ausfüllen (Template: `session-prompts/TEMPLATE.md`).
+2. Ein Item ziehen; Modell + Rolle aus `docs/roles/model-routing.md` setzen.
+3. Session-Prompt **vollständig ausfüllen und committen** — BEVOR der Worker-Agent startet.
+   Template: `session-prompts/TEMPLATE.md` (Pflichtfelder: Rolle, Pflichtlektüre, Out-of-Scope-Regel).
 4. **🔌/🧱** → direkt Worker. **🔬** → erst durch das Spike-Gate (`docs/loops/spike-gate.md`).
-5. Nach Implement: Review-Gate (Opus) → Merge → Item hier auf ✅, Dependents werden frei.
+5. Worker dispatchen (kalt — kein Kontext aus Leader-Session weitergeben).
+6. Nach Implement: Review-Gate (Opus, kalt) → Merge → Item hier auf ✅, Dependents werden frei.
+
+> **Invariante:** Session-Prompt existiert immer vor dem Worker-Dispatch.
+> Ein Worker der keinen vorbereiteten Prompt vorfindet, soll NICHT beginnen
+> sondern `STATE.md` auf "Blocked — kein Prompt" setzen.
 
 ## Abhängigkeits-DAG (Projekt: tg-bot-jetson)
 
diff --git a/session-prompts/TEMPLATE.md b/session-prompts/TEMPLATE.md
index a7aaabe..871b2aa 100644
--- a/session-prompts/TEMPLATE.md
+++ b/session-prompts/TEMPLATE.md
@@ -7,10 +7,16 @@ Jeder Prompt ist **kaltstartfähig** — die neue Session braucht kein Vorwissen
 
 ```
 Modell: _Haiku | Sonnet | Opus_
+Rolle: _Worker | Porter | Theorist | Reviewer_  → lies `docs/roles/<rolle>.md` vor dem Start.
 
 Du arbeitest in _<absoluter Pfad zum Repo>_ auf einem neuen Branch
 `_feat|fix|docs|audit/<name>_` (von `main`).
 
+## Pflichtlektüre (Kaltstart — in dieser Reihenfolge)
+1. `AGENTS.md` — Swarm-Rollen und Prozess
+2. `CONVENTIONS.md` — Code- und Commit-Standards
+3. `STATE.md` — aktueller Live-Stand (was läuft, was blockiert)
+
 ## Aufgabe
 _Kurze Beschreibung (1–3 Sätze) was implementiert, geprüft oder dokumentiert
 werden soll. Scope klar abgrenzen — was liegt AUSSERHALB dieser Session?_
@@ -27,10 +33,21 @@ Betroffene Dateien: `_<Pfad(e)>_`
 ## Nicht anfassen
 _Dateien / Pakete ausserhalb des Scopes. Kein Cross-Editing._
 
+## Out-of-Scope-Findings
+Fehler ausserhalb des Scopes: im Session-Log dokumentieren.
+Beheben nur wenn trivial (< 10 Zeilen, kein Design-Entscheid).
+Sonst: als Blocking-Issue in `STATE.md` eintragen und nicht mergen.
+
 ## Commit & Push
+- Tests ZUERST grün: `_<Test-Befehl>_` — erst dann committen.
 - Conventional Commit: `_feat|fix|docs|test|chore_: …`
 - Trailer: `Co-Authored-By: Claude _<Modell>_ <noreply@anthropic.com>`
 - Push nach `origin`, PR öffnen (Base: `main`).
+- NICHT selbst mergen — Review-Gate (Opus, kalt) folgt nach diesem Prompt.
+
+## Swarm-Kontext (bei automatisiertem Dispatch ausfüllen, sonst weglassen)
+- Leader-Session/Kanal: _<Session-ID, RemoteTrigger-ID oder n/a>_
+- Fertigmeldung: `STATE.md` aktualisieren + Hygiene-Gate-Output sichtbar machen.
 
 ## Abschluss
 1. Manifest-Eintrag updaten (`manifests/requirements.md` → Status `done`).