docs: add phased implementation plan and architecture decision records
Turns the design doc into an ordered, dependency-correct build plan (phases 0-9) with an exit criterion per phase, and records the twelve architectural decisions it rests on as ADRs. Decisions: single Rust binary with routed compose services; Streamable HTTP only; per-agent bearer tokens with clientInfo as a display hint only; SQLite; get_rules delivered via session gating; full-document rule delivery; project_id from day one; enforcement tier scoped to Bridle-mediated actions; stable tool list on upstream failure; OpenAI-compatible embeddings with model/dim guarding; pattern RAG gated behind a spike; CLAUDE.md + AGENTS.md as v1 renderer targets. Deviates from the design doc's original 1-8 ordering by moving the audit log and multi-project schema into phase 1, building the admin API incrementally rather than all at the Web Panel phase, downgrading vendor guardrail sourcing to manual-first, and gating the pattern-example RAG behind a validation spike. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m
This commit is contained in:
28
docs/adr/0012-v1-renderer-targets.md
Normal file
28
docs/adr/0012-v1-renderer-targets.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# ADR-0012: `CLAUDE.md` and `AGENTS.md` as the v1 renderer targets
|
||||
|
||||
**Status:** Accepted (2026-08-08)
|
||||
|
||||
## Context
|
||||
|
||||
The design doc names four agent targets: Claude, Codex, Kimi, and DeepSeek. Phase 2 exists to prove
|
||||
the single-source-of-truth thesis — that one canonical document renders correctly into genuinely
|
||||
different agent formats. Shipping only one renderer would not prove it, because nothing would force
|
||||
the canonical schema to stay format-neutral; it would quietly shape itself around the single target.
|
||||
Shipping all four means four renderers and four golden-test suites before the thesis is validated
|
||||
even once.
|
||||
|
||||
## Decision
|
||||
|
||||
Ship **`CLAUDE.md` (Claude conventions) and `AGENTS.md` (Codex)** at 1.0. Kimi and DeepSeek land
|
||||
post-1.0 as `AGENTS.md` dialects carrying the more explicit, step-by-step phrasing the design doc
|
||||
calls for on weaker instruction-followers.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Two formats different enough to keep the canonical schema honestly format-neutral.
|
||||
- Golden-file tests cover both from phase 2; renderer correctness is that phase's actual
|
||||
deliverable.
|
||||
- The renderer must be structured so a dialect (same base format, different phrasing verbosity) is
|
||||
a cheap addition rather than a fork.
|
||||
- `agent_profiles` entries for Kimi and DeepSeek may exist in the canonical schema before their
|
||||
renderers do.
|
||||
Reference in New Issue
Block a user