@kuznai/inception-engine 0.17.0 → 0.19.0

package/dist/core/init.js

@@ -1,42 +1,81 @@
-import { access, readFile, readdir, writeFile } from "node:fs/promises";
+import { access, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { dryRunPrefix, logger } from "../logger.js";
 import { AGENT_IDS, AgentDefinitionEntrySchema, ConfigEntrySchema, FileEntrySchema, McpServerEntrySchema, } from "../schemas/manifest.js";
+import { parseFrontmatterDocument } from "./adapters/frontmatter.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 = [
-    {
-        fileNames: ["claude.md", "claude-instructions.md"],
-        agents: ["claude-code"],
-    },
-    {
-        fileNames: ["agents.md", "agents-instructions.md"],
-        agents: ["codex", "opencode"],
-    },
-    {
-        fileNames: ["gemini.md", "gemini-instructions.md"],
-        agents: ["gemini-cli", "antigravity"],
-    },
-    { fileNames: ["copilot-instructions.md"], agents: ["claude-code"] },
-];
+// Derived from the registry: group agents by the filename of their global
+// agentRulesSupport path. Agents with requiresPrimary (e.g. github-copilot)
+// are excluded because they cannot be deployed independently. The
+// copilot-instructions.md convention mapping is appended explicitly since it
+// is a well-known filename convention, not derivable from a path template.
+const AGENT_RULES_FILE_PATTERNS = (() => {
+    const filenameToAgents = new Map();
+    for (const agent of AGENT_REGISTRY) {
+        const support = agent.agentRulesSupport;
+        if (support?.status !== "supported")
+            continue;
+        // Skip riders that require the primary — they cannot be listed independently
+        if (support.surfaceKind?.kind === "shared-via" &&
+            support.surfaceKind.requiresPrimary)
+            continue;
+        const filename = support.path.posix[support.path.posix.length - 1]?.toLowerCase();
+        if (!filename)
+            continue;
+        const list = filenameToAgents.get(filename) ?? [];
+        list.push(agent.id);
+        filenameToAgents.set(filename, list);
+    }
+    return [
+        ...Array.from(filenameToAgents.entries()).map(([filename, agents]) => ({
+            fileNames: [filename, filename.replace(".md", "-instructions.md")],
+            agents,
+        })),
+        // Convention mapping: copilot-instructions.md → claude-code. Copilot reads
+        // CLAUDE.md natively; this filename is a well-known convention that cannot
+        // be derived from any agent path template.
+        {
+            fileNames: ["copilot-instructions.md"],
+            agents: ["claude-code"],
+        },
+    ];
+})();
 // Conventional subdirectory names to scan one level deep for .md files.
-const AGENT_RULES_SUBDIRS = [
-    "rules",
-    "instructions",
-    ".github",
-    ".agents/rules",
-];
+const AGENT_RULES_SUBDIRS = ["rules", "instructions", ".github"];
 // 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",
-];
+// Derived from the registry: for each agent with a supported agentDefinitions
+// surface, extract the directory prefix from its posix path template.
+const AGENT_DEFINITION_SUBDIRS = (() => {
+    const subdirs = new Set();
+    for (const agent of AGENT_REGISTRY) {
+        const support = agent.agentDefinitionsSupport;
+        if (support?.status !== "supported")
+            continue;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            continue;
+        const dirSegs = tmpl.slice(repoIdx + 1, nameIdx);
+        if (dirSegs.length > 0)
+            subdirs.add(dirSegs.join("/"));
+    }
+    return Array.from(subdirs);
+})();
+async function hasAntigravityMcpFrontmatter(absPath) {
+    let raw;
+    try {
+        raw = await readFile(absPath, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const { attributes } = parseFrontmatterDocument(raw);
+    return (Object.hasOwn(attributes, "mcp-servers") ||
+        Object.hasOwn(attributes, "mcpServers"));
+}
 async function findSkillDirs(baseDir, dir, found) {
     let entries;
     try {
@@ -170,7 +209,7 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
             }
         }
         namesSeen.add(name);
-        rules.push({ name, path: relPath, agents });
+        rules.push({ name, path: relPath, agents, scope: "global" });
     }
     return rules;
 }
