@intellectronica/ruler 0.3.38 → 0.3.39

package/README.md

@@ -54,40 +54,40 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 
 ## Supported AI Agents
 
-| Agent                  | Rules File(s)                                  | MCP Configuration / Notes                        | Skills Support / Location |
-| ---------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------- |
-| AGENTS.md              | `AGENTS.md`                                    | (pseudo-agent ensuring root `AGENTS.md` exists)  | -                         |
-| GitHub Copilot         | `AGENTS.md`                                    | `.vscode/mcp.json`                               | `.claude/skills/`         |
-| Claude Code            | `CLAUDE.md`                                    | `.mcp.json`                                      | `.claude/skills/`         |
-| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.codex/skills/`          |
-| Pi Coding Agent        | `AGENTS.md`                                    | -                                                | `.pi/skills/`             |
-| Jules                  | `AGENTS.md`                                    | -                                                | -                         |
-| Cursor                 | `AGENTS.md`                                    | `.cursor/mcp.json`                               | `.cursor/skills/`         |
-| Windsurf               | `AGENTS.md`                                    | `.windsurf/mcp_config.json`                      | `.windsurf/skills/`       |
-| Cline                  | `.clinerules`                                  | -                                                | -                         |
-| Crush                  | `CRUSH.md`                                     | `.crush.json`                                    | -                         |
-| Amp                    | `AGENTS.md`                                    | -                                                | `.agents/skills/`         |
-| Antigravity            | `.agent/rules/ruler.md`                        | -                                                | `.agent/skills/`          |
-| Amazon Q CLI           | `.amazonq/rules/ruler_q_rules.md`              | `.amazonq/mcp.json`                              | -                         |
-| Aider                  | `AGENTS.md`, `.aider.conf.yml`                 | `.mcp.json`                                      | -                         |
-| Firebase Studio        | `.idx/airules.md`                              | `.idx/mcp.json`                                  | -                         |
-| Open Hands             | `.openhands/microagents/repo.md`               | `config.toml`                                    | -                         |
-| Gemini CLI             | `AGENTS.md`                                    | `.gemini/settings.json`                          | `.gemini/skills/`         |
-| Junie                  | `.junie/guidelines.md`                         | `.junie/mcp/mcp.json`                            | `.junie/skills/`          |
-| AugmentCode            | `.augment/rules/ruler_augment_instructions.md` | -                                                | -                         |
-| Kilo Code              | `AGENTS.md`                                    | `.kilocode/mcp.json`                             | `.claude/skills/`         |
-| OpenCode               | `AGENTS.md`                                    | `opencode.json`                                  | `.opencode/skills/`       |
-| Goose                  | `.goosehints`                                  | -                                                | `.agents/skills/`         |
-| Qwen Code              | `AGENTS.md`                                    | `.qwen/settings.json`                            | -                         |
-| RooCode                | `AGENTS.md`                                    | `.roo/mcp.json`                                  | `.roo/skills/`            |
-| Zed                    | `AGENTS.md`                                    | `.zed/settings.json` (project root, never $HOME) | -                         |
-| Trae AI                | `.trae/rules/project_rules.md`                 | -                                                | -                         |
-| Warp                   | `WARP.md`                                      | -                                                | -                         |
-| Kiro                   | `.kiro/steering/ruler_kiro_instructions.md`    | `.kiro/settings/mcp.json`                        | -                         |
-| Firebender             | `firebender.json`                              | `firebender.json` (rules and MCP in same file)   | -                         |
-| Factory Droid          | `AGENTS.md`                                    | `.factory/mcp.json`                              | `.factory/skills/`        |
-| Mistral Vibe           | `AGENTS.md`                                    | `.vibe/config.toml`                              | `.vibe/skills/`           |
-| JetBrains AI Assistant | `.aiassistant/rules/AGENTS.md`                 | -                                                | -                         |
+| Agent                  | Rules File(s)                                  | MCP Configuration / Notes                        | Skills Support / Location | Subagents Support / Location |
+| ---------------------- | ---------------------------------------------- | ------------------------------------------------ | ------------------------- | ---------------------------- |
+| AGENTS.md              | `AGENTS.md`                                    | (pseudo-agent ensuring root `AGENTS.md` exists)  | -                         | -                            |
+| GitHub Copilot         | `AGENTS.md`                                    | `.vscode/mcp.json`                               | `.claude/skills/`         | `.github/agents/`            |
+| Claude Code            | `CLAUDE.md`                                    | `.mcp.json`                                      | `.claude/skills/`         | `.claude/agents/`            |
+| OpenAI Codex CLI       | `AGENTS.md`                                    | `.codex/config.toml`                             | `.codex/skills/`          | `.codex/agents/` (`.toml`)   |
+| Pi Coding Agent        | `AGENTS.md`                                    | -                                                | `.pi/skills/`             | -                            |
+| Jules                  | `AGENTS.md`                                    | -                                                | -                         | -                            |
+| Cursor                 | `AGENTS.md`                                    | `.cursor/mcp.json`                               | `.cursor/skills/`         | `.cursor/agents/`            |
+| Windsurf               | `AGENTS.md`                                    | `.windsurf/mcp_config.json`                      | `.windsurf/skills/`       | -                            |
+| Cline                  | `.clinerules`                                  | -                                                | -                         | -                            |
+| Crush                  | `CRUSH.md`                                     | `.crush.json`                                    | -                         | -                            |
+| Amp                    | `AGENTS.md`                                    | -                                                | `.agents/skills/`         | -                            |
+| Antigravity            | `.agent/rules/ruler.md`                        | -                                                | `.agent/skills/`          | -                            |
+| Amazon Q CLI           | `.amazonq/rules/ruler_q_rules.md`              | `.amazonq/mcp.json`                              | -                         | -                            |
+| Aider                  | `AGENTS.md`, `.aider.conf.yml`                 | `.mcp.json`                                      | -                         | -                            |
+| Firebase Studio        | `.idx/airules.md`                              | `.idx/mcp.json`                                  | -                         | -                            |
+| Open Hands             | `.openhands/microagents/repo.md`               | `config.toml`                                    | -                         | -                            |
+| Gemini CLI             | `AGENTS.md`                                    | `.gemini/settings.json`                          | `.gemini/skills/`         | -                            |
+| Junie                  | `.junie/guidelines.md`                         | `.junie/mcp/mcp.json`                            | `.junie/skills/`          | -                            |
+| AugmentCode            | `.augment/rules/ruler_augment_instructions.md` | -                                                | -                         | -                            |
+| Kilo Code              | `AGENTS.md`                                    | `.kilocode/mcp.json`                             | `.claude/skills/`         | -                            |
+| OpenCode               | `AGENTS.md`                                    | `opencode.json`                                  | `.opencode/skills/`       | -                            |
+| Goose                  | `.goosehints`                                  | -                                                | `.agents/skills/`         | -                            |
+| Qwen Code              | `AGENTS.md`                                    | `.qwen/settings.json`                            | -                         | -                            |
+| RooCode                | `AGENTS.md`                                    | `.roo/mcp.json`                                  | `.roo/skills/`            | -                            |
+| Zed                    | `AGENTS.md`                                    | `.zed/settings.json` (project root, never $HOME) | -                         | -                            |
+| Trae AI                | `.trae/rules/project_rules.md`                 | -                                                | -                         | -                            |
+| Warp                   | `WARP.md`                                      | -                                                | -                         | -                            |
+| Kiro                   | `.kiro/steering/ruler_kiro_instructions.md`    | `.kiro/settings/mcp.json`                        | -                         | -                            |
+| Firebender             | `firebender.json`                              | `firebender.json` (rules and MCP in same file)   | -                         | -                            |
+| Factory Droid          | `AGENTS.md`                                    | `.factory/mcp.json`                              | `.factory/skills/`        | -                            |
+| Mistral Vibe           | `AGENTS.md`                                    | `.vibe/config.toml`                              | `.vibe/skills/`           | -                            |
+| JetBrains AI Assistant | `.aiassistant/rules/AGENTS.md`                 | -                                                | -                         | -                            |
 
 ## Getting Started
 
@@ -241,9 +241,12 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 | `--gitignore-local`            | Write managed ignore entries to `.git/info/exclude` instead.           |
 | `--nested`                     | Enable nested rule loading (default: inherit from config or disabled). |
 | `--no-nested`                  | Disable nested rule loading even if `nested = true` in config.         |
-| `--backup`                     | Toggle creation of `.bak` backup files (default: enabled).             |
+| `--backup`                     | Enable creation of `.bak` backup files (default: enabled).             |
+| `--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).             |
+| `--no-subagents`               | Disable subagents support.                                             |
 | `--dry-run`                    | Preview changes without writing files.                                 |
 | `--local-only`                 | Skip `$XDG_CONFIG_HOME` when looking for configuration.                |
 | `--verbose` / `-v`             | Display detailed output during execution.                              |
