Use the handbook

Keep one source for the team and its agents. A project vendors the book so its agreed version remains available without a network connection.

From the product’s root, with Node 20 or later:

node /path/to/principles/bin/principles.mjs init

This creates principles/HANDBOOK.md, its examples, the local CLI and version metadata, a pointer in AGENTS.md, and a short project note at docs/principles.md. Use --overlay <path> to put the note elsewhere. Link existing documentation instead of copying it into another template.

Make it available

Check that the agents your team uses actually load the project instructions. Some clients need an explicit import or configuration. File presence alone does not establish that the instructions were read.

Keep the project note limited to facts that affect decisions: what the product does, its authority boundaries, where its design system lives, and how to verify changes. Record a deliberate departure from the handbook with its reason. No pass table, new skill or new test framework is required.

The handbook explains what counts as proof. The product supplies the checks.

Update the copy

For a copy installed before the handbook, run the new checkout’s CLI once:

node /path/to/principles/bin/principles.mjs sync

This replaces the old layers and passes with the handbook. Later updates use the installed CLI:

node principles/principles.mjs check
node principles/principles.mjs sync

check checks the installed copy, instruction pointer and project note. It does not verify product behavior. sync updates the vendored files; review that diff before adopting changed principles. It leaves the project note alone. Change shared principles in this repository, not in a vendored copy.

Source resolution uses --source, then PRINCIPLES_SOURCE, then the local source checkout when running its CLI, then the recorded source or git@github.com:mutativ/principles.git. check --upstream compares the installed commit with the source’s current head.