monkeyshape 0.0.0-stage → 0.2.0

package/skills/review-pr/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: review-pr
+description: Use when asked to review a pull request (a number or URL), to re-review one after its author replied or pushed fixes, or to review a follow-up PR that answers an earlier review's findings. Runs the change on real data in a scratch worktree, probes what it claims to enforce, posts every finding on the PR with a severity, and re-reviews until it can say "LGTM".
+---
+
+# Review a pull request
+
+A review is judged by what it **ran and read**, not by what it guessed from the diff. Every
+finding carries its evidence: the input that breaks it, a real-data output, or the line of
+code it rests on. Read AGENTS.md first: it holds the rules the PR is reviewed against.
+
+**Ground rules**
+- **The PR is the review's only home.** Findings, evidence, replies and what is still open
+  all go on it; nothing about the review is kept anywhere else. A fresh chat re-reviewing
+  reads the thread.
+- **Don't fix the PR yourself**: the author fixes findings in the same PR.
+- **Hold the PR to 95%, not 100%.** A blocker is a defect the PR would ship and someone
+  would hit, shown by a concrete failing input or a real-data result. "Could be better", or
+  an edge nobody has, is a nit, in any round. Style never blocks: the linter owns style.
+- **A nit stays open until it's settled:** fixed in this PR, declined with a reason you
+  accept, or filed by the author as a bead when it is real work beyond the PR. Never call a
+  blocker a nit to close a review.
+- **As many rounds as that takes.** If each fix keeps opening a new blocker, tell the human:
+  the design may need rethinking more than another patch. The human can step in at any point.
+- Real data may be read and run freely; spend past the repo's cap, or writes to shared data,
+  need the human first (see AGENTS.md).
+
+## 1. A worktree at the PR's head
+
+```bash
+N=<pr number>
+gh pr view $N --json title,body,files,commits
+gh api repos/{owner}/{repo}/pulls/$N -q .head.sha   # the head you review and anchor to
+mshape review $N         # detached worktree at that head, shared data linked; prints its path
+cd <that path> && bun install --frozen-lockfile
+```
+
+Never review in your own checkout. If the review's head and the API's differ, the author
+pushed meanwhile: run `mshape review $N` again.
+
+**A follow-up PR** that answers an earlier review: read that PR's thread first
+(`gh pr view <earlier> --comments`, and its inline comments as in step 5). Each finding it
+claims to answer is a re-review item (step 5), on top of reviewing its own diff.
+
+## 2. Read the diff
+
+Read the PR body and every changed file. Then go through it for:
+
+- **The invariants it claims.** If a schema, check or test says it enforces something, list
+  the inputs that should fail. Those are your probes in step 3.
+- **Docs it touches, or should have.** Do AGENTS.md, DECISIONS.md, the skills and the
+  handoffs still agree with the change? Grep for prose it made stale.
+- **The usual misses.** New code outside the gate (a tsconfig `include`, a test glob)? A
+  check that a free-text field walks around? A check-then-write that isn't atomic? A path
+  that breaks in a worktree, a symlink or a fresh clone? An error message that doesn't say
+  what to do?
+
+## 3. Run it
+
+From cheapest to most expensive:
+
+1. **Run what the PR adds**, on real data, in every mode it has. Do the numbers in the PR
+   body reproduce? Does each exit code mean what its doc says?
+2. **Probe checks adversarially**: throwaway scripts that build inputs which should be
+   rejected, one variation each, from a real artifact where there is one. **A bad input
+   that passes is a finding**, and the probe's input and output are its evidence on the PR.
+   Probes are scratch and are never committed or kept: one worth keeping is a regression
+   test, and that is the author's to add (step 4). **When the PR adds a check**, also probe
+   it with valid input it must pass: a false failure reaches everyone who runs the check,
+   and is a blocker.
+3. **Run the real workflow** when the claim is about what it produces end to end.
+
+Don't rerun the gate on the first pass if the PR body shows it green; do on a re-review whose
+fix touched code.
+
+## 4. Post on the PR
+
+Post **one review**, inline comments anchored to the head commit, built as a JSON file so
+the quoting survives:
+
+```bash
+# review.json: {commit_id, event: "COMMENT", body, comments: [{path, line, side: "RIGHT", body}]}
+gh api repos/{owner}/{repo}/pulls/$N/reviews --input review.json -q .html_url
+```
+
+Anchor each comment to a head-commit line that is in the diff; a finding with no such line
+goes in the review body. Each comment opens with a **bold one-sentence finding** and its
+severity (blocker or nit), then the evidence, then a suggested fix.
+
+- **A blocker in code asks for a regression test** in the PR: one that fails on this head
+  and passes once fixed. A blocker in prose (two docs that disagree, a wrong instruction)
+  asks for the fix; there is nothing to test.
+- **If a check could rule out the whole class**, say so: the PR body's "Class closed by"
+  line is where the author answers it.
+
+The body says what was run and what came out, the blockers, the nits with no line, and what
+looked good. Use `COMMENT`: GitHub refuses approve and request-changes on your own
+account's PR. Then tell the human in a few lines: what you ran, each finding and its
+severity, the review link. **Stop and wait** for the author.
+
+## 5. Re-review
+
+When told the author responded, read the thread: every reply, the new commits and the fix
+diff (`gh pr view $N --comments`, `gh api repos/{owner}/{repo}/pulls/$N/comments`). The head
+you reviewed last is your previous review's `commit_id`
+(`gh api repos/{owner}/{repo}/pulls/$N/reviews`). Run `mshape review $N` to move the
+worktree to the new head; it prints the previous one too.
+
+1. **"Fixed" is a claim.** For each code blocker, find its regression test and run it on
+   both heads. It must fail on the old one and pass on the new:
+
+   ```bash
+   git switch --detach <old head> && git checkout <new head> -- <test file> <files it needs>
+   bun test <test file>                                   # must fail
+   git reset -q --hard && git switch --detach <new head>
+   bun test <test file>                                   # must pass
+   ```
+
+   The failure on the old head must be the test's own assertion, saying what the finding
+   said: a load or import error means it never reached the bug, so check out the helpers
+   and fixtures it imports too, and rerun `bun install` if the dependencies changed. A test
+   that passes on the old head doesn't test the bug: that is a finding. For a prose
+   blocker, read the fix. Rerun the real-data runs the findings rested on.
+2. Look for what the fix opened: a new unchecked field, the mirror case of a new check.
+3. **Pushback is an argument, not a refusal.** If it holds, say so and drop the point; if it
+   doesn't, answer with evidence.
+4. Reply in the threads, then post a short summary review: what was re-verified, what is
+   resolved, what is still open. Tell the human.
+
+**When nothing is open, say "LGTM"** explicitly, on the PR and to the human: every blocker
+resolved and verified, every nit settled. Never while a finding is open or unverified.
+Merging is the human's call. When the review is over, `mshape review rm $N`: it lists what
+it discards, which in a review worktree is only scratch, then removes it.
+
+Review this skill when a blocker it should have caught reaches `main`.

