@intellectronica/ruler 0.3.39 → 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,37 +772,43 @@ 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.
 
 ### Configuration
 
-Subagents are enabled by default. Toggle them via CLI flag or `ruler.toml`:
+Subagent propagation is **disabled by default**. Opt in via CLI flag or `ruler.toml`:
 
 ```bash
-ruler apply --no-subagents   # disable subagent propagation for one run
+ruler apply --subagents   # enable subagent propagation for one run
 ```
 
 ```toml
 # .ruler/ruler.toml
-[subagents]
-enabled = false
+[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)
 ```
 
-CLI flags take precedence over `ruler.toml`, which takes precedence over the default (enabled).
+> **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]`.
+
+`[agents] enabled` controls only native subagent propagation from `.ruler/agents/`. It is independent from `[agents.<name>] enabled` (which toggles per-coding-agent output like `CLAUDE.md` / `AGENTS.md`).
+
+CLI flags take precedence over `ruler.toml`, which takes precedence over the default (disabled).
 
 ### Validation
 
@@ -832,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 `[subagents] 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
 
@@ -850,10 +856,13 @@ readonly: true
 You review code changes for quality.
 EOF
 
-# 2. Apply (subagents enabled by default)
+# 2. Opt subagents in (default is disabled — see [agents] section above)
+echo -e "\n[agents]\nenabled = true" >> .ruler/ruler.toml
+
+# 3. Apply
 ruler apply
 
-# 3. The subagent is now available in each agent's native location:
+# 4. The subagent is now available in each agent's native location:
 #    - Claude Code:  .claude/agents/code-reviewer.md
 #    - Cursor:       .cursor/agents/code-reviewer.md
 #    - Codex CLI:    .codex/agents/code-reviewer.toml
@@ -862,7 +871,7 @@ ruler apply
 
 ### Limitations
 
-- **No explicit revert command.** Cleanup happens via `[subagents] 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

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetLegacySubagentsWarningForTests = _resetLegacySubagentsWarningForTests;
 exports.loadConfig = loadConfig;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
@@ -40,6 +41,21 @@ const os = __importStar(require("os"));
 const toml_1 = require("@iarna/toml");
 const zod_1 = require("zod");
 const constants_1 = require("../constants");
+// One-shot guard so the deprecation message fires once per process even when
+// `loadConfig` is called multiple times (e.g. nested mode walks every
+// `.ruler` directory).
+let _legacySubagentsWarned = false;
+function warnLegacySubagentsSection() {
+    if (_legacySubagentsWarned)
+        return;
+    _legacySubagentsWarned = true;
+    (0, constants_1.logWarn)('`[subagents]` is deprecated; rename it to `[agents]` in your ruler.toml. ' +
+        'The legacy section is honored for now and will be removed in a future release.');
+}
+/** Test helper — re-arms the deprecation guard so suites can assert it fires. */
+function _resetLegacySubagentsWarningForTests() {
+    _legacySubagentsWarned = false;
+}
 const mcpConfigSchema = zod_1.z
     .object({
     enabled: zod_1.z.boolean().optional(),
@@ -55,9 +71,26 @@ const agentConfigSchema = zod_1.z
     mcp: mcpConfigSchema,
 })
     .optional();
+// `[agents]` is a heterogeneous table that holds two unrelated kinds of keys:
+//   - reserved subagent-control booleans (`enabled`, `include_in_rules`)
+//   - 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',
+    'cleanup_orphaned',
+]);
 const rulerConfigSchema = zod_1.z.object({
     default_agents: zod_1.z.array(zod_1.z.string()).optional(),
-    agents: zod_1.z.record(zod_1.z.string(), agentConfigSchema).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(),
     mcp: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
@@ -75,9 +108,15 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
     })
         .optional(),
+    // Deprecated: kept in the schema only so that legacy `[subagents]` blocks
+    // are preserved through validation. The parser reads from here as a
+    // fallback when the new `[agents]` keys are absent and emits a one-time
+    // deprecation warning. Remove in the next minor release.
     subagents: 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(),
     })
         .optional(),
     nested: zod_1.z.boolean().optional(),
@@ -155,6 +194,11 @@ async function loadConfig(options) {
         : {};
     const agentConfigs = {};
     for (const [name, section] of Object.entries(agentsSection)) {
+        // Reserved subagent-control keys live alongside per-agent records in
+        // the same `[agents]` table; skip them here so we only process actual
+        // coding-agent integrations as agent configs.
+        if (SUBAGENT_RESERVED_KEYS.has(name))
+            continue;
         if (section && typeof section === 'object') {
             const sectionObj = section;
             const cfg = {};
@@ -219,14 +263,48 @@ async function loadConfig(options) {
     if (typeof rawSkillsSection.enabled === 'boolean') {
         skillsConfig.enabled = rawSkillsSection.enabled;
     }
-    const rawSubagentsSection = raw.subagents &&
+    // Subagent control lives under `[agents]` (alongside per-agent records).
+    // The reserved keys `enabled` and `include_in_rules` are pulled out here
+    // and surfaced internally as `LoadedConfig.subagents` for the rest of the
+    // codebase, which still uses the `Subagent*` naming.
+    //
+    // Backward-compatibility: the previous release used `[subagents]` for the
+    // same two keys. We still read those as a fallback when the matching
+    // `[agents]` key is absent, and emit a one-time deprecation warning so
+    // existing configs keep working while users migrate.
+    const rawLegacySubagentsSection = raw.subagents &&
         typeof raw.subagents === 'object' &&
         !Array.isArray(raw.subagents)
         ? raw.subagents
         : {};
+    const legacyHasContent = typeof rawLegacySubagentsSection.enabled === 'boolean' ||
+        typeof rawLegacySubagentsSection.include_in_rules === 'boolean' ||
+        typeof rawLegacySubagentsSection.cleanup_orphaned === 'boolean';
+    if (legacyHasContent) {
+        warnLegacySubagentsSection();
+    }
     const subagentsConfig = {};
-    if (typeof rawSubagentsSection.enabled === 'boolean') {
-        subagentsConfig.enabled = rawSubagentsSection.enabled;
+    if (typeof agentsSection.enabled === 'boolean') {
+        subagentsConfig.enabled = agentsSection.enabled;
+    }
+    else if (typeof rawLegacySubagentsSection.enabled === 'boolean') {
+        subagentsConfig.enabled = rawLegacySubagentsSection.enabled;
+    }
+    if (typeof agentsSection.include_in_rules === 'boolean') {
+        subagentsConfig.include_in_rules =
+            agentsSection.include_in_rules;
+    }
+    else if (typeof rawLegacySubagentsSection.include_in_rules === 'boolean') {
+        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;

package/dist/core/FileSystemUtils.js

@@ -44,6 +44,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const constants_1 = require("../constants");
+const SUBAGENTS_DIR_NAME = path.basename(constants_1.RULER_SUBAGENTS_PATH);
 /**
  * Gets the XDG config directory path, falling back to ~/.config if XDG_CONFIG_HOME is not set.
  */
@@ -93,9 +94,18 @@ async function findRulerDir(startPath, checkGlobal = true) {
 /**
  * Recursively reads all Markdown (.md) files in rulerDir, returning their paths and contents.
  * Files are sorted alphabetically by path.
+ *
+ * `.ruler/skills/` is always skipped (skills are propagated separately).
+ * `.ruler/agents/` is skipped unless `options.includeAgents` is `true`.
  */
-async function readMarkdownFiles(rulerDir) {
+async function readMarkdownFiles(rulerDir, options = {}) {
     const mdFiles = [];
+    const includeAgents = options.includeAgents === true;
+    // Tracks whether we skipped a `.ruler/agents` subtree so the root-AGENTS.md
+    // fallback below still recognises ruler content as present and does not
+    // resurrect a previously generated root AGENTS.md (which may itself contain
+    // the very agent docs we're now excluding).
+    let sawExcludedAgents = false;
     // Gather all markdown files (recursive) first
     async function walk(dir) {
         const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
@@ -115,13 +125,22 @@ async function readMarkdownFiles(rulerDir) {
                 }
             }
             if (isDir) {
-                // Skip .ruler/skills; skills are propagated separately and should not be concatenated
                 const relativeFromRoot = path.relative(rulerDir, fullPath);
+                // Skip .ruler/skills; skills are propagated separately and should not be concatenated
                 const isSkillsDir = relativeFromRoot === constants_1.SKILLS_DIR ||
                     relativeFromRoot.startsWith(`${constants_1.SKILLS_DIR}${path.sep}`);
                 if (isSkillsDir) {
                     continue;
                 }
+                // Skip .ruler/agents unless explicitly opted in via subagents.include_in_rules.
+                // Subagents are propagated separately to native locations and should not pollute
+                // the top-level rule concatenation by default.
+                const isAgentsDir = relativeFromRoot === SUBAGENTS_DIR_NAME ||
+                    relativeFromRoot.startsWith(`${SUBAGENTS_DIR_NAME}${path.sep}`);
+                if (isAgentsDir && !includeAgents) {
+                    sawExcludedAgents = true;
+                    continue;
+                }
                 await walk(fullPath);
             }
             else if (isFile && entry.name.endsWith('.md')) {
@@ -170,9 +189,12 @@ async function readMarkdownFiles(rulerDir) {
             const stat = await fs_1.promises.stat(rootAgentsPath);
             if (stat.isFile()) {
                 const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
-                // Check if this is a generated file and we have other .ruler files
+                // Check if this is a generated file and we have other .ruler files.
+                // `sawExcludedAgents` counts as "ruler content present" so a stale
+                // generated root AGENTS.md isn't resurrected when `.ruler/agents` was
+                // the only source under `.ruler` and is now being skipped.
                 const isGenerated = content.startsWith('<!-- Generated by Ruler -->');
-                const hasRulerFiles = others.length > 0 || primaryFile !== null;
+                const hasRulerFiles = others.length > 0 || primaryFile !== null || sawExcludedAgents;
                 // Additional check: if AGENTS.md contains ruler source comments and we have ruler files,
                 // it's likely a corrupted generated file that should be skipped
                 const containsRulerSources = content.includes('<!-- Source: .ruler/') ||

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/core/apply-engine.js

@@ -56,25 +56,23 @@ const constants_1 = require("../constants");
 async function loadNestedConfigurations(projectRoot, configPath, localOnly, resolvedNested) {
     const { dirs: rulerDirs } = await findRulerDirectories(projectRoot, localOnly, true);
     const results = [];
-    const rulerDirConfigs = await processIndependentRulerDirs(rulerDirs);
-    for (const { rulerDir, files } of rulerDirConfigs) {
+    // Load config first so we know whether `.ruler/agents/` should be included
+    // in the rule concatenation for each directory.
+    for (const rulerDir of rulerDirs) {
         const config = await loadConfigForRulerDir(rulerDir, configPath, resolvedNested);
+        const files = await FileSystemUtils.readMarkdownFiles(rulerDir, {
+            includeAgents: shouldIncludeAgentsInRules(config),
+        });
         results.push(await createHierarchicalConfiguration(rulerDir, files, config, configPath));
     }
     return results;
 }
 /**
- * Processes each .ruler directory independently, returning configuration for each.
- * Each .ruler directory gets its own rules (not merged with others).
+ * Returns true when `.ruler/agents/*.md` should be concatenated into the
+ * generated top-level rule files. Defaults to false.
  */
-async function processIndependentRulerDirs(rulerDirs) {
-    const results = [];
-    // Process each .ruler directory independently
-    for (const rulerDir of rulerDirs) {
-        const files = await FileSystemUtils.readMarkdownFiles(rulerDir);
-        results.push({ rulerDir, files });
-    }
-    return results;
+function shouldIncludeAgentsInRules(config) {
+    return config.subagents?.include_in_rules === true;
 }
 async function createHierarchicalConfiguration(rulerDir, files, config, cliConfigPath) {
     await warnAboutLegacyMcpJson(rulerDir);
@@ -146,6 +144,8 @@ function cloneLoadedConfig(config) {
         cliAgents: config.cliAgents ? [...config.cliAgents] : undefined,
         mcp: config.mcp ? { ...config.mcp } : undefined,
         gitignore: config.gitignore ? { ...config.gitignore } : undefined,
+        skills: config.skills ? { ...config.skills } : undefined,
+        subagents: config.subagents ? { ...config.subagents } : undefined,
         nested: config.nested,
         nestedDefined: config.nestedDefined,
     };
@@ -203,8 +203,11 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
         projectRoot,
         configPath,
     });
-    // Read rule files
-    const files = await FileSystemUtils.readMarkdownFiles(rulerDirs[0]);
+    // Read rule files. `.ruler/agents/` is only included when
+    // `[agents] include_in_rules = true`.
+    const files = await FileSystemUtils.readMarkdownFiles(rulerDirs[0], {
+        includeAgents: shouldIncludeAgentsInRules(config),
+    });
     // Concatenate rules
     const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(primaryDir));
     // Load unified config to get merged MCP configuration

package/dist/lib.js

@@ -55,14 +55,23 @@ function resolveSkillsEnabled(cliFlag, configSetting) {
 }
 /**
  * Resolves subagents enabled state based on precedence:
- * CLI flag > ruler.toml > default (enabled).
+ * CLI flag > ruler.toml > default (disabled).
+ *
+ * When neither `[agents] enabled` (nor the legacy `[subagents] enabled`)
+ * nor a CLI flag is provided, propagation is disabled by default per spec.
+ * Subagent definitions are an opt-in feature — propagating them silently
+ * could leak runtime prompts into native subagent locations on projects
+ * that never intended to use the feature.
  */
 function resolveSubagentsEnabled(cliFlag, configSetting) {
     return cliFlag !== undefined
         ? cliFlag
         : configSetting !== undefined
             ? configSetting
-            : true; // default to enabled
+            : false; // default to disabled — see spec: subagents must opt in
+}
+function resolveSubagentsCleanupOrphaned(configSetting) {
+    return configSetting === true;
 }
 /**
  * Applies ruler configurations for all supported AI agents.
@@ -113,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);
@@ -140,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.39",
+  "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",