CLI Reference¶

All AI-Rulez CLI commands and flags.

Command Overview¶

Core Commands¶

Aliases: generate → gen; validate → val. (g, clear, v and check were removed in 5.0; list check is list checks.)

All Commands¶

Every command in the binary, generated from the command tree (task docs:cli). The flags, defaults and examples of each are in the Command Reference.

CRUD Commands (Configuration Management)¶

add, remove and list take --local to work on the machine-local tree .ai-rulez/local/; include add|remove, skill install|remove and profile add|remove|set-default take --local to write to the config.local.* overlay. See Local Configuration.

CRUD Commands¶

AI-Rulez provides CRUD commands to programmatically modify your .ai-rulez/ configuration. These commands allow you to create domains, add rules/context/skills/agents/commands, manage includes, and organize profiles.

Results, --format json and which project¶

Every command below prints its result on stdout and its confirmation sentence on stderr, so a script can capture the result and -q only silences the sentence. add, remove, edit and domain add|remove print the path they created, removed or rewrote, alone on a line (relative to the working directory when below it). profile, include and skill install|remove change an entry in the config file, so they print nothing in text mode.

--format json is accepted by add, remove, edit, show, domain add|remove, profile add|remove|set-default, include add|remove and skill install|remove, and prints one versioned document (schema):

{"schema_version": 1, "status": "created", "type": "rule", "name": "style", "domain": "backend", "path": ".ai-rulez/rules/style.md"}

list and show print their own documents. A failure under --format json is the standard error document.

The global --config-dir <name> (a directory below the working directory, or an absolute path) and -C <dir> (a config directory, or a file inside one) select the project these commands act on, exactly as for generate. Without them the directory is discovered: .ai-rulez/, then .config/ai-rulez/.

ai-rulez add, remove, list, show, edit, domain, profile, include, skill and builtins without a subcommand print their help and exit 0; an unknown subcommand exits 1.

Names are file names: no /, no whitespace, no leading . or - and no trailing .md (the extension is added); domains and skills use letters, digits, _ and -. --priority is critical|high|medium|low|minimal; --targets takes preset names, paths or globs and rejects an unknown word. remove checks that the item exists before it asks for confirmation. domain remove refuses while a profile still lists the domain (remove the profile first). A new skill without --description gets a placeholder that passes validate.

add agent and add command take --domain, --description, --content and --local. remove agent|command and list agents|commands take the same flags as their rule/skill counterparts.

add check, remove check and list checks manage code-review guidelines (see Checks); they take --domain (and --description, --content, --severity low|medium|high|critical, --tools a,b and --targets for add; --yes/-y for remove) but have no --local.

ai-rulez show <kind> <name> prints the file as it is on disk (--format json adds the path). ai-rulez edit <kind> <name> replaces the content atomically: --content <text> (use - for stdin), --priority and --targets for rules, context and skills; for a check, content without frontmatter replaces only the body and --description, --severity, --tools and --targets are set on its frontmatter. Both take --domain, and --local except for checks.

edit keeps what the file already declares: a rule, context file or skill rewritten with bare content keeps its priority, targets, description and every other frontmatter key, and --priority or --targets change only that field (the MCP update_* tools do the same). Content that starts with its own frontmatter replaces the whole file. Content is never read, written or deleted through a symlink inside the configuration directory, and index and log are reserved names: index.md and log.md are the listings migrate okf generates, so they are not rules, context files or agents.

ai-rulez list --placement [--profile <name>] prints where every skill and command ends up (core or plugin-only), the plugins that bundle it, and flags plugin-only items nothing makes reachable.

ai-rulez skill update [name...] re-resolves the named installed skills (all without names) and records the commit and digest in ai-rulez.lock; it is ai-rulez lock --kind skill. A skill with a version range keeps a pin that still satisfies it; ai-rulez update moves range pins.

Domain Management¶

ai-rulez domain add <name> [flags]¶

Create a new domain with subdirectories for rules, context, and skills.

Syntax:

ai-rulez domain add <name> [flags]

Arguments:

• <name> (required): Domain name. Alphanumeric, hyphens, and underscores, 1-50 characters; must start and end with an alphanumeric character.

Flags:

• --description <text> (optional): Description of the domain

Examples:

Create a backend domain:

ai-rulez domain add backend

Create a domain with description:

ai-rulez domain add frontend --description "React web application"

ai-rulez domain remove <name> [flags]¶

Delete a domain and all its contents.

Syntax:

ai-rulez domain remove <name> [flags]

Arguments:

• <name> (required): Domain name to delete

Flags:

• --yes / -y (optional): Skip confirmation prompt

Examples:

Remove a domain (with confirmation):

ai-rulez domain remove backend

Remove without confirmation:

ai-rulez domain remove backend --yes

ai-rulez domain list [flags]¶

List all domains in the .ai-rulez/ directory.

Syntax:

ai-rulez domain list [flags]

Flags:

• --format text|json (optional, default text): json prints JSON.

Examples:

List domains:

ai-rulez domain list

List as JSON (a wrapper document, {"schema_version": 1, "items": [...]}):

ai-rulez domain list --format json

Content Management¶

Rules, context, and skills can be added to the root (always included) or to specific domains (profile-dependent).

ai-rulez add rule <name> [flags]¶

Create a new rule file with optional YAML frontmatter.

Syntax:

ai-rulez add rule <name> [flags]

Arguments:

• <name> (required): Rule filename without .md extension

Flags:

• --domain <name> (optional): Domain name. If not specified, creates in root rules directory
• --local (optional): Write to the machine-local tree .ai-rulez/local/rules/ instead of the shared tree. The output is gitignored and never committed. Combine with --domain to write to .ai-rulez/local/domains/<name>/rules/. See Local Configuration.
• --priority <level> (optional): Priority: critical, high, medium, low, minimal. Default: medium
• --targets <list> (optional): Comma-separated list of target providers (claude, cursor, etc.)
• --content <text> (optional): Rule content. Uses a template if omitted.

Examples:

Create a root rule:

ai-rulez add rule code-quality

Create a domain-specific rule:

ai-rulez add rule database-standards --domain backend --priority high

Create a machine-local override rule (gitignored, personal to this checkout):

ai-rulez add rule my-scratch-notes --local

Create with specific targets:

ai-rulez add rule performance --targets claude,cursor --priority high

ai-rulez add context <name> [flags]¶

Create a new context file (documentation/reference material).

Syntax:

ai-rulez add context <name> [flags]

Arguments:

• <name> (required): Context filename without .md extension

Flags:

• --domain <name> (optional): Domain name. If not specified, creates in root context directory
• --local (optional): Write to the machine-local tree .ai-rulez/local/context/ instead of the shared tree. The output is gitignored and never committed. Combine with --domain to write to .ai-rulez/local/domains/<name>/context/. See Local Configuration.
• --priority <level> (optional): Priority: critical, high, medium, low, minimal. Default: medium
• --content <text> (optional): Context content. Uses a template if omitted.

Examples:

Create root context:

ai-rulez add context architecture

Create domain context:

ai-rulez add context database-design --domain backend

Create a machine-local override context (gitignored, personal to this checkout):

ai-rulez add context local-env-notes --local

ai-rulez add skill <name> [flags]¶

Create a new skill file (AI prompt/expert definition).

Syntax:

ai-rulez add skill <name> [flags]

Arguments:

• <name> (required): Skill filename without .md extension

Flags:

• --domain <name> (optional): Domain name. If not specified, creates in root skills directory
• --description <text> (optional): Skill description
• --local (optional): Write to the machine-local tree .ai-rulez/local/skills/ (gitignored)
• --content <text> (optional): Skill content. Uses a template if omitted.

Examples:

Create a root skill:

ai-rulez add skill code-reviewer

Create a domain-specific skill:

ai-rulez add skill performance-optimizer --domain backend --description "Optimization workflow"

ai-rulez remove rule <name> [flags]¶

Delete a rule file.

Syntax:

ai-rulez remove rule <name> [flags]

Arguments:

• <name> (required): Rule filename without .md extension

Flags:

• --domain <name> (optional): Domain name
• --yes / -y (optional): Skip confirmation
• --local (optional): Remove from the machine-local tree .ai-rulez/local/

Examples:

Remove a root rule:

ai-rulez remove rule code-quality

Remove a domain rule:

ai-rulez remove rule database-standards --domain backend --yes

ai-rulez remove context <name> [flags]¶

Delete a context file.

Syntax:

ai-rulez remove context <name> [flags]

Arguments:

• <name> (required): Context filename without .md extension

Flags:

• --domain <name> (optional): Domain name
• --yes / -y (optional): Skip confirmation
• --local (optional): Remove from the machine-local tree .ai-rulez/local/

Examples:

ai-rulez remove context architecture
ai-rulez remove context backend-design --domain backend --yes

ai-rulez remove skill <name> [flags]¶

Delete a skill file.

Syntax:

ai-rulez remove skill <name> [flags]

Arguments:

• <name> (required): Skill filename without .md extension

Flags:

• --domain <name> (optional): Domain name
• --yes / -y (optional): Skip confirmation
• --local (optional): Remove from the machine-local tree .ai-rulez/local/

Examples:

ai-rulez remove skill code-reviewer
ai-rulez remove skill performance-optimizer --domain backend --yes

ai-rulez list rules [flags]¶

List all rule files.

Syntax:

ai-rulez list rules [flags]

Flags:

• --domain <name> (optional): List rules in specific domain only
• --format text|json (optional, default text): json prints JSON.
• --local (optional): List the machine-local tree .ai-rulez/local/ instead of the shared content

Examples:

List all rules:

ai-rulez list rules

List domain rules:

ai-rulez list rules --domain backend

ai-rulez list context [flags]¶

List all context files.

Syntax:

ai-rulez list context [flags]

Flags:

• --domain <name> (optional): List context in specific domain only
• --format text|json (optional, default text): json prints JSON.
• --local (optional): List the machine-local tree .ai-rulez/local/ instead of the shared content

Examples:

