@kuznai/inception-engine 0.22.0 → 0.23.0

package/README.md

@@ -51,9 +51,10 @@ Before executing, the deploy command runs preflight analysis on instruction file
 | 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 (`scope: "global"` → `~/.claude.json`; `scope: "repo"` → `{repo}/.claude/mcp.json`; `scope: "workspace"` → `{workspace}/.claude/mcp.json`), gemini-cli, codex, antigravity (`scope: "global"` → `~/.gemini/antigravity/mcp_config.json`; `scope: "repo"` → `{repo}/.agents/rules/{name}.md`), opencode; github-copilot with `scope: "repo"` deploys to `{repo}/.vscode/mcp.json` and `scope: "workspace"` deploys to `{workspace}/.vscode/mcp.json`; github-copilot with `scope: "global"` (default) is unsupported and warns | claude-code, gemini-cli, codex, antigravity, opencode, github-copilot |
-| 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 |
+| 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` (shared-via) and also supports native `scope: "copilot-repo"` (`{repo}/.github/copilot-instructions.md`) and `scope: "copilot-scoped"` (`{repo}/.github/instructions/{name}.instructions.md`) | All supported agents |
 | Permissions / Approval Config | claude-code (`~/.claude/settings.json`), codex (`~/.codex/config.toml`), opencode (`~/.config/opencode/opencode.json` on POSIX, `%APPDATA%\\opencode\\opencode.json` on Windows); other agents are warned and skipped | claude-code, codex, opencode |
 | Execution Hooks | claude-code (`~/.claude/settings.json`), github-copilot (`planned`); other agents are warned and skipped | claude-code |
+| Execution / Safety Config | gemini-cli (`~/.gemini/settings.json`); other agents are warned and skipped | gemini-cli |
 | Agent Definitions | claude-code (`{repo}/.claude/agents/{name}.md`), gemini-cli (`{repo}/.gemini/agents/{name}.md` or `.toml`, plus `scope: "global"` to `~/.gemini/agents/{name}.md` or `.toml`), antigravity (`{repo}/.agents/rules/{name}.md`), opencode (`{repo}/.opencode/agents/{name}.md`, plus `scope: "global"` to the user config dir), github-copilot (`{repo}/.github/copilot/agents/{name}.md`, with migration from legacy `.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`); shared surfaces default to the primary deploy target instead of shared riders; emits hints for `files/` and `configs/` directories | N/A |
 | Instruction preflight analysis | Emits capability warnings for implementation-only, planned, unsupported, and shared-through surfaces used by the manifest; 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; emits a `config-authority` warning when Gemini CLI's `settings.json` contains an `instructionFilename` override that differs from the deploy target | N/A |
@@ -143,10 +144,29 @@ Create an `inception.json` file at the root of your skills directory:
       "agents": ["claude-code"],
       "config": {
         "hooks": {
-          "pre_exec": "scripts/check-env.sh"
+          "PreToolUse": [
+            {
+              "matcher": "Bash",
+              "hooks": [{ "type": "command", "command": "scripts/check-env.sh" }]
+            }
+          ],
+          "Stop": [
+            {
+              "hooks": [{ "type": "command", "command": "scripts/notify.sh" }]
+            }
+          ]
         }
       }
     }
+  ],
+  "executionConfigs": [
+    {
+      "name": "gemini-safety",
+      "agents": ["gemini-cli"],
+      "config": {
+        "safeMode": true
+      }
+    }
   ]
 }
 ```
@@ -202,10 +222,12 @@ Each **agentRules** entry deploys a Markdown instruction file to an agent's supp
 - **name** - Unique identifier (same format as skill names)
 - **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:
+- **scope** - `"global"` (default), `"repo"`, `"workspace"`, `"copilot-repo"`, or `"copilot-scoped"`. 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
+  - `"copilot-repo"` — deploys to GitHub Copilot's native repo-level instruction file at `{repo}/.github/copilot-instructions.md` (`github-copilot` only; other agents are warned and skipped)
+  - `"copilot-scoped"` — deploys to `{repo}/.github/instructions/{name}.instructions.md` where `{name}` is the manifest entry name (`github-copilot` only; other agents are warned and skipped)
 
 Instruction rule deployment is supported for implemented global, repo, and workspace surfaces. The target path depends on the agent and the `scope`:
 
