monkeyshape 0.1.0 → 0.2.0

package/skills/track/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: track
+description: Use at the start of a chat in a track's worktree, when the human says /track or asks to continue a track's work. Finds the track, reads its handoff and queue, interviews the human first if the handoff is a stub, then works the queue and opens PRs.
+---
+
+# Track: the short horizon
+
+A track is one line of parallel work with its own worktree, branch, beads label and handoff.
+The handoff is the whole of what the last session knew; the queue is what is left to do.
+Your job is to pick up exactly where it stopped.
+
+## 1. Which track
+
+Run `mshape track current`. It prints the track's name. If it exits 1, stop: tell the human
+the reason it gave for this directory not being a track, and suggest
+`mshape track list` to find the worktree they meant, or `mshape track new <name>` if this is
+new work. Never work a track from outside its worktree.
+
+## 2. Read
+
+- The handoff, `.handoffs/<name>.md`: Messages first (they may change everything else),
+  then State, Traps and Charter.
+- AGENTS.md, and whatever the charter points at (often plan/MILESTONE.md, for the
+  interfaces this track owns or consumes).
+- The queue: `bd list --label track:<name>` for every open bead, including the one the last
+  session left in progress and those blocked on other tracks;
+  `bd ready --label track:<name>` for what can start now; `bd show` for each bead you take.
+- Where the code is: `git status`, `git log --oneline main..HEAD`, open PRs from this
+  branch (`gh pr list --head track/<name>`), and the gate as AGENTS.md says to run it.
+
+Text is a hypothesis: when the handoff or a bead disagrees with the code, trust the code,
+fix the text, and carry on.
+
+## 3. A stub: interview first
+
+`Status: stub` means nobody has said what this track is for. Before any code, interview the
+human, proposing answers rather than asking open questions:
+
+- What is the work, and why now?
+- What does done look like, on real data or a real target?
+- What is out of scope?
+- What does it touch, and does that collide with another track? (`mshape track list` and
+  the other handoffs say what is in flight.)
+- What will need the human: spend, data, anything public?
+
+Then write the charter, set `Status: active`, write a dated State, and create the beads with
+`--labels track:<name>`, each an intent and an outcome, not a spec. Show the human the
+charter and the beads; start once they agree.
+
+## 4. Work
+
+- Claim a bead (`bd update <id> --claim`) before starting it, and commit as you go.
+- **Batch beads into PRs** sized as the working-loop conventions say (docs/workflow.md in the
+  monkeyshape package): one theme, gate green, its body as AGENTS.md says. Close the beads
+  when it merges.
+- **One open PR at a time**, from `track/<name>`: the branch is the PR's head, so a commit
+  pushed while it is in review joins it. While it waits, answer its review and prepare the
+  next beads without committing. If waiting would stall the track, tell the human.
+- **Diverging from the milestone plan:** say so in the handoff's State. If it changes
+  another track's work or the milestone's goal, stop and tell the human.
+- **Talking to another track:** add to its handoff's Messages, saying who it is from and the
+  date. Edit the file in place; never rewrite another track's handoff. Read your own
+  Messages again after each PR.
+- **A mechanical step with no command:** don't script it into prose; file a bead for the CLI.
+- **The process got in the way:** `bd create --labels process` saying what broke.
+
+Update the handoff's State when a PR opens or merges, so a crash loses nothing. When the
+human says the context is running out, run `/handoff`. When this track's `beads` column
+in `mshape track list` shows 0 and the PRs are merged, tell the human the track is done (an
+empty `bd ready` is not enough: it hides beads in progress or blocked). A `-` there means
+beads weren't counted: act on the note `track list` prints, and don't call the track done.
+Removing it is the human's or `/milestone`'s.
+
+Review this skill when a fresh chat running it had to ask the human something the handoff
+should have said.

package/src/adapters/init.ts

@@ -0,0 +1,176 @@
+/** `mshape init`: writes a new repo from the package's template, installs it and commits it. */
+import { mkdir, readdir, realpath, symlink } from "node:fs/promises";
+import { dirname, relative } from "node:path";
+import { Effect } from "effect";
+import { HANDOFFS_LINK, handoffsLink, handoffsStore } from "../core/layout.ts";
+import { scaffold, type Toolchain } from "../core/scaffold.ts";
+import { resolveConfig } from "../schemas/config.ts";
+import { WorkspaceError } from "../schemas/errors.ts";
+import { runTool } from "./process.ts";
+import { installSkills, readTree } from "./skills.ts";
+
+export interface InitResult {
+  /** What was done, one line each. */
+  readonly done: ReadonlyArray<string>;
+  /** What was skipped or failed and how to finish it by hand; the repo still exists. */
+  readonly notes: ReadonlyArray<string>;
+}
+
+const fail = (path: string, reason: string) =>
+  new WorkspaceError({ operation: "init", path, reason });
+
+/** A command's exit code and combined output; one that can't start exits -1 with the reason. */
+const run = (cwd: string, command: ReadonlyArray<string>) =>
+  Effect.map(runTool(cwd, command), (ran) => ({
+    code: ran.code,
+    output: `${ran.stdout}${ran.stderr}`.trim(),
+  }));
+
+/** The last lines of a tool's output: enough to say why it failed. */
+const tail = (output: string): string => output.split("\n").slice(-3).join("\n  ");
+
+const isEmptyOrMissing = (dir: string) =>
+  Effect.promise(() =>
+    readdir(dir).then(
+      (entries) => entries.length === 0,
+      (error: NodeJS.ErrnoException) => error.code === "ENOENT",
+    ),
+  );
+
+/**
+ * The handoffs store under git's common directory, and the two links to it. Relative links,
+ * so the repo still works after it is moved. A failure is a note with the commands to finish:
+ * by now the repo exists, and init refuses to run over it again.
+ */
+const stateDirectory = (target: string, name: string) =>
+  Effect.gen(function* () {
+    const byHand = `In ${name}/ run \`mkdir -p .agents .git/monkeyshape/handoffs && ln -s ../.git/monkeyshape/handoffs .agents/handoffs && ln -s .git/monkeyshape/handoffs ${HANDOFFS_LINK}\``;
+    const common = yield* run(target, [
+      "git",
+      "rev-parse",
+      "--path-format=absolute",
+      "--git-common-dir",
+    ]);
+    if (common.code !== 0)
+      return `the handoffs store is not set up: git did not name its directory. ${byHand}:\n  ${tail(common.output)}`;
+    const store = handoffsStore(common.output);
+    return yield* Effect.promise(async () => {
+      try {
+        await mkdir(store, { recursive: true });
+        // git answers with real paths; a link computed from a symlinked path would miss.
+        const repo = await realpath(target);
+        for (const link of [handoffsLink(repo), `${repo}/${HANDOFFS_LINK}`]) {
+          await mkdir(dirname(link), { recursive: true });
+          await symlink(relative(dirname(link), store), link);
+        }
+        return undefined;
+      } catch (cause) {
+        return `the handoffs store is not fully set up (${String(cause)}). ${byHand}, skipping what exists.`;
+      }
+    });
+  });
+
+/**
+ * `bd init` without its AGENTS.md block, and prime capped at the budgets `mshape check` holds.
+ * prime caps characters and the budget counts UTF-8 bytes, so the character cap is only a
+ * backstop: while the check passes, memories are within the byte budget, hence also within
+ * the same number of characters, and prime never truncates them.
+ */
+const beads = (target: string, name: string) =>
+  Effect.gen(function* () {
+    const { memories, memoryBytes } = resolveConfig({}).budgets;
+    const steps = [
+      ["bd", "init", "--skip-agents", "--non-interactive", "--quiet", "--prefix", name],
+      ["bd", "config", "set", "prime.max-memories", String(memories)],
+      ["bd", "config", "set", "prime.max-memory-chars", String(memoryBytes)],
+    ];
+    const later = steps.map((step) => step.join(" ")).join(" && ");
+    if (Bun.which("bd") === null)
+      return `bd is not on PATH, so beads is not set up. Install bd, then in ${name}/ run \`${later}\` and commit .beads/`;
+    for (const step of steps) {
+      const result = yield* run(target, step);
+      if (result.code !== 0)
+        return `\`${step.join(" ")}\` failed, so beads is not fully set up. In ${name}/ run \`${later}\`:\n  ${tail(result.output)}`;
+    }
+    return undefined;
+  });
+
+/** `packageRoot` is the installed monkeyshape: its `template/` and `skills/` are copied. */
+export const initRepo = (target: string, name: string, packageRoot: string, toolchain: Toolchain) =>
+  Effect.gen(function* () {
+    if (!(yield* isEmptyOrMissing(target)))
+      return yield* Effect.fail(fail(target, "exists and is not empty; init only creates repos"));
+    /** Past this point the directory exists, and init won't run over it again. */
+    const partial = (reason: string) =>
+      fail(target, `${reason}. Delete ${target} and run mshape init again`);
+    const decoder = new TextDecoder();
+    const template = new Map(
+      [...(yield* readTree(`${packageRoot}/template`))].map(
+        ([path, bytes]) => [path, decoder.decode(bytes)] as const,
+      ),
+    );
+    if (template.size === 0)
+      return yield* Effect.fail(fail(packageRoot, "has no template/; reinstall monkeyshape"));
+    const files = scaffold(name, template, toolchain);
+    yield* Effect.tryPromise({
+      try: async () => {
+        for (const [path, text] of files) {
+          await mkdir(dirname(`${target}/${path}`), { recursive: true });
+          await Bun.write(`${target}/${path}`, text);
+        }
+      },
+      catch: (cause) => partial(`cannot write the template: ${String(cause)}`),
+    });
+    const done = [`wrote ${files.size} files`];
+    const notes: Array<string> = [];
+    const skills = yield* installSkills(`${packageRoot}/skills`, target).pipe(
+      Effect.mapError((error) => partial(`cannot install the skills: ${error.reason}`)),
+    );
+    done.push(`${skills.sync.added.length} shared skills`);
+
+    const git = yield* run(target, ["git", "init", "--quiet", "--initial-branch=main"]);
+    if (git.code !== 0) return yield* Effect.fail(partial(`git init failed: ${git.output}`));
+    done.push("git init (branch main)");
+
+    const stateNote = yield* stateDirectory(target, name);
+    if (stateNote === undefined) done.push("handoffs store");
+    else notes.push(stateNote);
+
+    const beadsNote = yield* beads(target, name);
+    if (beadsNote === undefined) done.push("bd init");
+    else notes.push(beadsNote);
+
+    // The current bun, not `bun` from PATH: it is the one running mshape, so it exists.
+    const install = yield* run(target, [process.execPath, "install"]);
+    if (install.code === 0) {
+      done.push("bun install");
+      // The generated JSON is laid out by JSON.stringify; the repo's own biome has the last word.
+      const format = yield* run(target, [
+        process.execPath,
+        "node_modules/.bin/biome",
+        "format",
+        "--write",
+        ".",
+      ]);
+      if (format.code !== 0)
+        notes.push(`biome format failed; run \`bun run fix\`:\n  ${tail(format.output)}`);
+    } else
+      notes.push(
+        `bun install failed, so bun.lock is not committed. Run \`bun install\` in ${name}/ and commit bun.lock:\n  ${tail(install.output)}`,
+      );
+
+    // `bd init` commits its own files; fold that into the one first commit, message and all.
+    const bdCommit = yield* run(target, ["git", "rev-parse", "--verify", "--quiet", "HEAD"]);
+    if (bdCommit.code === 0) yield* run(target, ["git", "update-ref", "-d", "HEAD"]);
+    const add = yield* run(target, ["git", "add", "--all"]);
+    const commit =
+      add.code === 0
+        ? yield* run(target, ["git", "commit", "--quiet", "-m", `Start ${name} with mshape init`])
+        : add;
+    if (commit.code === 0) done.push("first commit");
+    else
+      notes.push(
+        `the first commit failed; set your git identity, then \`git add --all && git commit\`:\n  ${tail(commit.output)}`,
+      );
+    return { done, notes } satisfies InitResult;
+  });

