@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/src/core/adapters/agent-definitions.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+/**
+ * Compiles deploy actions for agentDefinitions manifest entries.
+ *
+ * Agent definition files are Markdown (typically with YAML frontmatter) or
+ * TOML files that define custom agents or subagents for a given platform.
+ * Unlike agentRules (which target a single shared global file per agent),
+ * each definition entry produces a separate file named after the entry in
+ * the agent's dedicated agent-definitions directory.
+ *
+ * Target paths use the `{repo}` placeholder so definitions land in the
+ * repository being deployed, not the user's home directory.
+ *
+ * TOML source files (e.g. Gemini CLI `.gemini/agents/*.toml`) bypass
+ * Markdown-specific validation and are deployed verbatim.
+ */
+/**
+ * Returns the TOML-specific surface for an agent (global or repo-local),
+ * or undefined when the agent has no TOML definition surface.
+ */
+function resolveTomlDefinitionsSurface(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (!agent)
+        return undefined;
+    const tomlSupport = scope === "repo"
+        ? (agent.agentDefinitionsTomlRepoSupport ??
+            agent.agentDefinitionsTomlSupport)
+        : agent.agentDefinitionsTomlSupport;
+    if (!tomlSupport || tomlSupport.status !== "supported")
+        return undefined;
+    return tomlSupport;
+}
+/** Returns a warning when the requested scope cannot be resolved, or null when it is fine. */
+function scopeAvailabilityWarning(entry, agentId, repo, workspace) {
+    if (entry.scope === "repo" && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentDefinitions: scope "repo" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    if (entry.scope === "workspace" && !workspace && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentDefinitions: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    return null;
+}
+function resolveSupportedTargets(entry, targetAgents, home, repo, workspace) {
+    const targets = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const agentId of targetAgents) {
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "agentDefinitions",
+            entryName: entry.name,
+            targetAgentIds: targetAgents,
+            scope: entry.scope,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
+            continue;
+        }
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        // For TOML sources, use the agent's TOML-specific surface instead of the
+        // default Markdown surface. Agents without a TOML surface are skipped.
+        const support = isToml
+            ? resolveTomlDefinitionsSurface(agentId, entry.scope)
+            : resolveCapabilitySurface(agentId, "agentDefinitions", entry.scope)
+                .support;
+        if (!support)
+            continue;
+        const scopeWarning = scopeAvailabilityWarning(entry, agentId, repo, workspace);
+        if (scopeWarning) {
+            warnings.push(scopeWarning);
+            continue;
+        }
+        targets.push({
+            agentId,
+            confidence: plan.confidence ?? "provisional",
+            target: resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace),
+        });
+    }
+    return { targets, warnings };
+}
+async function createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace) {
+    const actions = [];
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const target of supportedTargets) {
+        // TOML definition files have no YAML frontmatter — skip Markdown validation.
+        if (!isToml) {
+            validateAgentRuleMarkdownPath(entry.path, target.agentId);
+            await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        }
+        let migratedFrom;
+        if (target.agentId === "github-copilot") {
+            migratedFrom = [
+                resolvePlaceholders(["{repo}", ".github", "agents", "{name}.agent.md"], entry.name, home, repo, workspace),
+            ];
+        }
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: target.agentId,
+            source,
+            target: target.target,
+            confidence: target.confidence,
+            migratedFrom,
+        });
+    }
+    return actions;
+}
+export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
+    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    if (targetAgents.length === 0) {
+        return { actions: [], warnings: [] };
+    }
+    const { targets: supportedTargets, warnings } = resolveSupportedTargets(entry, targetAgents, home, repo, workspace);
+    if (supportedTargets.length === 0) {
+        return { actions: [], warnings };
+    }
+    // Validate the shared source file only when at least one target is active.
+    const source = path.resolve(sourceDir, entry.path);
+    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSourceFile(source, entry.path);
+    const actions = await createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace);
+    return { actions, warnings };
+}
+export function compileAgentDefinitionReverts(entry, agentFilter, home, repo, workspace) {
+    const actions = [];
+    const platform = getPlatformKey();
+    const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const support = isToml
+            ? resolveTomlDefinitionsSurface(agentId, entry.scope)
+            : resolveCapabilitySurface(agentId, "agentDefinitions", entry.scope)
+                .support;
+        if (!support)
+            continue;
+        if (entry.scope === "repo" && !repo)
+            continue;
+        if (entry.scope === "workspace" && !workspace && !repo)
+            continue;
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

package/dist/{core → src/core}/adapters/frontmatter.d.ts

@@ -12,6 +12,7 @@ export declare function splitFrontmatter(raw: string): {
 export declare function parseFrontmatterDocument<T = Record<string, unknown>>(raw: string): {
     attributes: T;
     body: string;
+    hasFrontmatter: boolean;
 };
 /**
  * Serializes an object to a YAML block.
@@ -21,6 +22,9 @@ export declare function serializeFrontmatter(data: Record<string, unknown>): str
  * Builds the full content of a frontmatter-bearing Markdown file.
  */
 export declare function buildFrontmatterDocument(frontmatter: Record<string, unknown>, body?: string): string;
+export declare function buildMarkdownDocument(frontmatter: Record<string, unknown>, body?: string, options?: {
+    hasFrontmatter?: boolean;
+}): string;
 /**
  * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
@@ -29,6 +33,12 @@ export declare function readFrontmatterFile(filePath: string): Promise<{
     attributes: Record<string, unknown>;
     body: string;
 }>;
+export declare function readFrontmatterDocumentFile(filePath: string): Promise<{
+    exists: boolean;
+    hasFrontmatter: boolean;
+    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.

package/dist/{core → src/core}/adapters/frontmatter.js

@@ -26,10 +26,10 @@ export function splitFrontmatter(raw) {
 export function parseFrontmatterDocument(raw) {
     const { frontmatter, body } = splitFrontmatter(raw);
     if (!(frontmatter || raw.startsWith("---"))) {
-        return { attributes: {}, body };
+        return { attributes: {}, body, hasFrontmatter: false };
     }
     const attributes = YAML.parse(frontmatter);
-    return { attributes: (attributes || {}), body };
+    return { attributes: (attributes || {}), body, hasFrontmatter: true };
 }
 /**
  * Serializes an object to a YAML block.
@@ -42,9 +42,15 @@ export function serializeFrontmatter(data) {
  * Builds the full content of a frontmatter-bearing Markdown file.
  */
 export function buildFrontmatterDocument(frontmatter, body = "") {
+    return buildMarkdownDocument(frontmatter, body, { hasFrontmatter: true });
+}
+export function buildMarkdownDocument(frontmatter, body = "", options = {}) {
+    const cleanBody = body.trimStart();
+    if (Object.keys(frontmatter).length === 0 && !options.hasFrontmatter) {
+        return cleanBody;
+    }
     const serialized = serializeFrontmatter(frontmatter);
     // Ensure exactly one newline after the closing delimiter before the body
-    const cleanBody = body.trimStart();
     const separator = cleanBody ? "\n\n" : "\n";
     return `---\n${serialized}\n---\n${separator}${cleanBody}`;
 }
@@ -58,17 +64,28 @@ function createAtomicTempPath(targetPath) {
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export async function readFrontmatterFile(filePath) {
+    const document = await readFrontmatterDocumentFile(filePath);
+    return { attributes: document.attributes, body: document.body };
+}
+export async function readFrontmatterDocumentFile(filePath) {
     let raw;
     try {
         raw = await readFile(filePath, "utf-8");
     }
     catch (err) {
         const code = err.code;
-        if (code === "ENOENT")
-            return { attributes: {}, body: "" };
+        if (code === "ENOENT") {
+            return {
+                exists: false,
+                hasFrontmatter: false,
+                attributes: {},
+                body: "",
+            };
+        }
         throw err;
     }
-    return parseFrontmatterDocument(raw);
+    const parsed = parseFrontmatterDocument(raw);
+    return { exists: true, ...parsed };
 }
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional

package/dist/{core → src/core}/adapters/index.d.ts

@@ -10,4 +10,4 @@ export interface AdapterResult {
     actions: AdapterAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[]): Promise<AdapterResult>;
+export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string): Promise<AdapterResult>;

package/dist/{core → src/core}/adapters/index.js

@@ -3,16 +3,16 @@ import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
 export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions) {
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace) {
     const actions = [];
     const warnings = [];
     for (const entry of mcpServers) {
-        const r = compileMcpServerActions(entry, detectedAgents, home, repo);
+        const r = compileMcpServerActions(entry, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
     for (const entry of agentRules) {
-        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
+        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
@@ -22,7 +22,7 @@ export async function compileAdapterActions(mcpServers, agentRules, permissions,
         warnings.push(...r.warnings);
     }
     for (const entry of agentDefinitions ?? []) {
-        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
+        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }

package/dist/{core → src/core}/adapters/mcp.d.ts

@@ -4,5 +4,5 @@ export interface McpAdapterResult {
     actions: Array<ConfigPatchDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction>;
     warnings: PlanWarning[];
 }
-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>;
+export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): McpAdapterResult;
+export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): Array<ConfigPatchRevertAction | TomlPatchRevertAction | FrontmatterEmitRevertAction>;

package/dist/{core → src/core}/adapters/mcp.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validateMcpServerConfigShape } from "../validation.js";
 /**
@@ -46,51 +46,48 @@ function buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPat
         confidence,
     };
 }
-export function compileMcpServerActions(entry, detectedAgents, home, repo) {
+export function compileMcpServerActions(entry, detectedAgents, home, repo, workspace) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
         if (!detectedAgents.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.mcpSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                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}"`,
-            });
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "mcpServers",
+            entryName: entry.name,
+            targetAgentIds: entry.agents,
+            scope: entry.scope,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
             continue;
         }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `mcpServers: agent "${agentId}" MCP support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        const support = resolveCapabilitySurface(agentId, "mcpServers", entry.scope).support;
+        if (!support)
             continue;
-        }
         validateMcpServerConfigShape(entry.config, entry.name, agentId);
-        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const resolvedTarget = path.resolve(rawTarget);
-        const confidence = agent.provenance.mcpConfig ?? "provisional";
+        const confidence = plan.confidence ?? "provisional";
         const mcpPatchKey = support.mcpPatchKey ?? "mcpServers";
         actions.push(buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPatchKey));
     }
     return { actions, warnings };
 }
-export function compileMcpServerReverts(entry, agentFilter, home, repo) {
+export function compileMcpServerReverts(entry, agentFilter, home, repo, workspace) {
     const actions = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.mcpSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
+        const support = resolveCapabilitySurface(agentId, "mcpServers", entry.scope).support;
+        if (!support)
             continue;
-        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const target = path.resolve(rawTarget);
         if (isMarkdownTarget(target)) {
             actions.push({

package/dist/{core → src/core}/adapters/permissions.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validatePermissionsConfigShape } from "../validation.js";
 function isTomlTarget(targetPath) {
@@ -12,26 +12,25 @@ export function compilePermissionsActions(entry, detectedAgents, home) {
     for (const agentId of entry.agents) {
         if (!detectedAgents.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.permissionsSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                message: `permissions: agent "${agentId}" ${support?.status === "unsupported" ? support.reason : "does not expose a supported permissions adapter"} — skipping "${entry.name}"`,
-            });
+        const plan = planCapabilityForDeploy({
+            agentId,
+            capability: "permissions",
+            entryName: entry.name,
+            targetAgentIds: entry.agents,
+        });
+        if (plan.outcome === "warn") {
+            warnings.push(plan.warning);
             continue;
         }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `permissions: agent "${agentId}" permissions support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
+        if (plan.outcome === "native" || plan.outcome === "redundant")
+            continue;
+        const support = resolveCapabilitySurface(agentId, "permissions").support;
+        if (!support)
             continue;
-        }
         validatePermissionsConfigShape(entry.config, entry.name, agentId);
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const resolvedTarget = path.resolve(rawTarget);
-        const confidence = agent.provenance.permissions ?? "provisional";
+        const confidence = plan.confidence ?? "provisional";
         if (isTomlTarget(resolvedTarget)) {
             actions.push({
                 kind: "toml-patch",
@@ -61,11 +60,8 @@ export function compilePermissionsReverts(entry, agentFilter, home) {
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.permissionsSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
+        const support = resolveCapabilitySurface(agentId, "permissions").support;
+        if (!support)
             continue;
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const target = path.resolve(rawTarget);

package/dist/{core → src/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, repo?: string): Promise<RulesAdapterResult>;
-export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string): FileWriteRevertAction[];
+export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<RulesAdapterResult>;
+export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

package/dist/src/core/adapters/rules.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, allTargetAgentIds) {
+    const plan = planCapabilityForDeploy({
+        agentId,
+        capability: "agentRules",
+        entryName: entry.name,
+        targetAgentIds: allTargetAgentIds ?? [agentId],
+        scope: entry.scope,
+    });
+    if (plan.outcome === "warn")
+        return plan.warning;
+    if (plan.outcome === "native" || plan.outcome === "redundant")
+        return null;
+    const surface = resolveCapabilitySurface(agentId, "agentRules", entry.scope);
+    const support = surface.support;
+    if (entry.scope === "repo" && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentRules: scope "repo" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    if (entry.scope === "workspace" && !workspace && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentRules: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
+    return {
+        agentId,
+        confidence: plan.confidence,
+        target: resolvePlaceholders(support?.path[platform] ?? [], entry.name, home, repo, workspace),
+    };
+}
+export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
+    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 };
+    }
+    for (const agentId of targetAgents) {
+        const result = resolveAgentTarget(agentId, entry, home, repo, platform, workspace, targetAgents);
+        if (result === null) {
+            continue;
+        }
+        if ("kind" in result) {
+            warnings.push(result);
+        }
+        else {
+            supportedTargets.push(result);
+        }
+    }
+    if (supportedTargets.length === 0) {
+        return { actions, warnings };
+    }
+    // Deduplicate: when a shared-via rider's primary is also in supportedTargets,
+    // skip the rider — the primary agent writes the shared surface. As a fallback,
+    // also dedup by resolved path so no target file is written twice.
+    const seenTargetPaths = new Set();
+    const dedupedTargets = [];
+    for (const t of supportedTargets) {
+        const surface = resolveCapabilitySurface(t.agentId, "agentRules", entry.scope);
+        if (surface.surfaceKind === "shared-via" &&
+            surface.sharedVia &&
+            supportedTargets.some((o) => o.agentId === surface.sharedVia && o.target === t.target)) {
+            // Primary agent is present and writes the same target — skip rider.
+            continue;
+        }
+        if (!seenTargetPaths.has(t.target)) {
+            seenTargetPaths.add(t.target);
+            dedupedTargets.push(t);
+        }
+    }
+    // Validate the shared source file only when at least one target uses the
+    // current rules 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 dedupedTargets) {
+        validateAgentRuleMarkdownPath(entry.path, target.agentId);
+        await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: target.agentId,
+            source,
+            target: target.target,
+            confidence: target.confidence,
+        });
+    }
+    return { actions, warnings };
+}
+export function compileAgentRuleReverts(entry, agentFilter, home, repo, workspace) {
+    const actions = [];
+    const platform = getPlatformKey();
+    const seenRevertTargets = new Set();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const surface = resolveCapabilitySurface(agentId, "agentRules", entry.scope);
+        const support = surface.support;
+        if (surface.supportStatus !== "supported" || !support) {
+            continue;
+        }
+        if (entry.scope === "repo" && !repo)
+            continue;
+        if (entry.scope === "workspace" && !workspace && !repo)
+            continue;
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
+        if (seenRevertTargets.has(target))
+            continue;
+        seenRevertTargets.add(target);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

package/dist/src/core/capabilities.d.ts

@@ -0,0 +1,47 @@
+import type { AgentId, AgentSurfaceSupport, CapabilityKind, Confidence, PlanWarning, SupportedAgentSurface } from "../types.ts";
+type CapabilityScope = "global" | "repo" | "workspace";
+export interface ResolvedCapabilitySurface {
+    agentId: AgentId;
+    capability: CapabilityKind;
+    supportStatus: "supported" | "unsupported" | "planned";
+    support?: SupportedAgentSurface;
+    supportRecord?: AgentSurfaceSupport;
+    confidence?: Confidence;
+    schemaLabel: string;
+    surfaceKind: "agent-specific" | "native" | "shared-via";
+    sharedVia?: AgentId;
+    requiresPrimary: boolean;
+    canDeployDirectlyWhenPrimaryAbsent: boolean;
+    includeInInitByDefault: boolean;
+    reason?: string;
+    plannedSurface?: string;
+}
+export type DeployCapabilityPlan = {
+    outcome: "action";
+    confidence?: Confidence;
+    support?: SupportedAgentSurface;
+} | {
+    outcome: "redundant";
+    confidence?: Confidence;
+    support?: SupportedAgentSurface;
+    sharedVia: AgentId;
+} | {
+    outcome: "warn";
+    warning: PlanWarning;
+} | {
+    outcome: "native";
+};
+export declare function resolveCapabilitySurface(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): ResolvedCapabilitySurface;
+export declare function planCapabilityForDeploy(opts: {
+    agentId: AgentId;
+    capability: CapabilityKind;
+    entryName: string;
+    targetAgentIds: AgentId[];
+    scope?: CapabilityScope;
+}): DeployCapabilityPlan;
+export declare function shouldInitIncludeAgent(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): boolean;
+export declare function describeCapabilityConfidence(agentId: AgentId, capability: CapabilityKind, scope?: CapabilityScope): {
+    confidence?: Confidence;
+    message: string | null;
+};
+export {};