package/skills/roadmap/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: roadmap
+description: Use when the human brings a brain-dump about where the repo is heading (new goals, a change of direction, a fresh repo after mshape init), or asks to rewrite the roadmap. Interviews until the goals are clear, writes docs/roadmap.md with a status table first, keeps one deferred beads epic per goal, and opens a PR.
+---
+
+# Roadmap: the long horizon
+
+The roadmap is direction, not a spec: months ahead, coarse, rewritten in place, never cited
+by code or normative docs. Your job is to turn a brain-dump into goals clear enough that a
+later `/milestone` can pick one and give it acceptance on real data.
+
+Run this in the main checkout, on an up-to-date `main`, in a fresh chat.
+
+## 1. Read what exists
+
+- docs/roadmap.md, if there is one, and AGENTS.md.
+- The direction epics: `bd list --type epic --all`. Deferred ones are goals not yet pulled
+  into a milestone; open ones are in flight; closed ones shipped.
+- If a milestone is running, plan/MILESTONE.md, only to know what is already committed.
+
+## 2. Interview
+
+Ask in small batches, and propose answers rather than asking open questions: "I read this as
+X; is that right?" is cheaper for the human than "what do you mean?". Keep going until you
+could write, for every goal:
+
+- **The consumer:** who or what uses it first. No goal without one.
+- **What done looks like** on real data or a real target, not a feature list.
+- **Why now, or why later**, and what it depends on.
+- **What is out of scope**, said out loud, so the next agent doesn't build it.
+- **Spend or authority** it will need from the human (money, public releases, data).
+
+Push back where the brain-dump conflicts with the code, with the repo's principles in
+AGENTS.md, or with itself. The human owns priorities; you own pointing out that two of them
+collide. Stop interviewing when another question would not change what you write.
+
+## 3. Write docs/roadmap.md
+
+Rewrite it in place; git has the history, so keep no revision log and no frozen copy.
+
+- **Open with a status table**: one row per goal, with status `Shipped`, `Milestone N` (in
+  progress), `Later` or `Idea`, and the epic id. A reader learns what exists without reading
+  the design.
+- Then scope (who it's for, what it is not), then a section per goal: the intent, the
+  consumer, what done looks like, and what was learned so far. Far-off detail belongs here,
+  not in beads.
+- No dated promises, no restating AGENTS.md or DECISIONS.md, and nothing other docs would
+  need to cite: if something must be enforced, it becomes a check, a test or a decision.
+
+## 4. One deferred epic per goal
+
+For each goal without an epic: `bd create --type epic --title "<goal>" --description "..."`
+with the goal, two or three lines of why, and the roadmap section it comes from, then
+`bd defer <id>`. **No child stories:** a milestone creates those when it pulls the epic in.
+For goals that changed, rewrite the epic; for goals dropped, close it with the reason. Put
+each epic's id in the status table.
+
+## 5. PR
+
+Branch from `main`, commit, push, and open a PR whose body says what changed in the
+direction and why, which epics were created, rewritten or closed, and what the interview
+left open. Gate green first (`bun run check`). The human merges.
+
+Then tell the human the next step: `/milestone` in a fresh chat, with their priorities.
+
+Review this skill when a roadmap written with it was hard for `/milestone` to plan from.

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/baseline.ts

@@ -0,0 +1,55 @@
+/** `.shape/baseline.json`: grandfathered violation counts per rule and file. */
+import { Effect, Schema } from "effect";
+import type { Counts } from "../core/ratchet.ts";
+import { decodeStrict } from "../helpers/decodeStrict.ts";
+import { WorkspaceError } from "../schemas/errors.ts";
+import { readText } from "./workspace.ts";
+
+export const BASELINE_FILE = ".shape/baseline.json";
+
+const Baseline = Schema.Struct({
+  version: Schema.Literal(1),
+  counts: Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Int)),
+});
+
+export const readBaseline = (root: string) =>
+  Effect.gen(function* () {
+    if (!(yield* Effect.promise(() => Bun.file(`${root}/${BASELINE_FILE}`).exists())))
+      return {} as Counts;
+    const text = yield* readText(root, BASELINE_FILE);
+    const json = yield* Effect.try({
+      try: (): unknown => JSON.parse(text),
+      catch: () =>
+        new WorkspaceError({ operation: "parse", path: BASELINE_FILE, reason: "not valid JSON" }),
+    });
+    const baseline = yield* decodeStrict(Baseline)(json).pipe(
+      Effect.mapError(
+        (error) =>
+          new WorkspaceError({ operation: "decode", path: BASELINE_FILE, reason: error.message }),
+      ),
+    );
+    return baseline.counts;
+  });
+
+const sorted = (counts: Counts): Counts =>
+  Object.fromEntries(
+    Object.keys(counts)
+      .sort()
+      .map((rule) => [
+        rule,
+        Object.fromEntries(
+          Object.entries(counts[rule] ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+        ),
+      ]),
+  );
+
+export const writeBaseline = (root: string, counts: Counts) =>
+  Effect.tryPromise({
+    try: () =>
+      Bun.write(
+        `${root}/${BASELINE_FILE}`,
+        `${JSON.stringify({ version: 1, counts: sorted(counts) }, null, 2)}\n`,
+      ),
+    catch: (cause) =>
+      new WorkspaceError({ operation: "write", path: BASELINE_FILE, reason: String(cause) }),
+  });

package/src/adapters/config.ts

@@ -0,0 +1,25 @@
+/** Loads `shape.config.ts` by importing it, then decodes it strictly. */
+import { Effect } from "effect";
+import { decodeStrict } from "../helpers/decodeStrict.ts";
+import { resolveConfig, ShapeConfig } from "../schemas/config.ts";
+import { ConfigError } from "../schemas/errors.ts";
+
+export const CONFIG_FILE = "shape.config.ts";
+
+/** `path` overrides the repo's own config, e.g. to try monkeyshape on a repo before adopting it. */
+export const loadConfig = (root: string, path = `${root}/${CONFIG_FILE}`) =>
+  Effect.gen(function* () {
+    if (!(yield* Effect.promise(() => Bun.file(path).exists())))
+      return yield* Effect.fail(
+        new ConfigError({ path: CONFIG_FILE, reason: "not found; every adopting repo has one" }),
+      );
+    const module = yield* Effect.tryPromise({
+      try: () => import(path) as Promise<{ readonly default?: unknown }>,
+      catch: (cause) =>
+        new ConfigError({ path: CONFIG_FILE, reason: `could not load: ${String(cause)}` }),
+    });
+    const config = yield* decodeStrict(ShapeConfig)(module.default).pipe(
+      Effect.mapError((error) => new ConfigError({ path: CONFIG_FILE, reason: error.message })),
+    );
+    return resolveConfig(config);
+  });

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 }),
+    ),
+  );