agent-trellis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Leo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# Trellis
+
+**A single source of capability for every coding agent you run.**
+
+Skills, MCP servers, subagent definitions, shared memory, and secret policy —
+defined once, adapted natively into Claude Code, Codex, Kiro, and the [pi coding
+agent](https://github.com/earendil-works/pi), without drift and without a second
+copy of anything.
+
+Trellis does not replace any of these agents' native config. It generates and
+verifies each one's native adapter from one canonical source, and refuses to let
+a plaintext secret or a duplicated skill file slip through.
+
+## Why
+
+By late 2026 the "sync my AI agent rules across tools" space is crowded — at
+least seven open source projects do it (`block/ai-rules`, `ai-rules-sync`,
+`skillshare`, `skills-hub`, `skills-link`, `agent_sync`, and others). None of
+them cover **Kiro** or **pi**, and none of them go past rules/skills into MCP
+servers, shared memory, and secret hygiene as one coherent system. That's the
+gap Trellis fills — see [`docs/research.md`](docs/research.md) for the full
+landscape survey and [`docs/architecture.md`](docs/architecture.md) for what we
+build versus what we deliberately reuse.
+
+Trellis aligns with the emerging [`.agents Protocol`](https://dotagentsprotocol.com)
+draft rather than inventing a sixth competing standard, and is likely its first
+working implementation.
+
+## Install
+
+```
+npm install -g agent-trellis
+```
+
+## Quick start
+
+See [`docs/getting-started.md`](docs/getting-started.md) for the detailed
+walkthrough — example output for each command, what each `migrate`/`sync`
+conflict action means, and troubleshooting.
+
+**One command:**
+
+```
+trellis onboard
+```
+
+Creates canonical source, detects which of Claude Code/Codex/Kiro/pi are on
+this machine, picks a base agent to migrate from (auto-selected if only one
+is present; prompts if more than one — pass `--agent <id>` to skip the
+prompt), then runs `migrate` and `sync`. If no agent is detected, it prints
+each supported agent's real install command/URL and stops — it never
+installs anything itself. Add `--dry-run` to preview the whole thing with
+zero writes.
+
+**Or step by step** (what `onboard` is actually doing under the hood):
+
+**Already using Claude Code, Codex, Kiro, or pi and want to migrate what you
+already have?**
+
+1. `trellis init` — creates `~/.trellis/` with a minimal skeleton (only what's
+   missing; never overwrites a file you already have) and tells you which of
+   the four agents it found on this machine.
+2. `trellis migrate --from <agent>` — once per agent you already use. Copies
+   that agent's real skills and instructions into canonical source. Never
+   overwrites: an already-identical skill is reported and skipped, a genuine
+   conflict is reported and left for you to resolve by hand. Add `--dry-run`
+   to preview first.
+3. `trellis sync` — distributes canonical skills/instructions to every agent
+   present on this machine (including the ones you didn't migrate from).
+   Add `--dry-run` to preview first.
+4. `trellis mcp sync` — distributes `~/.trellis/mcp/servers.yaml` (see
+   [`schema/servers.example.yaml`](schema/servers.example.yaml)) to every
+   agent's native MCP config (create/repair only — see Known limitations).
+5. `trellis secrets audit` — fails non-zero if any agent's real config holds
+   a literal credential or an unexpected env var name.
+6. `trellis doctor` — read-only scan of every present agent's current state;
+   run any time to check for drift.
+
+**Starting from nothing?** Skip step 2 — `trellis init`'s placeholder
+`agents.md` and empty `skills/` are a fine starting point; edit them by hand.
+
+## Status
+
+**Early, pre-1.0.** All seven CLI commands above (`onboard`, `init`,
+`migrate`, `doctor`, `sync`, `mcp sync`, `secrets audit`) are implemented,
+unit-tested, and verified end-to-end against real Docker containers (never a
+developer's own dotfiles during development — see
+[`docs/architecture.md`](docs/architecture.md)'s testing philosophy). See
+[`docs/roadmap.md`](docs/roadmap.md) for what's shipped (P0–P6) vs. planned
+(P7, a GUI). `onboard` picks one agent as the migration base when more than
+one is present — merging differing content across multiple agents into one
+result is named future work, not built yet.
+
+**Known limitations, honestly stated rather than discovered the hard way:**
+- MCP servers are never spawned/handshake-tested by `trellis mcp sync` or
+  `trellis sync` — only that the *config* is written correctly.
+  `trellis doctor --probe-mcp` is the one command that actually connects,
+  and it's opt-in.
+- The pi bridge extension (`trellis-pi-mcp-bridge`) has been verified to
+  load and register tools without erroring, never against a real LLM tool
+  call in production.
+- Verification has run against real Docker containers and a real,
+  isolated pi CLI install — not yet against a developer's actual, existing
+  `~/.claude`/`~/.codex`/`~/.kiro`/`~/.pi` in daily use. If you hit
+  something a clean-room sandbox wouldn't have caught, please open an
+  issue.
+- Automatic removal of an MCP server is deliberately unsupported (create/
+  repair only) until an ownership-tracking mechanism exists — see
+  `docs/roadmap.md`'s P2 note.
+
+## Design principles
+
+1. **One canonical source, many adapters.** Each agent's native config file is
+   a generated or symlinked artifact, never hand-edited.
+2. **Reuse before building.** MCP aggregation, memory, and secret-reference
+   patterns already have mature open source answers — Trellis wires to them
+   instead of reimplementing them. See [`docs/architecture.md`](docs/architecture.md).
+3. **No plaintext secrets, ever.** Every adapter output holds variable
+   references only; `trellis secrets audit` scans for and rejects raw values.
+4. **Verify, don't assume.** Every claim this project makes about an agent's
+   behavior (file format, discovery path, MCP support) is backed by an
+   executed probe, not documentation-reading. Adapters that can't be verified
+   this way don't ship.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

package/dist/adapters/claude-code.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude Code adapter: `~/.claude/skills/<name>` symlinks per in-scope
+ * skill, `~/.claude/CLAUDE.md` symlinked to canonical `agents.md`. Builds
+ * out the create/repair/remove/refuse shape end-to-end (tasks.md 3.1)
+ * before the other three adapters commit to reusing `symlinkPlan.ts`.
+ *
+ * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
+ * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
+ * removal (D7).
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+export declare class ClaudeCodeAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    readonly name = "Claude Code";
+    readonly id: "claude-code";
+    constructor(homeDir?: string);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    private planMcp;
+    apply(plan: AdapterPlanItem[]): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}

package/dist/adapters/claude-code.js

@@ -0,0 +1,86 @@
+/**
+ * Claude Code adapter: `~/.claude/skills/<name>` symlinks per in-scope
+ * skill, `~/.claude/CLAUDE.md` symlinked to canonical `agents.md`. Builds
+ * out the create/repair/remove/refuse shape end-to-end (tasks.md 3.1)
+ * before the other three adapters commit to reusing `symlinkPlan.ts`.
+ *
+ * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
+ * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
+ * removal (D7).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { isInScope } from "../core/adapter.js";
+import * as claudeCodeProbe from "../probes/claude-code.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { applyJsonMcp, planJsonMcp } from "./jsonMcp.js";
+export class ClaudeCodeAdapter {
+    homeDir;
+    name = "Claude Code";
+    id = "claude-code";
+    constructor(homeDir = homedir()) {
+        this.homeDir = homeDir;
+    }
+    async probe() {
+        const snapshot = await claudeCodeProbe.probe(this.homeDir);
+        return { present: snapshot.present, version: snapshot.version };
+    }
+    async plan(canonical) {
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const skillsRoot = join(this.homeDir, ".claude", "skills");
+        const desiredSkills = canonical.skills
+            .filter((skill) => isInScope(this.id, skill.scope))
+            .map((skill) => ({ name: skill.name, target: skill.dir }));
+        const skillItems = planSymlinks({
+            rootDir: skillsRoot,
+            desired: desiredSkills,
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        });
+        const instructionsItems = planSymlinks({
+            rootDir: join(this.homeDir, ".claude"),
+            desired: [{ name: "CLAUDE.md", target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        });
+        const mcpItems = this.planMcp(canonical);
+        return [...skillItems, ...instructionsItems, ...mcpItems];
+    }
+    planMcp(canonical) {
+        const configPath = join(this.homeDir, ".claude.json");
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        return planJsonMcp({ configPath, parsed, mcp: canonical.mcp, agentId: this.id });
+    }
+    async apply(plan) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
+        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
+        if (mcpCreates.length === 0) {
+            return;
+        }
+        const configPath = mcpCreates[0].target;
+        const parsed = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf-8")) : undefined;
+        const merged = applyJsonMcp(parsed, mcpCreates);
+        writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+    async verify(canonical) {
+        const snapshot = await claudeCodeProbe.probe(this.homeDir);
+        if (!snapshot.present) {
+            return { ok: false, mismatches: ["claude-code is not present on this machine"] };
+        }
+        const mismatches = [];
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
+        for (const name of desiredNames) {
+            if (!actualSkills.has(name)) {
+                mismatches.push(`skill "${name}" is in canonical scope for claude-code but missing on disk`);
+            }
+        }
+        for (const name of actualSkills) {
+            if (!desiredNames.has(name)) {
+                mismatches.push(`skill "${name}" is present on disk but not in canonical scope for claude-code`);
+            }
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}

package/dist/adapters/codex.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Codex adapter: `~/.agents/skills/<name>` symlinks (Codex's own built-in
+ * convention, per docs/research.md — never `~/.codex/skills`, that's the
+ * duplication bug this project already found and fixed once). Instructions
+ * sync targets whatever `config.toml`'s `instructions` key names; if unset,
+ * this is a no-op with a diagnostic — Trellis never guesses or writes a
+ * path Codex itself didn't declare (design.md Risks, trellis-sync-p1).
+ *
+ * MCP servers are written via `src/lib/tomlSection.ts`'s line-based
+ * section splicer, never a TOML library (trellis-mcp-sync-p2 design.md
+ * D1/D2 — both rejected with evidence) — create/repair only, no
+ * automatic removal (D7: no ownership marker exists for a bare TOML key
+ * the way a symlink's realpath provides for skills).
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+export declare class CodexAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    readonly name = "Codex";
+    readonly id: "codex";
+    constructor(homeDir?: string);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    private planMcp;
+    apply(plan: AdapterPlanItem[]): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}

package/dist/adapters/codex.js

@@ -0,0 +1,119 @@
+/**
+ * Codex adapter: `~/.agents/skills/<name>` symlinks (Codex's own built-in
+ * convention, per docs/research.md — never `~/.codex/skills`, that's the
+ * duplication bug this project already found and fixed once). Instructions
+ * sync targets whatever `config.toml`'s `instructions` key names; if unset,
+ * this is a no-op with a diagnostic — Trellis never guesses or writes a
+ * path Codex itself didn't declare (design.md Risks, trellis-sync-p1).
+ *
+ * MCP servers are written via `src/lib/tomlSection.ts`'s line-based
+ * section splicer, never a TOML library (trellis-mcp-sync-p2 design.md
+ * D1/D2 — both rejected with evidence) — create/repair only, no
+ * automatic removal (D7: no ownership marker exists for a bare TOML key
+ * the way a symlink's realpath provides for skills).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { isInScope } from "../core/adapter.js";
+import * as codexProbe from "../probes/codex.js";
+import { readInstructionsPath } from "../probes/codex.js";
+import { applySymlinkPlan, planSymlinks } from "./symlinkPlan.js";
+import { resolveMcpPlan } from "./mcpPlan.js";
+import { currentServerSectionText, renderServerSection, upsertSection } from "../lib/tomlSection.js";
+export class CodexAdapter {
+    homeDir;
+    name = "Codex";
+    id = "codex";
+    constructor(homeDir = homedir()) {
+        this.homeDir = homeDir;
+    }
+    async probe() {
+        const snapshot = await codexProbe.probe(this.homeDir);
+        return { present: snapshot.present, version: snapshot.version };
+    }
+    async plan(canonical) {
+        const canonicalRoot = dirname(canonical.instructionsFile);
+        const skillsRoot = join(this.homeDir, ".agents", "skills");
+        const desiredSkills = canonical.skills
+            .filter((skill) => isInScope(this.id, skill.scope))
+            .map((skill) => ({ name: skill.name, target: skill.dir }));
+        const skillItems = planSymlinks({
+            rootDir: skillsRoot,
+            desired: desiredSkills,
+            canonicalRoot: join(canonicalRoot, "skills"),
+            kind: "skill",
+        });
+        const mcpItems = this.planMcp(canonical);
+        const configuredInstructionsPath = readInstructionsPath(join(this.homeDir, ".codex", "config.toml"));
+        if (!configuredInstructionsPath) {
+            // Codex has no `instructions` key set — not Trellis's to decide.
+            // MCP planning is independent of this and must still run.
+            return [...skillItems, ...mcpItems];
+        }
+        const instructionsItems = planSymlinks({
+            rootDir: dirname(configuredInstructionsPath),
+            desired: [{ name: basename(configuredInstructionsPath), target: canonical.instructionsFile }],
+            canonicalRoot,
+            kind: "instructions",
+        });
+        return [...skillItems, ...instructionsItems, ...mcpItems];
+    }
+    planMcp(canonical) {
+        const configTomlPath = join(this.homeDir, ".codex", "config.toml");
+        const content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
+        const { desired, conflicts } = resolveMcpPlan(this.id, canonical.mcp);
+        const items = [];
+        for (const { name, def } of desired) {
+            const current = currentServerSectionText(content, name);
+            const rendered = renderServerSection(name, def);
+            if (current === rendered) {
+                continue; // already correct — no-op
+            }
+            items.push({
+                action: "create",
+                kind: "mcp",
+                target: configTomlPath,
+                mcpWrite: { name, def },
+                description: `MCP server "${name}" ${current === null ? "created" : "updated"} in ${configTomlPath}`,
+            });
+        }
+        for (const conflict of conflicts) {
+            items.push({ action: "conflict", kind: "mcp", target: configTomlPath, description: conflict.message });
+        }
+        return items;
+    }
+    async apply(plan) {
+        await applySymlinkPlan(plan.filter((item) => item.kind !== "mcp"));
+        const mcpCreates = plan.filter((item) => item.kind === "mcp" && item.action === "create" && item.mcpWrite);
+        if (mcpCreates.length === 0) {
+            return;
+        }
+        const configTomlPath = mcpCreates[0].target;
+        let content = existsSync(configTomlPath) ? readFileSync(configTomlPath, "utf-8") : "";
+        for (const item of mcpCreates) {
+            content = upsertSection(content, item.mcpWrite.name, item.mcpWrite.def);
+        }
+        writeFileSync(configTomlPath, content);
+    }
+    async verify(canonical) {
+        const snapshot = await codexProbe.probe(this.homeDir);
+        if (!snapshot.present) {
+            return { ok: false, mismatches: ["codex is not present on this machine"] };
+        }
+        const mismatches = [];
+        const desiredNames = new Set(canonical.skills.filter((s) => isInScope(this.id, s.scope)).map((s) => s.name));
+        const actualSkills = new Set(snapshot.skillRoots.flatMap((root) => root.skills).map((s) => s.name));
+        for (const name of desiredNames) {
+            if (!actualSkills.has(name)) {
+                mismatches.push(`skill "${name}" is in canonical scope for codex but missing on disk`);
+            }
+        }
+        for (const name of actualSkills) {
+            if (!desiredNames.has(name)) {
+                mismatches.push(`skill "${name}" is present on disk but not in canonical scope for codex`);
+            }
+        }
+        return mismatches.length === 0 ? { ok: true } : { ok: false, mismatches };
+    }
+}

package/dist/adapters/jsonMcp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared JSON MCP config handling for Claude Code (`~/.claude.json`) and
+ * Kiro (`~/.kiro/settings/mcp.json`) — plain parse → merge under
+ * `mcpServers` → stringify (trellis-mcp-sync-p2 design.md D4). Unlike
+ * Codex's TOML, JSON has no comments to lose, so a full parse/stringify
+ * round-trip is safe as long as every sibling top-level key is carried
+ * through untouched.
+ */
+import type { AgentId, McpConfig, McpServerDef } from "../core/types.js";
+import type { AdapterPlanItem } from "../core/adapter.js";
+/** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
+ * expects — `env` values are always `${VAR}` references, never literals
+ * (docs/research.md "Secrets"). */
+export declare function renderJsonServerEntry(def: McpServerDef): Record<string, unknown>;
+export declare function planJsonMcp(opts: {
+    configPath: string;
+    parsed: Record<string, unknown> | undefined;
+    mcp: McpConfig;
+    agentId: AgentId;
+}): AdapterPlanItem[];
+/** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
+ * file didn't exist), returning the object to stringify — every sibling
+ * top-level key on `parsed` is spread through untouched. */
+export declare function applyJsonMcp(parsed: Record<string, unknown> | undefined, items: AdapterPlanItem[]): Record<string, unknown>;

package/dist/adapters/jsonMcp.js

@@ -0,0 +1,84 @@
+/**
+ * Shared JSON MCP config handling for Claude Code (`~/.claude.json`) and
+ * Kiro (`~/.kiro/settings/mcp.json`) — plain parse → merge under
+ * `mcpServers` → stringify (trellis-mcp-sync-p2 design.md D4). Unlike
+ * Codex's TOML, JSON has no comments to lose, so a full parse/stringify
+ * round-trip is safe as long as every sibling top-level key is carried
+ * through untouched.
+ */
+import { resolveMcpPlan } from "./mcpPlan.js";
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+/** Renders the native JSON shape Claude Code/Kiro's `mcpServers` map
+ * expects — `env` values are always `${VAR}` references, never literals
+ * (docs/research.md "Secrets"). */
+export function renderJsonServerEntry(def) {
+    if (def.transport === "http" || def.transport === "sse") {
+        const entry = { type: def.transport, url: def.url };
+        if (def.headers && Object.keys(def.headers).length > 0) {
+            entry.headers = def.headers;
+        }
+        return entry;
+    }
+    const entry = { type: "stdio", command: def.command, args: def.args ?? [] };
+    if (def.env && def.env.length > 0) {
+        entry.env = Object.fromEntries(def.env.map((name) => [name, `\${${name}}`]));
+    }
+    return entry;
+}
+export function planJsonMcp(opts) {
+    const { configPath, parsed, mcp, agentId } = opts;
+    const { desired, conflicts } = resolveMcpPlan(agentId, mcp);
+    const existingServers = parsed?.mcpServers ?? {};
+    const items = [];
+    for (const { name, def } of desired) {
+        const rendered = renderJsonServerEntry(def);
+        const current = existingServers[name];
+        if (deepEqual(current, rendered)) {
+            continue; // already correct — no-op
+        }
+        items.push({
+            action: "create",
+            kind: "mcp",
+            target: configPath,
+            mcpWrite: { name, def },
+            description: `MCP server "${name}" ${current === undefined ? "created" : "updated"} in ${configPath}`,
+        });
+    }
+    for (const conflict of conflicts) {
+        items.push({ action: "conflict", kind: "mcp", target: configPath, description: conflict.message });
+    }
+    return items;
+}
+/** Merges every `"create"` MCP item into `parsed` (or a fresh `{}` if the
+ * file didn't exist), returning the object to stringify — every sibling
+ * top-level key on `parsed` is spread through untouched. */
+export function applyJsonMcp(parsed, items) {
+    const base = parsed ?? {};
+    const existingServers = base.mcpServers ?? {};
+    const mergedServers = { ...existingServers };
+    for (const item of items) {
+        if (item.kind !== "mcp" || item.action !== "create" || !item.mcpWrite) {
+            continue;
+        }
+        mergedServers[item.mcpWrite.name] = renderJsonServerEntry(item.mcpWrite.def);
+    }
+    return { ...base, mcpServers: mergedServers };
+}

package/dist/adapters/kiro.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Kiro adapter: same shape as Claude Code — `~/.kiro/skills/<name>`
+ * symlinks, `~/.kiro/steering/CLAUDE.md` symlinked to canonical `agents.md`.
+ *
+ * MCP servers: plain JSON parse → merge under `mcpServers` → stringify
+ * (trellis-mcp-sync-p2 design.md D4) — create/repair only, no automatic
+ * removal (D7).
+ *
+ * Kiro's own `${VAR}` substitution (real, found by reading Kiro's
+ * installed extension source — trellis-kiro-approved-env-vars design.md
+ * Context) is gated by `kiroAgent.mcpApprovedEnvVars`, a completely
+ * separate, VS-Code-style global settings.json — not the mcp.json above.
+ * A name absent from that list is silently never substituted. This
+ * adapter keeps that list a superset of every env name it references,
+ * additive only.
+ */
+import type { AdapterPlanItem, AdapterProbeResult, AdapterVerifyResult, TrellisAdapter } from "../core/adapter.js";
+import type { CanonicalSource } from "../core/types.js";
+export declare class KiroAdapter implements TrellisAdapter {
+    private readonly homeDir;
+    readonly name = "Kiro";
+    readonly id: "kiro";
+    constructor(homeDir?: string);
+    probe(): Promise<AdapterProbeResult>;
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    private planMcp;
+    /** Names come from `resolveMcpPlan`, not a raw scan of `canonical.mcp.servers`
+     * (design.md D2) — a server scoped away from Kiro, or refused for a
+     * known_host_injected collision, never contributes a name here either. */
+    private desiredApprovedEnvVars;
+    private planApprovedEnvVars;
+    apply(plan: AdapterPlanItem[]): Promise<void>;
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}