@intellectronica/ruler 0.3.38 → 0.3.40

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