@kuznai/inception-engine 0.16.0 → 0.18.0

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

@@ -1,12 +1,13 @@
-import type { AgentRuleEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
+import type { AgentDefinitionEntry, AgentRuleEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
 import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, FrontmatterEmitDeployAction, PlanWarning, TomlPatchDeployAction } from "../../types.ts";
+import { compileAgentDefinitionReverts } from "./agent-definitions.ts";
 import { compileMcpServerReverts } from "./mcp.ts";
 import { compilePermissionsReverts } from "./permissions.ts";
 import { compileAgentRuleReverts } from "./rules.ts";
-export { compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
 export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction;
 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): 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[]): Promise<AdapterResult>;

package/dist/core/adapters/index.js

@@ -1,8 +1,9 @@
+import { compileAgentDefinitionActions, compileAgentDefinitionReverts, } from "./agent-definitions.js";
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
-export { compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions) {
     const actions = [];
     const warnings = [];
     for (const entry of mcpServers) {
@@ -20,5 +21,10 @@ export async function compileAdapterActions(mcpServers, agentRules, permissions,
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
+    for (const entry of agentDefinitions ?? []) {
+        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
+        actions.push(...r.actions);
+        warnings.push(...r.warnings);
+    }
     return { actions, warnings };
 }

package/dist/core/adapters/mcp.js

@@ -62,6 +62,13 @@ export function compileMcpServerActions(entry, detectedAgents, home, repo) {
             });
             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`,
+            });
+            continue;
+        }
         validateMcpServerConfigShape(entry.config, entry.name, agentId);
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
         const resolvedTarget = path.resolve(rawTarget);
@@ -79,7 +86,9 @@ export function compileMcpServerReverts(entry, agentFilter, home, repo) {
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
         const support = agent?.mcpSupport;
-        if (!support || support.status === "unsupported")
+        if (!support ||
+            support.status === "unsupported" ||
+            support.status === "planned")
             continue;
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
         const target = path.resolve(rawTarget);

package/dist/core/adapters/permissions.js

@@ -21,6 +21,13 @@ export function compilePermissionsActions(entry, detectedAgents, home) {
             });
             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`,
+            });
+            continue;
+        }
         validatePermissionsConfigShape(entry.config, entry.name, agentId);
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const resolvedTarget = path.resolve(rawTarget);
@@ -56,7 +63,9 @@ export function compilePermissionsReverts(entry, agentFilter, home) {
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
         const support = agent?.permissionsSupport;
-        if (!support || support.status === "unsupported")
+        if (!support ||
+            support.status === "unsupported" ||
+            support.status === "planned")
             continue;
         const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home);
         const target = path.resolve(rawTarget);

package/dist/core/adapters/rules.js

@@ -2,6 +2,40 @@ import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validateAgentRuleMarkdownPath, validateSourceFile, validateSourcePath, } from "../validation.js";
+function resolveRulesSupport(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "repo") {
+        return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
+    }
+    return agent?.agentRulesSupport;
+}
+function resolveAgentTarget(agentId, entry, home, repo, platform) {
+    const support = resolveRulesSupport(agentId, entry.scope);
+    if (!support || support.status === "unsupported") {
+        return {
+            kind: "confidence",
+            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}"`,
+        };
+    }
+    if (support.status === "planned") {
+        return {
+            kind: "confidence",
+            message: `agentRules: agent "${agentId}" rules support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
+        };
+    }
+    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}"`,
+        };
+    }
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    return {
+        agentId,
+        confidence: agent?.provenance.agentRules ?? "provisional",
+        target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
+    };
+}
 export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
     const actions = [];
     const warnings = [];
