@link-assistant/hive-mind 1.10.2 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @link-assistant/hive-mind
 
+## 1.11.1
+
+### Patch Changes
+
+- de2cc28: Use .gitkeep by default for --tool agent/opencode/codex instead of CLAUDE.md
+
+  When using non-Claude tools (agent, opencode, codex), the system now defaults to creating a `.gitkeep` file for task details instead of `CLAUDE.md`. This prevents pollution of CLAUDE.md, which has special meaning for Claude Code as a project-level instruction file.
+
+  **Tool-Specific Defaults:**
+  - `--tool claude`: defaults to `--claude-file` (existing behavior)
+  - `--tool agent/opencode/codex`: defaults to `--gitkeep-file`
+
+  Users can still explicitly override defaults with `--claude-file` or `--gitkeep-file` flags regardless of the selected tool.
+
+## 1.11.0
+
+### Minor Changes
+
+- ca28333: Add system prompt guidance for visual UI work when model supports vision
+
+  **Changes:**
+  - Add `checkModelVisionCapability` function in claude.lib.mjs to detect if a model supports image input using models.dev API
+  - Add vision-specific system prompt section in claude.prompts.lib.mjs and agent.prompts.lib.mjs
+  - When model supports vision, add guidance for including screenshots/renders of visual UI changes in pull request descriptions
+  - Use "When x, do y." style as requested
+
+  **Vision prompt guidance includes:**
+  - When working on visual UI changes, include a render or screenshot in the PR description
+  - When showing visual results, save screenshots to the repository (e.g., docs/screenshots/)
+  - When referencing images, use permanent raw file links in the PR description markdown
+  - When uploading images, commit them first, then use raw GitHub URL format
+  - When the visual result is important, mention it explicitly with embedded image
+
+  **Technical details:**
+  - Uses models.dev API to check if 'image' is in the model's input modalities
+  - All current Claude models (opus, sonnet, haiku) support vision
+  - Gracefully handles unknown models by returning false
+
+  Fixes #1175
+
 ## 1.10.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.10.2",
+  "version": "1.11.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent.lib.mjs

@@ -19,9 +19,9 @@ import { timeouts } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
 
 // Import pricing functions from claude.lib.mjs
-// We reuse fetchModelInfo to get pricing data from models.dev API
+// We reuse fetchModelInfo and checkModelVisionCapability to get data from models.dev API
 const claudeLib = await import('./claude.lib.mjs');
