@kuznai/inception-engine 0.11.1 → 0.13.0

package/README.md

@@ -48,8 +48,8 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Skills (SKILL.md) | All agents via manifest and CLI | All agents |
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
-| MCP Servers | claude-code, gemini-cli; other agents are warned and skipped | claude-code, gemini-cli |
-| Global Rules Files | claude-code, codex, gemini-cli, opencode; github-copilot reads CLAUDE.md natively (deploy via claude-code); other agents are warned and skipped | claude-code, codex, gemini-cli, opencode |
+| MCP Servers | claude-code, gemini-cli, codex, antigravity, opencode; github-copilot repo-scoped surfaces are warned and skipped | claude-code, gemini-cli, codex, antigravity, opencode |
+| Global/Repo Rules Files | All agents (antigravity uses repo-local `.agents/rules/`); github-copilot reads CLAUDE.md natively (deploy via claude-code) | All agents |
 | `init` manifest generation | Scans `SKILL.md` directories and writes starter `skills` entries | N/A |
 
 Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
@@ -128,17 +128,22 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 
 - **name** - Unique identifier (same format as skill names); used as the server's key in the config
 - **agents** - Array of agent IDs to register this server with
-- **config** - Raw server descriptor object (e.g. `{ "command": "...", "args": [...] }` for stdio transport). The exact shape is passed through verbatim; agent adapters handle agent-specific requirements.
+- **config** - Raw server descriptor object. For the currently supported JSON-backed adapters, inception-engine requires at least one non-empty `command` or `url` field, validates `args` as an array of strings when present, and validates `env` as a string-to-string object when present. Additional keys are passed through verbatim.
 
-MCP server registration is currently supported for `claude-code` (`~/.claude.json`) and `gemini-cli` (`~/.gemini/settings.json`). Other agents emit a warning and are skipped. Revert removes the registered server entry from the config file.
+MCP server registration is supported for all agents except GitHub Copilot. Inception-engine automatically uses the correct adapter for each agent's configuration schema:
+- **JSON (Merge Patch)**: `claude-code` (`~/.claude.json`), `gemini-cli` (`~/.gemini/settings.json`), and `opencode` (`~/.config/opencode/opencode.json` using the custom `"mcp"` key).
+- **TOML (Patch)**: `codex` (`~/.codex/config.toml`).
+- **Markdown Frontmatter (Emit)**: `antigravity` (repo-local `.agents/rules/{name}.md` files).
+
+Revert removes the registered server entry from the respective configuration file. GitHub Copilot, which uses repo-scoped MCP surfaces not yet implemented by inception-engine, continues to emit a schema-aware warning and is skipped.
 
 Each **agentRules** entry deploys a Markdown instruction file to an agent's supported global rules file location:
 
 - **name** - Unique identifier (same format as skill names)
-- **path** - Relative path to the source Markdown file within the repo
+- **path** - Relative path to the source Markdown file within the repo; supported global rules adapters require a `.md` or `.markdown` source path
 - **agents** - Array of agent IDs to deploy this file to
 
-Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Other agents emit a warning and are skipped because their instruction surfaces are different, repo-scoped, or not yet implemented. Revert removes the deployed rules file.
+Instruction rule deployment is supported for all agents. For most agents, this targets a single global rules file (e.g., `~/.claude/CLAUDE.md` for `claude-code`, `~/.codex/AGENTS.md` for `codex`, `~/.gemini/GEMINI.md` for `gemini-cli`, and `~/.config/opencode/AGENTS.md` for `opencode`). For `antigravity`, inception-engine deploys to repo-local instruction surfaces at `{repo}/.agents/rules/{name}.md`. For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -155,7 +160,7 @@ description: What this skill does and when to use it
 Instructions for the AI agent...
 ```
 
-The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine does not currently validate the frontmatter — missing or malformed fields may cause the skill to be ignored or misbehave at the agent level.
+The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine now validates this minimum contract during deploy: `SKILL.md` must start with YAML frontmatter and include non-empty single-line `name` and `description` fields. It still does not attempt full YAML/schema validation beyond that targeted check.
 
 ## `init` Command
 
@@ -171,7 +176,7 @@ Current `init` behavior:
 
 Current `init` limitations:
 
-- It does not read or validate YAML frontmatter inside `SKILL.md`
+- It does not reconcile generated manifest entries against `SKILL.md` frontmatter values
 - It does not infer `files`, `configs`, `mcpServers`, or `agentRules`
 - It does not reconcile generated output with the longer-term Claude-first portability direction
 

package/dist/config/agents.js

@@ -18,13 +18,21 @@ export const AGENT_REGISTRY = [
             mcpConfig: "documented",
             agentRules: "documented",
         },
-        mcpConfigPath: {
-            posix: ["{home}", ".claude.json"],
-            windows: ["{home}", ".claude.json"],
-        },
-        agentRulesPath: {
-            posix: ["{home}", ".claude", "CLAUDE.md"],
-            windows: ["{home}", ".claude", "CLAUDE.md"],
+        mcpSupport: {
+            status: "supported",
+            schemaLabel: "JSON mcpServers config",
+            path: {
+                posix: ["{home}", ".claude.json"],
+                windows: ["{home}", ".claude.json"],
+            },
+        },
+        agentRulesSupport: {
+            status: "supported",
+            schemaLabel: "global Markdown rules file",
+            path: {
+                posix: ["{home}", ".claude", "CLAUDE.md"],
+                windows: ["{home}", ".claude", "CLAUDE.md"],
+            },
         },
     },
     {
@@ -45,10 +53,21 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentRules: "documented",
         },
-        // mcpConfigPath omitted: Codex uses TOML config, not JSON — not supported by config-patch
-        agentRulesPath: {
-            posix: ["{home}", ".codex", "AGENTS.md"],
-            windows: ["{home}", ".codex", "AGENTS.md"],
+        mcpSupport: {
+            status: "supported",
+            schemaLabel: "TOML mcpServers config",
+            path: {
+                posix: ["{home}", ".codex", "config.toml"],
+                windows: ["{home}", ".codex", "config.toml"],
+            },
+        },
+        agentRulesSupport: {
+            status: "supported",
+            schemaLabel: "global Markdown rules file",
+            path: {
+                posix: ["{home}", ".codex", "AGENTS.md"],
+                windows: ["{home}", ".codex", "AGENTS.md"],
+            },
         },
     },
     {
@@ -70,13 +89,21 @@ export const AGENT_REGISTRY = [
             mcpConfig: "documented",
             agentRules: "documented",
         },
-        mcpConfigPath: {
-            posix: ["{home}", ".gemini", "settings.json"],
-            windows: ["{home}", ".gemini", "settings.json"],
-        },
-        agentRulesPath: {
-            posix: ["{home}", ".gemini", "GEMINI.md"],
-            windows: ["{home}", ".gemini", "GEMINI.md"],
+        mcpSupport: {
+            status: "supported",
+            schemaLabel: "JSON mcpServers config",
+            path: {
+                posix: ["{home}", ".gemini", "settings.json"],
+                windows: ["{home}", ".gemini", "settings.json"],
+            },
+        },
+        agentRulesSupport: {
+            status: "supported",
+            schemaLabel: "global Markdown rules file",
+            path: {
+                posix: ["{home}", ".gemini", "GEMINI.md"],
+                windows: ["{home}", ".gemini", "GEMINI.md"],
+            },
         },
     },
     {
@@ -96,7 +123,22 @@ export const AGENT_REGISTRY = [
             detectPaths: "implementation-only",
             detectBinary: "provisional",
         },
-        // mcpConfigPath and agentRulesPath omitted: paths not documented strongly enough for this release
+        mcpSupport: {
+            status: "supported",
+            schemaLabel: "repo-local frontmatter-emit MCP rules",
+            path: {
+                posix: ["{repo}", ".agents", "rules", "{name}.md"],
+                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+            },
+        },
+        agentRulesSupport: {
+            status: "supported",
+            schemaLabel: "repo-local Markdown rules file",
+            path: {
+                posix: ["{repo}", ".agents", "rules", "{name}.md"],
+                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+            },
+        },
     },
     {
         id: "opencode",
@@ -116,10 +158,22 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             agentRules: "documented",
         },
-        // mcpConfigPath omitted: OpenCode uses opencode.json (TOML-adjacent format), not plain JSON
-        agentRulesPath: {
-            posix: ["{xdg_config}", "opencode", "AGENTS.md"],
-            windows: ["{appdata}", "opencode", "AGENTS.md"],
+        mcpSupport: {
+            status: "supported",
+            schemaLabel: "opencode.json MCP config",
+            path: {
+                posix: ["{xdg_config}", "opencode", "opencode.json"],
+                windows: ["{appdata}", "opencode", "opencode.json"],
+            },
+            mcpPatchKey: "mcp",
+        },
+        agentRulesSupport: {
+            status: "supported",
+            schemaLabel: "global Markdown rules file",
+            path: {
+                posix: ["{xdg_config}", "opencode", "AGENTS.md"],
+                windows: ["{appdata}", "opencode", "AGENTS.md"],
+            },
         },
     },
     {
@@ -139,10 +193,16 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
         },
-        // agentRulesPath omitted: Copilot reads CLAUDE.md natively (Claude-first portability rule).
-        // Deploy via the "claude-code" agentRules entry — it reaches Copilot automatically.
-        // mcpConfigPath omitted: Copilot MCP config surface is not implemented here yet.
-        claudeNativeInstruction: true,
+        mcpSupport: {
+            status: "unsupported",
+            schemaLabel: "repo-scoped MCP surfaces",
+            reason: "GitHub Copilot MCP support depends on repo-scoped files such as devcontainer or agent-frontmatter mappings, which are not translated here",
+        },
+        agentRulesSupport: {
+            status: "unsupported",
+            schemaLabel: "Claude-native shared instructions",
+            reason: 'GitHub Copilot reads CLAUDE.md natively, so deploy via the "claude-code" agentRules target instead of a separate rules surface',
+        },
         policyNote: "Organization policies may override locally deployed skills. Verify with your GitHub org admin if deployed skills are not active.",
     },
 ];

package/dist/core/adapters/frontmatter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Serializes a flat (one-level) object to a YAML block suitable for use inside
+ * `---` frontmatter delimiters.
+ */
+export declare function serializeFrontmatter(data: Record<string, unknown>): string;
+/**
+ * Builds the full content of a frontmatter-bearing Markdown file.
+ * If `body` is provided it is appended after the closing delimiter.
+ */
+export declare function buildFrontmatterDocument(frontmatter: Record<string, unknown>, body?: string): string;
+/**
+ * Reads an existing `.md` file and parses its frontmatter (using the
+ * `front-matter` package). Returns the parsed attributes and raw body.
+ * Returns `{ attributes: {}, body: "" }` if the file does not exist.
+ */
+export declare function readFrontmatterFile(filePath: string): Promise<{
+    attributes: Record<string, unknown>;
+    body: string;
+}>;
+/**
+ * Atomically writes a Markdown file with the given frontmatter and optional
+ * body. Preserves any existing body content when `preserveBody` is true.
+ */
+export declare function writeFrontmatterFile(filePath: string, frontmatter: Record<string, unknown>, options?: {
+    preserveBody?: boolean;
+}): Promise<void>;

package/dist/core/adapters/frontmatter.js

@@ -0,0 +1,120 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+const _require = createRequire(import.meta.url);
+// front-matter is a CommonJS module whose export is the callable parse function.
+const parseFrontmatter = _require("front-matter");
+// ---------------------------------------------------------------------------
+// Hand-rolled flat-YAML serializer
+// Handles the shapes found in MCP server descriptors: strings, numbers,
+// booleans, string arrays, and one-level nested objects (e.g. "env").
+// ---------------------------------------------------------------------------
+function serializeScalar(value) {
+    if (typeof value === "string") {
+        const needsQuotes = /[:#[\]{},|>&*!'"@`]|^\s|\s$/.test(value);
+        return needsQuotes
+            ? `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+            : value;
+    }
+    return String(value);
+}
+function serializeArray(key, arr, pad) {
+    if (arr.length === 0)
+        return `${pad}${key}: []`;
+    const items = arr.map((item) => {
+        const scalar = typeof item === "string" ||
+            typeof item === "number" ||
+            typeof item === "boolean"
+            ? serializeScalar(item)
+            : JSON.stringify(item);
+        return `${pad}  - ${scalar}`;
+    });
+    return [`${pad}${key}:`, ...items].join("\n");
+}
+function serializeObject(key, obj, pad) {
+    const inner = serializeFrontmatterAtDepth(obj, `${pad}  `);
+    return inner ? `${pad}${key}:\n${inner}` : `${pad}${key}: {}`;
+}
+function serializeFrontmatterAtDepth(data, pad) {
+    const lines = [];
+    for (const [key, value] of Object.entries(data)) {
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            lines.push(serializeArray(key, value, pad));
+        }
+        else if (typeof value === "object") {
+            lines.push(serializeObject(key, value, pad));
+        }
+        else {
+            lines.push(`${pad}${key}: ${serializeScalar(value)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Serializes a flat (one-level) object to a YAML block suitable for use inside
+ * `---` frontmatter delimiters.
+ */
+export function serializeFrontmatter(data) {
+    return serializeFrontmatterAtDepth(data, "");
+}
+/**
+ * Builds the full content of a frontmatter-bearing Markdown file.
+ * If `body` is provided it is appended after the closing delimiter.
+ */
+export function buildFrontmatterDocument(frontmatter, body = "") {
+    const serialized = serializeFrontmatter(frontmatter);
+    return `---\n${serialized}\n---\n${body}`;
+}
+function createAtomicTempPath(targetPath) {
+    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
+}
+/**
+ * Reads an existing `.md` file and parses its frontmatter (using the
+ * `front-matter` package). Returns the parsed attributes and raw body.
+ * Returns `{ attributes: {}, body: "" }` if the file does not exist.
+ */
+export async function readFrontmatterFile(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { attributes: {}, body: "" };
+        throw err;
+    }
+    const parsed = parseFrontmatter(raw);
+    return { attributes: parsed.attributes, body: parsed.body };
+}
+/**
+ * Atomically writes a Markdown file with the given frontmatter and optional
+ * body. Preserves any existing body content when `preserveBody` is true.
+ */
+export async function writeFrontmatterFile(filePath, frontmatter, options = {}) {
+    let body = "";
+    if (options.preserveBody) {
+        const existing = await readFrontmatterFile(filePath);
+        body = existing.body;
+    }
+    const content = buildFrontmatterDocument(frontmatter, body);
+    const tempPath = createAtomicTempPath(filePath);
+    try {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(tempPath, content, "utf-8");
+        await rename(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}

package/dist/core/adapters/index.d.ts

@@ -1,11 +1,11 @@
 import type { AgentRuleEntry, McpServerEntry } from "../../schemas/manifest.ts";
-import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, PlanWarning } from "../../types.ts";
+import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, FrontmatterEmitDeployAction, PlanWarning, TomlPatchDeployAction } from "../../types.ts";
 import { compileMcpServerReverts } from "./mcp.ts";
 import { compileAgentRuleReverts } from "./rules.ts";
 export { compileAgentRuleReverts, compileMcpServerReverts };
-export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction;
+export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction;
 export interface AdapterResult {
     actions: AdapterAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string): Promise<AdapterResult>;
+export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string): Promise<AdapterResult>;

package/dist/core/adapters/index.js

@@ -1,16 +1,16 @@
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
 export { compileAgentRuleReverts, compileMcpServerReverts };
-export async function compileAdapterActions(mcpServers, agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+export async function compileAdapterActions(mcpServers, agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
     const actions = [];
     const warnings = [];
     for (const entry of mcpServers) {
-        const r = compileMcpServerActions(entry, detectedAgents, home);
+        const r = compileMcpServerActions(entry, detectedAgents, home, repo);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
     for (const entry of agentRules) {
-        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }

package/dist/core/adapters/mcp.d.ts

@@ -1,8 +1,8 @@
 import type { McpServerEntry } from "../../schemas/manifest.ts";
-import type { AgentId, ConfigPatchDeployAction, ConfigPatchRevertAction, PlanWarning } from "../../types.ts";
+import type { AgentId, ConfigPatchDeployAction, ConfigPatchRevertAction, FrontmatterEmitDeployAction, FrontmatterEmitRevertAction, PlanWarning, TomlPatchDeployAction, TomlPatchRevertAction } from "../../types.ts";
 export interface McpAdapterResult {
-    actions: ConfigPatchDeployAction[];
+    actions: Array<ConfigPatchDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction>;
     warnings: PlanWarning[];
 }
-export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string): McpAdapterResult;
-export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string): ConfigPatchRevertAction[];
+export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string, repo?: string): McpAdapterResult;
+export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string, repo?: string): Array<ConfigPatchRevertAction | TomlPatchRevertAction | FrontmatterEmitRevertAction>;