@@ -12,26 +46,19 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
         return { actions, warnings };
     }
     for (const agentId of targetAgents) {
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.agentRulesSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                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 result = resolveAgentTarget(agentId, entry, home, repo, platform);
+        if ("kind" in result) {
+            warnings.push(result);
+        }
+        else {
+            supportedTargets.push(result);
         }
-        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.
+    // current rules adapter surface.
     const source = path.resolve(sourceDir, entry.path);
     await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
     await validateSourceFile(source, entry.path);
@@ -55,8 +82,14 @@ export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.agentRulesSupport;
-        if (!support || support.status === "unsupported")
+        const support = entry.scope === "repo"
+            ? (agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport)
+            : agent?.agentRulesSupport;
+        if (!support ||
+            support.status === "unsupported" ||
+            support.status === "planned")
+            continue;
+        if (entry.scope === "repo" && !repo)
             continue;
         const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
         actions.push({

package/dist/core/deploy.js

@@ -91,7 +91,7 @@ function detectAmbiguities(detectedAgents, manifest) {
         if (bothAgents(entry.agents)) {
             warnings.push({
                 kind: "ambiguity",
-                message: `Both "gemini-cli" and "antigravity" are listed in agentRules entry "${entry.name}". They share a GEMINI.md-backed instruction shared surface — verify that deploying to both does not create conflicting behavior.`,
+                message: `Both "gemini-cli" and "antigravity" are listed in agentRules entry "${entry.name}". They write to distinct surfaces ("gemini-cli" → ~/.gemini/GEMINI.md, "antigravity" → {repo}/.agents/rules/${entry.name}.md) from the same source file — verify that deploying to both produces the intended behavior on each agent.`,
             });
         }
     }
@@ -119,6 +119,8 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
+            if (!agent.skills)
+                continue;
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
@@ -126,7 +128,7 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
                 source,
                 target: resolveAgentSkillPath(agent, skill.name, home),
                 method,
-                confidence: agent.provenance.skills,
+                confidence: agent.provenance.skills ?? "provisional",
             });
         }
     }
@@ -192,7 +194,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
         ...planConfigPatchActions(manifest, detectedAgents, home),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, undefined, manifest.agentDefinitions ?? []);
     actions.push(...adapterResult.actions);
     const warnings = [
         ...detectAmbiguities(detectedAgents, manifest),

package/dist/core/init.js

@@ -1,8 +1,8 @@
-import { access, readFile, readdir, writeFile } from "node:fs/promises";
+import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { dryRunPrefix, logger } from "../logger.js";
-import { AGENT_IDS, ConfigEntrySchema, FileEntrySchema, McpServerEntrySchema, } from "../schemas/manifest.js";
+import { AGENT_IDS, AgentDefinitionEntrySchema, ConfigEntrySchema, FileEntrySchema, McpServerEntrySchema, } from "../schemas/manifest.js";
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 // Ordered list: first match wins. Catch-all is applied at call site.
 const AGENT_RULES_FILE_PATTERNS = [
@@ -27,6 +27,16 @@ const AGENT_RULES_SUBDIRS = [
     ".github",
     ".agents/rules",
 ];
+// Conventional subdirectories that contain agent definition files.
+// These are the agent-specific directories that each agent scans for
+// subagent/persona definitions at runtime.
+const AGENT_DEFINITION_SUBDIRS = [
+    ".claude/agents",
+    ".gemini/agents",
+    ".agents/rules",
+    ".opencode/agents",
+    ".github/agents",
+];
 async function findSkillDirs(baseDir, dir, found) {
     let entries;
     try {
@@ -160,10 +170,121 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
             }
         }
         namesSeen.add(name);
-        rules.push({ name, path: relPath, agents });
+        rules.push({ name, path: relPath, agents, scope: "global" });
     }
     return rules;
 }
+/**
+ * Derives the name for an agent definition entry from its file name.
+ * For GitHub Copilot's `{name}.agent.md` naming convention, strips the
+ * `.agent` infix in addition to the `.md` extension.
+ */
+function deriveAgentDefinitionName(relPath, fileName) {
+    const ext = path.extname(fileName).toLowerCase();
+    // Strip the extension to get the base name, then strip any trailing ".agent"
+    // suffix (GitHub Copilot convention: foo.agent.md → foo).
+    let baseName = path.basename(fileName, ext);
+    if (baseName.endsWith(".agent")) {
+        baseName = baseName.slice(0, -".agent".length);
+    }
+    const rawName = baseName.toLowerCase().replace(/[^a-zA-Z0-9._-]/g, "-");
+    if (!SAFE_NAME_RE.test(rawName)) {
+        logger.warn("init", `Skipping "${relPath}": could not derive a valid agentDefinitions name`);
+        return null;
+    }
+    return rawName;
+}
+/**
+ * Maps a known agent-definition subdirectory to the agent IDs that own it.
+ * Returns null when the subdir is not agent-specific (fall back to all agents
+ * that support agentDefinitions).
+ */
+function agentsForDefinitionSubdir(subdir) {
+    switch (subdir) {
+        case ".claude/agents":
+            return ["claude-code"];
+        case ".gemini/agents":
+            return ["gemini-cli"];
+        case ".agents/rules":
+            return ["antigravity"];
+        case ".opencode/agents":
+            return ["opencode"];
+        case ".github/agents":
+            return ["github-copilot"];
+        default:
+            return null;
+    }
+}
+async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, agentRulesRelPaths, candidates) {
+    const suggestedAgents = agentsForDefinitionSubdir(subdir) ?? [];
+    const dir = path.join(baseDir, subdir);
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const ext = path.extname(entry.name).toLowerCase();
+        if (ext !== ".md" && ext !== ".markdown")
+            continue;
+        const absPath = path.join(dir, entry.name);
+        const relPath = path.relative(baseDir, absPath).split(path.sep).join("/");
+        if (seen.has(relPath) ||
+            isInsideSkillDir(relPath, skillDirRelPaths) ||
+            agentRulesRelPaths.has(relPath))
+            continue;
+        const name = deriveAgentDefinitionName(relPath, entry.name);
+        if (name === null)
+            continue;
+        seen.add(relPath);
+        candidates.push({ relPath, name, suggestedAgents });
+    }
+}
+async function findAgentDefinitionCandidates(baseDir, skillDirRelPaths, agentRulesRelPaths) {
+    const candidates = [];
+    const seen = new Set();
+    for (const subdir of AGENT_DEFINITION_SUBDIRS) {
+        await scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, agentRulesRelPaths, candidates);
+    }
+    return candidates;
+}
+function buildAgentDefinitions(candidates, activeAgents, namesSeen) {
+    const definitions = [];
+    const localNamesSeen = new Set(namesSeen);
+    const definitionsCapableAgents = activeAgents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentDefinitionsSupport?.status !==
+        "unsupported");
+    for (const { relPath, name: rawName, suggestedAgents } of candidates) {
+        // Use suggested agents (from the dir that was scanned), intersected with
+        // active agents that support agentDefinitions. Fall back to all capable
+        // agents if the intersection is empty.
+        const intersection = suggestedAgents.length > 0
+            ? suggestedAgents.filter((a) => definitionsCapableAgents.includes(a))
+            : [];
+        const agents = intersection.length > 0 ? intersection : definitionsCapableAgents;
+        if (agents.length === 0)
+            continue;
+        // Resolve name collision
+        let name = rawName;
+        if (localNamesSeen.has(name)) {
+            const candidate = `${name}-agent`;
+            if (SAFE_NAME_RE.test(candidate)) {
+                logger.warn("init", `agentDefinitions name "${name}" collides with an existing name; using "${candidate}"`);
+                name = candidate;
+            }
+            else {
+                logger.warn("init", `Skipping "${relPath}": name "${name}" collides and fallback is invalid`);
+                continue;
+            }
+        }
+        localNamesSeen.add(name);
+        definitions.push({ name, path: relPath, agents });
+    }
+    return definitions;
+}
 async function loadMcpServers(baseDir) {
     const filePath = path.join(baseDir, "mcp-servers.json");
     let raw;
@@ -263,6 +384,39 @@ async function loadConfigsManifest(baseDir) {
     }
     return results;
 }
+async function loadAgentDefinitionsManifest(baseDir) {
+    const filePath = path.join(baseDir, "agent-definitions-manifest.json");
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        logger.warn("init", "agent-definitions-manifest.json: invalid JSON, skipping");
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        logger.warn("init", "agent-definitions-manifest.json: expected a JSON array, skipping");
+        return [];
+    }
+    const results = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const result = AgentDefinitionEntrySchema.safeParse(parsed[i]);
+        if (result.success) {
+            results.push(result.data);
+        }
+        else {
+            logger.warn("init", `agent-definitions-manifest.json: entry[${i}] invalid, skipping`);
+        }
+    }
+    return results;
+}
 async function emitDirectoryHints(baseDir, filesLoaded, configsLoaded) {
     for (const [dir, section, loaded, sidecar] of [
         ["files", "files", filesLoaded, "files-manifest.json"],
@@ -288,16 +442,20 @@ async function manifestExists(manifestPath) {
         return false;
     }
 }
-function logVerboseManifest(skills, agentRules, mcpServers, files, configs) {
+function logPathAgentEntries(label, entries) {
+    if (entries.length === 0)
+        return;
+    logger.detail(`${label}:`);
+    for (const e of entries) {
+        logger.detail(`  ${e.name}  →  ${e.path}  [${e.agents.join(", ")}]`);
+    }
+}
+function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agentDefinitions) {
     for (const s of skills) {
         logger.detail(`${s.name}  →  ${s.path}`);
     }
-    if (agentRules.length > 0) {
-        logger.detail("agentRules:");
-        for (const r of agentRules) {
-            logger.detail(`  ${r.name}  →  ${r.path}  [${r.agents.join(", ")}]`);
-        }
-    }
+    logPathAgentEntries("agentRules", agentRules);
+    logPathAgentEntries("agentDefinitions", agentDefinitions);
     if (mcpServers.length > 0) {
         logger.detail("mcpServers:");
         for (const m of mcpServers) {
@@ -336,6 +494,16 @@ export async function runInit(options) {
     const skillDirRelPaths = new Set(found.map((f) => f.relPath));
     const agentRulesCandidates = await findAgentRulesCandidates(directory, skillDirRelPaths);
     const agentRules = buildAgentRules(agentRulesCandidates, agentRulesCapableAgents, skillNamesSeen);
+    const allNamesSeen = new Set([
+        ...skillNamesSeen,
+        ...agentRules.map((r) => r.name),
+    ]);
+    const agentRulesRelPaths = new Set(agentRules.map((r) => r.path));
+    const agentDefinitionCandidates = await findAgentDefinitionCandidates(directory, skillDirRelPaths, agentRulesRelPaths);
+    const discoveredDefinitions = buildAgentDefinitions(agentDefinitionCandidates, agents, allNamesSeen);
+    // Sidecar file overrides take precedence over auto-discovery
+    const sidecarDefinitions = await loadAgentDefinitionsManifest(directory);
+    const agentDefinitions = sidecarDefinitions.length > 0 ? sidecarDefinitions : discoveredDefinitions;
     const mcpServers = await loadMcpServers(directory);
     const files = await loadFilesManifest(directory);
     const configs = await loadConfigsManifest(directory);
@@ -345,12 +513,14 @@ export async function runInit(options) {
         configs,
         mcpServers,
         agentRules,
+        agentDefinitions,
     };
     const json = `${JSON.stringify(manifest, null, 2)}\n`;
     function summarize() {
         const parts = [
             `${skills.length} skill(s)`,
             `${agentRules.length} agentRule(s)`,
+            `${agentDefinitions.length} agentDefinition(s)`,
             `${mcpServers.length} mcpServer(s)`,
             `${files.length} file(s)`,
             `${configs.length} config(s)`,
@@ -367,7 +537,7 @@ export async function runInit(options) {
     await writeFile(manifestPath, json, "utf-8");
     logger.info(`Generated ${manifestPath} with ${summarize()}.`);
     if (verbose) {
-        logVerboseManifest(skills, agentRules, mcpServers, files, configs);
+        logVerboseManifest(skills, agentRules, mcpServers, files, configs, agentDefinitions);
     }
     await emitDirectoryHints(directory, files.length, configs.length);
     return 0;

package/dist/core/preflight.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId, CliOptions, Manifest } from "../types.ts";
 export interface PreflightWarning {
-    kind: "policy" | "config-authority" | "info";
+    kind: "policy" | "config-authority" | "info" | "precedence" | "budget";
     message: string;
 }
-export declare function runPreflight(_options: CliOptions, _manifest: Manifest, _home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;
+export declare function runPreflight(options: CliOptions, manifest: Manifest, _home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;

package/dist/core/preflight.js

@@ -1,5 +1,73 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
-export async function runPreflight(_options, _manifest, _home, detectedAgents) {
+const BUDGET_WARN_BYTES = 50 * 1024; // 50 KB
+function detectInstructionPrecedence(detectedAgents, manifest) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
+        const globalEntries = rulesForAgent.filter((e) => (e.scope ?? "global") === "global");
+        const repoEntries = rulesForAgent.filter((e) => e.scope === "repo");
+        if (globalEntries.length === 0 || repoEntries.length === 0)
+            continue;
+        const globalPaths = new Set(globalEntries.map((e) => e.path));
+        for (const entry of repoEntries) {
+            if (globalPaths.has(entry.path)) {
+                warnings.push({
+                    kind: "precedence",
+                    message: `Agent "${agentId}" has agentRules entry "${entry.name}" deployed to both global and repo scope from the same source path "${entry.path}". The file will be written to two distinct targets — verify this is intentional and not a copy-paste mistake.`,
+                });
+            }
+        }
+        const nonOverlapRepo = repoEntries.filter((e) => !globalPaths.has(e.path));
+        if (nonOverlapRepo.length > 0) {
+            const globalNames = globalEntries.map((e) => `"${e.name}"`).join(", ");
+            const repoNames = nonOverlapRepo.map((e) => `"${e.name}"`).join(", ");
+            warnings.push({
+                kind: "precedence",
+                message: `Agent "${agentId}" will have both global and repo instruction files active simultaneously: global [${globalNames}] and repo [${repoNames}]. Both will be loaded by the agent — ensure the content is intended to stack and does not conflict.`,
+            });
+        }
+    }
+    return warnings;
+}
+async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir) {
+    const warnings = [];
+    const checkedPaths = new Set();
+    async function checkEntry(entryPath, label, agentIds) {
+        if (!agentIds.some((id) => detectedAgents.includes(id)))
+            return;
+        const sourcePath = path.resolve(sourceDir, entryPath);
+        if (checkedPaths.has(sourcePath))
+            return;
+        checkedPaths.add(sourcePath);
+        try {
+            const fileStat = await stat(sourcePath);
+            if (fileStat.size > BUDGET_WARN_BYTES) {
+                const sizeKb = (fileStat.size / 1024).toFixed(1);
+                warnings.push({
+                    kind: "budget",
+                    message: `${label} source "${entryPath}" is ${sizeKb} KB — large instruction files risk crowding out code context in the agent's context window. Consider splitting into smaller focused files.`,
+                });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
+                throw err;
+            // Missing/unreadable files are silently skipped; compileAgentRuleActions
+            // will produce the proper UserError during action compilation.
+        }
+    }
+    for (const entry of manifest.agentRules ?? []) {
+        await checkEntry(entry.path, "agentRules", entry.agents);
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        await checkEntry(entry.path, "agentDefinitions", entry.agents);
+    }
+    return warnings;
+}
+export async function runPreflight(options, manifest, _home, detectedAgents) {
     const warnings = [];
     for (const agentId of detectedAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
@@ -24,5 +92,7 @@ export async function runPreflight(_options, _manifest, _home, detectedAgents) {
             });
         }
     }
+    warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
+    warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
     return warnings;
 }

package/dist/core/resolve.js

@@ -85,6 +85,10 @@ export function getDeployMethod() {
     return process.platform === "win32" ? "copy" : "symlink";
 }
 export function resolveAgentSkillPathFor(agent, skillName, home, platform) {
+    if (!agent.skills) {
+        throw new Error(`Agent "${agent.id}" does not have a skills deployment path. ` +
+            `Deploy skills via another agent target that covers this agent natively (e.g. claude-code for github-copilot).`);
+    }
     return resolvePlaceholders(agent.skills[platform], skillName, home);
 }
 export function resolveAgentDetectPathFor(agent, home, platform) {

package/dist/core/revert.js

@@ -1,7 +1,7 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
-import { compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
+import { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, } from "./adapters/index.js";
 import { revertTomlMcpPatch } from "./adapters/toml.js";
 import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
@@ -15,6 +15,8 @@ function buildSkillDirReverts(manifest, home, agentFilter) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
+            if (!agent.skills)
+                continue;
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
@@ -71,6 +73,7 @@ export function planRevert(manifest, detectedAgents, home, repo) {
         ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home, repo)),
         ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home, repo)),
         ...(manifest.permissions ?? []).flatMap((e) => compilePermissionsReverts(e, detectedAgents, home)),
+        ...(manifest.agentDefinitions ?? []).flatMap((e) => compileAgentDefinitionReverts(e, detectedAgents, home, repo)),
     ];
 }
 export function planRevertAll(manifest, home, repo) {
@@ -81,6 +84,7 @@ export function planRevertAll(manifest, home, repo) {
         ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home, repo)),
         ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home, repo)),
         ...(manifest.permissions ?? []).flatMap((e) => compilePermissionsReverts(e, null, home)),
+        ...(manifest.agentDefinitions ?? []).flatMap((e) => compileAgentDefinitionReverts(e, null, home, repo)),
     ];
 }
 function recordOutcome(result, action, counts, failed) {