### Project Setup

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Clone the repository, navigate to the directory, install dependencies, and build the project.

```bash
git clone https://github.com/intellectronica/ruler.git
cd ruler
npm install
npm run build
```

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

### Setup new project workflow

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This multi-step example outlines the process of setting up a new project with Ruler, including initialization, rule editing, applying changes, and committing to version control.

```bash
# 1. Initialize Ruler
cd my-project
ruler init

# 2. Edit .ruler/AGENTS.md with your rules
# 3. (Optional) Add MCP servers to .ruler/ruler.toml
# 4. Apply to agents
ruler apply

# 5. Commit to version control
git add .ruler/
git commit -m "Initialize Ruler configuration"
```

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

### Scenario 1: Getting Started Quickly with Ruler

Source: https://github.com/intellectronica/ruler/blob/main/README.md

This scenario outlines the initial steps to set up and apply Ruler rules in your project. It involves initializing Ruler, adding guidelines, and applying the rules.

```bash
# Initialize Ruler in your project
cd your-project
ruler init

# Edit the generated files
# - Add your coding guidelines to .ruler/AGENTS.md (or keep adding additional .md files)
# - Customize .ruler/ruler.toml if needed

# Apply rules to all AI agents
ruler apply

```

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

### Complete Configuration Example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

A comprehensive TOML configuration file demonstrating default agents, nested rule loading, global MCP settings, gitignore, backup, skills, subagents, and detailed agent-specific configurations. This serves as a template for a full Ruler setup.

```toml
# Default agents to run
default_agents = ["copilot", "claude", "aider"]

# Enable nested rule loading
nested = false

# Global MCP configuration
[mcp]
enabled = true
merge_strategy = "merge"

# Define global MCP servers
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]

[mcp_servers.remote_api]
url = "https://api.example.com"

[mcp_servers.remote_api.headers]
Authorization = "Bearer your-token"

# Gitignore configuration
[gitignore]
enabled = true
local = false

# Backup configuration
[backup]
enabled = true

# Skills configuration
[skills]
enabled = true

# Subagents configuration
[agents]
enabled = true
cleanup_orphaned = false
include_in_rules = false

# Agent-specific configurations
[agents.copilot]
enabled = true

[agents.claude]
enabled = true
output_path = "CLAUDE.md"

[agents.claude.mcp]
enabled = true
merge_strategy = "merge"

[agents.aider]
enabled = true
output_path_instructions = "AGENTS.md"
output_path_config = ".aider.conf.yml"

[agents.codex]
enabled = true
output_path = "AGENTS.md"
output_path_config = ".codex/config.toml"

[agents.firebase]
enabled = true
output_path = ".idx/airules.md"

[agents.windsurf]
enabled = false
```

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

### Install Ruler Globally

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Installs the Ruler CLI globally using npm. This command is used for initial setup.

```bash
npm install -g @intellectronica/ruler
```

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

### Makefile Usage Examples

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Demonstrates how to invoke the Ruler-related targets defined in a Makefile. Shows commands for applying, checking, reverting, and setup.

```bash
make ruler-apply
make ruler-check
make ruler-revert
make setup
```

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

### Full revert example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This example demonstrates a comprehensive revert operation, specifying the project root, target agents, backup retention, and verbose output.

```bash
ruler revert \
  --project-root /path/to/project \
  --agents claude,copilot,aider \
  --keep-backups \
  --verbose
```

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

### Verbose output example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This example demonstrates the detailed output provided when using the `--verbose` flag, showing configuration loading, agent selection, and rule application steps.

```bash
[ruler:verbose] Loading configuration from project root: /path/to/project
[ruler:verbose] Found .ruler directory at: /path/to/project/.ruler
[ruler:verbose] Loaded configuration with 4 agent configs
[ruler:verbose] Found .ruler directory with 1234 characters of rules
[ruler:verbose] Selected 4 agents: claude, copilot, cursor, cline
[ruler:verbose] Applying rules to: Claude Code
[ruler:verbose] Applying rules to: GitHub Copilot
```

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

### Example Python Project Guidelines

Source: https://github.com/intellectronica/ruler/blob/main/README.md

An example rule file demonstrating guidelines for a Python project, covering style, error handling, and security.

```markdown
# Python Project Guidelines

## General Style

- Follow PEP 8 for all Python code
- Use type hints for all function signatures and complex variables
- Keep functions short and focused on a single task

## Error Handling

- Use specific exception types rather than generic `Exception`
- Log errors effectively with context

## Security

- Always validate and sanitize user input
- Be mindful of potential injection vulnerabilities
```

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

### Example Workflow: Authoring and Applying a Subagent

Source: https://github.com/intellectronica/ruler/blob/main/README.md

