CrossRule

# CrossRule

A command-line tool for converting AI code editor rules between different formats. Work seamlessly across Cursor, Windsurf, Cline, VSCode, and other AI-powered development environments without losing your carefully crafted coding guidelines.

[![npm version](https://badge.fury.io/js/crossrule.svg)](https://www.npmjs.com/package/crossrule)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## The Problem

You've spent time crafting the perfect coding rules for Cursor, but now you want to try Windsurf. Or maybe your team uses different AI editors, and you need to share consistent guidelines across tools. Manually converting and maintaining rules across multiple editors is tedious and error-prone.

## The Solution

CrossRule automatically detects existing AI editor rules in your project and converts them to any other supported format. Your TypeScript conventions, React patterns, and testing requirements can follow you wherever you code.

## Supported Editors

CrossRule works with 9 major AI code editors:

- **Cursor** - `.mdc` files in `.cursor/rules/`
- **Windsurf** - Markdown files in `.windsurf/rules/`  
- **Cline** - Markdown files in `.clinerules/`
- **VSCode** - Instructions and prompts for AI extensions
- **AGENTS.md-compatible editors** (Codex CLI, OpenCode, VSCode Agents) - `AGENTS.md` project rules
- **Claude Code** - `CLAUDE.md` guidance files
- **Qoder** - Natural language rules with trigger conditions
- **Trae** - Markdown rules with YAML frontmatter
- **QwenCoder** - `QWEN.md` context files

## Installation

Install CrossRule globally to use it in any project:

```bash
npm install -g crossrule
```

Or run it directly without installing using npx:

```bash
npx crossrule init
```

Verify the installation:

```bash
crossrule --version
# Should output: 1.0.3
```

## Quick Start

Navigate to your project directory and run:

```bash
crossrule init
```

CrossRule will:
1. Scan your project for existing AI editor rules
2. Show you what it found and let you choose a source
3. Present an interactive list of target editors
4. Convert your rules while preserving their meaning and structure

## Universal Rule Management

### Adding New Rules

Create and deploy rules across all your AI editors with a single command:

```bash
# Simple always-apply rule
crossrule add "Use strict TypeScript configuration" --type always --to all

# Pattern-based rule for specific file types
crossrule add "React components must use functional syntax" \
  --type pattern --patterns "*.tsx,*.jsx" --to cursor,windsurf

# Complex multi-line rule from file
crossrule add --from-file team-standards.md \
  --type pattern --patterns "*.ts,*.tsx" --to all

# AI-decision rule with context
crossrule add "Suggest performance optimizations" \
  --type ai-decision --context "performance-critical" --to cursor,qoder
```

### Rule Types

CrossRule supports four intelligent rule types:

- **Always (`--type always`)** - Applied to all conversations and code
- **Pattern (`--type pattern`)** - Triggered when working with specific file types
- **Manual (`--type manual`)** - Invoked explicitly by name or command  
- **AI-Decision (`--type ai-decision`)** - Applied when AI determines relevance

### Multi-Line Rules

Handle complex coding standards with full markdown support:

```bash
# Using heredoc for complex rules
crossrule add --type always --to all << 'EOF'
# TypeScript Best Practices

## Type Safety
- Enable all strict mode flags
- Use 'unknown' instead of 'any'
- Implement proper error boundaries

## Code Organization
- One component per file
- Index files for clean imports
- Separate types into .types.ts files
EOF
```

### Command Options

- `--type <type>` - Rule type: always, pattern, manual, ai-decision
- `--patterns <patterns>` - File patterns (comma-separated) for pattern rules
- `--to <editors>` - Target editors: all, or comma-separated list
- `--from-file <file>` - Read rule content from markdown file
- `--name <name>` - Custom rule name (auto-generated if not provided)
- `--description <desc>` - Rule description for documentation
- `--context <context>` - Context hint for AI-decision rules

## How It Works

### Smart Detection
CrossRule understands the unique file structures and formats of each AI editor. It correctly parses YAML frontmatter, section delimiters, and trigger conditions to extract the semantic meaning of your rules.

### Semantic Preservation
When converting between formats, CrossRule maintains the intent of your rules:

- Always-active rules remain always-active
- File pattern rules are converted to equivalent glob patterns
- Manual trigger rules preserve their conditional nature
- Descriptions and metadata are carried forward appropriately

### Format-Specific Output
Each editor has its own conventions:

- **Cursor**: YAML frontmatter with `alwaysApply` and `globs` fields
- **Qoder**: Trigger-based frontmatter (`always_on`, `glob`, `manual`, `model_decisi

... (truncated)