Skip to content
patrickcleryPublic

About

CLI tool for managing AI assistant rules and configurations

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

684 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

Why ruly

Ruly compiles the rules each task needs, from one shared rules repository, into the files Claude Code reads: CLAUDE.local.md, .claude/skills/, .claude/commands/ and .claude/agents/.

  • Task-scoped recipes: a named recipe lists the rule files, skills, commands and MCP servers for one kind of work, and ruly squash <recipe> writes only that set.
  • requires: dependency resolution: rule files declare their dependencies; ruly resolves them recursively, includes each file once, and ruly stats reports circular requires: chains.
  • A recipe and model per subagent: each entry under a recipe's subagents: gets its own recipe and model, written to .claude/agents/.
  • One rules repo on every machine: ruly squash --sync mirrors a shared recipes.yml and the files it uses; per-machine overrides: add to it without copying it.
  • Checks on squash output: every squash that writes files (not --dry-run) reports ambiguous anchor links, and files that several skills require but the recipe leaves out.

See Ruly vs. native Claude Code for how each of these compares with what Claude Code does on its own, and Ruly vs. Ruler and rulesync for two cross-agent rule tools.

🚀 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

Ruly vs. native Claude Code

Claude Code already loads CLAUDE.md, .claude/rules/, @path imports, skills and subagents itself. Ruly runs before that: it picks the files a task needs and writes them where Claude Code reads them.

Capability Native Claude Code Ruly
Per-task selection A rule is scoped by file path only: paths is the only frontmatter field a rule reads (docs). It loads every session or when a matching file is opened; the docs send task-specific instructions to skills, which load on demand (docs). A named recipe lists the files, skills, commands and MCP servers for one task, and ruly squash <recipe> writes only that set.
Dependency resolution @path imports pull files into a CLAUDE.md, up to four hops deep (docs); a rule file has no field for declaring dependencies (docs). requires: frontmatter is resolved recursively, each file is included once, --strict fails on a missing dependency, and ruly stats lists circular chains.
Token cost of includes Imports "don't reduce its context cost, because imported files load together with the CLAUDE.md that imports them" (docs); path-scoped rules and skills defer loading instead (docs). The squashed output holds only the recipe's files and their requires:, and ruly stats reports token counts per file and in total. On ruly's synthetic bench fixture (five recipes, cl100k_base tokens), the squashed recipe output plus its skill and command descriptions was 74.3% smaller than loading every rule (median), and 68.4% smaller than a native layout's always-loaded set (63.0% if three fixture rules that no recipe uses are left out; benchmark details).
Cross-machine sharing Symlinked shared rules load only after a once-per-project approval of external imports, and then only the rules without paths (docs); ~/.claude/rules/ applies to every project on one machine (docs). ruly squash --sync mirrors a shared recipes.yml and every file it uses into ~/.config/ruly/remotes/, and per-machine overrides: add to a shared recipe without copying it.
Per-subagent model Each subagent file sets its own model: and preloaded skills: by hand (docs). A recipe's subagents: entries each name a recipe and a model; ruly writes the .claude/agents/ files, and the model falls back from subagent to recipe to inherit.
Post-squash checks Rules and imports are read as written, at session start or when a matching file is opened, with no compile step in between (docs). Every squash that writes output checks for ambiguous anchor links (a heading that appears more than once) and warns when several skills require a file the recipe leaves out.

Native behavior is quoted from the Claude Code docs as of November 2026.

Ruly vs. Ruler and rulesync

Ruler and rulesync write one rules source to many agents. The table compares how each tool chooses which rules go into an output, where the three tools overlap.