package/src/adapters/process.ts

@@ -0,0 +1,38 @@
+/** Running a command: the one spawn helper every adapter uses. */
+import { Effect } from "effect";
+import { WorkspaceError } from "../schemas/errors.ts";
+
+export interface Ran {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Runs `command` in `cwd` to completion. A command that can't start fails with the reason. */
+export const run = (cwd: string, command: ReadonlyArray<string>) =>
+  Effect.try({
+    try: () => Bun.spawn([...command], { cwd, stdout: "pipe", stderr: "pipe" }),
+    catch: (cause) =>
+      new WorkspaceError({ operation: "run", path: command.join(" "), reason: String(cause) }),
+  }).pipe(
+    Effect.flatMap((child) =>
+      // Both pipes at once: a tool that fills one while we wait on the other would hang.
+      Effect.all(
+        [
+          Effect.promise(() => new Response(child.stdout).text()),
+          Effect.promise(() => new Response(child.stderr).text()),
+          Effect.promise(() => child.exited),
+        ],
+        { concurrency: "unbounded" },
+      ),
+    ),
+    Effect.map(([stdout, stderr, code]): Ran => ({ code, stdout, stderr })),
+  );
+
+/** For optional tools: a spawn failure is exit code -1 with the reason on stderr, not an abort. */
+export const runTool = (cwd: string, command: ReadonlyArray<string>) =>
+  run(cwd, command).pipe(
+    Effect.catchTag("WorkspaceError", (error) =>
+      Effect.succeed<Ran>({ code: -1, stdout: "", stderr: error.reason }),
+    ),
+  );

package/src/adapters/reviews.ts

@@ -0,0 +1,170 @@
+/**
+ * `mshape review <n>` and `mshape review rm <n>`: a pull request's head in a detached worktree
+ * beside the tracks, with `tracks.sharedPaths` linked in, for the `review-pr` skill. A review is
+ * not a track: no branch, no handoff, no label. Its state lives on the pull request, and the
+ * worktree is scratch, removed when the review ends. Paths come from `src/core/layout.ts`.
+ */
+import { posix } from "node:path";
+import { Effect } from "effect";
+import { PR_NUMBER, reviewPath, reviewRef } from "../core/layout.ts";
+import { sharedPathProblems } from "../core/tracks.ts";
+import { loadConfig } from "./config.ts";
+import { git, gitOk, ignored, lexists, linkTo, locate, refuse, worktrees } from "./tracks.ts";
+
+/** Pull requests are fetched from here, as GitHub publishes them: `refs/pull/<n>/head`. */
+const REMOTE = "origin";
+
+const numberProblem = (pr: string) =>
+  PR_NUMBER.test(pr)
+    ? Effect.void
+    : refuse(`give the pull request's number, e.g. \`mshape review 12\` (got '${pr}')`);
+
+/** Fetch the head into the review's own ref; the commit it names. */
+const fetchHead = (repo: string, pr: string) =>
+  Effect.gen(function* () {
+    const ref = reviewRef(pr);
+    const fetched = yield* git(repo, [
+      "fetch",
+      "--quiet",
+      "--no-write-fetch-head",
+      REMOTE,
+      `+refs/pull/${pr}/head:${ref}`,
+    ]);
+    if (fetched.code !== 0)
+      return yield* refuse(
+        `could not fetch pull request #${pr} from \`${REMOTE}\` (as \`refs/pull/${pr}/head\`, which GitHub publishes): ${fetched.stderr || `exit ${fetched.code}`}`,
+      );
+    return yield* gitOk(repo, ["rev-parse", `${ref}^{commit}`]);
+  });
+
+/**
+ * `tracks.sharedPaths` linked into the review's worktree, after a create or a move alike: a path
+ * the head tracks is the PR's own (git put it there) and only noted; a missing link is made.
+ */
+const linkShared = (repo: string, path: string, pr: string, shared: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const said: Array<string> = [];
+    for (const entry of shared) {
+      const target = `${repo}/${entry}`;
+      if ((yield* git(path, ["cat-file", "-e", `HEAD:${entry}`])).code === 0)
+        said.push(
+          `note: shared path \`${entry}\` is tracked at the head of #${pr}; not linked. A shared path must be gitignored, never tracked`,
+        );
+      else if (yield* lexists(`${path}/${entry}`)) continue;
+      else if (!(yield* lexists(target)))
+        said.push(`note: shared path \`${entry}\` is missing in ${repo}; not linked`);
+      else {
+        yield* linkTo(repo, `${path}/${entry}`, target);
+        said.push(`linked ${path}/${entry} -> ${target}`);
+      }
+    }
+    return said;
+  });
+
+/**
+ * Puts an existing review worktree exactly at `head`. It is scratch, so edits to tracked files
+ * are discarded, after `say` lists them; untracked probes stay, unless `head` tracks the same
+ * path. Never git's "commit or stash" advice: the stash is shared by every worktree.
+ */
+const resetTo = (path: string, head: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    const status = yield* git(path, ["status", "--porcelain", "--untracked-files=all"]);
+    for (const line of status.stdout.split("\n").filter((line) => line.trim() !== "")) {
+      const file = line.slice(3);
+      if (!line.startsWith("??")) yield* say(`discarding in ${path}: ${line.trim()}`);
+      else if ((yield* git(path, ["cat-file", "-e", `${head}:${file}`])).code === 0)
+        yield* say(`overwriting in ${path}: ${file}, which the head tracks`);
+    }
+    yield* gitOk(path, ["checkout", "--quiet", "--force", "--detach", head]);
+  });
+
+/**
+ * Creates the review's worktree at the pull request's head, or puts an existing one there,
+ * printing the previous head: a re-review checks a regression test against both.
+ */
+export const reviewNew = (cwd: string, pr: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    yield* numberProblem(pr);
+    const { repo } = yield* locate(cwd);
+    const shared = (yield* loadConfig(repo)).tracks.sharedPaths;
+    const problems = sharedPathProblems(shared);
+    if (problems.length > 0) return yield* refuse(problems.join("\n"));
+    const path = reviewPath(repo, pr);
+    const registered = (yield* worktrees(repo)).some((worktree) => worktree.path === path);
+    const present = yield* lexists(path);
+    if (registered && !present)
+      return yield* refuse(
+        `git still has a worktree registered at ${path}: run \`git worktree prune\`, then this again`,
+      );
+    if (!registered && present)
+      return yield* refuse(
+        `${path} exists but git has no worktree there: remove it, then this again`,
+      );
+
+    const head = yield* fetchHead(repo, pr);
+    if (registered) {
+      const before = yield* gitOk(path, ["rev-parse", "HEAD"]);
+      yield* resetTo(path, head, say);
+      const linked = yield* linkShared(repo, path, pr, shared);
+      return [
+        ...(before === head
+          ? [`${path} is at the head of #${pr}: ${head}`]
+          : [`moved ${path} to the head of #${pr}: ${head}`, `previous head: ${before}`]),
+        ...linked,
+        `next: cd ${path}`,
+      ].join("\n");
+    }
+
+    const notes: Array<string> = [];
+    if (!(yield* ignored(repo, posix.relative(repo, path))))
+      notes.push(
+        `note: the worktrees directory (\`${posix.relative(repo, path)}\`) is not gitignored; add it to .gitignore`,
+      );
+    yield* gitOk(repo, ["worktree", "add", "--quiet", "--detach", path, head]);
+    const created = `created ${path} at the head of #${pr}: ${head}`;
+    const linked = yield* linkShared(repo, path, pr, shared).pipe(
+      Effect.catch((error) =>
+        refuse(
+          [
+            `review ${pr}: stopped: ${error.message}`,
+            `done: ${created}`,
+            `undo with \`mshape review rm ${pr}\``,
+          ].join("\n  "),
+        ),
+      ),
+    );
+    return [...notes, created, ...linked, `next: cd ${path}`].join("\n");
+  });
+
+/**
+ * Removes the review's worktree and its fetched ref. Everything in a review worktree is scratch,
+ * so changes in it are discarded, after `say` lists them. Shared data is only ever linked, and
+ * removing the worktree removes the links, never their targets.
+ */
+export const reviewRm = (cwd: string, pr: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    yield* numberProblem(pr);
+    const { repo } = yield* locate(cwd);
+    const path = reviewPath(repo, pr);
+    const registered = (yield* worktrees(repo)).some((worktree) => worktree.path === path);
+    const present = yield* lexists(path);
+    if (!registered && present)
+      return yield* refuse(
+        `${path} exists but git has no worktree there, so it isn't a review's: left alone`,
+      );
+    const removed: Array<string> = [];
+    if (registered && present) {
+      const status = yield* gitOk(path, ["status", "--porcelain", "--untracked-files=all"]);
+      const changes = status.split("\n").filter((line) => line.trim() !== "");
+      yield* Effect.forEach(changes, (line) => say(`discarding in ${path}: ${line.trim()}`));
+      yield* gitOk(repo, ["worktree", "remove", "--force", path]);
+      removed.push(`removed ${path}`);
+    }
+    const ref = reviewRef(pr);
+    if ((yield* git(repo, ["show-ref", "--verify", "--quiet", ref])).code === 0) {
+      yield* gitOk(repo, ["update-ref", "-d", ref]);
+      removed.push(`removed ${ref}`);
+    }
+    yield* gitOk(repo, ["worktree", "prune"]);
+    return removed.length > 0 ? removed.join("\n") : `no review of #${pr} here; nothing removed`;
+  });

