Citadel — Agent Orchestration Harness for Claude Code

---
name: citadel-agent-orchestration
description: Agent orchestration harness for Claude Code with four-tier routing, campaign persistence, parallel fleet agents, and 25 skills for autonomous coding campaigns.
triggers:
  - set up citadel for my project
  - run parallel agents with citadel
  - orchestrate a coding campaign
  - use citadel to build a feature
  - how do I use the /do router
  - run a fleet of agents in parallel
  - persist a coding campaign across sessions
  - automate code review with citadel
---

# Citadel — Agent Orchestration Harness for Claude Code

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Citadel is a Claude Code **plugin** that routes any coding task through the cheapest capable tool — from a direct one-line fix to a multi-day parallel agent campaign. It provides 25 skills, 4 autonomous sub-agents, 10 lifecycle hooks, and campaign persistence across sessions.

---

## Installation

**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) + Node.js 18+

# 1. Clone Citadel once (global install — works across all projects)

git clone https://github.com/SethGammon/Citadel.git ~/citadel

# 2. Launch Claude Code with the plugin loaded

claude --plugin-dir ~/citadel

# 3. Run first-time setup inside any project

/do setup

**Persistent install (recommended):**

/plugin marketplace add ~/citadel

/plugin install citadel@citadel-local

/reload-plugins

After install, `/do` is available in every Claude Code session.

---

## Core Concept: The `/do` Router

Type what you want in plain English. `/do` classifies intent and dispatches to the cheapest capable path automatically.

/do fix the typo on line 42 → Direct edit (zero overhead)

/do review the auth module → /review (5-pass code review)

/do why is the API returning 500 → /systematic-debugging

/do add payments to my app → /create-app tier 5

/do build me a recipe app → /prd → /architect → /archon

/do overhaul all three services → /fleet (parallel agents)

/do continue → resumes active campaign

You never have to choose the tier. If routing is wrong, say "wrong tool" or "just do it yourself" and it adjusts.

---

## Four-Tier Orchestration Ladder

| Tier | Tool | When to Use |
|------|------|-------------|
| 1 | **Skill** | Single-domain task (review, test, doc, refactor) |
| 2 | **Marshal** | Multi-skill chain within one session |
| 3 | **Archon** | Multi-session autonomous campaign with quality gates |
| 4 | **Fleet** | Parallel agents across isolated git worktrees |

---

## Key Skills Reference

### App Creation

/prd "a recipe sharing app with user accounts and ratings"

# → Generates a full Product Requirements Document

/architect

# → Converts active PRD into file tree, build phases, end conditions

/create-app

# → End-to-end creation (5 tiers: blank → guided → templated → generated → feature addition)

### Core Skills

/review src/auth/ # 5-pass: correctness, security, performance, readability, consistency

/test-gen src/payments.ts # Generates runnable tests; detects framework; retries up to 3x

/doc-gen src/api/ # Function/module/API reference docs; matches your style

/refactor src/legacy/ # Safe multi-file refactor; typechecks before/after; reverts on failure

/scaffold "UserService" # Project-aware file generation; reads your conventions

/create-skill # Turns a repeating pattern into a reusable Citadel skill

### Research & Debugging

/research "best approach for rate limiting in Express"

/research-fleet "compare auth strategies: JWT vs sessions vs OAuth" # parallel scouts

/experiment "optimize this function" fitness="benchmark score" # isolated worktree loops

/systematic-debugging # 4-phase root cause; stops after 2 failed fixes

### Quality & Verification

/design # Generates/maintains design manifest for visual consistency

/qa # Playwright-based browser interaction testing (optional dep)

/postmortem # Auto-generates structured postmortem from completed campaign

/triage # GitHub issue/PR investigator; classifies and reviews contributed code

### Utilities

/live-preview # Mid-build visual verification via screenshots

/session-handoff # Transfers context between sessions

/do setup # First-run harness configuration

---

## Campaign Persistence

Campaigns survive terminal closes and session restarts. State is stored in markdown files under `.planning/` and `.citadel/`.

# Start a campaign

/do build a full authentication system with JWT and refresh tokens

# Close terminal, come back tomorrow

/do continue # Picks up exactly where it left off

Campaign files track:
- Completed/pending phases
- Decisions made
- Feature status
- Continuation state

See `docs/CAMPAIGNS.md` in the Citadel repo for the full spec.

---

## Fleet: Parallel Agents

Fleet runs 2–3 Claude Code agents simultaneously in isolated git worktrees. Discoveries compress into ~500-token briefs that relay between waves.

/fleet "refactor the database layer, API layer, and auth layer in parallel"

**How it works internally:**
1. Fleet decomposes work into independent streams
2. Each stream gets an isolated worktree (`git worktree add`)
3. Agents run in parallel; discoveries are extracted and compressed
4. Wave 2 agents receive the compressed brief from wave 1
5. Results merge back to main branch

