ai-rulez

AI-Rulez Governance

AI-Rulez centralizes AI assistant governance in a config directory (default .ai-rulez/) and generates tool-specific outputs for Claude, Cursor, Windsurf, Copilot, Gemini, Codex, and other presets.

Use this skill when:

• Setting up or modifying .ai-rulez/ configuration
• Writing rules, context, skills, or agents for AI assistants
• 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

# Go (primary CLI)
go install github.com/Goldziher/ai-rulez@latest

# npm
npx ai-rulez@latest

# Python
uvx ai-rulez

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

# Validate configuration
ai-rulez validate

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)
  domains/             # Domain-scoped content
    backend/
      rules/
      context/
      skills/

config.toml

version = "4.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
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
permission_mode: 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 and inherit)
• 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)
• Windsurf: per-agent in .windsurf/agents/*.md frontmatter (max → high)
• Opencode: per-agent reasoningEffort in .opencode/agents/*.md
• Cursor, Copilot, Gemini, Junie, Antigravity, Cline, Continue.dev: 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

Available presets: claude, cursor, gemini, copilot, continue-dev, windsurf, cline, codex, amp, junie, opencode, hermes, antigravity.

MCP Integration

MCP servers are configured inline in config.toml with [[mcp_servers]]. ai-rulez exposes an MCP server for AI assistants to read, create, update, validate, dry-run, and generate configuration:

ai-rulez mcp

Configure in your AI tool's MCP settings to enable CRUD operations from within the assistant.

MCP server env values can use ${VAR} placeholders. ai-rulez generate resolves them from --env, process env, and dotenv files, then refuses to write secret-bearing generated MCP configs unless the target paths are gitignored.

Plugins and Marketplaces

V4 introduces support for plugins and marketplace integrations to extend ai-rulez functionality with custom generators, presets, and validators.