agent-trellis 0.2.0 → 0.3.0

package/dist/commands/migrate.d.ts

@@ -4,26 +4,52 @@
  * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
  * plan-then-apply split every adapter already uses.
  */
-import type { AgentId } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "already-migrated" | "conflict";
+import type { AgentId, McpServerDef } from "../core/types.js";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "conflict";
+/** Internal kind naming, unchanged since before `--only` existed
+ * (trellis-migrate-category-selection design.md D2) — the CLI-facing
+ * flag value is the plural `"skills"`, mapped to this singular `"skill"`
+ * in `runMigrate`, not renamed here to avoid touching every existing
+ * `MigratePlanItem.kind` comparison for no functional reason. */
+export type MigrateKind = "skill" | "instructions" | "mcp";
 export interface MigratePlanItem {
-    kind: "skill" | "instructions";
+    kind: MigrateKind;
     name: string;
     action: MigrateAction;
     detail: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;
+    /** Only set when kind === "mcp" && action === "create". */
+    mcpDef?: McpServerDef;
 }
 export interface MigratePlan {
     agent: AgentId;
     present: boolean;
     items: MigratePlanItem[];
 }
-export declare function collectMigratePlan(agent: AgentId, homeDir?: string): Promise<MigratePlan>;
+/**
+ * `only` restricts which kind(s) are even considered — not a post-hoc
+ * filter on a fully-computed plan (trellis-migrate-category-selection
+ * design.md D3): the excluded kind's canonical path is never read for
+ * comparison and never appears in the plan, not even as a suppressed
+ * conflict. Omitting `only` (or passing both kinds) is exactly today's
+ * behavior.
+ */
+export declare function collectMigratePlan(agent: AgentId, homeDir?: string, only?: readonly MigrateKind[]): Promise<MigratePlan>;
 export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string): void;
