Agent Orchestration
Agent orchestration
| Owner | Saga (Seneschal) |
| Last reviewed | 2026-05-07 by Vidar |
| Next review | 2026-08-07 |
| Source paths | .agents/personas/, .agents/skills/, .paperclip/, AGENTS.md |
What it is
The AI agent system that builds, tests, reviews, and operates Casaconomy. A local Paperclip instance orchestrates a household of officers — each with a persona, skills, and standing routines — that coordinate through GitHub issues, pull requests, and Paperclip’s issue queue.
How it fits
Agent orchestration is the meta-layer above the application itself. It does not ship in the binary; it governs how the binary gets built. The desktop app’s architecture docs describe what the system does — this doc describes who builds it and how they coordinate.
Components
| Source | Responsibility |
|---|---|
.agents/personas/*.md | Tier-2 working briefs: role, voice, working contract, red lines |
.agents/skills/ | Skill definitions: SKILL.md frontmatter + references + scripts |
.agents/skills/subscriptions.json | Manifest of subscribed external skills |
.paperclip/ | Local instance config: adapters, daemons, scripts, secrets |
.paperclip/adapters/oz-local/ | Oz-local adapter (npm package @abernerus/adapter-oz-local) |
.paperclip/scripts/ | Operational scripts: OAuth sync, orphan detection, daemon health |
.paperclip/launchd/ | LaunchAgent plist templates for macOS daemons |
AGENTS.md | Canonical engineer instructions (tech stack, git workflow, DoD) |
Persona model
Officer context loads in three tiers:
| Tier | What | Where | When loaded |
|---|---|---|---|
| 1 — Lore | Character backstory, voice, narrative | gripsborg-saga repo (Lore/characters/) | On demand via casaconomy-lore skill |
| 2 — Working brief | Role, craft, contract, protocols, red lines | .agents/personas/<role>.md | Every agent wake (Paperclip syncs to adapter) |
| 3 — Memory | Learned context, incident history, preferences | ~/.paperclip/…/agents/<id>/MEMORY.md | Every agent wake (auto-loaded) |
Work queue flow
Routines
Scheduled wakeups that drive recurring agent work.
| Routine | Officer | Interval | Purpose |
|---|---|---|---|
| Master’s Rounds | Vidar (CTO) | Every 30 min | Triage open PRs + Paperclip issues |
| Trial of the Stones | Sindri (Assayer) | Every 2 hours | Full-stack E2E smoke test |
| Ravens’ Flight | Ravens | Hourly | Mirror GitHub inbox → Paperclip CAS issues |
| Framework Watch | Tutor | Weekly | Digest upstream release notes (Tauri, Deno, Mantine, etc.) |
| Skill Subscription Sweep | Tutor | Weekly | Detect drift in subscribed external skills |
Daemons
Background launchd agents that keep the household infrastructure healthy.
| Daemon | Interval | Purpose |
|---|---|---|
sync-agent-envs | 2 min | Keep OAuth token synced to all agents; shadow ANTHROPIC_API_KEY="" |
hide-stale-inbox-syncs | 2 min | Hallucination safety net for inbox sync |
unstall-heartbeat-orphans | 2 min | Unblocks auto-blocked issues; prevents stalled continuation chains |
detect-orphan-clones | Hourly | Scan for orphan git repos (no remote) and alert |
worktree-gc | Daily | Clean merged worktrees whose parent CAS is done/cancelled |
check-daemon-health | Daily | Verify all daemons loaded + logs are recent |
Adapter and runtime
Agents run through the oz-local adapter: Paperclip sends a wake payload to Claude Code (Oz CLI), which spawns a session with the agent’s persona, skills, and memory loaded. The adapter streams NDJSON events back to Paperclip for attribution and run tracking.
Authentication uses a long-lived Claude Max OAuth token
(~/.paperclip/secrets/claude-oauth-token), rotated via
set-claude-oauth.sh and distributed by the sync-agent-envs daemon.
Every agent subprocess receives a JWT (PAPERCLIP_API_KEY) for
attributed API mutations via the pc CLI.
Git conventions
| Surface | Who commits | Identity | Guard |
|---|---|---|---|
Main clone (casaconomy-app/) | Saga only (via pc commit) | Officer author header | Pre-commit hook requires ALLOW_MAIN_CLONE_COMMIT=1 |
Per-task worktree (worktrees/CAS-N-slug/) | Assigned engineer | Worktree-local git user.name/email | Standard git hooks |
Role worktrees (casaconomy-app-{backend,frontend}/) | Read/test only | N/A | Not for commits |
Branch naming: {feature,fix}/cas-<n>-<slug> off origin/master.
Conventional commits: feat(CAS-child):, fix(CAS-child):, chore(CAS-child):.
Failure modes + recovery
| Failure | What happens | Recovery |
|---|---|---|
| OAuth token expired | All agent wakes fail with auth error | Run set-claude-oauth.sh; sync-agent-envs distributes within 2 min |
| Orphan worktree (GC missed) | Disk bloat; stale cargo target dirs | detect-orphan-clones alerts; run migrate-worktree-cargo.sh manually |
| Routine continuation loop | Agent posts empty comments, re-wakes indefinitely | Pause routine + flip issue to done; investigate trigger config |
| Daemon symlink breakage | Scripts in ~/.paperclip/scripts/ point to deleted worktree | Scan after worktree GC; re-run install.sh if needed |
| Pre-commit hook bypass | Engineer commits to main clone | Hook blocks unless ALLOW_MAIN_CLONE_COMMIT=1; investigate and revert |
What’s planned to change
No active architectural changes to the agent orchestration system. Open improvements:
- Worker security — Codex + Claude Code guard scopes need to stay aligned whenever Layer 2 rules change (see
casaconomy-cwd-guard.shand.codex/hooks.json).
Last reviewed: 2026-05-07 by Vidar. Next review: 2026-08-07.
What changed {#what-changed}
This chapter was introduced in CAS-3637 Phase 3 (The Casaconomy Book) as the canonical reference for the agent orchestration system.