@@ -196,24 +235,53 @@ function deriveAgentDefinitionName(relPath, fileName) {
 }
 /**
  * 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).
+ * Derived from the registry by matching each agent's agentDefinitionsSupport
+ * path prefix. Returns null when the subdir is not recognized.
  */
 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;
+    const matching = [];
+    for (const agent of AGENT_REGISTRY) {
+        const support = agent.agentDefinitionsSupport;
+        if (support?.status !== "supported")
+            continue;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            continue;
+        const agentSubdir = tmpl.slice(repoIdx + 1, nameIdx).join("/");
+        if (agentSubdir === subdir)
+            matching.push(agent.id);
     }
+    return matching.length > 0 ? matching : null;
+}
+/**
+ * Returns true when a file in a definition subdir contains MCP-specific
+ * frontmatter and should be excluded from agentDefinitions discovery. Detects
+ * this by checking whether any registered agent uses the same directory as
+ * both its definition surface and its MCP surface (currently: Antigravity's
+ * .agents/rules/).
+ */
+async function isSkippedMcpFile(subdir, absPath, relPath) {
+    const hasMcpSurfaceHere = AGENT_REGISTRY.some((agent) => {
+        const support = agent.mcpSupport;
+        if (support?.status !== "supported")
+            return false;
+        const tmpl = support.path.posix;
+        const repoIdx = tmpl.indexOf("{repo}");
+        const nameIdx = tmpl.findIndex((s) => s.includes("{name}"));
+        if (repoIdx === -1 || nameIdx === -1 || nameIdx <= repoIdx)
+            return false;
+        const prefix = tmpl.slice(repoIdx + 1, nameIdx).join("/");
+        return prefix === subdir;
+    });
+    if (!hasMcpSurfaceHere)
+        return false;
+    const isMcp = await hasAntigravityMcpFrontmatter(absPath);
+    if (isMcp) {
+        logger.warn("init", `Skipping "${relPath}" as agentDefinitions: frontmatter contains "mcp-servers" — file is an MCP surface, not an agent definition`);
+    }
+    return isMcp;
 }
 async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, agentRulesRelPaths, candidates) {
     const suggestedAgents = agentsForDefinitionSubdir(subdir) ?? [];
@@ -237,6 +305,8 @@ async function scanDefinitionSubdir(subdir, baseDir, seen, skillDirRelPaths, age
             isInsideSkillDir(relPath, skillDirRelPaths) ||
             agentRulesRelPaths.has(relPath))
             continue;
+        if (await isSkippedMcpFile(subdir, absPath, relPath))
+            continue;
         const name = deriveAgentDefinitionName(relPath, entry.name);
         if (name === null)
             continue;
@@ -478,7 +548,17 @@ function logVerboseManifest(skills, agentRules, mcpServers, files, configs, agen
 export async function runInit(options) {
     const { directory, dryRun, force, verbose } = options;
     const agents = options.agents ?? [...AGENT_IDS];
-    const agentRulesCapableAgents = agents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentRulesSupport?.status !== "unsupported");
+    const agentRulesCapableAgents = agents.filter((id) => {
+        const support = AGENT_REGISTRY_BY_ID[id].agentRulesSupport;
+        if (!support || support.status === "unsupported")
+            return false;
+        // Exclude riders that require the primary — they cannot operate independently
+        if (support.status === "supported" &&
+            support.surfaceKind?.kind === "shared-via" &&
+            support.surfaceKind.requiresPrimary)
+            return false;
+        return true;
+    });
     const manifestPath = path.join(directory, "inception.json");
     if (!dryRun && (await manifestExists(manifestPath)) && !force) {
         logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);

package/dist/core/ownership.d.ts

@@ -1,4 +1,4 @@
-import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
+import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type FrontmatterEmitRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
 export type { RegistryEntry } from "../schemas/registry.ts";
 export interface RegistryPersistence {
@@ -22,7 +22,7 @@ export type VerifyExpected = {
 };
 export declare function registryPath(home: string): string;
 export declare const defaultRegistryPersistence: RegistryPersistence;
-export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed">;
+export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed"> | Omit<FrontmatterEmitRegistryEntry, "deployed">;
 export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;
 export declare function unregisterDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<void>;
 export declare function lookupDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;

package/dist/core/preflight.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId, CliOptions, Manifest } from "../types.ts";
 export interface PreflightWarning {
-    kind: "policy" | "config-authority" | "info";
+    kind: "policy" | "config-authority" | "info" | "precedence" | "budget";
     message: string;
 }
-export declare function runPreflight(_options: CliOptions, _manifest: Manifest, _home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;
+export declare function runPreflight(options: CliOptions, manifest: Manifest, home: string, detectedAgents: AgentId[]): Promise<PreflightWarning[]>;

package/dist/core/preflight.js

@@ -1,5 +1,135 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
-export async function runPreflight(_options, _manifest, _home, detectedAgents) {
+import { resolveRuntimePaths } from "./runtime-paths.js";
+const BUDGET_WARN_BYTES = 50 * 1024; // 50 KB
+async function detectEnterpriseManagement(agentId, home) {
+    if (!AGENT_REGISTRY_BY_ID[agentId]?.enterprisePolicyDetection)
+        return null;
+    // Check for common GitHub Enterprise environment variables
+    if (process.env.GITHUB_ENTERPRISE_URL ||
+        process.env.GH_ENTERPRISE_TOKEN ||
+        process.env.GITHUB_TOKEN_TYPE === "enterprise") {
+        return "GitHub Enterprise environment variables detected. Enterprise policies may override local configurations.";
+    }
+    const { xdgConfig, localAppdata } = resolveRuntimePaths(home);
+    const configPath = process.platform === "win32"
+        ? path.join(localAppdata, "github-copilot", "hosts.json")
+        : path.join(xdgConfig, "github-copilot", "hosts.json");
+    try {
+        const content = await readFile(configPath, "utf8");
+        const hosts = JSON.parse(content);
+        const hostNames = Object.keys(hosts);
+        const enterpriseHosts = hostNames.filter((h) => h !== "github.com" && h !== "localhost");
+        if (enterpriseHosts.length > 0) {
+            return `GitHub Copilot is authenticated against enterprise host(s): ${enterpriseHosts.join(", ")}. Enterprise policies may override local configurations.`;
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" &&
+            code !== "EACCES" &&
+            code !== "EPERM" &&
+            code !== undefined) {
+            throw err;
+        }
+    }
+    return null;
+}
+function groupRulesByPath(rulesForAgent) {
+    const entriesByPath = new Map();
+    for (const entry of rulesForAgent ?? []) {
+        const list = entriesByPath.get(entry.path) ?? [];
+        list.push({ name: entry.name, scope: entry.scope });
+        entriesByPath.set(entry.path, list);
+    }
+    return entriesByPath;
+}
+function detectScopeOverlaps(agentId, rulesForAgent) {
+    const warnings = [];
+    const entriesByPath = groupRulesByPath(rulesForAgent);
+    for (const [path, list] of entriesByPath) {
+        const scopes = new Set(list.map((l) => l.scope));
+        if (scopes.size < 2)
+            continue;
+        const scopeList = Array.from(scopes).sort();
+        for (let i = 0; i < scopeList.length; i++) {
+            for (let j = i + 1; j < scopeList.length; j++) {
+                const entryB = list.find((l) => l.scope === scopeList[j]);
+                if (entryB) {
+                    warnings.push({
+                        kind: "precedence",
+                        message: `Agent "${agentId}" has agentRules entry "${entryB.name}" deployed to both ${scopeList[i]} and ${scopeList[j]} scope from the same source path "${path}". The file will be written to two distinct targets — verify this is intentional and not a copy-paste mistake.`,
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
+function detectMultipleActiveInstructionScopes(agentId, rulesForAgent) {
+    const activeScopes = Array.from(new Set((rulesForAgent ?? []).map((e) => e.scope))).sort();
+    if (activeScopes.length <= 1)
+        return [];
+    const scopeDescriptions = activeScopes
+        .map((s) => {
+        const entries = (rulesForAgent ?? []).filter((e) => e.scope === s);
+        return `${s} [${entries.map((e) => `"${e.name}"`).join(", ")}]`;
+    })
+        .join(" and ");
+    return [
+        {
+            kind: "precedence",
+            message: `Agent "${agentId}" will have multiple instruction files active simultaneously across ${activeScopes.length} scopes: ${scopeDescriptions}. All will be loaded by the agent — ensure the content is intended to stack and does not conflict.`,
+        },
+    ];
+}
+function detectInstructionPrecedence(detectedAgents, manifest) {
+    const warnings = [];
+    for (const agentId of detectedAgents) {
+        const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
+        warnings.push(...detectScopeOverlaps(agentId, rulesForAgent));
+        warnings.push(...detectMultipleActiveInstructionScopes(agentId, rulesForAgent));
+    }
+    return warnings;
+}
+async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir) {
+    const warnings = [];
+    const checkedPaths = new Set();
+    async function checkEntry(entryPath, label, agentIds) {
+        if (!agentIds.some((id) => detectedAgents.includes(id)))
+            return;
+        const sourcePath = path.resolve(sourceDir, entryPath);
+        if (checkedPaths.has(sourcePath))
+            return;
+        checkedPaths.add(sourcePath);
+        try {
+            const fileStat = await stat(sourcePath);
+            if (fileStat.size > BUDGET_WARN_BYTES) {
+                const sizeKb = (fileStat.size / 1024).toFixed(1);
+                warnings.push({
+                    kind: "budget",
+                    message: `${label} source "${entryPath}" is ${sizeKb} KB — large instruction files risk crowding out code context in the agent's context window. Consider splitting into smaller focused files.`,
+                });
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
+                throw err;
+            // Missing/unreadable files are silently skipped; compileAgentRuleActions
+            // will produce the proper UserError during action compilation.
+        }
+    }
+    for (const entry of manifest.agentRules ?? []) {
+        await checkEntry(entry.path, "agentRules", entry.agents);
+    }
+    for (const entry of manifest.agentDefinitions ?? []) {
+        await checkEntry(entry.path, "agentDefinitions", entry.agents);
+    }
+    return warnings;
+}
+export async function runPreflight(options, manifest, home, detectedAgents) {
     const warnings = [];
     for (const agentId of detectedAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
@@ -17,12 +147,22 @@ export async function runPreflight(_options, _manifest, _home, detectedAgents) {
                 message: `Agent "${agentId}" skill support is provisional: behavior has not been independently verified.`,
             });
         }
-        if (agent.policyNote) {
+        const enterpriseWarning = await detectEnterpriseManagement(agentId, home);
+        if (enterpriseWarning) {
+            warnings.push({
+                kind: "policy",
+                message: `Agent "${agentId}": ${enterpriseWarning}`,
+            });
+        }
+        else if (agent.policyNote &&
+            !agent.policyNote.includes("Organization policies may override")) {
             warnings.push({
                 kind: "policy",
                 message: `Agent "${agentId}": ${agent.policyNote}`,
             });
         }
     }
+    warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
+    warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
     return warnings;
 }

package/dist/core/resolve.d.ts

@@ -9,4 +9,4 @@ export declare function resolveAgentSkillPathFor(agent: AgentConfig, skillName:
 export declare function resolveAgentDetectPathFor(agent: AgentConfig, home: string, platform: "posix" | "windows"): string;
 export declare function resolveAgentSkillPath(agent: AgentConfig, skillName: string, home: string): string;
 export declare function resolveAgentDetectPath(agent: AgentConfig, home: string): string;
-export declare function resolvePlaceholders(segments: string[], skillName: string, home: string, repo?: string): string;
+export declare function resolvePlaceholders(segments: string[], skillName: string, home: string, repo?: string, workspace?: string): string;

package/dist/core/resolve.js

@@ -86,8 +86,10 @@ export function getDeployMethod() {
 }
 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).`);
+        const hint = agent.skillsSurfaceKind?.kind === "shared-via"
+            ? ` Deploy skills via the "${agent.skillsSurfaceKind.via}" target, which covers this agent natively.`
+            : "";
+        throw new Error(`Agent "${agent.id}" does not have a skills deployment path.${hint}`);
     }
     return resolvePlaceholders(agent.skills[platform], skillName, home);
 }
@@ -100,14 +102,15 @@ export function resolveAgentSkillPath(agent, skillName, home) {
 export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
-export function resolvePlaceholders(segments, skillName, home, repo) {
+export function resolvePlaceholders(segments, skillName, home, repo, workspace) {
     const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
         .replace("{appdata}", appdata)
         .replace("{xdg_config}", xdgConfig)
-        .replace("{repo}", repo ?? ""));
+        .replace("{repo}", repo ?? "")
+        .replace("{workspace}", workspace ?? repo ?? ""));
     const root = resolved.find((segment) => segment.length > 0) ?? home;
     return getPathApi(root).join(...resolved);
 }

package/dist/core/revert.js

@@ -138,11 +138,9 @@ function lstatOutcome(err) {
     return { outcome: "fail", error: msg };
 }
 export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
-    let succeeded = 0;
-    let skipped = 0;
     const failed = [];
     const planned = [];
-    const counts = { succeeded, skipped };
+    const counts = { succeeded: 0, skipped: 0 };
     for (const action of actions) {
         let result;
         switch (action.kind) {
@@ -168,14 +166,18 @@ export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
                     target: action.target,
                 }, dryRun, verbose, home, planned, deps);
                 break;
-            default:
+            default: {
                 throw new Error(`Unhandled revert action kind: ${action.kind}`);
+            }
         }
         recordOutcome(result, action, counts, failed);
     }
-    succeeded = counts.succeeded;
-    skipped = counts.skipped;
-    return { succeeded, skipped, failed, planned };
+    return {
+        succeeded: counts.succeeded,
+        skipped: counts.skipped,
+        failed,
+        planned,
+    };
 }
 async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;

package/dist/core/runtime-paths.d.ts

@@ -1,8 +1,9 @@
 import path from "node:path";
 export interface RuntimePaths {
     appdata: string;
+    localAppdata: string;
     xdgConfig: string;
 }
 export declare function getPathApi(root: string): typeof path.posix | typeof path.win32;
 export declare function resolveRuntimePaths(home: string): RuntimePaths;
-export declare function resolveTargetTemplate(template: string, home: string, repo?: string): string;
+export declare function resolveTargetTemplate(template: string, home: string, repo?: string, workspace?: string): string;

package/dist/core/runtime-paths.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config|repo)\}(?<suffix>(?:[\\/].*)?)$/;
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|local_appdata|xdg_config|repo|workspace)\}(?<suffix>(?:[\\/].*)?)$/;
 export function getPathApi(root) {
     if (root.includes("\\") || /^[a-zA-Z]:/.test(root)) {
         return path.win32;
@@ -22,49 +22,56 @@ function isSameOrDescendantPath(candidate, root) {
 }
 export function resolveRuntimePaths(home) {
     const appdataRaw = process.env.APPDATA;
+    const localAppdataRaw = process.env.LOCALAPPDATA;
     const homePathApi = getPathApi(home);
     const appdata = appdataRaw && getPathApi(appdataRaw).isAbsolute(appdataRaw)
         ? appdataRaw
         : homePathApi.join(home, "AppData", "Roaming");
+    const localAppdata = localAppdataRaw && getPathApi(localAppdataRaw).isAbsolute(localAppdataRaw)
+        ? localAppdataRaw
+        : homePathApi.join(home, "AppData", "Local");
     const xdgRaw = process.env.XDG_CONFIG_HOME;
     const xdgConfig = xdgRaw && getPathApi(xdgRaw).isAbsolute(xdgRaw)
         ? xdgRaw
         : homePathApi.join(home, ".config");
-    return { appdata, xdgConfig };
+    return { appdata, localAppdata, xdgConfig };
 }
-export function resolveTargetTemplate(template, home, repo) {
-    const { appdata, xdgConfig } = resolveRuntimePaths(home);
+function resolveVfsPlaceholder(root, template, suffix, repo, workspace) {
+    const rootPath = root === "repo" ? repo : (workspace ?? repo);
+    if (!rootPath) {
+        throw new Error(`Target template uses {${root}} but no ${root} directory was provided: ${template}`);
+    }
+    const segments = suffix.split(/[\\/]+/).filter(Boolean);
+    const rootPathApi = getPathApi(rootPath);
+    const resolved = segments.length === 0 ? rootPath : rootPathApi.join(rootPath, ...segments);
+    if (!isSameOrDescendantPath(resolved, rootPath)) {
+        throw new Error(`Target template resolves outside its placeholder root: ${template}`);
+    }
+    return suffix === "" ? rootPath : `${rootPath}${suffix}`;
+}
+export function resolveTargetTemplate(template, home, repo, workspace) {
+    const { appdata, localAppdata, xdgConfig } = resolveRuntimePaths(home);
     const match = TARGET_TEMPLATE_RE.exec(template);
     if (!match) {
         throw new Error(`Invalid target template: ${template}`);
     }
     const root = match[1];
-    if (root === "repo") {
-        if (!repo) {
-            throw new Error(`Target template uses {repo} but no manifest directory was provided: ${template}`);
-        }
-        const suffix = match.groups?.suffix ?? "";
-        const segments = suffix.split(/[\\/]+/).filter(Boolean);
-        const repoPathApi = getPathApi(repo);
-        const resolved = segments.length === 0 ? repo : repoPathApi.join(repo, ...segments);
-        if (!isSameOrDescendantPath(resolved, repo)) {
-            throw new Error(`Target template resolves outside its placeholder root: ${template}`);
-        }
-        return suffix === "" ? repo : `${repo}${suffix}`;
+    const suffix = match.groups?.suffix ?? "";
+    if (root === "repo" || root === "workspace") {
+        return resolveVfsPlaceholder(root, template, suffix, repo, workspace);
     }
     const baseByRoot = {
         home,
         appdata,
+        local_appdata: localAppdata,
         xdg_config: xdgConfig,
     };
-    const suffix = match.groups?.suffix ?? "";
+    const base = baseByRoot[root];
     const segments = suffix.split(/[\\/]+/).filter(Boolean);
-    const pathApi = getPathApi(baseByRoot[root]);
-    const resolved = segments.length === 0
-        ? baseByRoot[root]
-        : pathApi.join(baseByRoot[root], ...segments);
-    if (!isSameOrDescendantPath(resolved, baseByRoot[root])) {
+    const pathApi = getPathApi(base);
+    const resolved = segments.length === 0 ? base : pathApi.join(base, ...segments);
+    if (!isSameOrDescendantPath(resolved, base)) {
         throw new Error(`Target template resolves outside its placeholder root: ${template}`);
     }
-    return suffix === "" ? baseByRoot[root] : `${baseByRoot[root]}${suffix}`;
+    return suffix === "" ? base : `${base}${suffix}`;
 }

package/dist/core/validation.d.ts

@@ -1,7 +1,16 @@
+import type { AgentId } from "../schemas/manifest.ts";
 export declare function sourceAccessError(err: unknown, sourcePath: string): string;
 export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
 export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;
 export declare function validateMcpServerConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
 export declare function validatePermissionsConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
 export declare function validateAgentRuleMarkdownPath(manifestPath: string, agentId: string): void;
-export declare function validateSkillDefinitionFile(sourcePath: string, manifestPath: string): Promise<void>;
+export declare function validateSkillDefinitionFile(sourcePath: string, manifestPath: string): Promise<{
+    attributes: Record<string, unknown>;
+    body: string;
+}>;
+/**
+ * Validates that an instruction file (agentRules or agentDefinitions) meets
+ * the structural requirements of the target agent.
+ */
+export declare function validateInstructionFileRequirements(sourcePath: string, manifestPath: string, agentId: AgentId): Promise<void>;