AI Rulez

AI-Rulez

AI-Rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. It keeps one source of truth in a config directory (default .ai-rulez/) and takes it through author, generate (52 built-in harness presets: Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, and others), bundle (OKF, Agent Plugins, ARD), lint and validate, govern (lock, approvals, Sigstore signing, policy, SBOM) and publish.

Use this skill when:

• Setting up or modifying .ai-rulez/ configuration
• Writing rules, context, skills, agents, commands, or checks for AI assistants
• Declaring [[hooks]] or [permissions] once for every harness
• Generating a personal config into the home directory with generate --user
• Configuring domains, profiles, or includes
• Using custom config directory names via --config-dir
• Generating outputs for specific AI tools
• Auditing planned writes/deletes with --dry-run
• Installing or managing external skills

Installation

# npm (no install)
npx ai-rulez@latest

# Python (no install)
uvx ai-rulez

# Go (the module path needs /v5; without it @latest resolves to an old 1.x build)
go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest

Quick Start

# Initialize a new project
ai-rulez init

# Add rules and context
ai-rulez add rule my-rule --priority high
ai-rulez add context my-context

# Generate outputs for all configured presets
ai-rulez generate

# Regenerate whenever .ai-rulez/ changes
ai-rulez generate --watch

# Validate configuration
ai-rulez validate

# Read-only diagnostics: drift, removed presets, missing tools
ai-rulez doctor

Lifecycle commands

ai-rulez generate --plugin              # bundle: plugin bundles from the [plugin] block
ai-rulez export okf                     # bundle: an OKF bundle of the knowledge
ai-rulez validate --strict              # validate: warnings fail
ai-rulez okf validate docs/okf          # validate: any OKF bundle
ai-rulez lock                           # govern: pin includes, skills and content
ai-rulez sign --lock                    # govern: Sigstore attestation of the lock
ai-rulez sbom -o ai-bom.cdx.json        # govern: CycloneDX SBOM
ai-rulez publish --dry-run              # publish: preview release artifacts

Supported and planned standards, with pinned versions and test status, are in https://goldziher.github.io/ai-rulez/standards/.

Configuration Structure

.ai-rulez/
  config.toml          # Main configuration
  rules/               # Governance rules (.md files with frontmatter)
  context/             # Contextual information (.md files)
  skills/              # Specialized capabilities (name/SKILL.md plus resources)
  agents/              # Agent definitions (.md files)
  commands/            # Custom commands (.md files)
  checks/              # Code-review guidelines (.md files)
  domains/             # Domain-scoped content
    backend/
      rules/
      context/
      skills/

config.toml

version = "5.0"
name = "my-project"
description = "Project description"

presets = ["claude", "cursor", "gemini"]
default = "backend"
builtins = ["go", "security", "testing"]

[profiles]
backend = ["backend", "shared"]
frontend = ["frontend", "shared"]

[[includes]]
name = "shared-rules"
source = "https://github.com/org/shared-rules"

[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"

[[mcp_servers]]
name = "ai-rulez"
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]

[[scopes]]
path = "packages/web"
profile = "frontend"
presets = ["codex", "claude"]

Content Frontmatter

Rules, context, skills, and agents support YAML frontmatter:

---
priority: high # critical, high, medium, low, minimal
targets: # Limit to specific presets
  - CLAUDE.md
  - .cursor/rules/*
description: Brief description
---

Agent-only fields

Agent files under .ai-rulez/agents/ accept additional frontmatter that maps to Claude Code's subagent spec. Each is optional and only emitted into .claude/agents/*.md (other presets skip fields they do not support):

---
name: security-reviewer
description: Reviews code for security regressions
model: opus # haiku | sonnet | opus | inherit
effort: high # low | medium | high | xhigh | max | inherit
permissionMode: default
tools: # Restrict tool access
  - Read
  - Grep
  - Glob
---

effort controls reasoning depth. Set a project-wide default and per-preset overrides in config.toml:

[defaults]
effort = "medium"

[defaults.effort_by_preset]
codex = "high"      # Codex applies it globally and per agent
claude = "xhigh"    # Claude applies it as `effort` per agent
amp = "max"         # Amp writes amp.anthropic.effort to .amp/settings.json

Resolution order (per preset, per agent): per-agent effort → defaults.effort_by_preset[<preset>] → defaults.effort → omit.

Per-preset support:

• Claude: per-agent in .claude/agents/*.md (full vocabulary including max; inherit is not a Claude value and is dropped)
• Codex: global in .codex/config.toml and per-agent in .codex/agents/*.toml (max → high; inherit dropped)
• Amp: global in .amp/settings.json (xhigh → high)
• Devin: per-agent in .devin/agents/*.md frontmatter (max → high)
• Opencode: per-agent variant in .opencode/agents/*.md (joins the agent's model as model#variant)
• Cursor, Copilot, Gemini, Junie, Antigravity, Cline: silently skipped (those tools expose effort via UI toggles or user-managed config files we don't generate).

Domains and Profiles

Domains group content for different teams or concerns. Profiles select which domains are active.

ai-rulez domain add backend
ai-rulez add rule api-standards --domain backend
ai-rulez profile add backend-team backend shared
ai-rulez generate --profile backend-team

Includes

Share rules across projects using git repositories or local paths:

ai-rulez include add shared-rules https://github.com/org/shared-rules
ai-rulez include add local-rules ./path/to/local --merge-strategy include-override

Installed Skills

Install named skills from external repositories:

ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg
ai-rulez skill install ai-rulez --source https://github.com/Goldziher/ai-rulez
ai-rulez skill list
ai-rulez skill remove kreuzberg

Skills are fetched dynamically at generation time and included in outputs. Skill references/, scripts/, and assets/ directories are preserved as separate generated resource files when the target preset supports skill directories.

Built-in Presets

52 presets are available (ai-rulez init --help prints them): aiassistant, amp, antigravity, augment, baz, bob, claude, cline, codebuddy, codebuff, codewhale, codex, commandcode, copilot, copilot-cli, cortex, crush, cursor, deepagents, devin, dsh, factory, gemini, gitlab-duo, goose, grok, hermes, junie, kilo, kimi, kiro, letta, mimocode, muse, omp, openclaw, opencode, pi, poolside, qoder, qwen, reasonix, replit, rovodev, takt, trae, vibe, warp, xum, zcode, zed, zoocode, plus the opt-in okf preset (an Open Knowledge Format bundle in docs/okf/, see ai-rulez export okf). The mcp preset is a shared utility (the generic .mcp.json) invoked automatically when MCP servers are configured.

windsurf is now devin and continue-dev was removed; ai-rulez doctor reports both. docs/harnesses.md has the per-preset feature matrix (rules folder, skills, agents, commands, MCP, hooks, permissions, checks, user scope).

Hooks, Permissions, Checks and User Scope

• [[hooks]] in config.toml renders into the native hooks file of 36 harnesses (a generated plugin module for opencode, kilo, mimocode, pi and amp). Events, matchers and timeouts are translated per harness; a group a harness cannot express is skipped with a warning. See docs/settings.md.
• [permissions] (allow, ask, deny, Claude Code rule syntax) is translated for 24 harnesses. A rule that cannot be expressed is skipped, never widened, and an unenforced deny is reported. See docs/permissions.md.
• Checks are code-review guidelines in .ai-rulez/checks/<name>.md (frontmatter description, severity, tools, targets), rendered for cursor, kilo, qwen, factory, rovodev, amp, augment and gitlab-duo. Manage them with ai-rulez add|remove|list check. See docs/checks.md.
• ai-rulez generate --user renders a user config (~/.config/ai-rulez) into the home directories of 47 harnesses; clean --user removes what it wrote. See docs/user-scope.md.
• Settings files you also edit (JSON, JSONC, TOML, YAML) are merged key by key, so your own keys and comments survive generate and clean.
• [guard] generated = true adds a PreToolUse hook (ai-rulez guard) that blocks agent edits to generated files and points at the source under .ai-rulez/.