@@ -663,12 +666,13 @@ When skills support is enabled and gitignore integration is active, Ruler automa
 - `.gemini/skills/` (for Gemini CLI)
 - `.junie/skills/` (for Junie)
 - `.cursor/skills/` (for Cursor)
+- `.windsurf/skills/` (for Windsurf)
 
 to your `.gitignore` file within the managed Ruler block.
 
 ### Requirements
 
-- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor): No additional requirements.
+- **For agents with native skills support** (Claude Code, GitHub Copilot, Kilo Code, OpenAI Codex CLI, OpenCode, Pi Coding Agent, Goose, Amp, Antigravity, Factory Droid, Mistral Vibe, Roo Code, Gemini CLI, Junie, Cursor, Windsurf): No additional requirements.
 
 ### Validation
 
@@ -723,8 +727,145 @@ ruler apply
 #    - Gemini CLI: .gemini/skills/my-skill/
 #    - Junie: .junie/skills/my-skill/
 #    - Cursor: .cursor/skills/my-skill/
+#    - Windsurf: .windsurf/skills/my-skill/
 ```
 
+## Subagents Support (Experimental)
+
+> **⚠️ Experimental:** Subagents support is experimental and behavior may change in future releases.
+
+Ruler can distribute named, delegatable **subagents** from a single source of truth (`.ruler/agents/`) to each agent's native subagent location. Each source file is one Markdown file with YAML frontmatter; Ruler transforms it into the format the target agent expects.
+
+### How It Works
+
+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 |
+
+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`:
+
+```markdown
+---
+name: code-reviewer
+description: Use PROACTIVELY after a feature/fix is implemented. Reviews against SOLID/DRY/KISS. Read-only.
+tools: [Read, Grep, Glob, Bash]
+model: inherit
+readonly: true
+is_background: false
+---
+
+# Code Reviewer
+
+You operate in a fresh context window with read-only access. Your job is to
+review the diff and surrounding code against the design principles and return
+a structured verdict.
+```
+
+**Required frontmatter fields:**
+
+| 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. |
+
+**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.               |
+
+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`:
+
+```bash
+ruler apply --no-subagents   # disable subagent propagation for one run
+```
+
+```toml
+# .ruler/ruler.toml
+[subagents]
+enabled = false
+```
+
+CLI flags take precedence over `ruler.toml`, which takes precedence over the default (enabled).
+
+### Validation
+
+Source files are validated at discovery time:
+
+- Files without YAML frontmatter are skipped with a warning.
+- Files missing required `name` or `description` are skipped with a warning.
+- Files where `name` does not match the filename stem are skipped with a warning.
+- Unknown frontmatter keys are dropped (not errored).
+
+### Dry-Run Mode
+
+Use `--dry-run` to preview which files would be written without touching disk.
+
+### `.gitignore` Integration
+
+When subagents are enabled, the four target directories are added to the Ruler-managed block of `.gitignore`:
+
+```
+.claude/agents/
+.cursor/agents/
+.codex/agents/
+.github/agents/
+```
+
+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.
+
+### Example Workflow
+
+```bash
+# 1. Author a subagent in your project
+mkdir -p .ruler/agents
+cat > .ruler/agents/code-reviewer.md << 'EOF'
+---
+name: code-reviewer
+description: Reviews changes against SOLID/DRY/KISS
+tools: [Read, Grep, Glob]
+readonly: true
+---
+
+You review code changes for quality.
+EOF
+
+# 2. Apply (subagents enabled by default)
+ruler apply
+
+# 3. 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
+#    - GitHub Copilot: .github/agents/code-reviewer.md
+```
+
+### Limitations
+
+- **No explicit revert command.** Cleanup happens via `[subagents] 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.
+
 ## `.gitignore` Integration
 
 Ruler automatically manages your `.gitignore` file to keep generated agent configuration files out of version control.

