@intellectronica/ruler 0.3.39 → 0.3.40

package/README.md

@@ -790,19 +790,24 @@ For GitHub Copilot, source `tools` (Claude vocabulary: `Read`, `Grep`, `Bash`,
 
 ### 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)
 ```
 
-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 +837,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. 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.
 
 ### Example Workflow
 
@@ -850,10 +855,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 +870,7 @@ ruler apply
 
 ### Limitations
 
-- **No explicit revert command.** Cleanup happens via `[subagents] enabled = false` on a subsequent `apply`.
+- **No explicit revert command.** Cleanup happens via `[agents] enabled = false` on 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/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,21 @@ 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']);
 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(),
+    })
+        .catchall(agentConfigSchema)
+        .optional(),
     mcp: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
@@ -75,9 +103,14 @@ 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(),
     })
         .optional(),
     nested: zod_1.z.boolean().optional(),
@@ -155,6 +188,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 +257,39 @@ 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';
+    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;
     }
     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/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,20 @@ 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
 }
 /**
  * Applies ruler configurations for all supported AI agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.39",
+  "version": "0.3.40",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {