@kuznai/inception-engine 0.17.0 → 0.19.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 validates that `agentRules` and `agentDefinitions` for targets requiring specific structure (like `github-copilot` and `antigravity`) include valid YAML frontmatter with `name` and `description` fields. For `github-copilot`, it further ensures either `tools` or `instructions` are defined; for `antigravity`, it validates the shape of any `mcp-servers` or `mcpServers` defined in the frontmatter. It also warns when the same agent will have multiple `agentRules` scopes active simultaneously, when the same source file is deployed to multiple scopes (duplicate-content risk), when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk), and when GitHub Copilot appears to be running under enterprise-managed policy that may override local configuration. Warnings are printed but do not block deployment; structural validation failures block deployment for the affected targets.
+
 ## Agent Compatibility Matrix
 
 | Agent | ID | Skills | macOS | Linux | Windows |
@@ -49,10 +51,11 @@ Managed skills overwrite their previous version. If a target exists but was not
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
 | MCP Servers | claude-code, gemini-cli, codex, antigravity, opencode; github-copilot repo-scoped surfaces are warned and skipped | claude-code, gemini-cli, codex, antigravity, opencode |
-| Global/Repo Rules Files | All agents (antigravity uses repo-local `.agents/rules/`); github-copilot reads CLAUDE.md natively (deploy via claude-code) | All agents |
+| Global/Repo/Workspace Rules Files | `scope: "global"` and `scope: "repo"` are supported on the implemented agent surfaces; `scope: "workspace"` is supported for `claude-code`, `codex`, and `gemini-cli`; `github-copilot` reads Claude-native rules via `claude-code` and has no separate rules deployment target | All supported agents |
 | Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`); other agents are warned and skipped | claude-code, codex |
 | Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`), github-copilot (`{repo}/.github/agents/{name}.agent.md`); codex is warned and skipped | All supported agents |
 | `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), `mcp-servers.json` (`mcpServers`), and agent-definition Markdown files (`agentDefinitions`); emits hints for `files/` and `configs/` directories | N/A |
+| Instruction preflight analysis | Emits `precedence` warnings when an agent has multiple `agentRules` scopes active simultaneously or the same source file is deployed to multiple scopes; emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB; emits GitHub Copilot enterprise-policy warnings when local configuration may be overridden | N/A |
 
 Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
 
@@ -98,7 +101,14 @@ Create an `inception.json` file at the root of your skills directory:
     {
       "name": "my-rules",
       "path": "rules/CLAUDE.md",
-      "agents": ["claude-code"]
+      "agents": ["claude-code"],
+      "scope": "global"
+    },
+    {
+      "name": "project-rules",
+      "path": "rules/CLAUDE.md",
+      "agents": ["claude-code", "codex", "gemini-cli", "opencode"],
+      "scope": "repo"
     }
   ],
   "permissions": [
@@ -158,13 +168,28 @@ 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), `"repo"`, or `"workspace"`. Controls which instruction surface is targeted:
+  - `"global"` — deploys to the agent's home-directory instruction file when that surface is supported (e.g., `~/.claude/CLAUDE.md` for `claude-code`)
+  - `"repo"` — deploys to the project-root instruction file inside the deployed repository when that surface is supported (e.g., `{repo}/CLAUDE.md` for `claude-code`)
+  - `"workspace"` — deploys to the workspace-root instruction file when an agent exposes one (e.g., `{workspace}/CLAUDE.md` for `claude-code`); when unsupported, deployment is skipped with a warning
+
+Instruction rule deployment is supported for implemented global, repo, and workspace surfaces. The target path depends on the agent and the `scope`:
 
-Instruction rule deployment is supported for all agents. For most agents, this targets a single global rules file (e.g., `~/.claude/CLAUDE.md` for `claude-code`, `~/.codex/AGENTS.md` for `codex`, `~/.gemini/GEMINI.md` for `gemini-cli`, and `~/.config/opencode/AGENTS.md` for `opencode`). For `antigravity`, inception-engine deploys to repo-local instruction surfaces at `{repo}/.agents/rules/{name}.md`. For `github-copilot`, no separate deployment is needed because Copilot reads `CLAUDE.md` natively — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
+| Agent | `scope: "global"` | `scope: "repo"` | `scope: "workspace"` |
+|---|---|---|---|
+| `claude-code` | `~/.claude/CLAUDE.md` | `{repo}/CLAUDE.md` | `{workspace}/CLAUDE.md` |
+| `codex` | `~/.codex/AGENTS.md` | `{repo}/AGENTS.md` | `{workspace}/AGENTS.md` |
+| `gemini-cli` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` | `{workspace}/GEMINI.md` |
+| `antigravity` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` | unsupported; warns and skips |
+| `opencode` | `~/.config/opencode/AGENTS.md` | `{repo}/AGENTS.md` | unsupported; warns and skips |
+| `github-copilot` | unsupported / Claude-first | deploy via `claude-code` | unsupported; deploy via `claude-code` with `scope: "workspace"` |
+
+For `antigravity`, `agentRules` now targets the shared GEMINI.md surface (`~/.gemini/GEMINI.md` for `global`, `{repo}/GEMINI.md` for `repo`) — the same paths used by `gemini-cli`. When both agents appear in the same entry, deduplication ensures only one write action is emitted. `workspace` scope is not supported and is skipped with a warning. For `github-copilot`, no separate deployment is needed — 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:
 
@@ -251,8 +276,8 @@ Current `init` behavior:
 - Uses the directory name as the manifest skill name
 - Applies either the `--agents` list or all currently known agent IDs
 - Refuses to overwrite an existing `inception.json` unless `--force` is provided
-- Supports `--dry-run` so you can inspect the generated manifest before writing it
-- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`, `.agents/rules/`), mapping them to agents using Claude-first portability conventions: `copilot-instructions.md` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), and the fallback for unrecognized files excludes agents whose agentRules surface is unsupported
+- Supports `--plan` so you can inspect the generated manifest before writing it
+- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`), mapping them to agents using Claude-first portability conventions: `copilot-instructions.md` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), and the fallback for unrecognized files excludes agents whose agentRules surface is unsupported
 - 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
@@ -342,13 +367,15 @@ inception-engine init <directory> [options]
 
 | Option | Description |
 |---|---|
-| `--dry-run` | Show what would be done without making changes |
+| `--plan` | Show what would be done without making changes |
 | `--agents <list>` | Comma-separated list of agent IDs to target (overrides deploy detection; restricts revert) |
 | `--force` | `init` only; overwrite an existing `inception.json` |
 | `--verbose` | Show detailed output including file paths |
 | `--debug` | Show full error stack traces |
 | `--help` | Show help message |
 
+With `--plan`, deploy and revert print a grouped action preview by agent. Each planned change includes the source path when applicable, the resolved target path, and action-specific details such as JSON/TOML patch payloads or emitted frontmatter content.
+
 ### Examples
 
 ```bash
