AI Coding Assistant Rules Converter

# AI Coding Assistant Rules Converter

A universal tool to convert `.cursor/rules` files to formats compatible with multiple AI coding assistants.

## Overview

This script automatically converts Cursor IDE rule files (`.mdc` format) into formats compatible with multiple AI coding assistants. It preserves the structure, frontmatter metadata, and content of your Cursor rules while generating files that work across different tools.

**Purpose:** Enable teams to maintain **one source of truth** (`.cursor/rules/*.mdc`) that automatically generates rules for all AI coding assistants, with automatic synchronization via git hooks.

### Supported AI Assistants

✅ **Cursor** - via `AGENTS.md`  
✅ **Augment** - via `AGENTS.md` or `CLAUDE.md`  
✅ **Claude Code** - via `CLAUDE.md`  

Based on [Augment's rules system documentation](https://docs.augmentcode.com/cli/rules#supported-rules-files).

## Features

- ✅ **Multi-tool compatibility** - Generates `AGENTS.md` and `CLAUDE.md` for broad AI assistant support
- ✅ **Single source of truth** - Maintain rules in `.cursor/rules/*.mdc` format
- ✅ **Automatic synchronization** - Git hooks detect and convert changes automatically
- ✅ Parses Cursor `.mdc` files with frontmatter (description, globs, alwaysApply)
- ✅ Organizes rules into "Global Rules" (always apply) and "Conditional Rules"
- ✅ Generates clean, readable markdown output
- ✅ Works with any repository that has `.cursor/rules`

## But is it useful?
See [is-it-useful.md](docs/is-it-useful.md) for a self-assessment.

## Example Output

This repository includes **example generated files** in the root directory:
- **[AGENTS.md](AGENTS.md)** - Example output for Cursor and Augment
- **[CLAUDE.md](CLAUDE.md)** - Example output for Claude Code and Augment

These files are auto-generated from `.cursor/rules/*.mdc` and are included in version control to demonstrate the conversion output. In your own repository, you can choose to commit these files or regenerate them as needed.


## Quick Start

### Setup

First, install dependencies (this also sets up Husky git hooks):

```bash
npm install
```

### Automatic Conversion (Recommended)

Git hooks powered by [Husky](https://typicode.github.io/husky/) automatically detect changes to `.cursor/rules` and run the conversion script:

- **Before commits**: Detects changes in staged files (pre-commit)
- **After commits**: Detects changes in committed files (post-commit)
- **After merges/pulls**: Detects changes from merged branches (post-merge)
- **After branch switches**: Detects differences between branches (post-checkout)

Simply commit your changes to `.cursor/rules/` and the conversion happens automatically!

```bash
# Edit your cursor rules
vim .cursor/rules/my-rule.mdc

# Commit the changes
git add .cursor/rules/my-rule.mdc
git commit -m "Update cursor rules"

# 📝 Hook automatically detects changes and runs conversion
# ✅ You'll be notified if AGENTS.md or CLAUDE.md need to be committed
```

**Benefits of Husky:**
- ✅ Hooks are tracked in git (in `.husky/` directory)
- ✅ Automatically installed for all team members via `npm install`
- ✅ No manual setup required per developer
- ✅ Easy to maintain and update

## Usage

### Basic Usage

From your repository root:

```bash
npm run convert
# or
node scripts/cursor-to-augment-rules.js
```

This will:
- Read all `.mdc` files from `.cursor/rules/`
- Generate `AGENTS.md` (Cursor + Augment compatible)
- Generate `CLAUDE.md` (Claude Code + Augment compatible)

### Custom Paths

```bash
node scripts/cursor-to-augment-rules.js <cursor-rules-dir>
```

**Arguments:**
- `cursor-rules-dir`: Path to your Cursor rules directory (default: `.cursor/rules`)

**Example:**
```bash
node scripts/cursor-to-augment-rules.js ./my-custom-rules
```

**Note:** The script always generates `AGENTS.md` and `CLAUDE.md` in the repository root.

## Cursor Rules Format

The script expects Cursor rule files in `.mdc` format with optional frontmatter:

```markdown
---
description: Rule description
globs: *.ts
alwaysApply: true
---

Rule content goes here...
```

**Frontmatter fields:**
- `description`: Human-readable description of the rule
- `globs`: File pattern(s) this rule applies to (e.g., `*.ts`, `*.js`)
- `alwaysApply`: Boolean indicating if rule should always be applied (default: `true`)

### Finding Cursor Rules

Looking for pre-made Cursor rules? You can:
- Create your own rules based on your team's coding standards
- Search GitHub for community-contributed cursor rules
- Adapt existing coding guidelines into `.mdc` format

**Example: Adding Custom Cursor Rules**

```bash
# Create a new rule file
vim .cursor/rules/typescript.mdc

# Add your rule content with frontmatter
# ---
# description: TypeScript coding standards
# globs: *.ts
# alwaysApply: true
# ---
# Your rule content here...

# Commit the changes (hooks will auto-convert)
git add .cursor/rules/
git commit -m "Add TypeScript cursor rules"

# The conversion happens automatically!
# Then commit the gen

... (truncated)