whitlocktech/Agentic-Bridle
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
36a25dd15a65fe8e38f7cf7906aa7023c11e525a
Agentic-Bridle/docs/adr/0012-v1-renderer-targets.md
wtclaude 06917d43e2 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
2026-08-08 14:33:27 -05:00

1.3 KiB
Raw Blame History

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.