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: POST {CITADEL_URL}/api/mcp mit dem Header Authorization: Bearer. Stateless-JSON-Modus — jeder MCP-konforme Client funktioniert (z. B. Antigravity, Claude Code).
• stdio: mcp/stdio.ts mit den Envs CITADEL_URL + einem Credential ausführen. Gut für lokale Agenten, die pro Session einen Subprozess starten. Das Credential ist entweder CITADEL_TOKEN (ein Provisioning-Key — der Agent prägt via citadel_acquire_license eine kurzlebige Session-License; ein dauerhaftes Geheimnis bedient viele Agenten) oder CITADEL_LICENSE (ein statischer Agent-Key, klassischer Einzel-Agent-Modus).

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).

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.
• 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.