@@ -356,7 +383,7 @@ inception-engine init <directory> [options]
 npx @kuznai/inception-engine ./my-skills-repo
 
 # Preview what would be deployed
-npx @kuznai/inception-engine ./my-skills-repo --dry-run
+npx @kuznai/inception-engine ./my-skills-repo --plan
 
 # Deploy only to Claude Code and Codex
 npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
@@ -365,13 +392,13 @@ npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
 npx @kuznai/inception-engine revert ./my-skills-repo
 
 # Preview what would be removed
-npx @kuznai/inception-engine revert ./my-skills-repo --dry-run
+npx @kuznai/inception-engine revert ./my-skills-repo --plan
 
 # Generate a starter manifest from discovered skill folders
 npx @kuznai/inception-engine init ./my-skills-repo
 
 # Preview the generated manifest without writing it
-npx @kuznai/inception-engine init ./my-skills-repo --dry-run
+npx @kuznai/inception-engine init ./my-skills-repo --plan
 ```
 
 ## Sample Skills
@@ -381,8 +408,8 @@ The `limbo/` directory contains exceptional sample skills for testing purposes o
 Try them out:
 
 ```bash
-npx @kuznai/inception-engine init limbo --dry-run
-npx @kuznai/inception-engine limbo --dry-run
+npx @kuznai/inception-engine init limbo --plan
+npx @kuznai/inception-engine limbo --plan
 ```
 
 ## Agent Detection

package/dist/config/agents.js

@@ -36,6 +36,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".claude", "CLAUDE.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local CLAUDE.md",
+            path: {
+                posix: ["{repo}", "CLAUDE.md"],
+                windows: ["{repo}", "CLAUDE.md"],
+            },
+        },
         permissionsSupport: {
             status: "supported",
             schemaLabel: "JSON permissions config",
@@ -52,6 +60,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".claude", "agents", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local CLAUDE.md",
+            path: {
+                posix: ["{workspace}", "CLAUDE.md"],
+                windows: ["{workspace}", "CLAUDE.md"],
+            },
+        },
     },
     {
         id: "codex",
@@ -88,6 +104,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",
@@ -101,6 +125,14 @@ export const AGENT_REGISTRY = [
             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",
         },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local AGENTS.md",
+            path: {
+                posix: ["{workspace}", "AGENTS.md"],
+                windows: ["{workspace}", "AGENTS.md"],
+            },
+        },
     },
     {
         id: "gemini-cli",
@@ -138,6 +170,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{home}", ".gemini", "GEMINI.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local GEMINI.md",
+            path: {
+                posix: ["{repo}", "GEMINI.md"],
+                windows: ["{repo}", "GEMINI.md"],
+            },
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -151,6 +191,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".gemini", "agents", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            schemaLabel: "workspace-local GEMINI.md",
+            path: {
+                posix: ["{workspace}", "GEMINI.md"],
+                windows: ["{workspace}", "GEMINI.md"],
+            },
+        },
     },
     {
         id: "antigravity",
@@ -179,12 +227,25 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".agents", "rules", "{name}.md"],
             },
         },
+        // Antigravity shares its instruction surfaces with gemini-cli (both target
+        // the same GEMINI.md paths). surfaceKind: shared-via drives deduplication
+        // when both agents appear in the same agentRules entry.
         agentRulesSupport: {
             status: "supported",
-            schemaLabel: "repo-local Markdown rules file",
+            surfaceKind: { kind: "shared-via", via: "gemini-cli" },
+            schemaLabel: "global Gemini blueprint instructions file",
             path: {
-                posix: ["{repo}", ".agents", "rules", "{name}.md"],
-                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+                posix: ["{home}", ".gemini", "GEMINI.md"],
+                windows: ["{home}", ".gemini", "GEMINI.md"],
+            },
+        },
+        agentRulesRepoSupport: {
+            status: "supported",
+            surfaceKind: { kind: "shared-via", via: "gemini-cli" },
+            schemaLabel: "repo-local GEMINI.md",
+            path: {
+                posix: ["{repo}", "GEMINI.md"],
+                windows: ["{repo}", "GEMINI.md"],
             },
         },
         permissionsSupport: {
@@ -200,6 +261,12 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".agents", "rules", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "unsupported",
+            schemaLabel: "workspace-local instruction surface",
+            reason: "Antigravity is natively repo-local and does not expose a separate workspace-local instruction surface",
+        },
+        instructionFrontmatterRequired: true,
     },
     {
         id: "opencode",
@@ -237,6 +304,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{appdata}", "opencode", "AGENTS.md"],
             },
         },
+        agentRulesRepoSupport: {
+            status: "supported",
+            schemaLabel: "repo-local AGENTS.md",
+            path: {
+                posix: ["{repo}", "AGENTS.md"],
+                windows: ["{repo}", "AGENTS.md"],
+            },
+        },
         permissionsSupport: {
             status: "unsupported",
             schemaLabel: "global permissions surface",
@@ -250,6 +325,11 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".opencode", "agents", "{name}.md"],
             },
         },
+        agentRulesWorkspaceSupport: {
+            status: "unsupported",
+            schemaLabel: "workspace-local AGENTS.md",
+            reason: "OpenCode does not expose a documented workspace-local instruction surface distinct from repo-local AGENTS.md",
+        },
     },
     {
         id: "github-copilot",
@@ -258,6 +338,7 @@ export const AGENT_REGISTRY = [
         // 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.
+        skillsSurfaceKind: { kind: "shared-via", via: "claude-code" },
         detectPaths: {
             posix: ["{home}", ".copilot"],
             windows: ["{home}", ".copilot"],
@@ -274,10 +355,49 @@ export const AGENT_REGISTRY = [
             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",
         },
+        // GitHub Copilot reads Claude-native instruction files (CLAUDE.md) without
+        // a separate deploy action. These surfaces are marked shared-via claude-code
+        // with requiresPrimary: true so deploy skips emitting a separate action
+        // when claude-code is also targeted, and emits a guidance warning when it
+        // is not (copilot cannot write to these surfaces independently).
         agentRulesSupport: {
-            status: "unsupported",
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
             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',
+            path: {
+                posix: ["{home}", ".claude", "CLAUDE.md"],
+                windows: ["{home}", ".claude", "CLAUDE.md"],
+            },
+        },
+        agentRulesRepoSupport: {
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
+            schemaLabel: "repo-local CLAUDE.md",
+            path: {
+                posix: ["{repo}", "CLAUDE.md"],
+                windows: ["{repo}", "CLAUDE.md"],
+            },
+        },
+        agentRulesWorkspaceSupport: {
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
+            schemaLabel: "workspace-local CLAUDE.md",
+            path: {
+                posix: ["{workspace}", "CLAUDE.md"],
+                windows: ["{workspace}", "CLAUDE.md"],
+            },
         },
         permissionsSupport: {
             status: "unsupported",
@@ -293,6 +413,8 @@ export const AGENT_REGISTRY = [
             },
         },
         policyNote: "Organization policies may override locally deployed configuration. Verify with your GitHub org admin if deployed skills or rules are not active.",
+        instructionFrontmatterRequired: true,
+        enterprisePolicyDetection: true,
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

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

@@ -16,5 +16,5 @@ export interface AgentDefinitionsAdapterResult {
  * 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[];
+export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<AgentDefinitionsAdapterResult>;
+export declare function compileAgentDefinitionReverts(entry: AgentDefinitionEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

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

@@ -1,7 +1,7 @@
 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";
+import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
 /**
  * Compiles deploy actions for agentDefinitions manifest entries.
  *
@@ -14,7 +14,7 @@ import { validateAgentRuleMarkdownPath, validateSourceFile, validateSourcePath,
  * 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) {
+export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
@@ -43,7 +43,7 @@ export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSo
         supportedTargets.push({
             agentId,
             confidence: agent.provenance.agentDefinitions ?? "provisional",
-            target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
+            target: resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace),
         });
     }
     if (supportedTargets.length === 0) {
@@ -55,6 +55,7 @@ export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSo
     await validateSourceFile(source, entry.path);
     for (const target of supportedTargets) {
         validateAgentRuleMarkdownPath(entry.path, target.agentId);
+        await validateInstructionFileRequirements(source, entry.path, target.agentId);
         actions.push({
             kind: "file-write",
             skill: entry.name,
@@ -66,7 +67,7 @@ export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSo
     }
     return { actions, warnings };
 }
-export function compileAgentDefinitionReverts(entry, agentFilter, home, repo) {
+export function compileAgentDefinitionReverts(entry, agentFilter, home, repo, workspace) {
     const actions = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
@@ -78,7 +79,7 @@ export function compileAgentDefinitionReverts(entry, agentFilter, home, repo) {
             support.status === "unsupported" ||
             support.status === "planned")
             continue;
-        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         actions.push({
             kind: "file-write",
             skill: entry.name,

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

@@ -1,16 +1,28 @@
 /**
- * Serializes a flat (one-level) object to a YAML block suitable for use inside
- * `---` frontmatter delimiters.
+ * Splits a Markdown string into YAML frontmatter and the remaining body.
+ * Expects the file to start with --- delimiter.
+ */
+export declare function splitFrontmatter(raw: string): {
+    frontmatter: string;
+    body: string;
+};
+/**
+ * Parses a Markdown string with YAML frontmatter.
+ */
+export declare function parseFrontmatterDocument<T = Record<string, unknown>>(raw: string): {
+    attributes: T;
+    body: string;
+};
+/**
+ * Serializes an object to a YAML block.
  */
 export declare function serializeFrontmatter(data: Record<string, unknown>): string;
 /**
  * Builds the full content of a frontmatter-bearing Markdown file.
- * If `body` is provided it is appended after the closing delimiter.
  */
 export declare function buildFrontmatterDocument(frontmatter: Record<string, unknown>, body?: string): string;
 /**
- * Reads an existing `.md` file and parses its frontmatter (using the
- * `front-matter` package). Returns the parsed attributes and raw body.
+ * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export declare function readFrontmatterFile(filePath: string): Promise<{

package/dist/core/adapters/frontmatter.js

@@ -1,71 +1,52 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import path from "node:path";
-const _require = createRequire(import.meta.url);
-// front-matter is a CommonJS module whose export is the callable parse function.
-const parseFrontmatter = _require("front-matter");
-// ---------------------------------------------------------------------------
-// Hand-rolled flat-YAML serializer
-// Handles the shapes found in MCP server descriptors: strings, numbers,
-// booleans, string arrays, and one-level nested objects (e.g. "env").
-// ---------------------------------------------------------------------------
-function serializeScalar(value) {
-    if (typeof value === "string") {
-        const needsQuotes = /[:#[\]{},|>&*!'"@`]|^\s|\s$/.test(value);
-        return needsQuotes
-            ? `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
-            : value;
+import YAML from "yaml";
+/**
+ * Splits a Markdown string into YAML frontmatter and the remaining body.
+ * Expects the file to start with --- delimiter.
+ */
+export function splitFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        return { frontmatter: "", body: raw };
     }
-    return String(value);
-}
-function serializeArray(key, arr, pad) {
-    if (arr.length === 0)
-        return `${pad}${key}: []`;
-    const items = arr.map((item) => {
-        const scalar = typeof item === "string" ||
-            typeof item === "number" ||
-            typeof item === "boolean"
-            ? serializeScalar(item)
-            : JSON.stringify(item);
-        return `${pad}  - ${scalar}`;
-    });
-    return [`${pad}${key}:`, ...items].join("\n");
-}
-function serializeObject(key, obj, pad) {
-    const inner = serializeFrontmatterAtDepth(obj, `${pad}  `);
-    return inner ? `${pad}${key}:\n${inner}` : `${pad}${key}: {}`;
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (closingIndex === -1) {
+        return { frontmatter: "", body: raw };
+    }
+    // Preserve the actual lines for the body to avoid normalizing line endings if not needed
+    // but for frontmatter block, we join with \n for the YAML parser
+    const frontmatter = lines.slice(1, closingIndex).join("\n");
+    const body = lines.slice(closingIndex + 1).join("\n");
+    return { frontmatter, body };
 }
-function serializeFrontmatterAtDepth(data, pad) {
-    const lines = [];
-    for (const [key, value] of Object.entries(data)) {
-        if (value === null || value === undefined)
-            continue;
-        if (Array.isArray(value)) {
-            lines.push(serializeArray(key, value, pad));
-        }
-        else if (typeof value === "object") {
-            lines.push(serializeObject(key, value, pad));
-        }
-        else {
-            lines.push(`${pad}${key}: ${serializeScalar(value)}`);
-        }
+/**
+ * Parses a Markdown string with YAML frontmatter.
+ */
+export function parseFrontmatterDocument(raw) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    if (!(frontmatter || raw.startsWith("---"))) {
+        return { attributes: {}, body };
     }
-    return lines.join("\n");
+    const attributes = YAML.parse(frontmatter);
+    return { attributes: (attributes || {}), body };
 }
 /**
- * Serializes a flat (one-level) object to a YAML block suitable for use inside
- * `---` frontmatter delimiters.
+ * Serializes an object to a YAML block.
  */
 export function serializeFrontmatter(data) {
-    return serializeFrontmatterAtDepth(data, "");
+    // Using a consistent indentation that matches standard YAML
+    return YAML.stringify(data, { indent: 2 }).trim();
 }
 /**
  * Builds the full content of a frontmatter-bearing Markdown file.
- * If `body` is provided it is appended after the closing delimiter.
  */
 export function buildFrontmatterDocument(frontmatter, body = "") {
     const serialized = serializeFrontmatter(frontmatter);
-    return `---\n${serialized}\n---\n${body}`;
+    // Ensure exactly one newline after the closing delimiter before the body
+    const cleanBody = body.trimStart();
+    const separator = cleanBody ? "\n\n" : "\n";
+    return `---\n${serialized}\n---\n${separator}${cleanBody}`;
 }
 function createAtomicTempPath(targetPath) {
     return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
@@ -73,8 +54,7 @@ function createAtomicTempPath(targetPath) {
         .slice(2)}`;
 }
 /**
- * Reads an existing `.md` file and parses its frontmatter (using the
- * `front-matter` package). Returns the parsed attributes and raw body.
+ * Reads an existing `.md` file and parses its frontmatter.
  * Returns `{ attributes: {}, body: "" }` if the file does not exist.
  */
 export async function readFrontmatterFile(filePath) {
@@ -88,8 +68,7 @@ export async function readFrontmatterFile(filePath) {
             return { attributes: {}, body: "" };
         throw err;
     }
-    const parsed = parseFrontmatter(raw);
-    return { attributes: parsed.attributes, body: parsed.body };
+    return parseFrontmatterDocument(raw);
 }
 /**
  * Atomically writes a Markdown file with the given frontmatter and optional

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

@@ -10,4 +10,4 @@ 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, agentDefinitions?: AgentDefinitionEntry[]): 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[], workspace?: string): Promise<AdapterResult>;

package/dist/core/adapters/index.js

@@ -3,16 +3,16 @@ import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
 export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileMcpServerReverts, compilePermissionsReverts, };
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions) {
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace) {
     const actions = [];
     const warnings = [];
     for (const entry of mcpServers) {
-        const r = compileMcpServerActions(entry, detectedAgents, home, repo);
+        const r = compileMcpServerActions(entry, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
     for (const entry of agentRules) {
-        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
+        const r = await compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }
@@ -22,7 +22,7 @@ export async function compileAdapterActions(mcpServers, agentRules, permissions,
         warnings.push(...r.warnings);
     }
     for (const entry of agentDefinitions ?? []) {
-        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo);
+        const r = await compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace);
         actions.push(...r.actions);
         warnings.push(...r.warnings);
     }

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

@@ -4,5 +4,5 @@ export interface McpAdapterResult {
     actions: Array<ConfigPatchDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction>;
     warnings: PlanWarning[];
 }
-export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string, repo?: string): McpAdapterResult;
-export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string, repo?: string): Array<ConfigPatchRevertAction | TomlPatchRevertAction | FrontmatterEmitRevertAction>;
+export declare function compileMcpServerActions(entry: McpServerEntry, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): McpAdapterResult;
+export declare function compileMcpServerReverts(entry: McpServerEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): Array<ConfigPatchRevertAction | TomlPatchRevertAction | FrontmatterEmitRevertAction>;