-const { fetchModelInfo } = claudeLib;
+const { fetchModelInfo, checkModelVisionCapability } = claudeLib;
 
 /**
  * Parse agent JSON output to extract token usage from step_finish events
@@ -250,6 +250,13 @@ export const executeAgent = async params => {
   // Import prompt building functions from agent.prompts.lib.mjs
   const { buildUserPrompt, buildSystemPrompt } = await import('./agent.prompts.lib.mjs');
 
+  // Check if the model supports vision using models.dev API
+  const mappedModel = mapModelToId(argv.model);
+  const modelSupportsVision = await checkModelVisionCapability(mappedModel);
+  if (argv.verbose) {
+    await log(`👁️  Model vision capability: ${modelSupportsVision ? 'supported' : 'not supported'}`, { verbose: true });
+  }
+
   // Build the user prompt
   const prompt = buildUserPrompt({
     issueUrl,
@@ -281,6 +288,7 @@ export const executeAgent = async params => {
     isContinueMode,
     forkedRepo,
     argv,
+    modelSupportsVision,
   });
 
   // Log prompt details in verbose mode

package/src/agent.prompts.lib.mjs

@@ -81,7 +81,7 @@ export const buildUserPrompt = params => {
  * @returns {string} The formatted system prompt
  */
 export const buildSystemPrompt = params => {
-  const { owner, repo, issueNumber, prNumber, branchName, workspaceTmpDir, argv } = params;
+  const { owner, repo, issueNumber, prNumber, branchName, workspaceTmpDir, argv, modelSupportsVision } = params;
 
   // Build thinking instruction based on --think level
   let thinkLine = '';
@@ -223,7 +223,18 @@ GitHub CLI command patterns.
    - When adding PR comment, use gh pr comment NUMBER --body "text" --repo OWNER/REPO.
    - When adding issue comment, use gh issue comment NUMBER --body "text" --repo OWNER/REPO.
    - When viewing PR details, use gh pr view NUMBER --repo OWNER/REPO.
-   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${ciExamples}${getArchitectureCareSubPrompt(argv)}`;
+   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${
+     modelSupportsVision
+       ? `
+
+Visual UI work and screenshots.
+   - When you work on visual UI changes (frontend, CSS, HTML, design), include a render or screenshot of the final result in the pull request description.
+   - When you need to show visual results, take a screenshot and save it to the repository (e.g., in a docs/screenshots/ or assets/ folder).
+   - When you save screenshots to the repository, use permanent raw file links in the pull request description markdown (e.g., https://raw.githubusercontent.com/${owner}/${repo}/${branchName}/docs/screenshots/result.png).
+   - When uploading images, commit them to the branch first, then reference them using the raw GitHub URL format.
+   - When the visual result is important for review, mention it explicitly in the pull request description with the embedded image.`
+       : ''
+   }${ciExamples}${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/claude.lib.mjs

@@ -340,6 +340,14 @@ export const executeClaude = async params => {
 
   // Import prompt building functions from claude.prompts.lib.mjs
   const { buildUserPrompt, buildSystemPrompt } = await import('./claude.prompts.lib.mjs');
+
+  // Check if the model supports vision using models.dev API
+  const mappedModel = mapModelToId(argv.model);
+  const modelSupportsVision = await checkModelVisionCapability(mappedModel);
+  if (argv.verbose) {
+    await log(`👁️  Model vision capability: ${modelSupportsVision ? 'supported' : 'not supported'}`, { verbose: true });
+  }
+
   // Build the user prompt
   const prompt = buildUserPrompt({
     issueUrl,
@@ -372,6 +380,7 @@ export const executeClaude = async params => {
     isContinueMode,
     forkedRepo,
     argv,
+    modelSupportsVision,
   });
   // Log prompt details in verbose mode
   if (argv.verbose) {
@@ -478,6 +487,27 @@ export const fetchModelInfo = async modelId => {
     return null;
   }
 };
+
+/**
+ * Check if a model supports vision (image input) using models.dev API
+ * @param {string} modelId - The model ID (e.g., "claude-sonnet-4-5-20250929")
+ * @returns {Promise<boolean>} True if the model supports vision, false otherwise
+ */
+export const checkModelVisionCapability = async modelId => {
+  try {
+    const modelInfo = await fetchModelInfo(modelId);
+    if (!modelInfo) {
+      return false;
+    }
+    // Check if 'image' is in the input modalities
+    const inputModalities = modelInfo.modalities?.input || [];
+    return inputModalities.includes('image');
+  } catch {
+    // If we can't determine vision capability, default to false
+    return false;
+  }
+};
+
 /**
  * Calculate USD cost for a model's usage with detailed breakdown
  * @param {Object} usage - Token usage object
@@ -1441,4 +1471,5 @@ export default {
   getClaudeVersion,
   setClaudeVersion,
   resolveThinkingSettings,
+  checkModelVisionCapability,
 };

package/src/claude.prompts.lib.mjs

@@ -90,7 +90,7 @@ export const buildUserPrompt = params => {
  * @returns {string} The formatted system prompt
  */
 export const buildSystemPrompt = params => {
-  const { owner, repo, issueNumber, prNumber, branchName, workspaceTmpDir, argv } = params;
+  const { owner, repo, issueNumber, prNumber, branchName, workspaceTmpDir, argv, modelSupportsVision } = params;
 
   // Note: --think keywords are deprecated for Claude Code >= 2.1.12
   // Thinking is now enabled by default with 31,999 token budget
@@ -313,6 +313,17 @@ Agent Commander usage (unified subagent delegation).
    - Benefits: Saves main agent context, supports any agent type, provides unified API across different AI tools.
    - Note: The subagent will have access to the same working directory and can read/write files as needed.`
        : ''
+   }${
+     modelSupportsVision
+       ? `
+
+Visual UI work and screenshots.
+   - When you work on visual UI changes (frontend, CSS, HTML, design), include a render or screenshot of the final result in the pull request description.
+   - When you need to show visual results, take a screenshot and save it to the repository (e.g., in a docs/screenshots/ or assets/ folder).
+   - When you save screenshots to the repository, use permanent raw file links in the pull request description markdown (e.g., https://raw.githubusercontent.com/${owner}/${repo}/${branchName}/docs/screenshots/result.png).
+   - When uploading images, commit them to the branch first, then reference them using the raw GitHub URL format.
+   - When the visual result is important for review, mention it explicitly in the pull request description with the embedded image.`
+       : ''
    }${ciExamples}${getArchitectureCareSubPrompt(argv)}`;
 };
 

package/src/solve.config.lib.mjs

@@ -130,12 +130,12 @@ export const createYargsConfig = yargsInstance => {
       })
       .option('claude-file', {
         type: 'boolean',
-        description: 'Create CLAUDE.md file for task details (default, mutually exclusive with --gitkeep-file)',
+        description: 'Create CLAUDE.md file for task details (default for --tool claude, mutually exclusive with --gitkeep-file)',
         default: true,
       })
       .option('gitkeep-file', {
         type: 'boolean',
-        description: 'Create .gitkeep file instead of CLAUDE.md (mutually exclusive with --claude-file)',
+        description: 'Create .gitkeep file instead of CLAUDE.md (default for --tool agent/opencode/codex, mutually exclusive with --claude-file)',
         default: false,
       })
       .option('auto-gitkeep-file', {
@@ -477,6 +477,20 @@ export const parseArguments = async (yargs, hideBin) => {
     argv.model = 'grok-code';
   }
 
+  // Tool-specific defaults for --claude-file and --gitkeep-file
+  // For non-Claude tools, use .gitkeep by default to avoid polluting CLAUDE.md
+  // (CLAUDE.md has special meaning for Claude Code as a project-level instruction file)
+  // See: https://github.com/link-assistant/hive-mind/issues/1158
+  const claudeFileExplicitlyProvided = rawArgs.includes('--claude-file') || rawArgs.includes('--no-claude-file');
+  const gitkeepFileExplicitlyProvided = rawArgs.includes('--gitkeep-file') || rawArgs.includes('--no-gitkeep-file');
+
+  if (argv.tool !== 'claude' && !claudeFileExplicitlyProvided && !gitkeepFileExplicitlyProvided) {
+    // User did not explicitly provide either option, so use the correct defaults for non-Claude tools
+    // Non-Claude tools (agent, opencode, codex) should use .gitkeep by default
+    argv.claudeFile = false;
+    argv.gitkeepFile = true;
+  }
+
   // Validate mutual exclusivity of --claude-file and --gitkeep-file
   // Check if both are explicitly enabled (user passed both --claude-file and --gitkeep-file)
   if (argv.claudeFile && argv.gitkeepFile) {