██████╗░██╗░░░██╗██╗░░░░░██╗░░░██╗
██╔══██╗██║░░░██║██║░░░░░╚██╗░██╔╝
██████╔╝██║░░░██║██║░░░░░░╚████╔╝░
██╔══██╗██║░░░██║██║░░░░░░░╚██╔╝░░
██║░░██║╚██████╔╝███████╗░░░██║░░░
╚═╝░░╚═╝░╚═════╝░╚══════╝░░░╚═╝░░░

🚀 Quick Install

One-Line Installation

curl -fsSL https://raw.githubusercontent.com/patrickclery/ruly/main/setup.rb -o /tmp/ruly_setup.rb && ruby /tmp/ruly_setup.rb

This will:

• Install Ruly to ~/ruly
• Add ruly command to your PATH
• Set up initial configuration at ~/.config/ruly/recipes.yml

Manual Installation

If you prefer to install manually:

# Clone the repository
git clone https://github.com/patrickclery/ruly.git ~/ruly
cd ~/ruly

# Install dependencies
bundle config set --local path 'vendor/bundle'
bundle install

# Add to PATH (add to your ~/.bashrc or ~/.zshrc)
export PATH="$HOME/ruly/bin:$PATH"

# Initialize configuration
ruly init

Uninstall

To remove Ruly:

rm -rf ~/ruly
# Remove the PATH export from your shell configuration file

Getting Started

After installation, you can immediately start using Ruly:

# Initialize configuration (if not done during install)
$ ruly init

# List available commands
$ ruly help

# Combine all rules into one file
$ ruly squash

# Use a specific recipe
$ ruly squash starter

# Clean up generated files
$ ruly clean

# List available recipes
$ ruly list-recipes

# Show version
$ ruly version

🌟 How It Works

Standalone CLI Tool

Ruly is a standalone command-line tool that manages AI assistant rules:

1. Simple Installation: One-line install with curl
2. Self-Contained: Everything runs from ~/ruly
3. Recipe System: Use pre-configured recipes or create your own
4. Smart Caching: Cache compiled recipes for performance
5. Multiple Formats: Support for different AI assistants (Claude, Cursor, etc.)

Benefits:

• ✅ Standalone: No gem installation required
• ✅ Easy updates: Just pull the latest changes
• ✅ No system dependencies: Self-contained in your home directory
• ✅ Flexible rules system: Define your own rules repository or use remote sources
• ✅ Cross-platform: Works anywhere Ruby is installed

What Ruly Does

The ruly command provides:

• ✅ Combine multiple rule files into one document
• ✅ Use recipe collections for different contexts
• ✅ Fetch and include remote GitHub files
• ✅ Cache compiled recipes for performance
• ✅ Support for Claude, Cursor, and other AI assistants
• ✅ Clean up all agent-related files automatically

Generated Files:

your-project/
├── CLAUDE.local.md      # Generated by ruly squash (default)
├── .ruly.yml            # Metadata for clean command
└── .claude/
    └── commands/        # Command files for Claude agent
        ├── bug/         # Bug-related commands
        ├── pr/          # PR management commands
        ├── testing/     # Testing commands
        └── workflow/    # Workflow commands

For other agents:

• Cursor: Uses .cursor/ directory with .mdc files
• Custom: Specify with --agent and --output-file options

---

About Ruly

Ruly is a powerful CLI tool that manages AI assistant rules and configurations for software development projects. It provides a framework for organizing and combining rule files from various sources - your own private repositories, public GitHub repos, or local files - into a single document for AI assistants like Claude or Cursor.

⚠️ Important: Rules Not Included

This repository does not include rule files. You need to:

1. Create your own rules repository (private or public)
2. Configure recipes to point to your rule sources
3. Use the ruly init command to get started with a template

🎯 Setting Up Your Rules

Option 1: Create Your Own Rules Repository

1. Create a new repository for your rules:

   # Create a private repository
   gh repo create yourusername/rules --private --description "My AI assistant rules"
   
   # Clone it locally
   git clone git@github.com:yourusername/rules.git
   cd rules

2. Organize your rules:

   rules/
   ├── ruby/
   │   ├── common.md
   │   ├── rspec.md
   │   └── best-practices.md
   ├── testing/
   │   └── patterns.md
   ├── commands/
   │   ├── bug/
   │   │   └── diagnose.md
   │   └── pr/
   │       └── create.md
   └── core/
       └── debugging.md
   

Option 2: Use Multiple Rule Sources

Create ~/.config/ruly/recipes.yml to combine rules from different repositories:

