@codemcp/workflows 6.20.1 → 6.21.0

package/packages/opencode-plugin/dist/index.d.ts

@@ -1,72 +1,16 @@
-import { z } from 'zod';
-import { Effect } from 'effect';
+import { Plugin } from '@opencode-ai/plugin';
+export { Hooks, Plugin, PluginInput, PluginModule, ToolContext, ToolDefinition } from '@opencode-ai/plugin';
 
 /**
  * OpenCode Plugin Types
  *
- * Minimal type definitions needed for the plugin.
- * Based on @opencode-ai/plugin package types.
+ * Re-exports the types we need directly from the official @opencode-ai/plugin
+ * SDK so that any change to the SDK's type signatures (e.g. ToolContext.ask)
+ * is caught at compile time rather than silently breaking at runtime.
+ *
+ * Only types that are NOT exported by the SDK are defined here.
  */
 
-type Part = {
-    type: 'text' | 'image' | 'file' | 'tool_use' | 'tool_result';
-    text?: string;
-    [key: string]: unknown;
-};
-type UserMessage = {
-    id: string;
-    sessionID: string;
-    role: 'user';
-    [key: string]: unknown;
-};
-type Message = {
-    id: string;
-    sessionID: string;
-    role: 'user' | 'assistant';
-    [key: string]: unknown;
-};
-type Model = {
-    providerID: string;
-    modelID: string;
-    [key: string]: unknown;
-};
-type Project = {
-    id: string;
-    path: string;
-    [key: string]: unknown;
-};
-type PluginInput = {
-    client: unknown;
-    project: Project;
-    directory: string;
-    worktree: string;
-    serverUrl: URL;
-    $: unknown;
-};
-
-type ToolContext = {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    directory: string;
-    worktree: string;
-    abort: AbortSignal;
-    metadata(input: {
-        title?: string;
-        metadata?: Record<string, unknown>;
-    }): void;
-    ask(input: {
-        permission: string;
-        patterns: string[];
-        always: string[];
-        metadata: Record<string, unknown>;
-    }): Effect.Effect<void>;
-};
-type ToolDefinition = {
-    description: string;
-    args: z.ZodRawShape;
-    execute(args: unknown, context: ToolContext): Promise<string>;
-};
 type SessionCompactedEvent = {
     type: 'session.compacted';
     properties: {
@@ -84,134 +28,6 @@ type OtherEvent = {
     properties: Record<string, unknown>;
 };
 type BusEvent = SessionCompactedEvent | SessionIdleEvent | OtherEvent;
-interface Hooks {
-    event?: (input: {
-        event: BusEvent;
-    }) => Promise<void>;
-    config?: (input: unknown) => Promise<void>;
-    tool?: {
-        [key: string]: ToolDefinition;
-    };
-    auth?: unknown;
-    /**
-     * Called when a new message is received
-     */
-    'chat.message'?: (input: {
-        sessionID: string;
-        agent?: string;
-        model?: {
-            providerID: string;
-            modelID: string;
-        };
-        messageID?: string;
-        variant?: string;
-    }, output: {
-        message: UserMessage;
-        parts: Part[];
-    }) => Promise<void>;
-    /**
-     * Modify parameters sent to LLM
-     */
-    'chat.params'?: (input: {
-        sessionID: string;
-        agent: string;
-        model: Model;
-        provider: unknown;
-        message: UserMessage;
-    }, output: {
-        temperature: number;
-        topP: number;
-        topK: number;
-        options: Record<string, unknown>;
-    }) => Promise<void>;
-    'chat.headers'?: (input: {
-        sessionID: string;
-        agent: string;
-        model: Model;
-        provider: unknown;
-        message: UserMessage;
-    }, output: {
-        headers: Record<string, string>;
-    }) => Promise<void>;
-    'permission.ask'?: (input: unknown, output: {
-        status: 'ask' | 'deny' | 'allow';
-    }) => Promise<void>;
-    'command.execute.before'?: (input: {
-        command: string;
-        sessionID: string;
-        arguments: string;
-    }, output: {
-        parts: Part[];
-    }) => Promise<void>;
-    'tool.execute.before'?: (input: {
-        tool: string;
-        sessionID: string;
-        callID: string;
-    }, output: {
-        args: Record<string, unknown>;
-    }) => Promise<void>;
-    'shell.env'?: (input: {
-        cwd: string;
-        sessionID?: string;
-        callID?: string;
-    }, output: {
-        env: Record<string, string>;
-    }) => Promise<void>;
-    'tool.execute.after'?: (input: {
-        tool: string;
-        sessionID: string;
-        callID: string;
-        args: unknown;
-    }, output: {
-        title: string;
-        output: string;
-        metadata: unknown;
-    }) => Promise<void>;
-    'experimental.chat.messages.transform'?: (input: Record<string, never>, output: {
-        messages: {
-            info: Message;
-            parts: Part[];
-        }[];
-    }) => Promise<void>;
-    'experimental.chat.system.transform'?: (input: {
-        sessionID?: string;
-        model: Model;
-    }, output: {
-        system: string[];
-    }) => Promise<void>;
-    /**
-     * Called before session compaction starts. Allows plugins to customize
-     * the compaction prompt.
-     */
-    'experimental.session.compacting'?: (input: {
-        sessionID: string;
-    }, output: {
-        context: string[];
-        prompt?: string;
-    }) => Promise<void>;
-    'experimental.text.complete'?: (input: {
-        sessionID: string;
-        messageID: string;
-        partID: string;
-    }, output: {
-        text: string;
-    }) => Promise<void>;
-    /**
-     * Modify tool definitions (description and parameters) sent to LLM
-     */
-    'tool.definition'?: (input: {
-        toolID: string;
-    }, output: {
-        description: string;
-        parameters: unknown;
-    }) => Promise<void>;
-}
-type Plugin = (input: PluginInput) => Promise<Hooks>;
-type PluginModule = {
-    id?: string;
-    server: Plugin;
-    tui?: never;
-};
 
 /**
  * OpenCode Workflows Plugin
@@ -236,4 +52,4 @@ declare const _default: {
     server: Plugin;
 };
 
-export { type BusEvent, type Hooks, type Message, type Model, type OtherEvent, type Part, type Plugin, type PluginInput, type PluginModule, type Project, type SessionCompactedEvent, type SessionIdleEvent, type ToolContext, type ToolDefinition, type UserMessage, WorkflowsPlugin, _default as default };
+export { type BusEvent, type OtherEvent, type SessionCompactedEvent, type SessionIdleEvent, WorkflowsPlugin, _default as default };

package/packages/opencode-plugin/dist/index.js

@@ -16878,7 +16878,8 @@ var ConfigManager = class {
       this.validateConfig(config, configPath);
       logger3.info("Loaded project configuration", {
         configPath,
-        enabledWorkflows: config.enabled_workflows?.length || 0
+        enabledWorkflows: config.enabled_workflows?.length || 0,
+        capabilityModels: config.capability_models ? Object.keys(config.capability_models).length : 0
       });
       return config;
     } catch (error) {
@@ -16908,6 +16909,23 @@ var ConfigManager = class {
         }
       }
     }
+    if (config.capability_models !== void 0) {
+      if (typeof config.capability_models !== "object" || config.capability_models === null || Array.isArray(config.capability_models)) {
+        throw new Error(`Invalid config file ${configPath}: capability_models must be an object`);
+      }
+      for (const [key, entry] of Object.entries(config.capability_models)) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+          throw new Error(`Invalid config file ${configPath}: capability_models entry '${key}' must be an object`);
+        }
+        const { model, agent } = entry;
+        if (model !== void 0 && (typeof model !== "string" || model.trim() === "")) {
+          throw new Error(`Invalid config file ${configPath}: capability_models entry '${key}' model must be a non-empty string`);
+        }
+        if (agent !== void 0 && (typeof agent !== "string" || agent.trim() === "")) {
+          throw new Error(`Invalid config file ${configPath}: capability_models entry '${key}' agent must be a non-empty string`);
+        }
+      }
+    }
   }
 };
 
@@ -19861,6 +19879,31 @@ var BeadsStateManager = class {
   }
 };
 
+// ../core/dist/capability-hint.js
+var CAPABILITY_DESCRIPTIONS = {
+  thinking: "deep reasoning, complex planning",
+  research: "fast information gathering and browsing"
+};
+function formatCapabilityHint(capability, config) {
+  if (!capability) {
+    return "";
+  }
+  const description = CAPABILITY_DESCRIPTIONS[capability];
+  const label = description ? `Capability hint: This phase requires ${capability} capability (${description}).` : `Capability hint: This phase requires ${capability} capability.`;
+  const model = config?.model;
+  const agent = config?.agent;
+  if (agent && model) {
+    return `${label} When launching subagents, use agent: ${agent} (model: ${model}).`;
+  }
+  if (agent) {
+    return `${label} When launching subagents, use agent: ${agent}.`;
+  }
+  if (model) {
+    return `${label} When launching subagents, prefer model: ${model}.`;
+  }
+  return label;
+}
+
 // ../core/dist/interaction-logger.js
 var logger12 = createLogger("InteractionLogger");
 var InteractionLogger = class {
@@ -19987,7 +20030,7 @@ var InstructionGenerator = class {
    * Enhance base instructions with context-specific information
    */
   async enhanceInstructions(baseInstructions, context3) {
-    const { phase, conversationContext, allowedFilePatterns } = context3;
+    const { phase, conversationContext, allowedFilePatterns, requiredCapability, capabilityConfig } = context3;
     const phaseName = capitalizePhase(phase);
     let workflowSection = `---
 ### YOU MUST FOLLOW THESE INSTRUCTIONS:
@@ -20002,6 +20045,12 @@ var InstructionGenerator = class {
     if (allowedFilePatterns && allowedFilePatterns.length > 0 && !allowedFilePatterns.includes("**/*") && !allowedFilePatterns.includes("*")) {
       workflowSection += `
 - Files allowed: \`${allowedFilePatterns.join("`, `")}\``;
+    }
+    const capabilityHint = formatCapabilityHint(requiredCapability, capabilityConfig);
+    if (capabilityHint) {
+      workflowSection += `
+
+${capabilityHint}`;
     }
     workflowSection += "\n\nCall `whats_next()` after user messages.";
     return `## ${phaseName} Phase
@@ -26171,6 +26220,11 @@ var WhatsNextHandler = class extends ConversationRequiredToolHandler {
     );
     const phaseState = stateMachine.states[transitionResult.newPhase];
     const allowedFilePatterns = phaseState?.allowed_file_patterns ?? ["**/*"];
+    const requiredCapability = phaseState?.required_capability;
+    const projectConfig = ConfigManager.loadProjectConfig(
+      conversationContext.projectPath
+    );
+    const capabilityConfig = requiredCapability ? projectConfig?.capability_models?.[requiredCapability] : void 0;
     const instructions = await context3.instructionGenerator.generateInstructions(
       transitionResult.instructions,
       {
@@ -26182,7 +26236,9 @@ var WhatsNextHandler = class extends ConversationRequiredToolHandler {
         transitionReason: transitionResult.transitionReason,
         isModeled: transitionResult.isModeled,
         instructionSource: "whats_next",
-        allowedFilePatterns
+        allowedFilePatterns,
+        requiredCapability,
+        capabilityConfig
       }
     );
     let finalInstructions = instructions.instructions;
@@ -26343,6 +26399,11 @@ var ProceedToPhaseHandler = class extends ConversationRequiredToolHandler {
     );
     const phaseState = stateMachine.states[transitionResult.newPhase];
     const allowedFilePatterns = phaseState?.allowed_file_patterns ?? ["**/*"];
+    const requiredCapability = phaseState?.required_capability;
+    const projectConfig = ConfigManager.loadProjectConfig(
+      conversationContext.projectPath
+    );
+    const capabilityConfig = requiredCapability ? projectConfig?.capability_models?.[requiredCapability] : void 0;
     const instructions = await context3.instructionGenerator.generateInstructions(
       transitionResult.instructions,
       {
@@ -26354,7 +26415,9 @@ var ProceedToPhaseHandler = class extends ConversationRequiredToolHandler {
         transitionReason: transitionResult.transitionReason,
         isModeled: transitionResult.isModeled,
         instructionSource: "proceed_to_phase",
-        allowedFilePatterns
+        allowedFilePatterns,
+        requiredCapability,
+        capabilityConfig
       }
     );
     let finalInstructions = instructions.instructions;
@@ -28815,6 +28878,14 @@ function createOpenCodeLogger(client) {
 }
 
 // src/plugin.ts
+var EFFECT_TYPE_ID = "~effect/Effect";
+async function runAsk(askResult) {
+  if (askResult !== null && typeof askResult === "object" && EFFECT_TYPE_ID in askResult) {
+    await Effect_exports.runPromise(askResult);
+  } else {
+    await askResult;
+  }
+}
 function matchGlobPattern(filePath, pattern) {
   const normalised = filePath.replace(/\\/g, "/");
   const baseName = normalised.split("/").pop() ?? "";
@@ -29277,7 +29348,7 @@ ${phaseInstructions}`
               `Workflows are not enabled for this agent (${agent}). Set WORKFLOW_AGENTS environment variable to include this agent, or use a different agent.`
             );
           }
