@kuznai/inception-engine 0.11.1 → 0.12.0

package/README.md

@@ -128,17 +128,17 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 
 - **name** - Unique identifier (same format as skill names); used as the server's key in the config
 - **agents** - Array of agent IDs to register this server with
-- **config** - Raw server descriptor object (e.g. `{ "command": "...", "args": [...] }` for stdio transport). The exact shape is passed through verbatim; agent adapters handle agent-specific requirements.
+- **config** - Raw server descriptor object. For the currently supported JSON-backed adapters, inception-engine requires at least one non-empty `command` or `url` field, validates `args` as an array of strings when present, and validates `env` as a string-to-string object when present. Additional keys are passed through verbatim.
 
-MCP server registration is currently supported for `claude-code` (`~/.claude.json`) and `gemini-cli` (`~/.gemini/settings.json`). Other agents emit a warning and are skipped. Revert removes the registered server entry from the config file.
+MCP server registration is currently supported for `claude-code` (`~/.claude.json`) and `gemini-cli` (`~/.gemini/settings.json`). Other agents emit a schema-aware warning and are skipped when their support would require a non-JSON adapter, such as Codex `config.toml`, Antigravity frontmatter in repo-scoped rules files, OpenCode `opencode.json`, or GitHub Copilot repo-scoped MCP surfaces. Revert removes the registered server entry from the config file.
 
 Each **agentRules** entry deploys a Markdown instruction file to an agent's supported global rules file location:
 
 - **name** - Unique identifier (same format as skill names)
-- **path** - Relative path to the source Markdown file within the repo
+- **path** - Relative path to the source Markdown file within the repo; supported global rules adapters require a `.md` or `.markdown` source path
 - **agents** - Array of agent IDs to deploy this file to
 
-Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Other agents emit a warning and are skipped because their instruction surfaces are different, repo-scoped, or not yet implemented. Revert removes the deployed rules file.
+Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Other agents emit schema-aware warnings and are skipped when their instruction surfaces are repo-scoped, frontmatter-driven, or otherwise not implemented as a single global Markdown file. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -155,7 +155,7 @@ description: What this skill does and when to use it
 Instructions for the AI agent...
 ```
 
-The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine does not currently validate the frontmatter — missing or malformed fields may cause the skill to be ignored or misbehave at the agent level.
+The `name` and `description` fields in the frontmatter are used by most agents. The description determines when the agent activates the skill. inception-engine now validates this minimum contract during deploy: `SKILL.md` must start with YAML frontmatter and include non-empty single-line `name` and `description` fields. It still does not attempt full YAML/schema validation beyond that targeted check.
 
 ## `init` Command
 
@@ -171,7 +171,7 @@ Current `init` behavior:
 
 Current `init` limitations:
 
-- It does not read or validate YAML frontmatter inside `SKILL.md`
+- It does not reconcile generated manifest entries against `SKILL.md` frontmatter values
 - It does not infer `files`, `configs`, `mcpServers`, or `agentRules`
 - It does not reconcile generated output with the longer-term Claude-first portability direction
 

package/dist/config/agents.js

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

package/dist/core/adapters/mcp.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+import { validateMcpServerConfigShape } from "../validation.js";
 export function compileMcpServerActions(entry, detectedAgents, home) {
     const actions = [];
     const warnings = [];
@@ -9,14 +10,16 @@ export function compileMcpServerActions(entry, detectedAgents, home) {
         if (!detectedAgents.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent?.mcpConfigPath) {
+        const support = agent?.mcpSupport;
+        if (!support || support.status === "unsupported") {
             warnings.push({
                 kind: "confidence",
-                message: `mcpServers: agent "${agentId}" does not have a documented MCP config path — skipping "${entry.name}"`,
+                message: `mcpServers: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported MCP schema"} and ${support?.reason ?? "does not expose a supported MCP adapter"} — skipping "${entry.name}"`,
             });
             continue;
         }
