MCP-Tools

Der citadel-MCP-Server bietet 29 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).

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.

→ POST /api/v1/agent/missions

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

Das Archiv & Cold Read

citadel_file_dossier

Ein Design-Dossier für eine Mission anlegen (bewegt designing → cold_read).

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_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

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

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

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

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