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 | PostToolUse delivery for tool-lane ways and retirement of the semantic Bash surface | 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 |
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 | 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 |
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 |