package/dist/agents/ClaudeAgent.js

@@ -58,5 +58,8 @@ class ClaudeAgent extends AbstractAgent_1.AbstractAgent {
     supportsNativeSkills() {
         return true;
     }
+    supportsNativeSubagents() {
+        return true;
+    }
 }
 exports.ClaudeAgent = ClaudeAgent;

package/dist/agents/CodexCliAgent.js

@@ -149,5 +149,8 @@ class CodexCliAgent {
     supportsNativeSkills() {
         return true;
     }
+    supportsNativeSubagents() {
+        return true;
+    }
 }
 exports.CodexCliAgent = CodexCliAgent;

package/dist/agents/CopilotAgent.js

@@ -42,5 +42,8 @@ class CopilotAgent {
     supportsNativeSkills() {
         return true;
     }
+    supportsNativeSubagents() {
+        return true;
+    }
 }
 exports.CopilotAgent = CopilotAgent;

package/dist/agents/CursorAgent.js

@@ -33,5 +33,8 @@ class CursorAgent extends AgentsMdAgent_1.AgentsMdAgent {
     supportsNativeSkills() {
         return true;
     }
+    supportsNativeSubagents() {
+        return true;
+    }
 }
 exports.CursorAgent = CursorAgent;

package/dist/cli/commands.js

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

package/dist/cli/handlers.js

