@klhapp/skillmux 1.10.0 → 1.11.1

package/src/completions.ts

@@ -1,3 +1,5 @@
+import { MANAGED_PINS_AGENT_IDS, SUPPORTED_AGENT_IDS } from "./init-agents";
+
 export type ShellType = "bash" | "zsh" | "fish";
 
 const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
@@ -6,7 +8,7 @@ const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
   { name: "serve", description: "Start MCP server" },
   { name: "index", description: "Rebuild local search index" },
   { name: "sync", description: "Synchronize vault skills" },
-  { name: "init", description: "Configure this machine and its clients" },
+  { name: "init", description: "Configure this machine and its agents" },
   { name: "project", description: "Configure project-scoped skills" },
   { name: "target", description: "Manage advanced skill-delivery targets" },
   { name: "core", description: "Pin/unpin skills into [core]" },
@@ -62,18 +64,25 @@ _skillmux_completions() {
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
-        --client)
-            COMPREPLY=( $(compgen -W "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -- "$cur") )
+        eval)
+            COMPREPLY=( $(compgen -W "promote" -- "$cur") )
             ;;
-        --target)
-            COMPREPLY=( $(compgen -W "agent-skills claude-code codex custom" -- "$cur") )
+        --agent)
+            if [ "\${COMP_WORDS[1]}" = "project" ]; then
+                COMPREPLY=( $(compgen -W "${MANAGED_PINS_AGENT_IDS.join(" ")}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${SUPPORTED_AGENT_IDS.join(" ")}" -- "$cur") )
+            fi
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --dir --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--agent --vault --core --migrate-full-vault --show-mcp-setup --register-mcp --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
     if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
-        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--name --skill --agent --target --register-mcp --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "eval" ] && [ "\${COMP_WORDS[2]}" = "promote" ]; then
+        COMPREPLY=( $(compgen -W "--since --out --dry-run --yes --json" -- "$cur") )
     fi
 }
 complete -F _skillmux_completions skillmux
@@ -92,12 +101,12 @@ ${commands}
         _describe -t commands 'skillmux command' commands
     elif [[ "$words[2]" == "init" ]]; then
         _arguments \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \\
-          '*--target[select a delivery target]:target:(agent-skills claude-code codex custom)' \\
-          '--dir[custom target directory]:directory:_directories' \\
+          '*--agent[select an agent]:agent:(${SUPPORTED_AGENT_IDS.join(" ")})' \\
           '--vault[vault directory]:directory:_directories' \\
           '*--core[seed a core skill]:skill id:' \\
           '--migrate-full-vault[convert a full-vault symlink to managed pins]' \\
+          '--show-mcp-setup[also print the MCP registration snippet]' \\
+          '--register-mcp[register skillmux via the agent own CLI]' \\
           '--no-instructions[skip managed instruction files]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
@@ -109,8 +118,9 @@ ${commands}
           '1:project directory:_directories' \\
           '--name[project group name]:group:' \\
           '*--skill[project skill]:skill id:' \\
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \\
+          '*--agent[select an agent]:agent:(${MANAGED_PINS_AGENT_IDS.join(" ")})' \\
           '*--target[select an advanced target]:target:' \\
+          '--register-mcp[register a project-scoped MCP server for claude-code]' \\
           '--no-sync[save setup without synchronizing targets]' \\
           '--interactive[force guided setup]' \\
           '--yes[apply without prompts]' \\
@@ -118,6 +128,15 @@ ${commands}
           '--json[emit a JSON envelope]'
     elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
         _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "eval" && "$words[3]" == "promote" ]]; then
+        _arguments \
+          '--since[time window]:window:' \
+          '--out[output file]:file:_files' \
+          '--dry-run[print the plan without writing]' \
+          '--yes[apply without prompts]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "eval" && CURRENT == 3 ]]; then
+        _values 'eval command' promote
     elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
         _values 'target command' list show add remove
     elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
