MCP-Tools

Der citadel-MCP-Server bietet 33 citadel_*-Tools — ein dünner Wrapper über die REST-API (die Quelle der Wahrheit), authentifiziert mit der License des Agenten. Beide Transports (streamable-HTTP POST /api/mcp und stdio) bieten dieselben Tools.

Konventionen unten:

• Sektoren: FRONTEND · BACKEND · QA · INFRA · SECURITY · DESIGN.
• Scope-Badges markieren Tools, die einen Fähigkeits-Scope auf der License brauchen: plan (Planner) oder recon (Scout/Interrogator). Alles andere funktioniert mit jeder gültigen License (im Rahmen des Sektor-Scopes).
• Jedes Tool nennt den REST-Endpoint, den es aufruft — Statuscodes und Payloads siehe REST-Referenz.

Session & Ausrüstung

citadel_acquire_license

Session starten: eine kurzlebige, sektor-gebundene Session-License holen (der Acquire-Handshake) und den Agent-Kontext bekommen (Alias, Sektoren, Scopes, Projekt). Mit konfiguriertem Provisioning-Key wird eine frische Session-License geprägt; mit einer statischen License ist es nur ein Check-in. Einmal vor allen anderen Tools aufrufen.

Parameter	Typ	Beschreibung
sectors	Sector[] · optional	Diesen Agenten auf diese Sektoren beschränken (Default: die Obergrenze des Keys).
scopes	("plan"|"recon")[] · optional	Fähigkeits-Scopes anfordern.
alias	string · optional	Anzeigename des Agenten im HQ.
ttlMinutes	int > 0 · optional	Lebensdauer der Session-License.

→ POST /api/v1/agent/acquire (Provisioning-Key) oder POST /api/v1/agent/check-in (statische License).

citadel_get_briefing

Das geschichtete Projekt-Briefing holen (Vision, aktive Operation, Q-Ausrüstungs-Zusammenfassungen, Archiv-Zusammenfassungen).

Parameter	Typ	Beschreibung
operation	string · optional	Operation-Key zur Eingrenzung (z. B. OP-1).

→ GET /api/v1/projects/:id/briefing

citadel_get_quality_gates

Die aktiven Quality Gates des Projekts auflisten. Keine Parameter. → GET /api/v1/projects/:id/quality-gates

citadel_get_harness

Die Harness-Definitionen auflisten (Build- / Test- / Lint-Kommandos). Keine Parameter. → GET /api/v1/projects/:id/harness

citadel_get_design_guidelines

Die Design Guideline + Theme-Registry für das aktive (oder benannte) Theme holen.

Parameter	Typ	Beschreibung
theme	string · optional	Theme-Key (Default: active).

→ GET /api/v1/projects/:id/design-guidelines?theme=active

Orders & Mission-Lesezugriffe

citadel_check_orders

Auf unverbrauchte Control Orders prüfen (pause / stand_down / redirect). standDown: true heißt stopp. Keine Parameter. → GET /api/v1/agent/orders

citadel_claim_next_mission

Atomar die nächste ready-Mission in deinem/n Sektor(en) claimen. Keine Parameter. → POST /api/v1/agent/claim-next

citadel_get_mission

Eine Mission per id holen.

Parameter	Typ	Beschreibung
missionId	string	Mission-id.

→ GET /api/v1/missions/:id

citadel_list_missions

Alle Missions des Projekts auflisten. Keine Parameter. → GET /api/v1/projects/:id/missions

Planung · plan scope

citadel_plan_operation plan

Eine Operation (Sprint) planen. Angelegt als planned, oder active bei activate: true.

Parameter	Typ	Beschreibung
codename	string · Pflicht	Operation-Codename.
objective	string · optional	Was die Operation liefert.
sectorsInScope	Sector[] · optional	Sektoren, die die Operation berührt.
capacityPoints	int > 0 | null · optional	Kapazität für den Sprint.
successCriteria	string[] · optional	Definition of Done der Operation.
activate	boolean · optional	Sofort aktivieren.

→ POST /api/v1/agent/operations

citadel_create_mission plan

Eine Mission im Backlog anlegen (oder ready). Per Key an eine Operation/Parent hängen (OP-1 / WEB-42).

Hier wird die Ausführungsreihenfolge festgelegt. dependsOn sorgt dafür, dass Arbeit in der richtigen Reihenfolge passiert — siehe Die Reihenfolge festlegen unten.

Parameter	Typ	Beschreibung
title	string · Pflicht	Mission-Titel.
sector	Sector · Pflicht	Eigentümer-Sektor.
type	design|feature|test|bugfix|spike|chore|research · optional	Mission-Typ.
objective	string · optional	Das Ziel.
briefing	string · optional	Voller Briefing-Text.
priority	low|medium|high|urgent · optional	Priorität.
estimatePoints	int > 0 | null · optional	Schätzung.
acceptanceCriteria	string[] · optional	Akzeptanz-Checkliste.
requiredSkills	string[] · optional	Benötigte Skills.
operationKey	string · optional	An diese Operation hängen (OP-1).
parentKey	string · optional	Parent-Mission-Key.
status	backlog|ready · optional	ready = sofort claimbar.
dependsOn	string[] · optional	Mission-Keys, die vorher erledigt sein müssen.
orderIndex	int ≥ 0 · optional	Position unter Geschwistern ohne harte Abhängigkeit.

→ POST /api/v1/agent/missions

Die Reihenfolge festlegen

claim-next gibt die nächste ready-Mission nach Priorität → orderIndex → Erstellungszeit aus und überspringt jede Mission, deren blocked_by-Abhängigkeiten noch offen sind. Also:

• Wenn B erst nach A starten kann: citadel_create_mission({ title: "B", dependsOn: ["WEB-41"] }). B wird nie an einen Agenten ausgegeben, solange A offen ist, und wird von selbst claimbar, sobald A erledigt oder abgebrochen ist — ohne menschlichen Schritt.
• Sind zwei Missionen wirklich unabhängig, sollen aber grob in einer Reihenfolge laufen, gib ihnen unterschiedliche orderIndex-Werte.
• relates_to ordnet nichts. Es ist Dokumentation. Ein Plan, dessen Abhängigkeiten mit relates_to ausgedrückt sind, wird im Wesentlichen in Erstellungsreihenfolge abgearbeitet.

Ein vertippter Key in dependsOn lässt den ganzen Aufruf mit 404 scheitern — die Mission wird nicht angelegt und kann so nie ohne die gewünschte Reihenfolge claimbar werden.

citadel_update_mission plan

Eine bestehende Mission pflegen (Titel / Ziel / Priorität / Schätzung / Sektor / Operation per Key …). Nicht den Status — Statuswechsel laufen über die Lifecycle-Tools und Gates.

Parameter	Typ	Beschreibung
mission	string · Pflicht	Mission-id oder -Key (WEB-42).
title, objective, briefing	string · optional	Textfelder.
type	Mission-Typ · optional	Typ ändern.
sector	Sector · optional	Sektor umhängen.
priority	Priorität · optional	Priorität ändern.
estimatePoints	int > 0 | null · optional	Schätzung.
acceptanceCriteria, requiredSkills	string[] · optional	Listen.
orderIndex	int · optional	Backlog-Reihenfolge.
operationKey	string | null · optional	Zu einer Operation verschieben / lösen.

→ PATCH /api/v1/agent/missions/:id

citadel_link_missions plan

Zwei Missions per Key mit einer typisierten, bidirektionalen Referenz verknüpfen.

Parameter	Typ	Beschreibung
sourceKey	string · Pflicht	Quell-Mission-Key.
targetKey	string · Pflicht	Ziel-Mission-Key.
linkType	enum · Pflicht	spawned_from · spawns · tests · tested_by · fixes · fixed_by · blocks · blocked_by · relates_to · duplicates · part_of · follow_up_of

→ POST /api/v1/agent/links

citadel_propose_quality_gate plan

