Reference

Reference documentation for the Commonplace system — how to operate it and how it works.

This collection answers two kinds of question:

  • How do I...? — operational how-tos for the common workflows your agent runs on your behalf: writing, ingesting, connecting, validating, reviewing, and so on.
  • How does this work? — the shipped architecture, type system, control-plane conventions, authoring procedures, and the decision record behind major design choices.

Use this collection when the question is specifically about the shipped Commonplace system. For transferable claims and theory about knowledge-base methodology, see kb/notes/. For authoring conventions, each collection has a COLLECTION.md at its root.

Mental model

You do not operate the KB directly. You instruct an agent, and the agent operates the KB for you.

The agent reads the shipped skills (.claude/skills/cp-skill-*/SKILL.md or .agents/skills/cp-skill-*/SKILL.md), reads the target collection's COLLECTION.md, and writes output under kb/.

The practical consequence: ask for outcomes, not internal procedures. "Write a note about X" is better than "read the write skill and then ...". The skill is the agent's concern; the outcome is yours.

This guide assumes you have a running agent session (Claude Code, Codex, etc.) with Commonplace's skills in its discovery path. If commonplace-init has run and .claude/skills/ or .agents/skills/ exists, you're ready.

How to

Most operations are things you ask the agent to do. Each entry below shows what the operation is for, how to phrase the request, what the agent does, and the practical limits.

Add a note

What it's for. Capture an insight, decision, or observation as a structured artifact in the KB.

How to ask.

  • "Write a note arguing that rate limits should be applied per-tenant rather than per-endpoint. Connect it to existing notes on rate limiting."
  • "I just realized our retry logic is swallowing errors. Write that up."
  • "Capture the decision we just made about moving auth to a sidecar."

What happens. The agent searches the KB for related notes, picks a type, reads the writing conventions, drafts the file under kb/notes/, and connects it to related notes and indexes.

What you get. A new markdown file under kb/notes/ with frontmatter, a claim-shaped title, and inbound and outbound links to related notes.

Limitations. The agent's sense of "what's worth a note" depends on the ## KB Goals and Scope section in AGENTS.md. The out-of-scope list is load-bearing; without it, scope creeps.

Ingest a source

What it's for. Analyse one URL-backed external source while keeping its reading copy local.

How to ask.

  • "Ingest https://example.com/some-article and connect it to our notes on context engineering."
  • "Read this PDF and ingest the key claims."
  • "Ingest the README at github.com/org/project as a related system."

What happens. The agent snapshots the source into ignored kb/sources/.snapshots/, reads it, finds related notes, and writes a tracked analysis whose frontmatter carries the durable URL, capture provenance, genre, and exact snapshot checksum. In this repo, external system analysis enters through analyse-agentic-system. It delegates memory analysis to analyse-agent-memory against the frozen evidence boundary and canonical register. The specialist returns a typed report; the parent integrates it into the exact main result and publishes one compact whole-system review.

What you get. A local snapshot under kb/sources/.snapshots/ and a tracked ingest report at kb/sources/<slug>.ingest.md with summary, claims, and links into kb/notes/.

Limitations. Paywalled or JavaScript-heavy pages can snapshot incompletely. Classification into "related system" versus "source" is sometimes a judgment call.

Search and navigate

What it's for. Find notes relevant to a question without reading the whole KB.

How to ask.

  • "Find notes about how we decided to validate schemas."
  • "What do we have on retry backoff strategies?"
  • "Is there anything in the KB about the tradeoff between X and Y?"

What happens. The agent combines frontmatter search, curated tag READMEs, scoped ripgrep listings and body search, and link following. It filters by descriptions first, then loads only the notes that look relevant.

What you get. A short list of notes with justifications, usually followed by a synthesised answer that cites them inline.

Limitations. Search quality depends heavily on frontmatter descriptions, tag coverage, and the query terms an agent chooses. Vocabulary-mismatched concepts need synonym searches and link traversal rather than an external semantic-search daemon.

For the full read path and scaling direction, see navigation.md.

Connect an existing note

What it's for. Discover relationships between a note and the rest of the KB, and wire them up.

How to ask.

  • "Connect kb/notes/my-new-note.md to related notes."
  • "I just wrote a note on X. Find what it should link to."

What happens. The agent reads the source collection's COLLECTION.md for its per-destination outbound rules, prospects each authorised destination (curated indexes, scoped rg description listings, body search, link-following), applies the articulation test, labels candidates from the destination's authorised set, and writes a connection report. The skill never edits notes — the report is the entire deliverable.

What you get. A report at kb/reports/cache/connect/<collection>/<note-name>.connect.md (gitignored) listing candidate outbound edges, bidirectional candidates, reverse-edge candidates (notes that should link to this target under their own COLLECTION.md rules), off-authorisation candidates (articulated but outside the authorised label set), index memberships, synthesis opportunities, and a discovery trace. Review the candidates and apply the ones worth keeping — connect never mutates the source, so applying the suggestions is a separate step.

Limitations. Relationship labels are judgment calls and sometimes need correction. Connection is often underdone at write time, so running connect explicitly on new notes is a reasonable habit.

Convert text to a note

What it's for. Promote a rough capture to a more structured form as understanding matures.

How to ask.

  • "Convert kb/notes/scratch.md from text to a note."

What happens. The agent adds valid note frontmatter: a semantic description, type: kb/types/note.md, and empty traits and tags, while leaving user-verified absent. It does not edit the body. When the filename does not match the title, it renames the file within its collection and repairs backlinks.

What you get. The same captured content as a structurally valid, unverified note, possibly under a title-aligned filename with its inbound links updated.

Limitations. Only text → note is implemented; other conversions are unsupported. Conversion supplies structure and retrieval metadata; it does not improve the body or create rigor.

Revise a note

What it's for. Improve the prose of an existing note without changing its claims.

How to ask.

  • "Revise kb/notes/foo.md for flow and clarity. Don't change what it argues."
  • "This note feels redundant in the middle section. Tighten it."

What happens. The agent makes a revision pass, writes the result to a numbered copy, and asks you to compare before applying.

What you get. A revised version for review and, after approval, an updated original.

Limitations. Iterative revision can drift semantically over many passes. Keep passes short and verify that the claims survived.

Validate the KB

What it's for. Check mechanically decidable artifact properties—well-formed frontmatter, required fields, resolvable links, and valid type-specific structure—and explicit repository invariants for collection landings and site redirects. This is deterministic and does not call an LLM.

How to ask.

  • "Validate kb/notes/foo.md."
  • "Run validation across the whole KB and report any failures."
  • "Check the collection landings and published redirects."
  • Or run commonplace-validate kb/notes/foo.md.

What happens. Artifact targets check schemas, links, filename constraints, and type-specific structural requirements. The landings target requires a non-colliding README.md for every collection directly under kb/; redirects checks properdocs.yml against the live published tree.

What you get. A pass/fail report per target with FAIL, WARN, and INFO lines. Artifact findings are labelled [base], [type: <name>], or [schema]; repository findings are labelled [repository]. See the validation contract for what each source can express.

Limitations. Validation judges mechanically decidable properties only. Vacuous descriptions or weak claims are review problems, not validator problems.

Review notes

What it's for. Run snapshot-anchored assays against notes: closed-ended gates return decisions, while open-ended assays such as critique retain current reports.

How to ask.

  • "Review kb/notes/foo.md with the prose bundle."
  • "Run the semantic review sweep over anything I've changed recently."
  • "Ack the trivial changes in the review queue."

What happens. The review system stores state in SQLite, selects target (note, criterion) pairs, creates result-kind-homogeneous queued jobs, delegates each prompt to a worker, and advances the freshness baseline only after all pairs in the job finalize successfully.

What you get. Per-gate PASS / WARN / FAIL / ERROR decisions or open-ended reports, plus current freshness state pinned to the note and criterion bytes.

Limitations. The review UX is still agent-driven. Gate selection depends on note traits, worker delegation is owned by the current harness, and the selector/create/finalize command sequence is more operator-facing than a finished end-user CLI.

See README-REVIEW-SYSTEM.md for how to use the review system and review-architecture.md for how it is built; FIX-SYSTEM.md covers the complementary fix system.

Direct CLI commands

Most operations go through the agent, but a few CLI commands are reasonable to run directly:

Command Purpose
commonplace-validate <target> Validate an artifact or collection, global type specs, collection landings, or the published redirect map
commonplace-guard-full-pass-report <report> Refuse a full-pass transition unless every packet capture still matches its live artifact
commonplace-relocate-note <note> --to <dest> [--apply] Move or rename a note with link rewrites and ProperDocs redirect; dry-run by default
commonplace-github-snapshot <url> Snapshot a GitHub issue or PR into local kb/sources/.snapshots/
commonplace-x-snapshot <url> Snapshot a Twitter/X post into local kb/sources/.snapshots/

commonplace-relocate-note dry-runs by default. Pass --apply to write changes.

For the full CLI surface, see commands.md.

Reference

Look up how the shipped system is put together: its architecture, type system, always-loaded context, authoring procedures, and decision history.

Architecture and packaging

