The Recording Standard

A standard — and the tooling to keep it — for where your written work goes and how it's written, so your work compounds instead of scattering. Built to be used the same way by you and the AI agents you work with.

If you've ever finished something and later couldn't find what you wrote, re-explained the same context to an agent twice, or watched notes pile up with no home — this is for that.

Why this exists

Documentation is the record of work: the visible, reviewable, shareable version of what you did. It's the highest-value input to more work, for humans and machines alike. When it has no consistent home and no consistent form:

• you slow down every time you come back to something,
• collaborators (and future-you) can't follow the trail,
• and the agents you work with can't understand your work well enough to help.

The Recording Standard makes recording low-effort and self-maintaining: every piece of work has one home you can name without deciding, one form that's fast to read, and a background process that keeps it all consistent without you policing it.

What it does

• One home for everything. Every page is classified by mode and routed to a single findable place. No more "where did that go?"
• Your agents learn the standard automatically. A compact rules block is installed into the context your AI tools read, so they record the same way you do.
• A gentle write-time check. When a page is written, a non-blocking nudge flags anything off-form — it never gets in your way.
• An audit that keeps everything converged. The part that actually guarantees consistency: it reviews your pages, fixes safe drift, and proposes the rest.

The core idea: convergence, not policing

Checking every write is impossible — you'll edit things by hand, other tools will write pages, an agent will run somewhere you can't hook. So the guarantee isn't catching every write. It's convergence: an audit brings every page back to the standard on a cadence, no matter who wrote it or where.

That's what makes it safe to run unattended, and it rests on two rules:

• No silent changes. Every automatic fix is written down where you can see and undo it. Silence is the enemy of trusting an agent.
• Never delete. The audit restructures and marks; a human does the removing.

Install

Requires Claude Code (Node ships with it). Paste this into Claude Code:

Install recording-standard: add the plugin marketplace github:chzylee/recording-standard and
install the recording-standard plugin (this registers its hooks and the recording-standard-setup
and audit skills). Then run recording-standard-setup to configure it. Confirm the
RECORDING-STANDARD block landed in ~/.claude/CLAUDE.md, and tell me what's set up and what's left.

That's the whole install — it adds the plugin, opens the setup form, and reports. One install per machine (the floor; there's no zero-setup path).

Updating

Updates are not automatic by default — Claude Code only auto-updates its own official marketplaces, not third-party ones like this. To get a new version, either:

• Enable auto-update for this marketplace once (/plugin → Marketplaces → turn on auto-update). Claude Code then pulls new versions a few minutes after a session starts and prompts you to run /reload-plugins.

• Or update manually:

  /plugin marketplace update recording-standard
  /plugin update recording-standard@recording-standard
  /reload-plugins
  

The standard block ships inside the plugin, so it refreshes with the plugin — nothing to re-copy.

Maintainer note: bump version in .claude-plugin/plugin.json on every release, or updates won't be detected.

Set it up

recording-standard-setup opens a form with all your settings in one place, and remembers them. Re-run it any time to change them:

• Where your pages live — the registry the audit reads.
• Where audit results go — the one page the audit keeps updated with what it changed and what it suggests.
• How often, and how bold — cadence (default: every 2 days), and how far off-standard a problem must be before the audit fixes it automatically instead of just proposing.

Using it day to day

You mostly don't think about it. When you or an agent records something:

1. Classify what it is — one of six modes.
2. Route it to the first home that fits: its subject's home, else the hub for its mode, else ask and register a new one.
3. Write it to the form floor: a mode label up top, collapsible sections, plain language.

Then the audit handles upkeep. On its schedule it posts to your audit results page — Applied this audit (what it fixed, so you can review) and Outstanding (what it suggests, ranked by how far off-standard it is). Run the audit yourself in a session any time and it reports straight to you instead.

The rules at a glance

The six modes — every page declares one

1. Reference — read for knowledge (a human is in the audience).
2. Living documentation — the current state of a thing, kept up to date.
3. Operational surface — a live board or hub you read and update while working.
4. Standard / contract — rules a worker must follow (targets machine behavior, no human audience).
5. Log / archive — an append-only record.
6. Plan — intended work: editable until executed, then frozen.

Mode is the read/write contract of a page, not its topic. (Reference vs Standard: if a human is anywhere in the audience, it's Reference — a machine can read a Standard, but its target is behavior.)

Routing — how a page finds its one home

Classify → route to the first home that resolves → ask on miss:

• try the page's subject's home (put it where the thing it's about already lives),
• else the hub for its mode (a new analysis with no hub → your analyses hub),
• else ask, then register the new home so the next one of its kind is automatic.

One fact lives in one place; everything else links to it.

The form floor — what gets checked

The write-time check looks only at the objective, no-judgment things: a mode label in the opener, and collapsible sections for documentation so the outline reads at a glance.

Everything that needs judgment — clear openers, current-state-only, honest claims, and plain language (no coined jargon) — is the audit's call, by heuristic, not a fixed rulebook.

Make it yours

This repo ships with a working standard, but the point is to bend it to your own work.

• Change the rules. standard/recording-standard.block.md is the source of truth your agents follow. Edit it, bump the v<date>, and every machine picks it up. Your modes, your routing homes.
• Tune the audit. How bold it's allowed to be, and how often it runs, live in recording-standard-setup.
• Add a "why" layer (optional). This repo is the enforceable layer — the machine-readable rules and the tooling. If you also want a human-readable home for the reasoning behind your standard (a Notion space, an Obsidian vault, a wiki), keep the prose there and let this repo stay the single source of truth for what's actually enforced. That's how the author runs it: the repo is the how, a Notion space is the why. You don't need it to start — the repo stands on its own.

What's in here

Path	What it is
standard/recording-standard.block.md	The rules block your agents follow (edit this to change the standard)
skills/audit/	The audit that keeps everything converged — the guarantor
skills/recording-standard-setup/	The one setup + config handle (opens a form via config-form)
config/	The vendored config-form engine + your config schema
hooks/	Session-start self-heal + the write-time nudge (hooks.json registers them)
checks/mechanical-checks.mjs	The deterministic checks the audit and the write-time hook share
docs/	How the repo is built and why (see below)

Owning this repo

• docs/build_status.md — current state, read first.
• docs/decision_log.md — every design choice and why.
• docs/TEST_SPEC.md · docs/RATIFICATION_LOG.md — the trust contract.

License

MIT — see LICENSE. Fork it, adapt it, make it yours.