package/dist/core/adapters/mcp.js

@@ -1,7 +1,52 @@
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-export function compileMcpServerActions(entry, detectedAgents, home) {
+import { validateMcpServerConfigShape } from "../validation.js";
+/**
+ * Determines whether a resolved config path targets a TOML file.
+ */
+function isTomlTarget(targetPath) {
+    return path.extname(targetPath).toLowerCase() === ".toml";
+}
+/**
+ * Determines whether a resolved config path targets a Markdown file
+ * (indicates a frontmatter-emit surface, e.g. Antigravity's .agents/rules/).
+ */
+function isMarkdownTarget(targetPath) {
+    const ext = path.extname(targetPath).toLowerCase();
+    return ext === ".md" || ext === ".markdown";
+}
+function buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPatchKey) {
+    if (isMarkdownTarget(resolvedTarget)) {
+        return {
+            kind: "frontmatter-emit",
+            skill: entry.name,
+            agent: agentId,
+            target: resolvedTarget,
+            frontmatter: { "mcp-servers": { [entry.name]: entry.config } },
+            confidence,
+        };
+    }
+    if (isTomlTarget(resolvedTarget)) {
+        return {
+            kind: "toml-patch",
+            skill: entry.name,
+            agent: agentId,
+            target: resolvedTarget,
+            config: entry.config,
+            confidence,
+        };
+    }
+    return {
+        kind: "config-patch",
+        skill: entry.name,
+        agent: agentId,
+        target: resolvedTarget,
+        patch: { [mcpPatchKey]: { [entry.name]: entry.config } },
+        confidence,
+    };
+}
+export function compileMcpServerActions(entry, detectedAgents, home, repo) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
@@ -9,43 +54,59 @@ export function compileMcpServerActions(entry, detectedAgents, home) {
         if (!detectedAgents.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent?.mcpConfigPath) {
+        const support = agent?.mcpSupport;
+        if (!support || support.status === "unsupported") {
             warnings.push({
                 kind: "confidence",
-                message: `mcpServers: agent "${agentId}" does not have a documented MCP config path — skipping "${entry.name}"`,
+                message: `mcpServers: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported MCP schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported MCP adapter"} — skipping "${entry.name}"`,
             });
             continue;
         }
-        const target = resolvePlaceholders(agent.mcpConfigPath[platform], "", home);
-        // Ensure no stray empty segments collapse the path unexpectedly
-        const resolvedTarget = path.resolve(target);
-        actions.push({
-            kind: "config-patch",
-            skill: entry.name,
-            agent: agentId,
-            target: resolvedTarget,
-            patch: { mcpServers: { [entry.name]: entry.config } },
-            confidence: agent.provenance.mcpConfig ?? "provisional",
-        });
+        validateMcpServerConfigShape(entry.config, entry.name, agentId);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const resolvedTarget = path.resolve(rawTarget);
+        const confidence = agent.provenance.mcpConfig ?? "provisional";
+        const mcpPatchKey = support.mcpPatchKey ?? "mcpServers";
+        actions.push(buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPatchKey));
     }
     return { actions, warnings };
 }
