Skip to content

Compass Engineering Docs

Select theme

Designs
- agent
  - compass-agent-comms-tools
    Compass agent comms tools
  - compass-agent-config-delivery
    Compass agent config-delivery seam — skills / extensions / MCP-server configs / env-vars
  - compass-agent-config-passthrough
    Compass agent config passthrough — fleet OMP config delivery (settings, AGENTS.md, rules, subagent defs, models.yml)
  - Compass agent container runtime — design
  - compass-agent-error-abort-surfacing
    Pre-stream error/abort content surfacing (mapper)
  - compass-agent-forge-tools
    Compass agent forge tools
  - compass-agent-org-mgmt-tools
    Agent org-management tools (RIG-2673)
  - compass-agent-peer-dm
    Compass agent peer-DM — name-addressed comms + auto-created two-way agent↔agent DMs
  - compass-agent-primary-lifecycle
    Agent-primary issue-state write model (amendment)
  - compass-agent-runner-transport
    Compass agent↔Runner call transport
  - compass-agent-session-blobs
    Compass agent session blobs survive resume
  - compass-agent-session-persistence
    Compass agent session persistence: server-owned durable log via tee-emit; resume via a Runner-materialized session file + SDK-native load
  - compass-agent-spawn-despawn
    Compass: agent-facing spawn/despawn of peer agents
  - compass-agent-transport-consolidation
    Compass agent↔Runner transport consolidation
  - compass-agent-trees
    Compass agent trees
  - compass-ask-answer-recovery
    RIG-2257 — Compass ask-answer recovery: answer-as-message
  - compass-ask-comms-roundtrip
    Compass ask round-trip over the comms transport (RIG-1509 redesign)
  - compass-ask-in-channel
    Compass ADE — Ask-in-channel (first-responder-wins)
  - Compass ask typed derivation — the superseding ask contract (Option A)
  - compass-batteries-included
    Compass "batteries included" — the default skill/rule bundle (Dogfood cut)
  - compass-first-turn-delivery
    Compass first-turn delivery — remove `initial_prompt`
  - compass-forks-reversal
    Compass forks reversal — pinned GitHub imports (RIG-2336)
    Compass forks reversal — Open-Question resolutions (RIG-2336)
  - Remove dead `initial_prompt` from the agent-session start path
  - compass-manager-comms-substrate
    Compass Manager comms substrate — roster query, coordination channel, pinned board
  - compass-manager-prompt
    Compass Manager & implementer block-0 prompt + first skills (Dogfood cut)
  - compass-manager-role-taxonomy
    Compass Manager role taxonomy: supervisor / owner / manager + role-on-spawn
  - compass-per-agent-overrides
    Compass per-Manager profiles and in-process subagent topology
  - Resume: bind the transcript base after the Runner accepts
  - compass-spawn-control
    Compass spawn control — start/stop a workstream agent from the Bridge board
  - compass-system-sender-first-turn
    Compass `@compass` system sender + root-supervisor first turn (RIG-1820 case-1)
  - portable-operating-guidance
    Portable operating guidance
    Portable operating guidance migration
  - reload-control-restart
    Reload control restart
  - reload-replay-barrier
    Reload replay barrier
  - runner-session-id-allocation
    Runner session-ID allocation: server-minted fresh IDs (RIG-3696)
- Authoring design records in Compass
- decisions
  - Design decisions
  - agent
    DL-015
    DL-016
    DL-017
    DL-018
    DL-025
    DL-026
    DL-027
    DL-028
    DL-029
    DL-037
    DL-043
    DL-063
    DL-064
    DL-065
    DL-066
    DL-075
    DL-076
    DL-077
    DL-078
    DL-079
    DL-080
    DL-081
    DL-082
    DL-083
    DL-084
    DL-085
    DL-086
    DL-087
    DL-088
    DL-089
    DL-090
    DL-093
    DL-095
    DL-123
    DL-124
    DL-125
    DL-126
    DL-129
    DL-130
    DL-131
    DL-132
    DL-133
    DL-134
    DL-135
    DL-136
    DL-137
    DL-138
    DL-139
    DL-140
    DL-141
    DL-142
    DL-143
    DL-144
    DL-145
    DL-146
    DL-147
    DL-164
    DL-165
    DL-166
    DL-167
    DL-168
    DL-169
    DL-170
    DL-171
    DL-185
    DL-187
    DL-188
    DL-189
    DL-190
    DL-191
    DL-192
    DL-211
    DL-212
    DL-213
    DL-241
    DL-253
    DL-283
    DL-284
    DL-285
    DL-286
    DL-287
    DL-288
    DL-289
    DL-290
    DL-291
    DL-292
    DL-293
    DL-294
    DL-295
    DL-296
    DL-297
    DL-310
    DL-318
    DL-322
    DL-323
    DL-357
    DL-372
    DL-383
    DL-384
    DL-398
    DL-400
    DL-417
    DL-426
    DL-427
    DL-428
    DL-429
  - infra
    DL-257
    DL-258
    DL-259
    DL-260
    DL-261
    DL-262
    DL-263
    DL-277
    DL-278
    DL-279
    DL-280
    DL-298
    DL-299
    DL-300
    DL-301
    DL-311
    DL-312
    DL-313
    DL-314
    DL-315
    DL-316
    DL-317
    DL-325
    DL-326
    DL-331
    DL-332
    DL-333
    DL-334
    DL-335
    DL-336
    DL-337
    DL-366
    DL-368
    DL-369
    DL-378
    DL-379
    DL-380
    DL-381
    DL-382
    DL-385
    DL-386
    DL-387
  - meta
    DL-001
    DL-002
    DL-003
    DL-004
    DL-005
    DL-006
    DL-007
    DL-008
    DL-009
    DL-010
    DL-011
    DL-012
    DL-013
    DL-014
    DL-019
    DL-020
    DL-021
    DL-022
    DL-023
    DL-024
    DL-030
    DL-031
    DL-038
    DL-039
    DL-040
    DL-042
    DL-047
    DL-174
    DL-175
    DL-176
    DL-177
    DL-178
    DL-179
    DL-180
    DL-181
    DL-227
    DL-228
    DL-229
    DL-239
  - observability
    DL-303
  - platform
    DL-329
    DL-330
    DL-338
    DL-358
    DL-440
  - Compass design decisions
  - repo
    DL-413
    DL-414
    DL-415
    DL-439
  - server
    DL-048
    DL-049
    DL-050
    DL-051
    DL-052
    DL-053
    DL-054
    DL-055
    DL-067
    DL-068
    DL-069
    DL-070
    DL-071
    DL-072
    DL-073
    DL-074
    DL-091
    DL-092
    DL-094
    DL-098
    DL-099
    DL-161
    DL-162
    DL-163
    DL-182
    DL-186
    DL-200
    DL-201
    DL-202
    DL-203
    DL-204
    DL-205
    DL-206
    DL-210
    DL-226
    DL-240
    DL-254
    DL-255
    DL-256
    DL-264
    DL-265
    DL-266
    DL-267
    DL-268
    DL-269
    DL-270
    DL-271
    DL-276
    DL-281
    DL-302
    DL-304
    DL-305
    DL-306
    DL-307
    DL-308
    DL-309
    DL-324
    DL-327
    DL-328
    DL-340
    DL-342
    DL-343
    DL-347
    DL-350
    DL-351
    DL-352
    DL-353
    DL-354
    DL-355
    DL-356
    DL-360
    DL-361
    DL-362
    DL-363
    DL-364
    DL-365
    DL-370
    DL-371
    DL-375
    DL-376
    DL-377
    DL-392
    DL-393
    DL-394
    DL-395
    DL-396
    DL-408
    DL-410
    DL-411
    DL-412
  - ui
    DL-032
    DL-033
    DL-034
    DL-035
    DL-036
    DL-041
    DL-044
    DL-096
    DL-097
    DL-106
    DL-107
    DL-108
    DL-109
    DL-110
    DL-111
    DL-112
    DL-113
    DL-127
    DL-128
    DL-148
    DL-149
    DL-150
    DL-151
    DL-152
    DL-153
    DL-154
    DL-155
    DL-156
    DL-157
    DL-158
    DL-159
    DL-160
    DL-183
    DL-184
    DL-193
    DL-194
    DL-195
    DL-196
    DL-197
    DL-198
    DL-199
    DL-207
    DL-208
    DL-209
    DL-214
    DL-215
    DL-216
    DL-217
    DL-218
    DL-219
    DL-220
    DL-221
    DL-222
    DL-223
    DL-224
    DL-225
    DL-230
    DL-231
    DL-232
    DL-233
    DL-234
    DL-235
    DL-236
    DL-237
    DL-238
    DL-245
    DL-246
    DL-247
    DL-248
    DL-249
    DL-250
    DL-251
    DL-252
    DL-272
    DL-273
    DL-274
    DL-275
    DL-282
    DL-319
    DL-320
    DL-321
    DL-341
    DL-344
    DL-345
    DL-346
    DL-348
    DL-349
    DL-367
    DL-388
    DL-389
    DL-390
    DL-391
    DL-397
    DL-399
    DL-406
    DL-409
    DL-416
