@kuznai/inception-engine 0.16.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,9 +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 |
-| `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 |
+| 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.
 
@@ -97,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": [
@@ -111,6 +122,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"]
+    }
   ]
 }
 ```
@@ -150,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`:
+
+| 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` |
 
-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.
+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:
 
@@ -199,6 +231,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 +280,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 +330,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",
@@ -35,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",
@@ -43,6 +52,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",
@@ -79,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",
@@ -87,6 +112,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 +136,7 @@ export const AGENT_REGISTRY = [
             detectBinary: "documented",
             mcpConfig: "documented",
             agentRules: "documented",
+            agentDefinitions: "implementation-only",
         },
         mcpSupport: {
             status: "supported",
@@ -123,11 +154,27 @@ 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",
             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 +192,8 @@ export const AGENT_REGISTRY = [
             skills: "implementation-only",
             detectPaths: "implementation-only",
             detectBinary: "provisional",
+            agentRules: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -162,11 +211,27 @@ 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",
             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 +250,7 @@ export const AGENT_REGISTRY = [
             detectPaths: "documented",
             detectBinary: "documented",
             agentRules: "documented",
+            agentDefinitions: "documented",
         },
         mcpSupport: {
             status: "supported",
@@ -203,45 +269,75 @@ 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",
             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",
             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",
             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/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