This example demonstrates how to create a subagent, configure Ruler to enable subagents, and apply the changes. The subagent will then be available in various agent locations.

```bash
# 1. Author a subagent in your project
mkdir -p .ruler/agents
cat > .ruler/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: Reviews changes against SOLID/DRY/KISS
tools: [Read, Grep, Glob]
readonly: true
---

You review code changes for quality.
EOF

# 2. Opt subagents in (default is disabled — see [agents] section above)
echo -e "\n[agents]\nenabled = true" >> .ruler/ruler.toml

# 3. Apply
ruler apply

# 4. The subagent is now available in each agent's native location:
#    - Claude Code:  .claude/agents/code-reviewer.md
#    - Cursor:       .cursor/agents/code-reviewer.md
#    - Codex CLI:    .codex/agents/code-reviewer.toml
#    - GitHub Copilot: .github/agents/code-reviewer.md

```

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

### NPM Script Usage Examples

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Examples of how to execute the defined NPM scripts for Ruler operations.

```bash
npm run ruler:apply
npm run ruler:check
npm run ruler:revert
```

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

### Full Ruler Apply Example with Multiple Options

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

A comprehensive example demonstrating the use of multiple options for the ruler apply command, including project root, agents, custom config, MCP, gitignore, nested mode, backup, skills, and verbosity.

```bash
ruler apply \
  --project-root /path/to/project \
  --agents claude,copilot \
  --config /path/to/custom.toml \
  --mcp \
  --gitignore \
  --nested \
  --backup \
  --skills \
  --verbose
```

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

### Apply Ruler Configuration in GitHub Actions

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Installs Ruler globally and applies the configuration. Use this in CI/CD pipelines to ensure consistent project setup.

```bash
npm install -g @intellectronica/ruler
ruler apply --no-gitignore --verbose
```

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

### Example Subagent Source File

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Illustrates the structure of a subagent definition file, including YAML frontmatter and the main content body. This example shows how to define a subagent's name, description, tools, and other properties.

```markdown
---
name: code-reviewer
description: Reviews code changes against SOLID/DRY/KISS principles
tools: [Read, Grep, Glob, Bash]
model: claude-opus-4-8
readonly: true
is_background: false
---

# Code Reviewer

You review code changes for quality and adherence to design principles.
```

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

### TOML configuration with MCP servers

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Example `ruler.toml` including configurations for MCP filesystem and git servers.

```toml
default_agents = ["claude", "copilot"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
```

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

### TOML settings precedence example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Shows how settings are defined in the `ruler.toml` file for MCP and skills.

```toml
[mcp]
enabled = true

[skills]
enabled = false

[agents]
enabled = true
```

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

### Install Git Hooks

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Copies pre-commit hook to the .git/hooks directory and makes it executable. Alternatively, creates the hook programmatically.

```bash
# Copy hooks to .git/hooks
mkdir -p .git/hooks
cp .ruler/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Or create hooks programmatically
echo '#!/bin/sh
npx @intellectronica/ruler apply
git add CLAUDE.md AGENTS.md
' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

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

### Get Ruler Version

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Use this command to find the globally installed version of the Ruler CLI.

```bash
npm list -g @intellectronica/ruler
```

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

### Skills Directory Structure Example

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Illustrates the organization of skills within the `.ruler/skills/` directory, including required and optional files.

```tree
.ruler/skills/
├── my-skill/
│   ├── SKILL.md           # Required: skill instructions/knowledge
│   ├── helper.py          # Optional: additional resources (scripts)
│   └── reference.md       # Optional: additional resources (docs)
└── another-skill/
    └── SKILL.md
```

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

### Get Node Version

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Check the installed Node.js version, which might be relevant for compatibility issues.

```bash
node --version
```

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

### Install Ruler Globally

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

If you encounter a 'Cannot find module' error, you may need to install Ruler globally. Alternatively, you can use `npx` or install it as a local development dependency.

```bash
# Install globally
npm install -g @intellectronica/ruler
```

```bash
# Or use npx
npx @intellectronica/ruler apply
```

```bash
# Or install locally
npm install --save-dev @intellectronica/ruler
npx ruler apply
```

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

### CLI flag precedence example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Demonstrates the highest precedence for settings when using CLI flags.

```bash
ruler apply --mcp --subagents --no-skills
```

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

### Manage multiple teams workflow

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This example shows how to manage different teams or projects by using separate configuration files for Ruler, specified with the `--config` flag.

```bash
# Use different config files for different teams
ruler apply --config ./team-configs/frontend.toml --agents claude,copilot
ruler apply --config ./team-configs/backend.toml --agents claude,cursor
```

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

### Ruler TOML Configuration Example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/00-START-HERE.md

This TOML snippet shows how to configure default agents, MCP servers, and individual agent settings like enabling them and specifying output paths.

```toml
default_agents = ["claude", "copilot"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

[agents.claude]
enabled = true
outputPath = "CLAUDE.md"

```

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

### Dry-run output example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This example shows the typical output when running Ruler with the `--dry-run` option, indicating which files would be written without making any actual changes.

```bash
[ruler:dry-run] Would write: CLAUDE.md
[ruler:dry-run] Would write: AGENTS.md
[ruler:dry-run] Dry-run complete — no files modified
```

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

### Custom Agent Implementation Example

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/api-reference-main.md

An example of extending the AbstractAgent class to create a custom agent named 'MyCustomAgent'. This demonstrates implementing required abstract methods and enabling specific features like MCP stdio and native skills.

```typescript
import { AbstractAgent } from '@intellectronica/ruler';

export class MyCustomAgent extends AbstractAgent {
  getIdentifier(): string {
    return 'myagent';
  }

  getName(): string {
    return 'My Custom Agent';
  }

  getDefaultOutputPath(projectRoot: string): string {
    return path.join(projectRoot, 'MY_AGENT.md');
  }

  supportsMcpStdio(): boolean {
    return true;
  }

  supportsNativeSkills(): boolean {
    return true;
  }
}
```

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

### Run Ruler Without Installation

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Executes the Ruler CLI without a global installation using npx. Useful for quick, one-off commands.

```bash
npx @intellectronica/ruler apply
```

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

### Configuration validation error examples

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Illustrates common validation errors encountered when loading `ruler.toml`.

```bash
[ruler] Invalid TOML syntax: Expected key=value at line 5
[ruler] Invalid MCP merge_strategy: must be 'merge' or 'overwrite'
[ruler] Unknown agent identifier: 'myagent'
```

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

### Skills Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of configuring skills settings in ruler.toml. Enabling this setting activates the automated distribution of skills from the .ruler/skills/ directory.

```toml
[skills]
enabled = true
```

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

### Set XDG_CONFIG_HOME environment variable

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Example of setting the `XDG_CONFIG_HOME` environment variable to control the global Ruler configuration directory.

```bash
export XDG_CONFIG_HOME="/home/user/.config"
# Ruler looks in: /home/user/.config/ruler/ruler.toml
```

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

### Complete ruler.toml configuration example

Source: https://github.com/intellectronica/ruler/blob/main/README.md

This TOML configuration file defines default agents, MCP server settings, and gitignore behavior. It allows customization of Ruler's operation.

```toml
# Default agents to run when --agents is not specified
# Uses case-insensitive substring matching
default_agents = ["copilot", "claude", "aider"]

# --- Global MCP Server Configuration ---
[mcp]
# Enable/disable MCP propagation globally (default: true)
enabled = true
# Global merge strategy: 'merge' or 'overwrite' (default: 'merge')
merge_strategy = "merge"

# --- MCP Server Definitions ---
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]

[mcp_servers.remote_api]
url = "https://api.example.com"

[mcp_servers.remote_api.headers]
Authorization = "Bearer your-token"

# --- Global .gitignore Configuration ---
[gitignore]
# Enable/disable automatic .gitignore updates (default: true)
enabled = true
# Write managed entries to .git/info/exclude instead of .gitignore (default: false)
local = false

# --- Backup Configuration ---
[backup]
# Enable/disable creation of .bak backup files (default: true)
enabled = true

```

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

### Backup Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of configuring backup settings in ruler.toml. Enabling this setting ensures that .bak backup files are created before agent config files are overwritten.

```toml
[backup]
enabled = true
```

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

### Example Agent Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/api-reference-main.md

Illustrates how to configure a specific agent, 'claude', in the ruler.toml file, including enabling it, overriding output paths, and setting MCP propagation details.

```toml
[agents.claude]
enabled = true
outputPath = "CLAUDE.md"

[agents.claude.mcp]
enabled = true
merge_strategy = "merge"

