Skip to content

Agent Decision Records

This directory contains the Agent Decision Records (ADRs) for Claude Code Configuration, under the adr/v1 contract. A record's kind says what it holds: a decision, a spec kept current, or evidence (findings, surveys, explorations).

Record Format

  • Kind: decision / spec / evidence, as adr.yaml declares
  • Status: proposed / accepted / rejected / abandoned / superseded / archived
  • Capability: what the record is about, from the vocabulary in adr.yaml
  • Decisions also carry a verb (add / cut / change / retire / constrain), a basis, and open with a Summary
  • Numbers are permanent; a record's folder is its area

This index is auto-generated by adr index. Configuration: adr.yaml

Ways

The ways engine: how ways are matched, disclosed and re-disclosed

ADR Title Status
ADR-004 Way Macros for Dynamic Context Injection accepted
ADR-014 TF-IDF/BM25 Binary for Semantic Way Matching accepted
ADR-103 Checks — Epoch-Distance-Aware Confidence Sensors for Ways accepted
ADR-104 Token-Gated Way Re-Disclosure for Long Context Windows superseded (superseded by ADR-123)
ADR-105 Progressive Disclosure for Way Trees accepted
ADR-107 Corpus, Matching Pipeline, and Locale Support accepted (partially superseded by ADR-125)
ADR-108 Embedding-Based Way Matching with all-MiniLM-L6-v2 accepted
ADR-114 attend Events as an Insistent Way Trigger Type accepted
ADR-123 Firing dynamics — progression-axis unification for attend and ways accepted
ADR-125 Authored Disclosure Graph and Removal of BM25 accepted
ADR-126 Window-relative refire with named presets accepted
ADR-127 Full-body embedding corpus for way matching rejected
ADR-130 Sentence-salience input reduction for embed matching accepted
ADR-134 Empirical auto-tuning from fire and near-miss telemetry accepted
ADR-135 Content-aware write-time over-build gate with a self-extending pattern corpus accepted
ADR-139 Shelve maintainer i18n; adopter-run localization via ways-localize accepted
ADR-153 Session-introspection substrate — correlating fired ways to turns accepted
ADR-154 ways introspect — one model, three front-ends accepted
ADR-155 Semantic gating of the keyword channel and reasoning-channel rebuild accepted (partially superseded by ADR-188 §3)
ADR-156 Calibrated relevance scoring for the semantic lane accepted
ADR-157 Case-insensitive trigger regex compilation accepted
ADR-158 Calibration boundary quality — hard negatives and a fire-breadth ship gate accepted
ADR-159 Remove ways tune-curves and the legacy curve: cadence field accepted
ADR-160 Chunked late-interaction matching with softmax-share gating for way selection accepted
ADR-161 Queued mid-turn operator messages as an aggregated scan surface accepted
ADR-166 Single source of truth for model context-window resolution accepted
ADR-174 Progressive core — decoration guidance and the core re-disclosure gap accepted
ADR-183 Single-language localization tuning: the English anchor as a peer accepted
ADR-188 One tool-call lane keyed by tool type, and a Bash surface that is parsed, described and judged proposed
ADR-189 Session introspection implementation plan accepted
ADR-190 The lexical gate as a conditional threshold accepted
ADR-191 The tool-use channel is a signal problem: lookbehind, chunk-spread, and winner confirmation accepted
ADR-192 Late-interaction matching: the flow accepted
ADR-193 Cross-encoder rerank gate in a resident daemon for way injection abandoned
ADR-194 Per-injection ratings and continual local tuning of the way gate abandoned
ADR-195 Evidence: a yes/no relevance judge over live way fires accepted
ADR-196 A yes/no relevance gate on way injection, judged by a hosted model accepted
ADR-197 Cap the candidates the relevance gate judges per request accepted
ADR-198 Uninstall is a lifecycle command that keeps what the operator owns accepted
ADR-199 Ways sensors dispatch session activity to external consumers, async under a watchdog proposed

Governance

Provenance, traceability, controls, compliance mapping

ADR Title Status
ADR-005 Governance Traceability for Ways superseded (superseded by ADR-200)
ADR-151 Extract ways-core crate and ways-audit sibling binary accepted
ADR-200 Compliance claims and session-derived findings accepted
ADR-201 Findings assembled as classifier-ready assessment records accepted
ADR-202 License agent-ways under AGPL-3.0-or-later accepted

