fix: embed workflow descriptions in tool description instead of .describe()

mrsimpson · mrsimpson · commit 1bf74b1d6110 · 2026-05-07T20:45:33.000+02:00
OpenCode does not propagate Zod parameter .describe() text to the LLM.
Confirmed by canary test - descriptions are invisible regardless of zod
instance or registry. The tool description IS propagated, so embed the
workflow enum choices and their descriptions there directly.

Also removes the tool.definition hook and globalRegistry bridging code
which were solving the wrong problem.
diff --git a/.vibe/development-plan-fix-opencode-plugin-parameter-descriptions.md b/.vibe/development-plan-fix-opencode-plugin-parameter-descriptions.md
@@ -161,12 +161,21 @@ The core challenge: from within the plugin, we needed a reference to OpenCode's
 
 ### Final Working Solution
 
-Dynamic `import('zod')` in the `tool.definition` hook + `globalRegistry.add()` for each field schema:
-- Works because in production (peerDep, no local copy) the import resolves to host's zod module cache
-- `output.parameters._zod.def.shape` gives access to the original plugin field schemas
-- `fieldSchema.description` reads from plugin's registry cross-instance (it's just a getter calling `core.globalRegistry.get(inst)`)
-- `hostRegistry.add(fieldSchema, { description })` makes the SAME schema object findable in host's registry
-- All 64 tests pass
+**Embed workflow descriptions in the tool `description` string** (not in `.describe()` on the arg schema).
+
+All previous approaches (`globalRegistry` bridging, `tool.definition` hook, dynamic zod import) were abandoned after confirming via LLM inspection that OpenCode **never propagates Zod parameter `.describe()` text to the LLM at all** — confirmed by embedding a canary string `DESCRIPTION_TEST_CANARY_12345` via `.describe()` which was invisible to the LLM even after a fresh session.
+
+The tool `description` field IS propagated. Fix: embed the workflow enum descriptions directly there:
+```
+Start a development workflow.
+
+workflow parameter — available values:
+  - epcc: EPCC — <description>
+  - bugfix: Bugfix — <description>
+  - custom: Use a custom workflow name
+```
+
+All 286 tests pass. `generateWorkflowDescription()` import removed from `start-development.ts` (no longer needed). `tool.definition` hook removed from `plugin.ts`. `.describe()` calls on args left in place (harmless).
 
 ## Implementation Plan (Code Phase Tasks)
 
