Skip to content

Architecture Decision Records

ADR-0001

Title

Investigation Before Implementation

Status

Accepted

Context

The project involves multiple interacting systems including Claude Code, OmniRoute, and external AI providers.

Premature implementation risks building on incorrect assumptions.

Decision

Every project follows this sequence:

  1. Discovery
  2. Architecture
  3. Design
  4. Implementation
  5. Validation

Consequences

  • Better long-term maintainability.
  • Fewer rewrites.
  • Better documentation.
  • Evidence-based engineering.

ADR-0002

Title

Organic Skill Evolution

Status

Accepted

Context

The repository accumulates Claude Code workflows across sessions. Designing reusable project Skills in advance contradicts ADR-0001 (investigate before implement) and risks creating speculative structure that does not match actual use. Skills are more reliable when distilled from workflows that have already recurred and proven stable. Continuity across sessions requires an evidence ledger so a reusable workflow is not rediscovered repeatedly.

Decision

Project Skills are created only through the organic lifecycle defined in the "Skill lifecycle" section of CLAUDE.md:

  1. A workflow is recorded in Skill-Candidates.md when first observed and becomes a Skill candidate only after occurring in at least two distinct sessions.
  2. Skill-Candidates.md is an engineering evidence ledger, not a backlog or TODO list. Entries record session references, occurrences, evidence for recurrence, and the reason for promotion or rejection.
  3. Meeting the occurrence threshold makes a workflow eligible for review only. Promotion is never automatic and requires an explicit recommendation, user approval, Skill creation, and a record in Decisions.md.
  4. Discarded candidates remain in the ledger with the reason for rejection, so the repository retains the engineering history.
  5. No meta-skill is created to manage this process.
  6. Skill creation and retirement decisions are recorded here.

Consequences

  • Skills track actual, repeated need rather than prediction.
  • The same evidence discipline applies to workflows as to knowledge: a single occurrence is not a Skill.
  • Recurring cost: the session-end review and the ledger maintenance.
  • Risk: a workflow may not be recognized as repeatable on first observation and could go unrecorded.
  • Skills can be retired by the same observation loop when they stop being used.

ADR-0003

Title

Phase 1B Local Investigation Plan — Approval and Execution Record

Status

Recorded (2026-08-02)

Context

Roadmap gate (Phase 1B, immediate next action item 5) required the Phase 1B local investigation plan to be reviewed and approved before local inspection began. The plan (Findings/2026-08-01 - Phase 1B Investigation Plan.md) was executed on 2026-08-02 and Phase 1B was marked complete, but no written approval record existed at that time.

Decision

The Phase 1B plan is recorded as approved and executed. The read-only workstreams (A1, A3, B, C1, C2, C4, D1, D2, D4) ran as written. The three [NEEDS SEPARATE APPROVAL] steps (A2 experimental payload capture, C3 header observation, D3 container-down test) were deferred and were not executed; they remain open hypotheses in Knowledge-Base.md. Approval was confirmed during the Phase 1 completion review on 2026-08-02. This record closes Roadmap gate item 5.

Consequences

  • The deferred experiments remain hypotheses (container-down failure behavior, X-OmniRoute-* header exposure, management-token unlock) and must be separately approved before the Phase 2 architecture depends on them.
  • ADR-0001's audit trail is now closed for Phase 1B, but future plan approvals should be recorded at the time of approval rather than at completion review.

ADR-0004

Title

Phase 2 Architecture Plan — Approval and Execution Record

Status

Recorded (2026-08-02)

Context

The Roadmap Phase 2 gate required the Phase 2 architecture plan to be reviewed and approved before architecture synthesis began. The plan was proposed on 2026-08-02 and approved by the repository owner on 2026-08-02.

Decision

The Phase 2 plan (Workstreams 1–4: architecture synthesis, read-only verification, decision records, documentation updates) is recorded as approved and executed. The read-only verification ran as written: latency, resolved-model stability, transcript reliability, freshness, and provider-inference measurements against call_logs and the session transcript. No container-down experiment, no live gateway request, and no credential access were performed. Observations are in Findings/2026-08-02 - Phase 2 - Read-only Verification.md.

