@kuznai/inception-engine 0.16.0 → 0.17.0

package/README.md

@@ -51,7 +51,8 @@ Managed skills overwrite their previous version. If a target exists but was not
 | 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 |
 | Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`); other agents are warned and skipped | claude-code, codex |
-| `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), and `mcp-servers.json` (`mcpServers`); emits hints for `files/` and `configs/` directories | N/A |
+| 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 |
 
 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.
 
@@ -111,6 +112,13 @@ Create an `inception.json` file at the root of your skills directory:
         }
       }
     }
+  ],
+  "agentDefinitions": [
+    {
+      "name": "code-reviewer",
+      "path": "agents/code-reviewer.md",
+      "agents": ["claude-code", "opencode", "github-copilot"]
+    }
   ]
 }
 ```
@@ -199,6 +207,23 @@ Valid `approval_policy` values are `"auto"`, `"manual"`, `"suggest"`, and `"on-f
 
 Revert restores the previous config values using the undo patch recorded at deploy time.
 
+Each **agentDefinitions** entry deploys a Markdown agent-definition file to the repo-local agent-definitions directory of each targeted agent:
+
+- **name** - Unique identifier (same format as skill names); used as the definition filename
+- **path** - Relative path to the source Markdown file within the repo; must be a `.md` or `.markdown` file
+- **agents** - Array of agent IDs to deploy this definition to
+
+Agent-definition deployment is supported for `claude-code`, `gemini-cli`, `antigravity`, `opencode`, and `github-copilot`. For `codex`, inception-engine emits a warning and skips the entry — use `agentRules` to deploy persona instructions to Codex instead.
+
+All targets are repo-local (they land inside the repository being deployed, not the user's home directory):
+- **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` (note the `.agent.md` suffix)
+
+Revert removes the deployed agent-definition file.
+
 ## Creating Skills
 
 Each skill is a directory containing at minimum a `SKILL.md` file with YAML frontmatter:
@@ -231,6 +256,7 @@ Current `init` behavior:
 - Reads `mcp-servers.json` from the repo root (if present) and generates `mcpServers` entries; invalid entries are warned and skipped
 - Reads `files-manifest.json` from the repo root (if present) and generates `files` entries; invalid entries are warned and skipped
 - Reads `configs-manifest.json` from the repo root (if present) and generates `configs` entries; invalid entries are warned and skipped
+- Reads `agent-definitions-manifest.json` from the repo root (if present) and generates `agentDefinitions` entries; if absent, auto-discovers agent-definition Markdown files from `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, and `.github/agents/`; invalid entries are warned and skipped
 - Emits guidance to create a sidecar manifest when a `files/` or `configs/` directory is detected but the corresponding sidecar file is absent
 
 Current `init` limitations:
@@ -280,6 +306,22 @@ Place a `configs-manifest.json` file at the repo root to have `init` populate th
 
 Invalid entries are warned and skipped; the rest are written into the generated manifest verbatim.
 
+Place an `agent-definitions-manifest.json` file at the repo root to have `init` populate the `agentDefinitions` section automatically. The file must be a JSON array of agent-definition entries using the same schema as the `agentDefinitions` field in `inception.json`:
+
+```json
+[
+  {
+    "name": "code-reviewer",
+    "path": "agents/code-reviewer.md",
+    "agents": ["claude-code", "opencode", "github-copilot"]
+  }
+]
+```
+
+If no `agent-definitions-manifest.json` is present, `init` auto-discovers agent-definition Markdown files from five conventional subdirectories: `.claude/agents/`, `.gemini/agents/`, `.agents/rules/`, `.opencode/agents/`, and `.github/agents/`. Each discovered file is mapped to the owning agent(s). GitHub Copilot files named `{name}.agent.md` have the `.agent` infix stripped to derive the manifest name (e.g., `foo.agent.md` → name `foo`).
+
+Invalid entries are warned and skipped; the rest are written into the generated manifest verbatim.
+
 ## CLI Reference
 
 ```

package/dist/config/agents.js

@@ -18,6 +18,7 @@ export const AGENT_REGISTRY = [
             mcpConfig: "documented",
             agentRules: "documented",
             permissions: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -43,6 +44,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude", "settings.json"],
             },
         },
+        agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition Markdown file",
+            path: {
+                posix: ["{repo}", ".claude", "agents", "{name}.md"],
+                windows: ["{repo}", ".claude", "agents", "{name}.md"],
+            },
+        },
     },
     {
         id: "codex",
@@ -87,6 +96,11 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".codex", "config.toml"],
             },
         },
+        agentDefinitionsSupport: {
+            status: "unsupported",
+            schemaLabel: "dedicated agent definition directory",
+            reason: "OpenAI Codex does not expose a documented dedicated per-agent definition directory surface separate from AGENTS.md and config.toml — use agentRules to deploy persona instructions instead",
+        },
     },
     {
         id: "gemini-cli",
@@ -106,6 +120,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             mcpConfig: "documented",
             agentRules: "documented",
+            agentDefinitions: "implementation-only",
         },
         mcpSupport: {
             status: "supported",
@@ -128,6 +143,14 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "Gemini CLI does not expose a documented global per-user permission or approval config surface",
         },
+        agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition Markdown file",
+            path: {
+                posix: ["{repo}", ".gemini", "agents", "{name}.md"],
+                windows: ["{repo}", ".gemini", "agents", "{name}.md"],
+            },
+        },
     },
     {
         id: "antigravity",
@@ -145,6 +168,8 @@ export const AGENT_REGISTRY = [
             skills: "implementation-only",
             detectPaths: "implementation-only",
             detectBinary: "provisional",
+            agentRules: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -167,6 +192,14 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "Antigravity does not expose a documented global per-user permission or approval config surface",
         },
+        agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition Markdown file",
+            path: {
+                posix: ["{repo}", ".agents", "rules", "{name}.md"],
+                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+            },
+        },
     },
     {
         id: "opencode",
@@ -185,6 +218,7 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
             agentRules: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -208,28 +242,37 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "OpenCode does not expose a documented global per-user permission or approval config surface",
         },
+        agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition Markdown file",
+            path: {
+                posix: ["{repo}", ".opencode", "agents", "{name}.md"],
+                windows: ["{repo}", ".opencode", "agents", "{name}.md"],
+            },
+        },
     },
     {
         id: "github-copilot",
         displayName: "GitHub Copilot",
-        skills: {
-            posix: ["{home}", ".copilot", "skills", "{name}"],
-            windows: ["{home}", ".copilot", "skills", "{name}"],
-        },
+        // No `skills` field: GitHub Copilot natively executes Claude-style skills
+        // from `.claude/skills/` (the same path used by claude-code). Deploying
+        // via the `claude-code` skills target automatically covers Copilot — no
+        // separate `~/.copilot/skills/` path is needed or maintained.
         detectPaths: {
             posix: ["{home}", ".copilot"],
             windows: ["{home}", ".copilot"],
         },
         detectBinary: "github-copilot",
         provenance: {
-            skills: "documented",
             detectPaths: "documented",
             detectBinary: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
-            status: "unsupported",
+            status: "planned",
             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",
+            plannedSurface: "devcontainer (.devcontainer/devcontainer.json) and agent-frontmatter (.github/agents/*.agent.md)",
+            reason: "GitHub Copilot MCP support will be implemented via repo-scoped devcontainer features and agent-frontmatter mappings — surfaces that are genuinely Copilot-specific and not covered by other agent targets",
         },
         agentRulesSupport: {
             status: "unsupported",
@@ -241,7 +284,15 @@ export const AGENT_REGISTRY = [
             schemaLabel: "global permissions surface",
             reason: "GitHub Copilot permissions are managed via organization policy, not a deployable per-user config surface",
         },
-        policyNote: "Organization policies may override locally deployed skills. Verify with your GitHub org admin if deployed skills are not active.",
+        agentDefinitionsSupport: {
+            status: "supported",
+            schemaLabel: "repo-local agent definition Markdown file",
+            path: {
+                posix: ["{repo}", ".github", "agents", "{name}.agent.md"],
+                windows: ["{repo}", ".github", "agents", "{name}.agent.md"],
+            },
+        },
+        policyNote: "Organization policies may override locally deployed configuration. Verify with your GitHub org admin if deployed skills or rules are not active.",
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

package/dist/config/manifest.js

@@ -42,6 +42,8 @@ function validateManifest(data, filePath) {
         if (issuePath.length === 1 &&
             (issuePath[0] === "mcpServers" ||
                 issuePath[0] === "agentRules" ||
+                issuePath[0] === "agentDefinitions" ||
+                issuePath[0] === "permissions" ||
                 issuePath[0] === "files" ||
                 issuePath[0] === "configs")) {
             throw new UserError("MANIFEST_INVALID", `${filePath}: "${issuePath[0]}" must be an array`);

package/dist/core/adapters/agent-definitions.d.ts

@@ -0,0 +1,20 @@
+import type { AgentDefinitionEntry } from "../../schemas/manifest.ts";
+import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
+export interface AgentDefinitionsAdapterResult {
+    actions: FileWriteDeployAction[];
+    warnings: PlanWarning[];
+}
+/**
+ * Compiles deploy actions for agentDefinitions manifest entries.
+ *
+ * Agent definition files are Markdown files (typically with YAML frontmatter)
+ * 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 (repo-local).
+ *
+ * Target paths use the `{repo}` placeholder so definitions land in the
+ * repository being deployed, not the user's home directory.
+ */
+export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string): Promise<AgentDefinitionsAdapterResult>;
+export declare function compileAgentDefinitionReverts(entry: AgentDefinitionEntry, agentFilter: AgentId[] | null, home: string, repo?: string): FileWriteRevertAction[];

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

@@ -0,0 +1,90 @@
+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";
+/**
+ * Compiles deploy actions for agentDefinitions manifest entries.
+ *
+ * Agent definition files are Markdown files (typically with YAML frontmatter)
+ * 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 (repo-local).
+ *
+ * Target paths use the `{repo}` placeholder so definitions land in the
+ * repository being deployed, not the user's home directory.
+ */
+export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
+    const actions = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    const supportedTargets = [];
+    if (targetAgents.length === 0) {
+        return { actions, warnings };
+    }
+    for (const agentId of targetAgents) {
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        const support = agent?.agentDefinitionsSupport;
+        if (!support || support.status === "unsupported") {
+            warnings.push({
+                kind: "confidence",
+                message: `agentDefinitions: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported agent-definition schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported agent-definitions adapter"} — skipping "${entry.name}"`,
+            });
+            continue;
+        }
+        if (support.status === "planned") {
+            warnings.push({
+                kind: "confidence",
+                message: `agentDefinitions: agent "${agentId}" agent-definitions support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
+            });
+            continue;
+        }
+        supportedTargets.push({
+            agentId,
+            confidence: agent.provenance.agentDefinitions ?? "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 is active.
+    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: target.agentId,
+            source,
+            target: target.target,
+            confidence: target.confidence,
+        });
+    }
+    return { actions, warnings };
+}
+export function compileAgentDefinitionReverts(entry, agentFilter, home, repo) {
+    const actions = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        const support = agent?.agentDefinitionsSupport;
+        if (!support ||
+            support.status === "unsupported" ||
+            support.status === "planned")
+            continue;
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        actions.push({
+            kind: "file-write",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

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

@@ -21,6 +21,13 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
             });
             continue;
         }
+        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;
+        }
         supportedTargets.push({
             agentId,
             confidence: agent.provenance.agentRules ?? "provisional",
@@ -56,7 +63,9 @@ export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
             continue;
         const agent = AGENT_REGISTRY_BY_ID[agentId];
         const support = agent?.agentRulesSupport;
-        if (!support || support.status === "unsupported")
+        if (!support ||
+            support.status === "unsupported" ||
+            support.status === "planned")
             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

@@ -2,7 +2,7 @@ import { access, readFile, readdir, 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 {
@@ -164,6 +174,117 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
     }
     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/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) {

package/dist/schemas/manifest.d.ts

@@ -84,6 +84,18 @@ export declare const PermissionsEntrySchema: z.ZodObject<{
     }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
     config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
+export declare const AgentDefinitionEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "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;
+}, z.core.$strip>;
 export declare const ManifestSchema: z.ZodObject<{
     skills: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -159,6 +171,18 @@ export declare const ManifestSchema: z.ZodObject<{
         }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
         config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strip>>>;
+    agentDefinitions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "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;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SkillEntry = z.infer<typeof SkillEntrySchema>;
 export type FileEntry = z.infer<typeof FileEntrySchema>;
@@ -166,6 +190,7 @@ export type ConfigEntry = z.infer<typeof ConfigEntrySchema>;
 export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;
 export type AgentRuleEntry = z.infer<typeof AgentRuleEntrySchema>;
 export type PermissionsEntry = z.infer<typeof PermissionsEntrySchema>;
+export type AgentDefinitionEntry = z.infer<typeof AgentDefinitionEntrySchema>;
 export type Manifest = z.infer<typeof ManifestSchema>;
 export declare const AgentListSchema: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
     "claude-code": "claude-code";

package/dist/schemas/manifest.js

@@ -98,6 +98,14 @@ export const PermissionsEntrySchema = z.object({
     // For codex: { approval_policy?: "auto" | "manual" | "suggest" | "on-failure" }
     config: z.record(z.string(), z.unknown()),
 });
+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.
+    path: sourcePathField,
+});
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {
         const seen = new Set();
@@ -117,6 +125,7 @@ export const ManifestSchema = z.object({
     mcpServers: z.array(McpServerEntrySchema).default([]),
     agentRules: z.array(AgentRuleEntrySchema).default([]),
     permissions: z.array(PermissionsEntrySchema).default([]),
+    agentDefinitions: z.array(AgentDefinitionEntrySchema).default([]),
 });
 // Parses the --agents CLI flag: comma-separated agent IDs → AgentId[]
 export const AgentListSchema = z

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId } from "./schemas/manifest.ts";
-export type { AgentId, ConfigEntry, FileEntry, Manifest, SkillEntry, } from "./schemas/manifest.ts";
+export type { AgentDefinitionEntry, AgentId, ConfigEntry, FileEntry, Manifest, SkillEntry, } from "./schemas/manifest.ts";
 export interface AgentPaths {
     posix: string[];
     windows: string[];
@@ -16,25 +16,47 @@ export interface UnsupportedAgentSurface {
     schemaLabel: string;
     reason: string;
 }
-export type AgentSurfaceSupport = SupportedAgentSurface | UnsupportedAgentSurface;
+/**
+ * A surface that is confirmed as Copilot-specific and genuinely justified for
+ * future dedicated implementation, but not yet supported. Distinct from
+ * "unsupported" (which means the surface is either covered by another target or
+ * will never be added) so adapters can emit a forward-looking "planned" notice
+ * rather than a blocking skip warning.
+ */
+export interface PlannedAgentSurface {
+    status: "planned";
+    schemaLabel: string;
+    /** Short description of the concrete file / config surface to be implemented. */
+    plannedSurface: string;
+    reason: string;
+}
+export type AgentSurfaceSupport = SupportedAgentSurface | UnsupportedAgentSurface | PlannedAgentSurface;
 export interface AgentProvenance {
-    skills: Confidence;
+    /** Omit when the agent has no separate skill deployment path. */
+    skills?: Confidence;
     detectPaths: Confidence;
     detectBinary: Confidence;
     mcpConfig?: Confidence;
     agentRules?: Confidence;
     permissions?: Confidence;
+    agentDefinitions?: Confidence;
 }
 export interface AgentConfig {
     id: AgentId;
     displayName: string;
-    skills: AgentPaths;
+    /**
+     * The on-disk path template for deploying skills to this agent.
+     * Omit for agents that consume skills from another agent's path natively
+     * (e.g. GitHub Copilot reads `.claude/skills/` directly).
+     */
+    skills?: AgentPaths;
     detectPaths: AgentPaths;
     detectBinary: string | null;
     provenance: AgentProvenance;
     mcpSupport?: AgentSurfaceSupport;
     agentRulesSupport?: AgentSurfaceSupport;
     permissionsSupport?: AgentSurfaceSupport;
+    agentDefinitionsSupport?: AgentSurfaceSupport;
     policyNote?: string;
 }
 export interface PlanWarning {

package/package.json

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