@kuznai/inception-engine 0.18.0 → 0.19.0

package/README.md

@@ -27,7 +27,7 @@ inception-engine reads a manifest file (`inception.json`) from the target direct
 
 Managed skills overwrite their previous version. If a target exists but was not created by inception-engine, deployment refuses to replace it. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
 
-Before executing, the deploy command runs preflight analysis on instruction files: it warns when the same agent will have both global and repo `agentRules` active simultaneously, when the same source file is deployed to both scopes (duplicate-content risk), and when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk). Warnings are printed but do not block deployment.
+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
 
@@ -51,11 +51,11 @@ 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, 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 via `scope: "global"` (home-dir) or `scope: "repo"` (project-root); antigravity always uses repo-local `.agents/rules/`; github-copilot reads CLAUDE.md natively (deploy via claude-code) | All agents |
+| 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 both global and repo `agentRules` active simultaneously (stacking advisory) or the same source file deployed to both scopes (duplicate-content warning); emits `budget` warnings when `agentRules` or `agentDefinitions` source files exceed 50 KB | N/A |
+| 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.
 
@@ -173,22 +173,23 @@ 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) or `"repo"`. Controls which instruction surface is targeted:
-  - `"global"` — deploys to the agent's home-directory instruction file (e.g., `~/.claude/CLAUDE.md` for `claude-code`)
-  - `"repo"` — deploys to the project-root instruction file inside the deployed repository (e.g., `{repo}/CLAUDE.md` for `claude-code`)
+- **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 all agents. The target path depends on the agent and the `scope`:
+Instruction rule deployment is supported for implemented global, repo, and workspace surfaces. The target path depends on the agent and the `scope`:
 
-| Agent | `scope: "global"` | `scope: "repo"` |
-|---|---|---|
-| `claude-code` | `~/.claude/CLAUDE.md` | `{repo}/CLAUDE.md` |
-| `codex` | `~/.codex/AGENTS.md` | `{repo}/AGENTS.md` |
-| `gemini-cli` | `~/.gemini/GEMINI.md` | `{repo}/GEMINI.md` |
-| `antigravity` | `{repo}/.agents/rules/{name}.md` | `{repo}/.agents/rules/{name}.md` |
-| `opencode` | `~/.config/opencode/AGENTS.md` | `{repo}/AGENTS.md` |
-| `github-copilot` | unsupported — reads `CLAUDE.md` natively | unsupported — deploy via `claude-code` |
+| 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`, both scopes target the same repo-local surface (`{repo}/.agents/rules/{name}.md`) since Antigravity has no global home-directory instruction file. For `github-copilot`, no separate deployment is needed for either scope — target it via the `claude-code` agentRules entry and it reaches Copilot automatically. Revert removes the deployed rules file.
+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:
 
@@ -275,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
@@ -366,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
@@ -380,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
@@ -389,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
@@ -405,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

@@ -60,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",
@@ -117,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",
@@ -175,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",
@@ -203,20 +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",
-            schemaLabel: "repo-local Markdown rules file",
+            surfaceKind: { kind: "shared-via", via: "gemini-cli" },
+            schemaLabel: "repo-local GEMINI.md",
             path: {
-                posix: ["{repo}", ".agents", "rules", "{name}.md"],
-                windows: ["{repo}", ".agents", "rules", "{name}.md"],
+                posix: ["{repo}", "GEMINI.md"],
+                windows: ["{repo}", "GEMINI.md"],
             },
         },
         permissionsSupport: {
@@ -232,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",
@@ -290,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",
@@ -298,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"],
@@ -314,15 +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: "unsupported",
+            status: "supported",
+            surfaceKind: {
+                kind: "shared-via",
+                via: "claude-code",
+                requiresPrimary: true,
+            },
             schemaLabel: "repo-local CLAUDE.md",
-            reason: 'GitHub Copilot reads CLAUDE.md natively, so deploy via the "claude-code" agentRules target with scope: "repo" instead of a separate rules surface',
+            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",
@@ -338,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/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>;

package/dist/core/adapters/mcp.js

@@ -46,7 +46,7 @@ function buildMcpDeployAction(entry, agentId, resolvedTarget, confidence, mcpPat
         confidence,
     };
 }
-export function compileMcpServerActions(entry, detectedAgents, home, repo) {
+export function compileMcpServerActions(entry, detectedAgents, home, repo, workspace) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
@@ -70,7 +70,7 @@ export function compileMcpServerActions(entry, detectedAgents, home, repo) {
             continue;
         }
         validateMcpServerConfigShape(entry.config, entry.name, agentId);
-        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const resolvedTarget = path.resolve(rawTarget);
         const confidence = agent.provenance.mcpConfig ?? "provisional";
         const mcpPatchKey = support.mcpPatchKey ?? "mcpServers";
@@ -78,7 +78,7 @@ export function compileMcpServerActions(entry, detectedAgents, home, repo) {
     }
     return { actions, warnings };
 }
-export function compileMcpServerReverts(entry, agentFilter, home, repo) {
+export function compileMcpServerReverts(entry, agentFilter, home, repo, workspace) {
     const actions = [];
     const platform = getPlatformKey();
     for (const agentId of entry.agents) {
@@ -90,7 +90,7 @@ export function compileMcpServerReverts(entry, agentFilter, home, repo) {
             support.status === "unsupported" ||
             support.status === "planned")
             continue;
-        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        const rawTarget = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
         const target = path.resolve(rawTarget);
         if (isMarkdownTarget(target)) {
             actions.push({

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

@@ -4,5 +4,5 @@ export interface RulesAdapterResult {
     actions: FileWriteDeployAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string): Promise<RulesAdapterResult>;
-export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string): FileWriteRevertAction[];
+export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<RulesAdapterResult>;
+export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

package/dist/core/adapters/rules.js

@@ -1,20 +1,25 @@
 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";
 function resolveRulesSupport(agentId, scope) {
     const agent = AGENT_REGISTRY_BY_ID[agentId];
     if (scope === "repo") {
         return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
     }
+    if (scope === "workspace") {
+        return (agent?.agentRulesWorkspaceSupport ??
+            agent?.agentRulesRepoSupport ??
+            agent?.agentRulesSupport);
+    }
     return agent?.agentRulesSupport;
 }
-function resolveAgentTarget(agentId, entry, home, repo, platform) {
+function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, allTargetAgentIds) {
     const support = resolveRulesSupport(agentId, entry.scope);
     if (!support || support.status === "unsupported") {
         return {
             kind: "confidence",
-            message: `agentRules: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported instruction schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported rules adapter"} — skipping "${entry.name}"`,
+            message: `agentRules: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported instruction schema"} (unsupported) and ${support?.status === "unsupported" ? support.reason : "does not expose a supported rules adapter"} — skipping "${entry.name}"`,
         };
     }
     if (support.status === "planned") {
@@ -23,20 +28,37 @@ function resolveAgentTarget(agentId, entry, home, repo, platform) {
             message: `agentRules: agent "${agentId}" rules support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
         };
     }
+    // shared-via: when requiresPrimary is set and the primary agent is absent
+    // from the target list, emit a guidance warning instead of deploying.
+    if (support.surfaceKind?.kind === "shared-via" &&
+        support.surfaceKind.requiresPrimary &&
+        allTargetAgentIds &&
+        !allTargetAgentIds.includes(support.surfaceKind.via)) {
+        return {
+            kind: "confidence",
+            message: `agentRules: agent "${agentId}" reads this surface via "${support.surfaceKind.via}" — add "${support.surfaceKind.via}" to the entry's agents list to deploy to this surface, or deploy via the "${support.surfaceKind.via}" agentRules target instead`,
+        };
+    }
     if (entry.scope === "repo" && !repo) {
         return {
             kind: "confidence",
             message: `agentRules: scope "repo" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
         };
     }
+    if (entry.scope === "workspace" && !workspace && !repo) {
+        return {
+            kind: "confidence",
+            message: `agentRules: scope "workspace" requires a workspace or repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
+        };
+    }
     const agent = AGENT_REGISTRY_BY_ID[agentId];
     return {
         agentId,
         confidence: agent?.provenance.agentRules ?? "provisional",
-        target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
+        target: resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace),
     };
 }
