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.