Overview and reading guide¶
Purpose¶
This set of documents specifies how to build Sea Suite — Agentic Management Systems, the harness that runs the management layer of an organization. The product thesis, roster, deployment modes and requirements live in the PRD; these docs are the engineering counterpart: schemas, state machines, rule tables, edge cases, control loops and runbooks, written so a small team can build the system without re-deriving the decisions.
Scope / Non-scope¶
- In scope: everything between an owner's direction and a person's work — the Org Model, the harness, the manager agents, the policy engine, the decision pipeline, risk controls, escalation, communication rules, integrations, Atoms mode, security/privacy, evaluation, observability and rollout.
- Out of scope: the marketing site, the Seachonks IP itself (characters, series), model training, and any product that replaces IC labor rather than managing it.
The system in one paragraph¶
Sea Suite models a company as a versioned graph (the Org Model). A scheduler (the Harness) runs role-scoped agents (the Chonks) on cadences and events. Every consequential action passes through one decision pipeline — Observe → Propose → Pre-check → Act or route to a human → Verify → Record — where a policy engine assigns an autonomy class (AUTONOMOUS, PROPOSE_CONFIRM, HUMAN_ONLY) that the harness enforces, never the prompt. Deterministic function services do the math (planning, capacity, scheduling, budget, calibration). Every decision carries receipts and lands in a hash-chained audit log. Risk is managed as closed loops — Detect → Contain → Correct → Learn — backed by circuit breakers, a global kill switch, a per-tenant trust budget, and graduation from shadow mode to autonomy per function. People being managed always have a guaranteed escalation path to a named human, the manager of record.
Reading order¶
| If you are… | Read first | Then |
|---|---|---|
| Deciding whether to build this | PRD, 01 Architecture, 07 Closed-loop risk | 16 Rollout |
| Building the core | 02 Org Model, 03 Harness, 05 Policy engine, 06 Decision pipeline | 17 Data model & API, 04 Manager agents |
| Writing rules and reviewing safety | 05 Policy engine, 07 Closed-loop risk, 08 Edge-case catalog, 09 Escalation | 13 Security & compliance |
| Building the IC and owner experience | 04 Manager agents, 10 Communication rules | 09 Escalation |
| Connecting systems | 11 Integrations, 12 Atoms mode | 15 Observability & runbooks |
| Running it in production | 14 Evaluation & testing, 15 Observability & runbooks, 16 Rollout | 07 Closed-loop risk |
Document map¶
| Doc | What it settles |
|---|---|
| 01 System architecture | Components, boundaries, data flows, tenancy, failure domains, provider abstraction. |
| 02 Org Model spec | The graph schema, invariants, versioning, identity merging, offboarding, worked examples. |
| 03 Harness and orchestration | Run lifecycle, triggers, idempotency, retries, event sourcing, budgets, listening period, graduation state. |
| 04 Manager agents | Role charters, sub-agents, tool allowlists, prompt contract, memory rules, tone dial, handoffs. |
| 05 Policy and rule engine | Rule DSL, autonomy lattice, hard lines, precedence, versioning, testing, default rule set. |
| 06 Decision pipeline | The mandatory Observe→Record pipeline, receipts, confidence, novelty, blast radius, compensation. |
| 07 Closed-loop risk mitigation | Risk taxonomy with Detect/Contain/Correct/Learn loops, incidents, trust budget, breakers, kill switch. |
| 08 Edge-case catalog | 100+ hard cases across planning, outreach, scheduling, approvals, people, time, data, adversarial, legal. |
| 09 Escalation and human-in-the-loop | Escalation classes, SLAs, safe defaults, quorum, approvals inbox, IC escalation right, overrides. |
| 10 Communication engine rules | Channels, quiet hours, outreach caps, storm prevention, tone dial, candor and grounding rules, templates. |
| 11 Integrations spec | Connector contract, sync model, canonical mappings, write-back, degradation, health scoring. |
| 12 Atoms mode spec | Scheduling solver, shift lifecycle, SMS flows, location health, checklists, voice line, safety path. |
| 13 Security, privacy, compliance | Tenancy, data classes, read boundaries, retention, access, audit log, employment-law guardrails. |
| 14 Evaluation and testing | Simulation orgs, scenario suites, replay, property tests, red team, shadow evaluation, CI gates. |
| 15 Observability and runbooks | SLOs, golden signals, dashboards, alerting, and runbooks for the known failure modes. |
| 16 Rollout and operations | Onboarding flow, listening period, graduation criteria, tenant config, change management, cadence. |
| 17 Data model and API reference | Types, event catalog, endpoints, webhooks, error codes. |
| 18 Glossary and ADRs | Vocabulary and the architecture decision records behind the design. |
Conventions used across the set¶
- IDs. Edge cases are
EC-<DOMAIN>-<nnn>; rules areR-<DOMAIN>-<nnn>; breakers areBRK-<name>; runbooks areRB-<nn>; risks areRISK-<nn>; escalation classes areE0…E5; kill-switch levels areKS-L0…L3. - Autonomy classes are written in caps:
AUTONOMOUS,PROPOSE_CONFIRM,HUMAN_ONLY. Graduation states:SHADOW → PROPOSE → AUTONOMOUS. - Control loops are always written as Detect / Contain / Correct / Learn with an owner and a metric. A control without a Learn step is incomplete by definition.
- Simulation orgs referenced in tests:
chonk-test-co(40-person software company) andchowder-house(3-location restaurant group). Doc 02 also carries fuller worked examples under the names Lanternfish Software and Harbor Table Group; treat those as the same two shapes. - Where sibling docs use slightly different event or action names (e.g.
graduation.advancedvsgraduation.promoted), doc 17's event catalog is the source of truth; a naming reconciliation pass is tracked in the open questions below.
Status¶
All docs are draft v0.1, written 2026-09-03 as the initial build spec. They are deliberately opinionated so that disagreement is concrete: change the doc, not the vocabulary.
Open questions¶
- Reconcile event/action identifiers across docs 03, 05, 07, 09, 15, 16 against doc 17's catalog.
- Decide whether the Owner Console ships as a separate product line (see PRD §16).
- Confirm the override reason codes that carry no trust debit (doc 16 §3.4 vs doc 07).