[agents.claude.mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
```

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

### Initialize global configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

To initialize Ruler's global configuration, use the `--global` flag. This installs Ruler's configuration files in the user's global config directory.

```bash
ruler init --global
```

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

### Experiment safely workflow

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This workflow guides users on how to experiment with new Ruler configurations safely, including testing with `--dry-run`, applying changes, and reverting if issues arise.

```bash
# 1. Try new configuration
ruler apply --agents claude --dry-run

# 2. Actually apply
ruler apply --agents claude

# 3. Test in your AI tool
# ...

# 4. If problems, revert
ruler revert --agents claude

# 5. Fix and retry
# Edit .ruler/AGENTS.md
ruler apply --agents claude
```

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

### TOML configuration to disable agents

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Example `ruler.toml` demonstrating how to disable specific agents while keeping them in the default list.

```toml
default_agents = ["claude", "copilot", "cursor", "cline"]

[agents.cline]
enabled = false

[agents.windsurf]
enabled = false
```

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

### Local STDIN/STDOUT MCP Server Configuration

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Example TOML configuration for a local MCP server that communicates via stdio. Includes specifying the command, arguments, and environment variables.

```toml
[mcp_servers.local_server]
command = "node"
args = ["server.js"]

[mcp_servers.local_server.env]
DEBUG = "1"
```

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

### Docker Compose for Development

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Configures a Docker Compose service to run Ruler apply and then start the development server. Mounts volumes for persistent development.

```yaml
version: '3'
services:
  app:
    build: .
    volumes:
      - .:/project
      - /project/node_modules
    environment:
      NODE_ENV: development
    command: sh -c "ruler apply && npm run dev"
```

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

### Apply Agent Config with McpStrategy

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Demonstrates applying agent configurations using a specified McpStrategy. Ensure the 'applyAllAgentConfigs' function and necessary project setup are available.

```typescript
const strategy: McpStrategy = 'merge';
await applyAllAgentConfigs(
  projectRoot,
  ['claude'],
  undefined,
  true,
  strategy,  // Merge mode
);
```

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

### Agent Configurations in TOML

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Example TOML configurations for enabling agents like Copilot, Claude, Aider, Codex, Firebase, Gemini-CLI, Jules, Junie, Cursor, Windsurf, Kilocode, and Warp. Includes settings for output paths and MCP configurations.

```toml
[agents.copilot]
enabled = true

[agents.claude]
enabled = true
output_path = "CLAUDE.md"

[agents.aider]
enabled = true
output_path_instructions = "AGENTS.md"
output_path_config = ".aider.conf.yml"

# OpenAI Codex CLI agent and MCP config
[agents.codex]
enabled = true
output_path = "AGENTS.md"
output_path_config = ".codex/config.toml"

# Agent-specific MCP configuration for Codex CLI
[agents.codex.mcp]
enabled = true
merge_strategy = "merge"

[agents.firebase]
enabled = true
output_path = ".idx/airules.md"

[agents.gemini-cli]
enabled = true

[agents.jules]
enabled = true

[agents.junie]
enabled = true
output_path = ".junie/guidelines.md"

[agents.junie.mcp]
enabled = true
merge_strategy = "merge"

# Agent-specific MCP configuration
[agents.cursor.mcp]
enabled = true
merge_strategy = "merge"

# Disable specific agents
[agents.windsurf]
enabled = false

[agents.kilocode]
enabled = true
output_path = "AGENTS.md"

[agents.warp]
enabled = true
output_path = "WARP.md"
```

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

### Gitignore Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of configuring gitignore settings in ruler.toml. This enables automatic .gitignore updates and specifies that entries should not be written to local exclude files.

```toml
[gitignore]
enabled = true
local = false
```

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

### Global MCP Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of configuring global MCP settings in a ruler.toml file. This sets the MCP server propagation to enabled and uses the 'merge' strategy.

```toml
[mcp]
enabled = true
merge_strategy = "merge"
```

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

### Dockerfile for Ruler Integration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Integrates Ruler into a Dockerfile using a Node.js base image. Installs Ruler globally and applies configurations before the build process.

```dockerfile
FROM node:20-alpine

WORKDIR /project

# Install Ruler
RUN npm install -g @intellectronica/ruler

# Copy project
COPY . .

# Apply Ruler configuration
RUN ruler apply

# Continue with build
CMD ["npm", "run", "build"]
```

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

### Nested projects (monorepo) workflow

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

This example illustrates how to set up and use Ruler in a monorepo structure by creating `.ruler` directories at different levels and using the `--nested` flag.

```bash
# Create .ruler directories at different levels
mkdir -p src/.ruler tests/.ruler

# Use nested mode
ruler apply --nested --verbose

# Each level maintains its own rules and MCP config
```

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

### Remote MCP Server Configuration

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Example TOML configuration for a remote MCP server. Includes the URL and optional headers for authentication or versioning.

```toml
[mcp_servers.remote_server]
url = "https://api.example.com"

[mcp_servers.remote_server.headers]
Authorization = "Bearer token"
```

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

### GitLab CI Configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Automate Ruler application as a setup stage in GitLab CI pipelines. Ensures Ruler is applied before artifacts are collected.

```yaml
apply_ruler:
  stage: setup
  image: node:20
  script:
    - npm install -g @intellectronica/ruler
    - ruler apply --verbose
  artifacts:
    paths:
      - CLAUDE.md
      - AGENTS.md
      - .gitignore
  only:
    - merge_requests
    - main
```

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

### Legacy MCP Server Configuration in JSON

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Example of configuring MCP servers using the deprecated JSON format. This format is supported for backward compatibility but migration to TOML is recommended.

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
      ]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
    }
  }
}
```

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

### Valid MCP Server Formats

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Provides examples of valid STDIO and HTTP MCP server configurations in TOML format. Ensure your MCP server definitions adhere to these structures.

```toml
# STDIO server (requires command)
[mcp_servers.local]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

# HTTP server (requires url)
[mcp_servers.remote]
url = "https://api.example.com"
headers = { Authorization = "Bearer token" }
```

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

### GitHub Actions: Basic Ruler Apply in CI

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Set up a GitHub Actions workflow to automatically apply Ruler configurations on pull requests that modify Ruler-related paths. Includes installation and application steps.

```yaml
name: Update Ruler Configuration
on:
  pull_request:
    paths: ['.ruler/**']

jobs:
  apply-ruler:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Ruler
        run: npm install -g @intellectronica/ruler

      - name: Apply Ruler configuration
        run: ruler apply --no-gitignore

      - name: Check for unexpected changes
        run: |
          if [[ -n $(git status --porcelain) ]]; then
            echo "Ruler configuration is out of sync!"
            echo "Please run 'ruler apply' locally and commit changes."
            git diff
            exit 1
          fi
```

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

### Initialize Project Command

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/INDEX.md

Use the 'ruler init' command to set up the .ruler/ directory in your project. You can specify the project root and whether to initialize globally.

```bash
ruler init [--project-root /path] [--global]
```

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

### Example .gitignore Section Managed by Ruler

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Ruler manages a specific block within your .gitignore file to keep generated agent configuration files out of version control. This block is marked with start and end comments.

```gitignore
# Your existing rules
node_modules/
*.log

# START Ruler Generated Files
.aider.conf.yml
.clinerules
AGENTS.md
CLAUDE.md
# END Ruler Generated Files

dist/

```

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

### Initialize Ruler

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/00-START-HERE.md

Use the 'ruler init' command to set up the .ruler/ directory in your project.

```bash
# Initialize Ruler in your project
ruler init

```

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

### ruler init command options

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Lists available flags for the `ruler init` command, specifying project root and global initialization.

```bash
ruler init [options]
```

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

### Full Skill Application Workflow

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Demonstrates the complete process of adding a new skill, applying it to agents, and verifying its propagation.

```bash
# 1. Add a skill to your project
mkdir -p .ruler/skills/my-skill
cat > .ruler/skills/my-skill/SKILL.md << 'EOF'
# My Custom Skill

This skill provides specialized knowledge for...

## Usage

When working on this project, always follow these guidelines:
- Use TypeScript for all new code
- Write tests for all features
- Follow the existing code style
EOF

# 2. Apply to all agents (skills enabled by default)
ruler apply

# 3. Skills are now available to compatible agents:
#    - Claude Code, GitHub Copilot & Kilo Code: .claude/skills/my-skill/
#    - OpenAI Codex CLI: .codex/skills/my-skill/
#    - OpenCode: .opencode/skills/my-skill/
#    - Pi Coding Agent: .pi/skills/my-skill/
#    - Goose, Amp & Zed: .agents/skills/my-skill/
#    - Antigravity: .agent/skills/my-skill/
#    - Factory Droid: .factory/skills/my-skill/
#    - Mistral Vibe: .vibe/skills/my-skill/
#    - Roo Code: .roo/skills/my-skill/
#    - Gemini CLI: .gemini/skills/my-skill/
#    - Junie: .junie/skills/my-skill/
#    - Cursor: .cursor/skills/my-skill/
#    - Windsurf: .windsurf/skills/my-skill/
```

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

### Get Native MCP Path

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Gets the absolute path to an agent's native MCP configuration file within the project root.

```typescript
function getNativeMcpPath(agent: IAgent, projectRoot: string): string
```

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

### Troubleshoot Agent Configuration Application

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Check the output path in ruler.toml, use --dry-run with --verbose to preview changes, and ensure parent directories for output exist.

```bash
# Check output path in ruler.toml
[agents.claude]
output_path = "CLAUDE.md"    # Must be valid path

# Try dry-run to preview
ruler apply --dry-run --verbose

# Check if parent directories exist
mkdir -p /path/to/parent/dir
```

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

### Scenario 2: Setting Up Nested Rule Loading

Source: https://github.com/intellectronica/ruler/blob/main/README.md

This scenario demonstrates how to configure Ruler for complex projects with nested rule directories. It involves creating nested .ruler directories and adding component-specific instructions.

```bash
# Set up nested .ruler directories
mkdir -p src/.ruler tests/.ruler docs/.ruler

# Add component-specific instructions
echo "# API Design Guidelines" > src/.ruler/api_rules.md
echo "# Testing Best Practices" > tests/.ruler/test_rules.md
echo "# Documentation Standards" > docs/.ruler/docs_rules.md

```

```toml
# .ruler/ruler.toml
nested = true

```

```bash
# The CLI inherits nested mode from ruler.toml
ruler apply --verbose

# Override from the CLI at any time
ruler apply --no-nested

```

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

### Apply Configurations with a Custom Config File

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Applies configurations using a custom TOML file path instead of the default .ruler/ruler.toml.

```bash
ruler apply --config ./team-configs/ruler.toml
```

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

### getNativeMcpPath

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Gets the absolute path to an agent's native MCP configuration file within the project.

```APIDOC
## Function: `getNativeMcpPath`

### Description
Gets the absolute path to an agent's native MCP configuration file within the project.

### Signature
```typescript
function getNativeMcpPath(agent: IAgent, projectRoot: string): string
```

### Returns:
Absolute path to agent's native MCP config file
```

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

### Run Formatting

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Automatically format the code to adhere to project style guidelines.

```bash
npm run format
```

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

### Set CODEX_HOME environment variable

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Example of setting the `CODEX_HOME` environment variable for the OpenAI Codex CLI agent.

```bash
export CODEX_HOME="$(pwd)/.codex"
```

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

### Verify File Paths and Configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Ensure that all file paths specified in your configuration are correct and that the --config flag points to an existing ruler.toml file.

```bash
# Check file paths in configuration
# Verify --config path exists
ruler apply --config /actual/path/to/ruler.toml
```

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

### Monorepo TOML configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

TOML configuration for a monorepo setup, enabling nested rules and defining MCP settings.

```toml
nested = true
default_agents = ["claude", "copilot"]

[mcp]
enabled = true
merge_strategy = "merge"

[agents.claude]
enabled = true

[agents.copilot]
enabled = true
```

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

### Initialize Ruler Project

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/README.md

Initializes the .ruler/ directory for a project. Can specify a project root and whether to use global configuration.

```bash
ruler init [--project-root path] [--global]
```

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

### findRulerDir

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Searches for the nearest `.ruler/` directory starting from the specified project root. It can optionally check global configurations.

```APIDOC
## Function: `findRulerDir`

Searches for the nearest `.ruler/` directory.

### Parameters:

- **projectRoot** (string) - Required - The root directory to start searching from.
- **checkGlobal** (boolean) - Optional - Whether to check global configurations. Defaults to true.

### Returns:

Promise<string | null> - Path to `.ruler/` directory or null if not found
```

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

### Ruler CLI Commands

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/00-START-HERE.md

Ruler provides three main commands: 'init' to set up the .ruler/ directory, 'apply' to apply rules to agents, and 'revert' to undo changes. See cli-reference.md for more details.

```bash
ruler init        # Set up .ruler/ directory
ruler apply       # Apply rules to agents
ruler revert      # Undo all changes

```

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

### Global Backup Configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Enable or disable the creation of .bak backup files before Ruler overwrites existing files.

```toml
[backup]
# Enable/disable creation of .bak backup files
enabled = true
```

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

### Find Ruler Directory

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Asynchronously searches for the nearest `.ruler/` directory starting from the project root. Optionally checks global locations.

```typescript
async function findRulerDir(
  projectRoot: string,
  checkGlobal = true,
): Promise<string | null>
```

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

### Managed Block Markers in .gitignore

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Ruler maintains a managed block within the .gitignore file, indicated by START and END markers.

```gitignore
# START Ruler Generated Files
CLAUDE.md
AGENTS.md
# END Ruler Generated Files
```

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

### Apply Configurations with Skills and Subagents Enabled

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Applies configurations with both experimental skills and subagents distribution features enabled.

```bash
ruler apply --skills --subagents
```

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

### Validate TOML Syntax

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Use the ruler CLI with the --verbose flag to get more details on parsing issues and to validate TOML syntax.

```bash
# Validate TOML syntax
# Look for:
# - Missing quotes: key = value (should be key = "value")
# - Wrong brackets: [section name] vs [section.subsection]
# - Invalid characters or formatting

# Use --verbose to see parsing details
ruler apply --verbose
```

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

### Display Project Structure

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Show the top-level structure of the Ruler configuration directory, limited to two levels deep.

```bash
tree -L 2 .ruler/
```

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

### TOML configuration for custom output paths

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Shows how to specify custom output paths for different agents in `ruler.toml`.

```toml
[agents.claude]
output_path = "project-root/CLAUDE.md"

[agents.aider]
output_path_instructions = "project-root/AIDER_RULES.md"
output_path_config = "project-root/.aider.conf.yml"
```

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

### Configuration validation errors

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Examples of common validation errors encountered with the `ruler.toml` configuration file, indicating issues with syntax, strategy, or agent identifiers.

```bash
[ruler] Invalid TOML syntax: Expected key=value at line 5
[ruler] Invalid MCP merge_strategy: must be 'merge' or 'overwrite'
[ruler] Unknown agent identifier: 'myagent'
[ruler] TOML parse error: ...
```

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

### Profile Configuration Loading

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

To diagnose slow configuration loading, profile the `ruler apply` command with the `--verbose` flag and filter the output for 'Loading' messages. Also, check the size of your rule files.

```bash
# Profile configuration loading
ruler apply --verbose 2>&1 | grep "Loading"
```

```bash
# Check for large rule files
du -sh .ruler/
```

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

### Vite/Webpack Integration with Ruler Plugin

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Integrate Ruler into Vite or Webpack build configurations to automatically apply Ruler configurations when the development server starts.

```javascript
// vite.config.ts
import { defineConfig } from 'vite';
import { spawn } from 'child_process';

function rulerPlugin() {
  return {
    name: 'ruler-plugin',
    apply: 'serve',
    configResolved: () => {
      // Apply Ruler when dev server starts
      spawn('ruler', ['apply'], { stdio: 'inherit' });
    },
  };
}

export default defineConfig({
  plugins: [rulerPlugin()],
});
```

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

### loadSingleConfiguration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Loads configuration from a single .ruler/ directory. It returns the loaded configuration, concatenated rules, MCP JSON, and the project root.

```APIDOC
## Function: loadSingleConfiguration

### Description
Loads configuration from a single `.ruler/` directory.

### Parameters
#### Path Parameters
- **projectRoot** (string) - Required - Project root directory
- **configPath** (string) - Optional - Optional custom config path
- **localOnly** (boolean) - Required - Skip global config lookup

### Returns
Configuration object with loaded config, concatenated rules, and MCP JSON
```

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

### Run All Tests

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Execute all defined test suites for the project.

```bash
npm test
```

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

### Agent-Specific MCP Configuration in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of configuring MCP settings for a specific agent (e.g., 'claude') in ruler.toml. This enables MCP for the agent and sets the strategy to 'overwrite'.

```toml
[agents.claude.mcp]
enabled = true
merge_strategy = "overwrite"
```

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

### Makefile Targets for Ruler

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Defines Makefile targets for common Ruler operations like init, apply, check, and revert. Includes targets for setup, dev, and CI.

```makefile
.PHONY: ruler-init ruler-apply ruler-check ruler-revert

ruler-init:
	ruler init

ruler-apply:
	ruler apply

ruler-check:
	ruler apply --dry-run

ruler-revert:
	ruler revert

ruler-verbose:
	ruler apply --verbose

setup: ruler-apply
	npm install

dev: ruler-apply
	npm run dev

ci: ruler-check
	npm test
```

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

### Initialize Ruler in specific directory

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Use the `--project-root` option to specify a directory where Ruler should be initialized. This is useful for projects not located in the current working directory.

```bash
ruler init --project-root /path/to/project
```

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

### JetBrains IDE Run Configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Sets up a run configuration for JetBrains IDEs to execute the 'ruler:apply' npm script. Allows running Ruler from the IDE.

```xml
<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="Ruler: Apply" type="js.build_tools.npm">
    <package-json value="$PROJECT_DIR$/package.json" />
    <command value="run" />
    <scripts>
      <script value="ruler:apply" />
    </scripts>
    <node-interpreter value="project" />
  </configuration>
</component>
```

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

### Enable verbose logging for configuration diagnostics

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

Command to enable verbose logging for detailed diagnostics during configuration loading.

```bash
ruler apply --verbose
```

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

### Apply Configurations to All Agents

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Applies configurations from the default .ruler/ directory to all configured agents. This is the simplest form of the apply command.

```bash
ruler apply
```

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

### backupFile

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Backs up an existing file by creating a `.bak` copy. If the backup file already exists, it will be overwritten. If the original file does not exist, this function does nothing.

```APIDOC
## Function: `backupFile`

Backs up an existing file to `.bak`.

### Parameters:

- **filePath** (string) - Required - The path of the file to back up.

### Behavior:

- If file exists, copies to `${filePath}.bak`
- If `.bak` already exists, overwrites it
- If file doesn't exist, does nothing

### Returns:

Promise<void>
```

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

### Preview Configuration Changes

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Performs a dry run of the apply command, showing potential changes without writing them to disk. Useful for verification.

```bash
ruler apply --dry-run
```

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

### Permission Denied File System Error

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Indicates insufficient permissions to read or write files. Check directory permissions, use sudo if necessary, or adjust file ownership.

```text
[ruler] EACCES: permission denied, open '/path/to/file'
```

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

### SubagentsConfig Usage in ruler.toml

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/types.md

Example of how to configure subagent settings within the ruler.toml file. These settings control features like enabling subagent propagation and cleaning up orphaned directories.

```toml
[agents]
enabled = true
cleanup_orphaned = false
include_in_rules = false
```

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

### Verify Ruler Configuration Applied

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

A bash script to verify that required Ruler configuration files exist and contain the expected content. Exits with an error if verification fails.

```bash
#!/bin/bash
# verify-ruler.sh

REQUIRED_FILES=("CLAUDE.md" "AGENTS.md")

for file in "${REQUIRED_FILES[@]}"; do
  if [[ ! -f "$file" ]] || ! grep -q "Generated by Ruler" "$file"; then
    echo "ERROR: $file not generated by Ruler"
    exit 1
  fi
done

echo "✓ All Ruler configurations verified"
```

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

### File Not Found Error

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Occurs when a referenced file does not exist. Verify file paths in your configuration and ensure the --config path is correct.

```text
[ruler] ENOENT: no such file or directory
```

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

### Display Ruler Configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Show the content of the main Ruler configuration file.

```bash
cat .ruler/ruler.toml
```

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

### processSingleConfiguration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/core-modules.md

Applies rules from a single configuration to selected agents. It returns an array of generated file paths.

```APIDOC
## Function: processSingleConfiguration

### Description
Applies rules from a single configuration to selected agents.

### Parameters
#### Path Parameters
- **selectedAgents** (IAgent[]) - Required - The agents to apply rules to
- **singleConfig** (RulerConfiguration) - Required - The single configuration to apply
- **projectRoot** (string) - Required - Project root directory
- **verbose** (boolean) - Required - Enable verbose output
- **dryRun** (boolean) - Required - Perform a dry run without making changes
- **cliMcpEnabled** (boolean) - Required - Enable MCP processing via CLI
- **cliMcpStrategy** (McpStrategy) - Optional - The MCP strategy to use
- **backupEnabled** (boolean) - Optional - Enable backup of modified files

### Returns
Array of generated file paths
```

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

### Manually Restore from Backup and Revert

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Check if the backup file exists, manually restore it if necessary using cp, and then attempt the ruler revert command again.

```bash
# Check if backup exists
ls -la /path/to/file.bak

# Manually restore if needed
cp /path/to/file.bak /path/to/file

# Then try revert again
ruler revert
```

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

### Check for .ruler Directory

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

When configuration is not applied, verify the existence of the `.ruler` directory in your project root. This directory is essential for Ruler's operation.

```bash
ls -la .ruler/
```

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

### Set Custom XDG Config Home and Initialize Ruler Globally

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Configures the directory for global Ruler configuration files and initializes Ruler within that directory. This allows for centralized management of global Ruler settings.

```bash
export XDG_CONFIG_HOME="/custom/config/dir"
ruler init --global
```

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

### Apply Configurations to Specific Agents

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/cli-reference.md

Applies configurations to a specified list of agents. Agent identifiers are comma-separated.

```bash
ruler apply --agents claude,copilot
```

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

### Run Tests with Coverage

Source: https://github.com/intellectronica/ruler/blob/main/README.md

Execute all tests and generate a code coverage report.

```bash
npm run test:coverage
```

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

### Neovim Keymaps for Ruler

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/integration-guide.md

Sets up key mappings in Neovim for Ruler commands, including apply, check, and revert. Uses Lua for configuration.

```lua
-- Neovim
vim.keymap.set('n', '<leader>ra', ':!ruler apply<CR>', {})
vim.keymap.set('n', '<leader>rc', ':!ruler apply --dry-run<CR>', {})
vim.keymap.set('n', '<leader>rr', ':!ruler revert<CR>', {})
```

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

### Minimal TOML configuration

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/configuration.md

A basic `ruler.toml` file specifying default agents.

```toml
default_agents = ["claude", "copilot"]
```

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

### Check Agent Spelling and Use Substring Matching

Source: https://github.com/intellectronica/ruler/blob/main/_autodocs/errors-and-diagnostics.md

Use the ruler CLI to apply configurations, checking agent spelling (case-insensitive) and utilizing substring matching for agent identifiers.

```bash
# Check agent spelling (case-insensitive)
ruler apply --agents claude,copilot

# Use substring matching
ruler apply --agents code    # Matches: claude, opencode, kilocode, etc.
```