@codemcp/workflows 6.20.2 → 6.21.0

package/packages/cli/dist/{dist-ISN3FRV4.js → dist-FIUD5G5U.js}

@@ -7153,7 +7153,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) {
@@ -7183,6 +7184,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`);
+        }
+      }
+    }
   }
 };
 var logger4 = createLogger("WorkflowManager");
@@ -10081,6 +10099,29 @@ var BeadsStateManager = class {
     }
   }
 };
+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;
+}
 var logger12 = createLogger("InteractionLogger");
 var InteractionLogger = class {
   database;
@@ -10204,7 +10245,7 @@ var InstructionGenerator = class {
    * Enhance base instructions with context-specific information
    */
   async enhanceInstructions(baseInstructions, context) {
-    const { phase, conversationContext, allowedFilePatterns } = context;
+    const { phase, conversationContext, allowedFilePatterns, requiredCapability, capabilityConfig } = context;
     const phaseName = capitalizePhase(phase);
     let workflowSection = `---
 ### YOU MUST FOLLOW THESE INSTRUCTIONS:
@@ -10219,6 +10260,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
@@ -12254,6 +12301,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 context.instructionGenerator.generateInstructions(
       transitionResult.instructions,
       {
@@ -12265,7 +12317,9 @@ var WhatsNextHandler = class extends ConversationRequiredToolHandler {
         transitionReason: transitionResult.transitionReason,
         isModeled: transitionResult.isModeled,
         instructionSource: "whats_next",
-        allowedFilePatterns
+        allowedFilePatterns,
+        requiredCapability,
+        capabilityConfig
       }
     );
     let finalInstructions = instructions.instructions;
@@ -12424,6 +12478,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 context.instructionGenerator.generateInstructions(
       transitionResult.instructions,
       {
@@ -12435,7 +12494,9 @@ var ProceedToPhaseHandler = class extends ConversationRequiredToolHandler {
         transitionReason: transitionResult.transitionReason,
         isModeled: transitionResult.isModeled,
         instructionSource: "proceed_to_phase",
-        allowedFilePatterns
+        allowedFilePatterns,
+        requiredCapability,
+        capabilityConfig
       }
     );
     let finalInstructions = instructions.instructions;

package/packages/cli/dist/{dist-TDV3DJ2J.js → dist-ZTAPC4IK.js}

@@ -20,13 +20,14 @@ import {
   capitalizePhase,
   clearLogSink,
   createLogger,
+  formatCapabilityHint,
   generateSystemPrompt,
   getPathBasename,
   logger,
   registerLogSink,
   setLoggingLevel,
   setLoggingLevelFromString
-} from "./chunk-4N42FFJE.js";
+} from "./chunk-KWAFQZUI.js";
 import "./chunk-R5U7XKVJ.js";
 export {
   BeadsIntegration,
@@ -50,6 +51,7 @@ export {
   capitalizePhase,
   clearLogSink,
   createLogger,
+  formatCapabilityHint,
   generateSystemPrompt,
   getPathBasename,
   logger,

package/packages/cli/dist/index.js

@@ -10,7 +10,7 @@ var args = process.argv.slice(2);
 if (args.length === 0) {
   const isLocal = existsSync(join(__dirname, "../../mcp-server/dist/index.js"));
   if (isLocal) {
-    const { startMcpServer } = await import("./dist-ISN3FRV4.js");
+    const { startMcpServer } = await import("./dist-FIUD5G5U.js");
     await startMcpServer();
   } else {
     const mcpServerModule = "@codemcp/workflows-server";
@@ -18,6 +18,6 @@ if (args.length === 0) {
     await startMcpServer();
   }
 } else {
-  const { runCli } = await import("./cli-MFHC7UWY.js");
+  const { runCli } = await import("./cli-O52P3RVC.js");
   await runCli();
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows-cli",
-  "version": "6.20.2",
+  "version": "6.21.0",
   "description": "CLI tools for responsible-vibe development workflows",
   "type": "module",
   "scripts": {
@@ -14,10 +14,13 @@
     "format:check": "prettier --check .",
     "format": "prettier --write ."
   },
-  "dependencies": {},
+  "dependencies": {
+    "js-yaml": "4.1.1"
+  },
   "devDependencies": {
     "@codemcp/workflows-core": "workspace:*",
     "@codemcp/workflows-server": "workspace:*",
+    "@types/js-yaml": "4.0.9",
     "@types/node": "^22.0.0",
     "rimraf": "^5.0.10",
     "tsup": "^8.0.0",

package/packages/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/cli/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/core/dist/capability-hint.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Capability hint formatter
+ *
+ * Pure helper that renders an instruction-based "Capability hint" sentence so
+ * the LLM picks a good model/agent for subagent work in a given phase. The
+ * mechanism is intentionally instruction-based (no API model switching) and
+ * fully opt-in: absent a capability, the helper returns an empty string and
+ * there is no behavioral change.
+ *
+ * Built-in human-readable descriptions exist ONLY for `thinking` and
+ * `research`. `coding` is deliberately omitted as self-evident, and any
+ * unknown/custom term is echoed verbatim without a parenthetical.
+ */
+/**
+ * Optional model/agent routing configuration consumed by the clause builder.
+ */
+export interface CapabilityConfig {
+    model?: string;
+    agent?: string;
+}
+/**
+ * Format a capability hint instruction sentence.
+ *
+ * @returns The full hint text, or `""` when `capability` is falsy. The hint
+ *   is one sentence by default; when `config` declares model/agent a second
+ *   sentence (the subagent clause) is appended.
+ */
+export declare function formatCapabilityHint(capability: string | undefined, config?: CapabilityConfig): string;

package/packages/core/dist/capability-hint.js

@@ -0,0 +1,52 @@
+/**
+ * Capability hint formatter
+ *
+ * Pure helper that renders an instruction-based "Capability hint" sentence so
+ * the LLM picks a good model/agent for subagent work in a given phase. The
+ * mechanism is intentionally instruction-based (no API model switching) and
+ * fully opt-in: absent a capability, the helper returns an empty string and
+ * there is no behavioral change.
+ *
+ * Built-in human-readable descriptions exist ONLY for `thinking` and
+ * `research`. `coding` is deliberately omitted as self-evident, and any
+ * unknown/custom term is echoed verbatim without a parenthetical.
+ */
+/**
+ * Built-in human-readable descriptions for known capabilities. `coding` is
+ * INTENTIONALLY ABSENT because it is self-evident.
+ */
+const CAPABILITY_DESCRIPTIONS = {
+    thinking: 'deep reasoning, complex planning',
+    research: 'fast information gathering and browsing',
+};
+/**
+ * Format a capability hint instruction sentence.
+ *
+ * @returns The full hint text, or `""` when `capability` is falsy. The hint
+ *   is one sentence by default; when `config` declares model/agent a second
+ *   sentence (the subagent clause) is appended.
+ */
+export function formatCapabilityHint(capability, config) {
+    if (!capability) {
+        return '';
+    }
+    // Label sentence with optional parenthetical description.
+    const description = CAPABILITY_DESCRIPTIONS[capability];
+    const label = description
+        ? `Capability hint: This phase requires ${capability} capability (${description}).`
+        : `Capability hint: This phase requires ${capability} capability.`;
+    // Subagent clause (emitted only when model and/or agent is configured).
+    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;
+}
+//# sourceMappingURL=capability-hint.js.map

package/packages/core/dist/capability-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-hint.js","sourceRoot":"","sources":["../src/capability-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH;;;GAGG;AACH,MAAM,uBAAuB,GAA2B;IACtD,QAAQ,EAAE,kCAAkC;IAC5C,QAAQ,EAAE,yCAAyC;CACpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAA8B,EAC9B,MAAyB;IAEzB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,0DAA0D;IAC1D,MAAM,WAAW,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,WAAW;QACvB,CAAC,CAAC,wCAAwC,UAAU,gBAAgB,WAAW,IAAI;QACnF,CAAC,CAAC,wCAAwC,UAAU,cAAc,CAAC;IAErE,wEAAwE;IACxE,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAC;IAE5B,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QACnB,OAAO,GAAG,KAAK,yCAAyC,KAAK,YAAY,KAAK,IAAI,CAAC;IACrF,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,GAAG,KAAK,yCAAyC,KAAK,GAAG,CAAC;IACnE,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,GAAG,KAAK,4CAA4C,KAAK,GAAG,CAAC;IACtE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/packages/core/dist/config-manager.d.ts

@@ -5,6 +5,25 @@
  */
 export interface ProjectConfig {
     enabled_workflows?: string[];
+    /**
+     * Optional capability→model/agent routing map.
+     *
+     * Keys are capability strings declared on workflow phases via
+     * `required_capability` (e.g. `thinking`, `research`, `coding`, or any
+     * custom term). Each value is an object with optional `model` and `agent`
+     * fields used to enrich the capability hint instruction. Absent ⇒ no
+     * model/agent clause (opt-in). An empty entry object `{}` is allowed and
+     * is a no-op (no model, no agent).
+     * @example
+     * capability_models:
+     *   thinking:
+     *     model: anthropic/claude-opus-4-7
+     *     agent: general_thinking
+     */
+    capability_models?: Record<string, {
+        model?: string;
+        agent?: string;
+    }>;
 }
 /**
  * Manages project configuration loading and validation

package/packages/core/dist/config-manager.js

@@ -32,6 +32,9 @@ export class ConfigManager {
             logger.info('Loaded project configuration', {
                 configPath,
                 enabledWorkflows: config.enabled_workflows?.length || 0,
+                capabilityModels: config.capability_models
+                    ? Object.keys(config.capability_models).length
+                    : 0,
             });
             return config;
         }
@@ -63,6 +66,29 @@ export class ConfigManager {
                 }
             }
         }
+        if (config.capability_models !== undefined) {
+            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 !== undefined &&
+                    (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 !== undefined &&
+                    (typeof agent !== 'string' || agent.trim() === '')) {
+                    throw new Error(`Invalid config file ${configPath}: capability_models entry '${key}' agent must be a non-empty string`);
+                }
+            }
+        }
     }
 }
 //# sourceMappingURL=config-manager.js.map

package/packages/core/dist/config-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../src/config-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAM7C;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,MAAM,CAAU,eAAe,GAAG,aAAa,CAAC;IAExD;;;;OAIG;IACI,MAAM,CAAC,iBAAiB,CAAC,WAAmB;QACjD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QAEzE,oEAAoE;QACpE,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,sCAAsC,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAkB,CAAC;YAEzD,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAExC,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;gBAC1C,UAAU;gBACV,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,IAAI,CAAC;aACxD,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,IAAI,CAAC,aAAa,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CACb,+BAA+B,UAAU,KAAK,KAAK,CAAC,OAAO,EAAE,CAC9D,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,8BAA8B,UAAU,KAAK,KAAK,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,cAAc,CAC3B,MAAqB,EACrB,UAAkB;QAElB,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,uBAAuB,UAAU,yBAAyB,CAC3D,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBAC7C,MAAM,IAAI,KAAK,CACb,uBAAuB,UAAU,sCAAsC,CACxE,CAAC;YACJ,CAAC;YAED,IAAI,MAAM,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,KAAK,CACb,uBAAuB,UAAU,qCAAqC,CACvE,CAAC;YACJ,CAAC;YAED,mCAAmC;YACnC,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;gBAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;oBAC3D,MAAM,IAAI,KAAK,CACb,uBAAuB,UAAU,gDAAgD,CAClF,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC"}
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../src/config-manager.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from './git-manager.js';
 export * from './task-backend.js';
 export * from './beads-integration.js';
 export * from './beads-state-manager.js';
+export * from './capability-hint.js';
 export * from './string-utils.js';
 export * from './logger.js';
 export * from './interaction-logger.js';

package/packages/core/dist/index.js

@@ -22,6 +22,7 @@ export * from './task-backend.js';
 export * from './beads-integration.js';
 export * from './beads-state-manager.js';
 // Utilities and generators
+export * from './capability-hint.js';
 export * from './string-utils.js';
 export * from './logger.js';
 export * from './interaction-logger.js';

package/packages/core/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AAEzC,8BAA8B;AAC9B,cAAc,uBAAuB,CAAC;AAEtC,wCAAwC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC,kBAAkB;AAClB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAE1C,8BAA8B;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,2BAA2B;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AAEzC,8BAA8B;AAC9B,cAAc,uBAAuB,CAAC;AAEtC,wCAAwC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AAEvC,kBAAkB;AAClB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAE1C,8BAA8B;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,2BAA2B;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC"}

package/packages/core/dist/instruction-generator.js

@@ -9,6 +9,7 @@
 import { ProjectDocsManager } from './project-docs-manager.js';
 import { createLogger } from './logger.js';
 import { capitalizePhase } from './string-utils.js';
+import { formatCapabilityHint } from './capability-hint.js';
 export class InstructionGenerator {
     projectDocsManager;
     constructor(logger = createLogger('InstructionGenerator')) {
@@ -61,7 +62,7 @@ export class InstructionGenerator {
      * Enhance base instructions with context-specific information
      */
     async enhanceInstructions(baseInstructions, context) {
-        const { phase, conversationContext, allowedFilePatterns } = context;
+        const { phase, conversationContext, allowedFilePatterns, requiredCapability, capabilityConfig, } = context;
         const phaseName = capitalizePhase(phase);
         // IMPORTANT: Directive markers to make instructions stand out from context
         let workflowSection = `---
@@ -81,6 +82,11 @@ export class InstructionGenerator {
             !allowedFilePatterns.includes('*')) {
             workflowSection += `\n- Files allowed: \`${allowedFilePatterns.join('`, `')}\``;
         }
+        // Append optional capability hint. Opt-in: empty hint ⇒ skip entirely.
+        const capabilityHint = formatCapabilityHint(requiredCapability, capabilityConfig);
+        if (capabilityHint) {
+            workflowSection += `\n\n${capabilityHint}`;
+        }
         workflowSection += '\n\nCall `whats_next()` after user messages.';
         return `## ${phaseName} Phase\n\n${baseInstructions}\n\n${workflowSection}`;
     }