Rulesify

Rulesify is a command-line tool (written in Rust) that provides unified management of AI assistant rules across multiple platforms. Create rules once in Universal Rule Format (URF), then deploy them everywhere.

Supported AI Tools

• Cursor (.cursor/rules/*.mdc — Markdown with YAML frontmatter)
• Cline (.clinerules/*.md — Simple Markdown files)
• Claude Code (<rule-name>.md — Markdown files in project root)
• Goose (<rule-name>.goosehints — Plain text files in project root)

File Generation Details:

• Generated tool files are automatically Git-ignored
• Only edit URF files (.urf.yaml) - tool files are regenerated on deployment
• Each tool has specific format requirements that are handled automatically
• Round-trip integrity: URF → tool file → URF maintains all information

Features

• Rule Management: Create, edit, list, show, and delete rules
• Multi-Tool Deployment: Deploy rules to all supported AI tools
• Import Functionality: Import existing rules from any AI tool format
• Validation System: Comprehensive quality and format validation
• Template System: Create rules from built-in templates
• Configuration Management: Flexible storage and configuration options
• Sync: Synchronize deployed rules back to URF format
• Round-Trip Integrity: Import/export cycle is lossless and auto-validated
• Unicode Support: Handles international text
• Comprehensive Testing: 75 tests, 100% pass rate

Installation

One-liner (Recommended)

Run this command to install the latest stable release:

curl -sSL https://github.com/ihelio/rulesify/releases/latest/download/install.sh | bash

• This script detects your OS/architecture, downloads the correct binary, installs it to ~/.local/bin, and adds it to your PATH if needed.
• After installation, restart your shell or run:

  export PATH="$HOME/.local/bin:$PATH"
  

Installing Edge Releases

Edge releases are pre-release builds from the latest merged commit on the default branch. They allow you to test the newest changes without waiting for a production tag.

Install latest edge release (moving tag edge):

curl -sSL https://github.com/ihelio/rulesify/releases/latest/download/install.sh | bash -s -- --edge

Install a specific edge release by commit SHA (tag edge-<sha>):

curl -sSL https://github.com/ihelio/rulesify/releases/latest/download/install.sh | bash -s -- --edge abc1234

Install specific version tag:

curl -sSL https://github.com/ihelio/rulesify/releases/latest/download/install.sh | bash -s -- v0.3.0

Show help:

curl -sSL https://github.com/ihelio/rulesify/releases/latest/download/install.sh | bash -s -- --help

Note: Edge releases are tagged as edge (latest) and edge-<sha> (immutable). They are pre-release builds and may be unstable. Use stable releases for production.

Manual Installation (Fallback)

1. Download the latest binary for your OS/arch from GitHub Releases.
2. Move it to ~/.local/bin (create the directory if it doesn't exist):

   mkdir -p ~/.local/bin
   mv rulesify-<os>-<arch> ~/.local/bin/rulesify
   chmod +x ~/.local/bin/rulesify
   

3. Add ~/.local/bin to your PATH if not already present.

Quick Start

Basic Usage

# Create a new rule
rulesify rule new typescript-style

# Import existing rules from different tools
rulesify import --tool cursor .cursor/rules/my-rule.mdc
rulesify import --tool cline .clinerules/coding-standards.md

# Validate rules for quality and compliance
rulesify validate --all
rulesify validate typescript-style

# Deploy to all configured tools
rulesify deploy --all

# Deploy to specific tool
rulesify deploy --tool cursor --all
rulesify deploy --tool cline --rule typescript-style

# Sync deployed rules back to URF (preview first)
rulesify sync --dry-run
rulesify sync

Synchronization Examples

Sync reads deployed tool files and updates URF files when changes are detected.

# Synchronize all deployed rules back to URF format
rulesify sync

# Preview changes without applying them
rulesify sync --dry-run

# Sync a single rule only
rulesify sync --rule typescript-style --dry-run

# Sync from a specific tool only
rulesify sync --tool cursor

Import Examples

Import rules from different AI tools:

# Import from Cursor (YAML frontmatter + Markdown)
rulesify import --tool cursor .cursor/rules/python-style.mdc

# Import from Cline (Simple Markdown)
rulesify import --tool cline .clinerules/react-patterns.md

# Import from Claude Code (Markdown in project root)
rulesify import --tool claude-code python-style.md

# Import from Goose (Plain text hints)
rulesify import --tool goose coding-standards.goosehints

# Import with custom rule ID
rulesify import --tool cursor .cursor/rules/my-rule.mdc --rule-id custom-name

Validation

Ensure your rules meet quality standards:

# Validate all rules
rulesify validate --all

# Validate specific rule
rulesify validate python-style

# Validation checks include:
# - Name and content requirements
# - File reference security
# - Format consistency
# - Pattern validation

Universal Rule Format (URF)

Rulesify uses a YAML-based Universal Rule Format for internal storage. Each rule is a single .urf.yaml file. Edit only these files—generated tool files are Git-ignored. Each URF file starts with a fingerprint comment (# sha256:...) for integrity.

Sample URF YAML:

# -------------------------------------------------------------
#  UNIVERSAL RULE FILE (URF) – SINGLE SOURCE OF TRUTH
#  Replace <placeholders> and delete comments after editing.
# -------------------------------------------------------------
id: typescript-style              # machine-safe slug, filled automatically
version: 1.0.0                    # bump when you make breaking changes
metadata:
  name: "TypeScript Style Guide"  # appears in exported Markdown H1
  description: |
    Coding standards for TypeScript projects
  tags: [typescript, style, linting]
  priority: 5                     # 1 (low) → 10 (high); used for ordering
  # auto_apply is now in tool_overrides.cursor section
content:
  - title: "Code Style"           # Markdown H2 in exports
    format: markdown              # or plaintext / code
    value: |-
      • Use consistent formatting...
      • Add more guidelines here
references:                       # optional list of @file references
  - @tsconfig.json
conditions:                       # optional glob patterns that trigger auto-attach
  - type: file_pattern
    value: '**/*.ts'
# Tool-specific overrides (ignored by other exporters)
tool_overrides:
  cursor:
    # Application mode - how Cursor should apply this rule:
    # • always: Apply to every chat and cmd-k session
    # • intelligent: When Agent decides it's relevant (RECOMMENDED)
    # • specific_files: When file matches specified patterns
    # • manual: Only when @-mentioned by user
    apply_mode: intelligent     # Options: always | intelligent | specific_files | manual

    globs: [src/**/*.ts]        # File patterns (only used when apply_mode is "specific_files")
  cline:
    toggle_default: true
  claude-code: {}
  goose: {}

Editing & Round-Trip Integrity:

• Edit only *.urf.yaml files. Generated tool files are Git-ignored.
• Each URF file starts with a fingerprint comment (# sha256:...).
• Round-trip guarantee: urf → tool file → urf is lossless (auto-validated).
• Tool-specific quirks are isolated in tool_overrides.

Rule ID Management

Rulesify uses a unified rule ID system that ensures consistent, machine-safe identifiers across all operations:

Rule ID Format

• Lowercase with hyphens: typescript-style, react-patterns
• Alphanumeric and hyphens only: Special characters are removed
• Length limits: 2-50 characters
• No consecutive hyphens: Multiple hyphens are collapsed to single hyphens

ID Generation Hierarchy

When creating or importing rules, Rulesify determines the rule ID using this priority order:

1. Embedded HTML comment (highest priority): <!-- rulesify-id: custom-id -->
2. Filename-based ID: Extracted from filename and sanitized
3. Rule name: Sanitized version of the rule's display name
4. Timestamp fallback: imported-rule-{timestamp} as last resort

Sanitization Examples

"TypeScript Style Guide" → "typescript-style-guide"
"React_Components"       → "react-components"
"My Rule!!!"            → "my-rule"
"rule with   spaces"     → "rule-with-spaces"

ID Tracking in Sync Operations

• HTML Comment Embedding: Deployed files include <!-- rulesify-id: {id} --> for tracking
• Filename Preservation: Sync operations preserve original rule IDs based on .urf.yaml filenames
• Conflict Resolution: Filename-based IDs take precedence during sync to maintain consistency

This system ensures that rule IDs remain stable across import, export, and sync operations while maintaining compatibility with all supported AI tools.

Command Reference

Rule Management

• rulesify rule new <name> - Create a new rule from template skeleton
• rulesify rule edit <name> - Edit an existing rule in your configured editor
• rulesify rule list - List all rules with names and descriptions
• rulesify rule list -r <regex> - List rules matching regex pattern (e.g., -r "test.*")
• rulesify rule show <name> - Show detailed rule information including content and metadata
• rulesify rule delete <name> - Delete a rule (requires confirmation)

Validation

• rulesify validate [rule] - Validate specific rule for quality and format compliance
• rulesify validate --all - Validate all rules for issues, warnings, and best practices

Deployment

• rulesify deploy --all - Deploy all rules to all configured default t