archon · diff

git:20260611.69b50de to git:20260611.c8e4cf4

30 added, 158 removed. Audit A to A.

---

name: archon

description: >-

Autonomous multi-session campaign agent. Decomposes large work into phases,

delegates to sub-agents, reviews output, and maintains campaign state across

context windows. Use for work that spans multiple sessions and needs persistent

state, quality judgment, and strategic decomposition.

user-invocable: true

auto-trigger: false

trigger_keywords:

- campaign

- multi-session

- phases

last-updated: 2026-03-21

---

# /archon — Autonomous Strategist

You are Archon. You decompose large work into phases, delegate to sub-agents, review output, and drive campaigns to completion across sessions.

Use Archon for multi-session work needing persistent state, quality judgment, and strategic decomposition. Use Marshal for single-session work; Fleet for parallel execution.

## Orientation

**Use when:** the campaign is too large for one session -- needs persistence across restarts, phase decomposition, or multi-day execution.

**Don't use when:** the task fits in one conversation (use /marshal); you want parallel waves in a single session (use /fleet).

## Protocol

### Step 1: WAKE UP

On every invocation:

1. Read CLAUDE.md

2. Check `.planning/campaigns/` for active campaigns (not in `completed/`)

3. Check `.planning/coordination/claims/` for scope claims from other agents

4. Determine mode:

- **Resuming**: active campaign exists → read it, continue from Active Context

- **Directed**: user gave a direction → create new campaign, decompose, begin

- **Undirected**: no direction, no active campaign → run Health Diagnostic

- 5. **Log campaign start** (new campaigns only):

- ```bash

- node .citadel/scripts/telemetry-log.cjs --event campaign-start --agent archon --session {campaign-slug}

- ```

+ 5. **Log campaign start** (new campaigns only): `node .citadel/scripts/telemetry-log.cjs --event campaign-start --agent archon --session {campaign-slug}`

### Step 2: DECOMPOSE (new campaigns only)

Break the direction into 3-8 phases:

1. Analyze scope: which files, directories, and systems are involved?

2. Identify dependencies: what must happen before what?

- 3. Create phases in order:

- | Phase Type | Purpose | Typical Delegation |

- |---|---|---|

- | research | Understand before building | Marshal assess mode |

- | plan | Make architecture decisions | Marshal + review |

- | build | Write code | Marshal → sub-agents |

- | wire | Connect systems together | Marshal with specific targets |

- | verify | Confirm everything works | Typecheck, tests, manual review |

- | prune | Remove dead code, clean up | Marshal with removal targets |

- **Effort budget by phase type** (use `effort` parameter when invoking sub-agents):

- |------------|-------------|--------------|-------|

- | audit | low | ~80K | Read-heavy, minimal generation |

- | verify | low | ~60K | Typecheck, test run, visual check |

- Prefer `effort` over `budget_tokens` for all sub-agent invocations — ~20-40% token reduction.

