aradotso/skills/citadel-agent-orchestration

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

```bash
# 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 — Full install guide
• docs/SKILLS.md — All 25 skills with parameters
• docs/HOOKS.md — Hook reference and opt-in config
• docs/CAMPAIGNS.md — Campaign persistence spec
• docs/FLEET.md — Fleet coordination protocol
• CONTRIBUTING.md — How to submit skills and PRs