Consequences

  • The architecture in Architecture.md now depends only on verified data sources; the design does not depend on the deferred experiments (container-down behavior, header exposure, management-token unlock), which remain separately approvable hypotheses.
  • The four material architecture decisions from the synthesis (ADR-0005 through ADR-0008) were accepted in the Phase 2 completion review on 2026-08-02. Their acceptance closes the Phase 2 gate; Phase 3 (Design) is now in progress.

ADR-0005

Title

Primary Resolved-Model Source Is the Session Transcript

Status

Accepted (2026-08-02)

Context

Two read-only paths expose the resolved model: the SQLite call_logs table (Docker volume) and the Claude Code session transcript. Phase 2 measured the latency difference (transcript tail read sub-millisecond; SQLite query <10 ms but Docker startup 0.21–1.13 s depending on image), confirmed the transcript carries message.model on 78/78 assistant messages with values matching call_logs.model, and confirmed the transcript is session-local by construction while call_logs is shared across all gateway clients with session_tag NULL (no session correlation).

Decision

The statusline's primary resolved-model source is the last assistant message's message.model in the session transcript, with fallback to the statusline payload's model.display_name (the requested model) until the first assistant message exists.

Consequences

  • Fast (sub-ms) and session-accurate, with no Docker dependency and no auth.
  • Provides the model string only; provider is not in the transcript (see ADR-0006).
  • The parser must tolerate transcript structure changes (the field moved from the top level to message.model between Phase 1B and Phase 2).

ADR-0006

Title

Provider Display Is Best-Effort Enrichment, Never a Dependency

Status

Accepted (2026-08-02)

Context

The project objective is a provider-aware statusline, but the transcript carries no provider field. Provider can only come from SQLite call_logs.provider (authoritative but ~0.25–1.13 s via Docker, shared-gateway ambiguous, filtered by combo_name/status) or an empirical model→provider mapping (fast and local but a heuristic — unambiguous in observed data today, may drift as providers add or remove models). The Phase 2 gate requires that the design not depend on unverified behavior.

Decision

Provider display is optional and best-effort, architecturally subordinate to the resolved-model core. Each provider path has a defined fallback to model-only display: SQLite enrichment when the read is within budget and Docker is available; otherwise the empirical mapping treated as a heuristic; otherwise provider omitted. A missing or wrong provider degrades to model-only — it never crashes and never fabricates a provider.

Consequences

  • Meets the provider-aware objective while keeping the reliable core (transcript model).
  • The empirical mapping, if used, is treated as observed data with a confidence caveat, not a contract.
  • Phase 3 must specify the mapping's storage, refresh policy, and the exact SQLite correlation filter.

ADR-0007

Title

Correlation Model Is Most-Recent-Request

Status

Accepted (2026-08-02)

Context

session_tag is NULL on all call_logs rows and session_model_history is empty (Phase 1B), so per-session model history cannot be reconstructed from OmniRoute logs alone. The transcript, by contrast, is session-local by construction.

Decision

The statusline displays the most recent resolved route. Any per-session behavior must come from the transcript (which is session-local), not from OmniRoute logs. OmniRoute-based session history is recorded as not available in this installation.

Consequences

  • The display is "what the last response used," refreshed on each statusline event.
  • No session-history widget is built from OmniRoute data; the combo_name + status filters define which SQLite rows count as a route when provider enrichment is used.

ADR-0008

Title

Version-Change and Schema-Drift Handling

Status

Accepted (2026-08-02)

Context

The transcript's resolved-model field relocated from the assistant message top level to message.model between Phase 1B and Phase 2 (observed version drift). The OmniRoute image tag is latest (unpinned), so call_logs schema and combo_name semantics can change on update.

Decision

All upstream reads are defensive: the transcript parser checks message.model then top-level model; the SQLite query selects named columns and treats a missing column or empty combo_name as "no route info"; unknown structure degrades to "no data," never to failure.

Consequences

  • Survives upstream changes without crashing.
  • Documented fallbacks mean a schema change appears as a missing value, not a broken statusline.