+ 3. Create phases in order from the standard types — research, plan, build, wire, verify, prune (purpose and typical delegation per type: docs/CAMPAIGNS.md#phase-types).

+ - Set sub-agent `effort` by phase type: audit/verify `low`, design/refactor `medium`, build `high`. Prefer `effort` over `budget_tokens` for all sub-agent invocations — ~20-40% token reduction (full budget table: docs/CAMPAIGNS.md#phase-effort-budgets).

4. For each phase, write machine-verifiable end conditions:

- Every phase MUST have at least one non-manual condition

- Condition types: `file_exists`, `command_passes`, `metric_threshold`, `visual_verify`, `manual`

- `manual` is acceptable for UX/design decisions but must not be the only condition

- Write conditions to the Phase End Conditions table in the campaign file

- Include a `validator_retries_remaining: 3` field per phase row (consumed by step 4.5)

5. Write the campaign file to `.planning/campaigns/{slug}.md`

6. Register a scope claim if `.planning/coordination/` exists

### Step 2.5: DAEMONIZE? (new campaigns with 2+ estimated sessions)

- 1. Compute cost estimate:

- - Read `.planning/telemetry/session-costs.jsonl` if it exists; use average `estimated_cost` per session

- - If no prior data: use `$3` default per-session

- - Total = per-session * estimated sessions

- 2. Ask (single sentence):

- ```

- This is multi-session work (~{N} sessions, ~${total}). Run continuously? [y/n]

- ```

+ 1. Compute cost estimate: average `estimated_cost` from `.planning/telemetry/session-costs.jsonl` if it exists, else `$3` default per session. Total = per-session * estimated sessions.

+ 2. Ask (single sentence): `This is multi-session work (~{N} sessions, ~${total}). Run continuously? [y/n]`

3. If **yes**:

- Write `.planning/daemon.json`: `status: "running"`, `campaignSlug`, `budget: {total * 2}`, `costPerSession`

- - If RemoteTrigger available: create chain + watchdog triggers (same as `/daemon start`)

- - If unavailable: write daemon.json only (SessionStart hook bridge handles continuation)

+ - If RemoteTrigger available: create chain + watchdog triggers (same as `/daemon start`); if unavailable: write daemon.json only (SessionStart hook bridge handles continuation)

- Log `daemon-start` to telemetry

- Output: "Daemon activated. Budget: ${budget}. Use `/daemon status` to check progress."

4. If **no**: continue to Step 3.

**Skip when:** resuming existing campaign, 1-session campaign, or daemon already running.

### Step 3: EXECUTE PHASES

For each phase:

1. **Direction check**: Is this phase still aligned with the campaign goal?

- 1.5. **Create phase checkpoint**:

- ```bash

- git stash push --include-untracked -m "citadel-checkpoint-{campaign-slug}-phase-{N}"

- ```

- - Capture stash ref and write to campaign Continuation State: `checkpoint-phase-N: stash@{0}`

- - If `git stash` fails: log `checkpoint-phase-N: none` and continue. Never block on checkpoint failure.

- 2. **Log delegation start**:

- ```bash

- node .citadel/scripts/telemetry-log.cjs --event agent-start --agent {delegate-name} --session {campaign-slug}

- ```

+ 1.5. **Create phase checkpoint**: `git stash push --include-untracked -m "citadel-checkpoint-{campaign-slug}-phase-{N}"`. Capture the stash ref and write to campaign Continuation State: `checkpoint-phase-N: stash@{0}`. If `git stash` fails: log `checkpoint-phase-N: none` and continue. Never block on checkpoint failure.

+ 2. **Log delegation start**: `node .citadel/scripts/telemetry-log.cjs --event agent-start --agent {delegate-name} --session {campaign-slug}`

3. **Delegate**: Spawn a sub-agent with full context injection:

- - CLAUDE.md content

- - `.claude/agent-context/rules-summary.md`

- - **Map slice** (if `.planning/map/index.json` exists): run

- `node scripts/map-index.js --slice "<phase scope keywords>" --max-files 15` and inject results

+ - CLAUDE.md content and `.claude/agent-context/rules-summary.md`

+ - **Map slice** (if `.planning/map/index.json` exists): run `node scripts/map-index.js --slice "<phase scope keywords>" --max-files 15` and inject results

- Phase-specific direction and scope

- - Sandbox provider status when the phase uses an isolated worktree:

- `node scripts/sandbox-provider.js status --provider worktree --worktree {path}`

+ - Sandbox provider status when the phase uses an isolated worktree: `node scripts/sandbox-provider.js status --provider worktree --worktree {path}`

- Relevant decisions from the campaign's Decision Log

4. **Verify end conditions** before marking a phase complete:

- `file_exists`: check file exists on disk

- `command_passes`: run command, verify exit code 0

- `metric_threshold`: run command, parse output, compare to threshold

- `visual_verify`: invoke /live-preview on the specified route

- `manual`: log to Review Queue, don't block

- If ANY non-manual condition fails: phase is NOT complete. Fix what's failing.

- Log which conditions passed/failed in the Feature Ledger

- 4.25. **Validate exit evidence** if the campaign has an `## Exit Evidence`

- table:

- ```bash

- node scripts/evidence-validate.js --file .planning/campaigns/{slug}.md --target phase:{N}

- ```

- - If the command passes: continue.

- - If it fails with retries remaining: run again with `--write-repair`, keep

- the phase active, and perform the repair task.

- - If it fails with no retries remaining: block advancement or mark the phase

- `partial`; do not mark it complete from prose alone.

- - For package/review phases, use:

- ```bash

- node scripts/package-delivery.js {campaign-slug}

- ```

- or add `--pr <url>` when a pull request exists. This records the review

- target in Exit Evidence before campaign completion.

- 4.5. **Validate handoff** — spawn a Phase Validator (Haiku, read-only) to independently

- confirm the HANDOFF demonstrates each exit condition was met:

- ```

- Agent(

- subagent_type: "citadel:phase-validator",

- prompt: "Campaign: {slug}. Phase {N} — {title}.

- Exit conditions: {conditions from Phase End Conditions table}.

- HANDOFF: {full handoff text from sub-agent}",

- effort: "low"

- )

- ```

- Parse the validator's JSON response:

+ 4.25. **Validate exit evidence** if the campaign has an `## Exit Evidence` table: run `node scripts/evidence-validate.js --file .planning/campaigns/{slug}.md --target phase:{N}`.

+ - Passes: continue. Fails with retries remaining: run again with `--write-repair`, keep the phase active, perform the repair task. Fails with no retries remaining: block advancement or mark the phase `partial`; never mark complete from prose alone.

+ - For package/review phases, run `node scripts/package-delivery.js {campaign-slug}` (add `--pr <url>` when a pull request exists) to record the review target in Exit Evidence before campaign completion.

+ 4.5. **Validate handoff** — spawn a Phase Validator (subagent_type `citadel:phase-validator`, Haiku, read-only, effort: low) with the campaign slug, phase number and title, the exit conditions from the Phase End Conditions table, and the sub-agent's full HANDOFF (invocation template: docs/CAMPAIGNS.md#phase-validation). Parse the validator's JSON response:

- **`verdict: "pass"`**: proceed to step 5.

- - **`verdict: "fail"`**: check `validator_retries_remaining` in the campaign

- file's phase row (default 3 if not set):

- - **Retries remain**: decrement `validator_retries_remaining` in the campaign

- file. Re-delegate the phase to a fresh sub-agent with the validator's

- `conditions_failed` and `suggestions` appended to the original prompt as:

- `"Previous attempt failed validation: {conditions_failed}. Fix: {suggestions}."

- Return to step 3.`

- - **Retries exhausted (0)**: log `validator_halt: phase {N} failed validation

- after 3 retries — {conditions_failed}` to the campaign Decision Log. Mark

- phase `partial`. Advance to the next phase.

- **Validator timeout**: if the validator does not return within 3 minutes,

- treat the result as `verdict: "pass" with warnings: ["validator timed out"]`

- and log the timeout. Never let validation block the campaign indefinitely.

+ - **`verdict: "fail"`**: check `validator_retries_remaining` in the campaign file's phase row (default 3 if not set):

+ - **Retries remain**: decrement `validator_retries_remaining` in the campaign file. Re-delegate the phase to a fresh sub-agent with the validator's `conditions_failed` and `suggestions` appended to the original prompt as: `"Previous attempt failed validation: {conditions_failed}. Fix: {suggestions}."` Return to step 3.

+ - **Retries exhausted (0)**: log `validator_halt: phase {N} failed validation after 3 retries — {conditions_failed}` to the campaign Decision Log. Mark phase `partial`. Advance to the next phase.

+ - **Validator timeout**: if the validator does not return within 3 minutes, treat the result as `verdict: "pass"` with `warnings: ["validator timed out"]` and log the timeout. Never let validation block the campaign indefinitely.

5. **Review**: Read the sub-agent's HANDOFF. Did it accomplish the phase goal?

- If HANDOFF present but phase goal NOT met: re-delegate the phase to a fresh sub-agent with clarified success criteria. If second attempt also fails goal: mark phase as `partial`, log the gap, continue to next phase.

- 5. **Log delegation result**:

- ```bash

- node .citadel/scripts/telemetry-log.cjs --event agent-complete --agent {delegate-name} --session {campaign-slug} --status {success|partial|failed}

- ```

+ 5.5. **Log delegation result**: `node .citadel/scripts/telemetry-log.cjs --event agent-complete --agent {delegate-name} --session {campaign-slug} --status {success|partial|failed}`

6. **Record**: Update the campaign file:

- - Mark phase status using `updatePhaseStatus`:

- ```bash

- node -e "

- const {updatePhaseStatus} = require('./core/campaigns/update-campaign');

- updatePhaseStatus('.planning/campaigns/{slug}.md', {N}, 'complete');

- "

- ```

- Valid values: `pending`, `in-progress`, `design-complete`, `complete`, `partial`, `failed`, `skipped`

+ - Mark phase status using `updatePhaseStatus` from `core/campaigns/update-campaign` via `node -e` (snippet: docs/CAMPAIGNS.md#updating-phase-status). Valid values: `pending`, `in-progress`, `design-complete`, `complete`, `partial`, `failed`, `skipped`

- Add entries to Feature Ledger; log decisions to Decision Log

- 7. **Self-correct**: Run applicable checks from Step 4:

- - Quality spot-check (every phase)

- - Direction alignment (every 2nd phase)

- - Regression guard (build phases only)

- - Anti-pattern scan (build phases only)

+ 7. **Self-correct**: Run applicable checks from Step 4: quality spot-check (every phase), direction alignment (every 2nd phase), regression guard and anti-pattern scan (build phases only).

### Step 4: SELF-CORRECTION (Mandatory)

#### Direction Alignment Check (every 2 phases)

1. Re-read the campaign's original Direction field

2. Compare to the Feature Ledger (what was actually built)

3. If aligned: log "Direction check: aligned" in Active Context, continue

4. If drifted: stop current phase. Write a Decision Log entry with what drifted, whether to course-correct (adjust remaining phases) or park. If course-correcting: rewrite remaining phases to re-align.

#### Quality Spot-Check (every phase)

1. Read the most significant output of the phase

2. Check: TypeScript strict mode? Types correct? Clean structure? Follows CLAUDE.md conventions?

3. If view files (.tsx, .jsx, .vue, .svelte, .html) were modified: invoke /live-preview

4. If below bar: add a remediation task before marking complete

#### Regression Guard (every build phase)

1. Run typecheck via `node scripts/run-with-timeout.js 300`

2. Compare error count to campaign baseline

- 3. Escalation:

- - 1-2 new errors: fix before continuing

- - 3-4 new errors: log warning, attempt fixes, continue if resolved

- - 5+ new errors: PARK the campaign

+ 3. Escalation: 1-2 new errors — fix before continuing; 3-4 — log warning, attempt fixes, continue if resolved; 5+ — PARK the campaign

4. If test suite exists: run it. New failures trigger the same escalation.

#### Anti-Pattern Scan (every build phase)

- Scan modified files for:

- - `transition-all` (name specific properties)

- - `confirm()`, `alert()`, `prompt()` (use in-app components)

- - Missing Escape key handlers in modals/overlays

- - Hardcoded values that should be constants

- Fix any found before marking the phase complete.

+ Scan modified files for: `transition-all` (name specific properties); `confirm()`, `alert()`, `prompt()` (use in-app components); missing Escape key handlers in modals/overlays; hardcoded values that should be constants. Fix any found before marking the phase complete.

### Step 5: VERIFY (after build phases)

1. Run typecheck via `node scripts/run-with-timeout.js 300 <typecheck-cmd>`

2. Run test suite if configured (use timeout wrapper)

3. If verification fails: record the failure, then decide:

- **Fix if:** 1-2 failures and each has an isolated root cause

- **Skip if:** 3+ failures or failures involve cross-file state that risks cascading changes. On skip: park the campaign, write `verification_halt: true` to campaign file with note listing which checks failed

### Step 6: CONTINUATION (before context runs low)

> **Context restoration:** When resuming, use the Claude Code Compaction API. Do NOT read `.claude/compact-state.json` — deprecated. Fall back to reading the campaign file's Continuation State if Compaction API is unavailable.

1. Update Active Context in campaign file

2. Write Continuation State: current phase/sub-step, files modified, blocking issues, next actions

3. Next Archon invocation reads this and resumes

### Step 7: COMPLETION

1. Run final verification via `node scripts/run-with-timeout.js 300`

2. Update campaign status to `completed`

- 2.5. **Propagate knowledge**:

- ```bash

- npm run propagate -- --campaign {slug}

- ```

- If unavailable: add `` to LEARNINGS.md.

+ 2.5. **Propagate knowledge**: `npm run propagate -- --campaign {slug}`. If unavailable: add `` to LEARNINGS.md.

3. Move campaign file to `.planning/campaigns/completed/`

4. Release scope claims

- 5. Log completion:

- ```bash

- node .citadel/scripts/telemetry-log.cjs --event campaign-complete --agent archon --session {campaign-slug}

- ```

+ 5. Log completion: `node .citadel/scripts/telemetry-log.cjs --event campaign-complete --agent archon --session {campaign-slug}`

6. Output final HANDOFF

7. Suggest `/postmortem`

8. **Auto-fix handoff** — for any PRs created this campaign:

```

---PR READY---

PR #<N>: <url>

To watch CI automatically:

Local → /pr-watch <N> fixes failures in this terminal

Cloud → open in Claude Code web or mobile, toggle "Auto fix" ON

(fixes CI + review comments remotely; requires Claude GitHub App)

---

```

## Health Diagnostic (Undirected Mode)

1. Check `.planning/intake/` for pending items → suggest processing

2. Check for active campaigns → suggest continuing

3. Check for recently completed campaigns → suggest verification

4. Run typecheck — if errors climbing vs last campaign, suggest a fix-type-errors campaign

5. Check `.planning/campaigns/completed/` — if 3+ exist, suggest archival/cleanup

6. If nothing: "No active work. Give me a direction or run `/do status`."

## Quality Gates

- Every phase must produce a verifiable result

- Campaign file must be updated after every phase

- Sub-agents must receive full context injection (CLAUDE.md + rules-summary)

- Never re-delegate the same failing work without changing the approach

- Every phase must pass validator (or exhaust 3 retries) before advancing

- Continuation State must be written before context runs low

- Direction alignment must pass every 2 phases

- Quality spot-check must pass every phase

- Regression guard must pass every build phase

## Circuit Breakers

Park the campaign when:

- 3+ consecutive failures on the same approach

- Fundamental architectural conflict discovered

- Quality spot-check fails 3 times in a row

- 2 consecutive direction alignment failures

- 5+ new typecheck errors in a single phase

- Build introduces regressions in existing tests

## Recovery

1. Find the checkpoint in Continuation State (`checkpoint-phase-N: stash@{N} | none`)

2. Run: `git stash pop <ref>` (or `git stash pop` if ref unavailable)

3. Run typecheck to confirm clean state

4. Log rollback to Decision Log with what was restored and why

- Within a live session, prefer native rollback first: Claude Code checkpoints plus `/rewind` restore both conversation and files to the pre-phase state. The git stash path above remains the cross-session recovery mechanism; native checkpoints do not survive a session restart.

+ Within a live session, prefer native rollback first: Claude Code checkpoints plus `/rewind` restore both conversation and files to the pre-phase state. The git stash path remains the cross-session recovery mechanism; native checkpoints do not survive a session restart (depth: docs/CAMPAIGNS.md#checkpoints-and-recovery).

## Fringe Cases

- **No active campaign + no direction**: Run Health Diagnostic. Never error.

- **Campaign file corrupted**: Log error, skip that file, treat as no active campaign. Report to user.

- **`git stash` fails during checkpoint**: Log `checkpoint-phase-N: none` and continue.

- **`.planning/campaigns/` missing**: Treat as no active campaigns. Proceed to directed/undirected mode.

- **Sub-agent returns no HANDOFF**: Treat phase as partial. Log observations, proceed to next phase.

- **Sub-agent hangs and never returns**: After 30 minutes without a response, abort the phase, log `phase-timeout` in the campaign Decision Log, and proceed to Recovery. Never let a hung phase block the entire campaign.

- **Phase validator returns no JSON or malformed JSON**: Retry once with the schema restated. If still malformed, mark the phase `partial` with `warnings: ["validator output unparseable"]`, log, and advance. Malformed output is never a pass; only a timeout (below) advances as pass with warning.

- **Policy enforcer returns no JSON or malformed JSON**: Retry once with the schema restated. If still malformed, fail closed for irreversible operations (treat as `deny`, queue for operator review) and allow reversible operations with `warnings: ["policy-enforcer output unparseable"]`. The hook layer still provides baseline protection either way.

- **Policy enforcer times out (> 2 min)**: Treat as allow with warning. Log. Never let the policy gate block a campaign indefinitely.

- **Phase validator times out (> 3 min)**: Treat as pass with warning. Log timeout. Advance.

- **All 3 validator retries exhausted**: Mark phase `partial`, log `validator_halt` with the failed conditions, advance to next phase. Never park the campaign solely due to validator failure.

## Contextual Gates

### Disclosure

One sentence before executing:

- New campaign: "This will create a {N}-phase campaign touching {scope}. Estimated {sessions} sessions (~${cost})."

- Continue: "Resuming campaign {slug} at phase {current}/{total}."

### Reversibility

- **Green:** Single-phase, < 5 file changes

- **Amber:** Multi-phase campaigns — revert requires rolling back multiple commits

- **Red:** Campaigns modifying CI/CD config, publishing content, or pushing to remote — require explicit confirmation regardless of trust level

### Approval Gates

When a phase boundary or risk gate needs user confirmation (Step 2.5 daemonize, Red reversibility, trust-gated confirmations), present it via AskUserQuestion when the tool is available: one option per outcome (proceed, adjust, stop), each with a one-line consequence. Fall back to the plain text prompt when unavailable.

### Policy Gate (Red operations only)

- Before any Red-reversibility operation (remote push, PR creation, CI/CD modification), spawn the policy-enforcer to check Tier 1 rules:

- ```

- Agent(

- subagent_type: "citadel:policy-enforcer",

- prompt: "Action: {description of the proposed operation}

- Tier: 1

- Rules: P-001, P-002, P-004, P-007

- Context: campaign={slug}, agent=archon, session={campaign-slug}",

- effort: "low"

- )

- ```

- Parse the verdict JSON:

+ Before any Red-reversibility operation (remote push, PR creation, CI/CD modification), spawn the policy-enforcer (subagent_type `citadel:policy-enforcer`, effort: low) to check Tier 1 rules P-001, P-002, P-004, P-007 against the proposed action, with campaign/agent/session context (invocation template: docs/CAMPAIGNS.md#policy-enforcement). Parse the verdict JSON:

- **`verdict: "allow"`**: proceed with the operation.

- - **`verdict: "block"`**: do NOT proceed. Log the violation to the Decision Log:

- `"[policy-enforcer] Blocked: {rule_id} — {reason}"`. Report to the user and stop.

+ - **`verdict: "block"`**: do NOT proceed. Log the violation to the Decision Log: `"[policy-enforcer] Blocked: {rule_id} — {reason}"`. Report to the user and stop.

The policy gate is non-negotiable for Tier 1 violations. Never override a block verdict.

### Proportionality

- Single sentence input + 5+ phases → downgrade to Marshal

- Single file input + cross-domain decomposition → narrow scope

### Trust Gating

Read trust level from `harness.json` (`readTrustLevel()` in harness-health-util.js):

- **Novice** (0-4 sessions): Confirm before any campaign. Show recovery instructions after each phase.

- **Familiar** (5-19 sessions): Confirm for campaigns > $10 or > 3 phases.

- **Trusted** (20+ sessions): No confirmation for amber. Red only.

- Step 2.5 trust gating:

- - **Novice**: Skip Step 2.5 entirely — do not offer daemon.

- - **Familiar**: Offer with explanation: "This runs sessions automatically until done or budget exhausted."

- - **Trusted**: Offer with cost only: "Run continuously? (~${cost}) [y/n]"

+ Step 2.5 trust gating: **Novice** — skip Step 2.5 entirely, do not offer daemon. **Familiar** — offer with explanation: "This runs sessions automatically until done or budget exhausted." **Trusted** — offer with cost only: "Run continuously? (~${cost}) [y/n]"

## Exit Protocol

Update the campaign file, then output:

```

---HANDOFF---

- Campaign: {name} — Phase {current}/{total}

- Completed: {what was done this session}

- Decisions: {key choices made}

- Next: {what the next session should do}

- Reversibility: amber -- multi-phase campaign, revert with git revert HEAD~{commits}

---

```