Ein aus den Anforderungen abgeleitetes Quality Gate vorschlagen. Es landet pending und erzwingt nichts, bis ein Manager es im HQ aktiviert (M's Desk / Q-Branch).

Parameter	Typ	Beschreibung
key	string · Pflicht	Lowercase-dashed id, projekt-eindeutig (z. B. review-gate).
name	string · Pflicht	Menschlicher Name.
appliesToStatus	Mission-Status · Pflicht	Welchen Board-Status das Gate bewacht.
rule	Objekt · optional	requireArtifacts · requireColdRead · requireAcceptanceChecked · requireHarnessPass (alle boolean).
blocking	boolean · optional	Ob es hart blockt.

→ POST /api/v1/agent/quality-gates

citadel_propose_harness plan

Eine Harness-Definition vorschlagen — die im Repo gefundenen Build-/Test-/Lint-/Run-Kommandos. Sie landet pending und wird nicht genutzt, bis ein Manager sie im HQ aktiviert (Q-Branch). Vorher citadel_get_harness lesen: Keys sind projekt-eindeutig (409, wenn vergeben).

Parameter	Typ	Beschreibung
key	string · Pflicht	Lowercase-dashed id, projekt-eindeutig (z. B. default).
name	string · Pflicht	Menschlicher Name.
commands	Objekt · optional	build · test · lint · run — Shell-Kommandos ab Repo-Wurzel.
env	Objekt · optional	Nicht-geheime Env, die die Kommandos brauchen.
notes	string · optional	Vorbehalte (z. B. was geprüft wurde, was test benötigt).

→ POST /api/v1/agent/harness

citadel_propose_design_guideline plan

Eine Design-Richtlinie für ein Theme vorschlagen — das Design-System, dem Agenten folgen müssen. Sie landet pending und wird Agenten nicht ausgeliefert, bis ein Manager sie im HQ aktiviert (Q-Branch). Eine pro (Projekt, Theme) — 409, wenn das Theme schon eine hat.

Parameter	Typ	Beschreibung
themeKey	string · Pflicht	Das Theme, für das sie gilt (z. B. defcon-5).
title	string · Pflicht	Menschlicher Titel.
bodyMarkdown	string · optional	Die Richtlinie selbst — Regeln, denen ein Agent wörtlich folgt.

→ POST /api/v1/agent/design-guidelines

Das Archiv & Cold Read

citadel_file_dossier

Ein Design-Dossier für eine Mission anlegen. Es wird an die Mission angehängt und lässt den Status, wo er ist — der Wechsel designing → cold_read feuert nur für eine Mission, die bereits designing war, und claim_next gibt dir ohnehin nur eine ready-Mission. Beende deinen Lauf also normal.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
title	string · Pflicht	Dossier-Titel.
sections	Record<string,string> · optional	Benannte Abschnitte (Problem, Plan, …).
affectedFiles	string[] · optional	Vom Plan berührte Dateien.

→ POST /api/v1/missions/:id/dossier

citadel_get_dossier

Das Design-Dossier einer Mission per Key lesen — Problem, technischer Plan, betroffene Dateien, Abnahmekriterien, Cold-Read-Urteil. Nutze es, bevor du gegen ein von jemand anderem eingereichtes Design baust, statt es aus dem Briefing zu rekonstruieren. Das Dossier liegt meist auf einer anderen Mission als deiner (der Design-Mission oder der, von der du übergeben wurdest) — prüfe deine Links. Gibt null zurück, wenn diese Mission kein Dossier trägt.

Parameter	Typ	Beschreibung
missionKey	string · Pflicht	Mission-Key (z. B. WEB-42).

→ GET /api/v1/agent/dossier?missionKey=…

citadel_run_cold_read

Ein Cold-Read-Urteil als kontextloser Recruit abgeben (pass → ready, fail → designing). Nie das eigene Dossier cold-readen.

Parameter	Typ	Beschreibung
dossierId	string · Pflicht	Dossier-id.
verdict	pass|fail · Pflicht	Das Urteil.
comprehensionNotes	string · optional	Was du verstanden hast.
openQuestions	string[] · optional	Unklarheiten.

→ POST /api/v1/dossiers/:id/cold-read

Brownfield-Onboarding · Das Archiv

citadel_read_archive

Das volle Archiv lesen (alle zertifizierten KnowledgeDocs inkl. bodyMarkdown). Vor dem Planen eines Brownfield-Projekts nutzen, um zu sehen, was Scout/Interrogator abgelegt haben. Keine Parameter. → GET /api/v1/agent/knowledge

citadel_write_knowledge recon

Ein KnowledgeDoc ins Archiv schreiben (Scout-Repo-Recon / Interrogator-Debrief). Upsert pro Pfad; mit parentPath verschachteln. Schreibzugriffe landen quarantäniert — ein Fakt erreicht ein Briefing erst nach Zertifizierung durch einen fremden Akteur oder HQ.

Parameter	Typ	Beschreibung
path	string · Pflicht	Doc-Pfad / id (Upsert-Key), z. B. server/ oder INTEL/constraints.
summary	string · Pflicht	Einzeiler (erscheint in Briefings).
bodyMarkdown	string · optional	Voller Text.
level	int 0..10 · optional	Tiefe in der README-Hierarchie.
parentPath	string · optional	Pfad des Parent-Docs.

→ POST /api/v1/agent/knowledge

citadel_verify_knowledge

Fakten-Cold-Read: ein quarantäniertes KnowledgeDoc zertifizieren oder ablehnen, damit es ein Briefing erreichen kann (oder nie). Kontextlos-Regel — du darfst kein Doc verifizieren, das deine eigene License geschrieben hat.

Parameter	Typ	Beschreibung
docId	string · Pflicht	KnowledgeDoc-id.
verdict	certify|reject · Pflicht	Das Urteil.
notes	string · optional	Reviewer-Notizen.
reason	string · optional	Pflicht bei verdict = reject.

→ POST /api/v1/knowledge/:id/verify

citadel_delete_knowledge recon

Ein KnowledgeDoc per Pfad aus dem Archiv zurückziehen (ein veraltetes Recon-Doc oder ein INTEL/*-Eintrag, den der Operator entfernt haben will).

Parameter	Typ	Beschreibung
path	string · Pflicht	Doc-Pfad.

→ DELETE /api/v1/agent/knowledge?path=<p>

citadel_finish_recon recon

Das Ende eines Recon-Laufs signalisieren, nachdem KnowledgeDocs abgelegt wurden. Löst eine Archiv-aktualisiert-Benachrichtigung fürs HQ aus (statt einer Glocke pro Doc). Einmal am Ende aufrufen. Keine Parameter. → POST /api/v1/agent/knowledge/finish

Org-weiter Recall (von Nachbarprojekten lernen)

Jeder andere Lesezugriff ist auf dein eigenes Projekt beschränkt. Diese beiden lesen über alle Projekte deiner Organisation hinweg — damit ein Scout lernen kann, wie ein Nachbarprojekt etwas gelöst hat, und ein Planer darauf aufbauen kann, statt es neu zu entdecken.

Beide sind rein lesend und brauchen den plan- oder recon-Scope (Planer oder Scout); eine reine Ausführungs-License bleibt projekt-scoped. Die Organisation stammt aus deiner License, die Grenze lässt sich also nicht erweitern. Ungeprüftes Wissen und nicht-aktive Ausrüstung erscheinen nie, und jede Zeile nennt ihr Herkunftsprojekt.

Behandle Funde als Vorbilder, nicht als Regeln: Projekte unterscheiden sich und lösen Dinge berechtigterweise auf ihre eigene Art. Nichts wird automatisch übernommen — eine Konvention ins eigene Projekt zu holen ist ein eigener, bewusster Schritt (citadel_propose_harness / citadel_propose_quality_gate).

citadel_recall_knowledge plan | recon

Zertifiziertes Archiv-Wissen über alle Projekte der Organisation durchsuchen.

Parameter	Typ	Beschreibung
query	string · optional	Filtert case-insensitiv über Pfad, Summary oder Body-Text.

Liefert { docs: [{ projectKey, projectName, path, level, summary, bodyMarkdown }], truncated, count }. Auf 200 Docs gedeckelt — truncated: true heißt, es gibt mehr. → GET /api/v1/agent/org/knowledge

citadel_recall_equipment plan | recon

Die aktiven Harness-Definitionen, Quality Gates und Design-Guidelines über alle Projekte der Organisation auflisten — die Build-/Test-Konventionen, die Definition of Done und die Design-Regeln, die anderswo bereits funktionieren. Lies sie, bevor du eigene schreibst; das Übernehmen ist ein eigener Schritt. Keine Parameter.

Liefert { harness, qualityGates, designGuidelines }, jeder Eintrag mit projectKey + projectName. → GET /api/v1/agent/org/equipment

Hand-off & Zusammenarbeit

citadel_hand_off_mission

Eine neue Mission in einem anderen Sektor mit geteiltem Kontext + einer typisierten Referenz übergeben. Die neue Mission erbt Dossier + Artefakte + eine Rück-Referenz.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Quell-Mission.
sector	Sector · Pflicht	Ziel-Sektor.
type	Mission-Typ · Pflicht	Typ der neuen Mission.
title	string · Pflicht	Titel der neuen Mission.
objective, briefing	string · optional	Kontext fürs Ziel.
linkType	tests|fixes|blocks|relates_to|follow_up_of|duplicates · optional	Referenz-Typ.
note	string · optional	Hand-off-Notiz.

→ POST /api/v1/agent/missions/:id/hand-off

citadel_attach_artifact

Ein Artefakt anhängen. Ein test_report erfüllt das Harness-Gate.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
kind	pr|commit|file|url|test_report · Pflicht	Artefakt-Art.
url	string · Pflicht	Artefakt-URL.
label	string · Pflicht	Anzeige-Label.

→ POST /api/v1/agent/missions/:id/artifacts

citadel_add_comment

Einen Kommentar / Work-Log-Eintrag zu einer Mission hinzufügen.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
body	string · Pflicht	Kommentartext.

→ POST /api/v1/agent/missions/:id/comments

Lifecycle

citadel_report_blocker

Einen Blocker auf einer geclaimten Mission melden (→ blocked). Nur für Hindernisse, die Citadel nicht selbst sehen kann. Wartest du auf eine andere Mission, verlinke sie (blocked_by) und beende einfach deinen Lauf: claim_next gibt nie eine Mission mit offenem Blocker aus, und sie kehrt von selbst in die Warteschlange zurück, sobald der letzte Blocker erledigt ist. Siehe Abhängigkeiten, die sich selbst lösen.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
reason	string · Pflicht	Warum blockiert.

→ POST /api/v1/agent/missions/:id/block

citadel_resolve_blocker

Einen Blocker auf einer blockierten Mission auflösen (→ ready) und sie zurück in die Warteschlange geben — claime sie erneut mit claim_next. Die Mission muss blocked und in einem deiner Sektoren sein. Für Hindernisse außerhalb Citadels, die verschwunden sind; blocked_by-Abhängigkeiten lösen sich selbst.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
note	string · Pflicht	Wie der Blocker beseitigt wurde.

→ POST /api/v1/agent/missions/:id/resolve-blocker

citadel_request_human_input

HQ um eine Entscheidung bitten und die Mission dauerhaft aussetzen (→ waiting_human). Für echte Mehrdeutigkeit, die ein Mensch klären muss — nicht für Hindernisse (dafür citadel_report_blocker). Die Lease-Uhr stoppt; HQ antwortet; die Mission geht zurück ins Backlog und ein frischer Agent macht mit der Antwort im Dossier weiter. Beende deinen Lauf nach diesem Aufruf.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
question	string · Pflicht	Die benötigte Entscheidung.
context	string · optional	Hintergrund fürs HQ.
urgency	low|medium|high · optional	Wie dringend.
format	free_text|yes_no|multiple_choice · optional	Erwartete Antwortform.
choices	string[] · optional	Optionen für multiple_choice.

→ POST /api/v1/agent/missions/:id/request-human-input

citadel_submit_for_review

Eine geclaimte Mission zum Review einreichen (→ in_review, nicht-blockierend).

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.

→ POST /api/v1/agent/missions/:id/submit

citadel_heartbeat

Die Lease einer geclaimten Mission verlängern (bei langer Arbeit aufrufen, damit der Watchdog sie nicht neu einreiht).

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.

→ POST /api/v1/agent/missions/:id/heartbeat

citadel_complete_mission

Eine geclaimte Mission abschließen (erzwingt Quality Gates; → done). Vorher benötigte Artefakte anhängen.

Parameter	Typ	Beschreibung
missionId	string · Pflicht	Mission-id.
result	success|failed · optional	Ergebnis-Flag.
outcome	string · optional	Freitext-Ergebniszusammenfassung.

→ POST /api/v1/agent/missions/:id/complete

Abhängigkeiten, die sich selbst lösen

Verlinke eine Mission mit einer anderen über citadel_link_missions (linkType: "blocked_by"), und Citadel plant darum herum — kein citadel_report_blocker, kein Mensch im HQ:

• claim_next überspringt sie. Eine ready-Mission, deren blocked_by-Ziel nicht done oder cancelled ist, wird nie ausgegeben — ein Agent bekommt also nie Arbeit, die er nicht tun kann.
• Sie löst sich selbst. Sobald der letzte Blocker erledigt ist — abgeschlossen oder abgebrochen (er kommt nicht mehr) —, kehrt eine in blocked wartende Mission von selbst nach ready zurück, ihr Claim wird freigegeben. The Wire protokolliert einen system-Eintrag unblocked.

Behalte citadel_report_blocker für Hindernisse, die Citadel nicht sehen kann — eine API ist down, ein Zugang fehlt — und citadel_resolve_blocker, um diese aufzulösen, sobald sie wegfallen.