Sethgammon Citadel Citadel

/do — Unified Intent Router

Orientation

Use /do when the user wants something done but doesn't know (or care) which tool handles it. Don't use when: you know the destination — invoke /marshal, /archon, /fleet, or any skill directly.

Commands

Protocol

Classification runs top-to-bottom. First match wins. Each tier is cheaper than the next.

Step 0: Skill Registry Check (Cost: ~0 on hit | ~50 tokens on miss)

Before routing, check if new skills have been added since last registration.

1. Count installed Citadel skills (built-in from plugin + custom in project's .claude/skills/)
2. Read registeredSkillCount from .claude/harness.json
3. If counts match: continue to Tier 0. Zero cost.
4. If counts differ (or harness.json doesn't exist yet): a. Read the registeredSkills array from harness.json (default: []) b. Diff skill names against the registered list c. For each unknown skill: read ONLY lines 1-10 of its SKILL.md (frontmatter) d. Extract name and description from frontmatter e. Add the skill to the Tier 2 keyword table for this session using its name and description words as match targets f. Log to the user: "Discovered {N} new skill(s): {names}. Run /do setup to rebuild the registry and regenerate the routing table from skill frontmatter." g. Update registeredSkillCount and registeredSkills array in harness.json

This means:

• 99% of invocations: one number comparison, zero file reads
• New skill dropped in: reads only the new frontmatter, routes immediately
• /do setup rebuilds the registry and runs node scripts/generate-routing.js, which regenerates the Tier 2 table below from each skill's trigger_keywords frontmatter

Tier 0: Pattern Match (Cost: ~0 tokens | Latency: <1ms)

Regex/keyword on raw input. Catches trivial commands:

If matched → execute directly. Done.

Tier 1: Active State Short-Circuit (Cost: ~0 tokens | Latency: <100ms)

Check for active campaigns or fleet sessions that match the input scope:

0. For input exactly equivalent to continue, first run:

   node scripts/continue-action.js --run
   

   • If it executes a local command such as node scripts/package-delivery.js <slug>, report the output and stop.
   • If it returns /archon continue, invoke /archon continue.
   • If it returns /fleet continue, invoke /fleet continue.
   • If it returns no command, output "No active campaign or fleet session found. Nothing to continue."
1. Read .planning/campaigns/ for files with Status: active or status: active in frontmatter
2. Read .planning/fleet/ for session files with status: active or needs-continue
3. Review-package campaigns: if the campaign status is needs-review-package or its review-package Exit Evidence row is pending while prior phases are complete, route to node scripts/package-delivery.js <slug> before Archon.
4. Improve campaigns (type: improve): if the active campaign has type: improve in frontmatter, route to /improve {target} --continue where {target} is the campaign's target field. Do NOT route improve campaigns to archon -- improve is its own orchestrator.
5. If input scope matches a non-improve active campaign → /archon continue
6. If fleet session needs continuation → /fleet continue
7. If input mentions a campaign by name → resume it (check type field for routing)
8. If input is "continue" but NO active campaign or fleet session found:
   • Output: "No active campaign or fleet session found. Nothing to continue."
   • If .planning/daemon.json exists with status: "running": the daemon spawned this session but there's no work to do. Update daemon.json: status: "stopped", stopReason: "no-active-work", stoppedAt: "{ISO timestamp}". Delete both triggers if IDs are present. Output: "[daemon] Stopped -- no active campaign found. The work is done."
   • Exit. Do NOT fall through to Tier 2 or 3.

If matched → resume the active work. Done.

Tier 2: Skill Keyword Match (Cost: ~0 tokens | Latency: <10ms)

Match input against installed skill keywords from Citadel's built-in skills and any project-level custom skills in .claude/skills/.

Built-in skill triggers (generated from each skill's trigger_keywords frontmatter; edit the frontmatter, then run node scripts/generate-routing.js to refresh this table):

Script routes (hand-maintained; these dispatch to local scripts, not skills):

If ONE skill matches with high confidence → invoke it directly. Done. High confidence = evaluator assigns ≥ 0.85 probability to exactly one skill. Below 0.85, or multiple skills above 0.70, fall through to Tier 3. If MULTIPLE skills match → carry the candidate set to Tier 3. Tier 3 disambiguates between candidates only, not from scratch. Tie-break: prefer the candidate with fewer trigger keywords.

Tier 3: LLM Complexity Classifier (Cost: ~500 tokens | Latency: ~1-2s)

When Tiers 0-2 don't resolve, classify across 6 dimensions:

SCOPE: single-file | single-domain | cross-domain | platform-wide
COMPLEXITY: 1 (trivial) | 2 (simple) | 3 (moderate) | 4 (complex) | 5 (campaign)
INTENT: fix | build | create | add | audit | redesign | research | improve | wire | prune
REQUIRES_PERSISTENCE: true | false (multi-session?)
REQUIRES_PARALLEL: true | false (independent sub-tasks?)
REQUIRES_TASTE: true | false (quality judgment beyond tests?)

Routing rules (first match wins):

Ambiguity gate: When multiple Tier 2 candidates survive or classifier confidence is below 0.7, and the AskUserQuestion tool is available: present the top 2-3 candidate routes as options, each with a label and a one-line tradeoff, and route to the user's pick. When unavailable, apply the rules above unchanged (tie-break, then /marshal default).

Important: A repeated pattern complaint ("I keep doing X manually", "the agent always makes this mistake") should route to /create-skill. A repeated pattern is a skill waiting to be extracted.

Step 3.5: Proportionality Check

After classification and before execution, verify the response is proportional to the input:

Downgrade triggers (apply in order):

Upgrade triggers:

Fleet auto-decomposition — 1/2/3 confirmation prompt:

When 2+ independent tasks detected (non-overlapping scopes, complexity >= 3, not already routed to full Fleet), read consent.fleetSpawn from harness.json:

• auto-allow → route directly to /fleet --quick
• always-ask or null → show prompt: "These look independent — run in parallel? [1=yes 2=always 3=no]"
  • 1: route to --quick, preference unchanged
  • 2: route to --quick, write writeConsent('fleetSpawn', 'auto-allow')
  • 3: run sequentially; if "don't ask again", write always-ask

readConsent/writeConsent are in hooks_src/harness-health-util.js.

Trust level: Read from harness.json trust object. Levels: novice (0-4 sessions), familiar (5-19), trusted (20+ with 2+ campaigns). trust.override takes precedence.

Step 4: After Classification

1. Log routing decision (fire-and-forget): node .citadel/scripts/telemetry-log.cjs --event agent-complete --agent do-router --session routing --status success --meta '{"tier":N,"target":"[skill]","input_chars":M}'

   Use .citadel/scripts/telemetry-log.cjs (the project-local copy). If it doesn't exist, skip logging silently — never block routing on telemetry failure.

2. Announce the routing decision: "Routing to [target] because [one-sentence reason]"

3. Invoke the target skill or orchestrator

4. If the target fails or the user says "wrong tool", try the next tier up. If the target is already Tier 3 (marshal fails or user explicitly escalates from a failed marshal attempt): re-route to /archon with the original input as context.

/do --list

Output a grouped skill list drawn from the system reminder's available skills. Group by category (Orchestration, App Creation, Code Quality, Research & Debugging, GitHub & CI, Infrastructure, Monitoring, Utilities, Observability). For each skill, show /name — one-line description. Include a footer: "Direct invocation (/skill-name) always bypasses the router."

Fringe Cases

• .planning/ does not exist: The router works without .planning/. Tiers 0, 2, and 3 are fully independent of it. Tier 1 (active-state short-circuit) reads .planning/campaigns/ and .planning/fleet/ — if those directories are absent, skip Tier 1 gracefully and fall through to Tier 2. Never crash on a missing .planning/ directory.
• harness.json missing: Skip the Skill Registry Check and proceed directly to Tier 0. Announce discovered skills from the filesystem if counts can be read, otherwise route from built-in keywords.
• Multiple skills match at Tier 2: Carry candidates to Tier 3 per Tier 2 disambiguation rule above.
• User input is empty or whitespace: Respond with the --list output and a prompt to provide a direction.
• Routed skill not found: Report "Skill not found" and fall back to Marshal as the safe default.

Contextual Gates

Disclosure: "Routing to [skill]. See that skill's contextual gates for reversibility." Reversibility: depends on routed skill — check the routed skill's reversibility Trust gates:

• Any: routing and dispatch; inherits trust gates from the routed skill.

Quality Gates

• Tier 0-2 must resolve in under 1 second
• Tier 3 classification must be transparent (announce reasoning)
• Never route a trivial task (complexity 1) to Archon or Fleet
• Never route a multi-session task to a bare skill
• If routing fails, default to Marshal (safe middle ground)

Exit Protocol

After routing and execution complete:

• If the routed skill/orchestrator produces a HANDOFF, relay it to the user
• If the task was trivial (Tier 0), just show the result
• Do not add overhead to simple tasks
• Telemetry is fire-and-forget — never surface telemetry errors to the user

Source: SethGammon/Citadel — distributed by TomeVault.