@kuznai/inception-engine 0.17.0 → 0.18.0

package/README.md

@@ -27,6 +27,8 @@ inception-engine reads a manifest file (`inception.json`) from the target direct
 
 Managed skills overwrite their previous version. If a target exists but was not created by inception-engine, deployment refuses to replace it. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
 
+Before executing, the deploy command runs preflight analysis on instruction files: it warns when the same agent will have both global and repo `agentRules` active simultaneously, when the same source file is deployed to both scopes (duplicate-content risk), and when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk). Warnings are printed but do not block deployment.
+
 ## Agent Compatibility Matrix
 
 | Agent | ID | Skills | macOS | Linux | Windows |
@@ -49,10 +51,11 @@ Managed skills overwrite their previous version. If a target exists but was not
 | 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, 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 |
+| Global/Repo Rules Files | All agents via `scope: "global"` (home-dir) or `scope: "repo"` (project-root); antigravity always uses repo-local `.agents/rules/`; github-copilot reads CLAUDE.md natively (deploy via claude-code) | All agents |
 | Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`); other agents are warned and skipped | claude-code, codex |
 | Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`), github-copilot (`{repo}/.github/agents/{name}.agent.md`); codex is warned and skipped | All supported agents |
 | `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), `mcp-servers.json` (`mcpServers`), and agent-definition Markdown files (`agentDefinitions`); emits hints for `files/` and `configs/` directories | N/A |
+| Instruction preflight analysis | Emits `precedence` warnings when an agent has both global and repo `agentRules` active simultaneously (stacking advisory) or the same source file deployed to both scopes (duplicate-content warning); emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB | 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.
 
@@ -98,7 +101,14 @@ Create an `inception.json` file at the root of your skills directory:
     {
       "name": "my-rules",
       "path": "rules/CLAUDE.md",
-      "agents": ["claude-code"]
+      "agents": ["claude-code"],
+      "scope": "global"
+    },
+    {
+      "name": "project-rules",
+      "path": "rules/CLAUDE.md",
+      "agents": ["claude-code", "codex", "gemini-cli", "opencode"],
+      "scope": "repo"
     }
   ],
   "permissions": [
@@ -158,13 +168,27 @@ MCP server registration is supported for all agents except GitHub Copilot. Incep
 
 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:
+Each **agentRules** entry deploys a Markdown instruction file to an agent's supported instruction file location:
 
 - **name** - Unique identifier (same format as skill names)
-- **path** - Relative path to the source Markdown file within the repo; supported global rules adapters require a `.md` or `.markdown` source path
+- **path** - Relative path to the source Markdown file within the repo; supported rules adapters require a `.md` or `.markdown` source path
 - **agents** - Array of agent IDs to deploy this file to
+- **scope** - `"global"` (default) or `"repo"`. Controls which instruction surface is targeted:
+  - `"global"` — deploys to the agent's home-directory instruction file (e.g., `~/.claude/CLAUDE.md` for `claude-code`)
+  - `"repo"` — deploys to the project-root instruction file inside the deployed repository (e.g., `{repo}/CLAUDE.md` for `claude-code`)
+
+Instruction rule deployment is supported for all agents. The target path depends on the agent and the `scope`:
 
-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.
+| Agent | `scope: "global"` | `scope: "repo"` |
+|---|---|---|
+| `claude-code` | `~/.claude/CLAUDE.md` | `{repo}/CLAUDE.md` |
+| `codex` | `~/.codex/AGENTS.md` | `{repo}/AGENTS.md` |
+| `gemini-cli` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` |
+| `antigravity` | `{repo}/.agents/rules/{name}.md` | `{repo}/.agents/rules/{name}.md` |
+| `opencode` | `~/.config/opencode/AGENTS.md` | `{repo}/AGENTS.md` |
+| `github-copilot` | unsupported — reads `CLAUDE.md` natively | unsupported — deploy via `claude-code` |
+
+For `antigravity`, both scopes target the same repo-local surface (`{repo}/.agents/rules/{name}.md`) since Antigravity has no global home-directory instruction file. For `github-copilot`, no separate deployment is needed for either scope — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
 
 Each **permissions** entry deploys execution and safety-oriented configuration to an agent's permission or approval surface:
 

package/dist/config/agents.js

