@sven1103/opencode-worktree-workflow 0.5.1 → 0.6.1

package/README.md

@@ -1,6 +1,46 @@
 # OpenCode Worktree Workflow
 
-`@sven1103/opencode-worktree-workflow` is an OpenCode plugin that adds git worktree helpers for creating synced feature worktrees and cleaning up merged ones.
+`@sven1103/opencode-worktree-workflow` is an npm package that provides OpenCode git worktree helpers for creating synced feature worktrees and cleaning up merged ones.
+
+## Quick start
+
+To get the workflow running in a project:
+
+1. Install the package once by following [Recommended setup](#recommended-setup).
+2. Enable the plugin in your OpenCode config as shown in [Recommended setup](#recommended-setup).
+3. If you want manual `/wt-new` and `/wt-clean` triggers, install the markdown files from [Install slash commands](#install-slash-commands).
+4. If you want policy guidance for when to isolate work, install the skill from [Co-shipped skill](#co-shipped-skill).
+5. If you need to understand how the local fallback works, see [CLI fallback](#cli-fallback).
+
+## Recommended setup
+
+Install the package once:
+
+```sh
+npm install -D @sven1103/opencode-worktree-workflow
+```
+
+Enable the native OpenCode plugin in `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@sven1103/opencode-worktree-workflow"]
+}
+```
+
+This single package provides two access modes:
+
+- native plugin tools inside OpenCode: `worktree_prepare`, `worktree_cleanup`
+- local CLI fallback from the same installed package:
+  - `npx opencode-worktree-workflow wt-new "<title>" --json`
+  - `npx opencode-worktree-workflow wt-clean <args> --json`
+
+In practice:
+
+- if the plugin is loaded, use the native tools first
+- if the native tools are unavailable, use the local CLI fallback from the same installed package
+- if the package is not installed, no CLI fallback is available
 
 ## Install in an OpenCode project
 
@@ -28,7 +68,7 @@ Keeping the npm dependency in `package.json` makes the installation more durable
 If you do not already install dependencies in your project, you can add the package directly with npm:
 
 ```sh
-npm install @sven1103/opencode-worktree-workflow
+npm install -D @sven1103/opencode-worktree-workflow
 ```
 
 ## Install slash commands
@@ -75,12 +115,76 @@ curl -fsSL "https://github.com/sven1103-agent/opencode-worktree-plugin/releases/
 curl -fsSL "https://github.com/sven1103-agent/opencode-worktree-plugin/releases/download/${VERSION}/wt-clean.md" -o ".opencode/commands/wt-clean.md"
 ```
 
+## Co-shipped skill
+
+This repo also co-ships a `worktree-workflow` skill as a policy layer over the package capability.
+
+- checked-in skill: `skills/worktree-workflow/SKILL.md`
+- release asset: `SKILL.md`
+
+The skill teaches when to use task-scoped worktrees, when repo root is still acceptable, and how to prefer the native tool path before falling back to the packaged CLI.
+
+Project-local install (latest release):
+
+```sh
+mkdir -p .opencode/skills/worktree-workflow
+curl -fsSL "https://github.com/sven1103-agent/opencode-worktree-plugin/releases/latest/download/SKILL.md" -o ".opencode/skills/worktree-workflow/SKILL.md"
+```
+
+```sh
+mkdir -p .opencode/skills/worktree-workflow
+wget -qO ".opencode/skills/worktree-workflow/SKILL.md" "https://github.com/sven1103-agent/opencode-worktree-plugin/releases/latest/download/SKILL.md"
+```
+
+If your setup uses installed skill files, copy the released `SKILL.md` into a `worktree-workflow/` skill folder in the appropriate location for that environment, or consume the checked-in file from this repo directly.
+
 ## What the plugin provides
 
 - `worktree_prepare`: create a worktree and matching branch from the latest configured base-branch commit, or the default branch when no base branch is configured
 - `worktree_cleanup`: preview all connected worktrees against the configured base branch, auto-clean safe ones, and optionally remove selected review items
 
-This package currently focuses on plugin distribution. Slash command packaging can be layered on later.
+This package now ships the plugin capability, a CLI fallback surface, thin slash commands, and a co-shipped policy skill.
+
+## Structured contract
+
+The native tool results and CLI `--json` output now use a versioned structured contract with a `schema_version` field.
+
+- current `schema_version`: `1.0.0`
+- contract overview: `docs/contract.md`
+- compatibility model: `docs/compatibility.md`
+- checked-in schemas for transparency:
+  - `schemas/worktree-prepare.result.schema.json`
+  - `schemas/worktree-cleanup-preview.result.schema.json`
+  - `schemas/worktree-cleanup-apply.result.schema.json`
+
+Human-readable output remains available through the result `message`, but callers should depend on the structured fields rather than parsing prose.
+
+## CLI fallback
+
+The npm package also exposes a local CLI so agents can fall back to the same installed package when the native plugin tools are unavailable.
+
+Examples:
+
+```sh
+npx opencode-worktree-workflow wt-new "Improve checkout retry logic"
+npx opencode-worktree-workflow wt-new "Improve checkout retry logic" --json
+npx opencode-worktree-workflow wt-clean preview
+npx opencode-worktree-workflow wt-clean apply feature/foo --json
+```
+
+Defaults:
+
+- human-readable output by default
+- structured output with `--json`
+- the CLI shares the same underlying implementation and result contract as the native tools
+- the CLI fallback depends on the package already being installed in the project
+
+## Compatibility model
+
+The repo keeps config loading, argument normalization, and execution semantics centralized in the package implementation so existing installations continue to work across native tools, CLI fallback, and slash commands.
+
+- compatibility overview: `docs/compatibility.md`
+- existing `.opencode/worktree-workflow.json` setups remain the supported configuration path
 
 ## Optional project configuration
 

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@sven1103/opencode-worktree-workflow",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",
+  "bin": {
+    "opencode-worktree-workflow": "./src/cli.js"
+  },
   "exports": {
     ".": "./src/index.js"
   },
   "files": [
-    "src"
+    "src",
+    "schemas",
+    "skills"
   ],
   "keywords": [
     "opencode",

package/schemas/worktree-cleanup-apply.result.schema.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sven1103-agent/opencode-worktree-plugin/schemas/worktree-cleanup-apply.result.schema.json",
+  "title": "worktree_cleanup apply result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "ok",
+    "mode",
+    "default_branch",
+    "base_branch",
+    "base_ref",
+    "requested_selectors",
+    "removed",
+    "failed"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "ok": {
+      "type": "boolean",
+      "const": true
+    },
+    "mode": {
+      "type": "string",
+      "const": "apply"
+    },
+    "default_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "requested_selectors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "removed": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/removedItem"
+      }
+    },
+    "failed": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/failedItem"
+      }
+    },
+    "message": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "baseCleanupItem": {
+      "type": "object",
+      "required": [
+        "branch",
+        "worktree_path",
+        "head",
+        "status",
+        "reason",
+        "detached",
+        "selectable"
+      ],
+      "properties": {
+        "branch": {
+          "type": ["string", "null"]
+        },
+        "worktree_path": {
+          "type": ["string", "null"]
+        },
+        "head": {
+          "type": ["string", "null"]
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["safe", "review", "blocked", null]
+        },
+        "reason": {
+          "type": ["string", "null"]
+        },
+        "detached": {
+          "type": "boolean"
+        },
+        "selectable": {
+          "type": ["boolean", "null"]
+        }
+      }
+    },
+    "removedItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "branch",
+        "worktree_path",
+        "head",
+        "status",
+        "reason",
+        "detached",
+        "selectable",
+        "selected"
+      ],
+      "properties": {
+        "branch": {
+          "type": ["string", "null"]
+        },
+        "worktree_path": {
+          "type": ["string", "null"]
+        },
+        "head": {
+          "type": ["string", "null"]
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["safe", "review", "blocked", null]
+        },
+        "reason": {
+          "type": ["string", "null"]
+        },
+        "detached": {
+          "type": "boolean"
+        },
+        "selectable": {
+          "type": ["boolean", "null"]
+        },
+        "selected": {
+          "type": "boolean"
+        }
+      }
+    },
+    "failedItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "selector",
+        "branch",
+        "worktree_path",
+        "head",
+        "status",
+        "reason",
+        "detached",
+        "selectable"
+      ],
+      "properties": {
+        "selector": {
+          "type": ["string", "null"]
+        },
+        "branch": {
+          "type": ["string", "null"]
+        },
+        "worktree_path": {
+          "type": ["string", "null"]
+        },
+        "head": {
+          "type": ["string", "null"]
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["safe", "review", "blocked", null]
+        },
+        "reason": {
+          "type": ["string", "null"]
+        },
+        "detached": {
+          "type": "boolean"
+        },
+        "selectable": {
+          "type": ["boolean", "null"]
+        }
+      }
+    }
+  }
+}

package/schemas/worktree-cleanup-preview.result.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sven1103-agent/opencode-worktree-plugin/schemas/worktree-cleanup-preview.result.schema.json",
+  "title": "worktree_cleanup preview result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "ok",
+    "mode",
+    "default_branch",
+    "base_branch",
+    "base_ref",
+    "groups"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "ok": {
+      "type": "boolean",
+      "const": true
+    },
+    "mode": {
+      "type": "string",
+      "const": "preview"
+    },
+    "default_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "groups": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["safe", "review", "blocked"],
+      "properties": {
+        "safe": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cleanupItem"
+          }
+        },
+        "review": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cleanupItem"
+          }
+        },
+        "blocked": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/cleanupItem"
+          }
+        }
+      }
+    },
+    "message": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "cleanupItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "branch",
+        "worktree_path",
+        "head",
+        "status",
+        "reason",
+        "detached",
+        "selectable"
+      ],
+      "properties": {
+        "branch": {
+          "type": ["string", "null"]
+        },
+        "worktree_path": {
+          "type": ["string", "null"]
+        },
+        "head": {
+          "type": ["string", "null"]
+        },
+        "status": {
+          "type": ["string", "null"],
+          "enum": ["safe", "review", "blocked", null]
+        },
+        "reason": {
+          "type": ["string", "null"]
+        },
+        "detached": {
+          "type": "boolean"
+        },
+        "selectable": {
+          "type": ["boolean", "null"]
+        }
+      }
+    }
+  }
+}

package/schemas/worktree-prepare.result.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sven1103-agent/opencode-worktree-plugin/schemas/worktree-prepare.result.schema.json",
+  "title": "worktree_prepare result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "ok",
+    "title",
+    "branch",
+    "worktree_path",
+    "default_branch",
+    "base_branch",
+    "base_ref",
+    "base_commit",
+    "created"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "ok": {
+      "type": "boolean",
+      "const": true
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "worktree_path": {
+      "type": "string",
+      "minLength": 1
+    },
+    "default_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_branch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "base_commit": {
+      "type": "string",
+      "minLength": 1
+    },
+    "created": {
+      "type": "boolean",
+      "const": true
+    },
+    "message": {
+      "type": "string"
+    }
+  }
+}

package/skills/worktree-workflow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: worktree-workflow
+description: Use this skill when you need to decide whether a task should move into a git worktree, when repo root is still safe, or when you need to choose between native worktree tools and the standard CLI fallback.
+---
+
+## When to use me
+
+- Use this skill when work should be isolated from the current checkout.
+- Use this skill when the task is substantial, risky, or likely to involve multiple collaborating agents.
+- Use this skill when you need to decide whether repo root is still safe for a tiny edit.
+- Use this skill when you need to choose the native worktree tools first and the packaged CLI fallback second.
+
+## Goals
+
+- Keep user work isolated from repo root when appropriate.
+- Prefer task-scoped worktrees for non-trivial editable work.
+- Support both native worktree tools and CLI fallback environments.
+- Keep policy in the skill and execution semantics in the package.
+
+## Root policy
+
+- Treat repo root as shared space.
+- Use repo root only for tiny, root-safe tasks.
+- Treat a task as root-safe only when it is one focused change, touches at most one or two closely related files, does not need parallel delegation, does not imply a likely edit-test-fix loop, does not involve risky refactoring or migration work, and does not risk interfering with unrelated dirty root state.
+
+## Task worktree policy
+
+- Prefer one task-scoped worktree for non-trivial editable work.
+- Treat a task worktree as belonging to a task or workstream, not to a single agent.
+- Keep planning, implementation, and review for one linear task in the same task worktree unless the work splits.
+- Create a separate divergent worktree only when concurrent branches of work may conflict or need independent experimentation.
+
+## Capability ladder
+
+- Use the native worktree tools as the primary path when the native worktree tools are available.
+- Use the packaged CLI fallback path when the native tools are unavailable.
+- Continue in repo root only for tiny, root-safe tasks when no worktree capability is available; otherwise stop and explain that isolation capability is unavailable.
+
+## Creation behavior
+
+- Use a short descriptive task title when creating a worktree.
+- Treat the returned `worktree_path` as the active execution target for follow-up work.
+- Use that worktree path as the working directory for later shell commands.
+- Use paths inside that worktree for later file reads or edits.
+
+## Cleanup behavior
+
+- Keep cleanup preview-first by default because cleanup is preview-first unless deletion is clearly intended.
+- Use cleanup apply only when deletion is clearly intended and controlled by the orchestrating runtime.
+- Treat slash commands as manual human entry points, not as the canonical agent interface.
+
+## Boundaries
+
+- Do not encode runtime storage, session artifact, or orchestration file-layout details here.
+- Do not duplicate package argument normalization or config parsing here.
+- Rely on the shared package implementation for config loading, base-branch resolution, cleanup normalization, and structured result semantics.
+
+## Examples
+
+- Move a risky refactor into a task-scoped worktree before editing multiple files and running several test-fix loops.
+- Stay in repo root for a tiny, root-safe doc fix that touches one related file and does not need delegation.
+- Prefer the native worktree tools first, then switch to the packaged CLI fallback path if the native tools are unavailable.

package/src/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { WorktreeWorkflowPlugin } from "./index.js";
+
+const execFileAsync = promisify(execFile);
+
+function shellEscape(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function createShell(cwdBase) {
+  const shell = (strings, ...values) => {
+    const [firstValue] = values;
+    const raw = firstValue?.raw || strings.raw?.join("") || strings.join("");
+    let cwd = cwdBase;
+
+    return {
+      cwd(nextCwd) {
+        cwd = nextCwd;
+        return this;
+      },
+      quiet() {
+        return this;
+      },
+      async nothrow() {
+        try {
+          const result = await execFileAsync("sh", ["-lc", raw], { cwd });
+          return {
+            text() {
+              return result.stdout;
+            },
+            stderr: Buffer.from(result.stderr),
+            exitCode: 0,
+          };
+        } catch (error) {
+          return {
+            text() {
+              return error.stdout || "";
+            },
+            stderr: Buffer.from(error.stderr || ""),
+            exitCode: typeof error.code === "number" ? error.code : 1,
+          };
+        }
+      },
+    };
+  };
+
+  shell.escape = shellEscape;
+  return shell;
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      "Usage:",
+      "  opencode-worktree-workflow wt-new <title> [--json]",
+      "  opencode-worktree-workflow wt-clean [preview|apply] [selectors...] [--json]",
+      "",
+      "Examples:",
+      "  opencode-worktree-workflow wt-new \"Improve checkout retry logic\"",
+      "  opencode-worktree-workflow wt-clean preview",
+      "  opencode-worktree-workflow wt-clean apply feature/foo",
+    ].join("\n") + "\n",
+  );
+}
+
+function printSubcommandUsage(command) {
+  if (command === "wt-new") {
+    process.stdout.write(
+      [
+        "Usage:",
+        "  opencode-worktree-workflow wt-new <title> [--json]",
+        "",
+        "Create a synced worktree and branch from the configured base branch.",
+      ].join("\n") + "\n",
+    );
+    return;
+  }
+
+  if (command === "wt-clean") {
+    process.stdout.write(
+      [
+        "Usage:",
+        "  opencode-worktree-workflow wt-clean [preview|apply] [selectors...] [--json]",
+        "",
+        "Preview connected worktrees or remove safe and explicitly selected review worktrees.",
+      ].join("\n") + "\n",
+    );
+  }
+}
+
+export function parseCliArgs(argv) {
+  const outputJson = argv.includes("--json");
+  const args = argv.filter((arg) => arg !== "--json");
+  return { outputJson, args };
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const { outputJson, args } = parseCliArgs(argv);
+  const [command, ...rest] = args;
+
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    printUsage();
+    process.exitCode = command ? 0 : 1;
+    return;
+  }
+
+  if ((command === "wt-new" || command === "wt-clean") && rest.some((arg) => arg === "--help" || arg === "-h" || arg === "help")) {
+    printSubcommandUsage(command);
+    return;
+  }
+
+  const plugin = await WorktreeWorkflowPlugin({
+    $: createShell(process.cwd()),
+    directory: process.cwd(),
+  });
+
+  let result;
+
+  if (command === "wt-new") {
+    const title = rest.join(" ").trim();
+
+    if (!title) {
+      throw new Error("wt-new requires a descriptive title.");
+    }
+
+    result = await plugin.tool.worktree_prepare.execute(
+      { title },
+      { metadata() {}, worktree: process.cwd() },
+    );
+  } else if (command === "wt-clean") {
+    const raw = rest.join(" ").trim();
+    result = await plugin.tool.worktree_cleanup.execute(
+      { raw, selectors: [] },
+      { metadata() {}, worktree: process.cwd() },
+    );
+  } else {
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  if (outputJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`${result.message || JSON.stringify(result, null, 2)}\n`);
+}
+
+export function isInvokedAsScript(argvPath = process.argv[1]) {
+  if (!argvPath) {
+    return false;
+  }
+
+  try {
+    return fs.realpathSync(argvPath) === fileURLToPath(import.meta.url);
+  } catch {
+    return fileURLToPath(import.meta.url) === argvPath;
+  }
+}
+
+const invokedAsScript = isInvokedAsScript();
+
+if (invokedAsScript) {
+  run().catch((error) => {
+    process.stderr.write(`${error.message || String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/index.js

@@ -13,6 +13,8 @@ const DEFAULTS = {
   protectedBranches: [],
 };
 
+const RESULT_SCHEMA_VERSION = "1.0.0";
+
 async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -22,6 +24,14 @@ async function pathExists(targetPath) {
   }
 }
 
+function isMissingGitRepositoryError(message) {
+  return /not a git repository/i.test(message);
+}
+
+function isMissingRemoteError(message, remote) {
+  return new RegExp(`No such remote:?\s+${remote}|does not appear to be a git repository|Could not read from remote repository`, "i").test(message);
+}
+
 async function readJsonFile(filePath) {
   if (!(await pathExists(filePath))) {
     return null;
@@ -163,6 +173,18 @@ function formatPreview(grouped, defaultBranch) {
   ].join("\n");
 }
 
+function formatPrepareSummary(result) {
+  return [
+    `Created worktree for "${result.title}".`,
+    `- branch: ${result.branch}`,
+    `- worktree: ${result.worktree_path}`,
+    `- default branch: ${result.default_branch}`,
+    `- base branch: ${result.base_branch}`,
+    `- base ref: ${result.base_ref}`,
+    `- base commit: ${result.base_commit}`,
+  ].join("\n");
+}
+
 function formatCleanupSummary(defaultBranch, removed, failed, requestedSelectors) {
   const lines = [`Cleaned worktrees relative to ${defaultBranch}:`];
 
@@ -194,6 +216,88 @@ function formatCleanupSummary(defaultBranch, removed, failed, requestedSelectors
   return lines.join("\n");
 }
 
+function toStructuredCleanupItem(item) {
+  return {
+    branch: item.branch ?? null,
+    worktree_path: item.path ?? item.worktree_path ?? null,
+    head: item.head ?? null,
+    status: item.status ?? null,
+    reason: item.reason ?? null,
+    detached: Boolean(item.detached),
+    selectable: typeof item.selectable === "boolean" ? item.selectable : null,
+  };
+}
+
+function toStructuredCleanupFailure(item) {
+  return {
+    selector: item.selector ?? null,
+    branch: item.branch ?? null,
+    worktree_path: item.path ?? item.worktree_path ?? null,
+    head: item.head ?? null,
+    status: item.status ?? null,
+    reason: item.reason ?? null,
+    detached: Boolean(item.detached),
+    selectable: typeof item.selectable === "boolean" ? item.selectable : null,
+  };
+}
+
+function buildPrepareResult({ title, branch, worktreePath, defaultBranch, baseBranch, baseRef, baseCommit }) {
+  const result = {
+    schema_version: RESULT_SCHEMA_VERSION,
+    ok: true,
+    title,
+    branch,
+    worktree_path: worktreePath,
+    default_branch: defaultBranch,
+    base_branch: baseBranch,
+    base_ref: baseRef,
+    base_commit: baseCommit,
+    created: true,
+  };
+
+  return {
+    ...result,
+    message: formatPrepareSummary(result),
+  };
+}
+
+function buildCleanupPreviewResult({ defaultBranch, baseBranch, baseRef, grouped }) {
+  const structuredGroups = {
+    safe: grouped.safe.map(toStructuredCleanupItem),
+    review: grouped.review.map(toStructuredCleanupItem),
+    blocked: grouped.blocked.map(toStructuredCleanupItem),
+  };
+
+  return {
+    schema_version: RESULT_SCHEMA_VERSION,
+    ok: true,
+    mode: "preview",
+    default_branch: defaultBranch,
+    base_branch: baseBranch,
+    base_ref: baseRef,
+    groups: structuredGroups,
+    message: formatPreview(grouped, baseBranch),
+  };
+}
+
+function buildCleanupApplyResult({ defaultBranch, baseBranch, baseRef, removed, failed, requestedSelectors }) {
+  return {
+    schema_version: RESULT_SCHEMA_VERSION,
+    ok: true,
+    mode: "apply",
+    default_branch: defaultBranch,
+    base_branch: baseBranch,
+    base_ref: baseRef,
+    requested_selectors: requestedSelectors,
+    removed: removed.map((item) => ({
+      ...toStructuredCleanupItem(item),
+      selected: Boolean(item.selected),
+    })),
+    failed: failed.map(toStructuredCleanupFailure),
+    message: formatCleanupSummary(baseBranch, removed, failed, requestedSelectors),
+  };
+}
+
 function splitCleanupToken(value) {
   if (typeof value !== "string") {
     return [];
@@ -275,8 +379,17 @@ function normalizeCleanupArgs(args, config) {
 }
 
 export const __internal = {
+  RESULT_SCHEMA_VERSION,
+  buildCleanupApplyResult,
+  buildCleanupPreviewResult,
+  buildPrepareResult,
+  classifyEntry,
+  isMissingGitRepositoryError,
+  isMissingRemoteError,
   parseCleanupRawArguments,
   normalizeCleanupArgs,
+  toStructuredCleanupFailure,
+  toStructuredCleanupItem,
 };
 
 function selectorMatches(item, selector) {
@@ -367,8 +480,18 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   }
 
   async function getRepoRoot() {
-    const result = await git(["rev-parse", "--show-toplevel"]);
-    return result.stdout;
+    try {
+      const result = await git(["rev-parse", "--show-toplevel"]);
+      return result.stdout;
+    } catch (error) {
+      if (isMissingGitRepositoryError(error.message || "")) {
+        throw new Error(
+          "This command must run inside a git repository. Initialize a repository first or run it from an existing repo root.",
+        );
+      }
+
+      throw error;
+    }
   }
 
   async function loadWorkflowConfig(repoRoot) {
@@ -454,7 +577,17 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   }
 
   async function getBaseRef(repoRoot, remote, baseBranch) {
-    await git(["fetch", "--prune", remote, baseBranch], { cwd: repoRoot });
+    try {
+      await git(["fetch", "--prune", remote, baseBranch], { cwd: repoRoot });
+    } catch (error) {
+      if (isMissingRemoteError(error.message || "", remote)) {
+        throw new Error(
+          `Could not fetch base branch information from remote \"${remote}\". Configure the expected remote in .opencode/worktree-workflow.json or add that remote to this repository.`,
+        );
+      }
+
+      throw error;
+    }
 
     const remoteRef = `refs/remotes/${remote}/${baseBranch}`;
     const remoteExists = await git(["show-ref", "--verify", "--quiet", remoteRef], {
@@ -529,15 +662,15 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             );
           }
 
-          return [
-            `Created worktree for \"${args.title}\".`,
-            `- branch: ${branchName}`,
-            `- worktree: ${worktreePath}`,
-            `- default branch: ${defaultBranch}`,
-            `- base branch: ${baseBranch}`,
-            `- base ref: ${baseRef}`,
-            `- base commit: ${baseCommit}`,
-          ].join("\n");
+          return buildPrepareResult({
+            title: args.title,
+            branch: branchName,
+            worktreePath,
+            defaultBranch,
+            baseBranch,
+            baseRef,
+            baseCommit,
+          });
         },
       }),
       worktree_cleanup: tool({
@@ -593,7 +726,12 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           }
 
           if (normalizedArgs.mode !== "apply") {
-            return formatPreview(grouped, baseBranch);
+            return buildCleanupPreviewResult({
+              defaultBranch,
+              baseBranch,
+              baseRef,
+              grouped,
+            });
           }
 
           const requestedSelectors = [...new Set(normalizedArgs.selectors || [])];
@@ -622,7 +760,10 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
               continue;
             }
 
-            selected.push(match);
+            selected.push({
+              ...match,
+              selector,
+            });
           }
 
           const targets = [...grouped.safe];
@@ -631,6 +772,7 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             if (!targets.some((target) => target.path === item.path)) {
               targets.push({
                 ...item,
+                selector: item.selector ?? null,
                 selected: true,
               });
             }
@@ -676,7 +818,14 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             allowFailure: true,
           });
 
-          return formatCleanupSummary(baseBranch, removed, failed, requestedSelectors);
+          return buildCleanupApplyResult({
+            defaultBranch,
+            baseBranch,
+            baseRef,
+            removed,
+            failed,
+            requestedSelectors,
+          });
         },
       }),
     },