- infra
  - ci
    compass-agent-arm64-image
    Publish the compass-agent image for linux/arm64
    compass-agent-image-publish
    Publish the compass-agent image to GHCR
    compass-ci-check-naming
    Compass CI check naming — the check-name convention, and suppressing the no-op `edited` phantom run
    compass-ci-job-decomposition
    Compass CI job decomposition — dissolving the one-job gate
    compass-devenv-source-dry
    RIG-2546 — compass devenv source unify + CI devenv-CLI DRY
    compass-dogfood-e2e
    Compass dogfood e2e harness — full-stack scenario testing (RIG-1681)
    compass-dogfood-e2e-steer-deliver-seam
    Compass dogfood e2e — steer/deliver split observation seam
    compass-dogfood-loop
    Compass dogfood loop
    compass-e2e-mention-split-observation
    Design: E2E observation seam for the mention steer/deliver split (RIG-1788 / H4)
    compass-local-dev
    Compass local dev: UI in `devenv up`, macOS full setup, gate hazard
    compass-pr-validation
    Compass PR validation — agent-self-tested coverage, evidence on the PR
    compass-test-harness-tiers
    Consolidate the Go test-harness tiers (RIG-2742)
  - release
    compass-distribution
    Compass distribution & install surface
    compass-gateway-image
    Compass gateway image publish lane
    compass-release-bundling
    Bundle nix outputs, images, and binaries as GitHub Releases
    compass-unified-release-lane
    Compass unified release lane (release-please + folded image publishing)
  - runtime
    compass-elastic-session-runtime
    Compass hosted agent platform — the elastic session runtime (end-state)
    microVM CI + Dev Enablement
    Elastic session runtime — amendment: microVM is KVM-only, no degrade-to-container
    microVM Runner Backend
    Elastic session runtime — amendment: microVM KVM-only carved out for self-host single-tenant
    microVM Runner V2a — Guest Image + Boot Spike
    microVM Runner V2b — in-guest supervisor + vsock exec control plane
    microVM Runner V3 — egress-in-guest
    microVM Runner V4 — AgentGateway over host-side vsock
    microVM Runner V5 — preflight, boot canary, hard-fail startup gate
    microVM Runner V7 — teardown, crash recovery, observability
    microVM Runner V8 — isolation / contract / failure-mode acceptance suite + benchmarks
    P2 — Persistent Session Volume + VirtualFS Seam
    P2 — VFS reap/lock hardening: atomic rename-then-delete reap, ctx-interruptible lock acquisition, orphan lock reclaim
    Elastic session runtime — amendment: `VirtualFS` descoped from S1 to P2
    Why a coding agent doesn't split into a brain and hands
    compass-guest-image-artifact
    Compass guest image artifact
    compass-host-runtime-tier
    Compass host runtime tier
    compass-managed-delivery-cutover
    Design: Compass T3 delivery→EventFabric cutover (RIG-3107)
    compass-managed-multitenancy
    Compass multi-tenancy and NATS eventing substrate
    compass-managed-settle-turn-order
    Design: Order held delivery by turn sequence (RIG-4033)
    compass-runner-adoption-strategy
    Compass self-host runner topology and adoption strategy
    compass-runner-arbitrary-uid
    Design: compass-runner arbitrary host uid support
    compass-runner-concurrent-dispatch
    Design: Runner concurrent per-command Sessions dispatch
    compass-runner-gateway-error-sentinels
    Design: Runner gateway/operator-fault error sentinels
    compass-runnerhub-send-queue
    Design: Server runnerhub — per-router bounded send queue (non-blocking dispatch)