Documentation

Documentation structure, tooling, coherence

ADR Title Status
ADR-106 Project Pulse — Epoch-Mapped Project Awareness accepted
ADR-177 Version-stamped vendored tools with direction-aware drift detection accepted
ADR-300 Documentation Structure accepted
ADR-301 Situated socialization as canonical framing and documentation prose refactor accepted
ADR-302 A unified documentation model — typed graph, ways packaging, cross-repo convergence accepted
ADR-303 Active-set semantics, adr archive, and supersession reading for the ADR corpus accepted
ADR-304 Typed decision records: the adr/v1 contract Accepted
ADR-305 Capabilities active at adoption need no add decision superseded (superseded by ADR-311)
ADR-306 adr import: foreign records through a round-trip import sheet accepted
ADR-307 A decision names what should be observable when it holds accepted
ADR-308 A change decision may list several capabilities accepted
ADR-309 An evidence record kind for findings, surveys and explorations accepted
ADR-310 Record numbers are permanent identity, and records live by intent accepted
ADR-311 The adr tool checks shape and references; git keeps the history accepted
ADR-312 Seed the capability vocabulary from domains; ship process and adr accepted
ADR-313 An accepted record is edited in place where that keeps it correct, with a dated note where an edit changes a decision accepted
ADR-314 A citation ends what it supports, and text that ships carries none accepted

Attend

Session awareness: sensors, peers, messaging, keepwarm

ADR Title Status
ADR-101 Wormhole relay protocol for cross-instance agent communication superseded (superseded by ADR-113)
ADR-102 IRC-based local agent communication superseded (superseded by ADR-113)
ADR-113 attend — Active Awareness Module accepted
ADR-117 Sensor Crate Extraction and Feature Flags accepted
ADR-118 Focus Groups — Dynamic Agent Grouping accepted
ADR-119 Action Potential Engagement Model superseded (superseded by ADR-123)
ADR-120 Interactive Chat TUI — Human in the Signal Loop accepted
ADR-121 Salience decay for signal presentation — turn-based exponential superseded (superseded by ADR-123)
ADR-122 Attend disclosure sensor — token-gated affordance reheat accepted
ADR-124 TUI Legend Architecture — Base Channel, Liveness, and Ordering accepted
ADR-129 Instance suffix and heartbeat liveness for attend identity accepted
ADR-136 Split addressed messaging from the sensor-observation bus accepted
ADR-137 Boundedness — a unit of work must be bounded within its cycle accepted
ADR-170 Human focus-group membership via username identity and a shared attend-groups crate accepted
ADR-171 Stable session identity — the roster enumerates addressable coordinating units accepted
ADR-172 Turn-boundary inbound delivery via a CLI-owned drain checkpoint accepted
ADR-173 Chat-idiom convergence for the attend command surfaces accepted
ADR-182 Keepwarm: attend keeps the prompt cache warm with a wake floor accepted
ADR-187 Attend MCP server mode: outbound and queries as typed tools, inbound stays on Monitor and the Stop hook abandoned
ADR-400 Attend messaging disclosure with token-gated reheat accepted
ADR-401 Attend envelope fields: sender kind, principal, and addressee on every signal accepted
ADR-402 Claude Code channels deliver MCP server events into the model's turn and wake an idle session accepted
ADR-403 Attend hosts sensors under one spec: compiled, command and MCP sensors in YAML files accepted
ADR-404 Channel membership and history are managed by any member, with scopes, seals and an operator view accepted
ADR-405 One click on a channel selects it and opens its menu, and the chat's left column lists agents and channels accepted
ADR-406 attend reaches agents through a Claude Code mod that agent-ways installs: dormant by default, one status row, transport stays the signal store accepted
ADR-407 A click on a channel shows it and a second click opens its menu, which docks under its row, and the chat starts with the mouse on accepted
ADR-408 A question on the chat's bar is answered by a click as by a key, and one rule closes every overlay accepted
ADR-409 Esc in the chat never quits, and the compose box is for chatting: names and descriptions are typed in an entry dialog accepted
ADR-410 A chat message opens with one header band in the sender's colour across the feed, a rule under it, and the body at full width accepted
ADR-411 A session that listened comes back listening when its session id is resumed accepted
ADR-412 One message is one signal, and no conduit splits it accepted
ADR-413 Attend's CLI groups its verbs by noun; the mod's tools are the principal reply path accepted
ADR-414 The attend mod keeps an idle session warm for a bounded stretch after the operator's last prompt, then asks for a wrap and lets the cache lapse, while autocompact is off accepted
ADR-415 A session event record, written by the ways hooks to a per-session spool and read by attend, ways sensors and sensor conditions proposed