diff --git a/opencode/opencode.json b/opencode/opencode.json
@@ -0,0 +1,130 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "@ex-machina/opencode-anthropic-auth@1.8.0",
+    "/Users/oliverjaegle/projects/privat/codemcp/workflows/packages/opencode-plugin/dist/index.js"
+  ],
+  "provider": {
+    "@ai-sdk/openai-compatible": {
+      "name": "llama.cpp",
+      "options": {
+        "baseURL": "http://flinker:8080/v1"
+      },
+      "models": {
+        "Qwen3-Coder-30B-A3B-Instruct-UD-Q8_K_XL.gguf": {
+          "name": "Qwen3-Coder"
+        },
+        "gpt-oss-120b-F16.gguf": {
+          "name": "gpt-oss-120b"
+        },
+        "devstral2-small": {
+          "name": "Devstral-Small-2-24B-Instruct-2512-UD-Q8_K_XL.gguf"
+        }
+      }
+    }
+  },
+  "mcp": {
+    "workflows": {
+      "command": ["npx", "@codemcp/workflows@latest"],
+      "type": "local",
+      "environment": {
+        "COMMIT_BEHAVIOR": "end"
+      },
+      "enabled": false
+    },
+    "knowledge": {
+      "command": ["npx", "@codemcp/knowledge@latest"],
+      "type": "local"
+    },
+    "quiet_shell": {
+      "command": ["npx", "@codemcp/quiet-shell@latest"],
+      "type": "local",
+      "enabled": true
+    },
+    "prompts": {
+      "command": ["npx", "@codemcp/prompts@latest"],
+      "type": "local"
+    },
+    "crowd-mcp-local": {
+      "command": [
+        "node",
+        "/Users/oliverjaegle/projects/privat/mcp-server/crowd/packages/server/dist/index.js"
+      ],
+      "environment": {
+        "CROWD_DEMO_MODE": "true",
+        "OPERATOR_NAME": "Oliver",
+        "CROWD_LOG_LEVEL": "WARN"
+      },
+      "type": "local",
+      "enabled": false
+    },
+    "kinderspiel": {
+      "command": ["npx", "@codemcp/workflows@latest"],
+      "type": "local",
+      "enabled": false,
+      "environment": {
+        "VIBE_WORKFLOW_DOMAINS": "children"
+      }
+    }
+  },
+  "permission": {
+    "proceed_to_phase": "ask"
+  },
+  "agent": {
+    "vibe": {
+      "description": "Responsible vibe development agent with structured workflows",
+      "mode": "primary",
+      "prompt": "IMPORTANT: ALWAYS use whats_next after every user message to determine the next steps.\n Follow the instructions you get from whats_next exactly!\nIMPORTANT: You may also receive errors. Those errors also contain instructions how to proceed. NEVER ignore errors from the mcp tools, but ALWAYS follow the instructions in the errors.\n",
+      "tools": { "workflows": true },
+      "permission": {
+        "workflows_reset_development": "ask",
+        "workflows_start_development": "ask",
+        "workflows_proceed_to_phase": "ask"
+      }
+    },
+    "crowd": {
+      "description": "Manages subagents",
+      "mode": "primary",
+      "prompt": "You are a development project lead for software development projects. Use spawn_agent tool to employ agents for a specific capability. Assign atomic, well-described tasks.",
+      "tools": {
+        "workflows*": false,
+        "crowd-mcp-local*": true
+      }
+    },
+    "research": {
+      "description": "Research and development",
+      "mode": "primary",
+      "prompt": "You are a researcher who knows the docs of particular systems and processes. Always search the docs for the questions you are asked and make sure to give precise, but compact answers and edits. If you don't find anything in the docs, respond clearly that you do not know about this topic",
+      "tools": {
+        "knowledge*": true
+      }
+    },
+    "powerpoint": {
+      "description": "PowerPoint presentation generation",
+      "mode": "primary",
+      "prompt": "You are a tool that generates PowerPoint presentations from text prompts. Use the ppt-mcp tools manipulate the slides.",
+      "tools": {
+        "ppt-mcp*": true
+      }
+    },
+    "kinderspiel": {
+      "description": "Ein Agent, der Kindern beim Entwickeln von Spielen hilft",
+      "mode": "primary",
+      "prompt": "You are a friendly, patient, and encouraging AI assistant helping a child (ages 8-12) learn game development.\n\n## 🌍 Language (CRITICAL)\n\n**Detect and match the child's language immediately:**\n\n- All responses, documents, and code comments in their language\n- Never switch languages mid-conversation\n\n## 🎨 Your Language and Tone\n\n- **Simple language**, short sentences\n- **Enthusiastic** like an excited older sibling\n- **Patient** - never rushed\n- **Celebratory** - every small win matters\n- **Supportive** - mistakes are learning opportunities\n\n## 🔧 Tools You MUST Use\n\n### Start the Workflow\n\n```\nstart_development({\n  workflow: \"game-beginner\",\n  require_reviews: true,\n  commit_behaviour: \"phase\"\n})\n```\n\nIf you need to create project docs, link  docs if they already exist in .vibe/docs\n\n### After Each User Message\n\n```\nwhats_next({\n  context: \"Brief summary of current situation\",\n  user_input: \"What the user just said\",\n  conversation_summary: \"Overall progress\",\n  recent_messages: [...]\n})\n```\n\n**Then follow the instructions you receive exactly!**\nYou're inspiring future creators! 🚀\n",
+      "tools": {
+        "kinderspiel*": true,
+        "crowd-mcp-local*": false,
+        "workflows": false
+      }
+    },
+    "workflow": {
+      "description": "Metal alignment over autonomy",
+      "prompt": "You follow a defined workflow that helps you be in sync with the user.",
+      "permission": {
+        "start_development": "ask",
+        "reset_development": "ask",
+        "proceed_to_phase": "ask"
+      }
+    }
+  }
+}
diff --git a/packages/opencode-plugin/src/plugin.ts b/packages/opencode-plugin/src/plugin.ts
@@ -797,51 +797,6 @@ ACTION REQUIRED: Use proceed_to_phase tool to move to a phase that allows editin
         ),
       };
     })(),