- meta
  - compass-architecture-lineage
    Compass architecture lineage
  - compass-design-ledger
    Compass design-decision ledger
  - compass-test-strategy
    Compass full-system test strategy
  - compass-tier3-scope-gate
    Design: Scope-aware tier-3 command dispatch (RIG-2529)
  - oss-core-managed-boundary
    The OSS-core / managed-service boundary
- observability
  - compass-agent-loop-otel
    Deployer contract — compass-agent whole-agent telemetry
    Design: Activate OMP's native loop OpenTelemetry in compass-agent
  - compass-agent-message-trace-continuity
    Design: End-to-end trace continuity — inbound message → turn → tool calls
  - compass-observability-architecture
    Compass observability & in-product data architecture
  - compass-server-runner-otel
    Design: compass-server + compass-runner OTel emission and end-to-end trace continuity (T4b, RIG-2685)
- platform
  - apple-container-macos-runner
    Apple `container` as an embedded-macOS runner backend
    T-1 spike findings — apple `container` on real hardware
    Apple `container` macOS runner — amendment: transport slow-rolled, macOS ships podman
  - compass-runner-containerization
    Containerizing the Compass Runner
    Privilege-shape spike findings
  - compass-runner-workload-identity
    Runner authentication from Kubernetes workload identity
  - compass-stable-name-routing
    Compass stable-name provider routing (RIG-2845)
  - compass-stack-supervision
    Compass self-host stack supervision: constant-on cross-platform service
- repo
  - compass-agent-effect-adoption
    Design: Adopt Effect on the compass agent-runner transport
  - compass-agent-effect-otel
    Design: Adopt `@effect/opentelemetry` for compass-agent transport observability
    OTel endpoint: deployer contract
  - compass-design-docs-reorg
    Design: reorganize `docs/designs/`
  - Drop proto: devenv/nix as the single toolchain owner
  - Decision: adopt Effect on the compass agent-runner
  - compass-eng-docs
    Compass engineering docs site
  - compass-nilaway-gating
    Nilaway: advisory → gating
  - compass-renovate-go-analysis-pins
    Renovate-manage the Go analysis battery pins (RIG-3306)
  - Compass: migrate Dependabot → self-hosted Renovate in GitHub Actions
  - compass-renovate-relock-fail-closed
    Fail-closed Renovate relock for the devenv locks (RIG-3253)
  - compass-shared-nix-tooling
    Reconcile the shared Nix toolchain builder (RIG-4540)
  - compass-shared-tools-repo
    Share repo tools from one public repo (RIG-4351)
- server
  - compass-attribution-simplification
    Compass attribution simplification — attribution is a display fact
  - compass-comms-multi-actor-test-coverage
    Multi-actor test coverage for the Compass comms surface (RIG-3473)
  - compass-forge-agent-notification
    Compass forge agent-notification (RIG-2732 Pieces 2 + 3) — webhook-only
  - compass-forge-agent-server-e2e
    Design: Tier-2 forge e2e leg, agent to server (RIG-3823)
  - compass-forge-app-credentials
    Compass forge App-credential cutover (GitHub + Linear)
  - compass-forge-board-webhook-ingestion
    Compass board ingestion: forge poll → webhooks (App-only credential cutover)
  - compass-forge-integration-testing
    Compass forge integration testing
  - compass-forge-poll-driver
    Compass forge-poll driver (RIG-1810)
  - Design: Forge retry-after surface (RIG-2255)
  - compass-forge-scope-enforcement
    Design: Forge scope enforcement (A8, Beta tier)
  - compass-forge-self-delegate
    Design: Forge self-delegate write path (Record A)
  - compass-forge-self-delegate-suppression
    Design: Forge self-origin notification suppression
  - compass-forge-state-transition
    Design: Forge state-transition write op (RIG-3331)
  - compass-forge-write-path
    Compass forge write path
  - gateway_credentials at-rest encryption + master-key custody
  - compass-gateway-oauth-enrollment
    User OAuth login / credential enrollment for the Compass LLM gateway (RIG-3050)
  - compass-handle-addressing-cutover
    Design: Contract-wide id→handle cutover for compass request fields (RIG-2751)
  - compass-issue-model
    Compass Issue model
  - compass-issue-model-pr-linkage-amendment
    Compass issue model — amendment: link pull requests to issues
  - compass-linear-agent-responder
    Compass Linear Agent Session responder
  - compass-linear-return-path-indirection-amendment
    Compass Linear return path — amendment: server-resolved indirection link
  - compass-linear-webhook-mount-amendment
    Compass Linear webhook mount — amendment: provider-suffixed path, mount owned by the forge notification lane
  - Compass mention delivery for offline channel members — wake-based redelivery amendment
  - RIG-2490 — Close the pre-settle mention-loss window (sibling to RIG-1641)
  - compass-notification-delivery
    Compass notification delivery — the server-side push into the agent's session
  - compass-owner-peering
    Owner peering: cross-user agent-comms authorization
  - compass-server-llm-gateway
    Compass Server LLM Gateway (RIG-1715)
  - compass-server-ownership-layer
    Server as the ownership layer
  - compass-server-ownership-layer-amendment
    Compass server ownership layer — amendment: one canonical type family
  - Design addendum: Service subject principal (`SubjectService = 2`)
  - compass-sqlc-adoption
    Compass sqlc adoption — typed queries from SQL, and the inline-SQL ban
  - Compass user-secret store (Postgres, encrypted at rest)
  - compass-zulip-threading-model
    Compass: Zulip threading model