ADR-0009

Title

Phase 3 Design Plan — Approval and Execution Record

Status

Recorded (2026-08-02)

Context

The Roadmap Phase 3 gate requires the design to be approved before code is written. The Phase 3 design deliverables (Statusline/Design/01–06) and the design handoff (Statusline/Design/07-design-handoff.md) were proposed on 2026-08-02 and approved by the repository owner on 2026-08-02 with one approved change request.

Decision

The Phase 3 design is approved; the approved change request was incorporated into the design documents. The change request: the transcript tail read is required to be bounded at the architecture level, but the concrete window size is an implementation constant (currently 256 KB), not an architectural invariant. Statusline/Design/02, 04, and 07 were updated to frame the window size as the implementation's choice. The six deliverables (display requirements, input/output contract, provider/model naming rules, caching and timeout policy, security and privacy, test cases and acceptance criteria) and their 16 test cases are the Phase 4 implementation contract.

Consequences

  • The Phase 3 gate is closed; Phase 4 (Implementation) is approved to begin in a new session, against the design and its acceptance criteria.
  • Changing the transcript tail window size requires no ADR; it is an implementation tuning constant.
  • The design's four previously-open decisions (provider source, staleness threshold, mapping format and refresh, output format) are resolved and recorded in Architecture.md.

ADR-0010

Title

Phase 4/5 Execution Record and V1.0 Release

Status

Recorded (2026-08-03)

Context

Phase 4 implemented the approved Phase 3 design (Statusline/lib/*, Statusline/statusline.js, the 29-test contract suite, and Scripts/) and deployed it live; Phase 5 validated it against real and failure scenarios. One Phase 5 scenario remained at gate review — OmniRoute unavailable — and could not be safely induced: it would require stopping the local OmniRoute Docker container that serves all Claude Code traffic. The statusline has no runtime coupling to OmniRoute (it reads only the local transcript and the local mapping file), so the statusline-visible effect of OmniRoute being down is identical to a frozen transcript (route ages → [stale]), which was already validated live via overnight idle.

Decision

  1. Phase 4 is an implementation of the approved architecture, not a new architectural change; no new ADR was required for it.
  2. Phase 5 is closed. The OmniRoute-unavailable scenario is an opportunistic observation, not a required induced failure; a future natural outage may be recorded as additional validation evidence.
  3. The completed work is released as V1.0: merged into implementation/statusline-v1, then main, and tagged v1.0.0.
  4. Visual statusline improvements (progress bar, replacing the context display, other UX changes) are a separate V2 project, not part of V1.0.

Consequences

  • The Phase 4 and Phase 5 gates are closed; Phase 6 (documentation and maintenance) is complete.
  • main holds the stable V1.0 baseline; implementation/statusline-v1 is the implementation line.
  • Future OmniRoute outages are evidence-capturable, never a blocking test.
  • V2 begins as an independent project from the V1.0 baseline.

ADR-0011

Title

Standalone Global Skill: Phased Project Workflow

Status

Recorded (2026-08-04)

Context

The phase discipline used throughout this project's history (Discovery → Architecture → Design → Implementation → Validation, scaled to risk) is a reusable engineering method independent of this repository's content. The user requested it be encoded as a portable, user-level skill for projects that live outside this repo. The workflow had recurred across every session of this project, meeting the repeated/stable/bounded/nontrivial criteria, and the user explicitly approved creating it.

Decision

A standalone global skill phased-project-workflow is created at ~/.claude/skills/phased-project-workflow/SKILL.md. It is fully standalone: it captures general engineering workflow principles and does not reference this repository or any project-specific path as a source or dependency. Its defining feature is a ceremony-scaling matrix — the amount of process applied scales with the complexity and risk of the work, rather than being a rigid six-phase ritual. This entry is a provenance record only; the skill does not depend on this repo.

Consequences

  • The skill is usable in any project directory outside this repo.
  • This repo remains one concrete application of the method, not its canonical source.
  • No project Skill is created in .claude/skills/ for this workflow; the global skill supersedes the need for one here, and ADR-0002's organic lifecycle continues to govern project Skills.