Check an install

Three verbs that never write into a harness: list reports what state asks for, show prints one memory or one source from the store, and doctor checks what each harness will load against the files on disk. The quickstart is the install path these verbs check.

See what is installed: list

npx -y @vivswan/maxims list

The specification fixes what list reports and leaves the layout to mirror npx skills list. Everything past the recorded intent is re-derived when you run it, so a hand-edited hook registry is reported as it is, not as it was.

One local source installed for Claude Code, hashes illustrative:

Global memories
/home/user/rules  0b21639  fetched 2026-10-09  ok
  alpha-rule  (61809f9)
  beta-rule  (be9dead)
  Agents: claude-code (tier 1)  Rules: no
Defaults: agents=detected rule=false cooldownDays=7 ruleCap=25

list reports	derived from
each source and its fetched sha	state
its selected memories, each with its short content hash	the store copy or the live tree, filtered by the recorded selection
staleness per source, with the reason of the last failed fetch	state
a reviewed source's mark, and the revision held for review with its changed-line count	state
live name collisions and the renames resolving them	the name index, rebuilt from every source's intent
the tier each harness achieves, and the rule file token estimate	the harness configs and rule files on disk

--json prints the same facts as one document. Each harness under a source carries hook, with the values doctor reports.

Read one memory or source: show

npx -y @vivswan/maxims show tests-before-the-fix

show prints one installed memory in full: the source it came from, the installed revision, whether it is disabled here or held for review, the rule line as maxims renders it, then the whole file, frontmatter included. The body comes from the store copy, never from a harness's file, so what prints is what the next sync installs.

|
o  tests-before-the-fix
   source: @Octocat/rules
   revision: 3701003
   disabled: no
   held: no
   rule: - A fix lands with the test that failed before it, never a test written after the fact (detail: <HOME>/.agents/maxims/store/octocat/rules/memories/tests-before-the-fix.md, 997856e)
|
---
name: tests-before-the-fix
description: A fix lands with the test that failed before it, never a test written after the fact
...

<HOME> in the sample stands for your home directory; the real line carries the absolute path.

A name two sources provide exits 1 and lists them; --source <key>, -g or -p picks one. --json prints the same facts as one document with the file under body.

show <source> takes a source as remove and update spell it and prints its facts: revision and whether it tracks or pins, scope, agents, selection, renames, disabled names, and the review mark.

When a revision is held for review, a second block lists the rule lines it adds (+), removes (-) and changes (~), names the bodies that differ, and prints a unified diff of each. --json carries them under held.

doctor: what each harness loads

npx -y @vivswan/maxims doctor

doctor reads each harness's own loading rules against disk: the rule file at the path the harness reads, required frontmatter present, the hook entry registered, the hook command current. list reports what state asks for and re-derives the tier from disk when you run it; doctor goes file by file and fails on a mismatch. It prints one line per finding.

line starts with	meaning
ok	this harness loads what state asks for
!	a warning: an undefined harness id, a held revision, or "never synced"
x	one harness that will not load a rule you believe is installed

The report ends with a Defaults: line naming the rule and addHook defaults from config.json, and with the age of the last sync. Exit 0 when every harness in state passes, exit 1 when any line is x. A rule file held behind a block marker is one such x row.

The CI one-liner

npx -y @vivswan/maxims doctor --expect prefer-timeouts-to-hangs --json

--expect <name> or --expect @owner/repo/name asserts that memory has a rule line in place for every harness it targets. A missing one exits 1 with the harness and path named. The flag repeats, one memory per --expect.

--json emits the report as one document, so a CI job asserts "these rules are installed" without parsing lines. Its top-level keys are ok, findings, harnesses, unresolved, expect, lastSync, and defaults. findings carries the printed lines as { "kind": "ok" | "warn" | "fail", "text" }, and ok is false when any finding is fail, the x lines above.

Each entry of harnesses carries hook: none for a harness with no hook, not-wanted when state asks for none there, current, missing, or { "kind": "broken", "reason", "hint" } for a registry that cannot be planned (a dangling link, a file that does not parse). The printed line reads hook broken: <reason>.