-export function compileMcpServerReverts(entry, agentFilter, home) {
+export function compileMcpServerReverts(entry, agentFilter, home, repo) {
     const actions = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent?.mcpConfigPath)
+        const support = agent?.mcpSupport;
+        if (!support || support.status === "unsupported")
             continue;
-        const target = path.resolve(resolvePlaceholders(agent.mcpConfigPath[platform], "", home));
-        actions.push({
-            kind: "config-patch",
-            skill: entry.name,
-            agent: agentId,
-            target,
-        });
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const target = path.resolve(rawTarget);
+        if (isMarkdownTarget(target)) {
+            actions.push({
+                kind: "frontmatter-emit",
+                skill: entry.name,
+                agent: agentId,
+                target,
+            });
+        }
+        else if (isTomlTarget(target)) {
+            actions.push({
+                kind: "toml-patch",
+                skill: entry.name,
+                agent: agentId,
+                target,
+            });
+        }
+        else {
+            actions.push({
+                kind: "config-patch",
+                skill: entry.name,
+                agent: agentId,
+                target,
+            });
+        }
     }
     return actions;
 }

package/dist/core/adapters/rules.d.ts

@@ -4,5 +4,5 @@ export interface RulesAdapterResult {
     actions: FileWriteDeployAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string): Promise<RulesAdapterResult>;