recipes:
  my-complete-rules:
    description: "Combines personal and company rules"
    sources:
      # Your personal rules repository
      - github: yourusername/rules
        branch: main
        rules:
          - ruby
          - testing
          - commands

      # Company rules (e.g., "FakeCorp")
      - github: fakecorp/development-standards
        branch: main
        rules:
          - guidelines/code-review.md
          - guidelines/security.md

      # Individual files from public repos
      - https://github.com/thoughtbot/guides/blob/main/ruby/README.md

Option 3: Quick Start with Init

After installing Ruly, you can quickly get started with a basic configuration:

# Initialize Ruly with a starter configuration
ruly init

# This creates ~/.config/ruly/recipes.yml with example recipes
# Edit this file to add your own rule sources

Option 4: Use Remote Sources Only

If you don't want to maintain your own rules repository, you can use rules directly from GitHub:

recipes:
  remote-only:
    description: "Rules from various GitHub sources"
    sources:
      # Individual files
      - https://github.com/rubocop/ruby-style-guide/blob/master/README.md
      - https://github.com/testdouble/standard/blob/main/docs/README.md

      # Entire directories (expands to all .md files)
      - https://github.com/fakecorp/standards/tree/main/ruby
      - https://github.com/fakecorp/standards/tree/main/testing

Example: Setting Up Like patrickclery/rules

Here's how the maintainer set up their private rules repository:

1. Created a private repository:

   gh repo create patrickclery/rules --private --description "Private rules for Ruly gem"

2. Created your rules content and pushed to GitHub

3. Updated your Ruly configuration:

   # ~/.config/ruly/recipes.yml
   recipes:
     complete:
       description: "Personal + FakeCorp rules"
       sources:
         - github: patrickclery/rules
           branch: main
           rules:
             - ruby
             - testing
             - commands
   
         - github: fakecorp/cursor-rules
           branch: main
           rules:
             - workflow
             - jira

📝 Using Ruly Commands

Ruly provides a powerful CLI for managing and compiling your AI assistant rules.

Basic Commands

Combine all rules into one file:

ruly squash

Use a specific recipe:

# Recipe name as positional parameter
ruly squash rails
ruly squash api

Custom output file:

# Squash mode with custom output
ruly squash --output-file=combined-rules.md
# or using short option
ruly squash -o docs/my-rules.md

# Combine with recipe
ruly squash rails -o RAILS.md

Analyze token usage:

# Analyze a specific recipe
ruly analyze rails
ruly analyze api

# Analyze all recipes
ruly analyze --all
ruly analyze -a

Clean up generated files:

# Clean all agent-related files for current agent
ruly clean

# Clean files from specific recipe
ruly clean rails

# Clean files for specific agent
ruly clean --agent cursor

# Dry run to see what would be deleted
ruly clean --dry-run
ruly clean -d

# Clean before squashing (remove old files first)
ruly squash --clean
ruly squash rails --clean
ruly squash -c  # Short form

# Deep clean before squashing (remove ALL Claude artifacts)
ruly squash --deepclean
ruly squash rails --deepclean

Recipe System

Recipes allow you to define collections of rules to combine, rather than always including all files.

List available recipes:

ruly list-recipes

Use a specific recipe:

# Use the 'core' recipe
ruly squash --recipe core

# Use 'testing' recipe with custom output
ruly squash --recipe testing -o testing-rules.md

# Short form
ruly squash -r minimal

Available Recipes

Recipes depend on having access to rule files. If you cloned with the default rules submodule, you'll have access to the recipes defined in recipes.yml. Otherwise, create your own recipes in ~/.config/ruly/recipes.yml pointing to your rule sources.

Custom Recipes

Create a ~/.config/ruly/recipes.yml file to define your own recipes or override existing ones:

# ~/.config/ruly/recipes.yml
recipes:
  # Legacy format (still supported)
  my-legacy-project:
    - rules/core/core.md
    - rules/core/sequel.md
    - rules/workflow/pr-creation.md

  # New format: Local files with caching
  enhanced-rails:
    cache: true
    source: local
    files:
      - rules/ruby/*.md
      - rules/awesome-cursor.md
    remote_sources:
      # Individual files - use /blob/
      - https://github.com/danielscholl/mvn-mcp-server/blob/main/.claude/commands/bug-fix.md
      - https://github.com/example/repo/blob/main/rules/testing.md
      # Directories - use /tree/ (expands to all .md files)
      - https://github.com/example/repo/tree/main/rules/ruby

  # Minimal recipe with caching
  minimal-cached:
    cache: true
    source: local
    files:
      - rules/awesome-cursor.md
      - rules/core/core.md
      - rules/core/specs.md

  # Without caching
  docs-only:
    cache: false
    source: local
    files:
      - rules/workflow/*.md
      - rules/gateway/*.md

Remote Sources:

• Supports pulling rules directly from GitHub repositories
• Automatically converts GitHub blob URLs to raw URLs
• Command files (files with "command" in path/name) are saved to .claude/commands/ when using --agent claude
• Non-Claude agents include all files in the main output

GitHub URL Formats:

• Individual files: Use /blob/ URLs for specific files
  • Example: https://github.com/owner/repo/blob/branch/path/to/file.md
• Directories: Use /tree/ URLs to include all .md files in a directory
  • Example: https://github.com/owner/repo/tree/branch/path/to/directory
  • Automatically expands to include all markdown files in that directory
• Important: Files with extensions (like .md) in /tree/ URLs are treated as individual files, not directories

Command File Handling:

• When --agent claude (default), command files are saved to .claude/commands/
• For other agents, command files are included in the main output file
• Command detection: files in /commands/ directories or with "command" in the filename

Caching:

• Use --cache flag to enable caching for any recipe
• Cached files are stored in cache/<agent>/ directory
• Remote files are cached separately in cache/remote/ (7-day expiration)
• Cache is disabled by default
• Use ruly clean to remove cache files

User recipes:

• Are automatically loaded from ~/.config/ruly/recipes.yml
• Override base recipes with the same name
• Are stored in your home directory configuration
• Allow user-specific or team-specific customizations

Commands

• Squash (squash [RECIPE]): Combines all rule content into a single large file. Recipe is optional positional parameter. Supports fetching remote GitHub files and caching for performance. Use --toc or -t to generate a table of contents with unique anchors for all headers, ensuring proper navigation even when multiple files have identical header names. Also includes a list of available slash commands. Use --deepclean to remove all Claude artifacts before squashing (overrides --clean).

• Analyze (analyze [RECIPE]): Analyzes token usage for recipes without generating files. Shows detailed file breakdown and total token count. Use --all to analyze all recipes at once.

• Clean (clean [RECIPE]): Deletes output files created by the squash command. Recipe is optional and overrides metadata. Removes main output file and command files directory. Use --deepclean to remove all Claude artifacts (.claude/ directory, CLAUDE.local.md, CLAUDE.md) regardless of recipe.

• List Recipes (list-recipes): Shows all available recipes with file counts and cache indicators.

• Version (version): Shows the current Ruly version.

Slash Commands

Slash commands are special commands that can be defined in your rule files to provide quick actions for AI assistants. When you include command files in your rules (typically in a commands/ directory), they become available as slash commands in the generated output.

For example, if you have a file commands/bug/diagnose.md in your rules, it would become available as /bug:diagnose when using the generated rules with Claude or other AI assistants.

The --toc option will automatically generate:

1. A table of contents with links to all headers in the combined document
2. Unique anchors for headers (prefixed with the source file path) to handle duplicate header names across files
3. A list of all available slash commands in your squashed output

This ensures proper navigation even when multiple rule files contain headers with identical names (e.g., multiple files with "# Introduction" sections).

Examples

# Generate CLAUDE.local.md with all rules
ruly squash

# Dry run - see what would be created without creating it
ruly squash --dry-run
ruly squash -d

# Generate core rules only
ruly squash --recipe core
ruly squash -r core

# Generate squashed testing rules to a custom file
ruly squash -r testing -o test/testing-rules.md

# Generate rules for a different agent (e.g., cursor)
ruly squash -r rails --agent cursor -o CURSOR.md
ruly squash -r rails -a cursor -o CURSOR.md

# Generate with remote sources (command files go to .claude/commands/)
ruly squash -r example_mixed

# Use cached version (if recipe has cache: true)
ruly squash rails

# Bypass cache for one run
ruly squash rails --no-cache

# Clean up generated files
ruly clean

# Dry run - see what would be deleted
ruly clean --dry-run
ruly clean -d

# Deep clean - remove all Claude artifacts
ruly clean --deepclean

# Clean specific output file
ruly clean -o test/testing-rules.md

# List what recipes are available
ruly list-recipes

# Show version
ruly version

# View help
ruly help
ruly help squash
ruly help clean

Ruly will automatically:

• Load recipes from both recipes.yml and ~/.config/ruly/recipes.yml
• Support glob patterns in recipe definitions
• Create parent directories if using custom output paths
• Display file count and output size
• Show which recipe was used in the output

🔧 Troubleshooting

Common Issues

Permission denied:

• Ensure you have write access to your project directory
• Check that Ruby gems can be installed globally

Recipe not found:

• Run ruly list-recipes to see available recipes
• Check ~/.config/ruly/recipes.yml for user-defined recipes
• Ensure recipe names match exactly (case-sensitive)

Files not being cleaned:

• Check .ruly.yml metadata file exists
• Use ruly clean --dry-run to preview what will be deleted
• Specify agent with --agent option if not using Claude