docs: phased implementation plan and architecture decision records #1

wtclaude · 2026-08-08T19:35:48Z

wtclaude commented

2026-08-08 19:35:48 +00:00

Turns the design doc into an ordered, dependency-correct build plan and records the architectural decisions it rests on.

Locked decisions

Area	Decision
Deployment	One Rust binary (gateway, rules, memory, admin API, panel); Qdrant / Kanboard / Gitea MCP / embeddings as separate compose services routed through the binary
Transport	Streamable HTTP only (`/mcp`)
Auth	Bridle-issued per-agent bearer tokens; `clientInfo` is a display hint, never a permission source
Storage	SQLite (`bridle.db`)
Rule delivery	`get_rules` tool with hard session gating — every other tool errors until it succeeds
Multi-project	`project_id` from day one; single-project UX at 1.0
`enforcement` tier	Scoped to Bridle-mediated actions; bypass documented as a known limit
Degradation	Stable tool list always; downed upstreams return structured errors
Embeddings	Generic OpenAI-compatible endpoint with model/dimension guarding
Pattern RAG	Gated behind a throwaway validation spike
Renderers v1	`CLAUDE.md` + `AGENTS.md`; Kimi/DeepSeek dialects post-1.0

Deviations from the design doc's original 1–8 ordering

Audit log and multi-project schema moved to phase 1 — both are cheap upfront and expensive to retrofit across five subsystems
Admin API built incrementally from phase 1 rather than all at the Web Panel phase, so it isn't written twice
Vendor guardrail sourcing downgraded to manual-first — scraping vendor docs is fragile for the value it returns
Pattern-example RAG gated behind a spike rather than committed to outright

Notes for review

Two ADRs narrow claims the design doc made, and are worth a close read:

ADR-0008 redefines the enforcement tier. The gateway can only gate actions that route through it — an agent with shell access can git push or curl around Bridle entirely. The tier is now scoped honestly and the bypass documented rather than left implied.
ADR-0005 addresses the delivery gap: an MCP server can only offer get_rules, not make a model call it. Session gating closes that without needing a client-side component.

Documentation only — no code, no CI impact.

AI disclosure

Authored with Claude Code (Opus 5). Commits carry a Co-Authored-By: Claude trailer.

🤖 Generated with Claude Code

https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m

Turns the design doc into an ordered, dependency-correct build plan and records the architectural decisions it rests on. ## Contents - `docs/implementation-plan.md` — phases 0–9, each with scope, relative size, and an exit criterion - `docs/adr/0001`–`0012` — one ADR per architectural decision, with the alternatives that were considered and rejected - Tracks the previously-untracked design doc and `CLAUDE.md` ## Locked decisions | Area | Decision | |---|---| | Deployment | One Rust binary (gateway, rules, memory, admin API, panel); Qdrant / Kanboard / Gitea MCP / embeddings as separate compose services routed through the binary | | Transport | Streamable HTTP only (`/mcp`) | | Auth | Bridle-issued per-agent bearer tokens; `clientInfo` is a display hint, never a permission source | | Storage | SQLite (`bridle.db`) | | Rule delivery | `get_rules` tool with hard session gating — every other tool errors until it succeeds | | Multi-project | `project_id` from day one; single-project UX at 1.0 | | `enforcement` tier | Scoped to Bridle-mediated actions; bypass documented as a known limit | | Degradation | Stable tool list always; downed upstreams return structured errors | | Embeddings | Generic OpenAI-compatible endpoint with model/dimension guarding | | Pattern RAG | Gated behind a throwaway validation spike | | Renderers v1 | `CLAUDE.md` + `AGENTS.md`; Kimi/DeepSeek dialects post-1.0 | ## Deviations from the design doc's original 1–8 ordering - **Audit log and multi-project schema moved to phase 1** — both are cheap upfront and expensive to retrofit across five subsystems - **Admin API built incrementally from phase 1** rather than all at the Web Panel phase, so it isn't written twice - **Vendor guardrail sourcing downgraded to manual-first** — scraping vendor docs is fragile for the value it returns - **Pattern-example RAG gated behind a spike** rather than committed to outright ## Notes for review Two ADRs narrow claims the design doc made, and are worth a close read: - **ADR-0008** redefines the `enforcement` tier. The gateway can only gate actions that route through it — an agent with shell access can `git push` or `curl` around Bridle entirely. The tier is now scoped honestly and the bypass documented rather than left implied. - **ADR-0005** addresses the delivery gap: an MCP server can only *offer* `get_rules`, not make a model call it. Session gating closes that without needing a client-side component. Documentation only — no code, no CI impact. ## AI disclosure Authored with Claude Code (Opus 5). Commits carry a `Co-Authored-By: Claude` trailer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m

wtclaude added 2 commits 2026-08-08 19:35:50 +00:00

docs: add project design doc and agent guidance 7fdde56560

Tracks the two files that were sitting untracked in the working tree: the
original Agentic Bridle MCP design doc, and CLAUDE.md carrying the repo's
git/Gitea, SonarQube, and contribution conventions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m

docs: add phased implementation plan and architecture decision records 06917d43e2

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

whitlocktech approved these changes 2026-08-08 19:37:18 +00:00

whitlocktech merged commit 36a25dd15a into main

2026-08-08 19:37:26 +00:00

whitlocktech referenced this issue from a commit

2026-08-08 19:37:26 +00:00

Merge pull request 'docs: phased implementation plan and architecture decision records' (#1) from docs/implementation-plan into main

whitlocktech deleted branch docs/implementation-plan

2026-08-08 19:37:26 +00:00

wtclaude referenced this pull request

2026-08-08 19:40:48 +00:00

docs: note GPLv3 scope and third-party licensing in README #14

Sign in to join this conversation.