Integrations-Anleitung

Citadel Ops ist agent-agnostisch. Der Server (REST-API + MCP) ist die Quelle der Wahrheit und hält die gesamte Intelligenz — die State-Machine, Quality Gates, den Cold Read, Leases, den Kill-Switch, das hash-verkettete Audit. Ein Field-Agent ist nur etwas, das die Tools aufruft. Ob dieser Agent Claude Code, Google Antigravity, ein Hermes-Modell in deiner eigenen Harness oder ein Shell-Skript ist, ist Citadel egal: Es prüft nur die License und validiert jeden Call.

Drei Ebenen

Ebene	Was	Runtime-Kopplung
Protokoll	REST /api/v1/agent/** und MCP (/api/mcp + stdio)	keine — offene Standards
Schleife	die Mission-Schleife (was in welcher Reihenfolge)	keine — dieses Dokument
Treiber	wie eine konkrete Runtime die Schleife ausführt	runtime-spezifischer Adapter

Spricht dein Agent MCP, richte ihn auf den Citadel-MCP-Server und gib ihm die Mission-Schleife als Anweisung — das ist die ganze Integration. Wenn nicht, fahre dieselbe Schleife über pures REST.

Authentifizierung — die License

Jeder Agent-Call trägt eine License als Bearer-Token:

Authorization: Bearer lic_xxxxxxxx

• Eine License ist auf eine Org/Projekt und auf einen oder mehrere Sektoren beschränkt (FRONTEND, BACKEND, QA, INFRA, SECURITY, DESIGN). Du kannst nur Missions in deinen Sektoren claimen.
• Eine License kann außerdem Fähigkeits-Scopes tragen:
  • plan — die Planner-Fähigkeit: Operations & Missions anlegen und pflegen.
  • recon — die Scout/Interrogator-Fähigkeit: ins Archiv schreiben beim Onboarding eines Brownfield-Projekts.
  • Eine License ohne den Scope bekommt an den entsprechenden Endpoints 403.
• HQ kann eine License jederzeit widerrufen (Kill-Switch). Nach dem Widerruf liefert jeder Schreibzugriff 401 license_revoked → der Agent muss sofort stoppen (stand down).
• Licenses sind kurzlebig und rotierbar. Behandle das Token als Geheimnis; schreibe es nie in ein Dossier, einen Kommentar, ein Artefakt oder ein Log.

Es gibt kein weiteres Credential. Dasselbe Token funktioniert für beide Transports.

Die zwei Transports

Nimm einen — sie sind gleichwertig und bieten dieselbe Schleife.

MCP — der citadel-Server

Zwei Distributionen, beide License-authentifiziert, mit denselben citadel_*-Tools (komplette Liste →):

• Streamable-HTTP (empfohlen): POST {CITADEL_URL}/api/mcp mit dem Header Authorization: Bearer. Stateful-JSON-Modus — die Session bleibt pro Verbindung erhalten (über Mcp-Session-Id), sodass ein Provisioning-Key den Acquire-Handshake über HTTP genauso fährt wie stdio. Jeder MCP-konforme Client funktioniert (z. B. Antigravity, Claude Code); kein Repo, kein Client zum Herunterladen.
• stdio: den Client ausführen, den HQ unter GET /api/v1/agent/stdio ausliefert — eine self-contained Datei, kein Checkout dieses Repos. /citadel-init lädt ihn nach .citadel/stdio.mjs und zeigt .mcp.json auf node .citadel/stdio.mjs. Nimm es, wenn eine Runtime nur stdio spricht.

Zwei Credential-Modelle, und beide Transports nehmen beide. Wähle nach der Zahl der Agenten:

• Simple — ein Agent. Eine Standing-License in CITADEL_LICENSE. Der Key ist das Credential des Agenten: kein acquire-Aufruf, sonst nichts zu verdrahten. Fang hier an.
• Flotte — viele Agenten aus einem Key (ab dem zweiten Agenten empfohlen). Ein Provisioning-Key in CITADEL_TOKEN. Er kann selbst nicht arbeiten; jede Session ruft citadel_acquire_license und wählt ihren eigenen Sektor — so fährt ein dauerhaftes Geheimnis die ganze Flotte: jeder Agent kurzlebig, eigene Zeile im Roster, eigener Kill-Switch, begrenzt durch die Obergrenze des Keys.

In Claude Code verdrahtet dir der /citadel-init-Skill das (schreibt/merged .mcp.json mit ${CITADEL_TOKEN}-Env-Expansion, gitignored den Secret-Halter und prüft die Verbindung).

An die Skills kommen — ohne Repo

Die /citadel-*-Skills kommen mit dem Deploy, nicht mit dem Quellcode — wer also ein HQ-Login hat, aber keinen Zugriff auf dieses (private) Repo, bekommt sie trotzdem. Unter M Desk → Skills installieren lädt ein Button alle als ZIP; entpackt nach .claude/skills (nur dieses Projekt) oder ~/.claude/skills (alle Projekte) ist die Installation fertig. citadel-init ist selbst mit drin, also gibt es kein Henne-Ei-Problem: URL + Key + ein Download, und der Skill, der alles Weitere verdrahtet, liegt auf der Platte. Endpoints und die Skript-Variante für Rechner ohne Browser stehen in der REST-Referenz.

REST — /api/v1/agent/**

Dieselbe Schleife ohne MCP. Alle Calls brauchen den Header Authorization: Bearer. Die komplette Oberfläche steht in der REST-Referenz; die Kern-Endpoints der Schleife sind:

Schritt	Methode + Pfad
Session-License holen (Provisioning)	POST /api/v1/agent/acquire
Check-in (Identität + Sektoren + Projekt)	POST /api/v1/agent/check-in
Control Orders lesen	GET /api/v1/agent/orders
Nächste Mission claimen (atomar)	POST /api/v1/agent/claim-next
Artefakt anhängen	POST /api/v1/agent/missions/:id/artifacts
Kommentar / Work-Log	POST /api/v1/agent/missions/:id/comments
Heartbeat (Lease verlängern)	POST /api/v1/agent/missions/:id/heartbeat
An anderen Sektor übergeben	POST /api/v1/agent/missions/:id/hand-off
Zum Review einreichen (nicht-blockierend)	POST /api/v1/agent/missions/:id/submit
Abschließen (Quality Gates erzwungen)	POST /api/v1/agent/missions/:id/complete
Blocker melden	POST /api/v1/agent/missions/:id/block

Die Mission-Schleife

Frischer Kontext pro Mission — vergiss die vorige Mission und hole nur, was diese braucht. Das ist Pflicht: Es hält Agenten günstig und verhindert Context-Rot.

1. acquire / check-in    → Alias + Sektoren + aktives Projekt notieren
2. Briefing + Q lesen     → Briefing einmal; quality-gates, harness, design-guidelines (in-style bauen)
3. Orders lesen           → bei standDown: STOPP
4. claim-next            → keine: Backlog leer, Ende
5. Mission nach Typ bearbeiten:
     design   → Dossier anlegen (Problem, Plan, betroffene Dateien, Akzeptanz) → cold_read;
                ein ANDERER Agent macht den Cold Read (nie das eigene Dossier)
     feature/bugfix/chore → auf Branch mission/<KEY> umsetzen; Harness laufen lassen;
                ein test_report (und einen pr) als Artefakt anhängen
     test     → Tests laufen lassen; bei Fehler einen Bugfix (linkType "fixes") an den Eigentümer-Sektor übergeben
     research/spike → Ergebnisse via Kommentar oder Dossier festhalten
     anderer Sektor nötig? → hand-off (die neue Mission erbt Dossier + Artefakte + eine Rück-Referenz)
6. heartbeat bei langer Arbeit, damit die Lease nicht abläuft
7. Abschluss → submit-for-review (nicht-blockierend) oder complete (Gates erzwungen — vorher Artefakte anhängen)
8. Kontext für diese Mission leeren → weiter bei 3

Harte Regeln (der Server erzwingt sie)

• Sektor-Scope. Claiming liefert nur Missions in deinen Sektoren. Alles andere ist ein Hand-off.
• Frischer Kontext pro Mission. Briefing/Dossier jedes Mal neu lesen; keinen alten Zustand mitschleppen.
• Kill-Switch. Jedes 401 license_revoked → sofort stoppen.
• Gates. complete scheitert, wenn die Quality Gates nicht bestehen (z. B. ein test_report-Artefakt fürs Harness-Gate). Artefakte vor dem Abschluss anhängen.
• Idempotenz. Schreibzugriffe akzeptieren einen Idempotency-Key-Header für sichere Retries.
• Keine Secrets in Briefing, Dossier, Kommentar, Artefakt oder Log.

Planung & Brownfield-Onboarding

• Planner (plan-Scope) macht aus einem Ziel eine Operation + eine Menge verlinkter Missions, die Field-Agents dann claimen. Siehe citadel_plan_operation / citadel_create_mission / citadel_link_missions in der MCP-Referenz.
• Org-weiter Recall (plan- oder recon-Scope): citadel_recall_knowledge und citadel_recall_equipment lesen zertifiziertes Wissen und aktive Q-Branch-Ausrüstung über alle Projekte deiner Organisation hinweg. Ein Scout nutzt das beim Erkunden einer Codebase — zu sehen, wie ein Nachbarprojekt das Deployment oder das Test-Setup gelöst hat, ist genau der Punkt und schlägt Neuentdecken. Ein Planer baut darauf neue Arbeit auf. Rein lesend, jedes Ergebnis nennt sein Herkunftsprojekt, und nichts wird automatisch übernommen: Projekte unterscheiden sich, also behandle Funde als Vorbilder und schlage bewusst vor, was passt.
• Brownfield (recon-Scope): Bevor du eine bestehende Codebase planst, füllst du das Archiv. Scout liest das Repo und legt KnowledgeDocs an; Interrogator befragt den Operator nach INTEL/*; dann liest der Planner via citadel_read_archive alles tief und plant. Schreibzugriffe landen quarantäniert — ein Fakt erreicht ein Briefing erst, nachdem ein fremder Akteur oder HQ ihn zertifiziert (citadel_verify_knowledge).

In diesem Repo mitgelieferte Treiber

Treiber	Kommando	Runtime
Claude-Skill (/citadel-work)	in einer Claude-Code-Session	Claude Code, Schleife in der Session
Claude-CLI	citadel-agent --driver claude	frischer Claude-Code-Prozess pro Mission (Agent SDK)
Generic (BYO-Agent)	citadel-agent --driver generic --exec "<cmd>"	jede Runtime
Dry-Run	citadel-agent --dry-run	keine (stub-completes; testet die Schleife)

Der generische Treiber fährt die modell-agnostische Schleife und startet pro geclaimter Mission <cmd> in einem frischen Prozess mit dem Mission-Kontext, der License und dem MCP-Einstieg in der Umgebung (CITADEL_URL, CITADEL_LICENSE, CITADEL_MCP_STDIO, CITADEL_MISSION_*). Exit 0 = erledigt; ungleich null lässt den Treiber einen Blocker melden. Das ist die Integrations-Naht für Hermes, Antigravity oder alles andere — die Orchestrierung bleibt bei Citadel; das Gehirn ist deins.