@sven1103/opencode-worktree-workflow 0.6.1 → 0.6.3

package/README.md

@@ -42,6 +42,11 @@ In practice:
 - 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
 
+Important distinction:
+
+- `worktree_prepare` and `worktree_cleanup` are native OpenCode tools, not shell commands
+- from a terminal, use `npx opencode-worktree-workflow ...` or `./node_modules/.bin/opencode-worktree-workflow ...`
+
 ## Install in an OpenCode project
 
 Add the package as a project dependency, following the official docs style:
@@ -145,9 +150,11 @@ If your setup uses installed skill files, copy the released `SKILL.md` into a `w
 
 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.
+
 ## Structured contract
 
-The native tool results and CLI `--json` output now use a versioned structured contract with a `schema_version` field.
+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.
 
 - current `schema_version`: `1.0.0`
 - contract overview: `docs/contract.md`
@@ -163,21 +170,33 @@ Human-readable output remains available through the result `message`, but caller
 
 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.
 
+Use the CLI from a terminal when you want to run the workflow manually. Run it inside a real git repository. By default, the workflow expects a normal remote and base-branch setup such as `origin` plus the repository default branch, unless you override that in `.opencode/worktree-workflow.json`.
+
 Examples:
 
 ```sh
+npx opencode-worktree-workflow --help
+npx opencode-worktree-workflow wt-clean --help
 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
 ```
 
+Direct local bin examples:
+
+```sh
+./node_modules/.bin/opencode-worktree-workflow --help
+./node_modules/.bin/opencode-worktree-workflow wt-clean preview
+```
+
 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
+- if you run it outside a git repo or without the expected remote context, the CLI returns an actionable error
 
 ## Compatibility model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sven1103/opencode-worktree-workflow",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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

@@ -121,6 +121,15 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   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();
@@ -129,26 +138,20 @@ 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 },
-      { metadata() {}, worktree: process.cwd() },
-    );
+    result = await plugin.tool.worktree_prepare.execute({ title }, toolContext);
   } else if (command === "wt-clean") {
     const raw = rest.join(" ").trim();
-    result = await plugin.tool.worktree_cleanup.execute(
-      { raw, selectors: [] },
-      { metadata() {}, worktree: process.cwd() },
-    );
+    result = await plugin.tool.worktree_cleanup.execute({ raw, selectors: [] }, toolContext);
   } else {
     throw new Error(`Unknown command: ${command}`);
   }
 
   if (outputJson) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(structuredResult ?? { ok: true, message: result }, null, 2)}\n`);
     return;
   }
 
-  process.stdout.write(`${result.message || JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${result}\n`);
 }
 
 export function isInvokedAsScript(argvPath = process.argv[1]) {

package/src/index.js

@@ -261,6 +261,16 @@ function buildPrepareResult({ title, branch, worktreePath, defaultBranch, baseBr
   };
 }
 
+function publishStructuredResult(context, result) {
+  context.metadata({
+    metadata: {
+      result,
+    },
+  });
+
+  return result.message || JSON.stringify(result, null, 2);
+}
+
 function buildCleanupPreviewResult({ defaultBranch, baseBranch, baseRef, grouped }) {
   const structuredGroups = {
     safe: grouped.safe.map(toStructuredCleanupItem),
@@ -662,15 +672,18 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             );
           }
 
-          return buildPrepareResult({
-            title: args.title,
-            branch: branchName,
-            worktreePath,
-            defaultBranch,
-            baseBranch,
-            baseRef,
-            baseCommit,
-          });
+          return publishStructuredResult(
+            context,
+            buildPrepareResult({
+              title: args.title,
+              branch: branchName,
+              worktreePath,
+              defaultBranch,
+              baseBranch,
+              baseRef,
+              baseCommit,
+            }),
+          );
         },
       }),
       worktree_cleanup: tool({
@@ -726,12 +739,15 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           }
 
           if (normalizedArgs.mode !== "apply") {
-            return buildCleanupPreviewResult({
-              defaultBranch,
-              baseBranch,
-              baseRef,
-              grouped,
-            });
+            return publishStructuredResult(
+              context,
+              buildCleanupPreviewResult({
+                defaultBranch,
+                baseBranch,
+                baseRef,
+                grouped,
+              }),
+            );
           }
 
           const requestedSelectors = [...new Set(normalizedArgs.selectors || [])];
@@ -818,14 +834,17 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             allowFailure: true,
           });
 
-          return buildCleanupApplyResult({
-            defaultBranch,
-            baseBranch,
-            baseRef,
-            removed,
-            failed,
-            requestedSelectors,
-          });
+          return publishStructuredResult(
+            context,
+            buildCleanupApplyResult({
+              defaultBranch,
+              baseBranch,
+              baseRef,
+              removed,
+              failed,
+              requestedSelectors,
+            }),
+          );
         },
       }),
     },