@@ -36,6 +36,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude", "CLAUDE.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local CLAUDE.md",
+            path: {
+                posix: ["{repo}", "CLAUDE.md"],
+                windows: ["{repo}", "CLAUDE.md"],
+            },
+        },
         permissionsSupport: {
             status: "supported",
             schemaLabel: "JSON permissions config",
@@ -88,6 +96,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".codex", "AGENTS.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local AGENTS.md",
+            path: {
+                posix: ["{repo}", "AGENTS.md"],
+                windows: ["{repo}", "AGENTS.md"],
+            },
+        },
         permissionsSupport: {
             status: "supported",
             schemaLabel: "TOML approval policy config",
@@ -138,6 +154,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".gemini", "GEMINI.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local GEMINI.md",
+            path: {
+                posix: ["{repo}", "GEMINI.md"],
+                windows: ["{repo}", "GEMINI.md"],
+            },
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -187,6 +211,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".agents", "rules", "{name}.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local Markdown rules file",
+            path: {
+                posix: ["{repo}", ".agents", "rules", "{name}.md"],
+                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+            },
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -237,6 +269,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{appdata}", "opencode", "AGENTS.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local AGENTS.md",
+            path: {
+                posix: ["{repo}", "AGENTS.md"],
+                windows: ["{repo}", "AGENTS.md"],
+            },
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -279,6 +319,11 @@ export const AGENT_REGISTRY = [
             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',
         },
+        agentRulesRepoSupport: {
+            status: "unsupported",
+            schemaLabel: "repo-local CLAUDE.md",
+            reason: 'GitHub Copilot reads CLAUDE.md natively, so deploy via the "claude-code" agentRules target with scope: "repo" instead of a separate rules surface',
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",

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

@@ -1,16 +1,28 @@
 /**
- * Serializes a flat (one-level) object to a YAML block suitable for use inside
- * `---` frontmatter delimiters.
+ * Splits a Markdown string into YAML frontmatter and the remaining body.
+ * Expects the file to start with --- delimiter.
+ */
+export declare function splitFrontmatter(raw: string): {
+    frontmatter: string;
+    body: string;
+};
+/**
+ * Parses a Markdown string with YAML frontmatter.
+ */
+export declare function parseFrontmatterDocument<T = Record<string, unknown>>(raw: string): {
+    attributes: T;
+    body: string;
+};
+/**
+ * Serializes an object to a YAML block.
  */
 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.
+ * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export declare function readFrontmatterFile(filePath: string): Promise<{

package/dist/core/adapters/frontmatter.js

@@ -1,71 +1,52 @@
 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;
+import YAML from "yaml";
+/**
+ * Splits a Markdown string into YAML frontmatter and the remaining body.
+ * Expects the file to start with --- delimiter.
+ */
+export function splitFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        return { frontmatter: "", body: raw };
     }
-    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}: {}`;
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (closingIndex === -1) {
+        return { frontmatter: "", body: raw };
+    }
+    // Preserve the actual lines for the body to avoid normalizing line endings if not needed
+    // but for frontmatter block, we join with \n for the YAML parser
+    const frontmatter = lines.slice(1, closingIndex).join("\n");
+    const body = lines.slice(closingIndex + 1).join("\n");
+    return { frontmatter, body };
 }
-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)}`);
-        }
+/**
+ * Parses a Markdown string with YAML frontmatter.
+ */
+export function parseFrontmatterDocument(raw) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    if (!(frontmatter || raw.startsWith("---"))) {
+        return { attributes: {}, body };
     }
-    return lines.join("\n");
+    const attributes = YAML.parse(frontmatter);
+    return { attributes: (attributes || {}), body };
 }
 /**
- * Serializes a flat (one-level) object to a YAML block suitable for use inside
- * `---` frontmatter delimiters.
+ * Serializes an object to a YAML block.
  */
 export function serializeFrontmatter(data) {
-    return serializeFrontmatterAtDepth(data, "");
+    // Using a consistent indentation that matches standard YAML
+    return YAML.stringify(data, { indent: 2 }).trim();
 }
 /**
  * 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}`;
+    // 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}`;
 }
 function createAtomicTempPath(targetPath) {
     return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
@@ -73,8 +54,7 @@ function createAtomicTempPath(targetPath) {
         .slice(2)}`;
 }
 /**
- * Reads an existing `.md` file and parses its frontmatter (using the
- * `front-matter` package). Returns the parsed attributes and raw body.
+ * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export async function readFrontmatterFile(filePath) {
@@ -88,8 +68,7 @@ export async function readFrontmatterFile(filePath) {
             return { attributes: {}, body: "" };
         throw err;
     }
-    const parsed = parseFrontmatter(raw);
-    return { attributes: parsed.attributes, body: parsed.body };
+    return parseFrontmatterDocument(raw);
 }
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional

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,33 +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);
         }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `agentRules: agent "${agentId}" rules support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
-            continue;
+        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);
@@ -62,11 +82,15 @@ export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.agentRulesSupport;
+        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({
             kind: "file-write",

package/dist/core/init.js

@@ -1,4 +1,4 @@
-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";
@@ -170,7 +170,7 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
             }
         }
         namesSeen.add(name);
-        rules.push({ name, path: relPath, agents });
+        rules.push({ name, path: relPath, agents, scope: "global" });
     }
     return rules;
 }

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/validation.js

@@ -1,6 +1,7 @@
 import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { UserError } from "../errors.js";
+import { parseFrontmatterDocument } from "./adapters/frontmatter.js";
 export function sourceAccessError(err, sourcePath) {
     const code = err.code;
     if (code === "ENOENT")
@@ -147,23 +148,6 @@ export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
         throw new UserError("DEPLOY_FAILED", `agentRules entry "${manifestPath}" for agent "${agentId}" must point to a Markdown source file`);
     }
 }
-function trimMatchingQuotes(value) {
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-        return value.slice(1, -1).trim();
-    }
-    return value;
-}
-function parseSimpleFrontmatterValue(field, rawValue, manifestPath) {
-    const value = trimMatchingQuotes(rawValue.trim());
-    if (value.length === 0) {
-        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a non-empty string`);
-    }
-    if (rawValue.trim() === "|" || rawValue.trim() === ">") {
-        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a single-line string`);
-    }
-    return value;
-}
 export async function validateSkillDefinitionFile(sourcePath, manifestPath) {
     await validateSourceFile(sourcePath, `${manifestPath}/SKILL.md`);
     let raw;
@@ -181,27 +165,26 @@ export async function validateSkillDefinitionFile(sourcePath, manifestPath) {
     if (closingIndex === -1) {
         throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md is missing the closing --- frontmatter delimiter`);
     }
-    let name = null;
-    let description = null;
-    for (const line of lines.slice(1, closingIndex)) {
-        const trimmed = line.trim();
-        if (trimmed.length === 0 || trimmed.startsWith("#"))
-            continue;
-        const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
-        if (!match)
-            continue;
-        const [, key, rawValue] = match;
-        if (key === "name") {
-            name = parseSimpleFrontmatterValue("name", rawValue, manifestPath);
-        }
-        else if (key === "description") {
-            description = parseSimpleFrontmatterValue("description", rawValue, manifestPath);
-        }
-    }
-    if (name === null) {
-        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "name" field`);
+    let attributes;
+    try {
+        const parsed = parseFrontmatterDocument(raw);
+        attributes = parsed.attributes;
     }
-    if (description === null) {
-        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "description" field`);
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md has malformed YAML frontmatter: ${err instanceof Error ? err.message : String(err)}`);
     }
+    const validateField = (field) => {
+        const value = attributes[field];
+        if (value === undefined || value === null) {
+            throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "${field}" field`);
+        }
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a non-empty string`);
+        }
+        if (value.includes("\n") || value.includes("\r")) {
+            throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a single-line string`);
+        }
+    };
+    validateField("name");
+    validateField("description");
 }

package/dist/schemas/manifest.d.ts

@@ -71,6 +71,10 @@ export declare const AgentRuleEntrySchema: z.ZodObject<{
         "github-copilot": "github-copilot";
     }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
     path: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<{
+        global: "global";
+        repo: "repo";
+    }>>;
 }, z.core.$strip>;
 export declare const PermissionsEntrySchema: z.ZodObject<{
     name: z.ZodString;
@@ -158,6 +162,10 @@ export declare const ManifestSchema: z.ZodObject<{
             "github-copilot": "github-copilot";
         }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
         path: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<{
+            global: "global";
+            repo: "repo";
+        }>>;
     }, z.core.$strip>>>;
     permissions: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;

package/dist/schemas/manifest.js

@@ -89,6 +89,10 @@ export const AgentRuleEntrySchema = z.object({
     agents: agentsField,
     // Relative path to the rules/instruction file within the source bundle.
     path: sourcePathField,
+    // Deployment scope: "global" targets the agent's home-directory instruction
+    // file (default), "repo" targets the project-root instruction file within the
+    // deployed repository (e.g. {repo}/CLAUDE.md for claude-code).
+    scope: z.enum(["global", "repo"]).default("global"),
 });
 export const PermissionsEntrySchema = z.object({
     name: nameField,
@@ -102,8 +106,8 @@ export const AgentDefinitionEntrySchema = z.object({
     name: nameField,
     agents: agentsField,
     // Relative path to the agent definition Markdown file within the source bundle.
-    // Must be a .md or .markdown file containing YAML frontmatter that describes
-    // the agent's persona, instructions, and any tool configuration.
+    // Must be a .md or .markdown file. Content and frontmatter structure are not
+    // validated by inception-engine — format requirements are agent-specific.
     path: sourcePathField,
 });
 export const ManifestSchema = z.object({

package/dist/types.d.ts

@@ -55,6 +55,7 @@ export interface AgentConfig {
     provenance: AgentProvenance;
     mcpSupport?: AgentSurfaceSupport;
     agentRulesSupport?: AgentSurfaceSupport;
+    agentRulesRepoSupport?: AgentSurfaceSupport;
     permissionsSupport?: AgentSurfaceSupport;
     agentDefinitionsSupport?: AgentSurfaceSupport;
     policyNote?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -47,8 +47,8 @@
     "test:posix": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/posix/*.test.ts"
   },
   "dependencies": {
-    "front-matter": "^4.0.2",
     "smol-toml": "^1.6.1",
+    "yaml": "^2.8.3",
     "zod": "^4.0.0"
   },
   "devDependencies": {