Capability Ruler rulesync Ruly
Named rule sets No. Every .md under .ruler/ (except skills and subagents) is concatenated (source), and ruler.toml has no key that selects rule files (schema). No. The config has no profile or preset key (schema); a rule's targets and globs pick tools and paths (schema), and --input-roots layers whole source directories per run (docs). A named recipe lists the files, skills, commands and MCP servers for one task, and ruly squash <recipe> writes only that set.
Includes between rule files No. Rule files are joined with source markers; there is no include syntax (source). No. Rule frontmatter has no requires or include field (schema). requires: frontmatter is resolved recursively, for local and GitHub sources, and each file is included once.
Cycle reporting No. Without includes there are no include cycles to report (source). No. Without includes there are no include cycles to report (schema). ruly stats lists circular requires: chains; squash includes each file once, so a cycle cannot loop.
Per-subagent model Yes. A .ruler/agents/*.md subagent takes a model field (source); each subagent is one hand-written file, and the feature is marked experimental. Yes. A subagent file sets a model per tool, such as claudecode.model (docs); each subagent is one hand-written file. Each subagents: entry names a recipe and a model; ruly compiles that recipe into the subagent's .claude/agents/ file.
Shared source + overrides No. Without a local .ruler/ it falls back to $XDG_CONFIG_HOME/ruler as a whole, with no remote source and no merge (source). Yes. sources installs rules from GitHub, git or npm, pinned to commit SHAs in rulesync.lock (docs), and a later --input-roots tree replaces same-path files (docs). ruly squash --sync mirrors a shared recipes.yml and its files, and overrides: add to a named recipe without copying it; there is no lockfile, so --sync mirrors the current remote.
Post-compile checks Partial. Warns on skill directories without SKILL.md and on invalid subagent frontmatter (skills, subagents); no link checks. Partial. generate --check exits 1 on stale output (source) and doctor lints config and AGENTS.md size (docs); no link checks. Every squash that writes output checks for ambiguous anchor links (a heading that appears more than once) and warns when several skills require a file the recipe leaves out.
Agents 32 agent targets, including AGENTS.md (source). 69 --targets values, 61 of them with project rules, including agentsmd (docs). 3 targets, claude, agents (AGENTS.md) and cursor; skills, commands and subagents are written only for Claude Code.

Ruler and rulesync were checked by reading their source and docs at Ruler @5e551e6 (2026-10-27) and rulesync @6e3869d (2026-11-02), in November 2026; neither tool was run. Agent counts change often.

🌟 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. Multiple Formats: Support for different AI assistants (Claude, Cursor, etc.)

Benefits:

  • ✅ Standalone: No gem installation required
  • ✅ Easy updates: Just pull the latest changes
  • ✅ Requirements: Ruby 3.3+ (with Bundler), and the gh CLI for GitHub sources
  • ✅ 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
  • ✅ 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/
│   └── bin/             # Executable scripts (from scripts: key)
└── .claude/
    ├── commands/        # Command files for Claude agent
    │   ├── bug/         # Bug-related commands
    │   ├── pr/          # PR management commands
    │   └── workflow/    # Workflow commands
    └── skills/          # Skill files for Claude agent
        ├── debugging/
        │   └── SKILL.md
        └── pr-review-loop/
            └── SKILL.md

For other agents:

  • Cursor: Uses .cursor/ directory with .mdc files
  • AGENTS.md: -a agents writes AGENTS.md for agents that read the AGENTS.md standard. See AGENTS.md Output.
  • Claude Code plugin: -a claude-plugin packages the same skills, commands, agents, hooks and MCP servers as a plugin directory. See Claude Code Plugin Output.
  • Custom: Specify with --agent and --output-file options

About Ruly

Ruly is a 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
    ├── comms/
    │   ├── jira/
    │   │   ├── common.md           # Shared Jira patterns
    │   │   └── bin/                # Shell scripts for Jira operations
    │   │       └── fetch-jira-details.sh
    │   └── ms-teams/
    │       ├── common.md           # Shared Teams patterns
    │       ├── commands/
    │       │   └── dm.md           # User-facing command
    │       └── agents/
    │           └── ms-teams-dm.md  # Subagent instructions
    ├── github/
    │   ├── pr/
    │   │   └── bin/                # Shell scripts for PR operations
    │   │       └── fetch-pr-details.sh
    │   └── bin/                    # General GitHub scripts
    │       └── git_prettycommit.rb
    └── core/
        └── debugging.md
    

    Directory conventions:

    • commands/ - User-invocable slash commands (e.g., /ms-teams:dm). Must be listed under the commands: recipe key to be output as .claude/commands/ files.
    • skills/ - Skill files that become SKILL.md in .claude/skills/. Must be listed under the skills: recipe key.
    • agents/ - Subagent instruction files (dispatched by orchestrator, not user-invocable)
    • bin/ - Shell scripts and executables. Must be listed under the scripts: recipe key to be copied to .claude/scripts/.
    • Root files - Common patterns and shared configuration

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

Sharing Recipes Across Machines

Machine-specific absolute paths in recipes.yml are the main reason two machines end up squashing different file lists. Ruly solves this by mirroring a shared recipes file, together with every rule file it references, into a fixed local directory that looks the same on every machine.

1. Put a recipes.yml in your rules repository, using paths relative to the repo root:

# patrickclery/rules → recipes.yml
recipes:
  homelab:
    description: "Local development dispatcher"
    files:
      - home/use-media-stack.md
    skills:
      - home/skills/        # directories expand to every .md file inside
    subagents:
      - name: media_stack
        recipe: media-stack

2. Declare it as a remote in ~/.config/ruly/recipes.yml on each machine:

remotes:
  - github: patrickclery/rules
    path: recipes.yml   # default
    branch: main        # default

3. Mirror it with --sync:

ruly squash homelab --sync

--sync fetches the remote recipes.yml and the closure of files it needs — every entry under files:, skills:, commands: and scripts:, directory contents, and everything those files pull in through requires: and skills: frontmatter — into ~/.config/ruly/remotes/<owner>/<repo>/, preserving repo-relative paths. The mirror is replaced atomically; if a file a recipe lists directly cannot be fetched the sync aborts, lists the missing paths, and leaves the previous mirror untouched. Files reached only through requires:/skills: frontmatter are warned about and skipped, matching squash. If the recipes file itself cannot be fetched (offline), an existing mirror is kept with a warning.

Without --sync, Ruly makes no network calls for recipes and reads the mirror as-is.

Where recipes come from (first hit wins):

  1. ~/.config/ruly/remotes/<owner>/<repo>/recipes.yml — mirrored remotes
  2. ./.recipes.yml — a project-local recipes file in the current directory
  3. ~/.config/ruly/recipes.yml — the user config

Entries in a mirrored file are rebased onto the mirror directory; absolute paths, ~ paths and http(s) URLs are left untouched. ruly list-recipes shows which source won and where each recipe came from.

Per-machine tweaks with overrides:

remotes: and overrides: are settings, so they are read from both ~/.config/ruly/recipes.yml and ./.recipes.yml whichever source wins. An override adds to a shared recipe instead of restating it — arrays are unioned, scalars replaced, subagents merged by name:

# ~/.config/ruly/recipes.yml
remotes:
  - github: patrickclery/rules
overrides:
  homelab:
    files:
      - ~/notes/this-machine-only.md   # appended to the shared list
    mcp_servers:
      - grafana

Overriding a recipe that is not loaded is an error. The recipes: block in the user config still works as before and is used only when nothing higher in the chain exists; relative paths under a mirrored recipe (including in overrides) resolve inside the mirror.

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 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

Token statistics:

# Token stats for every file and recipe
ruly stats

# Token stats for one recipe
ruly stats rails

# Write the report somewhere else
ruly stats rails -o tokens.md

ruly stats writes stats.md (per-file token counts, per-recipe totals, orphaned files, circular requires: chains) to the rules directory unless -o is given. With no recipe source configured, it still writes the per-file counts and warns on stderr that recipe totals are skipped.

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

MCP servers are chosen per recipe with mcp_servers: (definitions come from ~/.config/ruly/mcp.json) and written to .mcp.json by ruly squash. For one-off servers, use Claude Code's claude mcp add.

Subagents (a recipe and model per subagent, MCP server propagation and the generated agent file format) are documented under Reference: see Subagents.

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 core

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

# Another recipe
ruly squash minimal

Available Recipes

Recipes depend on having access to rule files. The recommended setup is a recipes.yml at the root of your rules repository, declared under remotes: and mirrored with ruly squash --sync (see Sharing Recipes Across Machines). Alternatively, define recipes directly in ./.recipes.yml or ~/.config/ruly/recipes.yml.

  • qa — WorkAxle QA acceptance testing. Write and run Playwright specs in the automation-test-qa repo against dev.workaxle.com. Includes skills for running acceptance tests and syncing the QA repo.

Custom Recipes

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

# ~/.config/ruly/recipes.yml
---
recipes:
  # Complete development environment combining multiple sources
  my_company_core:
    description: Complete development environment with Ruby, testing, and workflow rules
    sources:
      # John's private rules repository
      - github: john/private-rules
        branch: main
        rules:
          - rules/commands/bug
          - rules/commands/pr
          - rules/bug
          - rules/commands.md
          - rules/core
          - rules/core/debugging
          - rules/pr
          - rules/ruby
          - rules/testing
          - rules/commands/testing
          - rules/commands/workflow

      # Company's shared rules repository
      - github: my_company/development-standards
        branch: main
        rules:
          - rules/commands/jira/details.md
          - rules/workflow
          - rules/jira

  # Local files from various projects
  development_local:
    description: Auto-generated from local sources
    files:
      - /Users/john/Projects/my_app/rules/ruby/common.md
      - /Users/john/Projects/my_app/rules/ruby/monads.md
      - /Users/john/Projects/my_app/rules/ruby/rspec.md
      - /Users/john/Projects/my_app/rules/ruby/sequel.md
      - /Users/john/Projects/my_app/rules/testing/common.md
      - /Users/john/Projects/my_app/rules/commands.md
      - /Users/john/Projects/my_app/rules/commands/bug/diagnose.md
      - /Users/john/Projects/my_app/rules/commands/bug/fix.md
      - /Users/john/Projects/my_app/rules/commands/pr/create.md

  # Simple recipe for specific context
  testing_only:
    description: Testing and QA rules
    files:
      - /Users/john/Projects/my_app/rules/testing/*.md
      - /Users/john/Projects/my_app/rules/commands/testing/*.md

Unknown or removed recipe keys print a warning on stderr and are ignored. A top-level tier: in ~/.config/ruly/recipes.yml or .recipes.yml (removed in 0.2.0) also warns and is ignored.

Recipe Keys: Skills, Commands, and Bins

Recipes support explicit keys for files that need special treatment. Files listed under files: are always squashed into the main output (CLAUDE.local.md) regardless of their path. To output files as skills, commands, or bins, use the dedicated keys:

recipes:
  my-recipe:
    description: "Example with explicit keys"
    files:
      # Regular rule files — squashed into CLAUDE.local.md
      - /path/to/rules/core.md
      - /path/to/rules/frameworks/ruby.md
    skills:
      # Output as .claude/skills/{name}/SKILL.md
      - /path/to/rules/skills/debugging.md
      - /path/to/rules/github/pr/skills/pr-review-loop.md
    commands:
      # Output as .claude/commands/{path}.md
      - /path/to/rules/github/pr/commands/create.md
      - /path/to/rules/comms/jira/commands/comment.md
    scripts:
      # Copied to .claude/scripts/ as executables
      - /path/to/rules/bin/deploy.sh

Key behavior:

Recipe key Output location What it does
files: CLAUDE.local.md Squashed into main output (always, regardless of path)
skills: .claude/skills/{name}/SKILL.md Creates individual skill files
commands: .claude/commands/{path}.md Creates slash command files
scripts: .claude/scripts/ Copies scripts as executables

All four keys support both individual file paths and directory paths. Directories are expanded:

  • skills: and commands: directories expand to all *.md files
  • scripts: directories expand to all *.sh files

Frontmatter skills: references in individual rule files still work independently. If a rule file declares skills: in its frontmatter, those referenced files are automatically resolved and output as SKILL.md files during squash, regardless of which recipe key they appear under.

Remote Sources:

  • Supports pulling rules directly from GitHub repositories
  • Automatically converts GitHub blob URLs to raw URLs
  • 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), files listed under the commands: recipe key are saved to .claude/commands/
  • For other agents (cursor, agents), command files are not written; -a agents lists them in its skipped-parts line
  • With -a claude-plugin, recipe commands go to the plugin's commands/ directory
  • Files in /commands/ paths under files: are treated as regular content (squashed into main output)

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

Recipe Inheritance (extends:)

Recipes can extend other recipes using the extends: key. The child recipe inherits all keys from the parent, with:

  • Array keys (files, skills, commands, scripts, sources, mcp_servers, omit_command_prefix): Merged via union — parent entries first, then child entries, deduplicated
  • Scalar keys (description, model): Child wins — parent value only used if child doesn't define it
  • Subagents: Merged by name — child entry overrides parent entry with same name
recipes:
  base:
    description: "Base development recipe"
    files:
      - rules/core.md
      - rules/common.md
    mcp_servers:
      - teams

  extended:
    extends: base
    description: "Extended recipe with extra tools"
    files:
      - rules/extra.md
    mcp_servers:
      - atlassian

After resolution, extended will have:

  • files: [rules/core.md, rules/common.md, rules/extra.md]
  • mcp_servers: [teams, atlassian]
  • description: "Extended recipe with extra tools"

Multi-level inheritance is supported (A extends B extends C). Circular references are detected and produce an error.

Context Isolation (isolate)

When running Claude Code in a subdirectory, it walks up the directory tree loading every CLAUDE.md and CLAUDE.local.md it finds. This can cause context bloat when worktrees or submodules are nested inside directories that have their own Claude instructions.

The isolate: true recipe option prevents this inheritance by populating claudeMdExcludes in .claude/settings.local.json with every parent CLAUDE.md and CLAUDE.local.md file found between the output directory and the filesystem root.

recipes:
  my-isolated-recipe:
    description: "Engineer with no parent context inheritance"
    isolate: true
    files:
      - /path/to/rules/core.md
      - /path/to/rules/frameworks/

After ruly squash my-isolated-recipe, the generated .claude/settings.local.json will contain:

{
  "claudeMdExcludes": [
    "/Users/you/agents/orchestrator/CLAUDE.local.md",
    "/Users/you/agents/orchestrator/workaxle-core/CLAUDE.md",
    "/Users/you/agents/orchestrator/workaxle-core/CLAUDE.local.md"
  ]
}

When to use:

  • Worktrees nested inside parent projects with large CLAUDE files
  • Submodules that should only use their own squashed rules
  • Any recipe where you want a clean, self-contained context

AGENTS.md Output

AGENTS.md is the cross-agent instruction file standard and the recommended cross-agent path for sharing a ruly recipe with agents other than Claude Code.

  • ruly squash RECIPE -a agents writes AGENTS.md; agents-md and agentsmd are aliases, and -o PATH writes elsewhere. There is no new command or recipe key.
  • The file starts with the header <!-- Generated by ruly from recipe: NAME — do not edit -->, followed by the same squashed rules CLAUDE.local.md gets (requires: resolved, frontmatter stripped), then the recipe's skills as plain sections under ## Skills. The Claude Code directives CLAUDE.local.md keeps in a rule's frontmatter (name:, description:, permissionMode:, allowed_tools:) are stripped too, unless you pass --front-matter.
  • Commands, subagents, hooks, mcp_servers and the model/isolate settings are Claude Code features, so they are skipped. Squash prints one line naming what it skipped (AGENTS.md target skips Claude-only parts: commands (2), subagents (1), ...).
  • Squash refuses to overwrite an AGENTS.md whose first line is not the ruly header (move it aside or pass -o PATH). The check runs before --clean/--deepclean, so a refused squash deletes nothing. ruly clean -a agents removes AGENTS.md only when it has that header and leaves .claude/, .mcp.json and CLAUDE.local.md alone; --deepclean still removes only Claude artifacts. Adding the header to a hand-written file hands that file to ruly. A UTF-8 BOM before the header (an editor re-save) is ignored.
  • -i/-I add AGENTS.md to .gitignore / .git/info/exclude. AGENTS.md is usually committed, so if the recipe pulls rules from a private repository, use -i or -I. New entries are merged into the existing # Ruly generated files section, so running -i for one target keeps the other target's entries (CLAUDE.local.md, .claude/commands/) ignored.
  • Recipe scripts: are copied to .claude/scripts/ for both targets, and AGENTS.md refers to them there. -i/-I also add each copied script (.claude/scripts/NAME). ruly clean -a agents keeps them; ruly clean --deepclean removes them.
  • Post-squash checks (such as ambiguous links) run over the whole AGENTS.md, inlined skills included.
  • -a cursor is unchanged.

Claude Code Plugin Output

ruly squash RECIPE -a claude-plugin writes the recipe as a Claude Code plugin directory that you load with claude --plugin-dir or share, instead of writing into the project's .claude/. The default output is unchanged. -o DIR picks the directory; the default is ruly-plugin-RECIPE/.

ruly-plugin-RECIPE/
├── .claude-plugin/plugin.json
├── skills/RECIPE-rules/SKILL.md   # the squashed rules
├── skills/<skill>/SKILL.md
├── commands/
├── agents/
├── hooks/hooks.json
├── scripts/
└── .mcp.json
  • Manifest: name is the recipe name (kebab-case recommended; claude plugin validate warns otherwise, and names Claude Code reserves, such as claude-*, are refused), version is the ruly version, description is the recipe description, author is git config user.name when set, and metadata.generator: ruly marks ruly's ownership.
  • Known limitation: version. version is always the ruly version, whatever the rules hold. Claude Code caches marketplace and git installs by version, so rules re-squashed under the same ruly version reach only --plugin-dir and local-path installs, which load in place. Before you publish updated rules, raise version in the generated plugin.json by hand (the next squash resets it).
  • Rules are not always-on. Plugins cannot carry always-on instructions: a plugin-root CLAUDE.md is not loaded (the docs say to ship instructions as a skill), a SessionStart hook's added context is capped at 10,000 characters, a forced plugin output style replaces the user's own and never reaches subagents, and a plugin agent setting replaces the whole system prompt. So the rules become the skill /RECIPE:RECIPE-rules, loaded when invoked, and squash prints a notice. For always-on rules keep using ruly squash RECIPE (CLAUDE.local.md). If you want a nudge, add your own SessionStart hook that tells Claude to invoke that skill; ruly does not generate one.
  • Skills and subagents: nested skill paths are flattened (skills/tdd/SKILL.md becomes skills/tdd/, git/commit becomes git-commit). Recipe and subagent skills are checked before they are written: a skill named RECIPE-rules, or one whose flattened name is not letters, digits, ., _ and - (or holds ..), is refused, and two skill files with the same flattened name get a warning (the last one wins). Subagent model: is kept. permissionMode, hooks and mcpServers are left out of plugin agents because Claude Code ignores them there; the recipe's hooks and MCP servers (subagent servers included) go to hooks/hooks.json and .mcp.json instead. Preloaded skills are listed as RECIPE:skill. Squash names what it left out, for example claude-plugin target skips: model, isolate, subagent permissionMode, subagent cwd hooks.
  • Scripts (the recipe's and its subagents') are copied to scripts/, and references in skills, commands, agents and hook commands are rewritten to ${CLAUDE_PLUGIN_ROOT}/scripts/.... In hook commands .claude/scripts/X, ./.claude/scripts/X and $CLAUDE_PROJECT_DIR/.claude/scripts/X (quoted or with braces) are rewritten; the result is double-quoted unless the reference already sits inside a quoted string (bash -c "...", sh -c '...'). Squash names any other .claude/scripts/ reference it leaves in a hook, such as ~/.claude/scripts/X.
  • MCP secrets: .mcp.json copies server definitions from ~/.config/ruly/mcp.json. Squash names (never prints) the servers with literal values that may be secrets: any env or headers value, args such as --token VALUE, --api-key=VALUE, KEY=VALUE or a token-shaped value, and a url with user:password@ or a credential query parameter. Replace those values with ${VAR} references before sharing the plugin.
  • Safety: squash refuses a directory ruly did not generate (no ruly metadata in .claude-plugin/plugin.json), the working directory, its parents and $HOME (compared after resolving symlinks, so a symlinked path or // is caught too), and a -o path starting with ~ (ruly does not expand it). A ruly-generated directory is replaced only when the whole build succeeds: the previous plugin is moved to a hidden .DIR.ruly-previous-* sibling during the build and put back if the build fails. Subagent names must be letters, digits, ., _ and - (no / or ..) for every target that writes subagents. ruly clean RECIPE -a claude-plugin removes only a ruly-generated plugin directory and never .claude/; --deepclean keeps its meaning. Adding the marker to a hand-made plugin.json hands that directory to ruly. -i/-I add the directory to .gitignore / .git/info/exclude.
  • Check and share: run claude plugin validate ruly-plugin-RECIPE. Ruly does not write a marketplace.json; publishing is up to you.

Commands

  • Squash (squash [RECIPE]): Combines all rule content into a single large file. Recipe is optional positional parameter. Supports fetching remote GitHub files. 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). Use --verbose or -v to show detailed per-file processing output (file paths, token counts, requires discovery). Default output shows only recipe, subagents, errors, and summary. Use --sync to mirror every remotes: entry (its recipes.yml plus all referenced rule files) into ~/.config/ruly/remotes/<owner>/<repo>/ before squashing. See Sharing Recipes Across Machines. Use -a agents to write AGENTS.md instead. See AGENTS.md Output. Use -a claude-plugin to write a Claude Code plugin directory instead. See Claude Code Plugin Output.

  • Stats (stats [RECIPE]): Writes stats.md with per-file token counts, per-recipe totals, orphaned files and circular requires: chains. Use -o to choose the output path.

  • Clean (clean [RECIPE]): Deletes output files created by the squash command. Recipe is optional. 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. ruly clean -a agents removes only a ruly-generated AGENTS.md. ruly clean RECIPE -a claude-plugin removes only a ruly-generated plugin directory.

  • Introspect (introspect RECIPE SOURCE...): Scans one or more local directories or GitHub repo URLs for markdown files and creates or updates the named recipe in ~/.config/ruly/recipes.yml (or the path given with -o). Options: -d/--description sets the recipe description, --dry-run prints the recipe YAML and writes nothing, and --relative writes repo-relative paths.

  • List Recipes (list-recipes): Shows all available recipes, which source in the lookup chain they came from (mirrored remote, ./.recipes.yml, or ~/.config/ruly/recipes.yml) and whether an overrides: block was applied. Accepts --sync like squash.

  • 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).

Available Ruly Commands

  • /recipe-from-project - Drafts a recipe from a project folder's current rules, skills, commands, subagents and MCP servers, and writes it to the rules repo's recipes.yml only after you approve the draft.
  • /ruly:compress - Analyze markdown rules to find redundancies and make them more DRY
  • /ruly:decompose - Decompose a markdown file into a directory using git mv (preserves history)
  • /run-acceptance-test - Takes acceptance criteria (direct text, Jira ticket WA-XXXX, or PR number PR:NNNN), reads page objects from automation-test-qa, writes a Playwright spec, runs it, and reports results.
  • /sync-qa-repo - Pulls latest from automation-test-qa, reports new/changed page objects, specs, and API helpers.

Drafting a Recipe From a Project

The skill is not installed with the gem. ruly squash fetches it from https://github.com/patrickclery/ruly/blob/main/skills/recipe-from-project.md, so any recipe that lists this URL needs the network at squash time and exits 1 offline.

There are two ways to run it:

  • A project already built from a recipe. Add the URL to that recipe's skills:, or add it under overrides: in ~/.config/ruly/recipes.yml for one machine, then squash as usual. The skill defaults to the current folder.
  • Any other project. Run ruly squash ruly-tools in an empty directory (add --sync the first time so the mirror has the recipe). Start Claude there with claude --add-dir <project> --add-dir <rules clone>, and pass the project path to the skill.

The ruly-tools recipe is defined in the rules repo's recipes.yml, so a machine that mirrors that repo gets it from ruly squash --sync. Ruly reads recipes: from ./.recipes.yml or ~/.config/ruly/recipes.yml only when no remote is mirrored, and overrides: cannot add a new recipe. Without a mirror, define it in one of those files:

recipes:
  ruly-tools:
    description: "Ruly authoring tools"
    skills:
      - https://github.com/patrickclery/ruly/blob/main/skills/recipe-from-project.md

Do not squash ruly-tools inside the project you want to scan. Squashing there overwrites CLAUDE.local.md and empties mcpServers in .mcp.json, even when the fetch fails, which destroys the files the skill reads.

Every match in the draft is labelled exact or inferred. Content that matches nothing in the rules repo is reported and left out. The skill shows the draft first, and once you approve it, writes and validates the recipe and leaves the change uncommitted.

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 core

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

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

# Generate AGENTS.md for agents that read the AGENTS.md standard
ruly squash rails -a agents

# Remove a ruly-generated AGENTS.md (a hand-written one is left alone)
ruly clean -a agents

# Package the rails recipe as a Claude Code plugin in ruly-plugin-rails/
ruly squash rails -a claude-plugin

# Load the generated plugin for one session
claude --plugin-dir ruly-plugin-rails

# Remove the ruly-generated plugin directory
ruly clean rails -a claude-plugin

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

# Mirror shared recipes from `remotes:` first, then squash from the mirror
ruly squash homelab --sync

# 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

# Preview a 'ruby' recipe built from a rules directory (writes nothing)
ruly introspect ruby rules/ruby/ --dry-run

# Write it with repo-relative paths and a description
ruly introspect ruby rules/ruby/ --relative -d "Ruby rules"

# List what recipes are available
ruly list-recipes

# Show version
ruly version

# View help
ruly help
ruly help squash
ruly help clean
ruly help introspect

# Per-command help flags work too
ruly squash --help
ruly stats -h

Ruly will automatically:

  • Load recipes from the first of: mirrored remotes (~/.config/ruly/remotes/), ./.recipes.yml, ~/.config/ruly/recipes.yml
  • Expand a directory entry in a recipe to every .md file inside it
  • Create parent directories if using custom output paths
  • Display file count and output size
  • Show which recipe was used in the output

Reference

This section holds detailed reference for features summarized above.

Subagents

Subagents allow you to generate specialized agent files that Claude can dispatch to for specific tasks. Each subagent is a self-contained agent with its own rules, commands, and MCP server access.

Defining Subagents in Recipes

Add a subagents array to any recipe. Each subagent references another recipe:

recipes:
  # Main recipe that spawns subagents
  full:
    description: "Complete development environment"
    files:
      - /path/to/rules/core.md
    subagents:
      - name: bug_investigator
        recipe: bug
      - name: test_runner
        recipe: testing
      - name: pr_manager
        recipe: pr

  # Recipes used by subagents
  bug:
    description: "Bug investigation and debugging"
    files:
      - /path/to/rules/bug/
      - /path/to/rules/debugging.md
    mcp_servers:
      - teams

  testing:
    description: "Testing and QA workflows"
    files:
      - /path/to/rules/testing/
    mcp_servers:
      - playwright

  pr:
    description: "PR management"
    files:
      - /path/to/rules/github/pr/

How It Works

When you run ruly squash full:

  1. MCP servers collected: Recursively collects mcp_servers from all subagent recipes
  2. .mcp.json written: Parent's .mcp.json includes all collected servers (deduplicated)
  3. Main rules generated: CLAUDE.local.md with the main recipe content
  4. Agent files created: .claude/agents/{name}.md for each subagent
  5. Commands organized: .claude/commands/{agent_name}/ for agent-specific commands
your-project/
├── CLAUDE.local.md              # Main rules (from 'full' recipe)
├── .mcp.json                    # MCP servers (parent + all subagent servers)
├── .ruly/
│   └── bin/                     # Bin files (from scripts: key)
└── .claude/
    ├── agents/
    │   ├── bug_investigator.md  # Squashed 'bug' recipe
    │   ├── test_runner.md       # Squashed 'testing' recipe
    │   └── pr_manager.md        # Squashed 'pr' recipe
    ├── commands/
    │   ├── bug_investigator/    # Commands for bug agent
    │   ├── test_runner/         # Commands for testing agent
    │   └── pr_manager/          # Commands for PR agent
    └── skills/                  # Skills (from skills: key)
        └── debugging/
            └── SKILL.md

MCP Server Propagation

Claude Code subagents inherit the parent session's MCP configuration — they cannot have independent MCP servers. Ruly handles this automatically: during ruly squash, MCP servers from all subagent recipes (recursively, including nested subagents) are collected and merged into the parent's .mcp.json.

For example, given this recipe configuration:

recipes:
  core:
    description: "Main orchestrator"
    files:
      - /path/to/rules/core.md
    # Note: no mcp_servers defined here
    subagents:
      - name: comms
        recipe: comms
      - name: feature
        recipe: feature

  comms:
    description: "Communication agent"
    files:
      - /path/to/rules/comms/
    mcp_servers:
      - teams

  feature:
    description: "Feature development"
    files:
      - /path/to/rules/feature/
    mcp_servers:
      - Ref

Running ruly squash core produces a .mcp.json containing teams and Ref — all propagated from the subagent recipes — even though core itself defines no MCP servers. The console output shows which servers were propagated:

🔌 Propagated MCP servers from subagents: teams, Ref
🔌 Updated .mcp.json with MCP servers

This propagation is recursive: if comms itself has subagents with additional MCP servers, those are collected too. Circular references are handled safely.

Agent File Format

Generated agent files have YAML frontmatter that Claude understands:

---
name: bug_investigator
description: Bug investigation and debugging
tools: inherit
model: haiku                # Set via subagent or recipe config (default: inherit)
# Auto-generated from recipe: bug
# Do not edit manually - regenerate using 'ruly squash full'
---

# Bug Investigator

Bug investigation and debugging

## Recipe Content

[squashed content from bug recipe]

## MCP Servers

This subagent has access to the following MCP servers:
- teams

---
*Last generated: 2026-02-04 12:30:00*
*Source recipe: bug*

Model Specification

Control which Claude model each subagent uses. Route lightweight tasks (context fetching, DMs) to faster/cheaper models while keeping complex tasks on the most capable model.

Subagent-Level Model

Specify model directly on a subagent entry:

subagents:
  - name: context_grabber
    recipe: context-grabber
    model: haiku          # Fast, cheap — just fetching data
  - name: core_engineer
    recipe: core-engineer
    model: opus           # Most capable — complex implementation
  - name: comms
    recipe: comms         # No model — inherits from recipe or defaults to 'inherit'
Recipe-Level Default Model

Set a default model for all subagents in a recipe:

recipes:
  core:
    description: "Main orchestrator"
    model: sonnet         # Default for all subagents
    files:
      - /path/to/rules/core.md
    subagents:
      - name: fast_agent
        recipe: fast-tasks
        model: haiku      # Overrides recipe default
      - name: smart_agent
        recipe: complex-tasks
                           # Uses recipe default (sonnet)
Inheritance Chain

Model is resolved in this order:

  1. Subagent model — if specified on the subagent entry
  2. Parent recipe model — if set on the recipe containing the subagents
  3. inherit — the default (inherits from the calling session)

Valid values: haiku, sonnet, opus, or inherit.

Note: Skills can also specify model in their frontmatter — this is already supported and preserved during squash.

Directory Structure for Subagents

Subagent instruction files should be organized in agents/ directories:

rules/
└── comms/
    ├── ms-teams/
    │   ├── common.md                     # Shared patterns (loaded by both)
    │   ├── commands/
    │   │   └── dm.md                     # User command: /ms-teams:dm
    │   └── agents/
    │       └── ms-teams-dm.md            # Subagent: dispatched on "send it"

Key distinction:

  • commands/ - User-invocable via /command-name
  • agents/ - Dispatched programmatically by the orchestrator

When to Use Subagents

Use Case Benefit
Specialized tasks Each agent has focused rules for its domain
Parallel work Dispatch multiple agents for independent tasks
Context isolation Agents only load rules they need
MCP server propagation Subagent MCP servers are automatically propagated to parent

Example: Development Workflow

recipes:
  workaxle:
    description: "Main WorkAxle development"
    files:
      - /path/to/rules/core.md
    subagents:
      - name: comms
        recipe: comms        # Jira, Teams, GitHub communications
      - name: merger
        recipe: merger       # PR merging operations
      - name: dashboard
        recipe: dashboard    # PR status dashboard

  comms:
    description: "Communication via Jira, Teams, GitHub"
    files:
      - /path/to/rules/comms/
    mcp_servers:
      - teams
      - atlassian

  merger:
    description: "PR merging commands"
    files:
      - /path/to/rules/github/pr/
    mcp_servers: []

  dashboard:
    description: "Open PRs dashboard"
    files:
      - /path/to/rules/dashboard.md
    mcp_servers: []

Then Claude can dispatch to these agents:

User: "Update all my PRs with latest main"
Claude: [Dispatches to merger agent which has PR merge rules]

User: "Send a Teams message about WA-1234"
Claude: [Dispatches to comms agent which has Teams MCP access]

User: "Show me my open PRs"
Claude: [Dispatches to dashboard agent]

Example Recipes

Multi-Repo Orchestrator

An orchestrator that manages multiple repositories, each with their own CLAUDE.md and hooks. Subagents dispatched into each repo automatically pick up the repo's configuration.

Directory Layout

~/agents/orchestrator/
├── CLAUDE.local.md              # Generated orchestrator rules
├── .mcp.json                    # MCP servers (collected from all subagents)
├── .claude/
│   ├── agents/
│   │   ├── backend_engineer.md  # Has acme-api's CLAUDE.md + hooks baked in
│   │   ├── frontend_engineer.md # Has acme-web's CLAUDE.md + rules + hooks baked in
│   │   └── comms.md             # Pure ruly recipe (no repo append)
│   ├── scripts/
│   │   └── worktree-create.sh   # Propagated to all submodule dirs
│   └── settings.local.json      # Parent hooks (WorktreeCreate)
├── acme-api/                    # Backend repo (git submodule)
│   ├── CLAUDE.md                # 1800-line repo-specific guidance
│   └── .claude/
│       └── settings.json        # No custom hooks
├── acme-web/                    # Frontend repo (git submodule)
│   ├── CLAUDE.md                # 500-line repo-specific guidance
│   └── .claude/
│       ├── rules/
│       │   └── command-timeouts.md  # Repo-specific rules
│       ├── hooks/
│       │   └── eslint-fix.sh        # Repo-specific hook script
│       └── settings.json            # PostToolUse hook for ESLint

Recipe Configuration

recipes:
  orchestrator:
    description: "Multi-repo dispatcher"
    hooks:
      WorktreeCreate:
        - hooks:
            - type: command
              command: ".claude/scripts/worktree-create.sh"
              timeout: 120
    files:
      - /path/to/rules/orchestrator/dispatch.md
    scripts:
      - /path/to/rules/orchestrator/bin/worktree-create.sh
    subagents:
      # Backend — reads acme-api's CLAUDE.md and hooks
      - name: backend_engineer
        recipe: backend-engineer
        cwd: acme-api
        append: true
      # Frontend — reads acme-web's CLAUDE.md, rules, and hooks
      - name: frontend_engineer
        recipe: frontend-engineer
        cwd: acme-web
        append: true
      # Comms — pure ruly recipe, no repo to append
      - name: comms
        recipe: comms

What append: true Does

When a subagent has both cwd: and append: true, ruly reads from the repo directory during squash:

Source What's read Where it goes
{cwd}/CLAUDE.md Repo's main guidance doc Appended to agent body as ## Repository Context
{cwd}/.claude/rules/*.md Repo-specific rules Appended to agent body as ## Repository Rules
{cwd}/.claude/settings.json Repo's hooks Merged into agent frontmatter hooks:

Each subagent gets only its own repo's hooks — no cross-contamination between subagents.

Generated Agent Frontmatter

The frontend_engineer subagent gets the parent's WorktreeCreate hook merged with the repo's PostToolUse hook:

---
name: frontend_engineer
description: Frontend feature development - React/TypeScript with TDD
tools: Bash, Read, Write, Edit, Glob, Grep
model: inherit
mcpServers: "[playwright, Ref]"
permissionMode: bypassPermissions
hooks:
  WorktreeCreate:
  - hooks:
    - type: command
      command: ".claude/scripts/worktree-create.sh"
      timeout: 120
  PostToolUse:
  - matcher: Edit|Write
    hooks:
    - type: command
      command: ".claude/hooks/eslint-fix.sh"
# Auto-generated from recipe: frontend-engineer
# Do not edit manually - regenerate using 'ruly squash orchestrator'
---

The backend_engineer subagent only gets the parent's hook (since acme-api has no custom hooks):

---
name: backend_engineer
description: Backend feature development - Ruby/Sequel with TDD
tools: Bash, Read, Write, Edit, Glob, Grep
model: inherit
hooks:
  WorktreeCreate:
  - hooks:
    - type: command
      command: ".claude/scripts/worktree-create.sh"
      timeout: 120
# Auto-generated from recipe: backend-engineer
# Do not edit manually - regenerate using 'ruly squash orchestrator'
---

Generated Agent Body (append sections)

After the recipe's squashed content, each subagent with append: true gets additional sections:

## Recipe Content

[squashed content from frontend-engineer recipe]

---

## Repository Context

# CLAUDE.md

This file provides guidance for the acme-web frontend application...

## Development

- Use `yarn dev` for development server
- Use `yarn typecheck` for type checking
- Use `yarn lint --fix` for linting

---

## Repository Rules

## Command Timeouts

### Rule
Always use a **5-minute timeout** (300000ms) for:
- `yarn typecheck`
- `yarn lint`

---
*Last generated: 2026-03-06 10:43:25*
*Source recipe: frontend-engineer*

With vs Without append

Feature append: true No append
Recipe content Included Included
Repo CLAUDE.md Baked into agent body Not visible to subagent
Repo .claude/rules/ Baked into agent body Not visible to subagent
Repo hooks (settings.json) Merged into frontmatter Not applied
Parent hooks Always included Always included
MCP servers From recipe (propagated to parent) From recipe (propagated to parent)

Note: Claude Code subagents do not automatically discover CLAUDE.md, .claude/rules/, or .claude/settings.json from their CWD. The append feature exists specifically to bridge this gap by baking repo configuration into the agent file at squash time.


🔧 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:

  • Use ruly clean --dry-run to preview what will be deleted
  • Specify agent with --agent option if not using Claude
  • Ensure you're using the correct recipe name if specified

About

CLI tool for managing AI assistant rules and configurations

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages