### AI-Powered ai-rulez Configuration Example

Source: https://goldziher.github.io/ai-rulez/quick-start

An example of an ai-rulez configuration generated with AI assistance. It includes richer details like project description, specific rules with priorities, sections, and custom agents tailored to the project's tech stack (e.g., Go).

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
metadata:
  name: "My Project"
  description: "Go microservice with REST API"
presets:
  - "popular"
rules:
  - name: "Go Standards"
    priority: high
    content: "Follow standard Go layout (cmd/, internal/, pkg/)"
  - name: "Error Handling"  
    priority: critical
    content: "Always handle errors properly, use wrapped errors"
sections:
  - name: "Architecture"
    content: "Clean architecture with dependency injection..."
agents:
  - name: "go-expert"
    description: "Go specialist for backend development"
```

--------------------------------

### Basic ai-rulez Configuration Example

Source: https://goldziher.github.io/ai-rulez/quick-start

A minimal ai-rulez configuration file created using the basic initialization command. It includes a schema reference, project metadata, and a list of presets.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
metadata:
  name: "My Project"
presets:
  - "popular"
```

--------------------------------

### Run ai-rulez Without Installation

Source: https://goldziher.github.io/ai-rulez/installation

Executes the ai-rulez CLI directly without a permanent installation, utilizing package runners like Go, uvx (for Python), and npx (for Node.js). This is useful for trying out the tool or for environments where installation is not feasible.

```bash
go run github.com/Goldziher/ai-rulez/cmd@latest --help
```

```bash
uvx ai-rulez --help
```

```bash
npx ai-rulez@latest --help
```

--------------------------------

### Verify ai-rulez Installation

Source: https://goldziher.github.io/ai-rulez/installation

Checks if the ai-rulez installation was successful by running the version command. This command should output the installed version of the ai-rulez CLI.

```bash
ai-rulez --version
```

--------------------------------

### Initialize ai-rulez Configuration

Source: https://goldziher.github.io/ai-rulez/quick-start

Initializes the ai-rulez configuration file. The AI-powered approach analyzes the codebase to generate tailored rules and agents, while the basic approach creates a simpler configuration. Both require a project name and can use presets.

```shell
# AI-powered initialization (recommended)
ai-rulez init "My Project" --preset popular --use-agent claude

# Or simple initialization without AI assistance
ai-rulez init "My Project" --preset popular
```

--------------------------------

### Install ai-rulez using Package Managers

Source: https://goldziher.github.io/ai-rulez/installation

Installs the ai-rulez CLI tool using common package managers like Homebrew, Go, npm, and pip. Ensure the respective package manager is installed and configured on your system.

```bash
brew install goldziher/tap/ai-rulez
```

```bash
go install github.com/Goldziher/ai-rulez/cmd@latest
```

```bash
npm install -g ai-rulez
```

```bash
pip install ai-rulez
```

--------------------------------

### Full AI Rulez Configuration with Tools and Commands

Source: https://goldziher.github.io/ai-rulez/examples

A comprehensive example showcasing advanced AI Rulez features. It includes metadata, inheritance from base configurations, presets, agent definitions with specific models and system prompts, critical rules, integration with external tools like a GitHub MCP server, and definition of custom slash commands.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json

metadata:
  name: "SaaS Platform API"
  version: "3.0.0"

extends: "./shared/base-go-service.yaml"

includes:
  - "./shared/security-standards.yaml"

presets:
  - "claude"
  - "cursor"
  - "continue-dev"

agents:
  - name: "go-expert"
    description: "For Go-specific questions about our backend services."
    model: "claude-3-opus-20240229"
    system_prompt: "You are an expert in Go, gRPC, and PostgreSQL..."

rules:
  - name: "API Design"
    content: "All new endpoints must follow RESTful principles and be documented in the OpenAPI spec."
    priority: critical

# Integrate external tools like a GitHub server
mcp_servers:
  - name: "github"
    description: "Provides context from GitHub issues and pull requests."
    command: "npx"
    args: ["-y", "@mcp/server-github"]
    env: {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}

# Define custom slash commands for your AI assistant
commands:
  - name: "new-endpoint"
    description: "Scaffold a new API endpoint"
    usage: "/new-endpoint <path> <method>"
    system_prompt: "Generate the boilerplate code for a new RESTful endpoint..."

```

--------------------------------

### Root AI Rulez Configuration Example

Source: https://goldziher.github.io/ai-rulez/monorepo

An example of a root `ai-rulez.yml` configuration. It defines high-level project metadata, system architecture rules, agent definitions with delegation instructions, and output file paths. This serves as the main entry point for `ai-rulez generate`.

```yaml
# /ai-rulez.yml
metadata:
  name: "My Full-Stack Project"

rules:
  - name: "System Architecture"
    priority: critical
    content: "This is a microservices project with a React frontend and a Go backend using gRPC."

agents:
  - name: "solution-architect"
    description: "For high-level system design questions."
    system_prompt: "You are a solution architect. For implementation details, delegate to the `frontend-expert` or `backend-expert` agents."

outputs:
  - path: "SYSTEM_OVERVIEW.md"

