Snook-A-Look Fleet Operating Manual
A visual field guide to the autonomous agent fleet: how work moves, who does what, and where it can fail.
What the Fleet Is
The Snook-A-Look fleet is an iTerm2-based multi-pane agent system that ships code across a monorepo family: snookalook-backend, snookalook-web, snookalook-mobile, snookalook-admin-web, and snookalook-frontend. It is not a chatroom of models; it is a pipeline with defined roles, queues, audit gates, and a doctrine of scars.
Panes
iTerm2 sessions running long-lived Claude/Codex roles, launched by agents/run-<role>.sh and wired through agents/topology.json.
Conductor
A Python one-transport daemon that turns agents/inbox/<from>-<to>-<topic>-<unix>.md briefs into pane input. It deduplicates, orders, and probes liveness.
Doctrine
Founder-penned engineering law in docs/doctrine/8.x slots. Each slot captures one recurring failure class and its prescribed fix.
Live Roster
Roles are divided into pillars (planning and governance), workers (execution), and support. The kk:code-reviewer is not a pane; it is a headless subagent spawned in a worktree.
| Role | Class | Model / Effort | Job |
|---|---|---|---|
| god | pillar | opus / high | Founder proxy; scheduling, FS-POLL, cadence, asks founder only when required. |
| principal | pillar | opus / high | Orchestrates execution, runs merge gate, filters scope-locks, owns audit receipts. |
| architect | pillar | opus / high | Refines prompts, audits structural/authority/money paths, pre-dispatch gate. |
| curator | pillar | sonnet / medium | Refines docs, audits correctness, doctrine curation, pre-dispatch gate. |
| infra | worker | opus / medium | Pillars, CI, launchd, secrets, environment wiring. |
| backend | worker | opus / medium | Fastify/Prisma server, settlement, APIs. |
| android / mobile | worker | sonnet / medium | KMP Compose Multiplatform Android builds. |
| ios | worker | sonnet / medium | iOS/KMP SwiftUI and App Store pipeline. |
| admin-web / web | worker | sonnet / medium | Next.js admin surface. |
| deploy | worker | sonnet / high | Vercel, VPS, mobile release runs. |
| qa-mobile | worker | sonnet / medium | Maestro E2E, device installs, visual evidence. |
| shared | worker | sonnet / medium | Cross-cutting KMP shared logic. |
| herald | support | haiku / low | Documentation-only projection (retired from execution 2026-08-26). |
| founder-console | support | opus / high | Founder-facing chat pane. |
| pr-steward | support | sonnet / medium | Thread closure, PR reply handshakes. |
| kk:code-reviewer | subagent | Agent tool | Independent code review in a worktree; never a pane, never woken. |
| conductor | daemon | opus | MD inbox to pane transport; launchd supervised. |
How Work Moves
A task enters through a pillar, is shaped by architect and curator, dispatched as a brief, executed by a worker, reported, and merged through principal-merge.sh.
flowchart TD
A[User prompt or cadence wakeup] --> B{god or principal?}
B -->|strategic / scheduling| C[god]
B -->|execution / merge| D[principal]
C --> E[FS-POLL + ScheduleWakeup pair]
D --> F[Scope-lock filter]
F --> G[Architect + Curator refine]
G --> H[Brief written to agents/inbox/]
H --> I[Conductor daemon]
I --> J{Correct layer + refine gate?}
J -->|yes| K[Wake target pane]
J -->|no| L[Quarantine / reject]
K --> M[Executor worker]
M --> N[agents/reports/ evidence]
N --> O[principal-merge.sh gate]
O --> P[dev or production]
Conductor Pipeline
- Ingest: reads
agents/inbox/*.md, from-first filename format. - Guard: content-hash dedup, payload size pointer, malformed brief quarantine.
- Order: priority queue with defer/backoff and a 2-hour abandon backstop.
- Inject: probes pane screen contents and types a brief pointer into the correct iTerm session.
Audit and Merge Gates
Impact-Routed PR Review Lifecycle
- Contract freeze: Architect, Curator, and kk audit the final local commit before the PR opens. Each PASS names the full SHA.
- Build loop: open the PR, then run CI, Codex, and AGY concurrently on the exact head.
- Fix loop: implement only verified findings. kk reviews the new exact head and the finding reviewer receives a targeted resolution handshake.
- Impact-routed delta: only the role whose axis changed re-attests the exact head. Documentation/mechanical/test-only fixes carry forward with a kk scope receipt.
- Close and merge: resolve approved threads, immutable-head recheck, then run
principal-merge.sh.
flowchart LR
A[Local commit ready] --> B[Architect audit]
A --> C[Curator audit]
A --> D[kk subagent review]
B --> E{PASS?}
C --> E
D --> E
E -->|all PASS| F[PR opened at exact head]
F --> G[CI]
F --> H[Codex review]
F --> I[AGY swarm]
G --> J{Findings?}
H --> J
I --> J
J -->|yes| K[Fix at new head + re-review]
K --> J
J -->|clean| L[principal-merge.sh]
L --> M[dev merge]
principal-merge.sh Checks
- Curator and Architect PASS reports exist for the trace.
- Reports name the exact audited commit and that commit matches PR head.
- Codex clean verdict on the head, or an engineer triage marker after the round cap.
- Zero unresolved P0/P1 threads (or proper closure label).
- AGY clean verdict if enabled; exception flags documented.
- Commit subject lint: no em-dash (U+2014), no mojibake, conventional-commit shape.
- Sensitive paths force curator + architect audit; other paths may use
--lane kk-codex.
Severity Floor (2026-09-14 Amendment)
| Severity | Action |
|---|---|
| P0/P1 | Blocks merge. Must be fixed and the finding reviewer must confirm closure. |
| P2/P3 | Becomes an FU entry under agents/backlog/ with verdict: PASS, not a merge blocker. |
| Round cap | After codex_round_cap reviewed heads, an engineer triage marker stands in for Codex clean. |
Doctrine System
Doctrine is the scar-compilation pipeline: each numbered slot is a founder-penned law born from a production incident. Slots flow from draft to LIVE and are mechanized in hooks, CI, or scripts.
flowchart LR
A[Incident] --> B[Founder pen]
B --> C[Numbered slot docs/doctrine/8.x]
C --> D[Mechanize in CI/hook/script]
D --> E[Register in doctrine-slot-tracker.md]
E --> F[Loaded into CLAUDE.md table]
Sample of LIVE Doctrine Slots
| Slot | Domain | Enforcement |
|---|---|---|
| 8.22 | Secret bytes never echo into chat | hook + prose |
| 8.26 v3 | Branch policy: mobile master, cadence merge | hook + GitHub rulesets |
| 8.31 | Never kill MobAI-Runner | fleet-hygiene hook |
| 8.37 | Post-build daemon kill mandatory | script + Fastlane after_all |
| 8.40 | Dev feature/<slug> sub-branches | prose |
| 8.42 | Architect + Curator pre-dispatch refine | wake-pane gate |
| 8.54 | Ktor 401 refresh race needs Mutex | script + CI |
| 8.67 | Logout-drain chain isolation | test fleet |
| 8.71 | Deploy env-delta ships with code | prose |
| model-tiering | Pane fixed by task type; cheap subagents for low-reasoning work | prose + spawn rules |
Full registry: agents/state/doctrine-slot-tracker.md. Pen history: docs/doctrine/PEN-LOG.md.
Key Decisions
Branch Policy v3
| Repo | Production | Merge rule |
|---|---|---|
| snookalook-mobile | master | Founder pen per merge + semver annotated tag |
| backend / admin-web / landing | main | Cadence-merge (audit-gated, god asks founder every 1-3 days) |
| All | dev | Unlocked canonical integration; feature/<slug> sub-branches |
Model Tiering
| Tier | Model | Use |
|---|---|---|
| hard | opus | Planning, audits, architect, principal, god |
| normal | sonnet | Implementation, workers, qa |
| trivial | haiku | herald projection only |
Mid-session /model switch is banned. Change tier only by relaunching the pane.
Autonomy Decision Tree
- Is the action one of the five founder-gated categories?
- Mobile deploy, founder decision, collision, P0 critical, payment/paid-account: STOP and surface to founder (or god).
- Is it a merge to main/master?
- Requires curator + architect PASS on head, then principal-merge.sh.
- Is it a dev merge?
- Requires curator + architect + qa PASS, then merge. No founder ask.
- Self-authorized: act, then report.
Lessons Learned
The fleet evolved through eras E1-E7. The most valuable meta-patterns and gotchas are captured here.
Top Techniques
- Scar-compilation pipeline: incident, pen, slot, gate, citations in hook headers.
- Identity-as-untrusted-input: session markers, process tree checks, fail-loud if identity is uncertain.
- Pointer-dispatch + payload gates: briefs live in files; wakes carry short pointers; no raw tool-call leakage.
- Exact-head evidence: audit receipts bind full SHAs, not branch names or timestamps.
- Cross-vendor quota failover: Claude/Codex defection with documented loss.
- Graduated-destructiveness recovery: wedge tiers ordered by what they destroy.
- Mechanical over behavioral: hooks and launchd replaced documented-but-fictional guarantees.
Common Gotchas
- kk is a subagent, not a pane. Never wake-pane for kk; dispatch it with a worktree and diff.
- Never put the full brief in the wake message. Inline payloads trigger the raw
<invoke>render glitch. - A clean automated review is evidence, not proof. The engineer owns the verdict, not the bot.
- Stale-base regression: always probe for symbol-dep, xcconfig literal, and claim-vs-AMEND drift.
- Post-build cleanup: kill gradle, KotlinCompileDaemon, xcodebuild, and emulators after every run. Never kill MobAI-Runner.
- Memory health:
MEMORY.mdauto-compacts at ~24.4KB. Durable facts live in individual memory files, not only MEMORY.md.
Scope Fence
Two fences keep principal from overstepping: founder-gated actions and the scope-lock registry.
Five Founder-Gated Actions
| # | Category | Examples |
|---|---|---|
| 1 | Mobile deployment | App/Play Store submit, master cut, semver tag |
| 2 | Founder decisions | Doctrine pen, legal/team/domain changes, product direction |
| 3 | Collisions | Conflicting pens needing arbitration |
| 4 | Critical issues | P0: prod down, data loss, active breach, fleet-wide auth break |
| 5 | Payment / paid-account | Stripe LIVE rotation, billing, any money movement |
Scope-Lock Registry
agents/state/principal-scope-locks.json lists workstreams owned by founder (often with god or architect) that principal must exclude from FS-POLL and status reports. Current locks include:
- ios-map-marker-fix-2026-06-22: iOS map marker workstream; founder + god joint. Reopen only on direct founder ask.
- herald-execution-retirement-2026-08-26: Herald is documentation-only for Notion; never dispatched.
Auto-add discriminators: "me and god", "hands off", "until I ask", "work solely".
Key Commands
bash agents/tools/wake-pane.sh <role> "see agents/inbox/<from>-<to>-<topic>-<unix>.md" bash agents/tools/principal-merge.sh <sub_repo> <branch> <trace> --gh-pr <n> bash agents/tools/ensure-pr-audit.sh <sub_repo> <branch> <trace> bash agents/tools/pr_raise_gate.sh <sub_repo> <branch> <review_trace_id> python3 agents/tools/lesson_recall_lean.py "<query>" python3 agents/tools/harness_audit.py python3 agents/tools/fleet_health_probe.py
Environment Flags
MERGE_THREADS_EXCEPTION=1 # codex quota exhausted; AGY still enforced MERGE_SWARM_EXCEPTION=1 # AGY down, founder authorized; codex still enforced DEVICE_EVIDENCE_EXCEPTION=1 # founder-pen override of pre-PR mobile device evidence REFINE_GATE_EXEMPT=1 # tiny value-tune / ops brief only, logged WAKE_PANE_ALLOW_LONG=1 # rare long wake message, otherwise 160-char pointer WAKE_PANE_SKIP_GATE=1 # legacy briefs, bypass layer gate