**Safety:** Parallel agents never share a worktree. Merges are gated on quality checks.

See `docs/FLEET.md` for coordination protocol details.

---

## Hooks (Automatic — No Configuration Needed)

These run without any action on your part:

| Hook | Trigger | Behavior |
|------|---------|----------|
| Per-file typecheck | Every file edit | Catches type errors at write-time |
| Circuit breaker | 3 consecutive tool failures | Forces "try a different approach" |
| Quality gate | Session end | Scans modified files for anti-patterns |
| Intake scanner | Session start | Reports pending work items |
| File protection | Before edit/read | Blocks edits to protected files; blocks `.env` reads |
| Pre-compaction save | Before context compaction | Saves full session state |
| Post-compaction restore | After context compaction | Restores session state |
| Worktree setup | Agent spawn | Auto-installs deps in parallel worktrees |
| External action gate | Before push/PR (opt-in) | Requires user approval before external actions |
| Init project | Session start | Auto-scaffolds `.planning/` and `.citadel/scripts/` |

**Validate all hooks are working:**

node hooks_src/smoke-test.js

---

## Real Usage Patterns

### Pattern 1: Start a New App from Scratch

/do build me a todo app with React, TypeScript, and Supabase

Citadel will:
1. Run `/prd` to generate requirements
2. Run `/architect` to generate file tree and phases
3. Spawn `/archon` to execute the campaign autonomously
4. Run `/qa` at the end to verify the result

### Pattern 2: Safe Multi-File Refactor

/refactor convert all callback-style async code in src/ to async/await

Citadel will:
1. Typecheck before changes
2. Apply refactoring across files
3. Typecheck after changes
4. Revert automatically if typechecks fail

### Pattern 3: Test Generation with Retry

/test-gen src/services/payments.ts

Citadel will:
1. Detect your test framework (Jest, Vitest, Mocha, etc.)
2. Generate tests
3. Run them
4. If failures occur, iterate up to 3 times to fix

### Pattern 4: Parallel Research

/research-fleet "compare: Prisma vs Drizzle vs Kysely for a multi-tenant SaaS"

Multiple research scouts run in parallel, then compress findings into a unified report.

### Pattern 5: Autonomous Debugging

/do why is my Stripe webhook returning 400 intermittently

Routes to `/systematic-debugging`, which runs:
1. Symptom classification
2. Hypothesis generation
3. Targeted investigation
4. Fix attempt (with emergency stop after 2 failed fixes)

---

## Creating Custom Skills

Turn any repeating pattern into a Citadel skill:

/create-skill "every time I add a new API endpoint I need to: create the route file,

add OpenAPI spec, generate the Zod schema, write integration tests, and update the README"

Citadel generates a `.claude/skills/your-skill-name.md` file you can invoke with `/your-skill-name` in future sessions.

---

## Project Structure After Setup

your-project/

├── .planning/ # Campaign state (phases, decisions, status)

│ ├── CAMPAIGN.md

│ ├── DECISIONS.md

│ └── FEATURES.md

├── .citadel/

│ └── scripts/ # Per-project hook scripts

└── ...your code...

~/citadel/ # Plugin install (global)

├── hooks_src/ # Hook implementations

│ └── smoke-test.js

├── skills/ # All 25 skill definitions

├── agents/ # Sub-agent definitions

└── docs/

├── CAMPAIGNS.md

├── FLEET.md

├── SKILLS.md

└── HOOKS.md

---

## Token Cost Guide

| Operation | Approximate Cost |
|-----------|-----------------|
| Skills (not loaded) | 0 tokens |
| `/do` router (Tier 3) | ~500 tokens |
| Hook per edit | ~100 tokens |
| The actual work | Varies by task |

---

## Troubleshooting

**`/do` not found after install:**

/reload-plugins

**Hooks not firing:**

node ~/citadel/hooks_src/smoke-test.js

**Campaign state corrupted:**

/do setup # Re-initializes .planning/ and .citadel/ without destroying code

**Fleet agents conflicting:**
Fleet uses isolated `git worktree` per agent — conflicts mean you have uncommitted changes in the main worktree. Commit or stash first:

git stash

/fleet "..."

**Archon stopped mid-campaign:**

/do continue # Reads .planning/CAMPAIGN.md and resumes from last completed phase

**Circuit breaker triggered (3 failures):**
This is intentional. Tell Citadel the correct approach explicitly:

/do [describe what you actually want, with more specifics]

---

## Key Docs

- [QUICKSTART.md](QUICKSTART.md) — Full install guide
- [docs/SKILLS.md](docs/SKILLS.md) — All 25 skills with parameters
- [docs/HOOKS.md](docs/HOOKS.md) — Hook reference and opt-in config
- [docs/CAMPAIGNS.md](docs/CAMPAIGNS.md) — Campaign persistence spec
- [docs/FLEET.md](docs/FLEET.md) — Fleet coordination protocol
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to submit skills and PRs