Documentation menu

Architecture Decision Records

The decisions that shaped skep, in order. Each ADR records the question it answered (the Q/G/D codes trace back to the original design review) and the version that landed it.

New ADRs and plans start from the invariants — the traits no change may trade away (Part I, with the review checklist) and the refinement backlog (Part II). Cite the invariant numbers a decision touches.

ADR Decision
0001 The contract owns itself (Q2-A)
0002 Worktree + patch artifact; applying the patch is the approval (Q5-A)
0003 Store carve-out boundary (Q6-A)
0004 Licensing (G1)
0005 Worker runs inside a macOS Seatbelt sandbox (Q1-A, v2)
0006 Supervisor-side re-verification (G10, v2)
0007 Auto-approval policy rules (D3, v2)
0008 True suspend/resume of pending_approval (Q8, v2)
0009 Usage accounting (G8, v2)
0010 Storage gate: SQLite-WAL single writer (G4, v3)
0011 Network domain-allowlist enforcement via a loopback proxy (D1, v3)
0012 Recurring schedules: cron drives a stateless tick (v3)
0013 D3 auto-approval goes active; the U1 acceptance demo (v3)
0014 Containerized worker isolation for Linux portability (Q1-B/G3, v3)
0015 Workflow templates: a filled template is just a normal task (v3.5)
0016 Learned skills: a generated template, gated into the same registry (v4)
0017 skep serve: the API daemon, the ticker, and mutable config (v5)
0018 The box: container packaging and the Linux sandbox posture (v5)
0019 LLM chat in the Queen: the voice, and the gated hands (v6)
0020 Notes & Tasks gating line (v7 Stage B)
0021 Interactive browser automation: deferred, with named triggers (v37-F5)
0022 Policy-first: one schema, two vocabularies, govern-via-MCP (v40, executing v36)
0023 Queen-side file reads as a policy-governed tool surface (v51-F2)
0024 Inline code execution as a governed script worker (v51-F3)
0025 Batch dispatch as N independent governed runs (v51-F5)
0026 Operator-policy resolution: the Queen's standing policy (v52)
0027 Chat context injection: memory and the skill index (v53-F2/F7)
0028 Profile-level persona: persona.md (v53-F4)
0029 Conversation-authored skills: observer + curator (v53-F1)
0030 Cron context chaining (v53-F5)
0031 Voice as a channel-layer capability (v53-F6)
0032 Card auto-deny on timeout (v54-F1)
0033 Human-readable confirmation cards (v54-F3)
0034 Multi-run PR grouping (v54-F4)
0035 Repo freshness is managed by the supervisor (v55-F1/F2)
0036 Per-project policy copy (v55-F4)
0037 Chat context: explicit window, budgeted replay, compaction (v56-F1/F2/F3)
0038 Approvals announce themselves (v56-F5/F6/F7)
0039 The Queen's git surface: reads free, mutations carded (v57)
0040 Bounded reactive worker execution — the act–observe loop (R2, v69)
0041 Reasoning-only delegation: delegate_analysis, cap 3 (v83-F7)
0042 Prompt schedules: read-only, store-reads-only Queen turns (v83-F5)
0043 Seed skills and the zero-grant rule (v83-F12/F13)
0044 Outbound content: verbatim cards, never-grantable prefixes (v84-F4)
0045 External shelves and the skill-pack ladder (v85)
0046 Session approval tier for the worker shell gate (v86)
0047 CLI-agent engines and where their authority boundary is (v90)
0048 Policy groups: reusable convenience grants, live-composed (v97)
0049 The caste roster is a registry, not five dict literals (v101)
0050 One verb, three faces: the operator's surface is never the narrow half (v104)
0051 The provider shelf: presets, per-profile keys, no borrowed identity (v108)
0059 Policy v3: one decide(), layer-aware ceilings, scoped grants (edge sweep; P3-1 implemented)
0060 Serve re-adopts a live worker after a restart (edge sweep D2)
0061 Unlocked mode on policy v3: a zero-ask project as one step inside decide()
0062 The provider-key relay: the worker never holds the provider key (V6b; behind a kill switch, default off)
0063 The Queen on a ChatGPT plan: the Codex login as a provider credential, Queen only (v118)
0066 New projects run sandboxed when the host can sandbox; stored modes are carried forward (v127-F8)
0067 A channel admin named at the desk confirms every card from the messenger, HIGH ones included (v130-F5)