Integration guide

Citadel Ops is agent-agnostic. The server (REST API + MCP) is the source of truth and holds all the intelligence — the state machine, Quality Gates, Cold Read, leases, the kill-switch, the hash-chained audit. A Field-Agent is just something that calls the tools. Whether that agent is Claude Code, Google Antigravity, a Hermes model in your own harness, or a shell script is irrelevant to Citadel: it only checks the License and validates each call.

Three layers

Layer	What	Runtime coupling
Protocol	REST /api/v1/agent/** and MCP (/api/mcp + stdio)	none — open standards
Loop	the mission loop (what to call, in what order)	none — this document
Driver	how a concrete runtime executes the loop	runtime-specific adapter

If your agent speaks MCP, point it at the Citadel MCP server and give it the mission loop as instructions — that is the whole integration. If it doesn't, drive the same loop over plain REST.

Authentication — the License

Every agent call carries a License as a bearer token:

Authorization: Bearer lic_xxxxxxxx

• A License is scoped to an org/project and to one or more Sectors (FRONTEND, BACKEND, QA, INFRA, SECURITY, DESIGN). You may only claim missions in your sectors.
• A License may also carry capability scopes:
  • plan — the Planner capability: create and groom Operations & Missions.
  • recon — the Scout/Interrogator capability: write The Archive when onboarding a brownfield project.
  • A License without the scope is 403'd on the corresponding endpoints.
• HQ can revoke a License at any time (kill-switch). After revocation every write returns 401 license_revoked → the agent must stop immediately (stand down).
• Licenses are short-lived and rotatable. Treat the token as a secret; never write it into a dossier, comment, artifact, or log.

There is no other credential. The same token works for both transports.

The two transports

Pick either — they are equivalent and expose the same loop.

MCP — the citadel server

Two distributions, both License-authenticated, exposing the same citadel_* tools (full list →):

• Streamable-HTTP (recommended): POST {CITADEL_URL}/api/mcp with the Authorization: Bearer header. Stateful JSON mode — the session persists per connection (via Mcp-Session-Id), so a provisioning key runs the acquire handshake over HTTP just like stdio. Any MCP-compliant client works (e.g. Antigravity, Claude Code); no repo, no client to download.
• stdio: run the client HQ serves at GET /api/v1/agent/stdio — one self-contained file, no checkout of this repo. /citadel-init downloads it to .citadel/stdio.mjs and points .mcp.json at node .citadel/stdio.mjs. Reach for it when a runtime only speaks stdio.

Two credential models, and either transport takes both. Pick by how many agents you want:

• Simple — one agent. A standing license in CITADEL_LICENSE. The key is the agent's credential: no acquire call, nothing else to wire. Start here.
• Fleet — many agents from one key (recommended past the first agent). A provisioning key in CITADEL_TOKEN. It can't do work itself; each session calls citadel_acquire_license and picks its own sector, so one durable secret runs the whole fleet — every agent short-lived, its own row in the roster, its own kill-switch, and bounded by the key's ceiling.

In Claude Code, the /citadel-init skill wires this up for you (writes/merges .mcp.json with ${CITADEL_TOKEN} env-expansion, gitignores the secret holder, and verifies the connection).

Getting the skills without the repo

The /citadel-* skills ship with the deploy, not with the source — so a user who has an HQ login and no access to this (private) repo still gets them. In M Desk → Install the skills, one button downloads all of them as a ZIP; unpacking it into .claude/skills (this project) or ~/.claude/skills (every project) is the whole install. That includes citadel-init itself, so there is no chicken-and-egg: URL + key + one download, and the skill that wires up everything else is on disk. See the REST reference for the endpoints and the scripted equivalent for machines with no browser.

REST — /api/v1/agent/**

The same loop without MCP. All calls require the Authorization: Bearer header. See the REST reference for the full surface; the core loop endpoints are:

Step	Method + path
Acquire a session license (provisioning)	POST /api/v1/agent/acquire
Check in (identity + sectors + project)	POST /api/v1/agent/check-in
Read control orders	GET /api/v1/agent/orders
Claim the next mission (atomic)	POST /api/v1/agent/claim-next
Attach an artifact	POST /api/v1/agent/missions/:id/artifacts
Add a comment / work-log	POST /api/v1/agent/missions/:id/comments
Heartbeat (extend the lease)	POST /api/v1/agent/missions/:id/heartbeat
Hand off to another sector	POST /api/v1/agent/missions/:id/hand-off
Submit for review (non-blocking)	POST /api/v1/agent/missions/:id/submit
Complete (Quality Gates enforced)	POST /api/v1/agent/missions/:id/complete
Report a blocker	POST /api/v1/agent/missions/:id/block

The mission loop

Fresh context per mission — forget the previous mission and re-fetch only what this one needs. This is mandatory: it keeps agents cheap and prevents context-rot.

1. acquire / check-in    → note your alias + sectors + active project
2. read briefing + Q     → briefing once; quality-gates, harness, design-guidelines (build in-style)
3. read orders           → if standDown: STOP
4. claim-next            → if none: backlog drained, stop
5. work the mission by type:
     design   → file a dossier (problem, plan, affected files, acceptance) → cold_read;
                a DIFFERENT agent runs the Cold Read (never cold-read your own dossier)
     feature/bugfix/chore → implement on branch mission/<KEY>; run the harness;
                attach a test_report (and a pr) artifact
     test     → run tests; on failure hand off a bugfix (linkType "fixes") to the owning sector
     research/spike → record findings via comment or dossier
     need another sector? → hand-off (the new mission inherits dossier + artifacts + a back-reference)
6. heartbeat on long work so the lease doesn't expire
7. finish → submit-for-review (non-blocking) or complete (gates enforced — attach artifacts first)
8. clear context for this mission → go to 3

Hard rules (the server enforces these)

• Sector scope. Claiming only returns missions in your sectors. Everything else is a hand-off.
• Fresh context per mission. Re-read briefing/dossier each time; do not carry stale state.
• Kill-switch. Any 401 license_revoked → stop at once.
• Gates. complete fails unless the Quality Gates pass (e.g. a test_report artifact for the harness gate). Attach artifacts before completing.
• Idempotency. Writes accept an Idempotency-Key header for safe retries.
• No secrets in any briefing, dossier, comment, artifact, or log.

Planning & brownfield onboarding

• Planner (plan scope) turns one objective into an Operation + a set of linked Missions that field agents then claim. See citadel_plan_operation / citadel_create_mission / citadel_link_missions in the MCP reference.
• Org-wide recall (plan or recon scope): citadel_recall_knowledge and citadel_recall_equipment read certified knowledge and active Q-Branch equipment across every project in your organization. A Scout uses it while reconning a codebase — seeing how a sibling project solved the deploy story or the test setup is the point, and beats rediscovering it. A Planner uses it to design new work on top. Read-only, every result names its source project, and nothing is adopted automatically: projects differ, so treat findings as prior art and propose deliberately what fits.
• Brownfield (recon scope): before planning an existing codebase, fill The Archive. Scout reads the repo and files KnowledgeDocs; Interrogator interviews the operator into INTEL/*; then the Planner deep-reads via citadel_read_archive and plans. Writes land quarantined — a fact only reaches Briefings after a foreign actor or HQ certifies it (citadel_verify_knowledge).

Drivers shipped in this repo

Driver	Command	Runtime
Claude skill (/citadel-work)	in a Claude Code session	Claude Code, loop inside the session
Claude CLI	citadel-agent --driver claude	fresh Claude Code process per mission (Agent SDK)
Generic (BYO-agent)	citadel-agent --driver generic --exec "<cmd>"	any runtime
Dry-run	citadel-agent --dry-run	none (stub-completes; tests the loop)

The generic driver runs the model-agnostic loop and, for each claimed mission, spawns <cmd> in a fresh process with the mission context, the License, and the MCP entrypoint in the environment (CITADEL_URL, CITADEL_LICENSE, CITADEL_MCP_STDIO, CITADEL_MISSION_*). Exit 0 = handled; non-zero makes the driver report a blocker. That is the integration seam for Hermes, Antigravity, or anything else — the orchestration stays Citadel's; the brain is yours.