Platform

Install, update, configuration, permissions, the CLI contract, testing

ADR Title Status
ADR-111 Unified ways CLI — Single Binary Tool Consolidation accepted
ADR-115 Declarative Configuration with Project-Scope Overlay accepted
ADR-116 Declarative Permission Requirements accepted
ADR-131 Project-scope way toggles accepted
ADR-140 Two install topologies: in-place repo and subdirectory projection accepted
ADR-142 agent-ways 1.0 — XDG application distribution accepted
ADR-144 Install / repair / migrate as one manifest reconciler accepted
ADR-146 installer binary verification and guided build fallback accepted
ADR-147 Composable settings.json — a store of YAML config fragments superseded (superseded by ADR-169)
ADR-148 framework surface ships operator content; dev harness in project scope accepted
ADR-149 operator config interview skill superseded (superseded by ADR-169)
ADR-150 Version-truth and downgrade-safe self-update accepted
ADR-152 Framework-default secret-path deny baseline accepted
ADR-162 Mechanical session-link suppression as defense against transcript disclosure superseded (superseded by ADR-167)
ADR-163 Config separation — dotfiles as source-of-truth feeding the settings fragment store accepted
ADR-164 File artifacts distributed across hosts must be carried by value not host-absolute reference accepted
ADR-167 Session-link suppression: attribution.sessionUrl as primary control, deny hook as backstop accepted
ADR-169 agent-ways relinquishes user-scoped settings.json; retains only its operational baseline accepted
ADR-179 Remove the pre-1.0 in-place migrator; keep the guards and the transition fallbacks Accepted
ADR-181 Guard hooks: a blocking PreToolUse class, shipped deactivated accepted
ADR-184 Installation and activation are separate states: targets as the unit of activation accepted
ADR-185 CLI output contract: structured output for people, JSON for machines accepted
ADR-186 Live integration fixture: install-path test levels and the tier 2 gate Accepted
ADR-500 settings.json three-way merge: spec and peer-writer coexistence contract accepted
ADR-501 The agent-ways MCP server: one server for attend, keepalive and later modules, inbound through channels accepted
ADR-502 The ways agent: one resident daemon per user for search, judging and key custody accepted
ADR-503 Settings are files described by one typed registry; the CLI and the TUI are two ways in accepted
ADR-504 One TUI engine on ratatui and one theme for every interactive surface accepted
ADR-505 Duplicated implementations across ways, attend and the hooks, audited 2026-10-01 proposed
ADR-506 The consolidation ends with no legacy compatibility accepted
ADR-507 The ways commands regroup into operator commands and six groups; names another process calls stay fixed accepted
ADR-508 The live fixture runs locally; its GitHub workflow runs on manual dispatch only accepted
ADR-509 Lifecycle commands sit under one ways manage group; the updater's reconcile stays a hidden fixed name accepted
ADR-510 Settings --project names the enclosing project, and a write names its file accepted
ADR-511 Every mutating lifecycle verb reports what it would change until --commit accepted
ADR-512 Each shipped Claude Code mod has one wanted state in settings, under mods., and ways manage converges every target to it accepted
ADR-513 Themes reach every surface, with gradients, glyphs and painted report bands accepted
ADR-514 Claude Code follows the active theme through the ways-theme mod, over externalised theme layers accepted
ADR-515 How themes, mods, sensors, ways and judge profiles are kept and shown across the store, the settings screens and the CLI, audited 2026-10-29 proposed
ADR-516 One item descriptor of kind, origin, path, source, version and state for themes, mods, sensors, ways and judge profiles, shared by the store, the settings screens and the CLI accepted
ADR-517 The images mod ships from agent-ways as a fourth mod, installed by default, its history moved from the operator's dotfiles accepted
ADR-518 Each settings tab shows its items by scope: user, this project and other projects, with a trust row per project and a project opt-out from user-scope ways accepted

Practice

The ways method, way authoring, the development loop

ADR Title Status
ADR-013 Ways, Skills, and Governance Architecture accepted
ADR-100 Ways Scaffolding Wizard accepted
ADR-109 Project-Scope Way Embedding with Manifest-Based Staleness Detection accepted
ADR-110 Way File Separation and Graph-Compatible Structure accepted
ADR-128 Memory as repo-portable ways — seed routing over accumulated snapshots accepted
ADR-132 Collaboration ways domain accepted
ADR-138 Skills own the how, ways own the 5W accepted
ADR-141 Knowledge Graph as Evidential Memory Backend accepted
ADR-143 Three-root way runtime — core, user, project accepted
ADR-165 Loop-control bookends: start, develop, merge, release, wrap accepted
ADR-175 Standing delegation authorization satisfies the harness permission gate rather than overriding it accepted
ADR-176 Contract identification as the develop-loop front gate accepted
ADR-178 Register transfers by demonstration - core.md carries policy accepted
ADR-180 GitHub issues as the shared truth for the session task list accepted
ADR-600 Cognitive loop and the awareness layer accepted
ADR-601 Autonomy as a layered system: goals, signposts, and the initiation pattern accepted
ADR-602 Ways functional audit: 117 ways against the firing contract accepted
ADR-603 Cypress survey: what a node-routed seed teaches a hook-disclosed corpus accepted
ADR-604 Ways defer to external system enforcement accepted
ADR-605 An evaluative ways domain: the agent authors, the harness and oracle judge accepted
ADR-606 Deferred macros, and the PR awareness, involvement check and PR feedback way built on them accepted
ADR-607 Children of a loop-type way are loop types or concerns several loops share accepted
ADR-608 Delegation is asked for by the user, a skill, or a CLAUDE.md file, not by a way's own text accepted
ADR-609 Outward writes need the user's ask or a grant in their CLAUDE.md, and ways offer them otherwise accepted
ADR-610 Every wrap is recorded by one ways command, and a session-start way steers the next session by its distance from the writer accepted
ADR-611 Working-branch GitHub writes need no grant, and merging into a consequential branch does accepted
ADR-612 Directional technical calls go to the operator as an interview with a lean defended from evidence accepted
ADR-613 Work in progress is held per stage by what the stage consumes, and a card is done when it is on main with its in-card findings fixed accepted
ADR-614 Findings are fixed in the change that surfaced them accepted

Ways engine

The ways engine, continued after the full 100-199 band: matching, disclosure and the corpus

ADR Title Status
ADR-700 Body content, score geometry and corpus growth in way routing: a measured exploration accepted
ADR-701 Neighbourhood matching: masking, relative scores, lookup on request and a learning loop from run logs accepted
ADR-702 Way identity and authored edges: UUIDs, frontmatter links and an integrity-checked graph index proposed
ADR-703 Self-evaluated probe sets gate ADR-701's matching changes, and the body score ships scaled on prompts that chunk to one piece accepted
ADR-704 A tool-name trigger lane proposed
ADR-705 Claude Code's tool surface and hook events, surveyed as tool types for trigger lanes and session sensing proposed
ADR-706 A shipped tool catalog maps the harness's tool names to abstract tool types, so ways and sensors depend on types and not on Claude Code's names proposed
ADR-707 Measurements of the shell surface, covering the semantic lane's on-topic rate, alternative match surfaces, and a judge reading the described call proposed
ADR-708 A Claude Code internal engine for the relevance gate, selectable, with one judge engine per session accepted
ADR-709 A spike of the prompt-lane handoff to a mod judge, covering the prompt.submit bracket, session identity and model latency proposed
ADR-710 Toggle patterns over way ids, and a switched-off way discarded at the last step with a logged event accepted

Archived

4 archived ADRs — no longer part of the active set; kept for history | ADR | Title | Status | |-----|-------|--------| | [ADR-112](archive/system/ADR-112-session-ledger-and-knowledge-graph-integration.md) | Session Ledger with Optional Knowledge Graph Enhancement | Superseded (superseded by ADR-123) | | [ADR-133](archive/system/ADR-133-plugin-way-discovery.md) | Plugin Way Discovery | Rejected | | [ADR-145](archive/system/ADR-145-explicit-three-source-convergence-manifest.md) | Explicit three-source convergence manifest | Superseded (superseded by ADR-144) | | [ADR-168](archive/system/ADR-168-instance-addressable-directed-messaging-for-same-cwd-attend-siblings.md) | Instance-addressable directed messaging for same-cwd attend siblings | Rejected |