-export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string): FileWriteRevertAction[];
+export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string): Promise<RulesAdapterResult>;
+export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string): FileWriteRevertAction[];

package/dist/core/adapters/rules.js

@@ -1,57 +1,64 @@
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-import { validateSourceFile, validateSourcePath } from "../validation.js";
-export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+import { validateAgentRuleMarkdownPath, validateSourceFile, validateSourcePath, } from "../validation.js";
+export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
     const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    const supportedTargets = [];
     if (targetAgents.length === 0) {
         return { actions, warnings };
     }
-    // Validate the source file once (before iterating agents) since it is shared.
-    const source = path.resolve(sourceDir, entry.path);
-    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
-    await validateSourceFile(source, entry.path);
     for (const agentId of targetAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (agent?.claudeNativeInstruction) {
-            warnings.push({
-                kind: "confidence",
-                message: `agentRules: agent "${agentId}" reads CLAUDE.md natively — deploy via "claude-code" target to reach Copilot automatically; no separate deployment needed`,
-            });
-            continue;
-        }
-        if (!agent?.agentRulesPath) {
+        const support = agent?.agentRulesSupport;
+        if (!support || support.status === "unsupported") {
             warnings.push({
                 kind: "confidence",
-                message: `agentRules: agent "${agentId}" does not have a documented rules file path — skipping "${entry.name}"`,
+                message: `agentRules: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported instruction schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported rules adapter"} — skipping "${entry.name}"`,
             });
             continue;
         }
-        const target = resolvePlaceholders(agent.agentRulesPath[platform], "", home);
+        supportedTargets.push({
+            agentId,
+            confidence: agent.provenance.agentRules ?? "provisional",
+            target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
+        });
+    }
+    if (supportedTargets.length === 0) {
+        return { actions, warnings };
+    }
+    // Validate the shared source file only when at least one target uses the
+    // current global-Markdown adapter surface.
+    const source = path.resolve(sourceDir, entry.path);
+    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSourceFile(source, entry.path);
+    for (const target of supportedTargets) {
+        validateAgentRuleMarkdownPath(entry.path, target.agentId);
         actions.push({
             kind: "file-write",
             skill: entry.name,
-            agent: agentId,
+            agent: target.agentId,
             source,
-            target,
-            confidence: agent.provenance.agentRules ?? "provisional",
+            target: target.target,
+            confidence: target.confidence,
         });
     }
     return { actions, warnings };
 }
-export function compileAgentRuleReverts(entry, agentFilter, home) {
+export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
     const actions = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent?.agentRulesPath)
+        const support = agent?.agentRulesSupport;
+        if (!support || support.status === "unsupported")
             continue;
-        const target = resolvePlaceholders(agent.agentRulesPath[platform], "", home);
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
         actions.push({
             kind: "file-write",
             skill: entry.name,