-export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
+export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
@@ -46,7 +68,7 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
         return { actions, warnings };
     }
     for (const agentId of targetAgents) {
-        const result = resolveAgentTarget(agentId, entry, home, repo, platform);
+        const result = resolveAgentTarget(agentId, entry, home, repo, platform, workspace, targetAgents);
         if ("kind" in result) {
             warnings.push(result);
         }
@@ -57,13 +79,34 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     if (supportedTargets.length === 0) {
         return { actions, warnings };
     }
+    // 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 sup = resolveRulesSupport(t.agentId, entry.scope);
+        if (sup?.status === "supported" &&
+            sup.surfaceKind?.kind === "shared-via" &&
+            supportedTargets.some((o) => o.agentId ===
+                sup.surfaceKind.via &&
+                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);
+        }
+    }
     // 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);
-    for (const target of supportedTargets) {
+    for (const target of dedupedTargets) {
         validateAgentRuleMarkdownPath(entry.path, target.agentId);
+        await validateInstructionFileRequirements(source, entry.path, target.agentId);
         actions.push({
             kind: "file-write",
             skill: entry.name,
@@ -75,23 +118,27 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     }
     return { actions, warnings };
 }
-export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
+export function compileAgentRuleReverts(entry, agentFilter, home, repo, workspace) {
     const actions = [];
     const platform = getPlatformKey();
+    const seenRevertTargets = new Set();
     for (const agentId of entry.agents) {
         if (agentFilter && !agentFilter.includes(agentId))
             continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = entry.scope === "repo"
-            ? (agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport)
-            : agent?.agentRulesSupport;
+        const support = resolveRulesSupport(agentId, entry.scope);
         if (!support ||
             support.status === "unsupported" ||
-            support.status === "planned")
+            support.status === "planned") {
             continue;
+        }
         if (entry.scope === "repo" && !repo)
             continue;
-        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
+        if (entry.scope === "workspace" && !workspace && !repo)
+            continue;
+        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo, workspace);
+        if (seenRevertTargets.has(target))
+            continue;
+        seenRevertTargets.add(target);
         actions.push({
             kind: "file-write",
             skill: entry.name,

package/dist/core/deploy.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning, SkillDirDeployAction } from "../types.ts";
 import { type RegistryPersistence } from "./ownership.ts";
-export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): Promise<{
+export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<{
     actions: DeployAction[];
     warnings: PlanWarning[];
 }>;