@@ -114,8 +114,16 @@ async function applyHandler(argv) {
     else {
         skillsEnabled = undefined; // Let config/default decide
     }
+    // Determine subagents preference: CLI > TOML > Default (enabled)
+    let subagentsEnabled;
+    if (argv.subagents !== undefined) {
+        subagentsEnabled = argv.subagents;
+    }
+    else {
+        subagentsEnabled = undefined; // Let config/default decide
+    }
     try {
-        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup, skillsEnabled, gitignoreLocalPreference);
+        await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup, skillsEnabled, gitignoreLocalPreference, subagentsEnabled);
         console.log('Ruler apply completed successfully.');
     }
     catch (err) {

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SKILL_MD_FILENAME = exports.ANTIGRAVITY_SKILLS_PATH = exports.FACTORY_SKILLS_PATH = exports.WINDSURF_SKILLS_PATH = exports.CURSOR_SKILLS_PATH = exports.JUNIE_SKILLS_PATH = exports.GEMINI_SKILLS_PATH = exports.ROO_SKILLS_PATH = exports.VIBE_SKILLS_PATH = exports.GOOSE_SKILLS_PATH = exports.PI_SKILLS_PATH = exports.OPENCODE_SKILLS_PATH = exports.CODEX_SKILLS_PATH = exports.CLAUDE_SKILLS_PATH = exports.RULER_SKILLS_PATH = exports.SKILLS_DIR = exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
+exports.COPILOT_SUBAGENTS_PATH = exports.CODEX_SUBAGENTS_PATH = exports.CURSOR_SUBAGENTS_PATH = exports.CLAUDE_SUBAGENTS_PATH = exports.RULER_SUBAGENTS_PATH = exports.SKILL_MD_FILENAME = exports.ANTIGRAVITY_SKILLS_PATH = exports.FACTORY_SKILLS_PATH = exports.WINDSURF_SKILLS_PATH = exports.CURSOR_SKILLS_PATH = exports.JUNIE_SKILLS_PATH = exports.GEMINI_SKILLS_PATH = exports.ROO_SKILLS_PATH = exports.VIBE_SKILLS_PATH = exports.GOOSE_SKILLS_PATH = exports.PI_SKILLS_PATH = exports.OPENCODE_SKILLS_PATH = exports.CODEX_SKILLS_PATH = exports.CLAUDE_SKILLS_PATH = exports.RULER_SKILLS_PATH = exports.SKILLS_DIR = exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
 exports.actionPrefix = actionPrefix;
 exports.createRulerError = createRulerError;
 exports.logVerbose = logVerbose;
@@ -66,3 +66,9 @@ exports.WINDSURF_SKILLS_PATH = '.windsurf/skills';
 exports.FACTORY_SKILLS_PATH = '.factory/skills';
 exports.ANTIGRAVITY_SKILLS_PATH = '.agent/skills';
 exports.SKILL_MD_FILENAME = 'SKILL.md';
+// Subagents-related constants
+exports.RULER_SUBAGENTS_PATH = '.ruler/agents';
+exports.CLAUDE_SUBAGENTS_PATH = '.claude/agents';
+exports.CURSOR_SUBAGENTS_PATH = '.cursor/agents';
+exports.CODEX_SUBAGENTS_PATH = '.codex/agents';
+exports.COPILOT_SUBAGENTS_PATH = '.github/agents';

package/dist/core/ConfigLoader.js

@@ -75,6 +75,11 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
     })
         .optional(),
+    subagents: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .optional(),
     nested: zod_1.z.boolean().optional(),
 });
 /**
@@ -214,6 +219,15 @@ async function loadConfig(options) {
     if (typeof rawSkillsSection.enabled === 'boolean') {
         skillsConfig.enabled = rawSkillsSection.enabled;
     }
+    const rawSubagentsSection = raw.subagents &&
+        typeof raw.subagents === 'object' &&
+        !Array.isArray(raw.subagents)
+        ? raw.subagents
+        : {};
+    const subagentsConfig = {};
+    if (typeof rawSubagentsSection.enabled === 'boolean') {
+        subagentsConfig.enabled = rawSubagentsSection.enabled;
+    }
     const nestedDefined = typeof raw.nested === 'boolean';
     const nested = nestedDefined ? raw.nested : false;
     return {
@@ -223,6 +237,7 @@ async function loadConfig(options) {
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
         skills: skillsConfig,
+        subagents: subagentsConfig,
         nested,
         nestedDefined,
     };

package/dist/core/SubagentsProcessor.js

@@ -0,0 +1,440 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverSubagents = discoverSubagents;
+exports.getSelectedSubagentTargets = getSelectedSubagentTargets;
+exports.getSubagentsGitignorePaths = getSubagentsGitignorePaths;
+exports._resetExperimentalWarningForTests = _resetExperimentalWarningForTests;
+exports.propagateSubagentsForClaude = propagateSubagentsForClaude;
+exports.propagateSubagentsForCursor = propagateSubagentsForCursor;
+exports.propagateSubagentsForCodex = propagateSubagentsForCodex;
+exports.propagateSubagentsForCopilot = propagateSubagentsForCopilot;
+exports.propagateSubagents = propagateSubagents;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const yaml = __importStar(require("js-yaml"));
+const toml_1 = require("@iarna/toml");
+const constants_1 = require("../constants");
+const SubagentsUtils_1 = require("./SubagentsUtils");
+/**
+ * Discovers subagent definitions in `.ruler/agents/`.
+ * Each `.md` file is parsed for YAML frontmatter (name, description, …).
+ * Files that fail validation are dropped from the returned list and
+ * reported via warnings.
+ */
+async function discoverSubagents(projectRoot) {
+    const dir = path.join(projectRoot, constants_1.RULER_SUBAGENTS_PATH);
+    try {
+        await fs.access(dir);
+    }
+    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 subagents = [];
+    const warnings = [];
+    for (const filePath of mdFiles) {
+        const info = await (0, SubagentsUtils_1.loadSubagentFile)(filePath);
+        if (info.valid) {
+            subagents.push(info);
+        }
+        else if (info.error) {
+            warnings.push(info.error);
+        }
+    }
+    return { subagents, warnings };
+}
+const SUBAGENT_TARGET_TO_IDENTIFIERS = new Map([
+    ['claude', ['claude']],
+    ['cursor', ['cursor']],
+    ['codex', ['codex']],
+    ['copilot', ['copilot']],
+]);
+const SUBAGENT_TARGET_PATHS = {
+    claude: constants_1.CLAUDE_SUBAGENTS_PATH,
+    cursor: constants_1.CURSOR_SUBAGENTS_PATH,
+    codex: constants_1.CODEX_SUBAGENTS_PATH,
+    copilot: constants_1.COPILOT_SUBAGENTS_PATH,
+};
+/**
+ * Returns which native subagent targets are reachable through the supplied
+ * agent list. An agent only contributes to a target when it implements
+ * `supportsNativeSubagents()` returning true.
+ */
+function getSelectedSubagentTargets(agents) {
+    const enabledIdentifiers = new Set(agents
+        .filter((agent) => agent.supportsNativeSubagents?.())
+        .map((agent) => agent.getIdentifier()));
+    const targets = new Set();
+    for (const [target, identifiers] of SUBAGENT_TARGET_TO_IDENTIFIERS) {
+        if (identifiers.some((id) => enabledIdentifiers.has(id))) {
+            targets.add(target);
+        }
+    }
+    return targets;
+}
+/**
+ * Returns absolute paths that subagent propagation may generate, for the
+ * supplied agents, used for `.gitignore` integration.
+ */
+async function getSubagentsGitignorePaths(projectRoot, agents) {
+    const dir = path.join(projectRoot, constants_1.RULER_SUBAGENTS_PATH);
+    try {
+        await fs.access(dir);
+    }
+    catch {
+        return [];
+    }
+    const targets = getSelectedSubagentTargets(agents);
+    return Array.from(targets).map((t) => path.join(projectRoot, SUBAGENT_TARGET_PATHS[t]));
+}
+/**
+ * Module-level state to track if experimental warning has been shown.
+ * Mirrors the SkillsProcessor convention to avoid spamming the user across
+ * multiple `apply` invocations within the same process.
+ */
+let hasWarnedExperimental = false;
+function warnOnceExperimental(dryRun) {
+    if (hasWarnedExperimental)
+        return;
+    hasWarnedExperimental = true;
+    (0, constants_1.logWarn)('Subagents support is experimental and behavior may change in future releases.', dryRun);
+}
+/**
+ * Test-only hook to reset the once-per-process experimental warning state.
+ */
+function _resetExperimentalWarningForTests() {
+    hasWarnedExperimental = false;
+}
+/* ------------------------------------------------------------------ */
+/* Frontmatter helpers                                                 */
+/* ------------------------------------------------------------------ */
+function buildFrontmatterBlock(meta) {
+    const yamlText = yaml.dump(meta, { lineWidth: -1, noRefs: true }).trimEnd();
+    return `---\n${yamlText}\n---\n`;
+}
+function ensureBodyFormatting(body) {
+    const text = (body ?? '').replace(/^\n+/, '');
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+/* ------------------------------------------------------------------ */
+/* Atomic directory write                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Stages files into a temp directory and atomically swaps it into place.
+ * Mirrors the pattern used by SkillsProcessor for safe overwriting.
+ */
+async function writeAgentsDirectoryAtomic(targetDir, files) {
+    const parent = path.dirname(targetDir);
+    await fs.mkdir(parent, { recursive: true });
+    const tempDir = path.join(parent, `agents.tmp-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+    try {
+        for (const { name, content } of files) {
+            await fs.writeFile(path.join(tempDir, name), content, 'utf8');
+        }
+        try {
+            await fs.rm(targetDir, { recursive: true, force: true });
+        }
+        catch {
+            // Target didn't exist; ignore.
+        }
+        await fs.rename(tempDir, targetDir);
+    }
+    catch (error) {
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors.
+        }
+        throw error;
+    }
+}
+function buildClaudeFile(sub) {
+    const fm = sub.frontmatter;
+    const meta = {
+        name: fm.name,
+        description: fm.description,
+    };
+    if (fm.tools !== undefined)
+        meta.tools = fm.tools;
+    if (fm.model !== undefined)
+        meta.model = fm.model;
+    // Pass through readonly and is_background verbatim so authoring intent
+    // survives the Claude transform. Claude Code ignores unknown frontmatter
+    // keys, but downstream tooling that reads .claude/agents/*.md can still
+    // observe the original values.
+    if (fm.readonly !== undefined)
+        meta.readonly = fm.readonly;
+    if (fm.is_background !== undefined)
+        meta.is_background = fm.is_background;
+    return `${buildFrontmatterBlock(meta)}\n${ensureBodyFormatting(sub.body)}`;
+}
+function buildCursorFile(sub) {
+    const fm = sub.frontmatter;
+    const meta = {
+        name: fm.name,
+        description: fm.description,
+        model: fm.model ?? 'inherit',
+        readonly: fm.readonly ?? false,
+        is_background: fm.is_background ?? false,
+    };
+    return `${buildFrontmatterBlock(meta)}\n${ensureBodyFormatting(sub.body)}`;
+}
+function buildCodexFile(sub) {
+    const fm = sub.frontmatter;
+    const config = {
+        name: fm.name,
+        description: fm.description,
+        developer_instructions: ensureBodyFormatting(sub.body),
+    };
+    if (fm.model !== undefined && fm.model !== 'inherit') {
+        config.model = fm.model;
+    }
+    if (fm.readonly === true) {
+        config.sandbox_mode = 'read-only';
+    }
+    // @iarna/toml requires JsonMap; the cast is safe because every value is a
+    // string/boolean/number/object that the library knows how to serialize.
+    return (0, toml_1.stringify)(config);
+}
+function buildCopilotFile(sub, dryRun, verbose) {
+    const fm = sub.frontmatter;
+    const meta = {
+        name: fm.name,
+        description: fm.description,
+        'user-invocable': true,
+    };
+    const warnings = [];
+    if (fm.tools && fm.tools.length > 0) {
+        const { tools, unknown } = (0, SubagentsUtils_1.mapToolsForCopilot)(fm.tools);
+        if (tools.length > 0) {
+            meta.tools = tools;
+        }
+        if (unknown.length > 0) {
+            warnings.push(`Subagent "${fm.name}": dropping tools not mappable to Copilot aliases: ${unknown.join(', ')}`);
+        }
+    }
+    if (fm.model !== undefined && fm.model !== 'inherit') {
+        meta.model = fm.model;
+    }
+    if (fm.readonly === true) {
+        meta['disable-model-invocation'] = true;
+    }
+    // Tool-drop is informational — surface it only when the user explicitly
+    // asked for detail (--verbose) or when previewing changes (--dry-run).
+    // A normal apply stays quiet to avoid noise on every run.
+    if (verbose || dryRun) {
+        for (const warning of warnings) {
+            (0, constants_1.logWarn)(warning, dryRun);
+        }
+    }
+    return {
+        content: `${buildFrontmatterBlock(meta)}\n${ensureBodyFormatting(sub.body)}`,
+        warnings,
+    };
+}
+async function propagateSubagentsForClaude(projectRoot, subagents, options) {
+    if (subagents.length === 0)
+        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`)}`);
+    }
+    const files = subagents.map((s) => ({
+        name: `${s.name}.md`,
+        content: buildClaudeFile(s),
+    }));
+    await writeAgentsDirectoryAtomic(targetDir, files);
+    return [];
+}
+async function propagateSubagentsForCursor(projectRoot, subagents, options) {
+    if (subagents.length === 0)
+        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`)}`);
+    }
+    const files = subagents.map((s) => ({
+        name: `${s.name}.md`,
+        content: buildCursorFile(s),
+    }));
+    await writeAgentsDirectoryAtomic(targetDir, files);
+    return [];
+}
+async function propagateSubagentsForCodex(projectRoot, subagents, options) {
+    if (subagents.length === 0)
+        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`)}`);
+    }
+    const files = subagents.map((s) => ({
+        name: `${s.name}.toml`,
+        content: buildCodexFile(s),
+    }));
+    await writeAgentsDirectoryAtomic(targetDir, files);
+    return [];
+}
+async function propagateSubagentsForCopilot(projectRoot, subagents, options) {
+    if (subagents.length === 0)
+        return [];
+    const targetDir = path.join(projectRoot, constants_1.COPILOT_SUBAGENTS_PATH);
+    const verbose = options.verbose ?? false;
+    if (options.dryRun) {
+        const planLines = [];
+        for (const s of subagents) {
+            // Surface tool-mapping warnings during dry-run too — buildCopilotFile
+            // 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`)}`);
+        }
+        return planLines;
+    }
+    const files = subagents.map((s) => ({
+        name: `${s.name}.md`,
+        content: buildCopilotFile(s, false, verbose).content,
+    }));
+    await writeAgentsDirectoryAtomic(targetDir, files);
+    return [];
+}
+/* ------------------------------------------------------------------ */
+/* Cleanup-on-disable                                                  */
+/* ------------------------------------------------------------------ */
+async function cleanupSubagentsDir(projectRoot, relPath, dryRun, verbose) {
+    const target = path.join(projectRoot, relPath);
+    try {
+        await fs.access(target);
+    }
+    catch {
+        return;
+    }
+    if (dryRun) {
+        (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${relPath}`, verbose, dryRun);
+        return;
+    }
+    await fs.rm(target, { recursive: true, force: true });
+    (0, constants_1.logVerboseInfo)(`Removed ${relPath} (subagents disabled)`, verbose, dryRun);
+}
+async function cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose) {
+    await cleanupSubagentsDir(projectRoot, constants_1.CLAUDE_SUBAGENTS_PATH, dryRun, verbose);
+    await cleanupSubagentsDir(projectRoot, constants_1.CURSOR_SUBAGENTS_PATH, dryRun, verbose);
+    await cleanupSubagentsDir(projectRoot, constants_1.CODEX_SUBAGENTS_PATH, dryRun, verbose);
+    await cleanupSubagentsDir(projectRoot, constants_1.COPILOT_SUBAGENTS_PATH, 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);
+        await cleanupAllSubagentsDirectories(projectRoot, dryRun, verbose);
+        return;
+    }
+    const sourceDir = path.join(projectRoot, constants_1.RULER_SUBAGENTS_PATH);
+    try {
+        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);
+        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);
+        return;
+    }
+    (0, constants_1.logVerboseInfo)(`Discovered ${subagents.length} subagent(s)`, verbose, dryRun);
+    const supporting = agents.filter((a) => a.supportsNativeSubagents?.());
+    const nonSupporting = agents.filter((a) => !a.supportsNativeSubagents?.());
+    if (nonSupporting.length > 0) {
+        const names = nonSupporting.map((a) => a.getName()).join(', ');
+        (0, constants_1.logWarn)(`Subagents are configured, but the following agents do not support native subagents and will be skipped: ${names}`, dryRun);
+    }
+    const targets = getSelectedSubagentTargets(agents);
+    // Reconcile: any managed target directory that is not in the current
+    // selection set is stale and must be removed. This catches the case where
+    // a user drops an agent (e.g. claude+cursor → claude only) so the previously
+    // generated .cursor/agents/ directory does not linger as orphaned config.
+    const allTargets = ['claude', 'cursor', 'codex', 'copilot'];
+    for (const target of allTargets) {
+        if (!targets.has(target)) {
+            await cleanupSubagentsDir(projectRoot, SUBAGENT_TARGET_PATHS[target], dryRun, verbose);
+        }
+    }
+    if (supporting.length === 0) {
+        (0, constants_1.logVerboseInfo)('No agents support native subagents, skipping subagent propagation', verbose, dryRun);
+        return;
+    }
+    warnOnceExperimental(dryRun);
+    if (targets.has('claude')) {
+        (0, constants_1.logVerboseInfo)(`Writing subagents to ${constants_1.CLAUDE_SUBAGENTS_PATH} for Claude Code`, verbose, dryRun);
+        await propagateSubagentsForClaude(projectRoot, subagents, {
+            dryRun,
+            verbose,
+        });
+    }
+    if (targets.has('cursor')) {
+        (0, constants_1.logVerboseInfo)(`Writing subagents to ${constants_1.CURSOR_SUBAGENTS_PATH} for Cursor`, verbose, dryRun);
+        await propagateSubagentsForCursor(projectRoot, subagents, {
+            dryRun,
+            verbose,
+        });
+    }
+    if (targets.has('codex')) {
+        (0, constants_1.logVerboseInfo)(`Writing subagents to ${constants_1.CODEX_SUBAGENTS_PATH} for OpenAI Codex CLI`, verbose, dryRun);
+        await propagateSubagentsForCodex(projectRoot, subagents, {
+            dryRun,
+            verbose,
+        });
+    }
+    if (targets.has('copilot')) {
+        (0, constants_1.logVerboseInfo)(`Writing subagents to ${constants_1.COPILOT_SUBAGENTS_PATH} for GitHub Copilot`, verbose, dryRun);
+        await propagateSubagentsForCopilot(projectRoot, subagents, {
+            dryRun,
+            verbose,
+        });
+    }
+}

package/dist/core/SubagentsUtils.js

@@ -0,0 +1,195 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+exports.validateFrontmatter = validateFrontmatter;
+exports.loadSubagentFile = loadSubagentFile;
+exports.mapToolsForCopilot = mapToolsForCopilot;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const yaml = __importStar(require("js-yaml"));
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/**
+ * Extracts YAML frontmatter and body from a Markdown file's contents.
+ * Returns null if no frontmatter delimiter pair is present at the head of the file.
+ */
+function parseFrontmatter(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return null;
+    }
+    const [, raw, body] = match;
+    const meta = yaml.load(raw);
+    return {
+        meta: meta && typeof meta === 'object' ? meta : {},
+        body: body ?? '',
+    };
+}
+/**
+ * Validates a parsed frontmatter object and reads the required and optional
+ * fields into a typed SubagentFrontmatter. Returns the typed value on success
+ * or an error message on failure.
+ */
+function validateFrontmatter(meta, expectedName) {
+    const name = meta.name;
+    const description = meta.description;
+    if (typeof name !== 'string' || name.length === 0) {
+        return { error: `missing or invalid required field "name"` };
+    }
+    if (typeof description !== 'string' || description.length === 0) {
+        return { error: `missing or invalid required field "description"` };
+    }
+    if (name !== expectedName) {
+        return {
+            error: `frontmatter name "${name}" does not match filename stem "${expectedName}"`,
+        };
+    }
+    const fm = { name, description };
+    if (meta.tools !== undefined) {
+        if (Array.isArray(meta.tools) &&
+            meta.tools.every((t) => typeof t === 'string')) {
+            fm.tools = meta.tools;
+        }
+        else if (typeof meta.tools === 'string') {
+            fm.tools = meta.tools
+                .split(',')
+                .map((t) => t.trim())
+                .filter(Boolean);
+        }
+        else {
+            return { error: `invalid "tools" field; expected string or string[]` };
+        }
+    }
+    if (meta.model !== undefined) {
+        if (typeof meta.model !== 'string') {
+            return { error: `invalid "model" field; expected string` };
+        }
+        fm.model = meta.model;
+    }
+    if (meta.readonly !== undefined) {
+        if (typeof meta.readonly !== 'boolean') {
+            return { error: `invalid "readonly" field; expected boolean` };
+        }
+        fm.readonly = meta.readonly;
+    }
+    if (meta.is_background !== undefined) {
+        if (typeof meta.is_background !== 'boolean') {
+            return { error: `invalid "is_background" field; expected boolean` };
+        }
+        fm.is_background = meta.is_background;
+    }
+    return { value: fm };
+}
+/**
+ * Loads a single subagent file and produces a SubagentInfo.
+ * Invalid files produce a SubagentInfo with valid=false and an error string.
+ */
+async function loadSubagentFile(filePath) {
+    const stem = path.basename(filePath, '.md');
+    const content = await fs.readFile(filePath, 'utf8');
+    // js-yaml throws on malformed YAML; convert that into the standard
+    // validation-failure shape so one bad file doesn't abort discovery.
+    let parsed;
+    try {
+        parsed = parseFrontmatter(content);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            name: stem,
+            path: filePath,
+            valid: false,
+            error: `${stem}.md: invalid YAML frontmatter: ${detail}`,
+        };
+    }
+    if (!parsed) {
+        return {
+            name: stem,
+            path: filePath,
+            valid: false,
+            error: `${stem}.md: missing YAML frontmatter`,
+        };
+    }
+    const result = validateFrontmatter(parsed.meta, stem);
+    if ('error' in result) {
+        return {
+            name: stem,
+            path: filePath,
+            valid: false,
+            error: `${stem}.md: ${result.error}`,
+        };
+    }
+    return {
+        name: stem,
+        path: filePath,
+        valid: true,
+        frontmatter: result.value,
+        body: parsed.body,
+    };
+}
+/**
+ * Maps Claude Code tool names to GitHub Copilot tool aliases.
+ * Unknown source tools return undefined and should be dropped (with a warning).
+ */
+const COPILOT_TOOL_MAP = {
+    Read: 'read',
+    Grep: 'search',
+    Glob: 'search',
+    Bash: 'execute',
+    Edit: 'edit',
+    Write: 'edit',
+    WebFetch: 'web',
+    WebSearch: 'web',
+    TodoWrite: 'todo',
+    Task: 'agent',
+};
+/**
+ * Translates Claude tool names to Copilot aliases. Deduplicates results.
+ * Unknown source tools are reported separately so callers can surface a warning.
+ */
+function mapToolsForCopilot(sourceTools) {
+    const mapped = new Set();
+    const unknown = [];
+    for (const tool of sourceTools) {
+        const alias = COPILOT_TOOL_MAP[tool];
+        if (alias) {
+            mapped.add(alias);
+        }
+        else {
+            unknown.push(tool);
+        }
+    }
+    return { tools: Array.from(mapped), unknown };
+}

package/dist/lib.js

@@ -53,6 +53,17 @@ function resolveSkillsEnabled(cliFlag, configSetting) {
             ? configSetting
             : true; // default to enabled
 }
+/**
+ * Resolves subagents enabled state based on precedence:
+ * CLI flag > ruler.toml > default (enabled).
+ */
+function resolveSubagentsEnabled(cliFlag, configSetting) {
+    return cliFlag !== undefined
+        ? cliFlag
+        : configSetting !== undefined
+            ? configSetting
+            : true; // default to enabled
+}
 /**
  * Applies ruler configurations for all supported AI agents.
  * @param projectRoot Root directory of the project
@@ -62,7 +73,7 @@ function resolveSkillsEnabled(cliFlag, configSetting) {
  * @param projectRoot Root directory of the project
  * @param includedAgents Optional list of agent name filters (case-insensitive substrings)
  */
-async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false, nested = false, backup = true, skillsEnabled, cliGitignoreLocal) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false, nested = false, backup = true, skillsEnabled, cliGitignoreLocal, subagentsEnabled) {
     // Load configuration and rules
     (0, constants_1.logVerbose)(`Loading configuration from project root: ${projectRoot}`, verbose);
     if (configPath) {
@@ -100,6 +111,16 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
                 await propagateSkills(nestedRoot, selectedAgents, skillsEnabledResolved, verbose, dryRun);
             }
         }
+        // Propagate subagents (mirrors skills handling for nested mode).
+        const subagentsEnabledResolved = resolveSubagentsEnabled(subagentsEnabled, rootConfig.subagents?.enabled);
+        {
+            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);
+            }
+        }
         generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }
     else {
@@ -117,6 +138,12 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
             const { propagateSkills } = await Promise.resolve().then(() => __importStar(require('./core/SkillsProcessor')));
             await propagateSkills(projectRoot, selectedAgents, skillsEnabledResolved, verbose, dryRun);
         }
+        // Propagate subagents (mirrors skills handling).
+        const subagentsEnabledResolvedSingle = resolveSubagentsEnabled(subagentsEnabled, singleConfig.config.subagents?.enabled);
+        {
+            const { propagateSubagents } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
+            await propagateSubagents(projectRoot, selectedAgents, subagentsEnabledResolvedSingle, verbose, dryRun);
+        }
         generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }
     // Add skills-generated paths to gitignore if skills are enabled
@@ -126,7 +153,14 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         // Skills enabled by default or explicitly
         const { getSkillsGitignorePaths } = await Promise.resolve().then(() => __importStar(require('./core/SkillsProcessor')));
         const skillsPaths = await getSkillsGitignorePaths(projectRoot, selectedAgents);
-        allGeneratedPaths = [...generatedPaths, ...skillsPaths];
+        allGeneratedPaths = [...allGeneratedPaths, ...skillsPaths];
+    }
+    // Add subagents-generated paths to gitignore if subagents are enabled.
+    const subagentsEnabledForGitignore = resolveSubagentsEnabled(subagentsEnabled, loadedConfig.subagents?.enabled);
+    if (subagentsEnabledForGitignore) {
+        const { getSubagentsGitignorePaths } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
+        const subagentPaths = await getSubagentsGitignorePaths(projectRoot, selectedAgents);
+        allGeneratedPaths = [...allGeneratedPaths, ...subagentPaths];
     }
     await (0, apply_engine_1.updateGitignore)(projectRoot, allGeneratedPaths, loadedConfig, cliGitignoreEnabled, dryRun, cliGitignoreLocal);
 }

package/package.json

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