# Architecture decision records

One record per decision, numbered in the order decisions were accepted.

| ADR | Title | Status | Date |
| --- | --- | --- | --- |
| [0001](https://codingowl.dev/docs/decisions/0001-single-owl-binary) | Single `owl` binary for everything headless | Accepted | 2026-09-09 |
| [0002](https://codingowl.dev/docs/decisions/0002-daemon-never-self-daemonizes) | The daemon never self-daemonizes | Accepted | 2026-09-09 |
| [0003](https://codingowl.dev/docs/decisions/0003-monorepo-single-go-module) | Monorepo with a single Go module | Accepted | 2026-09-09 |
| [0004](https://codingowl.dev/docs/decisions/0004-connectrpc-over-unix-socket) | ConnectRPC over a unix socket | Accepted | 2026-09-09 |
| [0005](https://codingowl.dev/docs/decisions/0005-internal-plugins-as-go-interfaces) | Plugins are Go interfaces, not external processes | Accepted | 2026-09-09 |
| [0006](https://codingowl.dev/docs/decisions/0006-host-execution-for-mvp) | MVP agents run as host processes, not containers | Accepted | 2026-09-09 |
| [0007](https://codingowl.dev/docs/decisions/0007-worktree-and-branch-per-job) | One git worktree and one branch per Job | Accepted | 2026-09-09 |
| [0008](https://codingowl.dev/docs/decisions/0008-sqlite-queue-behind-source-interface) | Work queue is local SQLite behind a `Source` interface | Accepted | 2026-09-09 |
| [0009](https://codingowl.dev/docs/decisions/0009-wails-react-desktop) | Desktop app is Wails with a React frontend | Accepted | 2026-09-09 |
| [0010](https://codingowl.dev/docs/decisions/0010-homebrew-formula-and-cask-naming) | Homebrew ships a `coding-owl` formula and a `coding-owl-desktop` cask | Accepted | 2026-09-09 |
| [0011](https://codingowl.dev/docs/decisions/0011-idle-policy-and-interruption) | Idle policy and interruption semantics | Accepted | 2026-09-09 |
| [0012](https://codingowl.dev/docs/decisions/0012-owl-owns-process-claude-owns-conversation) | Coding Owl owns the process, Claude Code owns the conversation | Accepted; the conversation-reuse half is superseded by ADR-0026 | 2026-09-09 |
| [0013](https://codingowl.dev/docs/decisions/0013-verification-gates-completion) | Verification gates Job completion, and does not retry | Accepted | 2026-09-09 |
| [0014](https://codingowl.dev/docs/decisions/0014-configuration-and-filesystem-layout) | Configuration discovery and filesystem layout | Accepted | 2026-09-09 |
| [0015](https://codingowl.dev/docs/decisions/0015-job-disposal-and-garbage-collection) | Job disposal and worktree garbage collection | Accepted | 2026-09-09 |
| [0016](https://codingowl.dev/docs/decisions/0016-rebase-job-branch-each-run) | Rebase the Job branch onto its base at the start of every Run | Accepted | 2026-09-09 |
| [0017](https://codingowl.dev/docs/decisions/0017-unattended-contract) | Owl appends a standing unattended contract to every Run | Accepted | 2026-09-09 |
| [0018](https://codingowl.dev/docs/decisions/0018-driver-and-executor-axes) | Driver and Executor are separate plugin axes | Accepted | 2026-09-09 |
| [0019](https://codingowl.dev/docs/decisions/0019-accounts) | Accounts are first-class, with isolated tool configuration | Accepted | 2026-09-09 |
| [0020](https://codingowl.dev/docs/decisions/0020-account-utilization-ceiling) | Scheduling respects a per-Account utilization ceiling | Accepted | 2026-09-09 |
| [0021](https://codingowl.dev/docs/decisions/0021-concurrency-caps) | Concurrency is capped globally, per Project and per Account | Accepted | 2026-09-09 |
| [0022](https://codingowl.dev/docs/decisions/0022-desktop-chat) | Desktop chat is a daemon service with consent-gated, shell-free commands | Accepted | 2026-09-09 |
| [0023](https://codingowl.dev/docs/decisions/0023-job-account-binding) | A Job runs on its Project's Account | Accepted | 2026-09-09 |
| [0024](https://codingowl.dev/docs/decisions/0024-skills-declared-per-project) | Skills are declared per Project and managed by Owl | Accepted | 2026-09-09 |
| [0025](https://codingowl.dev/docs/decisions/0025-queue-order-and-job-ttl) | Queue order and Job attempt limits | Accepted | 2026-09-09 |
| [0026](https://codingowl.dev/docs/decisions/0026-phases-and-handoff-continuity) | Plan then execute, each Run in a fresh context, continuity by handoff document | Accepted | 2026-09-09 |
| [0027](https://codingowl.dev/docs/decisions/0027-job-and-run) | A Job is a standing intent; a Run is one attempt at it | Accepted | 2026-09-09 |
| [0028](https://codingowl.dev/docs/decisions/0028-model-and-effort-selection) | Model and effort are chosen per phase | Accepted | 2026-09-09 |
| [0029](https://codingowl.dev/docs/decisions/0029-build-order) | The core loop ships first; features land across daemon and Desktop together | Accepted | 2026-09-09 |
| [0030](https://codingowl.dev/docs/decisions/0030-verification-check-specification) | Verification checks are shell commands with optional expectations | Accepted | 2026-09-09 |
| [0031](https://codingowl.dev/docs/decisions/0031-project-identity) | A Project is identified by a name, not by its path | Accepted | 2026-09-09 |
| [0032](https://codingowl.dev/docs/decisions/0032-source-idempotency) | Every Job carries a Source reference, and producing is an upsert | Accepted | 2026-09-09 |
| [0033](https://codingowl.dev/docs/decisions/0033-skill-fetching-and-placement) | Skills are fetched natively in Go and placed per Driver | Accepted | 2026-09-09 |
| [0034](https://codingowl.dev/docs/decisions/0034-sigkill-after-sigterm) | An Agent that will not stop when it is asked is killed | Accepted | 2026-09-11 |
| [0035](https://codingowl.dev/docs/decisions/0035-agent-permissions-allowlist) | An unattended Agent is granted a default allowlist, once, per Account | Accepted | 2026-09-14 |
| [0036](https://codingowl.dev/docs/decisions/0036-per-run-limits) | Every Run is bounded by a timeout and a stall limit | Accepted | 2026-09-17 |
| [0037](https://codingowl.dev/docs/decisions/0037-account-standing-instructions) | An Account carries standing instructions, kept as the tool's own file | Accepted | 2026-09-17 |
| [0038](https://codingowl.dev/docs/decisions/0038-shifts) | A Shift lets Owl work on an Account while the machine is in use | Accepted | 2026-09-19 |
| [0039](https://codingowl.dev/docs/decisions/0039-focus) | Each Account may have one Focus, a Project whose Jobs go first | Accepted | 2026-09-19 |