Files

Tarik Moussa d7a0cf7457 docs: template-improvements — Pflichtlektüre, Rollen-Aktivierung, Out-of-Scope-Regel

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>

2026-06-03 23:57:21 +02:00

3.8 KiB

Raw Blame History

ROADMAP — Board & Ready-Set

Eingang des Feature-Loops und der Abhängigkeits-DAG: jedes Item kennt seine Prerequisites. Der Leader berechnet jeden Zyklus das Ready-Set und dispatcht nur daraus.

ROADMAP vs. STATE: ROADMAP = der ganze geplante Graph (Planungsebene). STATE.md = was gerade jetzt läuft (Live-Ebene: Now / In Progress / Blocked). Ein Item wandert: ROADMAP-🔲 → beim Dispatch in STATE.md „In Progress" → bei Merge zurück als ROADMAP-✅ in „Done".

Legende

Typ: 🔌 port (Referenz-Impl/golden oracle) · 🔬 research (nur Paper-Formeln) · 🧱 infra
Status: ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern (Lizenz/Mensch-Entscheid)

Ready-Set-Regel (so dispatcht der Leader)

Ready-Set = { Items mit Status 🔲, deren Prereqs ALLE ✅ sind }

Ready-Set bilden (Board unten lesen).
Ein Item ziehen; Modell + Rolle aus docs/roles/model-routing.md setzen.
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).
🔌/🧱 → direkt Worker. 🔬 → erst durch das Spike-Gate (docs/loops/spike-gate.md).
Worker dispatchen (kalt — kein Kontext aus Leader-Session weitergeben).
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)

F-01 (Skeleton) ──┬──► F-03 (Whitelist)      ──┐
                  ├──► F-04 (Bot-Handler)     ──┼──► F-06 (Integration) ──► F-07 (Deploy)
                  └──► F-05 (Model-Connector) ──┘

Nach F-01 ✅ werden F-03, F-04 und F-05 gleichzeitig frei — alle drei können parallel dispatcht werden. F-06 bleibt ⏸ bis F-03 + F-04 + F-05 alle ✅ sind.

Board

ID	Item	Typ	Status	Prereqs	Rolle · Modell	Aufwand
F-01	Projekt-Skeleton (pyproject.toml, Paketstruktur, CI-Stub)	🧱	✅	—	Worker · Sonnet	~0.5 d
F-03	Whitelist-Middleware (User-ID-Allowlist, Env-Var-Config)	🧱	✅	F-01	Worker · Sonnet	~0.5 d
F-04	Telegram-Bot-Handler (Polling-Loop, /start, /help, Nachricht-Relay)	🔌	✅	F-01	Porter · Sonnet	~1 d
F-05	Modell-HTTP-Connector (httpx-Client gegen konfigurierbaren OpenAI-compat Endpoint)	🔌	✅	F-01	Porter · Sonnet	~0.5 d
F-06	Integration & Smoke-Test (Whitelist + Handler + Connector verdrahtet, E2E-Test)	🧱	✅	F-03, F-04, F-05	Worker · Sonnet	~1 d
F-07	Deployment-Config (.env.example, Docker oder systemd-Unit)	🧱	✅	F-06	Worker · Haiku	~0.5 d

F-04 ist 🔌: Referenz-Impl = python-telegram-bot-v21-Dokumentation (golden oracle vorhanden). F-05 ist 🔌: Referenz-Impl = OpenAI Chat Completions API (de-facto-Standard für selbst gehostete Modelle; Endpoint-URL ist reine Config, kein Forschungsproblem). ADR-0004 begründet, warum kein Spike nötig ist.

Done

ID	Item	Session	Commit
F-01	Projekt-Skeleton	F-01 (2026-06-03)	`82eb6a6`
F-03	Whitelist-Middleware	F-03/04/05 (2026-06-03)	`de34c34`
F-04	Telegram-Bot-Handler	F-03/04/05 (2026-06-03)	`de34c34`
F-05	Modell-HTTP-Connector	F-03/04/05 (2026-06-03)	`de34c34`
F-06	Integration & Smoke-Test	F-06 (2026-06-03)	`b2395e1`
F-07	Deployment-Config	F-07 (2026-06-03)	`cb3b5c6`

3.8 KiB Raw Blame History