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.

flowchart TB
    Board["Board (regent)"]
    Saga["Saga — Seneschal<br/>ops, dispatch, board exec"]
    Ragna["Ragna — Chancellor<br/>CEO, strategy"]
    Vidar["Vidar — Master of Craft<br/>CTO, review, architecture"]

    Runa["Runa — Artificer<br/>Backend (Rust)"]
    Finn["Finn — Weaver<br/>Frontend (React)"]
    Gerda["Gerda — Castellan<br/>DevOps"]
    Sindri["Sindri — Assayer<br/>QA, smoke tests"]
    Ravens["Ravens<br/>Inbox sync"]

    Board --> Saga
    Board --> Ragna
    Ragna --> Vidar
    Vidar --> Runa
    Vidar --> Finn
    Vidar --> Gerda
    Vidar --> Sindri
    Ragna --> Ravens

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

sequenceDiagram
    participant R as Regent (phone/desktop)
    participant GH as GitHub Issues
    participant RV as Ravens (hourly)
    participant PP as Paperclip (CAS-N)
    participant CTO as Vidar (CTO)
    participant Eng as Engineer agent
    participant PR as GitHub PR
    participant QA as Sindri (Assayer)

    R->>GH: gh issue create (or phone capture)
    RV->>GH: poll abernerus/paperclip-inbox + casaconomy-app
    RV->>PP: mirror as CAS-N issue
    CTO->>PP: plan, break down, assign to engineer
    PP->>Eng: wake on assignment (heartbeat)
    Eng->>Eng: create worktree, implement, test
    Eng->>PR: git push + gh pr create
    Eng->>PP: @CTO + @Assayer — ready for review
    QA->>PR: smoke test (Trial of the Stones)
    CTO->>PR: code review
    CTO->>PR: approve + merge (last reviewer merges)
    Eng->>Eng: post-merge cleanup (worktree GC)

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.sh and .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.

See: CHANGELOG → 2026-05-18