```

--------------------------------

### Add Project Details to ai-rulez Configuration

Source: https://goldziher.github.io/ai-rulez/quick-start

Adds specific rules or details to the ai-rulez configuration file. This is useful for basic initializations or enhancing existing configurations with project-specific information like tech stacks or workflow requirements.

```shell
# Add a rule for your tech stack
ai-rulez add rule "Tech Stack" --priority critical --content "Frontend: React, TypeScript, Tailwind CSS. Backend: Go, PostgreSQL."

# Add a rule for your development workflow
ai-rulez add rule "Workflow" --priority high --content "All new features must have 90%+ unit test coverage."

# Enhance existing config with AI analysis
ai-rulez init "My Project" --preset popular --use-agent claude --yes
```

--------------------------------

### Start MCP Server

Source: https://goldziher.github.io/ai-rulez/cli

Starts the Model Context Protocol (MCP) server. This server enables programmatic interaction with the AI configuration.

```bash
ai-rulez mcp
```

--------------------------------

### Scoped AI Rulez Configuration Example (Backend)

Source: https://goldziher.github.io/ai-rulez/monorepo

An example of a scoped `ai-rulez.yml` file for a specific project section, in this case, the backend. It includes metadata, rules specific to backend technologies (e.g., Go API patterns), and defines output files relevant to that scope. This file would typically reside in a subdirectory like `/backend/`.

```yaml
# /backend/ai-rulez.yml
metadata:
  name: "Backend API"

rules:
  - name: "Go API Patterns"
    priority: high
    content: "All new endpoints must include structured logging via the `slog` package and OpenTelemetry tracing."

outputs:
  - path: "BACKEND_RULES.md"

```

--------------------------------

### Initialize Basic ai-rulez Configuration

Source: https://goldziher.github.io/ai-rulez/cli

Creates a minimal ai-rulez configuration file with basic metadata and output paths. This is a starting point for simple projects.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
metadata:
  name: "My Project"
outputs:
  - path: "CLAUDE.md"

```

--------------------------------

### Generate AI Instruction Files with ai-rulez

Source: https://goldziher.github.io/ai-rulez/quick-start

Generates all necessary AI instruction files based on the `ai-rulez.yml` configuration. These files are essential for the AI tools included in the specified presets. Generated files are automatically added to `.gitignore`.

```shell
ai-rulez generate
```

--------------------------------

### Structured Output Template Example

Source: https://goldziher.github.io/ai-rulez/schema

This example demonstrates the structured object format for defining output templates in ai-rulez v2.0 and later. The `template` property now requires an object with `type` and `value` fields, specifying whether to use an 'inline', 'file', or 'builtin' template.

```yaml
outputs:
  - path: "CUSTOM.md"
    template:
      type: "inline" # Can be "inline", "file", or "builtin"
      value: "# {{ .ProjectName }}\n{{ range .Rules }}{{ .Content }}{{ end }}"

```

--------------------------------

### Configure Shell Completion for ai-rulez

Source: https://goldziher.github.io/ai-rulez/installation

Enables tab completion for ai-rulez commands in various shells (Bash, Zsh, Fish, PowerShell). This significantly improves usability by allowing interactive discovery of commands and flags. Follow the specific instructions for your shell and ensure the completion script is sourced on shell startup.

```bash
# Add to ~/.bashrc or ~/.bash_profile
source <(ai-rulez completion bash)
```

```bash
# Add to ~/.zshrc
source <(ai-rulez completion zsh)
```

```bash
# Add to ~/.config/fish/config.fish
ai-rulez completion fish | source
```

```powershell
# Add to your PowerShell profile
ai-rulez completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### Composable Configuration with `extends` and `includes` - Backend Service YAML

Source: https://goldziher.github.io/ai-rulez/examples

This YAML file represents a project's specific configuration. It demonstrates how to inherit from a base configuration (`base.yaml`) and include shared standards (`go-rules.yaml`) using `extends` and `includes`. It also defines project-specific metadata and rules.

```yaml
# Inherit all rules from the company-wide base file
extends: "./base.yaml"

# Also merge in the shared Go language standards
includes:
  - "./shared/go-rules.yaml"

metadata:
  name: "User Service"

rules:
  - name: "Service-Specific Logic"
    content: "This service handles user authentication and profile data."

