From 682fa28267c157e7e2ec216f5a6b036ad286bddf Mon Sep 17 00:00:00 2001 From: Jon Andersen Date: Fri, 23 Jan 2026 16:14:38 -0500 Subject: [PATCH 1/2] Update readme Signed-off-by: Jon Andersen --- README.md | 503 ++++-------------------------------- docs/agents.md | 26 ++ docs/commands-and-skills.md | 114 ++++++++ docs/configuration.md | 34 +++ docs/mcp.md | 41 +++ docs/project-structure.md | 78 ++++++ docs/rule-format.md | 60 +++++ 7 files changed, 397 insertions(+), 459 deletions(-) create mode 100644 docs/agents.md create mode 100644 docs/commands-and-skills.md create mode 100644 docs/configuration.md create mode 100644 docs/mcp.md create mode 100644 docs/project-structure.md create mode 100644 docs/rule-format.md diff --git a/README.md b/README.md index 9c8b37e..3ed05eb 100644 --- a/README.md +++ b/README.md @@ -1,516 +1,101 @@ # AI Rules Tool -CLI tool to manage AI rules across different AI coding agents. Standardize and distribute your coding guidelines and preferences across various development environments including AMP, Claude, Cline, Codex, Copilot, Cursor, Firebender, Gemini, Goose, Kilocode, and Roo. - -## Table of Contents - -- [Features](#features) -- [Installation](#installation) -- [Quick Start](#quick-start) -- [Configuration](#configuration) -- [Commands](#commands) - - [`ai-rules init`](#ai-rules-init) - - [`ai-rules generate [--agents ] [--gitignore] [--nested-depth ]`](#ai-rules-generate---agents-agent1agent2--gitignore---nested-depth-depth) - - [`ai-rules status [--agents ] [--nested-depth ]`](#ai-rules-status---agents-agent1agent2---nested-depth-depth) - - [`ai-rules clean [--nested-depth ]`](#ai-rules-clean---nested-depth-depth) - - [`ai-rules list-agents`](#ai-rules-list-agents) -- [Source Rule File Format (.md)](#source-rule-file-format-md) - - [Standard Mode Format](#standard-mode-format) - - [Symlink Mode Format](#symlink-mode-format) -- [MCP Configuration](#mcp-configuration) -- [Supported AI Coding Agents](#supported-ai-coding-agents) - - [Firebender Overlay Support](#firebender-overlay-support) - - [Custom Commands Support](#custom-commands-support) - - [Claude Code Skills Support](#claude-code-skills-support) - - [User-Defined Skills](#user-defined-skills) -- [Project Structure](#project-structure) - - [Standard Mode](#standard-mode) - - [Symlink Mode](#symlink-mode) -- [Development](#development) +CLI tool to manage AI rules across different AI coding agents. Standardize and distribute your coding guidelines across AMP, Claude, Cline, Codex, Copilot, Cursor, Firebender, Gemini, Goose, Kilocode, and Roo. ## Features -- ๐Ÿค– **Multi-Agent Support** - Generate rules for AI coding agents including AMP, Claude, Cline, Codex, Copilot, Cursor, Firebender, Gemini, Goose, Kilocode, and Roo -- ๐Ÿ”„ **Sync Management** - Track and maintain consistency across all generated rule files -- ๐Ÿงน **Easy Cleanup** - Remove generated files when needed -- ๐ŸŽฏ **Selective Generation** - Generate rules for specific agents only +- **Multi-Agent Support** - Generate rules for 11 AI coding agents from a single source +- **Sync Management** - Track and maintain consistency across all generated rule files +- **Selective Generation** - Generate rules for specific agents only +- **MCP Support** - Generate Model Context Protocol configurations for compatible agents ## Installation -### Quick Install (Recommended) - ```bash curl -fsSL https://raw.githubusercontent.com/block/ai-rules/main/scripts/install.sh | bash ``` Installs to `~/.local/bin/ai-rules`. Verify with `ai-rules --version`. -### Install Specific Version +
+More installation options +**Specific version:** ```bash curl -fsSL https://raw.githubusercontent.com/block/ai-rules/main/scripts/install.sh | VERSION=v1.0.0 bash ``` -### Custom Install Directory - +**Custom directory:** ```bash curl -fsSL https://raw.githubusercontent.com/block/ai-rules/main/scripts/install.sh | INSTALL_DIR=/usr/local/bin bash ``` +
## Quick Start -1. **Set up your AI rules directory** +1. **Initialize** your AI rules directory: ```bash ai-rules init ``` - This creates an `ai-rules/` directory with an example rule file. The command uses a built-in [Goose recipe](https://block.github.io/goose/docs/guides/recipes/) to generate a context-aware rule file automatically. If Goose is not available, it falls back to creating a basic example template. + Creates an `ai-rules/` directory with an example rule file. -2. **Add/Edit your rules** in `ai-rules/example.md` or create your own rule files +2. **Add your rules** in `ai-rules/*.md` files -3. **Configure for rule generation**(Optional) in `ai-rules/ai-rules-config.yaml` (see [Configuration](#configuration)) - -4. **Generate** rules +3. **Generate** agent-specific files: ```bash ai-rules generate ``` - This creates agent-specific files like `CLAUDE.md`, `.cursor/rules/*.mdc`, `.clinerules/*.md`, `AGENTS.md`, `firebender.json`, etc. + Creates `CLAUDE.md`, `.cursor/rules/*.mdc`, `AGENTS.md`, etc. -5. **Check status** to ensure everything is in sync: +4. **Check status** to ensure everything is in sync: ```bash ai-rules status ``` -## Configuration - -You can set default values for commonly used options in a configuration file. This is especially useful in team environments or when you have consistent preferences across projects. - -### Configuration File - -Create `ai-rules/ai-rules-config.yaml` in the `ai-rules` directory. Example: - -```yaml -agents: [claude, cursor, cline] # Generate rules only for these agents -command_agents: [claude, amp] # Generate commands for these agents (defaults to agents list if not specified) -nested_depth: 2 # Search 2 levels deep for ai-rules/ folders -gitignore: true # Ignore the generated rules in git -``` - -### Configuration Precedence - -Options are resolved in the following order (highest to lowest priority): - -1. **CLI options** - `--agents`, `--nested-depth`, `--no-gitignore` -2. **Config file** - `ai-rules/ai-rules-config.yaml` (at current working directory) -3. **Default values** - All agents, depth 0, generated files are NOT git ignored - -### Experimental Options - -**Claude Code Skills Mode (Testing)** - -```yaml -use_claude_skills: true # Default: false -``` - -Experimental toggle to test Claude Code's skills feature. When enabled, rules with `alwaysApply: false` are generated as separate skills in `.claude/skills/` instead of being included in `CLAUDE.md`. This allows Claude Code to selectively apply optional rules based on context. - ## Commands -### `ai-rules init` -Initialize AI rules in the current directory. Uses Goose recipes to generate context-aware rule files: -- **Custom recipe** (`ai-rules/custom-init/recipe.yaml` at git root): Run your own initialization workflow with custom parameters -- **Built-in recipe** ([Recipe](src/templates/init_default_recipe.yaml)): Generate a single rule file based on your project context -- **Fallback**: Creates a basic example template if Goose is not available +| Command | Description | +|---------|-------------| +| `ai-rules init` | Initialize AI rules in the current directory | +| `ai-rules generate` | Generate rules for AI coding agents | +| `ai-rules status` | Show sync status of AI rules | +| `ai-rules clean` | Remove all generated files | +| `ai-rules list-agents` | List all supported agents | -**Options:** -- `--params ` - Pass custom parameters to recipes (can be specified multiple times) -- `--force` - Skip confirmation prompts and assume yes. Automatically bypasses the "Run Goose to initialize another rule file?" prompt when rules already exist. For custom recipes, passes `force=true` as a parameter. +### Common Options -**Examples:** ```bash -# Basic initialization -ai-rules init - -# Pass parameters to custom recipes (e.g., service name, team ownership) -ai-rules init --params service=payments --params owner=checkout - -# Force initialization without confirmation prompts -ai-rules init --force +ai-rules generate --agents claude,cursor # Generate for specific agents +ai-rules generate --nested-depth 2 # Process subdirectories +ai-rules generate --gitignore # Add generated files to .gitignore ``` -### `ai-rules generate [--agents ] [--gitignore] [--nested-depth ]` -Generate rules for AI coding agents from your `ai-rules/*.md` source files. - -**Options:** -- `--agents` - Comma-separated list of specific agents (e.g., `--agents claude,cursor`). Can be set in config. -- `--gitignore` - Add generated file patterns to .gitignore. Can be set in config. -- `--no-gitignore` - (Deprecated: use `--gitignore` instead) Skip updating .gitignore with generated file patterns. -- `--nested-depth` - Maximum directory depth to scan for `ai-rules/` folders (default: 0). Can be set in config. - - `0` - Only process current directory - - `1` - Process current directory and immediate subdirectories - - `2` - Process up to 2 levels deep, etc. - -See [Configuration](#configuration) section for setting defaults. - -**Generates:** - -**Standard Mode** (when `ai-rules/*.md` files have YAML frontmatter): -- Rules files for AI coding agents (see [Supported AI Coding Agents](#supported-ai-coding-agents)) -- `ai-rules/.generated-ai-rules/` - Directory with extracted rule content files, referenced by coding agent rule files -- Skill symlinks from `ai-rules/skills/` to agent skill directories -- Updates `.gitignore` with generated files (only if `--gitignore` is specified) - -**Symlink Mode** (when only `AGENTS.md` exists in `ai-rules/` without frontmatter): -- Symlinks pointing directly to `ai-rules/AGENTS.md` for supported agents -- Skill symlinks from `ai-rules/skills/` to agent skill directories -- No `ai-rules/.generated-ai-rules/` directory created -- Updates `.gitignore` with symlink files (only if `--gitignore` is specified) - -**Examples:** -```bash -ai-rules generate -ai-rules generate --agents claude,cursor -ai-rules generate --nested-depth 2 -ai-rules generate --agents claude,cursor --nested-depth 1 -``` - -### `ai-rules status [--agents ] [--nested-depth ]` -Show the current sync status of AI rules - -**Options:** -- `--agents` - Comma-separated list of specific agents to check (e.g., `--agents claude,cursor`). Can be set in config. -- `--nested-depth` - Maximum directory depth to check for rules in `ai-rules/` folders (default: 0). Can be set in config. - -See [Configuration](#configuration) section for setting defaults. - -**Examples:** -```bash -ai-rules status -ai-rules status --nested-depth 1 - -# Output: -# โœ… Claude: In sync -# โŒ Cursor: Out of sync -# โœ… Goose: In sync -``` - -**Exit Codes:** Returns `0` if in sync, `1` if out of sync, or `2` if no rules found. Use this in build scripts to ensure generated rules stay in sync. - -### `ai-rules clean [--nested-depth ]` -Remove all generated AI rule files while preserving source files in `ai-rules/`. - -**Options:** -- `--nested-depth` - Maximum directory depth to clean generated files (default: 0). Can be set in config. - -See [Configuration](#configuration) section for setting defaults. - -**Examples:** -```bash -ai-rules clean -ai-rules clean --nested-depth 2 -``` - -### `ai-rules list-agents` -List all supported AI coding agents that rules can be generated for. - -**Example:** -```bash -ai-rules list-agents - -# Output: -# Supported agents: -# โ€ข amp -# โ€ข claude -# โ€ข cline -# โ€ข codex -# .... -``` - - -## Source Rule File Format (.md) - -### Standard Mode Format - -Rule files use a markdown format with optional YAML frontmatter: -```markdown ---- -description: Context description for when to apply this rule -alwaysApply: true/false -fileMatching: "**/*.ext" ---- - -# Rule Content - -Your markdown content here... -``` - -**Frontmatter Fields (all optional):** -- `description` - Context description that helps agents understand when to apply this rule if `alwaysApply` is `false`. -- `alwaysApply` - Controls when this rule is applied: - - `true` - Referenced directly in coding agent rule files - - `false` - Included in the coding agent rule files as optional rules based on context - - Default: `true` (if not specified) -- `fileMatching` - Glob patterns for which files this rule applies to (e.g., `"**/*.ts"`, `"src/**/*.py"`). Currently supported in Cursor. - -**Note:** If frontmatter is omitted entirely, the file is treated as a regular markdown rule with default settings (`alwaysApply: true`). - -## MCP Configuration - -The AI Rules Tool supports generating Model Context Protocol (MCP) configurations for compatible AI coding agents. MCP enables AI agents to connect to external tools and services. - -### Setup - -Create `ai-rules/mcp.json` with your MCP server configurations: - -```json -{ - "mcpServers": { - "server-name": { - "command": "executable-command", - "args": ["arg1", "arg2"], - "env": { - "ENV_VAR": "${use_environment_variable}" - } - }, - "remote-server-name": { - "type": "http", - "url": "https://api.example.com/mcp" - } - } -} -``` - -Run `ai-rules generate` to automatically create agent-specific MCP configurations. See the [Supported AI Coding Agents](#supported-ai-coding-agents) table for which agents support MCP and their generated file locations. - -### Symlink Mode Format - -For symlink mode, use a single `AGENTS.md` file with pure markdown (no YAML frontmatter): - -```markdown -# Project Rules - -- Use TypeScript for all new code -- Write comprehensive tests -- Follow conventional commits -- Prefer explicit types over `any` -``` - -**Requirements:** -- Must be named `AGENTS.md` -- Must be the only file in the `ai-rules/` directory -- Must not start with `---` (no YAML frontmatter) -- Content is used directly by all supported agents via symlinks - -## Supported AI Coding Agents - -| AI Coding Agent | Standard Mode | Symlink Mode | MCP Support | Notes | -|------|-------------|-------------|-------------|-------| -| **AMP** | `AGENTS.md` | โœ… `AGENTS.md` โ†’ `ai-rules/AGENTS.md` | โŒ | | -| **Claude Code** | `CLAUDE.md` (+ `.claude/skills/` if configured) | โœ… `CLAUDE.md` โ†’ `ai-rules/AGENTS.md` | โœ… `.mcp.json` | Skills support via `use_claude_skills` config | -| **Cline** | `.clinerules/*.md` | โœ… `.clinerules/AGENTS.md` โ†’ `../ai-rules/AGENTS.md` | โŒ | | -| **Codex** | `AGENTS.md` | โœ… `AGENTS.md` โ†’ `ai-rules/AGENTS.md` | โŒ | | -| **Copilot** | `AGENTS.md` | โœ… `AGENTS.md` โ†’ `ai-rules/AGENTS.md` | โŒ | | -| **Cursor** | `.cursor/rules/*.mdc` | โœ… `AGENTS.md` โ†’ `ai-rules/AGENTS.md` | โœ… `.cursor/mcp.json` | Symlink mode: only project root level | -| **Firebender** | `firebender.json` | โœ… `firebender.json` (references `ai-rules/AGENTS.md`) | โœ… Embedded in `firebender.json` | Supports overlay files | -| **Gemini** | `GEMINI.md` | โœ… `GEMINI.md` โ†’ `ai-rules/AGENTS.md` | โœ… Embedded in `.gemini/settings.json` | | -| **Goose** | `AGENTS.md` | โœ… `AGENTS.md` โ†’ `ai-rules/AGENTS.md` | โŒ | | -| **Kilocode** | `.kilocode/rules/*.md` | โœ… `.kilocode/rules/AGENTS.md` โ†’ `../../ai-rules/AGENTS.md` | โŒ | | -| **Roo** | `.roo/rules/*.md` | โœ… `.roo/rules/AGENTS.md` โ†’ `../../ai-rules/AGENTS.md` | โœ… `.roo/mcp.json` | | - -### Firebender Overlay Support - -Firebender supports overlay configuration files. To customize your configuration, create a `firebender-overlay.json` file inside the `ai-rules/` directory, located in the same parent directory as your generated `firebender.json` file. Any values defined in the overlay file will be merged into the base configuration, with overlay values taking precedence. - -**MCP Integration:** If you have `ai-rules/mcp.json`, the MCP servers are merged into `firebender.json` first, then the overlay is applied. This allows you to override MCP configurations in the overlay if needed. - -### Custom Commands Support - -Custom commands (also called "slash commands") allow you to define reusable prompts that can be invoked by name in supported AI agents. Commands are defined as markdown files in `ai-rules/commands/` and are generated to agent-specific locations. - -**Frontmatter Fields:** - -Command files support optional YAML frontmatter. The following fields are currently supported: - -- `allowed-tools` - Tool restrictions for the command (Claude-specific) -- `description` - Human-readable description of what the command does -- `model` - Specific model to use for this command (Claude-specific) - -**Agent Behavior:** - -| Agent | Output Location | Frontmatter Handling | -|-------|----------------|---------------------| -| **AMP** | `.agents/commands/{name}-ai-rules.md` | โŒ Stripped - AMP doesn't use YAML frontmatter | -| **Claude Code** | `.claude/commands/ai-rules/*.md` | โœ… Preserved - Claude uses frontmatter for tool restrictions and model selection | -| **Cursor** | `.cursor/commands/ai-rules/*.md` | โŒ Stripped - Cursor doesn't use YAML frontmatter | -| **Firebender** | `firebender.json` (commands array) | โŒ Stripped - Command paths embedded in JSON config | - -**Documentation:** -- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands) -- [Cursor Commands](https://cursor.com/docs/agent/chat/commands) -- [Firebender Commands](https://docs.firebender.com/context/commands) - -### Claude Code Skills Support - -Claude Code supports optional rules through [skills](https://docs.claude.com/en/docs/claude-code/skills) (requires `use_claude_skills: true` in config). When enabled and a source rule has `alwaysApply: false`, the tool generates: -- **CLAUDE.md** - References required rules (`alwaysApply: true`) only -- **.claude/skills/{rule-name}/SKILL.md** - Individual skill files for optional rules - -This allows Claude to selectively apply rules based on file context and user preferences. See [Experimental Options](#experimental-options) for configuration. - -**Example:** -```markdown ---- -description: React Testing Library best practices -alwaysApply: false ---- -# Testing Rules -- Prefer user-centric queries (getByRole, getByLabelText) -- Avoid implementation details (testId, class names) -- Test behavior, not implementation -``` - -**Generates:** -- `CLAUDE.md` - Contains only required rules -- `.claude/skills/testing/SKILL.md` - Skill that Claude can invoke when working with test files - -**Note:** Skills use the `description` field as the skill name for better discoverability. The directory name uses the source file's base filename. - -### User-Defined Skills - -You can define custom skill folders that are symlinked to supported agents' skill directories during generation. This allows you to create reusable skills that contain multiple files or complex structures. - -**Setup:** - -Create skill folders in `ai-rules/skills//` with a `SKILL.md` file: - -``` -ai-rules/ -โ”œโ”€โ”€ skills/ -โ”‚ โ””โ”€โ”€ debugging/ -โ”‚ โ””โ”€โ”€ SKILL.md # Required - defines the skill -``` - -**SKILL.md Format:** -```markdown ---- -name: debugging -description: Debugging guidelines and best practices ---- +## Configuration -# Debugging Guidelines +Create `ai-rules/ai-rules-config.yaml` to set defaults: -Your skill content here... +```yaml +agents: [claude, cursor, cline] +nested_depth: 2 +gitignore: true ``` -When you run `ai-rules generate`, symlinks are created in the agent's skills directory: -- `.agents/skills/ai-rules-generated-debugging` โ†’ `../../ai-rules/skills/debugging` (AMP) -- `.claude/skills/ai-rules-generated-debugging` โ†’ `../../ai-rules/skills/debugging` (Claude) -- `.codex/skills/ai-rules-generated-debugging` โ†’ `../../ai-rules/skills/debugging` (Codex) -- `.cursor/skills/ai-rules-generated-debugging` โ†’ `../../ai-rules/skills/debugging` (Cursor) +See [Configuration Guide](docs/configuration.md) for all options. -**Supported Agents:** AMP, Claude Code, Codex, Cursor +## Supported Agents -**Note:** Skill folders without a `SKILL.md` file are skipped with a warning. +AMP, Claude Code, Cline, Codex, Copilot, Cursor, Firebender, Gemini, Goose, Kilocode, Roo -## Project Structure +See [Supported Agents](docs/agents.md) for detailed compatibility information. -### Standard Mode +## Documentation -``` -monorepo/ -โ”œโ”€โ”€ ai-rules/ # Global rule files -โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ # Root processed files -โ”‚ โ”œโ”€โ”€ commands/ # Custom commands (slash commands) -โ”‚ โ”‚ โ””โ”€โ”€ commit.md # Example command -โ”‚ โ”œโ”€โ”€ skills/ # User-defined skills (symlinked to agents) -โ”‚ โ”‚ โ””โ”€โ”€ debugging/ # Example skill folder -โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Skill definition -โ”‚ โ”œโ”€โ”€ general.md # Repository-wide rules -โ”‚ โ””โ”€โ”€ mcp.json # MCP server configuration -โ”œโ”€โ”€ frontend/ # Frontend application -โ”‚ โ”œโ”€โ”€ ai-rules/ # Frontend-specific rules -โ”‚ โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ # Frontend processed files -โ”‚ โ”‚ โ”œโ”€โ”€ react.md # React component rules -โ”‚ โ”‚ โ””โ”€โ”€ styling.md # CSS/styling rules -โ”‚ โ”œโ”€โ”€ CLAUDE.md # Frontend Claude rules -โ”‚ โ”œโ”€โ”€ .agents/commands/ # Frontend AMP commands ({name}-ai-rules.md) -โ”‚ โ”œโ”€โ”€ .claude/skills/ # Frontend Claude skills (requires use_claude_skills: true) -โ”‚ โ”œโ”€โ”€ .claude/commands/ai-rules/ # Frontend Claude commands (*.md) -โ”‚ โ”œโ”€โ”€ .clinerules/ # Frontend Cline rules (*.md files) -โ”‚ โ”œโ”€โ”€ .cursor/rules/ # Frontend Cursor rules (*.mdc files) -โ”‚ โ”œโ”€โ”€ .cursor/commands/ai-rules/ # Frontend Cursor commands (*.md) -โ”‚ โ”œโ”€โ”€ GEMINI.md # Frontend Gemini rules -โ”‚ โ”œโ”€โ”€ AGENTS.md # Frontend Goose/AMP/Codex/Copilot rules -โ”‚ โ”œโ”€โ”€ .kilocode/rules/ # Frontend Kilocode rules (*.md files) -โ”‚ โ”œโ”€โ”€ .roo/rules/ # Frontend Roo rules (*.md files) -โ”‚ โ””โ”€โ”€ src/ -โ”œโ”€โ”€ backend/ # Backend services -โ”‚ โ”œโ”€โ”€ ai-rules/ # Backend-specific rules -โ”‚ โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ # Backend processed files -โ”‚ โ”‚ โ”œโ”€โ”€ api.md # API development rules -โ”‚ โ”‚ โ””โ”€โ”€ database.md # Database schema rules -โ”‚ โ”œโ”€โ”€ CLAUDE.md # Backend Claude rules -โ”‚ โ”œโ”€โ”€ .agents/commands/ # Backend AMP commands ({name}-ai-rules.md) -โ”‚ โ”œโ”€โ”€ .claude/skills/ # Backend Claude skills (requires use_claude_skills: true) -โ”‚ โ”œโ”€โ”€ .claude/commands/ai-rules/ # Backend Claude commands (*.md) -โ”‚ โ”œโ”€โ”€ .clinerules/ # Backend Cline rules (*.md files) -โ”‚ โ”œโ”€โ”€ .cursor/rules/ # Backend Cursor rules (*.mdc files) -โ”‚ โ”œโ”€โ”€ .cursor/commands/ai-rules/ # Backend Cursor commands (*.md) -โ”‚ โ”œโ”€โ”€ GEMINI.md # Backend Gemini rules -โ”‚ โ”œโ”€โ”€ AGENTS.md # Backend Goose/AMP/Codex/Copilot rules -โ”‚ โ”œโ”€โ”€ .kilocode/rules/ # Backend Kilocode rules (*.md files) -โ”‚ โ”œโ”€โ”€ .roo/rules/ # Backend Roo rules (*.md files) -โ”‚ โ””โ”€โ”€ api/ -โ”œโ”€โ”€ CLAUDE.md # Root Claude rules -โ”œโ”€โ”€ .agents/commands/ # Root AMP commands ({name}-ai-rules.md) -โ”œโ”€โ”€ .claude/skills/ # Root Claude skills (requires use_claude_skills: true) -โ”œโ”€โ”€ .claude/commands/ai-rules/ # Root Claude commands (*.md) -โ”œโ”€โ”€ .clinerules/ # Root Cline rules (*.md files) -โ”œโ”€โ”€ .cursor/rules/ # Root Cursor rules (*.mdc files) -โ”œโ”€โ”€ .cursor/commands/ai-rules/ # Root Cursor commands (*.md) -โ”œโ”€โ”€ .cursor/mcp.json # Root Cursor MCP config -โ”œโ”€โ”€ firebender.json # Root Firebender rules + MCP -โ”œโ”€โ”€ firebender-overlay.json # Root Firebender overlay -โ”œโ”€โ”€ GEMINI.md # Root Gemini rules -โ”œโ”€โ”€ AGENTS.md # Root Goose/AMP/Codex/Copilot rules -โ”œโ”€โ”€ .kilocode/rules/ # Root Kilocode rules (*.md files) -โ”œโ”€โ”€ .roo/rules/ # Root Roo rules (*.md files) -โ”œโ”€โ”€ .roo/mcp.json # Root Roo MCP config -โ””โ”€โ”€ .mcp.json # Root Claude Code MCP config -``` - -### Symlink Mode - -``` -project/ -โ”œโ”€โ”€ ai-rules/ -โ”‚ โ”œโ”€โ”€ AGENTS.md # Source file -โ”‚ โ”œโ”€โ”€ commands/ # Custom commands (optional) -โ”‚ โ”‚ โ””โ”€โ”€ commit.md # Example command -โ”‚ โ”œโ”€โ”€ skills/ # User-defined skills (optional) -โ”‚ โ”‚ โ””โ”€โ”€ debugging/ # Example skill folder -โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md # Skill definition -โ”‚ โ””โ”€โ”€ mcp.json # MCP config (optional) -โ”œโ”€โ”€ CLAUDE.md # Symlink โ†’ ai-rules/AGENTS.md -โ”œโ”€โ”€ GEMINI.md # Symlink โ†’ ai-rules/AGENTS.md -โ”œโ”€โ”€ AGENTS.md # Symlink โ†’ ai-rules/AGENTS.md -โ”œโ”€โ”€ firebender.json # References ai-rules/AGENTS.md + commands -โ”œโ”€โ”€ .agents/ -โ”‚ โ””โ”€โ”€ commands/ # AMP commands ({name}-ai-rules.md) -โ”œโ”€โ”€ .claude/ -โ”‚ โ””โ”€โ”€ commands/ai-rules/ # Claude commands (*.md) -โ”œโ”€โ”€ .clinerules/ -โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink โ†’ ../ai-rules/AGENTS.md -โ”œโ”€โ”€ .cursor/ -โ”‚ โ”œโ”€โ”€ commands/ai-rules/ # Cursor commands (*.md) -โ”‚ โ””โ”€โ”€ mcp.json # Cursor MCP config (if mcp.json exists) -โ”œโ”€โ”€ .kilocode/rules/ -โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink โ†’ ../../ai-rules/AGENTS.md -โ”œโ”€โ”€ .roo/ -โ”‚ โ”œโ”€โ”€ rules/ -โ”‚ โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink โ†’ ../../ai-rules/AGENTS.md -โ”‚ โ””โ”€โ”€ mcp.json # Roo MCP config (if mcp.json exists) -โ””โ”€โ”€ .mcp.json # Claude Code MCP config (if mcp.json exists) -``` +- [Configuration](docs/configuration.md) - Config file options and precedence +- [Rule Format](docs/rule-format.md) - Standard mode and symlink mode formats +- [Supported Agents](docs/agents.md) - Agent compatibility and generated files +- [MCP Configuration](docs/mcp.md) - Model Context Protocol setup +- [Commands and Skills](docs/commands-and-skills.md) - Custom commands and skills +- [Project Structure](docs/project-structure.md) - Example project layouts ## Development diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..5e8c4a4 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,26 @@ +# Supported AI Coding Agents + +## Agent Compatibility Table + +| Agent | Standard Mode | Symlink Mode | MCP Support | Notes | +|-------|---------------|--------------|-------------|-------| +| **AMP** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | | +| **Claude Code** | `CLAUDE.md` (+ `.claude/skills/` if configured) | `CLAUDE.md` -> `ai-rules/AGENTS.md` | `.mcp.json` | Skills support via `use_claude_skills` config | +| **Cline** | `.clinerules/*.md` | `.clinerules/AGENTS.md` -> `../ai-rules/AGENTS.md` | - | | +| **Codex** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | | +| **Copilot** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | | +| **Cursor** | `.cursor/rules/*.mdc` | `AGENTS.md` -> `ai-rules/AGENTS.md` | `.cursor/mcp.json` | Symlink mode: only project root level | +| **Firebender** | `firebender.json` | `firebender.json` (references `ai-rules/AGENTS.md`) | Embedded in `firebender.json` | Supports overlay files | +| **Gemini** | `GEMINI.md` | `GEMINI.md` -> `ai-rules/AGENTS.md` | Embedded in `.gemini/settings.json` | | +| **Goose** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | | +| **Kilocode** | `.kilocode/rules/*.md` | `.kilocode/rules/AGENTS.md` -> `../../ai-rules/AGENTS.md` | - | | +| **Roo** | `.roo/rules/*.md` | `.roo/rules/AGENTS.md` -> `../../ai-rules/AGENTS.md` | `.roo/mcp.json` | | + +## Firebender Overlay Support + +Firebender supports overlay configuration files. To customize your configuration: + +1. Create `ai-rules/firebender-overlay.json` in the same parent directory as your generated `firebender.json` +2. Any values defined in the overlay file will be merged into the base configuration, with overlay values taking precedence + +**MCP Integration:** If you have `ai-rules/mcp.json`, the MCP servers are merged into `firebender.json` first, then the overlay is applied. This allows you to override MCP configurations in the overlay if needed. diff --git a/docs/commands-and-skills.md b/docs/commands-and-skills.md new file mode 100644 index 0000000..89683e8 --- /dev/null +++ b/docs/commands-and-skills.md @@ -0,0 +1,114 @@ +# Commands and Skills + +## Custom Commands + +Custom commands (also called "slash commands") allow you to define reusable prompts that can be invoked by name in supported AI agents. + +### Setup + +Create markdown files in `ai-rules/commands/`: + +``` +ai-rules/ +โ””โ”€โ”€ commands/ + โ””โ”€โ”€ commit.md +``` + +### Frontmatter Fields + +Command files support optional YAML frontmatter: + +| Field | Description | Agent Support | +|-------|-------------|---------------| +| `allowed-tools` | Tool restrictions for the command | Claude only | +| `description` | Human-readable description of what the command does | All | +| `model` | Specific model to use for this command | Claude only | + +### Agent Behavior + +| Agent | Output Location | Frontmatter | +|-------|-----------------|-------------| +| **AMP** | `.agents/commands/{name}-ai-rules.md` | Stripped | +| **Claude Code** | `.claude/commands/ai-rules/*.md` | Preserved | +| **Cursor** | `.cursor/commands/ai-rules/*.md` | Stripped | +| **Firebender** | `firebender.json` (commands array) | Stripped | + +### Documentation + +- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands) +- [Cursor Commands](https://cursor.com/docs/agent/chat/commands) +- [Firebender Commands](https://docs.firebender.com/context/commands) + +--- + +## Claude Code Skills + +Claude Code supports optional rules through [skills](https://docs.claude.com/en/docs/claude-code/skills). This requires `use_claude_skills: true` in your config. + +When enabled and a source rule has `alwaysApply: false`, the tool generates: +- **CLAUDE.md** - References required rules (`alwaysApply: true`) only +- **.claude/skills/{rule-name}/SKILL.md** - Individual skill files for optional rules + +### Example + +Source file `ai-rules/testing.md`: + +```markdown +--- +description: React Testing Library best practices +alwaysApply: false +--- +# Testing Rules +- Prefer user-centric queries (getByRole, getByLabelText) +- Avoid implementation details (testId, class names) +- Test behavior, not implementation +``` + +Generates: +- `CLAUDE.md` - Contains only required rules +- `.claude/skills/testing/SKILL.md` - Skill that Claude can invoke when working with test files + +Skills use the `description` field as the skill name for better discoverability. + +--- + +## User-Defined Skills + +You can define custom skill folders that are symlinked to supported agents' skill directories during generation. + +### Setup + +Create skill folders in `ai-rules/skills//` with a `SKILL.md` file: + +``` +ai-rules/ +โ””โ”€โ”€ skills/ + โ””โ”€โ”€ debugging/ + โ””โ”€โ”€ SKILL.md +``` + +### SKILL.md Format + +```markdown +--- +name: debugging +description: Debugging guidelines and best practices +--- + +# Debugging Guidelines + +Your skill content here... +``` + +### Generated Symlinks + +When you run `ai-rules generate`, symlinks are created: + +| Agent | Symlink Location | +|-------|------------------| +| AMP | `.agents/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` | +| Claude | `.claude/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` | +| Codex | `.codex/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` | +| Cursor | `.cursor/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` | + +Skill folders without a `SKILL.md` file are skipped with a warning. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..2448423 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,34 @@ +# Configuration + +You can set default values for commonly used options in a configuration file. This is especially useful in team environments or when you have consistent preferences across projects. + +## Configuration File + +Create `ai-rules/ai-rules-config.yaml` in the `ai-rules` directory: + +```yaml +agents: [claude, cursor, cline] # Generate rules only for these agents +command_agents: [claude, amp] # Generate commands for these agents (defaults to agents list if not specified) +nested_depth: 2 # Search 2 levels deep for ai-rules/ folders +gitignore: true # Ignore the generated rules in git +``` + +## Configuration Precedence + +Options are resolved in the following order (highest to lowest priority): + +1. **CLI options** - `--agents`, `--nested-depth`, `--no-gitignore` +2. **Config file** - `ai-rules/ai-rules-config.yaml` (at current working directory) +3. **Default values** - All agents, depth 0, generated files are NOT git ignored + +## Experimental Options + +### Claude Code Skills Mode + +```yaml +use_claude_skills: true # Default: false +``` + +Experimental toggle to test Claude Code's skills feature. When enabled, rules with `alwaysApply: false` are generated as separate skills in `.claude/skills/` instead of being included in `CLAUDE.md`. This allows Claude Code to selectively apply optional rules based on context. + +See [Commands and Skills](commands-and-skills.md) for more details on skills. diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 0000000..8f2c6a8 --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,41 @@ +# MCP Configuration + +The AI Rules Tool supports generating Model Context Protocol (MCP) configurations for compatible AI coding agents. MCP enables AI agents to connect to external tools and services. + +## Setup + +Create `ai-rules/mcp.json` with your MCP server configurations: + +```json +{ + "mcpServers": { + "server-name": { + "command": "executable-command", + "args": ["arg1", "arg2"], + "env": { + "ENV_VAR": "${use_environment_variable}" + } + }, + "remote-server-name": { + "type": "http", + "url": "https://api.example.com/mcp" + } + } +} +``` + +## Generation + +Run `ai-rules generate` to automatically create agent-specific MCP configurations. + +## Supported Agents + +See the [Supported Agents](agents.md) table for which agents support MCP and their generated file locations: + +| Agent | MCP File Location | +|-------|-------------------| +| Claude Code | `.mcp.json` | +| Cursor | `.cursor/mcp.json` | +| Firebender | Embedded in `firebender.json` | +| Gemini | Embedded in `.gemini/settings.json` | +| Roo | `.roo/mcp.json` | diff --git a/docs/project-structure.md b/docs/project-structure.md new file mode 100644 index 0000000..4ba225a --- /dev/null +++ b/docs/project-structure.md @@ -0,0 +1,78 @@ +# Project Structure Examples + +## Standard Mode + +For projects using YAML frontmatter in rule files: + +``` +monorepo/ +โ”œโ”€โ”€ ai-rules/ # Global rule files +โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ # Processed files (generated) +โ”‚ โ”œโ”€โ”€ commands/ # Custom commands +โ”‚ โ”‚ โ””โ”€โ”€ commit.md +โ”‚ โ”œโ”€โ”€ skills/ # User-defined skills +โ”‚ โ”‚ โ””โ”€โ”€ debugging/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md +โ”‚ โ”œโ”€โ”€ general.md # Repository-wide rules +โ”‚ โ”œโ”€โ”€ ai-rules-config.yaml # Configuration +โ”‚ โ””โ”€โ”€ mcp.json # MCP server configuration +โ”‚ +โ”œโ”€โ”€ frontend/ # Frontend application +โ”‚ โ”œโ”€โ”€ ai-rules/ # Frontend-specific rules +โ”‚ โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ +โ”‚ โ”‚ โ”œโ”€โ”€ react.md +โ”‚ โ”‚ โ””โ”€โ”€ styling.md +โ”‚ โ”œโ”€โ”€ CLAUDE.md # Generated +โ”‚ โ”œโ”€โ”€ AGENTS.md # Generated +โ”‚ โ”œโ”€โ”€ .cursor/rules/ # Generated (*.mdc) +โ”‚ โ””โ”€โ”€ src/ +โ”‚ +โ”œโ”€โ”€ backend/ # Backend services +โ”‚ โ”œโ”€โ”€ ai-rules/ +โ”‚ โ”‚ โ”œโ”€โ”€ .generated-ai-rules/ +โ”‚ โ”‚ โ”œโ”€โ”€ api.md +โ”‚ โ”‚ โ””โ”€โ”€ database.md +โ”‚ โ”œโ”€โ”€ CLAUDE.md +โ”‚ โ”œโ”€โ”€ AGENTS.md +โ”‚ โ””โ”€โ”€ api/ +โ”‚ +โ”œโ”€โ”€ CLAUDE.md # Root rules (generated) +โ”œโ”€โ”€ AGENTS.md # Root rules (generated) +โ”œโ”€โ”€ .cursor/rules/ # Root Cursor rules (generated) +โ”œโ”€โ”€ .clinerules/ # Root Cline rules (generated) +โ”œโ”€โ”€ .mcp.json # Root MCP config (generated) +โ””โ”€โ”€ firebender.json # Root Firebender config (generated) +``` + +## Symlink Mode + +For simple projects with a single `AGENTS.md` file: + +``` +project/ +โ”œโ”€โ”€ ai-rules/ +โ”‚ โ”œโ”€โ”€ AGENTS.md # Source file (your rules) +โ”‚ โ”œโ”€โ”€ commands/ # Custom commands (optional) +โ”‚ โ”‚ โ””โ”€โ”€ commit.md +โ”‚ โ”œโ”€โ”€ skills/ # User-defined skills (optional) +โ”‚ โ”‚ โ””โ”€โ”€ debugging/ +โ”‚ โ”‚ โ””โ”€โ”€ SKILL.md +โ”‚ โ””โ”€โ”€ mcp.json # MCP config (optional) +โ”‚ +โ”œโ”€โ”€ CLAUDE.md # Symlink -> ai-rules/AGENTS.md +โ”œโ”€โ”€ GEMINI.md # Symlink -> ai-rules/AGENTS.md +โ”œโ”€โ”€ AGENTS.md # Symlink -> ai-rules/AGENTS.md +โ”œโ”€โ”€ firebender.json # References ai-rules/AGENTS.md +โ”œโ”€โ”€ .clinerules/ +โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink -> ../ai-rules/AGENTS.md +โ”œโ”€โ”€ .cursor/ +โ”‚ โ”œโ”€โ”€ commands/ai-rules/ # Commands (generated) +โ”‚ โ””โ”€โ”€ mcp.json # MCP config (if mcp.json exists) +โ”œโ”€โ”€ .kilocode/rules/ +โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink -> ../../ai-rules/AGENTS.md +โ”œโ”€โ”€ .roo/ +โ”‚ โ”œโ”€โ”€ rules/ +โ”‚ โ”‚ โ””โ”€โ”€ AGENTS.md # Symlink -> ../../ai-rules/AGENTS.md +โ”‚ โ””โ”€โ”€ mcp.json # MCP config (if mcp.json exists) +โ””โ”€โ”€ .mcp.json # Claude MCP config (if mcp.json exists) +``` diff --git a/docs/rule-format.md b/docs/rule-format.md new file mode 100644 index 0000000..dc7ac10 --- /dev/null +++ b/docs/rule-format.md @@ -0,0 +1,60 @@ +# Source Rule File Format + +Rule files are markdown files (`.md`) stored in your `ai-rules/` directory. There are two modes of operation: Standard Mode and Symlink Mode. + +## Standard Mode + +Use Standard Mode when you want fine-grained control over rules with YAML frontmatter. + +### Format + +```markdown +--- +description: Context description for when to apply this rule +alwaysApply: true/false +fileMatching: "**/*.ext" +--- + +# Rule Content + +Your markdown content here... +``` + +### Frontmatter Fields + +All fields are optional: + +| Field | Description | Default | +|-------|-------------|---------| +| `description` | Context description that helps agents understand when to apply this rule if `alwaysApply` is `false` | - | +| `alwaysApply` | `true` = referenced directly in agent rule files; `false` = included as optional rules based on context | `true` | +| `fileMatching` | Glob patterns for which files this rule applies to (e.g., `"**/*.ts"`, `"src/**/*.py"`). Currently supported in Cursor. | - | + +If frontmatter is omitted entirely, the file is treated as a regular markdown rule with default settings (`alwaysApply: true`). + +## Symlink Mode + +Use Symlink Mode for simple setups where all agents share the same rules. + +### Requirements + +- Must be named `AGENTS.md` +- Must be the only file in the `ai-rules/` directory (commands/ and skills/ subdirectories are allowed) +- Must not start with `---` (no YAML frontmatter) + +### Format + +```markdown +# Project Rules + +- Use TypeScript for all new code +- Write comprehensive tests +- Follow conventional commits +- Prefer explicit types over `any` +``` + +### How It Works + +In Symlink Mode, `ai-rules generate` creates symlinks pointing to `ai-rules/AGENTS.md` for supported agents instead of generating separate files. This keeps all your rules in one place. + +See [Supported Agents](agents.md) for details on which agents support symlink mode. From 2fad90b5578bcd6c8901b6149cd7f380df2df544 Mon Sep 17 00:00:00 2001 From: Jon Andersen Date: Mon, 26 Jan 2026 20:53:22 -0500 Subject: [PATCH 2/2] Address PR review feedback on Quick Start section - Add explanation of what rule files are for new users - Show --agents flag earlier in Quick Start to highlight selective generation Co-Authored-By: Claude Opus 4.5 Signed-off-by: Jon Andersen --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3ed05eb..9727bfa 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,14 @@ curl -fsSL https://raw.githubusercontent.com/block/ai-rules/main/scripts/install ```bash ai-rules init ``` - Creates an `ai-rules/` directory with an example rule file. + Creates an `ai-rules/` directory with example rule files. Rule files are markdown files containing coding guidelines, conventions, and instructions that get distributed to your AI coding agents. -2. **Add your rules** in `ai-rules/*.md` files +2. **Edit your rules** in `ai-rules/*.md` files to define your project's coding standards 3. **Generate** agent-specific files: ```bash - ai-rules generate + ai-rules generate # All agents + ai-rules generate --agents claude,cursor # Specific agents ``` Creates `CLAUDE.md`, `.cursor/rules/*.mdc`, `AGENTS.md`, etc.