package/src/adapters/skills.ts

@@ -0,0 +1,113 @@
+/** Installs the package's shared skills into a repo, and links them where Claude Code looks. */
+import { lstat, mkdir, readlink, rm, symlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { Effect } from "effect";
+import {
+  CLAUDE_SKILLS_LINK,
+  CLAUDE_SKILLS_TARGET,
+  SKILLS_DIR,
+  SKILLS_MANIFEST,
+} from "../core/layout.ts";
+import type { SkillFiles, SkillsLink, SkillsSnapshot } from "../core/model.ts";
+import { parseManifest, type SkillSync, syncSkills } from "../core/skills.ts";
+import { WorkspaceError } from "../schemas/errors.ts";
+
+/** Whether anything is at `path`, a dangling link included. */
+const present = (path: string): Promise<boolean> =>
+  lstat(path).then(
+    () => true,
+    () => false,
+  );
+
+/**
+ * Every file under `dir` as bytes, by relative path; a missing directory has none. Symlinks
+ * are followed, so a skill linked in from elsewhere is read like any other.
+ */
+export const readTree = (dir: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const files = new Map<string, Uint8Array>();
+      if (!(await present(dir))) return files as SkillFiles;
+      const glob = new Bun.Glob("**").scan({ cwd: dir, dot: true, followSymlinks: true });
+      for await (const path of glob) files.set(path, await Bun.file(`${dir}/${path}`).bytes());
+      return files as SkillFiles;
+    },
+    catch: (cause) => new WorkspaceError({ operation: "read", path: dir, reason: String(cause) }),
+  });
+
+export interface SkillsInstall {
+  readonly sync: SkillSync;
+  /** Whether `.claude/skills` had to be created. */
+  readonly linked: boolean;
+}
+
+/**
+ * Brings `<repo>/.agents/skills` up to the package's `skills/`, and creates the
+ * `.claude/skills` link if it is missing. An existing link or directory there is left alone:
+ * `mshape check` says what is wrong with it.
+ */
+export const installSkills = (shippedDir: string, repo: string) =>
+  Effect.gen(function* () {
+    const installedDir = `${repo}/${SKILLS_DIR}`;
+    const installed = yield* readTree(installedDir);
+    const manifest = installed.get(SKILLS_MANIFEST);
+    // An unreadable manifest can't tell shared skills from the repo's own: touch nothing.
+    if (manifest !== undefined && parseManifest(manifest) === undefined)
+      return yield* Effect.fail(
+        new WorkspaceError({
+          operation: "sync skills",
+          path: `${SKILLS_DIR}/${SKILLS_MANIFEST}`,
+          reason: `is not the list sync writes, so nothing was changed. Restore it with \`git checkout -- ${SKILLS_DIR}/${SKILLS_MANIFEST}\``,
+        }),
+      );
+    const sync = syncSkills(yield* readTree(shippedDir), installed);
+    const link = `${repo}/${CLAUDE_SKILLS_LINK}`;
+    const linked = yield* Effect.tryPromise({
+      try: async () => {
+        await mkdir(installedDir, { recursive: true });
+        for (const path of sync.remove) await rm(`${installedDir}/${path}`);
+        for (const skill of sync.retired) {
+          const target = resolve(installedDir, skill);
+          // Belt and braces: syncSkills only retires installed skill directories.
+          if (dirname(target) !== resolve(installedDir))
+            throw new Error(`refusing to remove ${target}: not a skill directory`);
+          await rm(target, { recursive: true });
+        }
+        for (const [path, bytes] of sync.write) {
+          await mkdir(dirname(`${installedDir}/${path}`), { recursive: true });
+          await Bun.write(`${installedDir}/${path}`, bytes);
+        }
+        if (await present(link)) return false;
+        await mkdir(dirname(link), { recursive: true });
+        await symlink(CLAUDE_SKILLS_TARGET, link);
+        return true;
+      },
+      catch: (cause) =>
+        new WorkspaceError({ operation: "install skills", path: repo, reason: String(cause) }),
+    });
+    return { sync, linked } satisfies SkillsInstall;
+  });
+
+const linkAt = (path: string): Promise<SkillsLink> =>
+  lstat(path).then(
+    async (info): Promise<SkillsLink> =>
+      info.isSymbolicLink()
+        ? { kind: "link", target: await readlink(path) }
+        : info.isDirectory()
+          ? { kind: "directory" }
+          : { kind: "other" },
+    (): SkillsLink => ({ kind: "missing" }),
+  );
+
+/** What `mshape check` needs to verify the install, read from disk as agents will see it. */
+export const loadSkills = (shippedDir: string, repo: string) =>
+  Effect.gen(function* () {
+    const link = yield* Effect.promise(() => linkAt(`${repo}/${CLAUDE_SKILLS_LINK}`));
+    return {
+      link,
+      installed: yield* readTree(`${repo}/${SKILLS_DIR}`),
+      claudeDirectory:
+        link.kind === "directory" ? yield* readTree(`${repo}/${CLAUDE_SKILLS_LINK}`) : new Map(),
+      shipped: yield* readTree(shippedDir),
+    } satisfies SkillsSnapshot;
+  });