```

--------------------------------

### Enable ai-rulez MCP Server with Local Go Installation

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet configures the ai-rulez MCP server using a local Go installation. It specifies 'ai-rulez' as the command and 'mcp' as an argument, allowing AI assistants to interact with the ai-rulez.yml configuration directly. This is suitable if ai-rulez has been installed globally via 'go install'.

```json
{
  "mcp_servers": {
    "ai-rulez": {
      "command": "ai-rulez",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Initialize AI Rulez Configuration with AI

Source: https://goldziher.github.io/ai-rulez/examples

Initiates the ai-rulez configuration process using AI to analyze a project. It supports specifying a project name, a preset for common rules, and a specific AI agent for analysis. The output is a comprehensive ai-rulez.yml file tailored to the project's tech stack.

```shell
ai-rulez init "My Project" --preset popular --use-agent claude
```

--------------------------------

### Composable Configuration with `extends` and `includes` - Base YAML

Source: https://goldziher.github.io/ai-rulez/examples

This YAML file defines a company-wide base configuration. It includes metadata and a critical security rule that can be inherited by other project-specific configurations using the `extends` and `includes` keywords.

```yaml
metadata:
  description: "Base configuration for all projects at our company."

rules:
  - name: "Security Policy"
    content: "All services must pass a security audit before deployment."
    priority: critical

```

--------------------------------

### Display ai-rulez Version

Source: https://goldziher.github.io/ai-rulez/cli

The `version` command shows the currently installed version of the ai-rulez CLI.

```bash
ai-rulez version

```

--------------------------------

### MCP Server Integration in v2.0

Source: https://goldziher.github.io/ai-rulez/migration-guide

v2.0 introduces support for integrating with MCP (Model Context Protocol) servers. This configuration block demonstrates how to define an MCP server, specifying its name, the command to execute, and any necessary arguments.

```yaml
mcp_servers:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

```

--------------------------------

### Validate ai-rulez Configuration

Source: https://goldziher.github.io/ai-rulez/quick-start

Validates the current ai-rulez configuration file to ensure it is correct and consistent. This is an optional step to check the integrity of the configuration before or after generating files.

```shell
ai-rulez validate
```

--------------------------------

### AI Rulez Configuration with Inheritance (YAML)

Source: https://goldziher.github.io/ai-rulez/monorepo

An example demonstrating inheritance in `ai-rulez.yml` using the `extends` keyword. This configuration inherits all rules from a base file (`../../shared/base-go-service.yaml`) and adds its own specific rules relevant to the 'User Service API'. This pattern is useful for applying common standards while customizing for specific modules.

```yaml
# Inherit all rules from the company-wide Go base file
extends: "../../shared/base-go-service.yaml"

metadata:
  name: "User Service API"

rules:
  - name: "Service-Specific Logic"
    content: "This service is responsible for JWT authentication."
    priority: high


```

--------------------------------

### Get Metadata

Source: https://goldziher.github.io/ai-rulez/cli

Retrieves the current top-level metadata configuration. This includes project name and version.

```bash
ai-rulez get metadata
```

--------------------------------

### Multi-Platform ai-rulez.yml with Popular Preset

Source: https://goldziher.github.io/ai-rulez/examples

Configuration for a multi-platform project using the 'popular' preset, which synchronizes instructions across multiple AI tools like Claude, Cursor, Windsurf, Copilot, and Gemini. It includes a general workflow rule applicable to all AI assistants.

```yaml
metadata:
  name: "My Multi-Platform Project"

# The "popular" preset includes Claude, Cursor, Windsurf, Copilot, and Gemini
presets:
  - "popular"

rules:
  - name: "General Workflow"
    content: "All code must be reviewed and tested before merging."
    priority: critical

```

--------------------------------

### Run ai-rulez command for automatic migration

Source: https://goldziher.github.io/ai-rulez/migration-guide

Executing any ai-rulez command on a v1 configuration automatically initiates the migration process to v2. The original file is backed up, and the configuration is updated. If the migration fails, the original file is restored. This command demonstrates the expected output during a successful migration.

```bash
ai-rulez generate
# ℹ️  Detected v1 configuration format, migrating to v2...
# ℹ️  Successfully migrated configuration from v1 to v2 format

```

--------------------------------

### Override Claude Template and Add Custom Output

Source: https://goldziher.github.io/ai-rulez/examples

This configuration demonstrates how to use presets and override specific output templates, such as the default Claude output, with a custom template file. It also shows how to define a completely new custom output file.

```yaml
presets:
  - "popular"

outputs:
  - path: "CLAUDE.md" # This will override the default Claude output
    template:
      type: "file"
      value: "./my-custom-claude-template.tmpl"
  - path: "INTERNAL_DOCS.md" # Add a completely custom output
```

--------------------------------

### Minimal ai-rulez.yml with Single Preset

Source: https://goldziher.github.io/ai-rulez/examples

A minimal ai-rulez.yml configuration for a single AI assistant. It utilizes the `presets` key to apply a predefined set of rules, in this case, 'claude', and includes a critical rule specifying the project's tech stack.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json

metadata:
  name: "My Project"

# Use a preset for a single tool
presets:
  - "claude"

rules:
  - name: "Tech Stack"
    content: "This project uses Go and PostgreSQL."
    priority: critical

```

--------------------------------

### Get Extends Path

Source: https://goldziher.github.io/ai-rulez/cli

Retrieves the current 'extends' path, which specifies a remote or local file to inherit configuration from.

```bash
ai-rulez get extends
```

--------------------------------

### Advanced ai-rulez.yml with Custom Outputs and Agents

Source: https://goldziher.github.io/ai-rulez/examples

An advanced ai-rulez.yml configuration demonstrating the use of the `outputs` key for custom file generation, including specialized agent files. It defines output paths and naming schemes, sets up a 'database-expert' agent, and specifies a rule targeted only at the main output file.

```yaml
metadata:
  name: "Project with Agents"

# Use outputs for custom file generation
outputs:
  - path: "CLAUDE.md" # Main instruction file
  - path: ".claude/agents/" # Directory for agent files
    type: "agent"
    naming_scheme: "{name}.md"

agents:
  - name: "database-expert"
    description: "For questions about schema design and query optimization."
    system_prompt: "You are an expert in PostgreSQL..."

rules:
  - name: "Agent Usage Instructions"
    content: "For database questions, please use the @database-expert agent."
    targets: ["CLAUDE.md"] # This rule only appears in the main Claude file

```

--------------------------------

### AI-Generated ai-rulez.yml for Go Microservice

Source: https://goldziher.github.io/ai-rulez/examples

A comprehensive ai-rulez.yml configuration file generated by AI for a Go microservice. It includes metadata, presets, detailed rules for Go code standards, error handling, database patterns, API standards, and specialized agents for Go development and API design.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json

metadata:
  name: "User Management Service"
  description: "Go-based microservice handling user authentication and profiles with PostgreSQL backend"
  version: "1.0.0"

presets:
  - "popular"  # Claude, Cursor, Windsurf, Copilot, Gemini

rules:
  - name: "Go Code Standards"
    priority: high
    content: |
      Follow standard Go project layout (cmd/, internal/, pkg/). 
      Use meaningful package names and export only what needs to be public.
      Prefer composition over inheritance.

  - name: "Error Handling"
    priority: critical  
    content: |
      Always handle errors properly. Use wrapped errors with fmt.Errorf("context: %w", err).
      Never ignore errors - at minimum log them.
      Return errors as the last return value.

  - name: "Database Patterns"
    priority: high
    content: |
      Use repository pattern for data access. 
      Always use transactions for multi-table operations.
      Use prepared statements to prevent SQL injection.

sections:
  - name: "Service Architecture" 
    priority: critical
    content: |
      This service implements clean architecture with:
      - cmd/: Application entry points
      - internal/handlers/: HTTP handlers and routing
      - internal/service/: Business logic layer
      - internal/repository/: Data access layer
      - internal/models/: Domain models and DTOs

  - name: "API Standards" 
    priority: high  
    content: |
      RESTful API design following OpenAPI 3.0 specification.
      All endpoints return JSON with consistent error format.
      Use HTTP status codes appropriately (200, 201, 400, 401, 404, 500).

agents:
  - name: "go-expert"
    description: "Go language specialist for backend development"
    system_prompt: |
      You are an expert Go developer specializing in microservices. 
      Focus on clean architecture, proper error handling, and performance.
      Always suggest testable patterns and consider concurrency safety.

  - name: "api-designer"
    description: "REST API design specialist"  
    system_prompt: |
      You specialize in designing clean, consistent REST APIs.
      Focus on proper HTTP semantics, clear request/response formats,
      and comprehensive error handling. Always consider API versioning.

```

--------------------------------

### Add an Output using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new output configuration to the ai-rulez setup, specifying a path, type, and naming scheme. This defines where and how generated files are stored.

```bash
# Add a directory output with a naming scheme and type
ai-rulez add output ".claude/agents/" --type agent --naming-scheme "{name}.md"

```

--------------------------------

### Configuration Inheritance using 'extends' in v2.0

Source: https://goldziher.github.io/ai-rulez/migration-guide

v2.0 introduces configuration inheritance through the 'extends' field. This allows a configuration file to inherit settings from another specified YAML file, promoting modularity and reusability of common configurations.

```yaml
extends: ./base-config.yaml

```

--------------------------------

### Get a Specific Rule using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Retrieves and displays the details of a specific rule from the ai-rulez configuration based on its name.

```bash
# Get a specific rule
ai-rulez get rule "Code Style"

```

--------------------------------

### Generate Custom Linter Config with ai-rulez

Source: https://goldziher.github.io/ai-rulez/configuration

Shows how to support custom tools like 'CodeSniffer' by generating their configuration files (e.g., `.codesniffer.json`) using `ai-rulez`'s `outputs` and Go templating. This example populates a JSON configuration with directory paths defined in `rules`.

```yaml
rules:
  - name: "Important Directories"
    content: "src/"
  - name: "Other Directories"
    content: "pkg/"

outputs:
  - path: ".codesniffer.json"
    template:
      type: "inline"
      value: |
        {
          "scan_directories": [
            {{- range $i, $rule := .Rules -}}
              {{- if $i -}},{{- end -}}
              "{{- .Content -}}"
            {{- end -}}
          ]
        }

```

--------------------------------

### Custom Commands in v2.0

Source: https://goldziher.github.io/ai-rulez/migration-guide

v2.0 allows for the definition of custom commands within the ai-rulez configuration. This feature enables users to define their own command-line tools with descriptions and system prompts, extending the functionality of ai-rulez.

```yaml
commands:
  - name: newtask
    description: Start a new task
    system_prompt: "Focus on the new task only."

```

--------------------------------

### Automatic CLI Configuration for Gemini CLI

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet configures an MCP server for the Gemini CLI. It uses 'npx' to run '@modelcontextprotocol/server-github' and targets '@gemini-cli'. This configuration allows for automatic setup and interaction with Gemini CLI tools through the MCP server.

```json
{
  "mcp_servers": [
    {
      "name": "github-tools",  
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
      "targets": ["@gemini-cli"]
    }
  ]
}
```

--------------------------------

### Agent Models Configuration in v2.0

Source: https://goldziher.github.io/ai-rulez/migration-guide

v2.0 enables the specification of AI models for agents. This configuration snippet shows how to assign a specific model, such as 'claude-3-opus-20240229', to an agent named 'specialist'.

```yaml
agents:
  - name: specialist
    model: "claude-3-opus-20240229"

```

--------------------------------

### Migration failure due to unsupported user_rulez

Source: https://goldziher.github.io/ai-rulez/migration-guide

The 'user_rulez' configuration is no longer supported in v2.0 and will cause migration to fail. The solution is to move the content of 'user_rulez' into separate '.local' configuration files, which are intended for user-specific overrides and custom rules.

```yaml
# This will fail migration
user_rulez:
  rules: [...]

```

--------------------------------

### Update schema URL for manual migration

Source: https://goldziher.github.io/ai-rulez/migration-guide

During manual migration, it is essential to update the schema URL to point to the v2.0 schema. This ensures that validation tools and IDEs correctly interpret the configuration structure and enforce the new schema rules.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json

```

--------------------------------

### Convert string template to object format

Source: https://goldziher.github.io/ai-rulez/migration-guide

In v2.0, templates are converted from a simple string format to a more structured object format. This change allows for explicit definition of template types (builtin, file, inline) and their values, providing more flexibility and clarity.

```yaml
# Before
template: "default"

# After  
template:
  type: builtin
  value: default

```

```yaml
# Before
template: "@path/file.tmpl"

# After
template:
  type: file
  value: "path/file.tmpl"

```

```yaml
# Before
template: "{{.Rules}}"

# After
template:
  type: inline
  value: "{{.Rules}}"

```

--------------------------------

### Migration failure due to includes (manual intervention required)

Source: https://goldziher.github.io/ai-rulez/migration-guide

The 'includes' directive is being replaced in v2.0. Configurations using 'includes' will fail during automatic migration. Manual intervention is required to either merge the included content directly or utilize the new 'extends' field for configuration inheritance.

```yaml
# This will fail migration
includes:
  - shared/config.yaml

```

--------------------------------

### Enable ai-rulez MCP Server with npx

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet configures the ai-rulez MCP server using 'npx', recommended for Node.js users. It ensures the latest version of ai-rulez is used without global installation. This method is suitable for enabling programmatic interaction with ai-rulez.yml via an AI assistant.

```json
{
  "mcp_servers": {
    "ai-rulez": {
      "command": "npx",
      "args": ["-y", "ai-rulez@latest", "mcp"]
    }
  }
}
```

--------------------------------

### Auto-generated IDs for agents and sections

Source: https://goldziher.github.io/ai-rulez/migration-guide

v2.0 introduces auto-generated IDs for agents and sections, derived from their names. This ensures unique identification and simplifies referencing these entities within the configuration. The 'id' field is added alongside the 'name' (formerly 'title' for sections).

```yaml
# Before
agents:
  - name: code-reviewer
sections:
  - title: Project Overview

# After
agents:
  - name: code-reviewer
    id: code-reviewer        # auto-generated
sections:
  - name: Project Overview   # title → name
    id: project-overview     # auto-generated

```

--------------------------------

### Convert integer priorities to enum with relative bucketing

Source: https://goldziher.github.io/ai-rulez/migration-guide

Priorities in v2.0 are now represented as string enums (critical, high, medium, low, minimal) instead of integers. This change preserves the relative importance of rules while offering a more human-readable and standardized approach to priority management.

```yaml
# Before
rules:
  - name: High Priority Rule
    priority: 100
  - name: Medium Priority Rule  
    priority: 50
  - name: Low Priority Rule
    priority: 1

# After
rules:
  - name: High Priority Rule
    priority: critical      # highest in your config
  - name: Medium Priority Rule
    priority: medium        # middle in your config
  - name: Low Priority Rule
    priority: minimal       # lowest in your config

```

--------------------------------

### Update field names: file to path, title to name

Source: https://goldziher.github.io/ai-rulez/migration-guide

In v2.0, certain field names have been updated for better consistency and clarity. Specifically, the 'file' field is now 'path', and the 'title' field is now 'name'. This applies to sections and potentially other relevant objects within the configuration.

```yaml
# Before
agents:
  - name: code-reviewer
sections:
  - title: Project Overview

# After
agents:
  - name: code-reviewer
sections:
  - name: Project Overview   # title → name

```

--------------------------------

### Initialize ai-rulez Project Configuration

Source: https://goldziher.github.io/ai-rulez/cli

The `init` command creates a new `ai-rulez.yml` file. It can perform intelligent project analysis and optionally use AI assistance for configuration generation. Dependencies include AI CLI tools if `--use-agent` is specified. Inputs are the project name and various flags. Outputs are configuration files and potentially AI-generated content.

```bash
# Quick start with popular AI tools
ai-rulez init "My Project" --popular

# Use a specific preset for targeted tools
ai-rulez init "My Project" --preset claude

# Get AI-powered configuration generation
ai-rulez init "My Project" --preset popular --use-agent claude

# Basic initialization
ai-rulez init "My Awesome Project"

# With popular AI tools
ai-rulez init "My Awesome Project" --popular

# Specific AI tool
ai-rulez init "My Project" --preset claude --with-agents

# Let Claude analyze your project and generate comprehensive rules
ai-rulez init "My Project" --preset popular --use-agent claude

# Use Gemini for configuration generation
ai-rulez init "My Project" --preset gemini --use-agent gemini

# Skip confirmation prompts for automation
ai-rulez init "My Project" --popular --use-agent claude --yes

# Multiple specific providers
ai-rulez init "My Project" --claude --cursor --windsurf

# All supported providers
ai-rulez init "My Project" --all

# Include specialized features
ai-rulez init "My Project" --claude --with-agents --with-sections

```

--------------------------------

### Initialize Advanced ai-rulez Configuration with AI and Presets

Source: https://goldziher.github.io/ai-rulez/cli

Generates a comprehensive ai-rulez configuration using AI assistance and popular presets. It includes metadata, description, presets, rules, sections, and agents, tailored for a Go microservice.

```yaml
$schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
metadata:
  name: "My Project"  
  description: "Go-based microservice with REST API and PostgreSQL backend"
presets:
  - "popular"
rules:
  - name: "Go Code Standards"
    priority: high
    content: "Follow standard Go project layout (cmd/, internal/, pkg/)..."
  - name: "API Design"  
    priority: critical
    content: "RESTful APIs should follow OpenAPI 3.0 specification..."
sections:
  - name: "Architecture Overview"
    priority: critical
    content: "This service implements clean architecture with..."
agents:
  - name: "go-expert"
    description: "Go language specialist for backend development"
    system_prompt: "You are a Go expert focusing on..."

```

--------------------------------

### Set Metadata

Source: https://goldziher.github.io/ai-rulez/cli

Sets the project name and version in the top-level metadata. Requires both name and version as arguments.

```bash
ai-rulez set metadata --name "My Awesome Project" --version "2.0.0"
```

--------------------------------

### Combine Presets and Custom Outputs in ai-rulez

Source: https://goldziher.github.io/ai-rulez/configuration

Demonstrates how to use both `presets` and `outputs` in a single configuration file. Outputs from presets are generated first, followed by custom outputs. Custom outputs with conflicting paths will override preset outputs.

```yaml
# Use the popular preset, but override the Claude file with a custom template
presets:
  - "popular"

outputs:
  - path: "CLAUDE.md" # This will override the default Claude output from the "popular" preset
    template:
      type: "file"
      value: "./my-custom-claude-template.tmpl"

```

--------------------------------

### Reusable Base AI Rulez Configuration (YAML)

Source: https://goldziher.github.io/ai-rulez/monorepo

A shared, reusable base configuration file written in YAML. This file defines common rules and best practices (e.g., Go best practices for microservices) that can be inherited by other specific configurations using the `extends` keyword. This promotes a single source of truth for shared standards.

```yaml
metadata:
  description: "Base configuration for all Go microservices."
rules:
  - name: "Go Best Practices"
    content: "Use structured logging (slog), handle all errors, and write unit tests."
    priority: critical


```

--------------------------------

### List All Rules using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Displays a list of all configured rules within the ai-rulez configuration.

```bash
# List all rules
ai-rulez list rules

```

--------------------------------

### List All Sections using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Displays a list of all configured sections within the ai-rulez configuration.

```bash
# List all sections
ai-rulez list sections

```

--------------------------------

### List All MCP Servers

Source: https://goldziher.github.io/ai-rulez/cli

Lists all configured MCP servers. This command provides an overview of the available MCP server integrations.

```bash
ai-rulez list mcp-servers
```

--------------------------------

### List All Custom Commands

Source: https://goldziher.github.io/ai-rulez/cli

Lists all custom commands configured in the AI rulez system. This helps in reviewing available shortcuts and aliases.

```bash
ai-rulez list commands
```

--------------------------------

### Add Include File

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new file to the 'includes' list. The content of this file will be merged into the main configuration.

```bash
ai-rulez add include "./shared/common-rules.yaml"
```

--------------------------------

### List All Outputs

Source: https://goldziher.github.io/ai-rulez/cli

Lists all configured outputs for the AI rulez system. This command helps in visualizing the current output destinations.

```bash
ai-rulez list outputs
```

--------------------------------

### List All Agents using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Displays a list of all configured AI agents within the ai-rulez configuration.

```bash
# List all agents
ai-rulez list agents

```

--------------------------------

### Generate AI Configuration Files

Source: https://goldziher.github.io/ai-rulez/cli

The `generate` command creates AI instruction files and configures MCP servers. It supports options for updating .gitignore, recursive generation, dry runs, and skipping CLI MCP tool configuration.

```bash
ai-rulez generate
```

```bash
# Generate without updating .gitignore
ai-rulez generate --update-gitignore=false
```

```bash
# Generate files recursively in subdirectories
ai-rulez generate --recursive
```

```bash
# Preview what would be generated without creating files
ai-rulez generate --dry-run
```

```bash
# Skip CLI MCP tool configuration (only generate files)
ai-rulez generate --no-configure-cli-mcp
```

--------------------------------

### Enable ai-rulez MCP Server with uvx

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet configures the ai-rulez MCP server using 'uvx', recommended for Python users. It utilizes 'uvx' to run ai-rulez in an ephemeral environment, providing a way for AI assistants to interact with ai-rulez.yml configurations. This method is useful for maintaining isolated environments.

```json
{
  "mcp_servers": {
    "ai-rulez": {
      "command": "uvx",
      "args": ["ai-rulez", "mcp"]
    }
  }
}
```

--------------------------------

### Set Extends Path

Source: https://goldziher.github.io/ai-rulez/cli

Sets the 'extends' path to a new configuration file, either local or remote. This allows for configuration inheritance.

```bash
ai-rulez set extends "https://example.com/base-config.yaml"
```

--------------------------------

### Configure Output Presets in ai-rulez.yml

Source: https://goldziher.github.io/ai-rulez/configuration

The presets section allows you to easily configure output files for common AI tools using predefined configurations. Each preset bundles settings for specific AI assistants like Claude, Cursor, Copilot, and Gemini.

```yaml
# Use presets for popular tools
presets:
  - "popular" # Includes Claude, Cursor, Windsurf, and Copilot
  - "gemini"

```

--------------------------------

### List Included Files

Source: https://goldziher.github.io/ai-rulez/cli

Lists all files currently included in the AI rulez configuration. These files are merged into the main configuration.

```bash
ai-rulez list includes
```

--------------------------------

### Add a New Agent using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new AI agent to the ai-rulez configuration with a description and a specified template type and value. This allows for custom AI behaviors.

```bash
# Add a new agent with a structured template
ai-rulez add agent "doc-writer" --description "Technical documentation writer" --template-type inline --template-value "Write clear documentation for the following code..."

```

--------------------------------

### Automatic CLI Configuration for Claude CLI

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet configures an MCP server for the Claude CLI. It uses 'uvx' to run 'mcp-server-postgres', sets a DATABASE_URL environment variable, and specifies 'stdio' transport. The 'targets' field indicates that this configuration is intended for '@claude-cli', enabling programmatic interaction with Claude CLI tools.

```json
{
  "mcp_servers": [
    {
      "name": "database-tools",
      "command": "uvx",
      "args": ["mcp-server-postgres"]
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      },
      "transport": "stdio",
      "targets": ["@claude-cli"]
    }
  ]
}
```

--------------------------------

### Add MCP Server

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new MCP server to the configuration. This involves specifying a name, command, arguments, and environment variables for the server.

```bash
ai-rulez add mcp-server "github" --command "npx" --arg "-y" --arg "@mcp/server-github" --env "TOKEN=123"
```

--------------------------------

### Migrating Output Templates from v1.x to v2.x

Source: https://goldziher.github.io/ai-rulez/schema

This snippet illustrates the required migration for output templates when upgrading from ai-rulez v1.x to v2.x. String-based templates are no longer supported and must be converted to the new structured object format, specifying the template `type` and `value`.

```yaml
# ❌ Old v1.x format (no longer supported)
outputs:
  - path: "rules.md"
    template: "documentation"

# ✅ New v2.x format (required)
outputs:
  - path: "rules.md"
    template:
      type: "builtin"
      value: "documentation"

```

--------------------------------

### Define Project Metadata in ai-rulez.yml

Source: https://goldziher.github.io/ai-rulez/configuration

The metadata section provides basic information about your project, such as its name, version, and a brief description. This is useful for organizing and identifying your AI rulez configurations.

```yaml
metadata:
  name: "My Project"
  version: "1.0.0"
  description: "A brief description of the project."

```

--------------------------------

### Configure ai-rulez.yaml for MCP Server

Source: https://goldziher.github.io/ai-rulez/mcp-server

This YAML snippet demonstrates how to define an MCP server within the ai-rulez.yml configuration file. It specifies the server name, command, and arguments required for the 'ai-rulez' MCP server. This configuration is used by the 'ai-rulez generate' command to automatically set up MCP servers.

```yaml
# ai-rulez.yaml
mcp_servers:
  - name: "ai-rulez"
    command: "ai-rulez"
    args: ["mcp"]
    description: "Configuration management server"

```

--------------------------------

### Add a New Section using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new section to the ai-rulez configuration, including an ID and content. Sections can be used for project overviews or architectural descriptions.

```bash
# Add a new section
ai-rulez add section "Project Overview" --id "proj-overview" --content "This project uses a clean architecture..."

```

--------------------------------

### Advanced Output Configuration in ai-rulez.yml

Source: https://goldziher.github.io/ai-rulez/configuration

The outputs section provides advanced, fine-grained control over output files, including file paths, naming schemes, and templates. This is ideal for custom tools or when presets do not meet specific requirements.

```yaml
# For advanced, custom configurations
outputs:
  - path: "CUSTOM_PROMPT.md"
    template:
      type: "inline"
      value: "My custom prompt template..."

```

--------------------------------

### Hybrid MCP Server Configuration

Source: https://goldziher.github.io/ai-rulez/mcp-server

This JSON snippet demonstrates a hybrid MCP server configuration that simultaneously configures CLI tools and generates config files. It specifies targets for '@claude-cli', '@gemini-cli', and a '.cursor/mcp.json' file, enabling automated workflows for multiple targets.

```json
{
  "mcp_servers": [
    {
      "name": "ai-rulez",
      "command": "ai-rulez",
      "args": ["mcp"]
      "targets":
        -"@claude-cli"
        -"@gemini-cli"
        -".cursor/mcp.json"
    }
  ]
}
```

--------------------------------

### Add Custom Command

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new custom command to the AI rulez system. Allows defining an alias, description, and keyboard shortcut for the command.

```bash
ai-rulez add command "new-task" --description "Starts a new task" --alias "nt" --shortcut "Ctrl+Shift+N"
```

--------------------------------

### Generated Custom Linter Configuration

Source: https://goldziher.github.io/ai-rulez/configuration

The resulting `.codesniffer.json` file generated by the `ai-rulez` configuration. This file lists the directories to be scanned by the custom linter.

```json
{
  "scan_directories": [
    "src/",
    "pkg/"
  ]
}

```

--------------------------------

### Validate ai-rulez Configuration

Source: https://goldziher.github.io/ai-rulez/cli

The `validate` command checks the current ai-rulez configuration for any errors or inconsistencies.

```bash
ai-rulez validate

```

--------------------------------

### Add a New Rule using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Adds a new rule to the ai-rulez configuration with specified ID, content, priority, and target files. This allows for granular control over code quality checks.

```bash
# Add a new rule with an ID and targets
ai-rulez add rule "Code Style" --id "style-guide" --content "Follow the official Go style guide." --priority high --target "*.go"

```

--------------------------------

### Enable ai-rulez Schema Validation

Source: https://goldziher.github.io/ai-rulez/schema

To enable editor support like autocompletion and real-time validation for your ai-rulez configuration, add the `$schema` key to the top of your `ai-rulez.yml` file, pointing to the official JSON schema URL. This allows modern editors to provide intelligent assistance.

```yaml
$schema: "https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json"

metadata:
  name: "My Project"
# ... rest of your configuration

```

--------------------------------

### Update an Existing Rule using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Modifies the content of an existing rule in the ai-rulez configuration. This is useful for refining code quality guidelines.

```bash
# Update a rule's content
ai-rulez update rule "Code Style" --content "Follow the official Go style guide, no exceptions."

```

--------------------------------

### Delete Extends Property

Source: https://goldziher.github.io/ai-rulez/cli

Removes the 'extends' property from the configuration, disabling any inherited configuration.

```bash
ai-rulez delete extends
```

--------------------------------

### Delete an MCP Server

Source: https://goldziher.github.io/ai-rulez/cli

Deletes a specified MCP server from the configuration. Requires the name of the MCP server to be removed.

```bash
ai-rulez delete mcp-server "github"
```

--------------------------------

### Delete a Section using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Removes a specific section from the ai-rulez configuration by its name.

```bash
# Delete a section
ai-rulez delete section "Project Overview"

```

--------------------------------

### Delete an Output

Source: https://goldziher.github.io/ai-rulez/cli

Deletes a specified output from the AI rulez configuration. Requires the path to the output to be removed.

```bash
ai-rulez delete output ".claude/agents/"
```

--------------------------------

### Delete a Rule using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Removes a specific rule from the ai-rulez configuration by its name.

```bash
# Delete a rule
ai-rulez delete rule "Code Style"

```

--------------------------------

### Delete Include File

Source: https://goldziher.github.io/ai-rulez/cli

Removes a file from the 'includes' list. This stops the content of the specified file from being merged into the main configuration.

```bash
ai-rulez delete include "./shared/common-rules.yaml"
```

--------------------------------

### Delete an Agent using ai-rulez CLI

Source: https://goldziher.github.io/ai-rulez/cli

Removes a specific AI agent from the ai-rulez configuration by its name.

```bash
# Delete an agent
ai-rulez delete agent "doc-writer"

```

--------------------------------

### Control .gitignore Updates in ai-rulez.yml

Source: https://goldziher.github.io/ai-rulez/configuration

The gitignore setting controls whether ai-rulez automatically updates your .gitignore file with generated files. By default, it's set to true to prevent generated files from being committed, but can be disabled.

```yaml
gitignore: false  # Disable automatic .gitignore updates

```

--------------------------------

### Delete a Custom Command

Source: https://goldziher.github.io/ai-rulez/cli

Deletes a specified custom command from the configuration. Requires the name of the custom command to be removed.

```bash
ai-rulez delete command "new-task"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.