nixos-config/docs/intent/kanban-board-admin-trigger.md

Intent: Kanban-Board mit Pilot-Übergang zum Admin-Agenten

Ziel

Ein eigenständiges, ausschließlich auf blunix laufendes Kanban-Board, das den Intent-Lifecycle (Planner-Dokumente aus docs/intent/*.md) visualisiert und für einen einzelnen Phasenübergang aktiv steuerbar ist: Wird eine Intent-Karte von "Geplant" nach "In Umsetzung" verschoben, löst das Board direkt einen echten Auftrag an den Admin-Agenten aus (headless codex exec mit agents/admin.md als Rolle und dem Intent-Dokument als Auftragstext) — kein manuelles Abtippen im Chat mehr für diesen einen Übergang.

Umfang

• Neuer, eigenständiger Stack ausschließlich auf blunix (kein Bezug zum bestehenden dashboard-Repo/pinix, keine Änderung daran).
• Board zeigt Spalten entlang des bestehenden Rollen-Workflows: Idee/Backlog → Geplant (Intent fertig) → In Umsetzung → Review → Deployed.
• Aktiv steuerbar ist nur der eine Pilot-Übergang Geplant → In Umsetzung. Alle anderen Spaltenwechsel sind zunächst reine Anzeige/manuelle Einordnung ohne Automatisierung.
• Zugriff Tailnet-only über blunix' internen Traefik-Entrypoint, kein öffentlicher Zugriff.
• Der Agenten-Aufruf läuft headless (codex exec, kein interaktives Herdr-Pane) und nutzt das bestehende Abo-Login (CODEX_HOME aus vorhandenem auth.json, kein ANTHROPIC_API_KEY/roher API-Key) — Kosten sollen aus dem Abo-Kontingent laufen, nicht als separates Pay-per-Token abgerechnet werden.
• Lauf-Ausgabe muss nachvollziehbar sein: mindestens über journalctl des auslösenden Dienstes, optional zusätzlich als kurze Statusmeldung im bestehenden XMPP-Raum update@muc.0ff.space.

Unverbindlicher technischer Anhaltspunkt (keine Vorwegnahme der Umsetzung)

Diskutierter Mechanismus, als Orientierung für die Umsetzung, nicht als bindende Vorgabe — folgt bewusst dem bereits produktiv laufenden Muster von hosts/blunix/localServices/agent-codex/:

1. Board-Frontend sendet bei Drag "Geplant → In Umsetzung" einen HTTP-Request an einen kleinen Trigger-Endpunkt auf blunix.
2. Der Endpunkt prüft den aktuellen Phasen-Status (verhindert Doppel-Trigger), setzt ihn auf "In Umsetzung" und legt eine Job-Datei in einem Queue-Verzeichnis ab (z. B. /var/lib/board-agent/inbox/<slug>-<zeitstempel>.json), analog zu AGENT_QUEUE_DIR/inbox/*.json bei agent-codex.
3. Ein systemd.paths-Unit beobachtet dieses Verzeichnis und startet bei neuer Datei einen Oneshot-Service (analog agent-codex-worker.path/.service).
4. Der Oneshot-Service kopiert/nutzt das bestehende Abo-Login (prepareCodexHome-Muster) und ruft codex exec --sandbox workspace-write -C agents/ --add-dir /home/drone/nixos-config ... mit agents/admin.md als Rolle auf, Intent-Inhalt als Auftrag.
5. Job-Datei wandert nach Abschluss von inbox/ nach processing/ und done//failed/, wie bei agent-codex bereits etabliert.
6. Ausgabe landet in journalctl, optional zusätzlich als kurze Meldung an update@muc.0ff.space.
7. Die eigentliche Code-/Konfigurationsänderung wird nicht automatisch committet oder deployt — das bleibt an eine ausdrückliche, separate Freigabe gebunden, unverändert gegenüber der heutigen Admin-Rolle.

Explizit ausgeschlossen

• Kein Aufbau auf/Integration mit Vikunja (bewusst separat, nicht dessen Kanban-Ansicht/API genutzt).
• Keine Automatisierung der Übergänge In Umsetzung → Review → Deployed in diesem Vorhaben.
• Keine Änderung an agents/admin.md, agents/catalog.json oder Rollen-Settings-Dateien als Teil dieses Intents (falls die Umsetzung das doch braucht, ist das eine separate Entscheidung der Umsetzung, nicht hier vorweggenommen).
• Keine Änderung am bestehenden dashboard-Repo/pinix-Stack.
• Kein öffentlicher Zugriff auf das Board.
• Keine automatische Aktivierung/Deployment von Änderungen, die der Admin-Agent im Zuge des Pilot-Laufs vornimmt.
• Kein Einsatz eines rohen API-Keys (ANTHROPIC_API_KEY o. Ä.) für den Agenten-Aufruf.

Annahmen

• Herdr läuft aktiv auf der dauerhaften Admin-Session auf blunix (HERDR_ENV=1) — für diesen Piloten aber irrelevant, da der Agenten-Aufruf bewusst nicht über Herdr läuft (siehe Entscheidung unten), sondern headless direkt per codex exec.
• Zugriff Tailnet-only via blunix-Traefik-internal, analog zum bestehenden Muster interner Dienste.
• Der Backend-/Worker-Mechanismus liest docs/intent/*.md aus dem bestehenden nixos-config-Checkout auf blunix (kein separates Repo für Intent-Inhalte).
• Headless-Aufruf über bestehendes Abo-Login (wie bei agent-codex) zieht gegen das Abo-Nutzungskontingent, nicht als separates Pay-per-Token — Stand der Recherche zum Zeitpunkt dieses Dokuments; ein bekannter, nicht abschließend geklärter Bugreport (anthropics/claude-code#43333) beschreibt Fälle, in denen OAuth/Abo-Login trotzdem als API-Nutzung abgerechnet wurde.

Offene Risiken / zu klärende Punkte (für die Umsetzung, nicht hier entschieden)

• Vor Produktivschaltung: ein einzelner echter Testaufruf, um zu verifizieren, dass der headless-Aufruf tatsächlich gegen das Abo-Kontingent und nicht gegen echtes API-Guthaben läuft (wegen des oben genannten Bugreports) — gleiches Vorgehen wie beim früheren XMPP-Agent-Relay-Vorhaben.
• Wo der Phasen-Status pro Intent gespeichert wird (Frontmatter in der Intent-Datei vs. separate State-Datei/DB) — bewusst offengelassen.
• Wer im Board die Aktion auslösen darf (nur Owner vs. jede Person mit Tailnet-Zugriff) — Zugriffsschutz noch nicht spezifiziert.
• Das Vorgehen umgeht für den Piloten bewusst die in agents/admin.md beschriebene Regel, dass der Orchestrator die einzige Dialogschnittstelle zu Spezialisten ist — explizit benannte Abweichung, keine stille Umgehung. Ob/wie das dauerhaft mit der Rollen-Architektur vereinbart wird, ist nicht Teil dieses Intents.
• Exaktes Job-/Queue-Schema, Locking bei parallelen Triggern, Fehlerbehandlung bei einem abstürzenden/unterbrochenen Lauf (z. B. durch einen Deploy, der den Worker-Dienst neu lädt) — Sache der Umsetzung, analog zu den bereits gelösten Fällen in agent-codex.

Erfolgskriterien

• Eine fertige Intent-Karte lässt sich im Board von "Geplant" nach "In Umsetzung" ziehen.
• Dieses Verschieben löst nachweisbar einen tatsächlichen, headless laufenden Auftrag an den Admin-Agenten mit dem Intent-Inhalt als Prompt aus — verifizierbar über journalctl des Worker-Dienstes.
• Der Aufruf läuft nachweislich über das Abo-Kontingent, nicht über separates Pay-per-Token (verifiziert durch den Testaufruf aus den offenen Risiken oben).
• Board läuft ausschließlich Tailnet-erreichbar, kein öffentlicher Zugriff.
• Keine bestehende Funktionalität (Planner-Workflow per Chat, dashboard-Repo, Vikunja, agent-codex) wird durch dieses Vorhaben verändert oder beeinträchtigt.