Instruction generation

Type: kb/types/note.md

How Commonplace instantiates build-time generation over runtime parameterisation in the shipped system. This note describes the scaffold, template substitution, and install entry point.

The entry point

commonplace-init is the single project-scaffold step. It creates the project directory structure, copies scaffold trees verbatim, and resolves a small set of templates with per-project values. Command installation is separate and user-level: uv installs the Python package before this command runs.

There are no runtime variables in the generated artifacts. AGENTS.md, skill definitions, and configuration files contain literal paths and names by the time an agent sees them.

Substitution points

init_project resolves three placeholder kinds during template processing:

Placeholder Replaced with Source
<your-project> Project directory name (or --name override) CLI argument or root.name
{{project_name}} Same same
/PATH/TO/COMMONPLACE/ Absolute path to the project root, with trailing slash root resolved to absolute path

Substitution is a flat string replace in _write_template. Templates that don't need substitution (scaffold trees) are copied byte-for-byte instead.

Generated artifacts

commonplace-init produces four kinds of output:

Directories (from MANIFEST.directories) — empty directory shells the practitioner fills in:

  • kb/types/ — shared global types
  • kb/notes/, kb/notes/types/ — user's notes collection
  • kb/reference/, kb/reference/types/ — user's reference collection
  • kb/instructions/ — user's instructions collection
  • kb/sources/, kb/sources/types/ — user's source captures
  • kb/tasks/backlog/, kb/tasks/active/, kb/tasks/completed/ — user's task lifecycle
  • kb/work/, kb/reports/, kb/reports/connect/, kb/reports/types/ — user's workshops and reports

Scaffold trees — copied from scaffold sources. In a built wheel these sources live under packaged commonplace/_data/; in an editable source checkout commonplace-init falls back to the canonical repo paths:

  • kb/commonplace/notes/ — shipped methodology library (from our kb/notes/)
  • kb/commonplace/reference/ — shipped-system documentation and ADRs
  • kb/commonplace/instructions/ — shipped procedures and cp-skill-* skills
  • kb/types/ — shared global types (text, note, instruction, definition, index)
  • kb/reports/types/, kb/sources/types/ — collection-local type definitions for user-space collections

Scaffold files — individual files copied into the user's collections:

  • kb/notes/COLLECTION.md — minimal theoretical/descriptive/prescriptive template
  • kb/notes/README.md — curated empty-state landing
  • kb/reference/COLLECTION.md — minimal template
  • kb/reference/README.md — curated empty-state landing
  • kb/instructions/COLLECTION.md — minimal template
  • kb/instructions/README.md — curated empty-state landing

Each COLLECTION.md template invites the practitioner to pick a register, state a quality goal, and declare outbound link rules, with pointers to the shipped kb/commonplace/<collection>/COLLECTION.md as a worked example. Each README.md supplies the collection's stable reader landing, points authors to that contract, and states that the collection has no artifacts yet.

Resolved templates — read, substituted, written:

  • AGENTS.md.template → AGENTS.md.template in the target root (practitioner then copies or renames to AGENTS.md)

The template flows through _write_template with the replacements dictionary. The scaffold creates no .envrc or Commonplace-specific project venv; command discovery belongs to the user-level uv tool installation.

Scaffold source resolution

The source tree does not keep symlinked copies of the shipped KB under src/commonplace/_data/. Instead, init_project resolves each scaffold input by checking two locations:

  1. commonplace/_data/<path> — packaged wheel data, populated by Hatch force-include entries from canonical repo paths. The sdist also explicitly includes those canonical inputs so wheels built from sdists have the same scaffold source.
  2. The canonical repo path — used in editable source checkouts, so edits to kb/notes/, kb/reference/, kb/instructions/, and the root templates are picked up without duplicating files.

The exception is src/commonplace/_data/templates/, which contains real scaffold-only files for the user collections' starter COLLECTION.md contracts and README.md landings. Those files have no canonical counterpart elsewhere in the KB.

Skill projection

In addition to copying the instructions tree under kb/commonplace/instructions/, init_project attempts to project a selected subset of skills (write, validate, connect, convert, health-check, ingest, snapshot-web, revise-autoreason, write-multistage) into two known runtime discovery layouts:

  • .claude/skills/cp-skill-<skill>/
  • .agents/skills/cp-skill-<skill>/

Each generated projection is a real copied directory of kb/commonplace/instructions/cp-skill-<skill>/. Projected files are classified per file by the same _record_existing rules as the rest of the scaffold, so a re-run reports copies that drifted from the canonical source without overwriting them.

The canonical contract is the source directory, not the two generated layouts. Agent runtimes and IDEs that use another skill surface must copy, register, or import the same kb/commonplace/instructions/cp-skill-* directories according to their own rules.

Re-running init

init_project is idempotent-ish. Existing files are classified into three groups by _record_existing:

  • Identical to scaffold — silently preserved
  • Different from scaffold — preserved without overwriting, reported as "preserved existing files differing from current scaffold output" so the operator can decide whether to diff and update manually
  • Missing — created fresh

The rule is "never clobber a practitioner edit." Updating an installed project to a newer Commonplace release is a manual diff-and-merge step, not a re-run.

.envrc is outside the current manifest, so re-running init neither inspects nor changes it.

What's not generated

A short list of things that are still authored by hand rather than generated:

  • Static-site navigation configuration, if a project publishes the KB as a site
  • Per-project customisation of the ## KB Goals and Scope section in a generated AGENTS.md — the template carries placeholder prose; the practitioner fills in real values

These could all move to generated form later, but the current build-time step covers the cases where runtime parameterisation would have cost the most interpretation overhead: paths in promoted skills and the project name stamped into the control-plane template.

Relevant Notes: