external-rules

# External Rules

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple.svg)](https://claude.ai/code)

**Import and reuse your existing AI coding rules from Cursor, Windsurf, GitHub Copilot, and Aider in Claude Code.**

Stop maintaining duplicate rule files for different AI tools. External Rules automatically imports your existing coding guidelines and conventions into every Claude Code conversation.

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Supported Sources](#supported-sources)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Commands](#commands)
- [How It Works](#how-it-works)
- [File Format Support](#file-format-support)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)

## Overview

Modern development teams often use multiple AI coding assistants. Each tool has its own configuration format for coding rules and guidelines:

- **Cursor** uses `.cursor/rules/*.mdc` files
- **Windsurf** uses `.windsurfrules`
- **GitHub Copilot** uses `.github/copilot-instructions.md`
- **Aider** uses `CONVENTIONS.md`

Maintaining separate files with the same content is tedious and error-prone. This plugin solves that problem by allowing Claude Code to read rules from any of these sources automatically.

## Features

- **Multi-Source Import**: Read rules from Cursor, Windsurf, GitHub Copilot, and Aider
- **Automatic Injection**: Rules are included in every conversation without manual intervention
- **Selective Import**: Enable or disable individual sources as needed
- **YAML Frontmatter Support**: Properly parses MDC and MD files with frontmatter
- **Recursive Scanning**: Finds all Cursor rules in subdirectories
- **Zero Configuration Runtime**: Once set up, works automatically
- **Non-Destructive**: Only reads files, never modifies your existing rules
- **Works with CLAUDE.md**: Complements Claude Code's native rule system

## Supported Sources

| Source | File Location | Format |
|--------|---------------|--------|
| **Cursor** | `.cursor/rules/*.mdc` | MDC (Markdown + frontmatter) |
| **Windsurf** | `.windsurfrules` | Plain text or Markdown |
| **GitHub Copilot** | `.github/copilot-instructions.md` | Markdown |
| **Aider** | `CONVENTIONS.md` | Markdown |

## Installation

### Option 1: Add Marketplace (Recommended)

Add this marketplace to Claude Code, then install the plugin:

```bash
# Add the marketplace
/plugin marketplace add https://gitlab.com/mirzaaghazadeh/claude-code-external-rules.git

# Install the plugin
/plugin install external-rules
```

### Option 2: Direct Installation

Install directly from this repository:

```bash
/plugin install https://github.com/mirzaaghazadeh/claude-code-external-rules.git
```

### Option 3: Manual Installation

Clone the repository to your Claude Code plugins directory:

```bash
# Navigate to your Claude Code plugins directory
cd ~/.claude/plugins

# Clone the plugin
git clone https://github.com/mirzaaghazadeh/claude-code-external-rules.git external-rules
```

Restart Claude Code or reload plugins.

### Project-Level Installation

To auto-install for all team members, add to your project's `.claude/settings.json`:

```json
{
  "plugins": {
    "marketplaces": [
      "mirzaaghazadeh/claude-code-external-rules"
    ]
  }
}
```

## Quick Start

1. **Configure the plugin** by running the configuration command:

   ```
   /external-rules
   ```

2. **Select your sources**: Choose which AI IDE rules to import when prompted.

3. **Start coding**: Your rules are now automatically included in every Claude Code conversation.

That's it! The plugin handles everything else automatically.

## Configuration

### Settings File

Configuration is stored in `.claude/external-rules.local.md` in your project root:

```markdown
---
enabled: true
cursor: true
windsurf: false
copilot: true
aider: false
---

# External Rules Configuration

Enabled sources will be imported into Claude Code context.
Run `/external-rules` to change settings.
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `false` | Master switch for the plugin |
| `cursor` | boolean | `false` | Import rules from `.cursor/rules/` |
| `windsurf` | boolean | `false` | Import rules from `.windsurfrules` |
| `copilot` | boolean | `false` | Import rules from `.github/copilot-instructions.md` |
| `aider` | boolean | `false` | Import rules from `CONVENTIONS.md` |

### Git Ignore

Add the settings file to your `.gitignore` to keep configuration local:

```gitignore
# Claude Code local settings
.claude/*.local.md
```

## Commands

### `/external-rules`

Configure which external AI IDE rules to import.

**What it does:**
1. Scans your project for available rule files
2. Prompts you to select which sources to enable
3. Creates or updates the settings file
4. Confirms your configuration

**Example output:**
```
Found external rule files:
  - .cursor/rules/coding-standards.mdc
  - .cursor/rules/testing.mdc
  - .github/copilot-instructions.md

Which sources would you like to enable?
  [x] Cursor (2 files)
  [ ] Windsurf (not found)
  [x] GitHub Copilot (1 file)
  [ ] Aider (not found)

Configuration saved! Rules will be included in future conversations.
```

### `/external-rules:status`

Display current configuration and loaded rules.

**Example output:**
```
External Rules Status
=====================

Overall: ENABLED

Sources:
  [x] Cursor    - .cursor/rules/*.mdc
  [ ] Windsurf  - .windsurfrules
  [x] Copilot   - .github/copilot-instructions.md
  [ ] Aider     - CONVENTIONS.md

Loaded Rules:
  - .cursor/rules/coding-standards.mdc
  - .cursor/rules/testing.mdc
  - .github/copilot-instructions.md

Total: 3 rule files
```

## How It Works

The plugin uses Claude Code's hook system to inject rules into every conversation:

```
┌─────────────────┐
│  User submits   │
│    a prompt     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ UserPromptSubmit│
│   hook fires    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  inject_rules.py│
│   executes      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Load settings  │
│  from .claude/  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Load rules from │
│ enabled sources │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Format rules   │
│  as system msg  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Rules injected  │
│ into context    │
└─────────────────┘
```

### Technical Details

- **Hook Type**: `UserPromptSubmit` - runs before each prompt is processed
- **Timeout**: 10 seconds maximum execution time
- **Output**: JSON with `systemMessage` field containing formatted rules
- **Error Handling**: Graceful degradation - returns empty JSON on errors

## File Format Support

### Cursor Rules (`.mdc`)

MDC files support YAML frontmatter which is stripped before injection:

```markdown
---
description: Coding standards for the project
globs: ["**/*.ts", "**/*.tsx"]
---

# Coding Standards

Always use TypeScript strict mode...
```

### Windsurf Rules

Plain text or markdown, loaded as-is:

```markdown
# Project Guidelines

Use functional components with hooks...
```

### GitHub Copilot Instructions

Standard markdown file:

```markdown
# Copilot Instructions

When generating code for this project:
- Use ESLint configuration
- Follow the existing patterns...
```

### Aider Conventions

Standard markdown file:

```markdown
# Coding Conventions

This project uses:
- Python 3.11+
- Type hints everywhere...
```

## Examples

### Example: Injected Rules Output

When rules are loaded, they appear in Claude's context like this:

```markdown
# External AI IDE Rules

The following rules have been imported from other AI coding assistants.
Please follow these guidelines.

## From Cursor

### coding-standards
*Source: .cursor/rules/coding-standards.mdc*

Always use TypeScript strict mode.
Prefer functional components over class components.
Use named exports instead of default exports.

### testing
*Source: .cursor/rules/testing.mdc*

Write unit tests for all utility functions.
Use React Testing Library for component tests.

## From GitHub Copilot

### copilot-instructions
*Source: .github/copilot-instructions.md*

Follow the existing code style in this repository.
Use meaningful variable and function names.
```

### Example: Project Setup

A typical project structure with external rules:

```
my-project/
├── .cursor/
│   └── rules/
│       ├── coding-standards.mdc
│       ├── testing.mdc
│       └── react-patterns.mdc
├── .github/
│   └── copilot-instructions.md
├── .windsurfrules
├── .claude/
│   ├── external-rules.local.md  # Plugin settings (gitignored)
│   └── CLAUDE.md                # Claude Code native rules
├── CONVENTIONS.md               # Aider conventions
└── src/
    └── ...
```

## Troubleshooting

### Rules not being loaded

1. **Check if plugin is enabled**: Run `/external-rules:status`
2. **Verify settings file exists**: Check for `.claude/external-rules.local.md`
3. **Confirm `enabled: true`** in settings file
4. **Check file locations**: Ensure rule files are in expected paths

### Python errors

The plugin requires Python 3.8+. Verify your Python installation:

```bash
python3 --version
```

### Hook not firing

1. Check that the plugin is properly installed
2. Restart Claude Code
3. Verify `hooks/hooks.json` is properly formatted

### Empty rules

1. Verify the rule files have content (not just frontmatter)
2. Check file permissions
3. Ensure files are UTF-8 encoded

## FAQ

### Does this modify my existing rule files?

No. The plugin only reads files - it never writes to or modifies your existing rules.

### Can I use this alongside CLAUDE.md?

Yes! External rules complement Claude Code's native `CLAUDE.md` files. Both are included in the context.

### Which rules take priority?

Claude Code processes all rules together. There's no strict priority - all enabled rules are included in the context.

### Does this slow down my prompts?

The plugin adds minimal overhead (typically < 100ms) to read and format rule files.

### Can I use different rules for different projects?

Yes. The settings file is stored per-project in `.claude/external-rules.local.md`, so each project can have its own configuration.

### What happens if a rule file doesn't exist?

The plugin gracefully handles missing files - it simply skips sources where files don't exist.

## Requirements

- **Claude Code**: Version 1.0.0 or higher
- **Python**: Version 3.8 or higher
- **Operating System**: macOS, Linux, or Windows (with Python)

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development

To test changes locally:

1. Make your modifications
2. Test with a sample project containing rule files
3. Run `/external-rules:status` to verify loading
4. Check that rules appear in Claude's responses

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Thanks to the Claude Code team for the plugin system
- Inspired by the need to unify AI coding assistant configurations
- Built for the community by the community

---

**Made with care for developers who use multiple AI tools.**