Architecture

Type: types/tag-readme.md

How Commonplace is structured and installed: the repository layout, the user's KB living in the project while the library is read in place from the installed package (ADR 086), the control plane in AGENTS.md, and the file-based storage decision. Nearby but different: computational-model is about what runs, not where it lives.

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
• 086-projects read the library from the installed package — how Commonplace installs into projects today: no copy, init-written stubs and a routing file pointing at the installed library; supersedes the two-tree layout of ADR 006 and the one-tree model of ADR 014
• 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 scenario-derived shipped architecture, the user's KB in the project with the library read from the package, package commands, promoted skills, 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
• Channel-compiled instruction artifacts - Proposal: resolve execution channel at install time so an agent reads one literal procedure, extending build-time generation from paths to shell and command form
• Checked inline blocks for shared instruction text - Proposal: reuse natural-language authoring mechanics in specialized writer prompts through literal inlining backed by deterministic source-to-copy checks
• 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