+/** CLI-facing spelling: `"skills"` (plural — a run usually touches more
+ * than one), `"instructions"` (already singular-shaped), or `"mcp"`
+ * (already the CLI's own convention, matching `trellis mcp`'s own
+ * command name). Mapped to `MigrateKind` in `runMigrate`, the one place
+ * this translation lives. */
+export type MigrateOnlyValue = "skills" | "instructions" | "mcp";
 export interface RunMigrateOptions {
     from?: string;
+    /** Restricts the run to one category (`"skills"`, `"instructions"`, or
+     * `"mcp"`, raw and unvalidated same as `from` — `runMigrate` checks
+     * it). `undefined` means all three, exactly as before `"mcp"` existed. */
+    only?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */

package/dist/commands/migrate.js

@@ -12,7 +12,10 @@ import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import { AGENTS_MD_TEMPLATE } from "./init.js";
-import { dirContentsEqual } from "../lib/dirEquals.js";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { deepEqual } from "../lib/deepEqual.js";
+import { readClaudeCodeMcpDefs, readCodexMcpDefs, readKiroMcpDefs } from "../lib/mcpMigrateRead.js";
+import { loadCanonicalSource, upsertServerYaml } from "../core/canonical.js";
 import { ALL_AGENTS } from "../core/types.js";
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
@@ -20,6 +23,14 @@ const PROBES = {
     kiro: (homeDir) => kiroProbe.probe(homeDir),
     pi: (homeDir) => piProbe.probe(homeDir),
 };
+/** pi has no static MCP config to read at all (roadmap.md P14/
+ * trellis-migrate-mcp-servers) — deliberately absent, not an oversight;
+ * `collectMigratePlan` skips the `mcp` category entirely for pi. */
+const MCP_READERS = {
+    "claude-code": readClaudeCodeMcpDefs,
+    kiro: readKiroMcpDefs,
+    codex: readCodexMcpDefs,
+};
 function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (isSymlink) {
         return { kind: "skill", name, action: "skip-symlink", detail: "shared in from elsewhere, not this agent's own content" };
@@ -27,13 +38,14 @@ function planSkill(name, sourceDir, isSymlink, caseCorrect, canonicalDir) {
     if (!caseCorrect) {
         return { kind: "skill", name, action: "skip-case-broken", detail: "already undiscoverable on at least one other agent — fix on the source before migrating" };
     }
-    if (!existsSync(canonicalDir)) {
-        return { kind: "skill", name, action: "create", detail: `will copy from ${sourceDir}`, sourceDir };
-    }
-    if (dirContentsEqual(sourceDir, canonicalDir)) {
-        return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
+    switch (decideDirImport(sourceDir, canonicalDir)) {
+        case "create":
+            return { kind: "skill", name, action: "create", detail: `will copy from ${sourceDir}`, sourceDir };
+        case "already-present":
+            return { kind: "skill", name, action: "already-migrated", detail: "canonical content is byte-identical" };
+        case "conflict":
+            return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
     }
-    return { kind: "skill", name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
 }
 function planInstructions(snapshot, canonicalAgentsMd) {
     if (!snapshot.instructionsFile)
@@ -60,21 +72,56 @@ function planInstructions(snapshot, canonicalAgentsMd) {
     }
     return { kind: "instructions", name: "agents.md", action: "conflict", detail: "canonical agents.md already has different real content — resolve by hand" };
 }
-export async function collectMigratePlan(agent, homeDir = homedir()) {
+function planMcpServer(name, def, existing) {
+    if (existing === undefined) {
+        return { kind: "mcp", name, action: "create", detail: "will add to servers.yaml", mcpDef: def };
+    }
+    if (deepEqual(existing, def)) {
+        return { kind: "mcp", name, action: "already-migrated", detail: "canonical definition is already identical" };
+    }
+    return { kind: "mcp", name, action: "conflict", detail: `canonical mcp/servers.yaml already has a different definition for "${name}" — resolve by hand` };
+}
+/**
+ * `only` restricts which kind(s) are even considered — not a post-hoc
+ * filter on a fully-computed plan (trellis-migrate-category-selection
+ * design.md D3): the excluded kind's canonical path is never read for
+ * comparison and never appears in the plan, not even as a suppressed
+ * conflict. Omitting `only` (or passing both kinds) is exactly today's
+ * behavior.
+ */
+export async function collectMigratePlan(agent, homeDir = homedir(), only) {
     const snapshot = await PROBES[agent](homeDir);
     if (!snapshot.present) {
         return { agent, present: false, items: [] };
     }
     const canonicalRoot = join(homeDir, ".trellis");
     const items = [];
-    for (const root of snapshot.skillRoots) {
-        for (const skill of root.skills) {
-            items.push(planSkill(skill.name, skill.dir, skill.isSymlink, skill.caseCorrect, join(canonicalRoot, "skills", skill.name)));
+    const wants = (kind) => !only || only.includes(kind);
+    if (wants("skill")) {
+        for (const root of snapshot.skillRoots) {
+            for (const skill of root.skills) {
+                items.push(planSkill(skill.name, skill.dir, skill.isSymlink, skill.caseCorrect, join(canonicalRoot, "skills", skill.name)));
+            }
+        }
+    }
+    if (wants("instructions")) {
+        const instructionsItem = planInstructions(snapshot, join(canonicalRoot, "agents.md"));
+        if (instructionsItem)
+            items.push(instructionsItem);
+    }
+    if (wants("mcp")) {
+        const reader = MCP_READERS[agent];
+        if (reader) {
+            const canonicalServers = loadCanonicalSource(homeDir).mcp.servers;
+            const { entries, unsupported } = reader(homeDir);
+            for (const { name, def } of entries) {
+                items.push(planMcpServer(name, def, canonicalServers[name]));
+            }
+            for (const { name, reason } of unsupported) {
+                items.push({ kind: "mcp", name, action: "skip-unsupported", detail: reason });
+            }
         }
     }
-    const instructionsItem = planInstructions(snapshot, join(canonicalRoot, "agents.md"));
-    if (instructionsItem)
-        items.push(instructionsItem);
     return { agent, present: true, items };
 }
 export function applyMigratePlan(plan, homeDir = homedir()) {
@@ -91,8 +138,22 @@ export function applyMigratePlan(plan, homeDir = homedir()) {
             mkdirSync(canonicalRoot, { recursive: true });
             writeFileSync(join(canonicalRoot, "agents.md"), item.sourceContent);
         }
+        else if (item.kind === "mcp" && item.mcpDef) {
+            upsertServerYaml(join(canonicalRoot, "mcp", "servers.yaml"), item.name, item.mcpDef);
+        }
     }
 }
+const ONLY_VALUES = ["skills", "instructions", "mcp"];
+function isMigrateOnlyValue(value) {
+    return ONLY_VALUES.includes(value);
+}
+function toMigrateKinds(only) {
+    if (only === "skills")
+        return ["skill"];
+    if (only === "instructions")
+        return ["instructions"];
+    return ["mcp"];
+}
 export async function runMigrate(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     if (!opts.from || !ALL_AGENTS.includes(opts.from)) {
@@ -100,7 +161,12 @@ export async function runMigrate(opts = {}) {
         return { exitCode: 1 };
     }
     const agent = opts.from;
-    const plan = await collectMigratePlan(agent, homeDir);
+    if (opts.only !== undefined && !isMigrateOnlyValue(opts.only)) {
+        console.error(`--only must be one of: ${ONLY_VALUES.join(", ")} (got ${opts.only})`);
+        return { exitCode: 1 };
+    }
+    const only = opts.only && isMigrateOnlyValue(opts.only) ? toMigrateKinds(opts.only) : undefined;
+    const plan = await collectMigratePlan(agent, homeDir, only);
     if (!plan.present) {
         console.error(`${agent} is not present on this machine — nothing to migrate.`);
         return { exitCode: 1 };
@@ -127,6 +193,7 @@ export function printPlan(plan, dryRun) {
         return;
     }
     for (const item of plan.items) {
-        console.log(`  [${item.action}] ${item.kind === "skill" ? `skill "${item.name}"` : "instructions"} — ${item.detail}`);
+        const label = item.kind === "skill" ? `skill "${item.name}"` : item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions";
+        console.log(`  [${item.action}] ${label} — ${item.detail}`);
     }
 }

package/dist/commands/onboard.d.ts

@@ -1,18 +1,19 @@
 /**
  * `trellis onboard` — chains `init` → agent detection → migration-source
- * resolution → managed-agent-set selection (install-then-manage for a
+ * resolution → migrate-category selection (trellis-migrate-category-
+ * selection) → managed-agent-set selection (install-then-manage for a
  * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
  * `secrets audit` into one guided flow (trellis-cli-onboard,
  * trellis-managed-agents) — a user should never have to type a second
- * command by hand to finish onboarding. Source and managed set are
- * independent choices (design.md D2): importing from a source never
- * writes back to it, and it is not implicitly added to the managed set.
- * Orchestrates existing commands' own plan/apply logic; no new
- * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
- * is made here.
+ * command by hand to finish onboarding. Source, categories, and managed
+ * set are three independent choices (design.md D2): importing from a
+ * source never writes back to it, and it is not implicitly added to the
+ * managed set. Orchestrates existing commands' own plan/apply logic; no
+ * new skill-copy, symlink, conflict-detection, or secrets-scanning
+ * judgment is made here.
  */
 import type { AgentId } from "../core/types.js";
-import type { MigratePlan } from "./migrate.js";
+import type { MigrateKind, MigratePlan } from "./migrate.js";
 import type { SyncReport } from "./sync.js";
 import type { McpSyncReport } from "./mcp.js";
 import type { SecretsAuditReport } from "./secretsAudit.js";
@@ -50,6 +51,11 @@ export interface RunOnboardOptions {
      * pre-parsed list — so the same parsing/validation code path is
      * exercised whether the answer came from a flag or a prompt. */
     promptForManagedAgents?: (candidates: OnboardAgentSummary[], alreadyManaged: readonly AgentId[]) => Promise<string>;
+    /** Test-only: replaces the real migrate-category picker/default logic
+     * (trellis-migrate-category-selection). An empty array is a valid
+     * answer — "skip migrate for this run" (design.md D6) — distinct from
+     * `source` being unresolved at all. */
+    promptForMigrateCategories?: (source: OnboardAgentSummary) => Promise<MigrateKind[]>;
     /** Test-only: injected into every `confirmAndInstall` call for a
      * selected, not-yet-present agent. Never a real terminal prompt or a
      * real `npm install` in a unit test. */
@@ -70,6 +76,10 @@ export interface OnboardResult {
     managedAgents?: AgentId[];
     installResults?: OnboardInstallResult[];
     migratePlan?: MigratePlan;
+    /** Set when a source was resolved but zero migrate categories were
+     * selected (design.md D6) — distinct from `migratePlan` being absent
+     * because no source existed at all, which prints nothing here. */
+    migrateSkipped?: string;
     syncReport?: SyncReport;
     mcpSyncReport?: McpSyncReport;
     secretsAuditReport?: SecretsAuditReport;

package/dist/commands/onboard.js

@@ -1,20 +1,22 @@
 /**
  * `trellis onboard` — chains `init` → agent detection → migration-source
- * resolution → managed-agent-set selection (install-then-manage for a
+ * resolution → migrate-category selection (trellis-migrate-category-
+ * selection) → managed-agent-set selection (install-then-manage for a
  * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
  * `secrets audit` into one guided flow (trellis-cli-onboard,
  * trellis-managed-agents) — a user should never have to type a second
- * command by hand to finish onboarding. Source and managed set are
- * independent choices (design.md D2): importing from a source never
- * writes back to it, and it is not implicitly added to the managed set.
- * Orchestrates existing commands' own plan/apply logic; no new
- * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
- * is made here.
+ * command by hand to finish onboarding. Source, categories, and managed
+ * set are three independent choices (design.md D2): importing from a
+ * source never writes back to it, and it is not implicitly added to the
+ * managed set. Orchestrates existing commands' own plan/apply logic; no
+ * new skill-copy, symlink, conflict-detection, or secrets-scanning
+ * judgment is made here.
  */
 import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { canUseInteractivePicker, runMultiSelectPicker, runSingleSelectPicker } from "../lib/terminalPicker.js";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
@@ -48,13 +50,19 @@ export async function collectOnboardSummary(homeDir = homedir()) {
 function hasContent(s) {
     return s.skillCount > 0 || s.hasRealInstructions;
 }
-async function promptForAgentReal(present) {
+function agentSummaryLabel(s) {
+    const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
+    return `${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`;
+}
+/** Numbered-typing fallback (trellis-onboard-interactive-picker design.md
+ * D2) — used only when the terminal can't support the raw-mode picker
+ * (`canUseInteractivePicker()` false). Unchanged from before that change. */
+async function promptForAgentNumbered(present) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         console.log("Multiple agents detected:");
         present.forEach((s, i) => {
-            const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
-            console.log(`  ${i + 1}) ${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`);
+            console.log(`  ${i + 1}) ${agentSummaryLabel(s)}`);
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const answer = (await rl.question(`Choose a migration source [1-${present.length}]: `)).trim();
@@ -74,7 +82,28 @@ async function promptForAgentReal(present) {
         rl.close();
     }
 }
-async function promptForManagedAgentsReal(candidates, alreadyManaged) {
+/** Arrow-key single-select on a real, raw-mode-capable terminal; falls
+ * back to `promptForAgentNumbered` otherwise. Resolves to the exact same
+ * string contract either way — a real agent id — so `resolveMigrationSource`
+ * and every test injecting `RunOnboardOptions.promptForAgent` need no
+ * changes (design.md D5). Cancel (Ctrl+C) prints a message and exits
+ * directly, rather than threading a new "cancelled" state through the
+ * rest of onboard's return-based refusal plumbing. */
+async function promptForAgentReal(present) {
+    if (!canUseInteractivePicker()) {
+        return promptForAgentNumbered(present);
+    }
+    console.log("Multiple agents detected — use Up/Down (or j/k) and Enter to choose a migration source:");
+    const index = await runSingleSelectPicker(present.map(agentSummaryLabel));
+    if (index === null) {
+        console.log("cancelled, no changes made");
+        process.exit(1);
+    }
+    return present[index].agent;
+}
+/** Numbered-typing fallback — unchanged from before this change (see
+ * `promptForAgentNumbered`'s doc comment). */
+async function promptForManagedAgentsNumbered(candidates, alreadyManaged) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         console.log("Which agents should Trellis manage? (comma-separated numbers; enter for none new)");
@@ -90,6 +119,74 @@ async function promptForManagedAgentsReal(candidates, alreadyManaged) {
         rl.close();
     }
 }
+/** Checkbox multi-select on a real, raw-mode-capable terminal; falls
+ * back to `promptForManagedAgentsNumbered` otherwise. Resolves to the
+ * same comma-separated-agent-id string contract `parseManagedSelection`
+ * already parses — an empty selection resolves to `""` (comma-separated
+ * join of zero items), which `parseManagedSelection` already treats as
+ * "none" (design.md D5). Cancel behaves like `promptForAgentReal`'s. */
+async function promptForManagedAgentsReal(candidates, alreadyManaged) {
+    if (!canUseInteractivePicker()) {
+        return promptForManagedAgentsNumbered(candidates, alreadyManaged);
+    }
+    console.log("Which agents should Trellis manage? Up/Down (or j/k) to move, Space to toggle, Enter to confirm:");
+    const labels = candidates.map((s) => {
+        const status = s.present ? `present, ${s.skillCount} skill(s)` : "not installed";
+        return `${s.agent} — ${status}`;
+    });
+    const initiallyChecked = candidates.map((s) => alreadyManaged.includes(s.agent));
+    const indices = await runMultiSelectPicker(labels, initiallyChecked);
+    if (indices === null) {
+        console.log("cancelled, no changes made");
+        process.exit(1);
+    }
+    return indices.map((i) => candidates[i].agent).join(",");
+}
+/**
+ * Resolves which categories (skills, instructions) to migrate from a
+ * resolved source (trellis-migrate-category-selection). Unlike the two
+ * pickers above, there is no numbered-text fallback to preserve parity
+ * with — this concept never existed before this change, so "can't
+ * prompt" simply means "default to whichever kind(s) actually have real
+ * content, silently" (design.md D4). The picker itself is only offered
+ * when the choice is meaningful — both kinds present, a capable
+ * terminal, and not a `--json` run (design.md D5). An empty result is a
+ * valid answer: "skip migrate for this run" (design.md D6), left for
+ * the caller to act on.
+ */
+async function resolveMigrateCategories(source, opts) {
+    const wantsSkills = source.skillCount > 0;
+    const wantsInstructions = source.hasRealInstructions;
+    // The choice is only meaningful when both kinds are real — same gate
+    // for the injected test seam as for the real picker, mirroring how
+    // `promptForAgent`/`promptForManagedAgents` are only ever consulted
+    // when their own real prompt would actually apply.
+    if (wantsSkills && wantsInstructions && !opts.json) {
+        if (opts.promptForMigrateCategories) {
+            return opts.promptForMigrateCategories(source);
+        }
+        if (canUseInteractivePicker()) {
+            console.log(`Which categories should be migrated from ${source.agent}? Space to toggle, Enter to confirm:`);
+            const indices = await runMultiSelectPicker(["skills", "instructions"], [true, true]);
+            if (indices === null) {
+                console.log("cancelled, no changes made");
+                process.exit(1);
+            }
+            const kinds = [];
+            if (indices.includes(0))
+                kinds.push("skill");
+            if (indices.includes(1))
+                kinds.push("instructions");
+            return kinds;
+        }
+    }
+    const kinds = [];
+    if (wantsSkills)
+        kinds.push("skill");
+    if (wantsInstructions)
+        kinds.push("instructions");
+    return kinds;
+}
 /** Shared by `--manage` and the interactive prompt's answer — same
  * grammar either way (design.md D4): a real agent id list, comma- or
  * whitespace-separated numbers referring to `candidates`' own order, or
@@ -224,10 +321,18 @@ export async function collectOnboardPlan(opts = {}) {
         writeManagedYaml(homeDir, managedAgents);
     }
     let migratePlan;
+    let migrateSkipped;
     if (source) {
-        migratePlan = await collectMigratePlan(source, homeDir);
-        if (!opts.dryRun) {
-            applyMigratePlan(migratePlan, homeDir);
+        const sourceSummary = summary.find((s) => s.agent === source);
+        const categories = await resolveMigrateCategories(sourceSummary, opts);
+        if (categories.length > 0) {
+            migratePlan = await collectMigratePlan(source, homeDir, categories);
+            if (!opts.dryRun) {
+                applyMigratePlan(migratePlan, homeDir);
+            }
+        }
+        else {
+            migrateSkipped = "migrate skipped — no categories selected";
         }
     }
     // One session for the whole chained run (trellis-backup-rollback) —
@@ -249,6 +354,7 @@ export async function collectOnboardPlan(opts = {}) {
         managedAgents,
         installResults: installResults.length > 0 ? installResults : undefined,
         migratePlan,
+        migrateSkipped,
         syncReport,
         mcpSyncReport,
         secretsAuditReport,
@@ -313,6 +419,10 @@ function printResult(result, dryRun) {
         console.log("");
         printMigratePlan(result.migratePlan, false);
     }
+    else if (result.migrateSkipped) {
+        console.log("");
+        console.log(result.migrateSkipped);
+    }
     if (result.syncReport) {
         console.log("\nsync");
         printSyncReport(result.syncReport, false);

package/dist/commands/skill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import type { AgentId } from "../core/types.js";
+export interface SkillListEntry {
+    name: string;
+    scope: readonly AgentId[];
+}
+export declare function collectSkillList(homeDir?: string): SkillListEntry[];
+export declare function runSkillList(opts?: {
+    homeDir?: string;
+    json?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillAddAction = "create" | "already-present" | "conflict" | "invalid-source";
+export interface SkillAddPlan {
+    name: string;
+    action: SkillAddAction;
+    detail: string;
+    sourceDir?: string;
+}
+export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
+export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string): void;
+export declare function runSkillAdd(name: string, fromPath: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
+export type SkillRemoveAction = "removed" | "not-found";
+export interface SkillRemovePlan {
+    name: string;
+    action: SkillRemoveAction;
+}
+export declare function collectSkillRemovePlan(name: string, homeDir?: string): SkillRemovePlan;
+export declare function applySkillRemovePlan(plan: SkillRemovePlan, homeDir?: string): void;
+export declare function runSkillRemove(name: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};

package/dist/commands/skill.js

@@ -0,0 +1,104 @@
+/**
+ * `trellis skill list|add|remove` — command-line CRUD for canonical
+ * skills (trellis-canonical-cli-crud), an alternative to hand-editing
+ * `~/.trellis/skills/<name>/SKILL.md` directly. `add`'s conflict
+ * decision and `remove`'s "sync will un-sync it" behavior both reuse
+ * existing, already-shipped logic rather than reimplementing it — see
+ * `decideDirImport` (src/lib/dirEquals.ts) and `src/adapters/
+ * symlinkPlan.ts`'s pre-existing stale-symlink removal.
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { decideDirImport } from "../lib/dirEquals.js";
+import { findSkillFile } from "../lib/skillFile.js";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { resolveScope } from "../core/types.js";
+export function collectSkillList(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return canonical.skills.map((skill) => ({
+        name: skill.name,
+        scope: resolveScope(skill.scope, canonical.managedAgents),
+    }));
+}
+export function runSkillList(opts = {}) {
+    const entries = collectSkillList(opts.homeDir ?? homedir());
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    else if (entries.length === 0) {
+        console.log("No skills in canonical source yet.");
+    }
+    else {
+        for (const { name, scope } of entries) {
+            console.log(`${name} — ${scope.length > 0 ? scope.join(", ") : "(no managed agent reaches it)"}`);
+        }
+    }
+    return { exitCode: 0 };
+}
+export function collectSkillAddPlan(name, fromPath, homeDir = homedir()) {
+    const skillFile = findSkillFile(fromPath);
+    if (!skillFile) {
+        return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
+    }
+    if (!skillFile.caseCorrect) {
+        return { name, action: "invalid-source", detail: `${fromPath} has skill.md, not case-correct SKILL.md — fix the case first` };
+    }
+    const canonicalDir = join(homeDir, ".trellis", "skills", name);
+    switch (decideDirImport(fromPath, canonicalDir)) {
+        case "create":
+            return { name, action: "create", detail: `will copy from ${fromPath}`, sourceDir: fromPath };
+        case "already-present":
+            return { name, action: "already-present", detail: "canonical content is already byte-identical" };
+        case "conflict":
+            return { name, action: "conflict", detail: `canonical skills/${name}/ already exists with different content — resolve by hand` };
+    }
+}
+export function applySkillAddPlan(plan, homeDir = homedir()) {
+    if (plan.action !== "create" || !plan.sourceDir)
+        return;
+    const dest = join(homeDir, ".trellis", "skills", plan.name);
+    mkdirSync(dest, { recursive: true });
+    cpSync(plan.sourceDir, dest, { recursive: true });
+}
+export function runSkillAdd(name, fromPath, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillAddPlan(name, fromPath, homeDir);
+    if (!opts.dryRun && plan.action === "create") {
+        applySkillAddPlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+    }
+    return { exitCode: plan.action === "conflict" || plan.action === "invalid-source" ? 1 : 0 };
+}
+export function collectSkillRemovePlan(name, homeDir = homedir()) {
+    const dir = join(homeDir, ".trellis", "skills", name);
+    return { name, action: existsSync(dir) ? "removed" : "not-found" };
+}
+export function applySkillRemovePlan(plan, homeDir = homedir()) {
+    if (plan.action !== "removed")
+        return;
+    rmSync(join(homeDir, ".trellis", "skills", plan.name), { recursive: true, force: true });
+}
+export function runSkillRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const plan = collectSkillRemovePlan(name, homeDir);
+    if (!opts.dryRun) {
+        applySkillRemovePlan(plan, homeDir);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else if (plan.action === "not-found") {
+        console.error(`"${name}" is not a canonical skill — nothing to remove.`);
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}removed skill "${name}" from canonical source.`);
+    }
+    return { exitCode: plan.action === "not-found" ? 1 : 0 };
+}

package/dist/core/adapter.d.ts

@@ -20,14 +20,18 @@ export interface AdapterPlanItem {
     /**
      * "create" also covers repair (wrong symlink target, or an MCP server
      * definition that differs from canonical); "remove" is the delete half
-     * for skills/instructions — a Trellis-managed symlink whose canonical
-     * entry is gone or was just scoped away from this agent. MCP server
-     * items never use "remove" (see `kind: "mcp"` below — no ownership
-     * marker exists yet to make that provably safe, trellis-mcp-sync-p2
-     * design.md D7). "conflict" is either a real, non-symlink path
-     * occupying a spot Trellis would otherwise touch, or an MCP server
-     * refused for a collision/secrets-guard reason — reported, never acted
-     * on. See `plan()`'s doc below.
+     * for skills/instructions (a Trellis-managed symlink whose canonical
+     * entry is gone or was just scoped away from this agent) and, since
+     * trellis-mcp-lifecycle-parity, for MCP servers too — but only when
+     * `src/lib/mcpOwnership.ts`'s ledger proves the agent's current native
+     * entry is still exactly what Trellis itself last wrote there
+     * (mcpPlan.ts's own D7 reasoning: a bare TOML/JSON key has no ownership
+     * marker on its own, so this ledger is what makes removal provably
+     * safe instead of guessing). A name whose native content has since
+     * been hand-edited is left alone, never removed. "conflict" is either
+     * a real, non-symlink path occupying a spot Trellis would otherwise
+     * touch, or an MCP server refused for a collision/secrets-guard
+     * reason — reported, never acted on. See `plan()`'s doc below.
      */
     action: "create" | "remove" | "conflict";
     /** Lets `trellis sync skills` / `trellis sync instructions` /
@@ -64,6 +68,12 @@ export interface AdapterPlanItem {
         name: string;
         def: McpServerDef;
     };
+    /** Only set (and only meaningful) when `kind === "mcp"` and
+     * `action === "remove"`: the server name to delete from `target` via
+     * that agent's own mechanism. */
+    mcpRemove?: {
+        name: string;
+    };
     /** Only set (and only meaningful) when `kind === "kiro-approved-env-vars"`
      * and `action === "create"`: the full, already-deduplicated array to
      * write as `kiroAgent.mcpApprovedEnvVars` — a union of whatever was