@intellectronica/ruler 0.3.40 → 0.3.41

package/README.md

@@ -245,7 +245,7 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 | `--no-backup`                  | Disable creation of `.bak` backup files.                               |
 | `--skills`                     | Enable skills support (experimental, default: enabled).                |
 | `--no-skills`                  | Disable skills support.                                                |
-| `--subagents`                  | Enable subagents support (experimental, default: enabled).             |
+| `--subagents`                  | Enable subagents support (experimental, default: disabled).            |
 | `--no-subagents`               | Disable subagents support.                                             |
 | `--dry-run`                    | Preview changes without writing files.                                 |
 | `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                |
@@ -740,18 +740,18 @@ Ruler can distribute named, delegatable **subagents** from a single source of tr
 
 For agents with a native subagent primitive, Ruler writes one file per subagent into the target directory:
 
-| Agent             | Target location                | Format |
-| ----------------- | ------------------------------ | ------ |
-| Claude Code       | `.claude/agents/<name>.md`     | Markdown + YAML frontmatter |
-| Cursor            | `.cursor/agents/<name>.md`     | Markdown + YAML frontmatter |
-| OpenAI Codex CLI  | `.codex/agents/<name>.toml`    | TOML (one self-contained file per agent) |
-| GitHub Copilot    | `.github/agents/<name>.md`     | Markdown + YAML frontmatter |
+| Agent            | Target location                      | Format                                   |
+| ---------------- | ------------------------------------ | ---------------------------------------- |
+| Claude Code      | `.claude/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
+| Cursor           | `.cursor/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
+| OpenAI Codex CLI | `.codex/agents/<relative-path>.toml` | TOML (one self-contained file per agent) |
+| GitHub Copilot   | `.github/agents/<relative-path>.md`  | Markdown + YAML frontmatter              |
 
 Other agents (Windsurf, RooCode, Aider, Gemini CLI, …) do not yet have a comparable native subagent primitive and are skipped with a warning. Subagent propagation will be added when those agents ship a comparable file format.
 
 ### Source Format
 
-Author each subagent as `.ruler/agents/<name>.md`:
+Author each subagent as `.ruler/agents/<name>.md` (nested folders are supported and preserved in outputs):
 
 ```markdown
 ---
@@ -772,19 +772,19 @@ a structured verdict.
 
 **Required frontmatter fields:**
 
-| Field         | Type   | Notes                                                 |
-| ------------- | ------ | ----------------------------------------------------- |
+| Field         | Type   | Notes                                                                      |
+| ------------- | ------ | -------------------------------------------------------------------------- |
 | `name`        | string | Must match the filename stem (`code-reviewer.md` → `name: code-reviewer`). |
-| `description` | string | When the parent agent should delegate to this subagent. |
+| `description` | string | When the parent agent should delegate to this subagent.                    |
 
 **Optional frontmatter fields:**
 
-| Field           | Type             | Used by                                          | Default behavior                              |
-| --------------- | ---------------- | ------------------------------------------------ | --------------------------------------------- |
-| `tools`         | string[]         | Claude (verbatim), Copilot (mapped to aliases)   | Cursor / Codex ignore; omitted if absent.     |
-| `model`         | string           | All four targets                                 | Cursor defaults to `inherit`; others omit.    |
-| `readonly`      | boolean          | Cursor (verbatim), Codex (`sandbox_mode`), Copilot (`disable-model-invocation`) | Defaults to `false` for Cursor; omitted otherwise. |
-| `is_background` | boolean          | Cursor only                                      | Defaults to `false` for Cursor.               |
+| Field           | Type     | Used by                                                                         | Default behavior                                   |
+| --------------- | -------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `tools`         | string[] | Claude (verbatim), Copilot (mapped to aliases)                                  | Cursor / Codex ignore; omitted if absent.          |
+| `model`         | string   | All four targets                                                                | Cursor defaults to `inherit`; others omit.         |
+| `readonly`      | boolean  | Cursor (verbatim), Codex (`sandbox_mode`), Copilot (`disable-model-invocation`) | Defaults to `false` for Cursor; omitted otherwise. |
+| `is_background` | boolean  | Cursor only                                                                     | Defaults to `false` for Cursor.                    |
 
 For GitHub Copilot, source `tools` (Claude vocabulary: `Read`, `Grep`, `Bash`, …) are translated to Copilot's aliases (`read`, `search`, `execute`, …). Tools that do not have a Copilot equivalent are dropped silently on a normal apply; pass `--verbose` (or use `--dry-run` to preview) to see which tools were dropped.
 