-        const target = resolvePlaceholders(agent.mcpConfigPath[platform], "", home);
+        validateMcpServerConfigShape(entry.config, entry.name, agentId);
+        const target = resolvePlaceholders(support.path[platform], "", home);
         // Ensure no stray empty segments collapse the path unexpectedly
         const resolvedTarget = path.resolve(target);
         actions.push({
@@ -37,9 +40,10 @@ export function compileMcpServerReverts(entry, agentFilter, home) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent?.mcpConfigPath)
+        const support = agent?.mcpSupport;
+        if (!support || support.status === "unsupported")
             continue;
-        const target = path.resolve(resolvePlaceholders(agent.mcpConfigPath[platform], "", home));
+        const target = path.resolve(resolvePlaceholders(support.path[platform], "", home));
         actions.push({
             kind: "config-patch",
             skill: entry.name,

package/dist/core/adapters/rules.js

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

package/dist/core/deploy.js

@@ -8,7 +8,7 @@ import { compileAdapterActions } from "./adapters/index.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
-import { sourceAccessError, validateSourceFile, validateSourcePath, } from "./validation.js";
+import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -505,6 +505,7 @@ async function validateSkillContract(source, skillPath) {
         }
         throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`);
     }
+    await validateSkillDefinitionFile(path.join(source, "SKILL.md"), skillPath);
 }
 async function assertTargetAbsent(targetPath) {
     try {

package/dist/core/validation.d.ts

@@ -1,3 +1,6 @@
 export declare function sourceAccessError(err: unknown, sourcePath: string): string;
 export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
 export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;
+export declare function validateMcpServerConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
+export declare function validateAgentRuleMarkdownPath(manifestPath: string, agentId: string): void;
+export declare function validateSkillDefinitionFile(sourcePath: string, manifestPath: string): Promise<void>;

package/dist/core/validation.js

@@ -1,4 +1,4 @@
-import { lstat, realpath, stat } from "node:fs/promises";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { UserError } from "../errors.js";
 export function sourceAccessError(err, sourcePath) {
@@ -64,3 +64,99 @@ export async function validateSourceFile(sourcePath, manifestPath) {
         throw new UserError("DEPLOY_FAILED", `Source is not a file: ${manifestPath}`);
     }
 }
+function isRecordOfStrings(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function validateNonEmptyStringField(value, field, entryName, agentId) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "${field}" as a non-empty string`);
+    }
+}
+export function validateMcpServerConfigShape(config, entryName, agentId) {
+    const hasCommand = Object.hasOwn(config, "command");
+    const hasUrl = Object.hasOwn(config, "url");
+    if (!(hasCommand || hasUrl)) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define either a non-empty "command" or "url"`);
+    }
+    if (hasCommand) {
+        validateNonEmptyStringField(config.command, "command", entryName, agentId);
+    }
+    if (hasUrl) {
+        validateNonEmptyStringField(config.url, "url", entryName, agentId);
+    }
+    if (Object.hasOwn(config, "args") &&
+        (!Array.isArray(config.args) ||
+            config.args.some((arg) => typeof arg !== "string"))) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "args" as an array of strings when present`);
+    }
+    if (Object.hasOwn(config, "env") && !isRecordOfStrings(config.env)) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "env" as an object of string values when present`);
+    }
+}
+export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
+    const extension = path.extname(manifestPath).toLowerCase();
+    if (extension !== ".md" && extension !== ".markdown") {
+        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;
+    try {
+        raw = await readFile(sourcePath, "utf-8");
+    }
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", sourceAccessError(err, `${manifestPath}/SKILL.md`));
+    }
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md must start with YAML frontmatter delimited by ---`);
+    }
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    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`);
+    }
+    if (description === null) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "description" field`);
+    }
+}

package/dist/types.d.ts

@@ -5,6 +5,17 @@ export interface AgentPaths {
     windows: string[];
 }
 export type Confidence = "documented" | "implementation-only" | "provisional";
+export interface SupportedAgentSurface {
+    status: "supported";
+    path: AgentPaths;
+    schemaLabel: string;
+}
+export interface UnsupportedAgentSurface {
+    status: "unsupported";
+    schemaLabel: string;
+    reason: string;
+}
+export type AgentSurfaceSupport = SupportedAgentSurface | UnsupportedAgentSurface;
 export interface AgentProvenance {
     skills: Confidence;
     detectPaths: Confidence;
@@ -19,9 +30,8 @@ export interface AgentConfig {
     detectPaths: AgentPaths;
     detectBinary: string | null;
     provenance: AgentProvenance;
-    mcpConfigPath?: AgentPaths;
-    agentRulesPath?: AgentPaths;
-    claudeNativeInstruction?: true;
+    mcpSupport?: AgentSurfaceSupport;
+    agentRulesSupport?: AgentSurfaceSupport;
     policyNote?: string;
 }
 export interface PlanWarning {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",