Citadel

# Codex Harness

An agent orchestration system for Codex. This repo IS the harness.

## What This Is

The harness is a collection of skills, agents, hooks, and state files that enable
Codex to operate autonomously on any codebase. It provides:
- Intent routing (`/do`) that dispatches tasks to the right tool
- Campaign persistence across sessions
- Parallel agent coordination with discovery sharing
- Automated quality enforcement through lifecycle hooks

## Key Conventions

- Skills live in `skills/`. Each skill is a directory `skills/{name}/SKILL.md`.
- Agents live in `agents/`. They spawn as sub-processes with their own context.
- Hooks live in `hooks_src/`. Installed per-project via `scripts/install-hooks.js`.
- The `init-project` hook auto-scaffolds per-project state on session start:
  - `.planning/` — campaign state, fleet sessions, intake, telemetry
  - `.citadel/scripts/` — utility scripts (telemetry, coordination, compression)
  - `.claude/agent-context/` — rules injected into sub-agents
- Campaign state lives in `.planning/campaigns/` (per-project).
- Fleet session state lives in `.planning/fleet/` (per-project).
- Templates live in `.planning/_templates/` (copied from plugin on init).
- Configuration lives in `.claude/harness.json` (generated by `/do setup`, per-project).

## Testing

Always run tests after modifying hooks or skills. Five levels:

| Command | What it checks | When to run |
|---|---|---|
| `node scripts/test-all.js` | Hooks + skill structure (fast, no LLM) | After any change |
| `node hooks_src/smoke-test.js` | Hooks only | After hook changes |
| `node scripts/verify-hooks.js` | Hook install + runtime (synthetic payloads, no LLM) | After hook changes |
| `node scripts/integration-test.js` | Full Pre→tool→Post pipeline sequences (no LLM) | After hook changes |
| `node scripts/skill-lint.js` | All SKILL.md structure | After skill changes |
| `node scripts/skill-bench.js` | Scenario file validity | After adding benchmarks |
| `node scripts/skill-bench.js --execute` | Live scenario execution | Before shipping |
| `node scripts/skill-bench.js --execute --verify-hooks` | Live execution + confirms hooks fired | Before shipping |

**Adding a new skill:** create `skills/{name}/SKILL.md`, then run `node scripts/skill-lint.js {name}` to verify structure.

**Adding a benchmark scenario:** create `skills/{name}/__benchmarks__/{scenario}.md`, then run `node scripts/skill-bench.js --skill {name}` to validate.

**CI:** `node scripts/test-all.js` exits non-zero on any failure. Use `--strict` to treat WARNs as failures.

**Shallow clones:** `Freeze dependency closure` reads committed freezes with `git show <commit>:<path>` and fails on a shallow clone for reasons unrelated to your change. Run `git fetch --unshallow` first; see CONTRIBUTING.md for detail.

## Review Guidelines

Codex GitHub review should focus on actionable P0/P1 issues:
- correctness regressions in hooks, skills, routing, MCP, generated config, or campaign state
- security boundaries around shell commands, protected files, permissions, and unattended automations
- missing verification when a change affects hooks, skills, runtime adapters, or generated Codex artifacts
- stale generated artifacts that would mislead Codex users

## Handoff Summary (Required)

After completing any task, output a `HANDOFF` block:

```
---HANDOFF---
- What was built or changed
- Key decisions and tradeoffs
- Unresolved items or next steps
---
```

3-5 bullets, under 150 words.