@@ -801,6 +801,7 @@ ruler apply --subagents   # enable subagent propagation for one run
 [agents]
 enabled = true
 # include_in_rules = true  # also append .ruler/agents/*.md into top-level CLAUDE.md / AGENTS.md (default: false)
+# cleanup_orphaned = true   # allow ruler to delete stale native subagent dirs (default: false)
 ```
 
 > **Note:** the previous release used `[subagents]` for these keys. `[subagents]` is still honored as a fallback with a deprecation warning, and will be removed in a future release. Please migrate to `[agents]`.
@@ -837,7 +838,7 @@ Use `--no-gitignore` to opt out.
 
 ### Cleanup
 
-Subagent propagation does **not** currently have explicit `ruler revert` support. To remove generated subagent directories, set `[agents] enabled = false` (or pass `--no-subagents`) and run `ruler apply` once. Cleanup will run for all four targets even if no source `.ruler/agents/` directory exists.
+Subagent propagation does **not** currently have explicit `ruler revert` support. By default, `ruler apply` is non-destructive and leaves existing native subagent directories untouched when subagents are disabled or missing. To allow automatic cleanup of stale generated directories, set `[agents] cleanup_orphaned = true`, then disable subagents (`[agents] enabled = false` or `--no-subagents`) and run `ruler apply`.
 
 ### Example Workflow
 
@@ -870,7 +871,7 @@ ruler apply
 
 ### Limitations
 
-- **No explicit revert command.** Cleanup happens via `[agents] enabled = false` on a subsequent `apply`.
+- **No explicit revert command.** Optional cleanup is available via `[agents] cleanup_orphaned = true` and a subsequent `apply`.
 - **Atomic replace, not merge.** Ruler regenerates each agent's subagent directory from the source on every apply. Manual edits to generated files will be overwritten.
 - **No support yet for agents without a native subagent primitive.** Windsurf, RooCode, Aider, Gemini CLI, and others are skipped with a warning. Propagation will be added when those agents ship a comparable file format.
 

package/dist/cli/commands.js

@@ -80,7 +80,7 @@ function run() {
         })
             .option('subagents', {
             type: 'boolean',
-            description: 'Enable/disable subagents support (experimental, default: enabled)',
+            description: 'Enable/disable subagents support (experimental, default: disabled)',
         });
     }, handlers_1.applyHandler)
         .command('init', 'Scaffold a .ruler directory with default files', (y) => {

package/dist/cli/handlers.js

@@ -114,7 +114,7 @@ async function applyHandler(argv) {
     else {
         skillsEnabled = undefined; // Let config/default decide
     }
-    // Determine subagents preference: CLI > TOML > Default (enabled)
+    // Determine subagents preference: CLI > TOML > Default (disabled)
     let subagentsEnabled;
     if (argv.subagents !== undefined) {
         subagentsEnabled = argv.subagents;

package/dist/core/ConfigLoader.js

@@ -76,13 +76,18 @@ const agentConfigSchema = zod_1.z
 //   - one nested table per coding-agent integration (`[agents.claude]`, etc.)
 // Reserved keys are validated by the object shape; everything else falls
 // through `catchall` and is treated as a per-agent config record.
-const SUBAGENT_RESERVED_KEYS = new Set(['enabled', 'include_in_rules']);
+const SUBAGENT_RESERVED_KEYS = new Set([
+    'enabled',
+    'include_in_rules',
+    'cleanup_orphaned',
+]);
 const rulerConfigSchema = zod_1.z.object({
     default_agents: zod_1.z.array(zod_1.z.string()).optional(),
     agents: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
         include_in_rules: zod_1.z.boolean().optional(),
+        cleanup_orphaned: zod_1.z.boolean().optional(),
     })
         .catchall(agentConfigSchema)
         .optional(),
@@ -111,6 +116,7 @@ const rulerConfigSchema = zod_1.z.object({
         .object({
         enabled: zod_1.z.boolean().optional(),
         include_in_rules: zod_1.z.boolean().optional(),
+        cleanup_orphaned: zod_1.z.boolean().optional(),
     })
         .optional(),
     nested: zod_1.z.boolean().optional(),
@@ -272,7 +278,8 @@ async function loadConfig(options) {
         ? raw.subagents
         : {};
     const legacyHasContent = typeof rawLegacySubagentsSection.enabled === 'boolean' ||
-        typeof rawLegacySubagentsSection.include_in_rules === 'boolean';
+        typeof rawLegacySubagentsSection.include_in_rules === 'boolean' ||
+        typeof rawLegacySubagentsSection.cleanup_orphaned === 'boolean';
     if (legacyHasContent) {
         warnLegacySubagentsSection();
     }
@@ -291,6 +298,14 @@ async function loadConfig(options) {
         subagentsConfig.include_in_rules =
             rawLegacySubagentsSection.include_in_rules;
     }
+    if (typeof agentsSection.cleanup_orphaned === 'boolean') {
+        subagentsConfig.cleanup_orphaned =
+            agentsSection.cleanup_orphaned;
+    }
+    else if (typeof rawLegacySubagentsSection.cleanup_orphaned === 'boolean') {
+        subagentsConfig.cleanup_orphaned =
+            rawLegacySubagentsSection.cleanup_orphaned;
+    }
     const nestedDefined = typeof raw.nested === 'boolean';
     const nested = nestedDefined ? raw.nested : false;
     return {

package/dist/core/SubagentsProcessor.js

@@ -62,16 +62,13 @@ async function discoverSubagents(projectRoot) {
     catch {
         return { subagents: [], warnings: [] };
     }
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    const mdFiles = entries
-        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-        .map((entry) => path.join(dir, entry.name))
-        .sort();
+    const mdFiles = await listMarkdownFilesRecursive(dir);
     const subagents = [];
     const warnings = [];
     for (const filePath of mdFiles) {
         const info = await (0, SubagentsUtils_1.loadSubagentFile)(filePath);
         if (info.valid) {
+            info.sourceRelativePath = path.relative(dir, filePath);
             subagents.push(info);
         }
         else if (info.error) {
@@ -80,6 +77,22 @@ async function discoverSubagents(projectRoot) {
     }
     return { subagents, warnings };
 }
+async function listMarkdownFilesRecursive(dir) {
+    const results = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = await listMarkdownFilesRecursive(fullPath);
+            results.push(...nested);
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+            results.push(fullPath);
+        }
+    }
+    return results.sort();
+}
 const SUBAGENT_TARGET_TO_IDENTIFIERS = new Map([
     ['claude', ['claude']],
     ['cursor', ['cursor']],
@@ -167,7 +180,9 @@ async function writeAgentsDirectoryAtomic(targetDir, files) {
     await fs.mkdir(tempDir, { recursive: true });
     try {
         for (const { name, content } of files) {
-            await fs.writeFile(path.join(tempDir, name), content, 'utf8');
+            const outputPath = path.join(tempDir, name);
+            await fs.mkdir(path.dirname(outputPath), { recursive: true });
+            await fs.writeFile(outputPath, content, 'utf8');
         }
         try {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -187,6 +202,19 @@ async function writeAgentsDirectoryAtomic(targetDir, files) {
         throw error;
     }
 }
+function getSourceRelativeMdPath(sub) {
+    const fromSource = sub.sourceRelativePath;
+    if (typeof fromSource === 'string' &&
+        fromSource.length > 0 &&
+        !path.isAbsolute(fromSource) &&
+        !fromSource.startsWith('..')) {
+        return fromSource;
+    }
+    return `${sub.name}.md`;
+}
+function withExtension(filePath, ext) {
+    return filePath.replace(/\.md$/i, ext);
+}
 function buildClaudeFile(sub) {
     const fm = sub.frontmatter;
     const meta = {
@@ -276,10 +304,10 @@ async function propagateSubagentsForClaude(projectRoot, subagents, options) {
         return [];
     const targetDir = path.join(projectRoot, constants_1.CLAUDE_SUBAGENTS_PATH);
     if (options.dryRun) {
-        return subagents.map((s) => `Write ${path.join(constants_1.CLAUDE_SUBAGENTS_PATH, `${s.name}.md`)}`);
+        return subagents.map((s) => `Write ${path.join(constants_1.CLAUDE_SUBAGENTS_PATH, getSourceRelativeMdPath(s))}`);
     }
     const files = subagents.map((s) => ({
-        name: `${s.name}.md`,
+        name: getSourceRelativeMdPath(s),
         content: buildClaudeFile(s),
     }));
     await writeAgentsDirectoryAtomic(targetDir, files);
@@ -290,10 +318,10 @@ async function propagateSubagentsForCursor(projectRoot, subagents, options) {
         return [];
     const targetDir = path.join(projectRoot, constants_1.CURSOR_SUBAGENTS_PATH);
     if (options.dryRun) {
-        return subagents.map((s) => `Write ${path.join(constants_1.CURSOR_SUBAGENTS_PATH, `${s.name}.md`)}`);
+        return subagents.map((s) => `Write ${path.join(constants_1.CURSOR_SUBAGENTS_PATH, getSourceRelativeMdPath(s))}`);
     }
     const files = subagents.map((s) => ({
-        name: `${s.name}.md`,
+        name: getSourceRelativeMdPath(s),
         content: buildCursorFile(s),
     }));
     await writeAgentsDirectoryAtomic(targetDir, files);
@@ -304,10 +332,10 @@ async function propagateSubagentsForCodex(projectRoot, subagents, options) {
         return [];
     const targetDir = path.join(projectRoot, constants_1.CODEX_SUBAGENTS_PATH);
     if (options.dryRun) {
-        return subagents.map((s) => `Write ${path.join(constants_1.CODEX_SUBAGENTS_PATH, `${s.name}.toml`)}`);
+        return subagents.map((s) => `Write ${path.join(constants_1.CODEX_SUBAGENTS_PATH, withExtension(getSourceRelativeMdPath(s), '.toml'))}`);
     }
     const files = subagents.map((s) => ({
-        name: `${s.name}.toml`,
+        name: withExtension(getSourceRelativeMdPath(s), '.toml'),
         content: buildCodexFile(s),
     }));
     await writeAgentsDirectoryAtomic(targetDir, files);
@@ -325,12 +353,12 @@ async function propagateSubagentsForCopilot(projectRoot, subagents, options) {
             // emits when dryRun is true so users previewing a change can see
             // which tools would be dropped before it actually happens.
             buildCopilotFile(s, true, verbose);
-            planLines.push(`Write ${path.join(constants_1.COPILOT_SUBAGENTS_PATH, `${s.name}.md`)}`);
+            planLines.push(`Write ${path.join(constants_1.COPILOT_SUBAGENTS_PATH, getSourceRelativeMdPath(s))}`);
         }
         return planLines;
     }
     const files = subagents.map((s) => ({
-        name: `${s.name}.md`,
+        name: getSourceRelativeMdPath(s),
         content: buildCopilotFile(s, false, verbose).content,
     }));
     await writeAgentsDirectoryAtomic(targetDir, files);
@@ -363,10 +391,24 @@ async function cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose) {
 /* ------------------------------------------------------------------ */
 /* Orchestrator                                                        */
 /* ------------------------------------------------------------------ */
-async function propagateSubagents(projectRoot, agents, subagentsEnabled, verbose, dryRun) {
-    if (!subagentsEnabled) {
-        (0, constants_1.logVerboseInfo)('Subagents support disabled, cleaning up subagent directories', verbose, dryRun);
+async function propagateSubagents(projectRoot, agents, subagentsEnabled, cleanupOrphaned, verbose, dryRun) {
+    const maybeCleanupAllSubagentsDirectories = async () => {
+        if (!cleanupOrphaned) {
+            (0, constants_1.logVerboseInfo)('Subagent cleanup skipped (set [agents] cleanup_orphaned = true to enable directory cleanup)', verbose, dryRun);
+            return;
+        }
         await cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose);
+    };
+    const maybeCleanupSubagentsDir = async (relPath) => {
+        if (!cleanupOrphaned)
+            return;
+        await cleanupSubagentsDir(projectRoot, relPath, dryRun, verbose);
+    };
+    if (!subagentsEnabled) {
+        (0, constants_1.logVerboseInfo)(cleanupOrphaned
+            ? 'Subagents support disabled, cleaning up subagent directories'
+            : 'Subagents support disabled, leaving existing subagent directories unchanged', verbose, dryRun);
+        await maybeCleanupAllSubagentsDirectories();
         return;
     }
     const sourceDir = path.join(projectRoot, constants_1.RULER_SUBAGENTS_PATH);
@@ -374,16 +416,20 @@ async function propagateSubagents(projectRoot, agents, subagentsEnabled, verbose
         await fs.access(sourceDir);
     }
     catch {
-        (0, constants_1.logVerboseInfo)('No .ruler/agents directory found, cleaning up any stale managed subagent directories', verbose, dryRun);
-        await cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose);
+        (0, constants_1.logVerboseInfo)(cleanupOrphaned
+            ? 'No .ruler/agents directory found, cleaning up any stale managed subagent directories'
+            : 'No .ruler/agents directory found; leaving existing subagent directories unchanged', verbose, dryRun);
+        await maybeCleanupAllSubagentsDirectories();
         return;
     }
     const { subagents, warnings } = await discoverSubagents(projectRoot);
     for (const w of warnings)
         (0, constants_1.logWarn)(w, dryRun);
     if (subagents.length === 0) {
-        (0, constants_1.logVerboseInfo)('No valid subagents found in .ruler/agents; cleaning up any stale managed subagent directories', verbose, dryRun);
-        await cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose);
+        (0, constants_1.logVerboseInfo)(cleanupOrphaned
+            ? 'No valid subagents found in .ruler/agents; cleaning up any stale managed subagent directories'
+            : 'No valid subagents found in .ruler/agents; leaving existing subagent directories unchanged', verbose, dryRun);
+        await maybeCleanupAllSubagentsDirectories();
         return;
     }
     (0, constants_1.logVerboseInfo)(`Discovered ${subagents.length} subagent(s)`, verbose, dryRun);
@@ -401,7 +447,7 @@ async function propagateSubagents(projectRoot, agents, subagentsEnabled, verbose
     const allTargets = ['claude', 'cursor', 'codex', 'copilot'];
     for (const target of allTargets) {
         if (!targets.has(target)) {
-            await cleanupSubagentsDir(projectRoot, SUBAGENT_TARGET_PATHS[target], dryRun, verbose);
+            await maybeCleanupSubagentsDir(SUBAGENT_TARGET_PATHS[target]);
         }
     }
     if (supporting.length === 0) {

package/dist/lib.js

@@ -70,6 +70,9 @@ function resolveSubagentsEnabled(cliFlag, configSetting) {
             ? configSetting
             : false; // default to disabled — see spec: subagents must opt in
 }
+function resolveSubagentsCleanupOrphaned(configSetting) {
+    return configSetting === true;
+}
 /**
  * Applies ruler configurations for all supported AI agents.
  * @param projectRoot Root directory of the project
@@ -119,12 +122,13 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         }
         // Propagate subagents (mirrors skills handling for nested mode).
         const subagentsEnabledResolved = resolveSubagentsEnabled(subagentsEnabled, rootConfig.subagents?.enabled);
+        const subagentsCleanupOrphaned = resolveSubagentsCleanupOrphaned(rootConfig.subagents?.cleanup_orphaned);
         {
             const { propagateSubagents } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
             for (const configEntry of hierarchicalConfigs) {
                 const nestedRoot = path.dirname(configEntry.rulerDir);
                 (0, constants_1.logVerbose)(`Propagating subagents for nested directory: ${nestedRoot}`, verbose);
-                await propagateSubagents(nestedRoot, selectedAgents, subagentsEnabledResolved, verbose, dryRun);
+                await propagateSubagents(nestedRoot, selectedAgents, subagentsEnabledResolved, subagentsCleanupOrphaned, verbose, dryRun);
             }
         }
         generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
@@ -146,9 +150,10 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         }
         // Propagate subagents (mirrors skills handling).
         const subagentsEnabledResolvedSingle = resolveSubagentsEnabled(subagentsEnabled, singleConfig.config.subagents?.enabled);
+        const subagentsCleanupOrphanedSingle = resolveSubagentsCleanupOrphaned(singleConfig.config.subagents?.cleanup_orphaned);
         {
             const { propagateSubagents } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
-            await propagateSubagents(projectRoot, selectedAgents, subagentsEnabledResolvedSingle, verbose, dryRun);
+            await propagateSubagents(projectRoot, selectedAgents, subagentsEnabledResolvedSingle, subagentsCleanupOrphanedSingle, verbose, dryRun);
         }
         generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.40",
+  "version": "0.3.41",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {
@@ -58,6 +58,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "jest": "^29.7.0",
+    "jest-util": "^29.7.0",
     "prettier": "^3.6.2",
     "ts-jest": "^29.4.5",
     "typescript": "^5.9.3",