ai-rulez list context
ai-rulez list context --domain backend

ai-rulez list skills [flags]¶

List all skill files.

Syntax:

ai-rulez list skills [flags]

Flags:

• --domain <name> (optional): List skills in specific domain only
• --format text|json (optional, default text): json prints JSON.
• --local (optional): List the machine-local tree .ai-rulez/local/ instead of the shared content

Examples:

ai-rulez list skills
ai-rulez list skills --domain backend

Installed Skill Management¶

Install named skills from external repositories. See Installed Skills for full details.

ai-rulez skill install <name> --source <url> [flags]¶

Install a named skill from a git repository or local path.

Arguments:

• <name> (required): Skill name (unique identifier)

Flags:

• --source <url> (required): Git URL or local path
• --path <dir> (optional): Path within repo to skill directory (defaults to skills/<name>)
• --ref <ref> (optional): Git reference (branch, tag, commit)
• --local (optional): Record the skill in the machine-local config.local.* overlay instead of the shared config

Examples:

ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg
ai-rulez skill install my-lib --source https://github.com/org/repo --path custom/path --ref v2.0
ai-rulez skill install local-skill --source ../my-other-repo

ai-rulez skill remove <name> [flags]¶

Remove an installed skill from the configuration.

Arguments:

• <name> (required): Skill name to remove

Flags:

• --yes / -y (optional): Skip confirmation prompt
• --local (optional): Remove through the config.local.* overlay. A skill installed in the shared config is hidden on this machine with remove = true

Examples:

ai-rulez skill remove kreuzberg
ai-rulez skill remove my-lib --yes

ai-rulez skill list [flags]¶

List all installed skills.

Flags:

• --format text|json (optional, default text): json prints JSON.

Examples:

ai-rulez skill list
ai-rulez skill list --format json

Include Management¶

Manage external rule sources (git repositories or local packages).

ai-rulez include add <name> <source> [flags]¶

Add a new include source to the configuration.

Syntax:

ai-rulez include add <name> <source> [flags]

Arguments:

• <name> (required): Unique identifier for this include
• <source> (required): Git URL (e.g., https://github.com/org/repo) or local path (e.g., ./packages/shared)

Flags:

• --path <dir> (optional): Path within git repository where .ai-rulez/ content is located
• --ref <branch> (optional): Git reference (branch, tag, commit). Defaults to the repository's default branch (HEAD), not necessarily main.
• --include <types> (optional): Comma-separated content types (default rules,context,skills): rules,context,skills,agents,commands
• --merge-strategy <strategy> (optional): Merge strategy: local-override (default), include-override, or error
• --install-to <path> (optional): Installation target path in .ai-rulez/
• --local (optional): Add the include to the machine-local config.local.* overlay instead of the shared config

A local source in the shared config must resolve inside the project, the same check the loader applies, so a path outside it is refused when it is added (use --local for a path that leaves the project). A URL with a credential in its userinfo (https://user:token@host/...) is refused: the credential would be written in clear into the committed config.toml, so include add and skill install stop with the URL redacted and never write the secret. Keep the URL free of secrets and authenticate with the git credential helper or the AI_RULEZ_GIT_TOKEN environment variable (sent as a scoped git header, never stored); an SSH remote (git@host:org/repo.git) carries no credential. An existing credentialed source is reported by validate/scan as AR035 (see Strict validation). include remove and skill remove edit config.toml directly without loading the project, so an include that keeps the project from loading can always be removed.

Examples:

Add a git-based include:

ai-rulez include add corporate-rules https://github.com/myorg/shared-rules

Add with custom path and ref:

ai-rulez include add shared-patterns https://github.com/myorg/repo --path .ai-rulez --ref develop

Add local include:

ai-rulez include add backend-package ./packages/backend

ai-rulez include remove <name> [flags]¶

Remove an include source.

Syntax:

ai-rulez include remove <name> [flags]

Arguments:

• <name> (required): Include name to remove

Flags:

• --yes / -y (optional): Skip confirmation
• --local (optional): Remove through the config.local.* overlay. An include defined in the shared config is hidden on this machine with remove = true

Examples:

ai-rulez include remove corporate-rules
ai-rulez include remove shared-patterns --yes

ai-rulez include list [flags]¶

List all include sources.

Syntax:

ai-rulez include list [flags]

Flags:

• --format text|json (optional, default text): json prints JSON.

Examples:

ai-rulez include list
ai-rulez include list --format json

Profile Management¶

Organize domains into named profiles for targeted generation.

ai-rulez profile add <name> <domains...> [flags]¶

Create a new profile.

Syntax:

ai-rulez profile add <name> <domains...> [flags]

Arguments:

• <name> (required): Profile name
• <domains...> (required): Space-separated list of domain names to include

Flags:

• --set-default (optional): Set this as the default profile
• --local (optional): Define the profile in the machine-local config.local.* overlay. It may reference local domains

Examples:

Create a backend profile:

ai-rulez profile add backend backend qa

Create and set as default:

ai-rulez profile add full backend frontend qa --set-default

ai-rulez profile remove <name> [flags]¶

Delete a profile.

Syntax:

ai-rulez profile remove <name> [flags]

Arguments:

• <name> (required): Profile name to remove

Flags:

• --yes / -y (optional): Skip confirmation
• --local (optional): Remove a profile defined in the overlay. A profile from the shared config cannot be removed locally (error)

Examples:

ai-rulez profile remove staging
ai-rulez profile remove development --yes

ai-rulez profile set-default <name> [flags]¶

Set a profile as the default for generation.

Syntax:

ai-rulez profile set-default <name> [flags]

Arguments:

• <name> (required): Profile name to set as default

Flags:

• --local (optional): Set default in the machine-local overlay instead of the shared config

Examples:

ai-rulez profile set-default full

ai-rulez profile list [flags]¶

List all profiles.

Syntax:

ai-rulez profile list [flags]

Flags:

• --format text|json (optional, default text): json prints JSON.

Examples:

ai-rulez profile list
ai-rulez profile list --format json

Local Configuration¶

Machine-local configuration has two layers: the .ai-rulez/local/ content tree (managed with --local on add, remove and list) and the config.local.toml overlay (managed with ai-rulez local and --local on the config commands). The full guide is Local Configuration; this section is the command reference.

ai-rulez local <subcommand>¶

Manage config.local.toml, the machine-local overlay merged onto the shared config at load time. It sits beside config.toml, is gitignored, and is never written into the shared file.

ai-rulez local init                     # commented config.local.toml skeleton
ai-rulez local show [--format json] [--reveal] # keys the overlay sets, with the shared value each replaces
ai-rulez local set <path> <value>       # value is a TOML literal, falling back to a plain string
ai-rulez local set <path> --stdin       # read the value from standard input
ai-rulez local unset <path>
ai-rulez local path

The subcommands honour the global --config / -C and their own persistent --config-dir.

Paths are dotted keys. For lists of named entries (mcp_servers, plugins, includes, installed_skills, marketplaces, scopes) the segment after the list is the entry name. A segment that contains a dot is written in brackets with double quotes:

ai-rulez local set default dev
ai-rulez local set presets '["codex", "!cursor"]'
ai-rulez local set mcp_servers.github.command npx
ai-rulez local set 'mcp_servers["foo.bar"].command' npx
printf %s "$GITHUB_TOKEN" | ai-rulez local set mcp_servers.github.env.GITHUB_TOKEN --stdin

Pass secrets with --stdin, not as an argument, so they stay out of shell history and the process list.

Every change is validated against the local schema and the merged config (offline: remote includes are read from cache only) and rolled back if it is invalid. A new MCP server must have a command or url. Edits take an advisory lock (.config.local.lock) so two commands cannot interleave.

local show is default-deny: it prints values only for keys known to hold no credentials (name, description, default, presets, gitignore, compact, builtins, profile names, the enum and bool settings under defaults, rules and header (style, hashes, timestamp, mcp_line, nested), an entry's own transport, enabled and remove, mcp.self_server, mcp.self_server_version, mcp.skills_instructions); every other key is listed by path with <redacted>, on both the overlay and the shared side. --reveal prints everything.

local set stores values under env/headers and known text fields (url, command, source, path, ref, description, name, transport, default, *_version) as strings; --string forces a string and --stdin reads the value from standard input so a secret stays out of shell history.

The overlay is written owner-only (0600) through a temp file and rename, and local refuses to replace a symlinked config.local.*. On Windows the file mode is not enforced by the OS, so rely on your user profile directory permissions there; the advisory lock is also not taken.

The --local flag on profile add|remove|set-default, include add|remove and skill install|remove writes to the overlay instead of the shared config. Removing a shared include or installed skill writes remove = true for it; profile remove --local of a shared profile is an error ("Shared profiles cannot be removed locally"). The MCP tools update_config, add_profile, remove_profile, set_default_profile, add_include, remove_include, install_skill and uninstall_skill accept local: true.

Local overrides and generate¶

When a config.local.* overlay or local/ content exists, generate also renders the shared baseline (the config as a teammate without them sees it) and compares:

• local-only files exist only because of your local config (an extra preset, local content). They are git-ignored (*.local.* names through the managed .gitignore block, other names through .git/info/exclude) and listed in the gitignored .ai-rulez/.generated-manifest.local.json, never in the committed manifest. Generation stops, listing paths only, if such a file is tracked by git.
• drift files are shared outputs your local config would change. Generation stops, listing paths only, if such a file is tracked by git or not ignored; pass --allow-local-drift to write it anyway.
• suppressed files are shared outputs your local config no longer produces (for example a preset dropped with "!claude"). They are left alone, never deleted.

.git/info/exclude is per clone and shared by linked worktrees, so each project gets its own block, delimited by # BEGIN ai-rulez local: <absolute config dir> / # END ... and anchored at the repository root; generate only ever rewrites its own block, removes it once the project has no overlay-derived outputs, and never touches other lines or other projects' blocks. Paths git's exclude file cannot hold (and every path outside a repository) go to the managed .gitignore block instead, with a warning.

Whether a path is tracked or ignored is asked of git in one call each; if git fails inside a repository the guard assumes every affected file is tracked and refuses. If a .gitignore rule un-ignores a machine-local or secret-bearing output, the overlay or the local/ tree, or .gitignore is a symbolic link (entries then go to .git/info/exclude), see Local overrides; the run is refused with the paths listed when something would stay committable. --allow-local-drift is command-line only (MCP clients cannot pass it) and can write non-secret overlay values into files that are tracked and shared, so review git diff before committing. It does not bypass the secret guard: a generated MCP config that would carry resolved secrets (env, headers, URL credentials, secret flags) is still refused unless it is git-ignored.

Shared outputs keep the baseline hashes, so your headers match a teammate's; local-only outputs carry a hash of their local inputs. generate --dry-run prints local-only:, drift:, allowed: (a drift file that is git-ignored), suppressed: and blocked: lines, and exits non-zero when any line is blocked: (the real run would refuse). A run with --no-local (or generate --plugin, which never uses local config) does not delete your local files.

Builtins Command¶

ai-rulez builtins list [flags]¶

List all built-in domains embedded in the ai-rulez binary.

Flags:

• --format text|json (optional, default text): json prints JSON.

ai-rulez builtins show <name> [flags]¶

Show the full rules, context, skills, agents, and commands for a built-in domain. The item names are the identifiers builtins accepts as <domain>/<name> (load only that item) and !<domain>/<name> (drop it).

Arguments:

• <name> (required): Built-in domain name, such as security, go, or typescript

Flags:

• --format text|json (optional, default text): json prints JSON.

Convert Command¶

ai-rulez convert¶

Read another tool's configuration and produce an equivalent .ai-rulez/ tree, with a report that lists every input construct as mapped, approximated, dropped, needs-action or unsupported. It never modifies the source files, never runs anything, uses the network only with --fetch, and writes nothing unless --write is given.

ai-rulez convert --dry-run                        # what would carry over, and what would be lost
ai-rulez convert --write                          # write .ai-rulez/
ai-rulez convert --from native,skills-lock --write
ai-rulez convert --from rulesync --dry-run        # import a rulesync project
ai-rulez convert --from apm --write --fetch --lock  # import an APM project with its remote packages, then pin
ai-rulez convert --from tessl --write             # vendored Tessl plugins and their eval scenarios
ai-rulez convert --from okf --write --domain kb   # an OKF bundle, into a domain
ai-rulez convert --write --merge                  # add beside an existing tree, keeping every file of it
ai-rulez convert --write --enable-hooks           # imported hooks live (they are commented out by default)
ai-rulez convert --dry-run --format json --report convert.json
ai-rulez convert --write --domain imported        # import beside an existing tree
ai-rulez convert --list                           # importers and what each detects here

Flags:

Importers:

config.toml is merged, never replaced, with or without --force: new presets, [[mcp_servers]] and [[installed_skills]] are appended (existing entries win; a differing imported entry of the same name is a needs-action finding), and the file is rewritten with the config writer, which does not keep comments. When nothing is new it is unchanged and untouched. A V3 config (config.yaml, config.yml, config.json), which ai-rulez no longer reads, is left alone and reported as manual; a config.toml that cannot be parsed stops the run. When nothing identifies a preset and the config already has presets, none is added.

Rule frontmatter is translated, not copied: Cursor alwaysApply/globs/description, Copilot applyTo, Kiro inclusion/fileMatchPattern, Devin and Windsurf trigger, and paths become activation, globs and description; any other key is reported as dropped. A Cursor rule with alwaysApply: true and globs is always on, so its globs are dropped (approximated). Frontmatter that is not valid YAML as written (an unquoted globs: **/*.ts) is read leniently with block scalars and lists intact, and reported as approximated. Skills, agents and commands are copied with their frontmatter, and every key ai-rulez has no field for (Claude color, permissionMode; Copilot handoffs, target, mode, agent; ...) is reported as approximated, because only presets that copy unknown keys render it; a comma-separated Claude tools string becomes a list. The name: of a SKILL.md follows its directory when the directory is renamed to a valid name or suffixed after a collision. A name with no ASCII letters or digits (日本語) gets a stable derived name (unnamed-<hash>), reported as approximated. Presets are inferred only from files one tool owns (.cursor/rules implies cursor, .windsurf implies devin, .roo implies zoocode); shared files such as AGENTS.md and .agents/skills imply none, and with no other evidence claude is used and reported. A command file convert imported (.claude/commands/daily.md) is removed by the first generate once the generated .claude/skills/daily/SKILL.md replaces it and the file and its copy under .ai-rulez/commands/ are both unchanged since the import, so the command does not appear twice; clean writes it back from that copy as it removes the skill. An edited file stays, and a skill whose command cannot be written back byte for byte is kept by clean. A root file that is a symlink onto an imported AGENTS.md (CLAUDE.md -> AGENTS.md) is not imported, but codex (which writes AGENTS.md) and the preset the link name implies (claude) are added, so the first generate writes AGENTS.md and keeps the link. Files ai-rulez generated are never read back as source: the AI-RULEZ :: header, the GENERATED FILE and Generated by ai-rulez banners (also in skill resource files), the Content-Hash and Source-Hash lines, and every path in .ai-rulez/.generated-manifest.json are skipped with a dropped finding, as are root files that only contain an @path pointer. A path that exists but cannot be read (permissions, a symlink, an invalid .claude/settings.json) is reported as dropped with the error, never silently ignored. Identical content found in several files (for example CLAUDE.md and AGENTS.md) is imported once; different content under one name gets a stable hash suffix.

A root file such as CLAUDE.md or AGENTS.md becomes a context file. Frontmatter keys no tool reads (title, applies_to, updated) are kept under metadata: so validate does not report them as AR303, and the report lists them as approximated.

When native and skills-lock run together, skills named in skills-lock.json are imported only as [[installed_skills]], not copied from .agents/skills. The lock's computedHash is never carried (its scheme differs from the ai-rulez.lock tree digest) and is reported as needs-action; run ai-rulez lock after converting. node_modules and local skill sources are unsupported; global skill locks are out of scope. A lock source must be an https://, ssh:// or git@host:path URL: a leading -, a transport helper such as ext::, file://, git://, plain http:// and URLs with embedded credentials are unsupported, as are a ref starting with - and a skillPath that is absolute or contains ... The planned installed_skills go through the same field validation as at config load, without any network access.

MCP servers keep command, args, env, url, headers and transport. Every string is checked with the security scan's secret detectors: a literal under a credential-looking name (*_KEY, *_TOKEN, Authorization, ...), a recognised token or key in any value whatever its name, a connection string with a password, --api-key x and --token=x style arguments (and KEY=value arguments), URL userinfo and credential query parameters are replaced by a ${VAR} reference and reported as needs-action; the value is never printed or written. Only an exact $VAR or ${VAR} (upper case) counts as an existing reference. The scan of the planned tree also reads config.toml, so a secret that gets through (for example in a description) blocks the write.

Hooks and permissions¶

Hooks and permission rules of the tool files above (and of rulesync's hooks.jsonc and permissions.jsonc) become [[hooks]] and [permissions]. Imported hooks are never enabled by the importer: a hook runs a command on your machine, and an allow rule widens what every harness may do (the rule was written for one tool, [permissions] renders into all of them).

A comment is inert to every ai-rulez command, so nothing runs until you remove the leading #. The scan and validation cover the commented text too: a hook with a secret or a curl | sh blocks the write, and an invalid hook is a validation error, enabled or not. A second run does not repeat a block config.toml already holds; into an existing config, live hooks and rules are added when not already declared.

Each hook group keeps the harness it came from in targets, so a hook that ran in one tool does not start running in the others; a matcher written in a tool's own vocabulary (Gemini run_shell_command, Cursor Shell) is kept as matchers.<harness>. The same hook found in several tools' files is declared once for all of them. Event names are translated to Claude Code's (Gemini BeforeTool is PreToolUse, Cursor beforeSubmitPrompt is UserPromptSubmit, rulesync sessionStart is SessionStart); millisecond timeouts become seconds (rounded up); command, args, timeout, async, if and statusMessage are carried. Anything else is reported, never guessed:

• an event with no ai-rulez hook event (Cursor afterFileEdit, rulesync beforeShellExecution) is unsupported, listed;
• a handler that is not a command (prompt, http, agent, mcp_tool) is unsupported; handler keys with no equivalent (shell, env, failClosed, ...) are dropped, listed;
• the guard hook ai-rulez writes itself (ai-rulez guard) and .github/hooks/ai-rulez.json are not read back as source;
• a command that runs a script of the rulesync tree (.rulesync/hooks/...) or of a package (${CLAUDE_PLUGIN_ROOT}) is needs-action: copy the script into the project and use a script path;
• hooks declared inline in .codex/config.toml are needs-action (move them to .codex/hooks.json);
• rulesync per-tool blocks for tools without a hook harness are unsupported.

Permission rules are Claude Code rules: .claude/settings.json permissions.allow|ask|deny verbatim (defaultMode, additionalDirectories and other keys are dropped); rulesync permission.<category>.<pattern> = action becomes Tool(pattern) (bash is Bash, write and notebookedit path rules Edit, a bare * pattern the bare tool; a category * is unsupported; tool-scoped blocks such as claudecode.permission are dropped); Cursor .cursor/cli.json rules are rewritten (Shell to Bash, Shell(cmd:args*) to Bash(cmd args:*) and Shell(cmd:args) to Bash(cmd args), Write to Edit, Mcp(server:tool) to mcp__server__tool, approximated); a deny whose arguments hold an inner glob is widened to its literal prefix, an allow of that kind is unsupported, and the rules a previous generate wrote into cli.json (named by the manifest) are dropped as generated. Gemini's tools.allowed/exclude and Codex's .codex/rules are unsupported rather than inverted. Other keys of .claude/settings.json (model, env, statusLine, ...) are dropped, one finding each.

Merging, names and delivery¶

--merge is for adding to a project that already has content: every existing file is left byte for byte, and an item whose path is taken by other content is written as NAME-imported (a skill's name: follows; the report's finding names both). The suffix is reused when the file it chose last time is still there, so a second run changes nothing. config.toml is merged as always. With --keep-names nothing is renamed: under --merge the collision stays a conflict (exit 1), and between imported items it is an error naming both sources. --force and --merge exclude each other.

--delivery writes the default for the imported skills. [skills] delivery is the default of every skill, including ones already in the project, so prefer --domain NAME (writes [domains.NAME] delivery) next to an existing tree.

Fetching remote sources¶

--fetch reads the git sources an input names but does not hold: rulesync sources (github and git transports; the npm transport is unsupported) and APM dependencies that are not installed. It uses the skill-source fetcher ([[skill_sources]]: the same clone size and file limits, cache and credential rules), only for https:// URLs; http://, git://, file://, ssh, URLs with credentials, and paths that leave the repository are unsupported before any request is made. A lock file of the input (rulesync.lock, apm.lock.yaml) decides which commit is read.

Everything fetched is planned like any other input: copied text is scanned in the planned tree, and the text of the skills that are referenced rather than copied is scanned as well, under the name host/owner/repo@<commit>:path. A blocking finding exits 2 and writes nothing. A failed fetch, or a resolved commit that is not a full hash, stops the run with nothing written. --dry-run --fetch fetches (the cache is filled) and writes nothing. Pass --lock to pin the installed skills in ai-rulez.lock right after the write.

APM¶

--from apm reads a Microsoft APM project. The layout is read from the public documentation and from rulesync's APM-compatible reader, not verified against a release of apm.

Tessl¶

--from tessl reads tessl.json and the vendored plugins under .tessl/plugins/<workspace>/<plugin>/ (a version directory below it is found by the version tessl.json names, or when it is the only one). The layout follows the Tessl documentation and is not verified against a release. Nothing is fetched from the registry: a dependency that is not on disk (mode managed, or not vendored) is needs-action; run tessl install and convert again, or point --source at a populated directory. A project that is itself a plugin (.tessl-plugin/ at its root) is read the same way.

OKF¶

--from okf is import okf through convert: the same bundle mapping (see OKF), with the lossiness report, the scan before write and --domain. A bundle is found at the source root or in docs/okf. Findings of the bundle (lossy links, skipped files) become report findings. A skill's script keeps its executable bit, here and in the native, rulesync and APM importers.

rulesync¶

--from rulesync reads a rulesync project. The layout follows rulesync's own source (docs/reference/file-formats.md, src/constants/rulesync-paths.ts); rulesync.jsonc is parsed as JSONC (comments, trailing commas). A rulesync.jsonc that cannot be parsed stops the run with AR9F0.

A later entry of inputRoots overrides a same-named item of an earlier one (approximated); roots that are absolute or leave the source directory are unsupported. Anything under .rulesync/ that is not a rulesync input is dropped.

Design decisions. Root rules become context, not priority: critical rules, because context is what ai-rulez writes into every root file. localRoot rules go to the machine-local tree, since they are personal and the rest of the output is committed. A tool section is never merged into the item, so a per-tool override cannot silently widen to every tool; the few lifted keys are reported. native is skipped by auto next to rulesync so generated files are not imported twice. Hooks and allow rules are written disabled (open question 5 of the design, decided as proposed: never enabled automatically).

First generate after convert. convert --write records the native files it imported (and root files that only hold an @path pointer) with their SHA-256 in .ai-rulez/.converted.json. The first generate replaces those files without --force as long as they are unchanged since; a file convert did not import still stops generate (see Existing files). clean keeps the generated file that replaced such an original. Commit the record with .ai-rulez/.

Blocked scan. When the scan finds an error-level problem (a secret, a risky command), convert prints each finding at the source file and line it came from (.rulesync/rules/x.md:33), with the planned .ai-rulez/ path in parentheses, exits 2 and writes nothing. Remove the text from the source and run again. To write anyway, pass --allow-findings AR001 (repeatable, comma separated): the finding stays in the report, marked allowed, and only that code is let through. Findings in the generated config.toml keep their planned path. In --format json the source location is file/line and the planned one is planned.

Safety: the planned tree is loaded and security-scanned (the AR0xx family of validate) in a scratch directory before anything is written. A blocking finding or a validation error exits 2 with AR9F5/validation messages and writes nothing; the security findings are reported even when validation fails, and inline ai-rulez-lint-ignore comments in converted text are not honoured. Writes are atomic per file; if one fails, every file written so far is restored or removed, the directories the run created are removed, and anything that could not be undone is named in the error.

Report codes: AR9F1 approximated, AR9F2 dropped, AR9F3 needs-action, AR9F4 unsupported, AR9F5 blocked by the scan; AR9F0 marks an input file that cannot be parsed at all and appears only in the error that stops the run. They have their own range, apart from the AR9E0-AR9E4 scanner codes, and appear in the convert report only; validate does not emit them.

Exit codes: 0 done (the report may contain losses) or nothing to convert, 1 could not run or would overwrite existing files, 2 blocked by the scan or validation, or --fail-on matched.

Nothing to convert. When no importer finds anything to import (no tool files, or only files ai-rulez generate wrote), convert prints Nothing to convert: ... with a hint, writes nothing and exits 0, so a script converting many repositories keeps going. With --format json the message goes to stderr and stdout carries an empty report (written: false, no files) that validates against the report schema.

init --from¶

ai-rulez init --from runs convert --write with its sources: importer names (auto, native, rulesync, ...) or the project paths it always took (.claude, .cursor, CLAUDE.md), which limit the native importer to those paths. The sources are checked in a scratch directory first, so a source that cannot be imported, or a blocked scan, leaves an existing .ai-rulez/ alone. When you confirm replacing an existing configuration directory (or pass --force; --yes only skips prompts and never replaces one), it is moved aside to <dir>.bak-<timestamp> while the import writes and restored if the write fails; after a successful import it stays there as the backup. Compared with the engine it replaced: a root file such as CLAUDE.md is one context item (convert --split-headings splits it), and MCP files, hooks and permissions are imported, with the report printed. import okf stays as the direct entry point to the OKF mapping; convert --from okf is the same mapping with convert's report.

Initialization Command¶

ai-rulez init [project-name]¶

Initialize a new directory-based configuration. It writes .ai-rulez/config.toml and an OKF bundle around it: example concepts with type, title and x-ai-rulez frontmatter, and an index.md per directory (the root one names okf_version).

An existing configuration directory is never deleted. init refuses unless you pass --force (or answer yes at the prompt), and then moves the old directory to <dir>.bak-<timestamp> first; if creating the new one fails, the old directory is moved back. --yes only skips prompts; it does not replace an existing directory.

Syntax:

ai-rulez init [project-name] [flags]

Arguments:

• [project-name] (optional): The project name. If omitted, the current directory's base name is used (falling back to MyProject). Nothing is prompted.

Flags:

The global --config-dir (default .ai-rulez; use .config/ai-rulez for the .config/ convention) names the directory to scaffold. The created directory is printed on stdout; the file listing and next steps go to stderr, where -q hides them. The replace prompt is on stderr.

With --source agents, init writes .agents/ai-rulez.toml (or config.toml with source = "agents" in the directory --config-dir names) and a starter AGENTS.md when the project has none. It scaffolds no content directories and never moves .agents aside: an existing configuration file is replaced only with --force, which keeps it as <file>.bak-<timestamp>. --from then converts the named tool files into .agents (the same as convert --into .agents).

--setup-hooks detects an existing lefthook, pre-commit, or husky setup and adds ai-rulez to it in place; if none of the three is present it logs a message and does nothing rather than failing. The two YAML configurations (lefthook.yml, .pre-commit-config.yaml) are edited node by node, so existing comments, key order and indentation width survive. Husky has no configuration file to preserve — the validation step is appended to .husky/pre-commit. Re-running is a no-op once ai-rulez is already wired in.

ai-rulez is safe to run inside a git hook. Git exports GIT_DIR, GIT_INDEX_FILE and related variables to hooks, which would make every nested git call act on the hook's repository; ai-rulez removes GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, GIT_COMMON_DIR, GIT_PREFIX, GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES and GIT_NAMESPACE from the environment of every git subprocess it starts (and of telemetry sink commands) and targets repositories only with an explicit -C. The generated config lists the built-in presets in a comment (ai-rulez init --help prints them too) and enables claude. Add the harnesses you use to presets; all 52 and what each supports are in Supported harnesses. The former windsurf preset is devin, and continue-dev is removed.

General Flags:

Examples:

Basic initialization:

ai-rulez init "my-project"

V4 with multiple domains:

ai-rulez init "my-project" --domains "backend,frontend,qa"

With example content skipped:

ai-rulez init "my-project" --skip-content

Scaffold the project-level .config/ convention instead of .ai-rulez/:

ai-rulez init "my-project" --config-dir .config/ai-rulez

Generate Command¶

ai-rulez generate¶

Generate AI assistant rule files from configuration.

Syntax:

ai-rulez generate [flags]

Generation Flags:

General Flags:

--token / -T is a global flag (see Global Flags); it is not generate-specific. --update-gitignore, --no-configure-cli-mcp and --skip-cli-mcp were removed in v5 (use --gitignore; the others had no effect).

--dry-run lists each file as write-file: (it would be written), unchanged: (already current) or edited: (changed by hand; generate overwrites the edit).

Before writing, generate also prints a summary of hook commands (the SessionStart hook of [session_start] included), command-based MCP servers, [permissions] allow rules and other command-bearing settings that are new or changed since the previous run on this machine (all of them in a fresh clone), even with --quiet. It only warns; --yes or AI_RULEZ_ACK_COMMANDS=1 silences it. The MCP generate_outputs tool returns the same summary as new_commands. With --watch the summary is printed on each regeneration (what is new since the previous run), so a hook or MCP command that arrives with a pulled change is shown by the run that writes it.

Exit codes: 0 written, 1 a configuration failed to load, validate or generate (every root of a --recursive run is still processed), 2 --check found drift or --locked/--frozen found an authored source that differs from the lock (also a recursive run where every failure is lock drift). See Exit Codes.

Detecting drift¶

Teams that commit generated files can gate CI on generate --check. It renders in memory, never writes or deletes, and prints one line per file that differs:

With a machine-local overlay or local/ content, --check classifies the outputs like generate does, so files that generate keeps for the local inputs and that are in sync are not reported. --check does not print the summary of rules whose activation a tool cannot express; generate prints it.

Exit codes: 0 nothing differs, 1 the check could not run (configuration invalid, a nested root failed to load, or an environment variable an MCP server references is unset: --check renders the outputs and needs the same secrets as generate), 2 at least one file differs. A trailing-newline-only difference is not reported, because generate normalizes it. With [header] hashes = "none" there is no hash to compare, so every difference is stale. --check cannot be combined with --dry-run, --plugin (use verify --plugin) or --gitignore.

With --recursive the roots are compared concurrently (at most GOMAXPROCS at a time) over one shared listing of the git index, and the differing files and errors are reported in root order, so the output and exit code do not depend on which root finishes first. A [n/N] path (time) line per root goes to stderr; --quiet and --format json silence it.

Watch mode¶

generate --watch generates once, then keeps running and regenerates whenever the sources change. It watches .ai-rulez/ recursively (subdirectories created later included), the machine-local overlay files, the config file, and every includes / local_override source that is a local path. Remote includes are not polled.

• Changes are debounced for 300 ms, so a save storm or git checkout produces one run.
• Runs never overlap. A change that arrives during a run triggers exactly one more run afterwards.
• Generated output, the generated manifests and editor swap/backup files (*.swp, *~, .#*, 4913, ...) never trigger a run.
• Every regeneration runs the same preflight as a one-shot generate, including the summary of new hook and MCP commands.
• A configuration that fails to load or validate is logged and watching continues, so you can fix it and the next save regenerates.
• If .ai-rulez/ is deleted and re-created (for example by switching branches), it is watched again.
• SIGINT / SIGTERM stop it cleanly, after any run in progress finishes. The first one cancels the run in progress; a second Ctrl-C kills the process immediately.
• Files the previous run recorded as generated (the manifests list them) never trigger a run, even when an include source is a tree that also holds outputs. Editor and VCS names (.git, node_modules, swap files) are ignored below the watched root only, so a project that itself lives under a node_modules directory is still watched.
• Symlinked watch roots and symlinked subdirectories are followed (a link back to a parent directory is not).
• A local include removed from the configuration stops being watched after the next run.
• If the operating system refuses to watch a directory (a limit such as fs.inotify.max_user_watches on Linux, or the open-file limit on macOS and BSD), one warning per run says so, with the hint to raise the limit; changes in the directories that could not be added are not noticed.

--watch cannot be combined with --dry-run, --check, --user, --plugin or --recursive; it watches one configuration and writes on every change. Other flags (--profile, --no-local, --env, ...) apply to every run.

Examples:

Generate with default profile:

ai-rulez generate

Generate specific profile:

ai-rulez generate --profile backend

Dry-run to preview generation:

ai-rulez generate --dry-run --profile backend

Generate and maintain the managed .gitignore block (opt-in):

ai-rulez generate --profile full --gitignore

Generate MCP configs with secret env values:

ai-rulez generate --env GRAFANA_SERVICE_ACCOUNT_TOKEN="$GRAFANA_SERVICE_ACCOUNT_TOKEN"

Package the project as distributable plugin bundles:

ai-rulez generate --plugin

Generate recursively in monorepo:

ai-rulez generate --recursive

Every discovered root is processed and all errors are printed; the exit status is 1 if any root failed to load, validate, or generate (also with --dry-run). With --profile, a root that does not define the named profile fails with a profile not found error for that root rather than falling back to default content.

Generate from a non-default configuration directory:

ai-rulez generate --config-dir ai-policy

Generate with private repository authentication:

# Using environment variable (recommended)
export AI_RULEZ_GIT_TOKEN="ghp_your_github_token_here"
ai-rulez generate

# Using CLI flag
ai-rulez generate --token "ghp_your_github_token_here"

Embedding the plan¶

generate --emit-plan FILE renders everything in memory and writes the result as JSON, without writing, deleting or git-ignoring anything. Go code can get the same value from generator.PlanOutputs(ctx, cfg, generator.PlanOptions{Profile, Role}); config.WithHost injects the environment, clock, process runner and logger of the load (the zero host is the real process).

ai-rulez generate --emit-plan plan.json --profile backend

The document follows schema/plan.schema.json:

• files: every output sorted by path, with action (write, merge into a document the consumer owns), mode, and the size and sha256 of the content generate writes, minus the header's Generated: stamp and hash lines (so with [header] hashes = "none" and no timestamp the digest is that of the file on disk).
• removals: files an earlier run recorded and this one no longer renders (stale), and documents ai-rulez takes its earlier entries out of (unmerge, delete).

The plan is deterministic and holds no secret: MCP placeholders such as ${TOKEN} stay as written, and an output that may carry a secret (sensitive), or whose content holds a credential the security scan detects, has no digest. It is conservative about that flag, so a plan may call a document sensitive that a real run finds clean. It reads the project the way a run does (the previous manifest, merged documents) and honours --profile, --role and --no-local; it runs the read-only part of the generate preflight (the schema check, --strict-config, and the role selection warnings) and records nothing, so a later run still warns about new commands. --emit-plan is refused with --watch, --check, --user, --recursive and --plugin, which never reach the plan or render something else. The plan lists neither the .gitignore update nor the .ai-rulez/.generated-manifest.json record generate writes: it covers rendered outputs and removals only.

Design decisions:

• generate is not yet built on the plan. PlanOutputs and generate share the rendering code (collectOutputs, the stale and unmerge planning); the write path still interleaves side effects (gitignore, secret guards) with writes, and splitting it is a separate change guarded by tests/golden.
• The plan carries digests, not content, so it stays small and cannot leak. Callers that need bytes render through generate.
• renderer is the generator's render-schema version: a renderer change changes digests, and the plan says so.

Profile Selection¶

When using profile-based configuration:

1. No --profile flag: Uses default profile from config
2. --profile backend: Generates content for the backend profile
3. Invalid profile: Shows error and lists available profiles

Example with profile hierarchy:

# .ai-rulez/config.toml
default = "full"

[profiles]
full = ["backend", "frontend", "qa"]
backend = ["backend"]
frontend = ["frontend"]

# Uses "full" profile (default)
ai-rulez generate

# Uses "backend" profile only
ai-rulez generate --profile backend

# Uses "frontend" profile only
ai-rulez generate --profile frontend

Clean Command¶

Existing files generate will not overwrite¶

generate replaces a file only when it can prove ai-rulez wrote it: the file carries a Content-Hash or a generated banner, its bytes already equal the rendering, the generated manifest lists it and it carries a banner or matches the digest this machine recorded for it, or convert --write imported it and it is unchanged since (.ai-rulez/.converted.json records the digest of each imported file). Any other existing file at an output path, such as a hand-written CLAUDE.md in a repository you just ran init in, stops the run before anything is written: exit 1, naming the file with the way out. Import it with ai-rulez convert --write, move or delete it, or pass --force to overwrite it. --dry-run prints blocked: CLAUDE.md (an existing file ai-rulez did not write) and exits non-zero; --check lists the path as blocked. An output whose path crosses a symlink leading out of the project (a .cursor folder linked elsewhere) is refused the same way, before any file is written or removed. init warns when a hand-written CLAUDE.md, AGENTS.md or GEMINI.md already exists and points at convert --write; --check names the same remedy instead of telling you to run generate. A manifest-listed file whose rendering carries no generated header (JSON, the Codex agent TOML) and that this machine recorded no digest for (an older ai-rulez wrote it, or the checkout is a fresh clone) is replaced with a warning; once it differs from the recorded digest it counts as hand-edited and is refused like any other unprovable file. clean applies the same proof and, where generate only warns, keeps the file. Rule folders keep their own guard (a hand-written rule file is skipped with a warning, or the generated rule is renamed), merged settings documents are merged into, and an empty file is replaced. generate --user applies the same proof to the files under your home directory.

A symlinked output is never written through. CLAUDE.md -> AGENTS.md is accepted when AGENTS.md is itself generated in the same run: the link stays as you made it, AGENTS.md gets its own content, and the link is not recorded as generated (so clean leaves it). A link to anything else is refused, naming the link and its target; remove the link, or point it at a generated path.

ai-rulez clean¶

Remove the files and directories that generate produced — the inverse of generate. This deletes the generated assistant outputs (CLAUDE.md, AGENTS.md, GEMINI.md, .claude/, .codex/, generated skills, etc.), the generated manifest (.ai-rulez/.generated-manifest.json), the local manifest (.ai-rulez/.generated-manifest.local.json) and the local rule files recorded in it, this project's block in .git/info/exclude, and the ai-rulez managed block in .gitignore. The ignore entries for the config.local.* overlay and .ai-rulez/local/ stay in .gitignore: clean removes generated outputs, not the machine-local sources beside them. The committed manifest is treated as untrusted (see What ai-rulez may change): generate and clean delete a manifest-listed file only when its path is one a preset writes and the file proves it is ai-rulez output (its Content-Hash matches its body, or its SHA-256 equals the digests entry this machine recorded in the gitignored local manifest for header-less files). Anything else is kept and reported in one Stale files not removed warning per reason that names the files; on a fresh clone a header-less stale file is therefore reported, not deleted. On an upgrade, the Claude MCP servers an older version wrote into a manifest-listed .claude/settings.json are taken out of it when they are exactly that rendering (they now live in .mcp.json only). A generated file whose body was edited by hand is kept with a warning unless --include-edited is given (generate rewrites it instead). The generated file that replaced an original convert imported (listed in .ai-rulez/.converted.json) is kept as well, even with --include-edited: the original text lives under .ai-rulez/, and removing it would leave neither; delete it by hand if you no longer want it. A symlink is never removed, whoever made it. A merged settings document (.claude/settings.json, .mcp.json, ...) is deleted only when this machine recorded writing it whole and its digest still matches; a document that existed before ai-rulez first wrote to it is never deleted. Neither generate nor clean removes a path whose parent directory resolves through a symlink outside the project. Manifests written by older versions have no digests, so their header-less leftovers stay until deleted by hand. In a project with a [plugin] block or a plugin marketplace, clean also removes the bundle generate --plugin wrote: each file whose bytes still equal what generate --plugin renders, and the folders that leaves empty; an edited bundle file is kept with a warning. clean has no --recursive: run it in each root. It never needs MCP secrets: unset ${VAR} placeholders do not stop it. A git-tracked .ai-rulez/.generated-manifest.local.json is ignored by generate and kept by clean, with a warning to git rm --cached it.

The .ai-rulez/ source tree is never touched. Generated directories are only removed once they are empty, so any files you authored inside a generated directory are preserved.

Settings documents you share with ai-rulez (.claude/settings.json, .gemini/settings.json, opencode.json, .mcp.json, ...) are not deleted: clean removes only the keys, MCP server entries and array elements ai-rulez merged into them (including a stale entry that holds a resolved secret), and deletes the file only when nothing else is left. The plan lists them as remove ai-rulez keys from:. See Settings documents shared with you.

By default clean lists what it will remove and asks for confirmation. In non-interactive shells the prompt declines automatically and clean exits 1 without removing anything — pass --yes there.

Syntax:

ai-rulez clean [flags]

Flags:

Preview what would be removed:

ai-rulez clean --dry-run

Remove all generated files without a prompt:

ai-rulez clean --yes

Remove generated files but keep the .gitignore block and manifest:

ai-rulez clean --yes --keep-gitignore --keep-manifest

Verify Command¶

ai-rulez verify¶

verify checks signatures, approvals and provenance: --attestation (and --bundle, --skill, --sbom), --approvals, --self and --plugin. It does not report drift. Run generate --check to find generated files that differ from their sources (hand edits, deleted files and sources that changed since the last generate). A bare ai-rulez verify names no mode and exits 1 with that pointer; it used to compare the generated files with their own Content-Hash, which generate --check also covers. With --plugin, generated plugin bundles are checked against their provenance hashes.

Syntax:

ai-rulez verify (--attestation | --approvals | --self | --plugin) [flags]

Flags:

Verify the signed lock (exit 0 verified, 1 cannot run, 2 verification failed with an AR720 to AR727 code):

ai-rulez verify --attestation
ai-rulez verify --attestation --public-key release.pub --format json

Re-check the approvals recorded in the lock above the asserted level (--approvals): every signed approval against its attestation and the [[signing.trust]] entries for approvals, offline, and with --online every review-linked approval against the forge (the review still exists, still approves, and was made on content whose lock pin is the approved digest). Exit 0 every checked approval holds, 1 the check could not run (including a forge that cannot be reached), 2 an approval no longer holds (AR718). --format json follows schema/verify-approvals.schema.json. See Approvals.

ai-rulez verify --approvals
ai-rulez verify --approvals --online --format json

Verify one producer:

ai-rulez verify --plugin

Verify every plugin producer and marketplace in a repository:

ai-rulez verify --recursive --plugin --if-configured

Exit codes: 0 the bundle matches its sources, 1 the check could not run (invalid configuration, no plugin configuration, no mode given), 2 a bundle file is missing, stale, obsolete, a symlink, lost or gained its executable bit, unrecorded inside a generated skill directory, or fails its provenance hash. On drift, text output lists each drifted path with its kind (changed, missing, stale-source, obsolete, extra, symlink, mode) before the error. --plugin --format json prints {schema_version, status: ok|skipped|drift, configs, error?, drift?}, where drift is an array of {path, kind} (project-relative paths); the failure is also on stderr. stale-source names a provenance sidecar that no longer matches its bundle; mode names a file whose content is right but whose executable bit differs from the one generate --plugin sets (a hook or skill script that lost it in a zip round trip or under core.fileMode=false). verify --recursive --plugin reports the failure without a drift list.

When a [plugin] block exists but no bundle was generated, verify --plugin fails with plugin bundle not generated; runai-rulez generate --plugin`.--if-configuredonly skips a project with no plugin configuration; add--if-generated` to also skip until the bundle exists.

Recursive verification treats a marketplace root and its members as one atomic producer. Consumer-only plugin installation declarations are skipped. Missing authoring configuration is ignored only with --if-configured; stale, missing, or invalid generated outputs still fail verification.

Guard Command¶

ai-rulez guard¶

The harness runs this command, not people, but it is a normal listed command you can try by piping a payload into it. generate adds it as a PreToolUse hook when [guard] generated = true (Settings). It reads the hook payload (JSON) on stdin and checks the file the tool call edits against .ai-rulez/.generated-manifest.json and .generated-manifest.local.json.

Exit codes: 2 the call edits a generated file (the reason, with the source to edit, is on stderr); 0 everything else, including files merged into a settings document, paths outside the project, read-only tools and a payload that cannot be parsed. The guard fails open.

echo '{"tool_name":"Edit","tool_input":{"file_path":"AGENTS.md"}}' | ai-rulez guard; echo $?

Session-start Command¶

ai-rulez session-start¶

The harness runs this command, not people. generate adds it as a SessionStart hook to .claude/settings.json by default for a project that generates for Claude Code (Run generate when a remote session starts). In a remote session (CLAUDE_CODE_REMOTE=true) it runs generate, then prints the hook's additionalContext JSON on stdout; elsewhere it does nothing unless [session_start] when = "always". It always exits 0; a problem is one line on stderr.

echo '{"source":"startup"}' | CLAUDE_CODE_REMOTE=true ai-rulez session-start
ai-rulez session-start --when always --generate-mode plain

Doctor Command¶

ai-rulez doctor¶

Read-only diagnostics. It never writes, and reports each problem as an error, a warning or info.

ai-rulez doctor [--strict] [--format json] [--profile <name>] [--no-local]

With --debug, doctor logs one Doctor check finished line per check with its name and duration, to find the slow one.

When outputs cannot be rendered at all (for example because an MCP placeholder is unset), drift says so and the gitignore check is skipped; the mcp-env finding names the cause.

doctor never uses the network and never writes the include cache: it loads the configuration without resolving includes and installed skills. A project that declares them gets one info finding on drift saying the comparison was skipped (generate --check does it against the resolved content), and the gitignore check is skipped with it.

Exit codes: 0 no errors (and, with --strict, no warnings), 2 at least one finding at the failing severity, 1 doctor could not run: the configuration does not load at all (the config finding is still printed) or the report could not be written. The MCP server exposes the same checks as the read-only doctor tool, with URL credentials removed from every message, hint and path.

Cost Command¶

ai-rulez cost¶

Find what to trim. tokens reports the token surface per runtime and bucket; cost adds the per-item view: the biggest offenders among rules, context files, skills, agents and commands, split into what is paid on every request and what is paid only when an item is opened.

• Always loaded per item: a rule or context body (a path-scoped rule is conditional instead), or the name and description of a listed skill, agent or command plus the 27-token listing framing used by tokens (an item with disable-model-invocation: true is not listed).
• On demand per item: the body of a skill, agent or command.
• The runtime totals at the top are the ai-rulez tokens figures for the target. The per-item table is an estimate from the sources and does not add up to them exactly; both are shown, never summed.

ai-rulez cost                                   # largest runtime, top 10 offenders
ai-rulez cost --target codex --top 5
ai-rulez cost --format markdown                 # for a PR comment
ai-rulez cost --format json
ai-rulez cost --budget 8000 --on-demand-budget 60000   # exit 2 when over, naming the top 3 offenders

Exit 0 within budget, 2 over a ceiling, 1 the configuration could not be loaded.

Verifiers Command¶

ai-rulez verifiers run|list|explain|test|calibrate|suggest¶

Run the read-only, deterministic repo checks declared as [[verifiers]] in config.toml (a file exists or is absent, a glob matches a bounded number of files, a regex is required or forbidden, a JSON/YAML/TOML key has a value, generated files are in sync) and as rule-linked specs under .ai-rulez/verifiers/*.toml (paired files, all/any/not, changed-only scope; a failure names the rule or skill it enforces). Verifiers never write. Two predicates of a rule-linked verifier are opt-in per run: command starts a program (--allow-exec) and llm sends the changed lines to a model (--allow-llm); without the flags nothing runs and nothing leaves the machine. Types, fields and semantics are in Verifiers and the verifiers reference.

ai-rulez verifiers run [--since <rev> | --staged | --all] [--rule <id>] [--name <name>]... [--format text|json|sarif|junit] [--output <file>] [--fail-on error|warning|info|none] [--strict] [--strict-applicability] [--profile <name>] [--role <name>] [--allow-exec] [--allow-llm] [--gate-llm] [--max-cost <usd>] [--estimate] [--no-local]
ai-rulez verifiers list [--format text|json] [--no-local]
ai-rulez verifiers explain <name> [--format text|json]
ai-rulez verifiers test [name...] [--allow-exec] [--format text|json]
ai-rulez verifiers calibrate [name...] [--allow-llm] [--max-cost <usd>] [--estimate] [--no-write] [--format json]
ai-rulez verifiers suggest <id> [--kind rule|skill|agent|command] [--max-proposals <n>] [--replay <n>] [--write] [--allow-llm] [--max-cost <usd>] [--estimate] [--format json]

--format json of list, explain and test follows schema/verifiers-list.schema.json, schema/verifiers-explain.schema.json (the fields of the declaration plus the text that explain prints) and schema/verifiers-test.schema.json ({ok, passed, total, results, untested, problems}; exit 2 when ok is false). list prints what is declared (the rule or skill each verifier enforces, invalid declarations included) without evaluating it. explain prints what one verifier checks, the item it enforces, its scope and its fix. test runs the [[verifiers.examples]] of each spec offline (exit 0 all match, 2 one does not or a declaration is invalid, 1 the configuration does not load or a name is unknown). All commands (and validate) check the config.toml verifiers first: unknown types, fields that do not apply to the type, globs that do not compile or expand to more than 64 brace alternatives, an unsupported key_equals file extension or malformed key, and a generated_in_sync profile that is not defined are rejected at load time. Invalid spec files are reported as AR9H2. calibrate measures the precision and recall of an llm verifier's fail verdict on its labeled examples and records it in .ai-rulez/verifiers/calibration/<id>.json (--no-write prints it only); run --gate-llm reads that record. suggest asks the model for candidate verifiers for a rule and prints the ones that pass deterministic checks; it never writes without --write (see Verifiers). [verifiers_settings] holds the limits and policy (max_timeout_s, max_file_bytes, require_examples, warn_dead, trust_exec_from, command_env).

Exit codes: 0 no verifier failed at the --fail-on severity, 2 at least one failed, even when another verifier could not be evaluated (a failure is never hidden behind exit 1; the report shows both), 1 nothing failed but the run could not complete: the configuration does not load or validate, a --name is unknown, the --since base cannot be used, or a verifier could not be evaluated (status error). A failing info verifier never fails the run unless --fail-on info. The MCP server exposes the same run as the read-only run_verifiers tool (with since, staged and rule parameters); it does not resolve includes, so generated_in_sync reports error there for a project that declares includes or installed skills.

Tokens Command¶

ai-rulez tokens¶

Report how many prompt tokens the generated configuration costs, split by when an agent loads it.

Artifacts are measured as rendered strings in memory — nothing is read back off disk, so the report is correct even before generate has ever run, and a stale output tree cannot corrupt the numbers.

Syntax:

ai-rulez tokens [flags]

Flags:

ai-rulez tokens
ai-rulez tokens --format json
ai-rulez tokens --compare-profiles base --compare-profiles backend --compare-profiles full
ai-rulez tokens --compare-profiles base --compare-profiles base,backend
ai-rulez tokens --budget 6000
ai-rulez tokens --role backend
ai-rulez tokens --by-role

Reading the report¶

Output is grouped per runtime (one provider's files) and, within a runtime, by when the surface is loaded:

Native rule files (.claude/rules, .cursor/rules, .github/instructions, ...) are bucketed by their activation, read from each file's frontmatter: always-on files count as always, path-scoped files as conditional ("path-scoped rule files"), agent-requested rules split into an always description and an on demand body, and manual rules are on demand. Machine-local rule files (*.local.*) count as conditional.

The root instructions file is broken down per section, and rules and context are listed individually so an expensive one can be named. The item listing, bodies and file overhead are separate lines: they are loaded on different schedules, and a single per-file total hides which part is actually costing anything.

The item listing¶

A harness that supports skills does not wait for a skill to be opened. At session start it puts a listing of the skills (and, for some, commands and agents) it can load into the prompt: one entry per item with its name and description, and for Codex and pi its path. That listing is paid on every request, whether or not a skill is ever used, and it is usually the largest always-loaded cost a skill tree adds. Each runtime whose harness lists items gets one skill listing line (and command listing / agent listing where the harness lists those), with the names, descriptions, paths and per-entry framing as children. The listing is included in the runtime's always figure, in the headline and in --budget.

An item with disable-model-invocation: true is not offered to the model and is not listed. Each entry costs the token count of its name, description and path plus a framing constant of 27 tokens (listing_entry_overhead in the JSON).

The figure is an estimate, and so is the constant. Calibration method, which you can repeat on your own harness version:

mkdir p && cd p && git init -q
# empty project
claude -p "reply with the single word ok" --output-format json \
  --setting-sources project --strict-mcp-config --mcp-config '{"mcpServers":{}}'
# then add 100 skills with ~165-character descriptions under .claude/skills and rerun

The prompt size is input_tokens + cache_creation_input_tokens + cache_read_input_tokens. On Claude Code 2.1.289, 100 such skills added 6,402 tokens (64 per skill); ai-rulez tokens reports 6,400 for the same skills as an ai-rulez source. The constant is the difference between that per-skill figure and the cl100k_base count of the name and description (3 + 34 tokens), so it also absorbs the tokenizer gap on that text.

What the estimate does not model: a harness bounds its listing and shortens or omits entries beyond it (Codex: a share of the context window; Claude Code: a total budget in addition to the 1,536-character per-entry cap, which capped the same probe at about 9.6k tokens from 100 skills up). A very large skill set is therefore an upper estimate. truncated_descriptions counts entries whose description exceeds a known per-entry limit. With agents_md, skills written only to the shared .agents/skills tree are not attributed to a preset.

The earlier model counted only skill and command names (and agent descriptions) as always and skill descriptions as conditional. Those figures remain in the JSON as always_legacy, conditional_legacy (per runtime) and headline_always_legacy, and the text report prints the pre-listing headline next to the listing share, so a number recorded before this change stays comparable. headline_always itself now includes the listing, so a --budget that passed before can fail; raise the ceiling or trim descriptions. Provider specs declare the listing with a [listing] table (skills, commands, agents, include_path, description_limit).

--budget compares against the headline figure and exits 2 when it is exceeded, which is distinct from 1 so a hook can tell "over budget" from "the command failed".

JSON keys¶

--format json prints one document (schema/tokens-report.schema.json) with the always-loaded figures a budget gate reads:

The report is a result, so it goes to stdout; every diagnostic (the "Duplicate skill collapsed" warnings generation raises, and the over-budget line) goes to stderr under --format json, leaving stdout exactly one parseable document.

When agents_md is on, a preset whose root file imports the shared AGENTS.md (claude's CLAUDE.md shim) follows that import: the runtime's always-loaded figure counts the AGENTS.md content under an AGENTS.md (imported) entry, not just the shim. The file is counted once per runtime, and runtimes are still not additive, so the headline stays the largest single runtime.

What the numbers are not¶

• Approximate. Claude's tokenizer is not published. The default counter uses the embedded cl100k_base BPE vocabulary, which measured 8% low against one real 19,230-byte instruction file. Use the numbers to compare profiles, and to compare before an edit against after — not as absolute truth.
• Not a session total. ai-rulez counts only the artifacts it generates. The agent harness adds a fixed floor of its own system prompt and tool schemas, plus per-artifact overhead, neither of which ai-rulez can see.
• Not additive across runtimes. One session loads one runtime's root instructions file, so emitting both CLAUDE.md and AGENTS.md costs one of them. The headline is the largest single runtime, not the sum. A runtime whose root file imports another (claude's CLAUDE.md importing AGENTS.md) does pay for the imported file, counted once (see JSON keys).
• Noisy in the provenance lines. A blake3 hex digest is incompressible, and two digests of the same length do not tokenize to the same count, so a few tokens per artifact move between two profiles for no reason you can act on.

--tokenizer estimate replaces the tokenizer with a bytes-per-token ratio. It is labeled as an estimate in the output because the real ratio has been measured between 1.81 and 5.30 bytes per token across whole trees, so a tree-level total from it can be wrong by a factor of three.

Acting on the report¶

The agents_delegation line under the root instructions file is the cheapest thing to cut: it restates every agent's name and description in a file loaded on every request, while .claude/agents/*.md already carry the same text on demand. Drop it with builtins = ["!agent-delegation"] — the agent files are still generated, so nothing is lost. See Configuration.

Telemetry Commands¶

Opt-in usage and item-load telemetry, documented in Usage telemetry and Telemetry. One namespace replaces the 4.x usage ... and report usage|evals commands.

Eval Commands¶

Documented in Evals. eval run --format is text by default (a plain table, like every other command); markdown, json and junit are chosen on purpose.

Review Commands¶

Documented in Review.

ai-rulez review [id|name|path...]¶

Score skills, agents and commands against a rubric. Offline by default (lint evidence, no model); --semantic adds an LLM judge.

Exit codes: 0 reviewed, 1 could not run or was refused, 2 --gate failed.

ai-rulez review calibrate|fix|explain¶

ai-rulez rubric list|show|lint¶

List the built-in and project rubrics, print one rubric's dimensions and weights, or lint rubrics, golden files and calibration records (AR9G8; --format text\|json\|sarif; exit 2 with findings).

Judge Command¶

Documented in Judge.

ai-rulez judge [paths...]¶

Review agent configuration (skills, agents, commands, rules, CLAUDE.md, AGENTS.md, MCP and settings files) with security, quality and governance reviewers, a verifier that checks every quote, and an adjudicator. It needs no configuration. With no paths it judges every unit below the working directory that a harness reads, nested .claude/ directories included; generated files are skipped.

Exit codes: 0 every unit passed or warned (or --estimate), 1 the run could not complete (refused, capped, a call failed, nothing to judge, a unit only partly reviewed), 2 a unit met --fail-on or was withheld for secrets.

Search Command¶

Documented in Skill Search.

ai-rulez search <query>¶

Rank the skills mcp --serve-skills would serve against a query, with the ranker find_skill uses: lexical BM25F (offline, deterministic) by default, or hybrid with an embedding index.

A hybrid or vector search that cannot embed the query ranks lexically and reports degraded (no_index, provider_unavailable, timeout, budget, network_disabled). With the default [search] fusion = "auto", hybrid ranks by cosine alone while every skill has a current vector. With [search] vector_min_sim set, a vector ranking with no skill above it returns nothing and reports abstained (see Abstaining).

ai-rulez search index and ai-rulez search status¶

index embeds the served skills and writes the index find_skill and search --mode hybrid read; only skills whose embedded text changed are sent. --dry-run shows the host, the number of texts and bytes and an estimate first; --rebuild re-embeds everything; --items a,b also re-embeds those skills although their text did not change (every changed or unindexed skill is embedded and sent regardless). A skill whose text looks like it holds a secret is withheld (AR9D3). A batch the provider rejects is split until the refused skill stands alone, which is skipped and named. Exit 2 when a skipped skill, a budget or a provider stop left skills without a vector (the finished ones are written). status reports the index against the served skills (none, unreadable, incompatible, stale, fresh) without any network call. See Skill Search.

ai-rulez search mine¶

Turn the opt-in query log ([search] log_queries = true in the user config, or AI_RULEZ_SEARCH_LOG_QUERIES=1) into candidate cases: --output file (default stdout), --min-count n, --purge (delete the log afterwards).

ai-rulez improve run <skill> --with CMD (experimental)¶

Runs an external optimizer on a throwaway copy of an authored skill and accepts its candidate only if a held-out eval set improves without regressions. The authored skill is untouched until improve apply, which never commits. Required: --with and --max-cost.

Defaults can come from the [improve] table; a flag wins.

Exit 0: candidate accepted. Exit 2: no acceptable candidate (report written). Exit 1: refused or could not run. See Improve.

ai-rulez improve apply <run-id> (experimental)¶

Shows the diff of an accepted run and writes it into the skill after confirmation (--yes skips it). Refuses with AR9J1 when the skill changed since the run. --allow-frontmatter and --allow-scripts widen the diff policy as for run; --format text|json.

ai-rulez improve show|clean|pr|adapters (experimental)¶

• improve show <run-id>: the report of a saved run (rounds, held-out comparison with its bootstrap interval, sibling guard, costs) and the diff; --format json prints improve-show/1.
• improve clean [<run-id>|--all]: delete saved runs (--dry-run, --yes).
• improve pr <run-id>: branch and pull request from an isolated worktree (--base, --remote, --draft, --no-push, --run-evals, --eval-arg, --env-pass, --isolation none|auto|require, --allow-network, --allow-frontmatter, --allow-scripts, --yes); git runs scrubbed with no hooks and only the push keeps transport credentials; the ai-rulez commands it runs in the worktree get a scrubbed environment, so pass the eval runner's credentials by name with --env-pass. Refusals carry AR9J8.
• improve adapters [name]: list the bundled optimizers, or print a template (shell, research, and repair-workflow, a scheduled GitHub Actions workflow that repairs skills after a model change).

ai-rulez search --eval <cases.yaml>¶

Measure the ranking against labeled queries: top-1, recall@k, hit@k, MRR and, for graded cases, nDCG@k. With positive and negative cases and a vector or hybrid mode it also prints the [search] vector_min_sim that best separates them (calibration, abstain rate; see Abstaining).

Exit codes: 0 pass, 1 cannot run (bad flags, invalid cases file AR9D2, no catalog, a vector mode with no index or with degraded embeddings), 2 a gate failed (AR9D4).

Validation Command¶

ai-rulez validate¶

Validate configuration without generating files.

Syntax:

ai-rulez validate [flags]

Flags:

Exit codes: 0 valid, 1 the configuration is invalid or could not be loaded, 2 findings at or above --fail-on.

When the content tree is an OKF bundle (a root index.md, see migrate okf), validate also runs the OKF checks. "Configuration is valid" is printed only after they pass, so a run that exits 2 never says it; with --format json (or --output) that run writes the OKF document (bundle, okf_spec, concepts, findings) instead of the lint report, so a JSON consumer always gets a document. A rule or context file with no frontmatter block at all is plain native markdown: generate accepts it, so validate reports it as an AR9B1 warning (run migrate okf to add the type) and generate --check stays clean; a frontmatter block without a type, or one that does not parse, is still an error. -q drops the summary lines (N concepts, ... and validation: ...); findings stay.

Examples:

Explain a rule:

ai-rulez validate --explain AR401

Run the checks as JSON across every root:

ai-rulez validate --recursive --format json

Fail on warnings too:

ai-rulez validate

Check only the configuration file, as validate did before v5:

ai-rulez validate --config-only

Validate every config in a monorepo (all roots are checked; exit status 1 if any config is invalid, 2 on findings):

ai-rulez validate --recursive

Validate current configuration (configuration checks, then the deep content checks):

ai-rulez validate

Validate specific config file:

ai-rulez -C .ai-rulez/config.toml validate

With debug output:

ai-rulez validate --debug

What Gets Validated¶

The raw config file is also checked against schema/ai-rules.schema.json, so an unknown key or a value outside an enum fails rather than being silently dropped. The structural checks are:

• A config.local.* overlay, when present, is checked against schema/ai-rules-local.schema.json, and the merged config is validated. The output names the overlay file and prints a one-line summary of overridden, added and removed key paths, never values
• version is "5.0" ("4.0" and older are rejected; ai-rulez migrate v5 upgrades them)
• name is present and non-empty
• All preset names are valid
• A builtin:<name> or builtin:<name>/<item> reference in a profile names a real builtin or pack item
• A positive builtins entry (<name> or <name>/<item>) names a real builtin or pack item
• default, if set, names an existing profile
• A profile referencing a domain not present in the content tree is a warning, not a failure (and is downgraded to a debug hint when includes are configured, since the domain may come from an include)
• File paths are accessible
• No two skills, or two commands, in the same scope resolve to the same output id. The flat (commands/deploy.md) and directory (commands/deploy/COMMAND.md) forms resolve identically, so declaring both is a collision rather than an override.
• No skill and command share an output id. Both render to .claude/skills/{id}/SKILL.md, differing only in whether the item is user-invocable, so a shared id silently overwrites one with the other. This check pools root and every domain, because the output layout has no domain segment.

Lock Command¶

ai-rulez lock [name...]¶

ai-rulez.lock (commit it) pins the parts of your AI configuration that an attacker, or an honest mistake, could change without anyone noticing. See Lock file for the threat model, the hashing scheme and how to review a lock diff. It records:

• for every git include and installed skill: the source, path and requested ref, the commit the ref resolved to, and a sha256 digest of the imported file tree;
• for every authored rule, context file, skill (with its resources), agent, command, hook and role: a sha256:<hex> digest of the raw files, with its id, domain, owner and version;
• for every [[skill_sources]] entry ([[source]]: commit and tree digest) and every skill the skills server serves ([[served]]: a sha256: digest in the same scheme as the content pins; skills that only a role serves are included): the entries [lock] enforce checks at serve time;
• a digest of each generated output, and one tree digest over everything;
• one [[scan]] record per staged external scanner with a cached result for the current content (what was scanned and the outcome; lock starts no scanner, so run scan --external first; see Lock file).

Local-path includes are pinned as local-include items, and project scripts run by agent, skill and command frontmatter hooks are pinned with their item. Sources are recorded as written in the config, with credentials in a URL redacted. A symlink inside a pinned tree is pinned by its link target.

ai-rulez lock                     # pin everything (uses the network for remotes)
ai-rulez lock shared              # re-pin one include or skill, keep the other pins (and the content pins)
ai-rulez skill update kreuzberg   # same, for installed skills only
ai-rulez lock --content-only      # re-pin authored content and outputs; offline
ai-rulez lock --check             # verify everything, offline; exit 2 and name each difference
ai-rulez lock --diff              # what `lock` would change, for a pull request
ai-rulez lock --diff --format json
ai-rulez lock --check --format json   # the same document, exit code still 2 on drift
ai-rulez lock --subject               # the digest to sign with cosign (see Lock file, "Signing the lock")
ai-rulez lock --outdated              # sources whose version constraint allows a newer tag (network)
ai-rulez lock --outdated --format json --fail-on-outdated

With a lock present, generate fetches the locked commit instead of the moving ref, so two runs produce identical output even after the remote moved, and verifies the digest of what it fetched. A mismatch fails the run (a damaged cache is repaired by fetching the pinned commit again first; a remote that serves different bytes for the same commit is a hard failure). A source the lock does not cover is fetched as before, with the advice to run ai-rulez lock. generate never writes the lock.

Exit codes: 0 ok, 1 the command could not run (a tool error; also --check with no ai-rulez.lock, or an unknown name), 2 --check found drift (also a lock without content pins; with [lock] enforce, a missing lock too), or --outdated found a moved tag (AR732), a deleted one (AR735) or an unsatisfiable constraint (AR730), or --refuse-findings refused a served skill the security scan refuses (nothing written), 3 the lock was written but served skills were left unpinned because the security scan refuses them. Over several roots (--recursive) the most severe code wins: 1, then 2, then 3.

CI: generate --locked fails when the lock is missing or does not cover a configured remote source, or when an authored source no longer matches the lock's content pins (exit 2); generate --frozen additionally never touches the network. validate logs a warning for each remote source that follows a moving ref without a pin, and validate reports it as AR010 (a warning; an error under enforcement, or raise it with [lint.severity]). Enforcement is on whenever ai-rulez.lock exists ([lock] enforce = false opts out); it also reports content drift as AR981 / AR982, and generate refuses a remote source the lock does not cover, as --locked does. Pinning ref to a full commit SHA also counts as pinned.

The lock proves the bytes did not change since you reviewed them, not who published them. To add that, sign it with ai-rulez sign --lock and verify with verify --attestation, or sign lock --subject with cosign (recipe).

Sign Command¶

ai-rulez sign¶

Signs one subject into a Sigstore bundle (a DSSE envelope over an in-toto statement): the lock-subject statement of ai-rulez.lock (written next to the lock), a plugin bundle, a skill directory, an SBOM file or an organization policy. Verify it with verify --attestation. See Signing for the policy, keyless and KMS signing, thresholds, SLSA provenance and cosign interoperability.

ai-rulez sign --lock --key cosign.key        # key mode, offline
ai-rulez sign --lock --keyless               # Fulcio + Rekor; the identity and digest go to a public log
ai-rulez sign --lock --key awskms:///alias/release   # a key held in a KMS
ai-rulez sign --bundle dist/acme-plugin --key cosign.key --provenance
ai-rulez sign --skill skills/deploy --key cosign.key
ai-rulez sign --sbom sbom.cdx.json --key cosign.key
ai-rulez sign --org-policy ai-rulez-policy.toml --key cosign.key   # an organization policy ([Policy](policy.md#signed-policies))
ai-rulez sign --lock --key second.key --append       # a second signer, for [signing] thresholds