Architecture

Type: kb/types/tag-readme.md

How Commonplace is structured and installed. Repo layout, the two-tree split between user content and framework, control-plane design, and the file-based storage decision.

For current-state subsystem documentation and ADR navigation, start at ../reference/README.md.

Notes

• reference overview — entry point for current-state docs and architecture decisions
• commonplace-architecture — the Commonplace repo structure: KB collections, packaged runtime, shipped skills, and operational surfaces
• 006-two-tree-installation-layout — how Commonplace installs into projects: two-tree layout, copy-vs-reference boundary, design rationale
• 010-review state should move to sqlite once reviews leave git and accumulate operational metadata — review operational state crosses a deliberate authority boundary once acknowledgements and indexed transitions keyed by (note, criterion, model_partition) become database-owned
• kb-goals-in-always-loaded-context-guide-inclusion-decisions — installed KBs need explicit domain goals in the control-plane file
• control-plane-goals — current-state: how Commonplace realises KB goals in AGENTS.md, the scaffold template, and the install-time fill-in flow
• files-defer-centralized-schema-commitment-until-invariants-stabilize — canonical files can defer a shared schema while meanings remain unsettled; database authority is a separate commitment made through an operative write path, not a consequence of invariant shape or unowned state
• storage-architecture — current-state: how Commonplace lays out files as source of truth, regenerable indexes, and the scoped SQLite review-state exception
• agents-md-should-be-organized-as-a-control-plane — theory for AGENTS.md as a control plane: invariants, routing, escalation boundaries
• instruction-specificity-should-match-loading-frequency — CLAUDE.md should be a slim router; match instruction specificity to loading frequency
• generate-instructions-at-build-time — generate CLAUDE.md and routing tables at build time rather than maintaining them by hand
• instruction-generation — current-state: the Commonplace commonplace-init build step, scaffold trees, and substitution points that implement build-time generation today
• scenario-decomposition-drives-architecture — concrete use cases decomposed into step-by-step context needs
• scenario-architecture — current-state: the two-tree split, the escalation path to commonplace/kb/, the AGENTS.md fragment contract, and the tests/scenarios/ measurement surface

Other tagged notes

• Agent-runtime analysis should separate scheduling, context assembly, and external state - For runtimes composed of bounded model calls, separating control progression, per-call context, and external state or action services localizes failures even when one implementation owns all three
• Always-loaded context mechanisms in agent harnesses - Survey of always-loaded context mechanisms across agent harnesses — system prompt files, capability descriptions, memory, and configuration injection — cataloguing what each carries, how write policies differ, and where the gaps are
• Edge ownership selects the key; choosing files or a database requires a workload comparison - Distinguishes the complete edge key required by relation-owned mutable state from the workload-specific choice between edge files and a database.
• Runtime structure determines the control surfaces available to governance - Runtime structure and runtime governance are separable, but the runtime's structure determines which inspection, validation, correction, and drift-control operations governance can actually perform
• Skill discovery re-fires in every sub-agent context, not just the top-level invocation - Skill discovery is per-context and autonomous — every installed skill is re-matched in each sub-agent context, even ones a parent narrowed, so a delegating skill's own discoverability is a leak vector