- ui
  - compass-ade-shell
    Compass ADE shell — Orca-mirror UI + a real, tracker-mapped state model
  - compass-ask-free-text
    Always-explicit ask submission + free-text (`custom_text`) answers (RIG-1330)
  - compass-badge-clarity
    Compass badge clarity (RIG-2117)
  - compass-board-view
    Compass board: Issues/PRs tabs, cross-linking, PR-card badges
  - compass-bridge-keyboard-nav
    Design: Compass Bridge keyboard navigation — 2-D roving-tabindex grid + empty-board state (RIG-2130)
  - compass-bridge-reclothe
    Design: Compass Bridge re-clothe (RIG-2111)
  - compass-channels-in-agent-tree
    Compass channels in the agent tree
  - compass-coaching-tooltips
    Compass coaching keyboard-discoverability tooltips (RIG-2530)
  - compass-command-palette
    Compass command palette (Cmd/Ctrl+K) + shortcut chips at point-of-use (RIG-2483)
  - compass-dev-boot-gate
    Compass UI dev-boot smoke gate (RIG-1536)
  - compass-dock-in-sidebar
    Compass ADE shell — fold the bottom dock into the right sidebar
  - compass-ds-token-cutover
    Design: Compass DS Token Full Cutover + Canvas Migration
  - compass-first-run-tour
    Compass native first-run product tour (RIG-2797)
  - compass-global-search
    Compass global search — top-bar search over agents / PRs / issues / chats
  - compass-glyph-primitives
    Compass glyph primitives (RIG-3603)
  - compass-gtk4-migration
    Design: Compass native shell GTK4 / webkitgtk-6.0 migration (RIG-1770)
  - compass-in-window-tabs
    Design: In-Window Tabs and Split Views
  - compass-keyboard-shortcuts-overlay
    Design: Searchable `?` Keyboard-Shortcuts Overlay (RIG-2482)
  - compass-keyboard-spine-app-root
    Compass keyboard spine at the App root (RIG-2456)
  - compass-leader-chords
    Design: Leader/Mnemonic Keyboard Chords, Focus-Context-Gated (RIG-2484)
  - compass-live-roster
    Compass Live Roster — the agent tree reads the live roster (RIG-2033)
  - compass-message-surface-rendering
    Compass message surface — virtualized thread list + streaming markdown (RIG-1332)
  - compass-multi-window
    Compass Native App — Multi-Window Support
  - compass-native-app
    Compass native app — embedded vs remote architecture
  - compass-native-client-mode
    Compass-native T5 — native-client mode end to end (RIG-1686)
  - compass-native-client-only
    Compass native app — client-only (retire embedded mode)
  - compass-native-embedded-revival
    Compass native app — embedded-mode revival (dual-mode returns; client mode survives)
  - compass-native-packaging
    Compass native app — packaging + CI baseline (T6)
  - compass-native-server-url-entry
    Compass native: server URL entry from the UI
  - compass-outbound-session-header
    Outbound `X-POSTHOG-SESSION-ID` interceptor + boot reorder (RIG-2874 slice 2)
  - Compass session-trace DiffBlock: real line diff (RIG-1350)
  - compass-shell-routing
    Compass shell routing (@solidjs/router adoption)
  - compass-sidebar-pins
    Compass configurable sidebar pins
  - compass-sidebar-pins-unreachable-amendment
    Compass sidebar pins — unreachable-pin amendment
  - Compass Slack-model thread rendering (RIG-1352)
  - compass-stack-cross-process-teardown
    Cross-process teardown for the embedded native-app stack
  - Compass Tauri desktop shell — design
  - compass-threading-ui
    Compass Threading UI — Slack-style threads in the channel surface
  - compass-ui-fixture-boot
    Compass UI fixture boot — fully offline, fixture-seeded UI
  - compass-ui-markdown-react10
    Adopt react-markdown-10 rewrite (solid-markdown #44 + #45) into @rigelbuild/solid-markdown
  - compass-ui-query-layer
    Compass UI query layer (@tanstack/solid-query + connect-query-core adoption)
  - compass-ui-solid-v2
    Solid v2 migration — compass apps/ui (RIG-2187)
  - compass-ux-foundation
    Compass UX foundation — target design system + interaction model
  - Visual regression: local baseline captures
  - compass-visual-regression-gate
    Design: Compass automated visual-regression gate (RIG-2154)
Specs
Architecture
- Build & CI
Packages
- app-bundle
  - Compass packaged-app smoke
- apps-ui
  - src
    design
    Compass component visual contracts (D3)
    Editor theme (D8)
    Compass motion primitives (D9)
    Compass surface composition specs (D6)
- Changelog
- config
  - rules
    Compact often
    Delegate within the management tree
    Design first
    Evidence and safe tool arguments
    Hold your lane
    Never block — stay reachable
    Never merge — the operator holds the gate
    One investigator per shared failure
    Own your issue's state
    Red → Green (tests fail BEFORE the fix)
  - skills
    ci-failure-triage
    CI failure triage
    comms-playbook
    Comms playbook
    compass-setup
    Compass workspace setup
    design
    Lean design
    infrastructure-as-code
    Infrastructure as code
    jj
    Jujutsu (`jj`) + stacked PRs on Compass
    management-trees
    Management trees
    manager-coordination-channel
    Manager coordination channel
    review
    Code review
    supervisor-channel
    Supervisor channel discipline
- dashboards
  - Compass Observability — Grafana Dashboards
- docs
- go
  - AGENTS.md (go/)
  - internal
    fabric
    Fabric subjects and JetStream configuration
- packages
  - compass-agent
    compass-agent — package contract
- tools
  - agent-image-env-gate
    agent-image-env-gate
  - agent-image-index
    agent-image-index
  - biome-plugins
    biome-plugins
  - ci-matrix
    ci-matrix
  - compass-app-dev
    compass-app-dev
  - cx-token-gate
    cx-token-gate
  - design-ledger-gate
    design-ledger-gate
  - dl-claim
    dl-claim
  - dl-reconcile
    dl-reconcile
  - flake-gate
    flake-gate
  - font-coverage-gate
    font-coverage-gate
  - forge-linear-token
    forge-linear-token
  - gateway-image
    gateway-image
  - guest-image
    guest-image
  - inline-sql-gate
    inline-sql-gate
  - macos-bundle
    macos-bundle
  - microvm-boot-test
    microvm-boot-test
  - operator-cli-check
    operator-cli-check
  - orion-ref-gate
    orion-ref-gate
  - release-notes
    release-notes
  - renovate
    renovate
  - renovate-preflight
    renovate-preflight
  - runner-image
    runner-image
  - sea-ref-gate
    sea-ref-gate
  - sql-migration-gate
    sql-migration-gate
  - stamp-gate
    stamp-gate
  - toolchain
    devenv-cli
    devenv-cli
    toolchain
Contributing

Select theme

On this page

Overview

On this page

Overview

DL-004

Adopt Cotal as the coordination substrate behind a thin Compass-owned seam

Status: Superseded by DL-005 (Matt, 2026-07-04)

Record: ../../meta/compass-architecture-lineage/design.md

Previous
DL-003 Next
DL-005