Agent Rulebook

TypeScript CLI and MCP foundation for managing reusable agent rules.

Requirements

The packaged 0.1.5 artifact supports Node.js 20 and 22 through 26. Node.js 21 is excluded because the pinned [email protected] native runtime does not declare support for it. The first supported platform is Darwin arm64, where the local tarball matrix covers Node.js 20 and 22 through 26. Windows x64 is currently unverified and unsupported; its native acceptance matrix is required before any Windows or cross-platform support claim, but it does not block the Darwin-only rollout.

Agent Rulebook keeps rule YAML and its rebuildable SQLite index outside the npm package in ~/.agent-rulebook by default. Reinstalling the package or clearing the npm cache must not remove that data.

Run the CLI

Run the published immutable version without a global install:

npx -y [email protected] --help
npx -y [email protected] mcp

[email protected] is an immutable package version. Production configuration should pin this exact version. Registry tags such as latest are mutable and are not asserted by this artifact.

The 0.1.5 release keeps current-project rules directly searchable when legacy migration metadata lacks stack facets and resolves project identity from the Git remote before falling back to the checkout directory name. Exact-version pinning remains the recommended production configuration; Windows x64 remains unsupported and deferred.

Documentation

• Codex adapter setup

Private YAML sync

Initialize ~/.agent-rulebook as a Git repository whose tracked files are limited to rules/**/*.yaml, .gitignore, and a safe config.yaml or config.example.yaml. SQLite/WAL/SHM files, locks, logs, reports, and temporary files must remain untracked. Setup documentation stays in this product repository, not in the private data remote. If any local artifact or other non-allowlisted file is tracked, sync push fails with a remediation path.

First machine and an empty private remote

Create an empty private repository with the Git hosting provider. Do not add a server-generated README, license, or .gitignore. Then initialize and commit the local Rulebook data:

agent-rulebook init
git -C ~/.agent-rulebook init -b main
git -C ~/.agent-rulebook remote add origin <private-remote-url>
git -C ~/.agent-rulebook add .gitignore config.yaml
git -C ~/.agent-rulebook commit -m "Initialize private Agent Rulebook data"

Verify the repository visibility with the hosting provider. Only after it is confirmed private, record that evidence in local Git config. This marker is local and must be configured independently on every machine:

git -C ~/.agent-rulebook config remote.origin.agentRulebookPrivacy private
agent-rulebook sync push       # preview remote URL and changed files
agent-rulebook sync push --yes # execute exactly the reviewed push

The privacy marker is not inferred from the URL. A missing/unknown marker or a public marker blocks push. Before invoking Git, the command also requires a clean, conflict-free worktree and preflights every changed rule through schema validation and secret detection. sync pull uses fast-forward-only Git and then checks/rebuilds the local SQLite projection from canonical YAML.

Actual private-remote writes remain user-approved operations. Inspect the target and commits with git remote -v and git log --oneline @{upstream}..HEAD before the first real push.

Additional machine

On a new machine, clone first so agent-rulebook init does not create a nonempty destination before Git:

git clone <private-remote-url> ~/.agent-rulebook
agent-rulebook init
git -C ~/.agent-rulebook config remote.origin.agentRulebookPrivacy private
agent-rulebook sync pull
agent-rulebook index check

sync pull is fast-forward-only. It validates the pulled rule sources and checks the local index, rebuilding SQLite when the source count, semantic checksum, or schema version differs. The SQLite database is created separately on every machine and is never pulled from Git.

An intentionally empty data remote is a valid initial state. In that case, index check --json should report status: ok, sourceCount: 0, and indexedCount: 0; search returns no results until the first active canonical rule is committed. Do not seed a new private remote from temporary test homes or fixtures—wait for a real rule or migrate a reviewed permanent source.

Normal workflow

agent-rulebook sync pull
# Add, verify, deprecate, or supersede rules locally.
git -C ~/.agent-rulebook add rules
git -C ~/.agent-rulebook commit -m "Update Agent Rulebook rules"
agent-rulebook sync push
agent-rulebook sync push --yes

If sync push reports a dirty worktree, commit the reviewed canonical YAML change first. If it reports a conflict, resolve every listed YAML field and rebuild the index before retrying.

Lifecycle and recovery

Lifecycle changes preview by default; add --yes after reviewing the target:

agent-rulebook rule verify <draft-id> --evidence <test-or-review-reference>
agent-rulebook rule deprecate <active-id>
agent-rulebook rule supersede <active-id> --replacement <active-replacement-id>

Verification requires explicit evidence and known compatibility. Superseding requires an existing active replacement and rejects replacement cycles. Applied changes atomically replace one YAML source and rebuild SQLite, so default CLI/MCP search immediately reflects the lifecycle state.

Use these local-first recovery paths:

agent-rulebook index check
agent-rulebook index rebuild
git -C ~/.agent-rulebook status

• For a corrupt, outdated, or checksum-mismatched index, rebuild from YAML.
• For Git conflicts, resolve every listed YAML file and validate it before rebuilding or pushing; the tool never auto-merges rule conflicts.
• For a bad synced commit, create a normal git revert <commit> rollback, then pull and rebuild. Do not restore or synchronize a SQLite file.

Development

npm run typecheck
npm test
npm run build
node dist/cli.js --help

Verify the publish artifact without writing to the registry:

npm run release:verify
npm pack --dry-run
npm run check:package
npm run smoke:package

The packed smoke creates an empty custom npm cache, installs the local tarball, runs CLI/init/native SQLite/MCP acceptance, then repeats from the warm cache in a second isolated install. All package and rulebook homes are temporary.

The project uses better-sqlite3 for the local SQLite store because the MVP needs synchronous, embedded persistence with a small API surface. It is a native dependency. Install or startup diagnostics include the exact Node version, platform, and architecture so unsupported native combinations can be reported.

Release status

The packaged release version is 0.1.5, the package is explicitly UNLICENSED, and no public repository, homepage, or issue tracker is currently advertised because the source remote is not publicly accessible. Package availability and mutable registry tags must be checked again immediately before publish. No publish or dist-tag operation is performed by the local verification scripts.