@sven1103/opencode-worktree-workflow 0.6.2 → 1.0.0-alpha.1

package/README.md

@@ -12,6 +12,22 @@ To get the workflow running in a project:
 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).
 
+## Verify installation
+
+After setup, verify the surface you installed:
+
+- Plugin: confirm OpenCode exposes `worktree_prepare` and `worktree_cleanup`.
+- CLI: run `npx opencode-worktree-workflow --help`.
+- Slash commands: confirm `/wt-new <title>` and `/wt-clean` are available.
+
+Quick smoke check:
+
+```sh
+npx opencode-worktree-workflow wt-new "docs smoke check" --json
+```
+
+That should return a structured result with a `worktree_path`. For release verification before installing, see `docs/releases.md`.
+
 ## Recommended setup
 
 Install the package once:
@@ -146,12 +162,55 @@ If your setup uses installed skill files, copy the released `SKILL.md` into a `w
 ## 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
+- `worktree_cleanup`: preview connected worktrees against the configured base branch and, when explicitly applied, remove safe or selected review items
 
 This package now ships the plugin capability, a CLI fallback surface, thin slash commands, and a co-shipped policy skill.
 
 These native tools are exposed inside OpenCode after the plugin is loaded. They are not terminal commands.
 
+## Lifecycle hooks (determinism)
+
+If you use this plugin in autonomous agent tasks, the key feature is that it uses OpenCode lifecycle hooks to make workspace selection deterministic.
+
+Hooks implemented by the plugin:
+
+- `tool.execute.before`
+  - Enforces isolation for repo-mutating tools by ensuring a session-scoped active worktree exists (requires `sessionID`).
+  - Rewrites tool inputs so they operate inside the active worktree by default:
+    - `bash`: injects `workdir`/`cwd` when missing
+    - `glob`/`grep`: injects `path` when missing
+    - known path arguments are rewritten from repo-root paths into the bound `worktree_path`
+  - Blocks unsafe calls that cannot be rewritten safely (for example repo-root absolute paths in opaque arguments).
+  - For delegated `task` calls: requires the prompt to reference a safe handoff artifact path under `.opencode/sessions/<session>/handoffs/*.json`, then enriches that handoff with the active workspace context (`task_id`, `worktree_path`, `workspace_role`).
+
+- `tool.execute.after`
+  - Records tool usage for the session (used to keep runtime state and cleanup advice consistent across steps).
+  - After a delegated `task`, correlates the handoff with result artifacts to infer lifecycle transitions (complete/block) and persists them.
+  - When completion is detected, emits an advisory cleanup preview (non-fatal if it cannot be generated).
+
+- `experimental.chat.system.transform`
+  - Injects an "Active workspace context" block into the system prompt when an active worktree is bound, so agents and tools see the same worktree context every step.
+
+- `command.execute.before`
+  - Implements `/wt-new` and `/wt-clean` as thin prompt shims (it rewrites the command output parts so the agent calls `worktree_prepare` / `worktree_cleanup`).
+
+Net effect: once a `sessionID` is in play, the plugin keeps a stable session-to-worktree binding and consistently routes repository actions into that worktree. This removes prompt-only ambiguity ("did the agent remember to cd?") and is what makes the workflow reproducible.
+
+## Typical usage
+
+Most users only need one of these flows:
+
+1. Plugin only: use `worktree_prepare` and `worktree_cleanup` directly in OpenCode.
+2. Plugin plus slash commands: use `/wt-new <title>` to start isolated work and `/wt-clean` to preview cleanup.
+3. CLI fallback: use `npx opencode-worktree-workflow wt-new "<title>"` when native tools are unavailable.
+
+Typical manual flow:
+
+1. Create a worktree with `worktree_prepare`, `/wt-new <title>`, or `npx opencode-worktree-workflow wt-new "<title>"`.
+2. Do the task inside the returned `worktree_path`.
+3. Preview cleanup with `worktree_cleanup`, `/wt-clean`, or `npx opencode-worktree-workflow wt-clean preview`.
+4. Apply cleanup only when deletion is intentional.
+
 ## Structured contract
 
 The package now exposes a versioned structured contract with a `schema_version` field. Native tools return human-readable text and publish the structured result in tool metadata, while CLI `--json` prints the same structured object directly.
@@ -240,6 +299,20 @@ Supported settings:
 - `cleanupMode`: default cleanup behavior, either `preview` or `apply`
 - `protectedBranches`: branches that should never be auto-cleaned
 
+## Uninstall
+
+Remove only the surfaces you installed:
+
+- npm package: `npm remove @sven1103/opencode-worktree-workflow`
+- OpenCode plugin entry: remove `@sven1103/opencode-worktree-workflow` from `opencode.json`
+- Slash commands: delete `wt-new.md` and `wt-clean.md` from `.opencode/commands/` or `~/.config/opencode/commands/`
+- Skill: delete `SKILL.md` from your `worktree-workflow/` skill folder
+
+Optional cleanup:
+
+- remove `.opencode/worktree-workflow.json` if you created it only for this plugin
+- remove persisted runtime state from `OPENCODE_WORKTREE_STATE_DIR` or the platform default state directory if you no longer want stored task bindings
+
 ## Publish workflow
 
 This repo is prepared for npm publishing from GitHub Actions using npm trusted publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sven1103/opencode-worktree-workflow",
-  "version": "0.6.2",
+  "version": "1.0.0-alpha.1",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",

package/skills/worktree-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use this skill when working on changes that should be isolated from the main repo, such as refactoring multiple files, making risky edits, experimenting, creating parallel work (like branches or worktrees), or when you are unsure whether it is safe to edit directly in the repo root. Use it when you are orchestrating tasks for implementation and review. Not needed for small, simple one-file edits.
 ---
 
 ## When to use me
@@ -49,6 +49,27 @@ description: Use this skill when you need to decide whether a task should move i
 - 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.
 
+## Result reporting
+
+- Always surface the concrete outcome of worktree operations to the user.
+- Do not summarize away important details.
+
+When a worktree is created, include:
+- The worktree path
+- The branch name (if created or used)
+- The base branch
+- Whether it was newly created or reused
+
+When cleanup is run:
+- Show the preview or the list of affected worktrees
+- Clearly distinguish preview vs applied changes
+
+When commands are executed inside a worktree:
+- Mention that the worktree path is the active working directory
+- Include relevant command results (status, diff summary, errors)
+
+Prefer structured, explicit output over vague summaries.
+
 ## Boundaries
 
 - Do not encode runtime storage, session artifact, or orchestration file-layout details here.

package/src/cli.js

@@ -5,7 +5,8 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
-import { WorktreeWorkflowPlugin } from "./index.js";
+import { createWorktreeWorkflowService } from "./core/worktree-service.js";
+import { createRuntimeStateStore } from "./runtime/state-store.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -115,21 +116,26 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const plugin = await WorktreeWorkflowPlugin({
-    $: createShell(process.cwd()),
+  const shell = createShell(process.cwd());
+  const git = async (args, options = {}) => {
+    const cwd = options.cwd ?? process.cwd();
+    const command = `git ${args.map((arg) => shell.escape(String(arg))).join(" ")}`;
+    const result = await shell`${{ raw: command }}`.cwd(cwd).quiet().nothrow();
+    const stdout = result.text().trim();
+    const stderr = result.stderr.toString("utf8").trim();
+    if (!options.allowFailure && result.exitCode !== 0) {
+      throw new Error(stderr || stdout || `Git command failed: ${command}`);
+    }
+    return { stdout, stderr, exitCode: result.exitCode };
+  };
+  const service = createWorktreeWorkflowService({
     directory: process.cwd(),
+    git,
+    stateStore: createRuntimeStateStore(),
   });
 
   let result;
   let structuredResult = null;
-  const toolContext = {
-    metadata(input) {
-      if (input?.metadata?.result) {
-        structuredResult = input.metadata.result;
-      }
-    },
-    worktree: process.cwd(),
-  };
 
   if (command === "wt-new") {
     const title = rest.join(" ").trim();
@@ -138,10 +144,12 @@ export async function run(argv = process.argv.slice(2)) {
       throw new Error("wt-new requires a descriptive title.");
     }
 
-    result = await plugin.tool.worktree_prepare.execute({ title }, toolContext);
+    structuredResult = await service.prepare({ title, sessionID: "cli" });
+    result = structuredResult.message;
   } else if (command === "wt-clean") {
     const raw = rest.join(" ").trim();
-    result = await plugin.tool.worktree_cleanup.execute({ raw, selectors: [] }, toolContext);
+    structuredResult = await service.cleanup({ raw, selectors: [], worktree: process.cwd(), sessionID: "cli" });
+    result = structuredResult.message;
   } else {
     throw new Error(`Unknown command: ${command}`);
   }

package/src/core/task-binding.js

@@ -0,0 +1,154 @@
+import path from "node:path";
+
+export function decideContinuity({ hasActiveTask = false, continuationSignal = false, distinctObjectiveSignal = false, alternativeRequested = false, ambiguous = false } = {}) {
+  if (!hasActiveTask) {
+    return { decision: "create-new", reason: "no-active-task" };
+  }
+
+  if (distinctObjectiveSignal || alternativeRequested) {
+    return { decision: "create-new", reason: alternativeRequested ? "alternative-requested" : "distinct-objective" };
+  }
+
+  if (ambiguous) {
+    return { decision: "ask-user", reason: "ambiguous-continuity" };
+  }
+
+  if (continuationSignal) {
+    return { decision: "reuse-active", reason: "clear-continuation" };
+  }
+
+  return { decision: "ask-user", reason: "insufficient-signal" };
+}
+
+export function inferTaskLifecycleTransition({ currentStatus = "inactive", explicitSignal = "none" } = {}) {
+  if (explicitSignal === "activate") return "active";
+  if (explicitSignal === "deactivate") return "inactive";
+  if (explicitSignal === "complete") return "completed";
+  if (explicitSignal === "block") return "blocked";
+  return currentStatus;
+}
+
+const READ_ONLY_TOOLS = new Set(["read", "glob", "grep", "webfetch"]);
+const WORKTREE_CONTROL_TOOLS = new Set(["worktree_prepare", "worktree_cleanup"]);
+const MUTATING_TOOLS = new Set(["write", "edit", "apply_patch"]);
+const WORKSPACE_ROLES = new Set(["planner", "implementer", "reviewer", "linear-flow"]);
+const READ_ONLY_GIT_COMMAND = /^\s*git\s+(status|diff|log|show|rev-parse|symbolic-ref|branch\s+--show-current|remote\s+show)\b/i;
+
+export function classifyToolExecution({ toolName, args = {} } = {}) {
+  const name = typeof toolName === "string" ? toolName : "";
+  if (WORKTREE_CONTROL_TOOLS.has(name)) return { requiresIsolation: false, bypass: true, kind: "worktree-control" };
+  if (READ_ONLY_TOOLS.has(name)) return { requiresIsolation: false, bypass: false, kind: "read-only" };
+  if (name === "task") return { requiresIsolation: true, bypass: false, kind: "delegation" };
+  if (MUTATING_TOOLS.has(name)) return { requiresIsolation: true, bypass: false, kind: "mutating" };
+  if (name === "bash") {
+    const command = typeof args.command === "string" ? args.command : "";
+    if (READ_ONLY_GIT_COMMAND.test(command)) return { requiresIsolation: false, bypass: false, kind: "read-only" };
+    return { requiresIsolation: true, bypass: false, kind: "mutating" };
+  }
+  return { requiresIsolation: true, bypass: false, kind: "unknown" };
+}
+
+export function deriveTaskTitle({ explicitTitle, toolName, args = {}, sessionID } = {}) {
+  if (typeof explicitTitle === "string" && explicitTitle.trim()) return explicitTitle.trim();
+  if (typeof args.title === "string" && args.title.trim()) return args.title.trim();
+  if (typeof args.prompt === "string" && args.prompt.trim()) return args.prompt.trim().slice(0, 80);
+  if (typeof args.description === "string" && args.description.trim()) return args.description.trim().slice(0, 80);
+  const shortID = typeof sessionID === "string" && sessionID ? sessionID.slice(0, 8) : "auto";
+  if (typeof toolName === "string" && toolName) return `${toolName}-${shortID}`;
+  return `task-${shortID}`;
+}
+
+export function deriveWorkspaceRole({ subagentType } = {}) {
+  if (typeof subagentType !== "string") return "linear-flow";
+  const normalized = subagentType.trim().toLowerCase();
+  return WORKSPACE_ROLES.has(normalized) ? normalized : "linear-flow";
+}
+
+export function extractHandoffArtifactPath(prompt) {
+  if (typeof prompt !== "string" || !prompt.trim()) return null;
+  const match = prompt.match(/(?:^|\s)(\/?[^\s]*\.opencode\/sessions\/[A-Za-z0-9_-]+\/handoffs\/[A-Za-z0-9._-]+\.json)(?:\s|$)/);
+  return match?.[1] ?? null;
+}
+
+export function buildWorkspaceContext({ task, workspaceRole } = {}) {
+  return {
+    task_id: task?.task_id ?? null,
+    task_title: task?.title ?? null,
+    worktree_path: task?.worktree_path ?? null,
+    workspace_role: workspaceRole || "linear-flow",
+    lifecycle_state: task?.status ?? "active",
+  };
+}
+
+const REWRITE_POLICIES = {
+  read: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  write: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  edit: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  glob: { pathArgKeys: ["path"], opaqueArgKeys: [] },
+  grep: { pathArgKeys: ["path"], opaqueArgKeys: [] },
+  bash: { pathArgKeys: ["workdir", "cwd"], opaqueArgKeys: ["command"] },
+  apply_patch: { pathArgKeys: [], opaqueArgKeys: ["patchText"] },
+};
+
+export function getToolRewritePolicy({ toolName } = {}) {
+  return REWRITE_POLICIES[toolName] || { pathArgKeys: [], opaqueArgKeys: [] };
+}
+
+function isInsideRepoRoot(candidatePath, repoRoot) {
+  const relative = path.relative(repoRoot, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isInsideWorktree(candidatePath, worktreePath) {
+  const relative = path.relative(worktreePath, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function rewriteRepoScopedPathIntoWorktree({ value, repoRoot, worktreePath } = {}) {
+  if (typeof value !== "string" || !value.trim()) return value;
+  const normalizedRepoRoot = path.resolve(repoRoot);
+  const normalizedWorktreePath = path.resolve(worktreePath);
+  if (!path.isAbsolute(value)) return path.join(normalizedWorktreePath, value);
+  const resolvedValue = path.resolve(value);
+  if (isInsideWorktree(resolvedValue, normalizedWorktreePath)) return resolvedValue;
+  if (!isInsideRepoRoot(resolvedValue, normalizedRepoRoot)) return value;
+  const relative = path.relative(normalizedRepoRoot, resolvedValue);
+  return relative ? path.join(normalizedWorktreePath, relative) : normalizedWorktreePath;
+}
+
+function isBoundaryChar(char) {
+  if (!char) return true;
+  return /[\s"'`()[\]{}<>,:;=]/.test(char) || char === "/" || char === "\\";
+}
+
+export function hasOpaqueRepoRootAbsoluteReference({ value, repoRoot } = {}) {
+  if (typeof value !== "string" || !value) return false;
+  const normalizedRepoRoot = path.resolve(repoRoot).replaceAll("\\", "/");
+  const normalizedValue = value.replaceAll("\\", "/");
+  let index = normalizedValue.indexOf(normalizedRepoRoot);
+  while (index !== -1) {
+    const before = index > 0 ? normalizedValue[index - 1] : "";
+    const after = normalizedValue[index + normalizedRepoRoot.length] || "";
+    if (isBoundaryChar(before) && isBoundaryChar(after)) return true;
+    index = normalizedValue.indexOf(normalizedRepoRoot, index + 1);
+  }
+  return false;
+}
+
+export function buildWtNewCommandPromptParts(argumentsText = "") {
+  const title = typeof argumentsText === "string" ? argumentsText.trim() : "";
+  if (!title) {
+    return [{ type: "text", text: "Usage: /wt-new <title>\nExample: /wt-new improve checkout retry logic" }];
+  }
+  return [
+    {
+      type: "text",
+      text: `Call worktree_prepare with ${JSON.stringify({ title })}. Return the tool result and treat its worktree_path as the active workspace for follow-up work.`,
+    },
+  ];
+}
+
+export function buildWtCleanCommandPromptParts(argumentsText = "") {
+  const raw = typeof argumentsText === "string" ? argumentsText : "";
+  return [{ type: "text", text: `Call worktree_cleanup with ${JSON.stringify({ raw })}. Return the tool result.` }];
+}