Context
Operator main-goal directive (2026-06-12, chief-architect session on Epic #13012): "a future session must easily be capable to pick up the concept, and know where we are and what's up next. could be an ADR and or a project board. we do NOT want to read 20 pages each session."
The harness concept currently lives across: closed Discussion #10119 (36KB archaeology), Epic #13012 (body + maintained plan-of-record comment), sub-epics/leaves, and tonight's decision records. Each surface is correct at its altitude — but a fresh session has no single ≤-few-pages concept anchor, and "where are we" requires thread-walking. The same evening produced two operator token-economics corrections (work items ≠ ideation venues; epic-review cap 2) — the intake surface must honor that principle structurally.
The Problem
Session-intake cost compounds: every future session (mine, a peer's, a post-compaction recovery) pays the full archaeology unless a durable, small, versioned concept anchor exists. Project boards carry live state but not the WHY/WHAT; epic bodies carry solution shape but evolve; Discussions are archaeology. The missing piece is the stable narrative layer — exactly what ADRs are for (precedent: ADR 0018 identity SSOT, ADR 0019 AiConfig SSOT — both serve as cold-read anchors today).
The Architectural Reality
- ADRs live in
learn/agentos/decisions/ (next free number: 0020; sibling shapes to lift: 0018-neo-identity-source-of-truth-model.md, 0019-aiconfig-reactive-provider-ssot.md).
- The intake stack this ADR completes: (1) ADR 0020 (concept, stable) → (2) Project board 13 (live state: epics/leaves/status) → (3) the target work item (detail). Bounded cold-read.
- Content the ADR must anchor (all converged on #13012 as of 2026-06-12): the product bar (compete with Claude Desktop / Claude Code tab); simplicity-first (download → productive); the two entry modes (bring-your-harness via extended-NL MCP; native Anthropic-account login); two-axis architecture (multi-window Neo app + extended-NL coordination substrate); Electron decision + rationale (always Chromium + Node, Agent OS in-process, Tauri retired); hemisphere placement (UI in
apps/ replacing the agentos PoC; fleet services in ai/; PATs Brain-side only); three pillars (fleet manager → conversational creation → deploy plane); git-tooling requirement; streaming + buffered chat rendering; the binding guardrails (Topological-Locking-before-multi-writer, benchmark-before-perf-claims, session-id canonicalization #12984, restart affordances, breadcrumb scope); FOSS posture (MIT engine + harness; monetize the hosted plane).
The Fix
One PR: author learn/agentos/decisions/0020-agent-harness-concept.md per the sibling ADR conventions (status/context/decision/consequences shape), ≤ a few pages, ending with the session-intake recipe (the 3-step stack above) as an explicit section. Wire any docs-tree registration the decisions folder requires (verify against how 0018/0019 are wired). The ADR cites Epic #13012 as the live decomposition root and Discussion #10119 as archaeology-only.
Out of scope: the roadmap/vision public-surface rewrite (operator named it as a possible companion — separate leaf when called; this ADR is the internal anchor), the AGENTS-substrate breadcrumb PR (separate guardrail leaf, may reference the ADR once it exists).
Acceptance Criteria
Release classification: post-release (product line).
Related
- Parent: Epic #13012 (link via native relationship). Board: Project 13.
- Operator directive provenance: this session's chief-architect inputs (2026-06-12 evening).
- Siblings: #13015 (Fleet Manager MVP), #13018 (Markdown VDOM, @neo-fable-clio), #13019 (epic-review cap, @neo-gpt).
Origin Session ID: c4caff26-d818-486b-8663-19b85ac3cc11
Retrieval Hint: "ADR 0020 agent harness concept anchor session intake recipe board 13"
Context
Operator main-goal directive (2026-06-12, chief-architect session on Epic #13012): "a future session must easily be capable to pick up the concept, and know where we are and what's up next. could be an ADR and or a project board. we do NOT want to read 20 pages each session."
The harness concept currently lives across: closed Discussion #10119 (36KB archaeology), Epic #13012 (body + maintained plan-of-record comment), sub-epics/leaves, and tonight's decision records. Each surface is correct at its altitude — but a fresh session has no single ≤-few-pages concept anchor, and "where are we" requires thread-walking. The same evening produced two operator token-economics corrections (work items ≠ ideation venues; epic-review cap 2) — the intake surface must honor that principle structurally.
The Problem
Session-intake cost compounds: every future session (mine, a peer's, a post-compaction recovery) pays the full archaeology unless a durable, small, versioned concept anchor exists. Project boards carry live state but not the WHY/WHAT; epic bodies carry solution shape but evolve; Discussions are archaeology. The missing piece is the stable narrative layer — exactly what ADRs are for (precedent: ADR 0018 identity SSOT, ADR 0019 AiConfig SSOT — both serve as cold-read anchors today).
The Architectural Reality
learn/agentos/decisions/(next free number: 0020; sibling shapes to lift:0018-neo-identity-source-of-truth-model.md,0019-aiconfig-reactive-provider-ssot.md).apps/replacing the agentos PoC; fleet services inai/; PATs Brain-side only); three pillars (fleet manager → conversational creation → deploy plane); git-tooling requirement; streaming + buffered chat rendering; the binding guardrails (Topological-Locking-before-multi-writer, benchmark-before-perf-claims, session-id canonicalization#12984, restart affordances, breadcrumb scope); FOSS posture (MIT engine + harness; monetize the hosted plane).The Fix
One PR: author
learn/agentos/decisions/0020-agent-harness-concept.mdper the sibling ADR conventions (status/context/decision/consequences shape), ≤ a few pages, ending with the session-intake recipe (the 3-step stack above) as an explicit section. Wire any docs-tree registration the decisions folder requires (verify against how 0018/0019 are wired). The ADR cites Epic #13012 as the live decomposition root and Discussion #10119 as archaeology-only.Out of scope: the roadmap/vision public-surface rewrite (operator named it as a possible companion — separate leaf when called; this ADR is the internal anchor), the AGENTS-substrate breadcrumb PR (separate guardrail leaf, may reference the ADR once it exists).
Acceptance Criteria
learn/agentos/decisions/0020-agent-harness-concept.mdexists, sibling-convention-compliant, ≤ a few pages.aligned-with ADR 0018(identity surfaces), no conflicts.Release classification: post-release (product line).
Related
Origin Session ID: c4caff26-d818-486b-8663-19b85ac3cc11 Retrieval Hint: "ADR 0020 agent harness concept anchor session intake recipe board 13"