For exact implementation behavior, inspect src/commonplace/ in this checkout. From an installed project, commonplace-source locates the package that supplies the running commands. The documents below retain architecture, invariants, and orientation that the implementation does not cheaply recover.

  • architecture.md — installed topology and the library/user, command-runtime, skill-projection, and path-invariance boundaries
  • scenario-architecture.md — scenario-derived architecture: the library/user split under kb/commonplace/, package-provided commands, and measurable scenario decomposition
  • storage-architecture.md — authority and lifecycle boundaries among authored files, local copies, derived artifacts, and operational state
  • documentation-site.md — how the ProperDocs site renders kb/: the README-vs-index rule, the nav-generation hook, and the full inventory of reader landing pages
  • navigation.md — how agents move through the KB using control-plane pointers, rg, titles/descriptions, indexes, links, connect reports, and future search layers
  • control-plane-goals.md — how Commonplace ships KB goals in always-loaded context via AGENTS.md
  • instruction-generation.md — build-time instruction generation flow and commonplace-init
  • review-architecture.md — review dispatch ownership, canonical state versus derived artifacts, all-or-nothing finalization, and the freshness hash boundary (the build-side companion to README-REVIEW-SYSTEM.md)
  • freshness-architecture.md — target and input identity, registered-status versus review discovery, transition semantics, and queue-to-finalize concurrency

Type system and collection model

  • collections-and-types.md — how collection and type contracts compose, how path-valued type pointers resolve, common examples, and where global and collection-local type specs live
  • link-vocabulary.md — linking approach and label catalogue: collection-owned outbound rules, reader-need labels, articulation tests, connect reports, and guidance for COLLECTION.md authors
  • collection-prototypes.md — optional creation-time contracts that may be copied into a new collection; the resulting COLLECTION.md is independently owned and receives no prototype updates
  • collections-never-own-frontmatter-semantics.md — why the collection/type split is asymmetric: a type spec owns frontmatter semantics, COLLECTION.md owns only text-level features
  • Answerability — Commonplace's stipulated admission boundary: what an artifact answers to, the property it asserts, and the discrepancy that triggers correction
  • Collection and text contract — canonical definitions of the collection boundary and its complete local authoring declaration
  • Commonplace doctrine — the standing instruction a worker inherits with binding force when its runtime loads it; a handoff is a delta from it

Authoring and operator procedures

Imperative how-to procedures live in kb/instructions/ rather than this collection, but they are part of the shipped surface:

  • Each collection's COLLECTION.md — collection-specific writing conventions, quality goals, and placement rules
  • README-REVIEW-SYSTEM.md — how to use the review system: concepts, freshness, the batch workflow, and command surface (the how-it-is-built companion is review-architecture.md)
  • FIX-SYSTEM.md — current fix-system workflow
  • full-improvement-pass-closure.md — how the full-improvement workflow reassays final note bytes, routes residual findings, and stops without claiming convergence
  • harness-sub-agent-model-selection-regression.md — the July harness regression that mis-attributed review executions, the August partial restoration of bounded-fork model overrides, and why a requested model is still not execution provenance

The repository as a worked case

Commonplace runs on its own methodology, so this collection also documents this repository as an operating instance — what it has been observed to do, under which declared boundary, and what that does and does not establish. These describe the case, not the surface a consuming project installs.

  • commonplace-declared-frame.md — the declared boundary all the assessments below are made under: what is inside, what is outside, and how to cite or depart from it
  • commonplace-as-a-reflective-system.md — classifies the repository as a human-inclusive reflective self-improving system and locates which functions in one observed pathway are human, joint, or computational
  • commonplace-as-an-instrument.md — what the KB application is for in the design program: the composition test, two worked provenance instances, and the transfer evidence the repository does not have
  • design-rationale-management.md — how workshops, proposals, ADRs, contracts, and validators distribute design rationale, and the end-to-end continuity the shipped contracts do not enforce
  • content-routing.md — routing table from content kind (intent, force, decision, alternatives, scope, mechanism, procedure, implementation fact, change narrative, observation, evidence, source claim) to destination, with the regeneration source and consumer that justify each row
  • tag-readme-trace-observed-causal-connection.md — the ADR-026 change traced commit by commit as one observed instance of causal connection in both directions
  • tag-readme-trace-as-self-improving-loop.md — the same trace mapped onto search, evaluation, and retention, showing which half of each step runs in code
  • where-change-candidates-come-from-in-commonplace.md — how problem-noticing and candidate-drafting happen beyond a maintainer's own judgment
  • agent-memory-coverage.md — how the shipped surfaces realize agent-memory requirements, and where they currently fall short
  • commonplace-agent-memory-gap-plan.md — the plan for closing those gaps: session traces, candidates, cue activation, behavioral evaluation, lifecycle, import, ranking, and authority

Decision history

adr/ contains the architecture decision records for major shipped-system choices. Notable entries:

Collection boundary

  • Use kb/notes/ for beliefs about the design space whose particular system choices are bound.
  • Use kb/reference/ for Commonplace's selections and the current or historical state they produced.
  • Use kb/instructions/ for imperative procedures and operator-facing process details.

Keep these docs self-contained within the shipped surface. A consuming project should be able to read kb/reference/ without needing links back to the Commonplace source repository or methodology library.

Complete file listing (generated at build time)