@@ -139,12 +158,12 @@ _skillmux "$@"
     return `# fish completion for skillmux
 complete -c skillmux -f
 ${topLevel}
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a delivery target"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l dir -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l agent -x -a "${SUPPORTED_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l show-mcp-setup -d "Also print the MCP registration snippet"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l register-mcp -d "Register skillmux via the agent's own CLI"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-instructions -d "Skip managed instruction files"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
@@ -154,11 +173,18 @@ complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JS
 complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
-complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l agent -x -a "${MANAGED_PINS_AGENT_IDS.join(" ")}" -d "Select an agent"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l register-mcp -d "Register a project-scoped MCP server for claude-code"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval" -a "promote" -d "Promote correlated fetches into eval cases"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l since -x -d "Time window"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l out -r -d "Output file"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l dry-run -d "Print the plan without writing"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l json -d "Emit a JSON envelope"
 complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
 complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
 complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"

package/src/config-service.ts

@@ -309,7 +309,7 @@ export async function getDottedKey(key: string, configPath?: string): Promise<un
 export async function setDottedKey(
   key: string,
   rawValStr: string,
-  opts?: { configPath?: string; dryRun?: boolean; targetName?: string }
+  opts?: { configPath?: string; dryRun?: boolean; contextName?: string }
 ): Promise<SetConfigResult> {
   validateDottedKey(key);
   if (isEnvMasked(key)) {
@@ -317,7 +317,7 @@ export async function setDottedKey(
   }
 
   const path = opts?.configPath ?? process.env.SKILLMUX_CONFIG ?? DEFAULT_CONFIG_PATH;
-  const targetName = opts?.targetName ?? "local";
+  const contextName = opts?.contextName ?? "local";
 
   const { effective: priorEffective, rawToml } = await getEffectiveConfig(path);
   const priorVal = getNestedValue(priorEffective as Record<string, any>, key);
@@ -364,7 +364,7 @@ export async function setDottedKey(
     key,
     prior_val: priorVal,
     resulting_val: parsedVal,
-    target: targetName,
+    target: contextName,
     prior_revision: priorRevision,
     resulting_revision: resultingRevision,
     persistence,

package/src/init-agents.ts

@@ -0,0 +1,329 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SUPPORTED_AGENT_IDS = [
+  "claude-code",
+  "codex",
+  "opencode",
+  "github-copilot",
+  "windsurf",
+  "antigravity",
+  "goose",
+  "hermes",
+] as const;
+
+export type AgentId = (typeof SUPPORTED_AGENT_IDS)[number];
+export type DeliveryMode = "managed-pins" | "full-vault";
+
+export interface DetectedAgent {
+  agent: AgentId;
+  evidence: string;
+}
+
+export type McpRegistrationScope = "user" | "project";
+
+export interface McpRegistrationCommand {
+  command: string;
+  /** Returns undefined when this agent's CLI has no way to register at the requested scope. */
+  buildArgs: (scope: McpRegistrationScope) => string[] | undefined;
+}
+
+interface AgentPathOptions {
+  home: string;
+  codexHome: string;
+}
+
+interface AgentInstructionOptions extends AgentPathOptions {
+  claudeConfigDir: string;
+}
+
+/**
+ * The single source of truth for what each agent supports. Every other
+ * module (detection, skill-surface planning, readiness reporting, MCP
+ * registration, instruction files, shell completions, CLI help text) reads
+ * from this record instead of keeping its own copy — see git history for
+ * what it looked like before consolidation (agent support was duplicated
+ * across 6+ files and could silently drift, e.g. shell completions offering
+ * goose/hermes for `project init` when they can't actually be attached).
+ */
+interface AgentDefinition {
+  id: AgentId;
+  surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
+  deliveryMode: DeliveryMode;
+  /** Filesystem evidence used by guided-mode agent detection. */
+  detectionPath?: (options: AgentPathOptions) => string;
+  /** Bespoke readiness message for full-vault agents with no managed-pins surface. */
+  manualSkillSurfaceMessage?: string;
+  instructions?: {
+    global?: (options: AgentInstructionOptions) => string;
+    project?: (projectRoot: string) => string;
+  };
+  /**
+   * Only set for agents whose own CLI's exact registration command was
+   * verified against its own --help, not guessed from docs. Every other
+   * agent falls back to printing the registration snippet (see
+   * printLastMile in init.ts) rather than a guessed command.
+   */
+  mcpRegistration?: McpRegistrationCommand;
+}
+
+export interface PlannedAgentSurface {
+  id: string;
+  targetName: string;
+  path: string;
+  deliveryMode: "managed-pins";
+  agents: AgentId[];
+}
+
+export interface AgentSurfacePlan {
+  agents: AgentDefinition[];
+  surfaces: PlannedAgentSurface[];
+}
+
+type ReadinessStatus = "ready" | "planned" | "manual" | "not-applicable";
+
+export interface ReadinessAxis {
+  status: ReadinessStatus;
+  detail: string;
+}
+
+export interface AgentReadiness {
+  agent: AgentId;
+  skillSurface: ReadinessAxis;
+  mcpRegistration: ReadinessAxis;
+  instructionSetup: ReadinessAxis;
+}
+
+export interface ResolvedBuiltInTarget {
+  targetName: string;
+  path: string;
+}
+
+/** Target names whose install directory is deterministic — --dir is optional for these. */
+export const BUILT_IN_TARGET_NAMES = new Set(["agent-skills", "claude-code", "codex"]);
+
+const AGENTS: Record<AgentId, AgentDefinition> = {
+  "claude-code": {
+    id: "claude-code",
+    surfaceId: "claude-code",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".claude"),
+    instructions: {
+      global: ({ claudeConfigDir }) => join(claudeConfigDir, "CLAUDE.md"),
+      project: (projectRoot) => join(projectRoot, "CLAUDE.md"),
+    },
+    mcpRegistration: {
+      command: "claude",
+      // claude mcp add --scope: local (default, unshared), project (writes a
+      // committed .mcp.json), or user (global). "project" is the only shared
+      // option, so that's what a project-scoped registration means here.
+      buildArgs: (scope) => [
+        "mcp",
+        "add",
+        "-s",
+        scope === "project" ? "project" : "user",
+        "skillmux",
+        "--",
+        "skillmux",
+        "serve",
+      ],
+    },
+  },
+  codex: {
+    id: "codex",
+    surfaceId: "codex",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ codexHome }) => codexHome,
+    instructions: {
+      global: ({ codexHome }) => join(codexHome, "AGENTS.md"),
+    },
+    mcpRegistration: {
+      command: "codex",
+      // codex mcp add has no --scope flag at all — it always writes to the
+      // global ~/.codex/config.toml, so project scope is not representable.
+      buildArgs: (scope) =>
+        scope === "project"
+          ? undefined
+          : ["mcp", "add", "skillmux", "--", "skillmux", "serve"],
+    },
+  },
+  opencode: {
+    id: "opencode",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".config", "opencode"),
+    instructions: {
+      global: ({ home }) => join(home, ".config", "opencode", "AGENTS.md"),
+    },
+  },
+  "github-copilot": {
+    id: "github-copilot",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".config", "github-copilot"),
+  },
+  windsurf: {
+    id: "windsurf",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".codeium", "windsurf"),
+  },
+  antigravity: {
+    id: "antigravity",
+    surfaceId: "antigravity",
+    deliveryMode: "managed-pins",
+    instructions: {
+      global: ({ home }) => join(home, ".gemini", "GEMINI.md"),
+    },
+  },
+  goose: {
+    id: "goose",
+    deliveryMode: "full-vault",
+    detectionPath: ({ home }) => join(home, ".config", "goose"),
+    manualSkillSurfaceMessage: "configure the full vault in Goose",
+    instructions: {
+      global: ({ home }) => join(home, ".config", "goose", ".goosehints"),
+    },
+  },
+  hermes: {
+    id: "hermes",
+    deliveryMode: "full-vault",
+    detectionPath: ({ home }) => join(home, ".hermes"),
+    manualSkillSurfaceMessage: "configure the full vault in Hermes external_dirs",
+    instructions: {
+      global: ({ home }) => join(home, ".hermes.md"),
+    },
+  },
+};
+
+export function getAgentDefinition(agent: AgentId): AgentDefinition {
+  return AGENTS[agent];
+}
+
+/** Agents that can be attached to a project group (managed-pins delivery, not full-vault). */
+export const MANAGED_PINS_AGENT_IDS = SUPPORTED_AGENT_IDS.filter(
+  (id) => AGENTS[id].deliveryMode === "managed-pins",
+);
+
+export function detectInstalledAgents(
+  options: {
+    home?: string;
+    codexHome?: string;
+    exists?: (path: string) => boolean;
+  } = {},
+): DetectedAgent[] {
+  const home = options.home ?? homedir();
+  const codexHome = options.codexHome ?? join(home, ".codex");
+  const exists = options.exists ?? existsSync;
+  return SUPPORTED_AGENT_IDS.flatMap((agent) => {
+    const evidence = AGENTS[agent].detectionPath?.({ home, codexHome });
+    return evidence && exists(evidence) ? [{ agent, evidence }] : [];
+  });
+}
+
+function surfacePath(
+  surfaceId: NonNullable<AgentDefinition["surfaceId"]>,
+  options: { home: string; codexHome?: string },
+): string {
+  if (surfaceId === "agent-skills") return join(options.home, ".agents", "skills");
+  if (surfaceId === "claude-code") return join(options.home, ".claude", "skills");
+  if (surfaceId === "codex") return join(options.codexHome ?? join(options.home, ".codex"), "skills");
+  return join(options.home, ".gemini", "config", "skills");
+}
+
+export function resolveBuiltInTarget(
+  name: string,
+  options: { home?: string; codexHome?: string; customPath?: string } = {},
+): ResolvedBuiltInTarget {
+  const home = options.home ?? homedir();
+  if (name === "custom") {
+    if (!options.customPath) throw new Error("--target custom requires --path <dir>");
+    return { targetName: name, path: options.customPath };
+  }
+  if (name === "agent-skills") {
+    return { targetName: name, path: surfacePath("agent-skills", { home }) };
+  }
+  if (name === "claude-code") {
+    return { targetName: name, path: surfacePath("claude-code", { home }) };
+  }
+  if (name === "codex") {
+    return {
+      targetName: name,
+      path: surfacePath("codex", { home, codexHome: options.codexHome }),
+    };
+  }
+  throw new Error(
+    `unknown --target "${name}"; supported targets: agent-skills, claude-code, codex, custom`,
+  );
+}
+
+export function planAgentSurfaces(
+  requestedAgents: readonly string[],
+  options: { home?: string; codexHome?: string } = {},
+): AgentSurfacePlan {
+  const agents = [...new Set(requestedAgents)].map((id) => {
+    if (!SUPPORTED_AGENT_IDS.includes(id as AgentId)) {
+      throw new Error(
+        `unsupported agent "${id}"; supported agents: ${SUPPORTED_AGENT_IDS.join(", ")}`,
+      );
+    }
+    return AGENTS[id as AgentId];
+  });
+  const home = options.home ?? homedir();
+  const surfaces = new Map<string, PlannedAgentSurface>();
+
+  for (const agent of agents) {
+    if (!agent.surfaceId) continue;
+    const path = surfacePath(agent.surfaceId, { home, codexHome: options.codexHome });
+    const existing = surfaces.get(path);
+    if (existing) {
+      if (!existing.agents.includes(agent.id)) existing.agents.push(agent.id);
+      continue;
+    }
+    surfaces.set(path, {
+      id: agent.surfaceId,
+      targetName: agent.surfaceId,
+      path,
+      deliveryMode: "managed-pins",
+      agents: [agent.id],
+    });
+  }
+
+  return { agents, surfaces: [...surfaces.values()] };
+}
+
+export function assessAgentReadiness(
+  plan: AgentSurfacePlan,
+  instructionReadiness: Partial<Record<AgentId, ReadinessAxis>> = {},
+): AgentReadiness[] {
+  return plan.agents.map((agent) => {
+    const surface = plan.surfaces.find((candidate) => candidate.agents.includes(agent.id));
+    let skillSurface: ReadinessAxis;
+    if (surface) {
+      skillSurface = { status: "planned", detail: surface.path };
+    } else if (agent.manualSkillSurfaceMessage) {
+      skillSurface = { status: "manual", detail: agent.manualSkillSurfaceMessage };
+    } else {
+      skillSurface = {
+        status: "not-applicable",
+        detail: "skills resolve through Skillmux MCP",
+      };
+    }
+
+    const mcpRegistration: ReadinessAxis = {
+      status: "not-applicable",
+      detail: "native skill loading",
+    };
+
+    return {
+      agent: agent.id,
+      skillSurface,
+      mcpRegistration,
+      instructionSetup: instructionReadiness[agent.id] ?? {
+        status: "manual",
+        detail: "instruction adapter not applied",
+      },
+    };
+  });
+}

package/src/init-instructions.ts

@@ -9,7 +9,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { DISCOVERY_PARAGRAPH } from "./init";
-import type { ClientId } from "./init-clients";
+import { getAgentDefinition, type AgentId } from "./init-agents";
 
 export const INSTRUCTION_BLOCK_START = "<!-- skillmux:discovery:start -->";
 export const INSTRUCTION_BLOCK_END = "<!-- skillmux:discovery:end -->";
@@ -22,7 +22,7 @@ const MANAGED_BLOCK = [
 
 export interface InstructionChange {
   path: string;
-  clients: ClientId[];
+  agents: AgentId[];
   status: "create" | "update" | "unchanged";
   before: string | null;
   after: string;
@@ -30,7 +30,7 @@ export interface InstructionChange {
 
 export interface InstructionPlan {
   changes: InstructionChange[];
-  manual: Array<{ client: ClientId; reason: string }>;
+  manual: Array<{ agent: AgentId; reason: string }>;
 }
 
 interface InstructionPlanOptions {
@@ -41,18 +41,10 @@ interface InstructionPlanOptions {
 }
 
 function instructionPath(
-  client: ClientId,
+  agent: AgentId,
   options: Required<Pick<InstructionPlanOptions, "home" | "codexHome" | "claudeConfigDir">>,
 ): string | undefined {
-  if (client === "claude-code") return join(options.claudeConfigDir, "CLAUDE.md");
-  if (client === "codex") return join(options.codexHome, "AGENTS.md");
-  if (client === "gemini-cli" || client === "antigravity") {
-    return join(options.home, ".gemini", "GEMINI.md");
-  }
-  if (client === "opencode") return join(options.home, ".config", "opencode", "AGENTS.md");
-  if (client === "goose") return join(options.home, ".config", "goose", ".goosehints");
-  if (client === "hermes") return join(options.home, ".hermes.md");
-  return undefined;
+  return getAgentDefinition(agent).instructions?.global?.(options);
 }
 
 function readInstructionFile(path: string): string | null {
@@ -85,29 +77,23 @@ function withManagedBlock(existing: string | null, path: string): string {
   return `${existing.slice(0, start)}${MANAGED_BLOCK}${existing.slice(end + INSTRUCTION_BLOCK_END.length)}`;
 }
 
-export function planInstructionSetup(
-  requestedClients: readonly ClientId[],
-  options: InstructionPlanOptions = {},
+function planInstructionSetupWithResolver(
+  requestedAgents: readonly AgentId[],
+  resolvePath: (agent: AgentId) => string | undefined,
+  readFile: (path: string) => string | null,
 ): InstructionPlan {
-  const home = options.home ?? process.env.HOME ?? "";
-  const resolvedOptions = {
-    home,
-    codexHome: options.codexHome ?? process.env.CODEX_HOME ?? join(home, ".codex"),
-    claudeConfigDir: options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"),
-  };
-  const readFile = options.readFile ?? readInstructionFile;
   const changesByPath = new Map<string, InstructionChange>();
   const manual: InstructionPlan["manual"] = [];
 
-  for (const client of [...new Set(requestedClients)]) {
-    const path = instructionPath(client, resolvedOptions);
+  for (const agent of [...new Set(requestedAgents)]) {
+    const path = resolvePath(agent);
     if (!path) {
-      manual.push({ client, reason: "no safe durable user instruction file is known" });
+      manual.push({ agent, reason: "no safe durable user instruction file is known" });
       continue;
     }
     const existingChange = changesByPath.get(path);
     if (existingChange) {
-      existingChange.clients.push(client);
+      existingChange.agents.push(agent);
       continue;
     }
 
@@ -115,7 +101,7 @@ export function planInstructionSetup(
     const after = withManagedBlock(before, path);
     changesByPath.set(path, {
       path,
-      clients: [client],
+      agents: [agent],
       status: before === null ? "create" : before === after ? "unchanged" : "update",
       before,
       after,
@@ -125,6 +111,39 @@ export function planInstructionSetup(
   return { changes: [...changesByPath.values()], manual };
 }
 
+export function planInstructionSetup(
+  requestedAgents: readonly AgentId[],
+  options: InstructionPlanOptions = {},
+): InstructionPlan {
+  const home = options.home ?? process.env.HOME ?? "";
+  const resolvedOptions = {
+    home,
+    codexHome: options.codexHome ?? process.env.CODEX_HOME ?? join(home, ".codex"),
+    claudeConfigDir: options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"),
+  };
+  return planInstructionSetupWithResolver(
+    requestedAgents,
+    (agent) => instructionPath(agent, resolvedOptions),
+    options.readFile ?? readInstructionFile,
+  );
+}
+
+function projectInstructionPath(agent: AgentId, projectRoot: string): string | undefined {
+  return getAgentDefinition(agent).instructions?.project?.(projectRoot);
+}
+
+export function planProjectInstructionSetup(
+  requestedAgents: readonly AgentId[],
+  projectRoot: string,
+  options: Pick<InstructionPlanOptions, "readFile"> = {},
+): InstructionPlan {
+  return planInstructionSetupWithResolver(
+    requestedAgents,
+    (agent) => projectInstructionPath(agent, projectRoot),
+    options.readFile ?? readInstructionFile,
+  );
+}
+
 function atomicWrite(path: string, content: string, mode: number): void {
   mkdirSync(dirname(path), { recursive: true });
   const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;