@@ -218,7 +240,13 @@ Instruction rule deployment is supported for implemented global, repo, and works
 | `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.
+GitHub Copilot also exposes two native instruction surfaces via dedicated scope values:
+
+| Agent | `scope: "copilot-repo"` | `scope: "copilot-scoped"` |
+|---|---|---|
+| `github-copilot` | `{repo}/.github/copilot-instructions.md` | `{repo}/.github/instructions/{name}.instructions.md` |
+
+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`, the Claude-first path (targeting via `claude-code` agentRules) remains the recommended approach for shared rules; the `copilot-repo` and `copilot-scoped` scopes are for Copilot-specific instructions that should not be shared with other agents. When both are present, preflight emits a precedence warning. Revert removes the deployed rules file.
 
 Each **permissions** entry deploys execution and safety-oriented configuration to an agent's permission or approval surface:
 
@@ -269,7 +297,7 @@ Each **hooks** entry deploys lifecycle-binding configurations to an agent's exec
 
 Hook deployment is currently supported for `claude-code`. For `github-copilot`, it is marked as `planned`. Other agents emit a warning and are skipped.
 
-For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the `hooks` key is accepted:
+For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the `hooks` key is accepted. Event names follow Claude Code's settings.json hooks surface (e.g. `PreToolUse`, `PostToolUse`, `Notification`, `Stop`, `SubagentStop`). Each event maps to an array of hook matchers; each matcher has an optional `matcher` string and a required `hooks` array of `{ type: "command", command: string }` objects:
 
 ```json
 {
@@ -277,8 +305,17 @@ For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the
   "agents": ["claude-code"],
   "config": {
     "hooks": {
-      "pre_exec": "scripts/check-env.sh",
-      "post_exec": "scripts/notify.sh"
+      "PreToolUse": [
+        {
+          "matcher": "Bash",
+          "hooks": [{ "type": "command", "command": "scripts/check-env.sh" }]
+        }
+      ],
+      "Stop": [
+        {
+          "hooks": [{ "type": "command", "command": "scripts/notify.sh" }]
+        }
+      ]
     }
   }
 }
@@ -341,7 +378,7 @@ Current `init` behavior:
 - Applies either the `--agents` list or all currently known agent IDs
 - Refuses to overwrite an existing `inception.json` unless `--force` is provided
 - 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 unsupported agents plus shared-surface riders that should default to their primary deploy target
+- 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` found outside `.github/` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), `.github/copilot-instructions.md` maps to `github-copilot` with `scope: "copilot-repo"`, and `*.instructions.md` files in `.github/instructions/` map to `github-copilot` with `scope: "copilot-scoped"`; the fallback for unrecognized files excludes unsupported agents plus shared-surface riders that should default to their primary deploy target
 - 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

package/dist/src/config/agents.js

@@ -185,6 +185,7 @@ export const AGENT_REGISTRY = [
             agentRules: "documented",
             hooks: "provisional",
             agentDefinitions: "documented",
+            executionConfig: "provisional",
         },
         mcpSupport: {
             status: "supported",
@@ -256,6 +257,14 @@ export const AGENT_REGISTRY = [
                 windows: ["{repo}", ".gemini", "agents", "{name}.toml"],
             },
         },
+        executionConfigSupport: {
+            status: "supported",
+            schemaLabel: "Settings execution config",
+            path: {
+                posix: ["{home}", ".gemini", "settings.json"],
+                windows: ["{home}", ".gemini", "settings.json"],
+            },
+        },
         agentRulesWorkspaceSupport: {
             status: "supported",
             schemaLabel: "workspace-local GEMINI.md",
@@ -443,6 +452,7 @@ export const AGENT_REGISTRY = [
         provenance: {
             detectPaths: "documented",
             detectBinary: "documented",
+            agentRules: "documented",
             agentDefinitions: "documented",
             mcpConfig: "documented",
             hooks: "provisional",
@@ -514,6 +524,35 @@ export const AGENT_REGISTRY = [
                 windows: ["{workspace}", "CLAUDE.md"],
             },
         },
+        // GitHub Copilot native repo-level instruction file. Not shared via
+        // CLAUDE.md; this is Copilot's own .github/copilot-instructions.md surface
+        // deployed directly without the shared-via deduplication path.
+        agentRulesCopilotRepoSupport: {
+            status: "supported",
+            surfaceKind: { kind: "agent-specific" },
+            schemaLabel: "repo-local .github/copilot-instructions.md",
+            path: {
+                posix: ["{repo}", ".github", "copilot-instructions.md"],
+                windows: ["{repo}", ".github", "copilot-instructions.md"],
+            },
+        },
+        // GitHub Copilot scoped instruction files. Each entry deploys to
+        // .github/instructions/{name}.instructions.md where {name} comes from
+        // the manifest entry name field.
+        agentRulesCopilotScopedSupport: {
+            status: "supported",
+            surfaceKind: { kind: "agent-specific" },
+            schemaLabel: "scoped .github/instructions/{name}.instructions.md",
+            path: {
+                posix: ["{repo}", ".github", "instructions", "{name}.instructions.md"],
+                windows: [
+                    "{repo}",
+                    ".github",
+                    "instructions",
+                    "{name}.instructions.md",
+                ],
+            },
+        },
         mcpDevcontainerSupport: {
             status: "supported",
             schemaLabel: "devcontainer.json MCP surface",

package/dist/src/core/adapters/execution-config.d.ts

@@ -0,0 +1,14 @@
+import type { ExecutionConfigEntry } from "../../schemas/manifest.ts";
+import type { AgentId, ConfigPatchDeployAction, ConfigPatchRevertAction, PlanWarning } from "../../types.ts";
+export interface ExecutionConfigAdapterResult {
+    actions: ConfigPatchDeployAction[];
+    warnings: PlanWarning[];
+}
+/**
+ * Compiles deploy actions for executionConfigs manifest entries.
+ *
+ * Execution configuration settings (like Gemini CLI's safeMode) are patched
+ * directly into the agent's primary settings file using config-patch actions.
+ */
+export declare function compileExecutionConfigActions(entry: ExecutionConfigEntry, detectedAgents: AgentId[], home: string): ExecutionConfigAdapterResult;
+export declare function compileExecutionConfigReverts(entry: ExecutionConfigEntry, agentFilter: AgentId[] | null, home: string): ConfigPatchRevertAction[];

package/dist/src/core/adapters/execution-config.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
+import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
+/**
+ * Compiles deploy actions for executionConfigs manifest entries.
+ *
+ * Execution configuration settings (like Gemini CLI's safeMode) are patched
+ * directly into the agent's primary settings file using config-patch actions.
+ */
+export function compileExecutionConfigActions(entry, detectedAgents, home) {
+    const actions = [];
+    const warnings = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (!detectedAgents.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.executionConfigSupport ||
+            agent.executionConfigSupport.status !== "supported") {
+            warnings.push({
+                kind: "confidence",
+                message: `Agent "${agentId}" does not support modeled execution configuration surfaces — skipping "${entry.name}"`,
+            });
+            continue;
+        }
+        const rawTarget = resolvePlaceholders(agent.executionConfigSupport.path[platform], entry.name, home);
+        const target = path.resolve(rawTarget);
+        actions.push({
+            kind: "config-patch",
+            skill: entry.name,
+            agent: agentId,
+            target,
+            patch: entry.config,
+            confidence: "provisional",
+        });
+    }
+    return { actions, warnings };
+}
+export function compileExecutionConfigReverts(entry, agentFilter, home) {
+    const actions = [];
+    const platform = getPlatformKey();
+    for (const agentId of entry.agents) {
+        if (agentFilter && !agentFilter.includes(agentId))
+            continue;
+        const agent = AGENT_REGISTRY_BY_ID[agentId];
+        if (!agent?.executionConfigSupport ||
+            agent.executionConfigSupport.status !== "supported") {
+            continue;
+        }
+        const rawTarget = resolvePlaceholders(agent.executionConfigSupport.path[platform], entry.name, home);
+        const target = path.resolve(rawTarget);
+        actions.push({
+            kind: "config-patch",
+            skill: entry.name,
+            agent: agentId,
+            target,
+        });
+    }
+    return actions;
+}

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

@@ -1,14 +1,15 @@
-import type { AgentDefinitionEntry, AgentRuleEntry, HookEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
+import type { AgentDefinitionEntry, AgentRuleEntry, ExecutionConfigEntry, HookEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
 import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, FrontmatterEmitDeployAction, PlanWarning, TomlPatchDeployAction } from "../../types.ts";
 import { compileAgentDefinitionReverts } from "./agent-definitions.ts";
+import { compileExecutionConfigReverts } from "./execution-config.ts";
 import { compileHookReverts } from "./hooks.ts";
 import { compileMcpServerReverts } from "./mcp.ts";
 import { compilePermissionsReverts } from "./permissions.ts";
 import { compileAgentRuleReverts } from "./rules.ts";
-export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileExecutionConfigReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
 export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction | TomlPatchDeployAction | FrontmatterEmitDeployAction;
 export interface AdapterResult {
     actions: AdapterAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string, hooks?: HookEntry[]): 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, hooks?: HookEntry[], executionConfigs?: ExecutionConfigEntry[]): Promise<AdapterResult>;

package/dist/src/core/adapters/index.js

@@ -1,9 +1,10 @@
 import { compileAgentDefinitionActions, compileAgentDefinitionReverts, } from "./agent-definitions.js";
+import { compileExecutionConfigActions, compileExecutionConfigReverts, } from "./execution-config.js";
 import { compileHookActions, compileHookReverts } from "./hooks.js";
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compilePermissionsActions, compilePermissionsReverts, } from "./permissions.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
-export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
+export { compileAgentDefinitionReverts, compileAgentRuleReverts, compileExecutionConfigReverts, compileHookReverts, compileMcpServerReverts, compilePermissionsReverts, };
 async function compileAll(entries, fn) {
     const results = await Promise.all(entries.map(fn));
     return {
@@ -11,17 +12,18 @@ async function compileAll(entries, fn) {
         warnings: results.flatMap((r) => r.warnings),
     };
 }
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace, hooks = []) {
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace, hooks = [], executionConfigs = []) {
     const actions = [];
     const warnings = [];
-    const [mcp, rules, perms, defs, hookResults] = await Promise.all([
+    const [mcp, rules, perms, defs, hookResults, execResults] = await Promise.all([
         compileAll(mcpServers, (entry) => compileMcpServerActions(entry, detectedAgents, home, repo, workspace)),
         compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
         compileAll(permissions, (entry) => compilePermissionsActions(entry, detectedAgents, home)),
         compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
         compileAll(hooks, (entry) => compileHookActions(entry, detectedAgents, home)),
+        compileAll(executionConfigs, (entry) => compileExecutionConfigActions(entry, detectedAgents, home)),
     ]);
-    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions, ...hookResults.actions);
-    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings, ...hookResults.warnings);
+    actions.push(...mcp.actions, ...rules.actions, ...perms.actions, ...defs.actions, ...hookResults.actions, ...execResults.actions);
+    warnings.push(...mcp.warnings, ...rules.warnings, ...perms.warnings, ...defs.warnings, ...hookResults.warnings, ...execResults.warnings);
     return { actions, warnings };
 }

package/dist/src/core/adapters/rules.js

@@ -2,6 +2,37 @@ import path from "node:path";
 import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
 import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+function requiresRepoPath(scope) {
+    return (scope === "repo" || scope === "copilot-repo" || scope === "copilot-scoped");
+}
+function deduplicateTargets(supportedTargets, scope) {
+    const seenTargetPaths = new Set();
+    const dedupedTargets = [];
+    for (const t of supportedTargets) {
+        const surface = resolveCapabilitySurface(t.agentId, "agentRules", scope);
+        if (surface.surfaceKind === "shared-via" &&
+            surface.sharedVia &&
+            supportedTargets.some((o) => o.agentId === surface.sharedVia && o.target === t.target)) {
+            continue;
+        }
+        if (!seenTargetPaths.has(t.target)) {
+            seenTargetPaths.add(t.target);
+            dedupedTargets.push(t);
+        }
+    }
+    return dedupedTargets;
+}
+function injectTargetDir(pathSegments, targetDir) {
+    if (!targetDir)
+        return pathSegments;
+    const placeholderIndex = pathSegments.findIndex((seg) => seg === "{repo}" || seg === "{workspace}");
+    if (placeholderIndex === -1)
+        return pathSegments;
+    const dirSegments = targetDir.split(/[\\/]+/).filter(Boolean);
+    const result = [...pathSegments];
+    result.splice(placeholderIndex + 1, 0, ...dirSegments);
+    return result;
+}
 function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, allTargetAgentIds) {
     const plan = planCapabilityForDeploy({
         agentId,
@@ -28,10 +59,17 @@ function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, all
             message: `agentRules: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
         };
     }
+    if ((entry.scope === "copilot-repo" || entry.scope === "copilot-scoped") &&
+        !repo) {
+        return {
+            kind: "confidence",
+            message: `agentRules: scope "${entry.scope}" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
     return {
         agentId,
         confidence: plan.confidence,
-        target: resolvePlaceholders(support?.path[platform] ?? [], entry.name, home, repo, workspace),
+        target: resolvePlaceholders(injectTargetDir(support?.path[platform] ?? [], entry.targetDir), entry.name, home, repo, workspace),
     };
 }
 export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
@@ -61,29 +99,22 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     // Deduplicate: when a shared-via rider's primary is also in supportedTargets,
     // skip the rider — the primary agent writes the shared surface. As a fallback,
     // also dedup by resolved path so no target file is written twice.
-    const seenTargetPaths = new Set();
-    const dedupedTargets = [];
-    for (const t of supportedTargets) {
-        const surface = resolveCapabilitySurface(t.agentId, "agentRules", entry.scope);
-        if (surface.surfaceKind === "shared-via" &&
-            surface.sharedVia &&
-            supportedTargets.some((o) => o.agentId === surface.sharedVia && o.target === t.target)) {
-            // Primary agent is present and writes the same target — skip rider.
-            continue;
-        }
-        if (!seenTargetPaths.has(t.target)) {
-            seenTargetPaths.add(t.target);
-            dedupedTargets.push(t);
-        }
-    }
+    const dedupedTargets = deduplicateTargets(supportedTargets, entry.scope);
     // Validate the shared source file only when at least one target uses the
     // current rules adapter surface.
     const source = path.resolve(sourceDir, entry.path);
     await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
     await validateSourceFile(source, entry.path);
+    // Native Copilot instruction files (.github/copilot-instructions.md and
+    // .github/instructions/*.instructions.md) are plain markdown and do not
+    // require agent-definition-style frontmatter (tools/instructions keys).
+    // Skip the instructionFrontmatterRequired check for these scopes.
+    const skipFrontmatterValidation = entry.scope === "copilot-repo" || entry.scope === "copilot-scoped";
     for (const target of dedupedTargets) {
         validateAgentRuleMarkdownPath(entry.path, target.agentId);
-        await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        if (!skipFrontmatterValidation) {
+            await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        }
         actions.push({
             kind: "file-write",
             skill: entry.name,
@@ -107,11 +138,11 @@ export function compileAgentRuleReverts(entry, agentFilter, home, repo, workspac
         if (surface.supportStatus !== "supported" || !support) {
             continue;
         }
-        if (entry.scope === "repo" && !repo)
+        if (requiresRepoPath(entry.scope) && !repo)
             continue;
         if (entry.scope === "workspace" && !workspace && !repo)
             continue;
-        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
+        const target = resolvePlaceholders(injectTargetDir(support.path[platform], entry.targetDir), entry.name, home, repo, workspace);
         if (seenRevertTargets.has(target))
             continue;
         seenRevertTargets.add(target);

package/dist/src/core/capabilities.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId, AgentSurfaceSupport, CapabilityKind, Confidence, PlanWarning, SupportedAgentSurface } from "../types.ts";
-type CapabilityScope = "global" | "repo" | "workspace" | "devcontainer";
+type CapabilityScope = "global" | "repo" | "workspace" | "devcontainer" | "copilot-repo" | "copilot-scoped";
 export interface ResolvedCapabilitySurface {
     agentId: AgentId;
     capability: CapabilityKind;

package/dist/src/core/capabilities.js

@@ -1,6 +1,12 @@
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 function resolveAgentRulesSupport(agentId, scope) {
     const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "copilot-repo") {
+        return agent?.agentRulesCopilotRepoSupport;
+    }
+    if (scope === "copilot-scoped") {
+        return agent?.agentRulesCopilotScopedSupport;
+    }
     if (scope === "repo") {
         return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
     }
@@ -52,6 +58,8 @@ function capabilityLabel(capability) {
             return "agentDefinitions";
         case "hooks":
             return "hooks";
+        case "executionConfigs":
+            return "executionConfigs";
     }
 }
 function capabilitySurfaceLabel(capability) {
@@ -68,6 +76,8 @@ function capabilitySurfaceLabel(capability) {
             return "agent-definitions";
         case "hooks":
             return "hooks";
+        case "executionConfigs":
+            return "execution-config";
     }
 }
 function resolveSkillsCapability(agentId) {
@@ -125,9 +135,15 @@ function getSurfaceRecordAndConfidence(agentId, capability, scope) {
             confidence: agent.provenance.agentDefinitions,
         };
     }
+    if (capability === "hooks") {
+        return {
+            supportRecord: agent.hooksSupport,
+            confidence: agent.provenance.hooks,
+        };
+    }
     return {
-        supportRecord: agent.hooksSupport,
-        confidence: agent.provenance.hooks,
+        supportRecord: agent.executionConfigSupport,
+        confidence: agent.provenance.executionConfig,
     };
 }
 function resolveUnsupportedSurface(agentId, capability, supportRecord, confidence) {

package/dist/src/core/deploy.js

@@ -280,7 +280,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, workspace)),
         ...planConfigPatchActions(manifest, detectedAgents, home, repoDir, workspace),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace, manifest.hooks ?? []);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace, manifest.hooks ?? [], manifest.executionConfigs ?? []);
     actions.push(...adapterResult.actions);
     const warnings = [
         ...skillPlan.warnings,

package/dist/src/core/init.js

@@ -32,9 +32,10 @@ const AGENT_RULES_FILE_PATTERNS = (() => {
             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.
+        // Convention mapping for copilot-instructions.md found outside .github/:
+        // map to claude-code since Copilot reads CLAUDE.md natively. Files at
+        // .github/copilot-instructions.md are handled separately as a native
+        // Copilot surface via the copilot-repo scope.
         {
             fileNames: ["copilot-instructions.md"],
             agents: ["claude-code"],
@@ -183,18 +184,73 @@ async function findAgentRulesCandidates(baseDir, skillDirRelPaths) {
     for (const subdir of AGENT_RULES_SUBDIRS) {
         await scanDirForMarkdown(path.join(baseDir, subdir), baseDir, skillDirRelPaths, seen, candidates);
     }
+    // Promote .github/copilot-instructions.md to the native copilot-repo scope.
+    // The general scanDirForMarkdown pass above picks it up via AGENT_RULES_SUBDIRS
+    // (".github"), so we just patch the candidate that was already added.
+    const copilotRepoRelPath = ".github/copilot-instructions.md";
+    const copilotRepoCandidate = candidates.find((c) => c.relPath === copilotRepoRelPath);
+    if (copilotRepoCandidate) {
+        copilotRepoCandidate.defaultAgents = ["github-copilot"];
+        copilotRepoCandidate.scope = "copilot-repo";
+    }
+    // Discover .github/instructions/*.instructions.md as copilot-scoped entries.
+    // These are not covered by the general scan (it only looks for .md/.markdown
+    // and the stem derivation would lose the .instructions suffix).
+    const instructionsDir = path.join(baseDir, ".github", "instructions");
+    let instrEntries;
+    try {
+        instrEntries = await readdir(instructionsDir, {
+            withFileTypes: true,
+            encoding: "utf-8",
+        });
+    }
+    catch {
+        instrEntries = [];
+    }
+    for (const entry of instrEntries) {
+        if (!entry.isFile())
+            continue;
+        const lower = entry.name.toLowerCase();
+        if (!lower.endsWith(".instructions.md"))
+            continue;
+        const absPath = path.join(instructionsDir, entry.name);
+        const relPath = path.relative(baseDir, absPath).split(path.sep).join("/");
+        if (seen.has(relPath) || isInsideSkillDir(relPath, skillDirRelPaths))
+            continue;
+        // Derive name by stripping ".instructions.md" suffix
+        const baseStem = entry.name.slice(0, -".instructions.md".length);
+        const rawName = baseStem.toLowerCase().replace(/[^a-zA-Z0-9._-]/g, "-");
+        if (!SAFE_NAME_RE.test(rawName)) {
+            logger.warn("init", `Skipping "${relPath}": could not derive a valid agentRules name`);
+            continue;
+        }
+        seen.add(relPath);
+        candidates.push({
+            relPath,
+            name: rawName,
+            defaultAgents: ["github-copilot"],
+            scope: "copilot-scoped",
+        });
+    }
     return candidates;
 }
-function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
+function buildAgentRules(candidates, activeAgents, allAgents, skillNamesSeen) {
     const rules = [];
     const namesSeen = new Set(skillNamesSeen);
-    for (const { relPath, name: rawName } of candidates) {
-        const fileName = path.basename(relPath);
-        const defaultAgents = defaultAgentsForFile(fileName, activeAgents);
-        // Intersect with active agents; fall back to full active list if empty
-        const intersection = defaultAgents.filter((a) => activeAgents.includes(a));
-        const agents = intersection.length > 0 ? intersection : activeAgents;
-        // Skip if no capable agents remain (e.g. --agents github-copilot only)
+    for (const { relPath, name: rawName, defaultAgents: presetAgents, scope: presetScope, } of candidates) {
+        let agents;
+        if (presetAgents.length > 0) {
+            // Candidates with preset agents (e.g. copilot-repo, copilot-scoped) use
+            // those agents directly, intersected with the full agents list.
+            agents = presetAgents.filter((a) => allAgents.includes(a));
+        }
+        else {
+            // Derive from filename pattern and intersect with active (capable) agents.
+            const defaults = defaultAgentsForFile(path.basename(relPath), activeAgents);
+            const ix = defaults.filter((a) => activeAgents.includes(a));
+            agents = ix.length > 0 ? ix : activeAgents;
+        }
+        // Skip if excluded by --agents or no capable agents remain
         if (agents.length === 0)
             continue;
         // Resolve name collision with skill names
@@ -211,7 +267,7 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
             }
         }
         namesSeen.add(name);
-        rules.push({ name, path: relPath, agents, scope: "global" });
+        rules.push({ name, path: relPath, agents, scope: presetScope ?? "global" });
     }
     return rules;
 }
@@ -576,7 +632,7 @@ export async function runInit(options) {
     const skillNamesSeen = new Set(skills.map((s) => s.name));
     const skillDirRelPaths = new Set(found.map((f) => f.relPath));
     const agentRulesCandidates = await findAgentRulesCandidates(directory, skillDirRelPaths);
-    const agentRules = buildAgentRules(agentRulesCandidates, agentRulesCapableAgents, skillNamesSeen);
+    const agentRules = buildAgentRules(agentRulesCandidates, agentRulesCapableAgents, agents, skillNamesSeen);
     const allNamesSeen = new Set([
         ...skillNamesSeen,
         ...agentRules.map((r) => r.name),