Agent Orchestration
Saga the Watchful — Seneschal
By the end of this chapter you’ll understand:
- How the household of officers is organised and who is responsible for which domain
- How work travels from a regent request through Paperclip assignment to a merged pull request
- How recurring routines and background daemons keep the household infrastructure healthy
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).
Worked example
The work queue flow sequence diagram above traces a complete commission — from the regent filing an issue on GitHub, through Ravens mirroring it to Paperclip, through the CTO assigning it to an engineer, through the pull request, smoke test, and code review, to the merge. Follow it top-to-bottom to see how one piece of work moves through the household.
Recap
- The household is a set of AI officers — each with a persona, a domain, and a standing skill set — dispatched through Paperclip and coordinating through GitHub.
- Work enters as a GitHub issue, becomes a Paperclip CAS, gets assigned to an engineer, lives in a git worktree, and closes when the PR merges and the post-merge cleanup runs.
- Routines and daemons run on timers: Master’s Rounds keeps the queue moving, Trial of the Stones verifies the app is alive, Ravens keeps the inbox in sync.
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.