-
-    /**
-     * Bridge Zod .describe() descriptions from plugin's registry into host's registry.
-     *
-     * Problem: this plugin uses a different zod instance than OpenCode (host). In Zod v4,
-     * .describe() stores descriptions in a module-level globalRegistry singleton. When
-     * OpenCode calls z.toJSONSchema(parameters), it reads from its own registry which has
-     * no entries for plugin schemas — so all parameter descriptions are missing from the
-     * JSON Schema sent to the LLM.
-     *
-     * Solution: dynamically import 'zod' at hook call time. When the plugin is installed
-     * without its own node_modules/zod (zod is a peerDependency), this import resolves to
-     * the host's (OpenCode's) zod module — the same instance used when creating
-     * output.parameters. We then register each field schema's description into the host's
-     * globalRegistry, making them visible to the subsequent z.toJSONSchema() call.
-     */
-    'tool.definition': async (
-      _input: { toolID: string },
-      output: { description: string; parameters: unknown }
-    ): Promise<void> => {
-      try {
-        const parameters = output.parameters as {
-          _zod?: { def?: { shape?: Record<string, { description?: string }> } };
-        };
-        const shape = parameters?._zod?.def?.shape;
-        if (!shape) return;
-
-        // Dynamically import zod — in production (installed without local node_modules/zod),
-        // this resolves to the host's zod instance, sharing the same globalRegistry.
-        const { globalRegistry: hostRegistry } = await import('zod');
-
-        for (const [_key, fieldSchema] of Object.entries(shape)) {
-          const desc = fieldSchema?.description;
-          if (desc && typeof desc === 'string') {
-            (
-              hostRegistry as {
-                add(schema: unknown, meta: { description: string }): void;
-              }
-            ).add(fieldSchema, { description: desc });
-          }
-        }
-      } catch {
-        // Silently ignore — descriptions are a nice-to-have, not critical
-      }
-    },
   };
 };
 
diff --git a/packages/opencode-plugin/src/tool-handlers/start-development.ts b/packages/opencode-plugin/src/tool-handlers/start-development.ts
@@ -1,7 +1,6 @@
 import { z } from 'zod';
 import {
   StartDevelopmentHandler,
-  generateWorkflowDescription,
   buildWorkflowEnum,
   type WhatsNextResult,
   type ServerContext,
@@ -26,18 +25,20 @@ export function createStartDevelopmentTool(
     workflowManager.getAvailableWorkflowsForProject(projectDir);
   const workflowNames = availableWorkflows.map(w => w.name);
 
-  // Build tool description with workflow list
+  // Build tool description with full workflow details embedded,
+  // since OpenCode does not propagate Zod .describe() to the LLM.
+  const workflowLines = availableWorkflows
+    .map(w => `  - ${w.name}: ${w.displayName} — ${w.description}`)
+    .join('\n');
   const toolDescription =
     workflowNames.length > 0
-      ? `Start a development workflow. Available: ${workflowNames.join(', ')}`
+      ? `Start a development workflow.\n\nworkflow parameter — available values:\n${workflowLines}\n  - custom: Use a custom workflow name`
       : 'Start a development workflow (no workflows available - check WORKFLOW_DOMAINS)';
 
   return tool({
     description: toolDescription,
     args: {
-      workflow: z
-        .enum(buildWorkflowEnum(workflowNames))
-        .describe(generateWorkflowDescription(availableWorkflows)),
+      workflow: z.enum(buildWorkflowEnum(workflowNames)),
       require_reviews: z
         .boolean()
         .optional()