-          await Effect_exports.runPromise(
+          await runAsk(
             ctx.ask({
               permission: toolName,
               patterns: buildPermissionPatterns(

package/packages/opencode-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows-opencode",
-  "version": "6.20.1",
+  "version": "6.21.0",
   "description": "OpenCode plugin for structured development workflows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,18 +29,23 @@
   "devDependencies": {
     "@codemcp/workflows-core": "workspace:*",
     "@codemcp/workflows-server": "workspace:*",
+    "@opencode-ai/plugin": "*",
     "rimraf": "^6.0.1",
     "tsup": "^8.0.0",
     "vitest": "4.0.18"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "*",
+    "@opencode-ai/plugin": "*",
     "zod": ">=4.1.8"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sdk": {
       "optional": true
     },
+    "@opencode-ai/plugin": {
+      "optional": false
+    },
     "zod": {
       "optional": false
     }

package/packages/opencode-plugin/resources/templates/opencode-agents/coding.md.tmpl

@@ -0,0 +1,13 @@
+---
+description: "Subagent for code generation and editing, focused on idiomatic patterns and minimal scope."
+mode: subagent
+model: ${model}
+---
+
+You are the `${capability}` subagent for the workflows system. Your job is to implement focused, high-quality code changes on behalf of the parent agent.
+
+Read the file you are about to edit before changing it. Match the surrounding style: indentation, naming, import order, error-handling conventions, and test patterns. Prefer small, surgical edits over large rewrites — change as little as possible to satisfy the requirement, and leave unrelated code untouched.
+
+Write idiomatic code for the language and framework in use. Avoid clever one-liners, speculative abstractions, or new dependencies unless they are clearly justified. When a fix could be done two ways, pick the simpler one and note the trade-off in a short comment if it matters.
+
+Run the relevant tests and linters when you can. If a build or test fails, do not declare success — diagnose and fix the root cause rather than papering over it. Never commit, push, or modify git state unless the parent agent explicitly instructs you to.

package/packages/opencode-plugin/resources/templates/opencode-agents/research.md.tmpl

@@ -0,0 +1,13 @@
+---
+description: "Subagent for fast information gathering and codebase exploration."
+mode: subagent
+model: ${model}
+---
+
+You are the `${capability}` subagent for the workflows system. Your job is to gather information quickly and report back concisely to the parent agent.
+
+Search the codebase, documentation, and any provided context before answering. Use the most targeted query you can — exact symbol names, file paths, or distinctive error messages — before falling back to broader patterns. When a question can be answered by reading one or two files, just read them instead of guessing.
+
+Report findings as a tight, structured summary: the direct answer first, then supporting evidence with file paths and line numbers. Quote only the snippets that matter. Do not paraphrase code when the original is clearer.
+
+Avoid making changes. Do not implement, refactor, or "fix while you're there" — your job is to inform the parent's decision, not to make it. If a question cannot be answered from the available context, say so plainly and suggest the next investigation step.

package/packages/opencode-plugin/resources/templates/opencode-agents/thinking.md.tmpl

@@ -0,0 +1,13 @@
+---
+description: "Subagent for deep reasoning, complex planning, and architectural trade-off analysis."
+mode: subagent
+model: ${model}
+---
+
+You are the `${capability}` subagent for the workflows system. Your job is to support the parent agent during phases that demand careful reasoning, planning, and architectural analysis.
+
+Approach problems methodically. Read the relevant code, surrounding tests, and any linked design notes before forming an opinion. When a question involves trade-offs, lay out the options with their concrete consequences rather than jumping to a single answer. Distinguish clearly between observed facts, reasonable inferences, and assumptions that still need verification.
+
+Prefer structured output: short bullet lists, named options, and explicit recommendation with rationale. Call out open questions, risks, and edge cases the parent agent should not overlook. When a decision depends on values (readability, performance, maintainability, scope) name them rather than hand-waving.
+
+Avoid making code changes unless the parent agent explicitly asks you to. Your primary value is sharp thinking, not typing. Do not invent APIs, file paths, or version numbers — when uncertain, say so and point at where to verify.

package/packages/opencode-plugin/resources/workflows/bugfix.yaml

@@ -26,10 +26,13 @@ metadata:
 states:
   reproduce:
     description: 'Reproduce and understand the bug'
+    required_capability: 'research'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
       - '**/*.adoc'
+      - '**/*test*'
+      - '**/*spec*'
     default_instructions: |
       Gather specific information to reliably reproduce the reported bug:
       - What are the exact OS, browser/runtime versions, and hardware specs?
@@ -46,6 +49,7 @@ states:
 
   analyze:
     description: 'Analyze the bug and identify root cause'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -74,6 +78,7 @@ states:
 
   fix:
     description: 'Implement the bug fix'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |
@@ -110,6 +115,7 @@ states:
 
   verify:
     description: 'Verify the fix and ensure no regressions'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*'
     default_instructions: Test the fix thoroughly to ensure the original bug is resolved and no new issues were introduced. Run existing tests, create new ones if needed, and verify the solution is robust.

package/packages/opencode-plugin/resources/workflows/epcc.yaml

@@ -26,6 +26,7 @@ metadata:
 states:
   explore:
     description: 'Research and exploration phase - understanding the problem space'
+    required_capability: 'research'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -48,6 +49,7 @@ states:
 
   plan:
     description: 'Planning phase - creating a detailed implementation strategy'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -92,6 +94,7 @@ states:
 
   code:
     description: 'Implementation phase - writing and building the solution'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |

package/packages/opencode-plugin/resources/workflows/greenfield.yaml

@@ -27,6 +27,7 @@ metadata:
 states:
   ideation:
     description: 'Deep requirements discovery and PRD creation phase'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -51,6 +52,7 @@ states:
 
   architecture:
     description: 'Tech stack selection and architecture design phase'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -130,6 +132,7 @@ states:
 
   code:
     description: 'Implementation phase following the established plan and architecture'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |

package/packages/opencode-plugin/resources/workflows/pr-review.yaml

@@ -57,6 +57,7 @@ states:
 
   review_architecture:
     description: 'Review whether the change is in the right place and respects existing structure'
+    required_capability: 'thinking'
     default_instructions: |
       Evaluate the structural decisions in the change against the confirmed intent:
 
@@ -93,6 +94,7 @@ states:
 
   review_correctness:
     description: 'Review whether the logic correctly achieves the confirmed intent'
+    required_capability: 'thinking'
     default_instructions: |
       Evaluate the logic of the change against the confirmed intent:
 

package/packages/opencode-plugin/resources/workflows/qrspi.yaml

@@ -54,6 +54,7 @@ states:
 
   research:
     description: 'Gather facts without forming conclusions or proposing solutions'
+    required_capability: 'research'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -81,6 +82,7 @@ states:
 
   design:
     description: 'Explore options and reach consensus on WHAT and high-level HOW'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -114,6 +116,7 @@ states:
 
   structure:
     description: 'Decompose the approved design into end-to-end vertical slices'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -143,6 +146,7 @@ states:
 
   plan:
     description: 'Create a detailed implementation plan per vertical slice'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -182,6 +186,7 @@ states:
 
   implement:
     description: 'Build the solution slice by slice'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |

package/packages/opencode-plugin/resources/workflows/tdd.yaml

@@ -26,6 +26,7 @@ metadata:
 states:
   explore:
     description: 'Research and exploration phase - understanding the problem space and codebase'
+    required_capability: 'research'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -50,6 +51,7 @@ states:
 
   red:
     description: 'RED phase - Write a failing test that defines the expected behavior'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |
@@ -87,6 +89,7 @@ states:
 
   green:
     description: 'GREEN phase - Write only the necessary code to make the test pass'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |

package/packages/opencode-plugin/resources/workflows/waterfall.yaml

@@ -27,6 +27,7 @@ metadata:
 states:
   requirements:
     description: 'Gathering and analyzing requirements'
+    required_capability: 'research'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -53,6 +54,7 @@ states:
 
   design:
     description: 'Technical design and architecture planning'
+    required_capability: 'thinking'
     allowed_file_patterns:
       - '**/*.md'
       - '**/*.txt'
@@ -80,6 +82,7 @@ states:
 
   implementation:
     description: 'Building the solution according to design'
+    required_capability: 'coding'
     allowed_file_patterns:
       - '**/*'
     default_instructions: |

package/packages/opencode-tui-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows-opencode-tui",
-  "version": "6.20.1",
+  "version": "6.21.0",
   "description": "OpenCode TUI sidebar plugin that displays the current responsible-vibe workflow phase and name",
   "main": "workflows-phase.tsx",
   "exports": {

package/packages/visualizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows-visualizer",
-  "version": "6.20.1",
+  "version": "6.21.0",
   "type": "module",
   "main": "dist/index.ts",
   "module": "dist/index.ts",

package/resources/state-machine-schema.json

@@ -82,6 +82,10 @@
           },
           "description": "Glob patterns for files that can be edited in this state. Use '**/*' to allow all files."
         },
+        "required_capability": {
+          "type": "string",
+          "description": "Optional capability hint for this phase. If absent, no capability routing is applied. Free-form string; conventional values are `thinking`, `research`, `coding`. See `.vibe/config.yaml` `capability_models` for optional model/agent mapping."
+        },
         "default_instructions": {
           "type": "string",
           "description": "Default instructions when entering this state"