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.yamldeclares - 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. |
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 |