@link-assistant/hive-mind 0.54.6 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @link-assistant/hive-mind
 
+## 1.0.1
+
+### Patch Changes
+
+- 2a3848d: Add --prompt-architecture-care flag for managing REQUIREMENTS.md and ARCHITECTURE.md files
+
+  Adds an optional experimental flag `--prompt-architecture-care` that provides guidance for:
+  - Managing REQUIREMENTS.md (high-level why/what documentation)
+  - Managing ARCHITECTURE.md (high-level how documentation)
+  - TODO.md workflow management for task persistence across sessions
+
+  The flag is disabled by default and works with all tools (claude, agent, opencode, codex).
+
+- a18a664: Fix session ID extraction error for --tool agent
+  - Fixed JSON parsing logic in agent tool to extract session IDs from NDJSON output
+  - Modified session summary to show informational message for agent tool instead of error
+
+## 1.0.0
+
+### Major Changes
+
+- 4e8d141: Rename `--auto-continue-on-limit-reset` to `--auto-resume-on-limit-reset` for clarity
+
+  BREAKING CHANGE: The `--auto-continue-on-limit-reset` option has been renamed to `--auto-resume-on-limit-reset`. Users must update their commands and configurations to use the new flag name.
+
+  The option is related to `--resume` for `claude` command and has an entirely different meaning from `--auto-continue` mode. This rename makes the distinction clearer and aligns the terminology with the resume functionality.
+
+  Migration:
+  - Replace `--auto-continue-on-limit-reset` with `--auto-resume-on-limit-reset` in all commands
+  - Update environment variables and configuration files accordingly
+
 ## 0.54.6
 
 ### Patch Changes

package/README.md

@@ -223,12 +223,12 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options.
        --attach-logs
        --verbose
        --no-tool-check
-       --auto-continue-on-limit-reset
+       --auto-resume-on-limit-reset
      TELEGRAM_SOLVE_OVERRIDES:
        --attach-logs
        --verbose
        --no-tool-check
-       --auto-continue-on-limit-reset
+       --auto-resume-on-limit-reset
      TELEGRAM_BOT_VERBOSE: true
    "
 
@@ -250,12 +250,12 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options.
      --attach-logs
      --verbose
      --no-tool-check
-     --auto-continue-on-limit-reset
+     --auto-resume-on-limit-reset
    )" --solve-overrides "(
      --attach-logs
      --verbose
      --no-tool-check
-     --auto-continue-on-limit-reset
+     --auto-resume-on-limit-reset
    )" --verbose
 
    # Press CTRL + A + D for detach from screen

package/package.json

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

package/src/agent.lib.mjs

@@ -405,7 +405,26 @@ export const executeAgentCommand = async params => {
       for await (const chunk of execCommand.stream()) {
         if (chunk.type === 'stdout') {
           const output = chunk.data.toString();
-          await log(output);
+          // Split output into individual lines for NDJSON parsing
+          // Agent outputs NDJSON (newline-delimited JSON) format where each line is a separate JSON object
+          // This allows us to parse each event independently and extract structured data like session IDs
+          const lines = output.split('\n');
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+              const data = JSON.parse(line);
+              // Output formatted JSON
+              await log(JSON.stringify(data, null, 2));
+              // Capture session ID from the first message
+              if (!sessionId && data.sessionID) {
+                sessionId = data.sessionID;
+                await log(`📌 Session ID: ${sessionId}`);
+              }
+            } catch {
+              // Not JSON - log as plain text
+              await log(line);
+            }
+          }
           lastMessage = output;
           fullOutput += output; // Collect for both pricing calculation and error detection
         }

package/src/agent.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Agent commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Agent
  * @param {Object} params - Parameters for building the user prompt
@@ -183,7 +185,7 @@ 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]'.`;
+   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/architecture-care.prompts.lib.mjs

@@ -0,0 +1,52 @@
+/**
+ * Architecture care sub-prompt module
+ * Provides guidance for managing REQUIREMENTS.md, ARCHITECTURE.md, and TODO.md files
+ *
+ * This is an experimental feature enabled via --prompt-architecture-care flag
+ */
+
+/**
+ * Build the architecture care sub-prompt content
+ * @returns {string} The formatted sub-prompt for architecture documentation care
+ */
+export const buildArchitectureCareSubPrompt = () => {
+  return `
+Architecture and Requirements Documentation Care.
+   - REQUIREMENTS.md is a file that gives high level description on why/what it is for and so on relative to the entire repository.
+   - ARCHITECTURE.md is a file that gives high level description on how it was implemented so far.
+   - When any issue or comment changes how we see REQUIREMENTS.md or ARCHITECTURE.md, these files should be updated accordingly.
+   - When REQUIREMENTS.md or ARCHITECTURE.md files get too large, consider creating additional README.md, REQUIREMENTS.md, and ARCHITECTURE.md files in separate folders.
+   - When creating nested documentation files, make sure the root files have references to inner level documentation.
+   - When working with documentation, each README.md, REQUIREMENTS.md, and ARCHITECTURE.md scope should be related to the entire folder where such file exists.
+   - When you make changes that affect the high-level purpose, goals, or requirements of the project, update REQUIREMENTS.md.
+   - When you make changes that affect the implementation, architecture, or design patterns of the project, update ARCHITECTURE.md.
+   - When reviewing your changes before committing, check if REQUIREMENTS.md or ARCHITECTURE.md need updates based on the scope of your changes.
+
+TODO.md Workflow Management.
+   - At the start of each working session, check if TODO.md exists in the repository root.
+   - When TODO.md exists, read it first and continue finishing all items listed in it before starting any new work.
+   - When all items in TODO.md are completed, delete the TODO.md file to indicate work is done.
+   - When you cannot finish all tasks in the current working session, create or update TODO.md with all remaining tasks that need to be completed.
+   - When creating TODO.md, use a clear markdown checklist format with each item as a separate line.
+   - When updating TODO.md during a session, remove completed items and add any newly discovered tasks that couldn't be finished.
+   - TODO.md serves as a persistent task list across working sessions, ensuring continuity and nothing is forgotten between sessions.
+   - When starting work on a repository, the priority is: (1) Check TODO.md, (2) Complete TODO.md items, (3) Work on current issue/task, (4) Update TODO.md if needed before ending session.`;
+};
+
+/**
+ * Get the architecture care sub-prompt if enabled
+ * @param {Object} argv - Command line arguments
+ * @returns {string} The sub-prompt content or empty string if disabled
+ */
+export const getArchitectureCareSubPrompt = argv => {
+  if (argv && argv.promptArchitectureCare) {
+    return buildArchitectureCareSubPrompt();
+  }
+  return '';
+};
+
+// Export all functions as default object too
+export default {
+  buildArchitectureCareSubPrompt,
+  getArchitectureCareSubPrompt,
+};

package/src/claude.command-builder.lib.mjs

@@ -9,7 +9,7 @@
  *
  *   (cd "/path/to/workdir" && claude --resume <session-id>)
  *
- * This is the same pattern used by --auto-continue-on-limit-reset and allows users to:
+ * This is the same pattern used by --auto-resume-on-limit-reset and allows users to:
  * 1. Resume sessions directly using Claude CLI (not through solve.mjs)
  * 2. Investigate issues interactively in the working directory
  * 3. Continue work after usage limits reset
@@ -26,7 +26,7 @@
  *
  * This generates a copy-pasteable command that users can execute directly
  * to resume a Claude session in interactive mode. This is the same pattern
- * used by --auto-continue-on-limit-reset.
+ * used by --auto-resume-on-limit-reset.
  *
  * The command includes all necessary flags to match how the original session was run:
  * - --resume <sessionId>: Resume from the specified session

package/src/claude.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Claude commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Claude
  * @param {Object} params - Parameters for building the user prompt
@@ -241,7 +243,7 @@ Plan sub-agent usage.
    - When using the Plan sub-agent, you can add it as the first item in your todo list.
    - When you delegate planning, use the Task tool with subagent_type="Plan" before starting implementation work.`
        : ''
-   }`;
+   }${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/codex.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for Codex CLI commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for Codex
  * @param {Object} params - Parameters for building the user prompt
@@ -191,7 +193,7 @@ 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]'.`;
+   - When filtering with jq, use gh api repos/\${owner}/\${repo}/pulls/\${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/hive.config.lib.mjs

@@ -202,9 +202,9 @@ export const createYargsConfig = yargsInstance => {
       description: 'Pass --auto-continue to solve for each issue (continues with existing PRs instead of creating new ones)',
       default: true,
     })
-    .option('auto-continue-on-limit-reset', {
+    .option('auto-resume-on-limit-reset', {
       type: 'boolean',
-      description: 'Automatically continue when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
+      description: 'Automatically resume when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
       default: false,
     })
     .option('think', {
@@ -281,6 +281,11 @@ export const createYargsConfig = yargsInstance => {
       description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
       default: true,
     })
+    .option('prompt-architecture-care', {
+      type: 'boolean',
+      description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
+      default: false,
+    })
     .parserConfiguration({
       'boolean-negation': true,
       'strip-dashed': false,

package/src/hive.mjs

@@ -745,7 +745,7 @@ if (isDirectExecution) {
             if (argv.dryRun) args.push('--dry-run');
             if (argv.skipToolConnectionCheck || argv.toolConnectionCheck === false) args.push('--skip-tool-connection-check');
             args.push(argv.autoContinue ? '--auto-continue' : '--no-auto-continue');
-            if (argv.autoContinueOnLimitReset) args.push('--auto-continue-on-limit-reset');
+            if (argv.autoResumeOnLimitReset) args.push('--auto-resume-on-limit-reset');
             if (argv.think) args.push('--think', argv.think);
             if (argv.promptPlanSubAgent) args.push('--prompt-plan-sub-agent');
             if (!argv.sentry) args.push('--no-sentry');

package/src/opencode.prompts.lib.mjs

@@ -3,6 +3,8 @@
  * Handles building prompts for OpenCode commands
  */
 
+import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mjs';
+
 /**
  * Build the user prompt for OpenCode
  * @param {Object} params - Parameters for building the user prompt
@@ -182,7 +184,7 @@ 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]'.`;
+   - When filtering with jq, use gh api repos/${owner}/${repo}/pulls/${prNumber}/comments --paginate --jq 'reverse | .[0:5]'.${getArchitectureCareSubPrompt(argv)}`;
 };
 
 // Export all functions as default object too

package/src/solve.auto-continue.lib.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-// Auto-continue module for solve command
+// Session continuation module for solve command
+// Handles session resumption, PR detection, and limit reset waiting
 // Extracted from solve.mjs to keep files under 1500 lines
 
 // Use use-m to dynamically import modules for cross-runtime compatibility
@@ -103,9 +104,9 @@ export const autoContinueWhenLimitResets = async (issueUrl, sessionId, argv, sho
       sessionId,
     ];
 
-    // Preserve auto-continue flag
-    if (argv.autoContinueOnLimitReset) {
-      resumeArgs.push('--auto-continue-on-limit-reset');
+    // Preserve auto-resume flag
+    if (argv.autoResumeOnLimitReset) {
+      resumeArgs.push('--auto-resume-on-limit-reset');
     }
 
     // Preserve other flags from original invocation

package/src/solve.config.lib.mjs

@@ -145,9 +145,9 @@ export const createYargsConfig = yargsInstance => {
         description: 'Continue with existing PR when issue URL is provided (instead of creating new PR)',
         default: true,
       })
-      .option('auto-continue-on-limit-reset', {
+      .option('auto-resume-on-limit-reset', {
         type: 'boolean',
-        description: 'Automatically continue when AI tool limit resets (calculates reset time and waits)',
+        description: 'Automatically resume when AI tool limit resets (calculates reset time and waits)',
         default: false,
       })
       .option('auto-resume-on-errors', {
@@ -278,6 +278,11 @@ export const createYargsConfig = yargsInstance => {
         description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
         default: false,
       })
+      .option('prompt-architecture-care', {
+        type: 'boolean',
+        description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
+        default: false,
+      })
       .option('prompt-case-studies', {
         type: 'boolean',
         description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',

package/src/solve.mjs

@@ -892,10 +892,10 @@ try {
 
   // Handle limit reached scenario
   if (limitReached) {
-    const shouldAutoContinueOnReset = argv.autoContinueOnLimitReset;
+    const shouldAutoResumeOnReset = argv.autoResumeOnLimitReset;
 
-    // If limit was reached but auto-continue-on-limit-reset is NOT enabled, fail immediately
-    if (!shouldAutoContinueOnReset) {
+    // If limit was reached but auto-resume-on-limit-reset is NOT enabled, fail immediately
+    if (!shouldAutoResumeOnReset) {
       await log('\n❌ USAGE LIMIT REACHED!');
       await log('   The AI tool has reached its usage limit.');
 
@@ -972,9 +972,9 @@ try {
         }
       }
 
-      await safeExit(1, 'Usage limit reached - use --auto-continue-on-limit-reset to wait for reset');
+      await safeExit(1, 'Usage limit reached - use --auto-resume-on-limit-reset to wait for reset');
     } else {
-      // auto-continue-on-limit-reset is enabled - attach logs and/or post waiting comment
+      // auto-resume-on-limit-reset is enabled - attach logs and/or post waiting comment
       if (prNumber && global.limitResetTime) {
         // If --attach-logs is enabled, upload logs with usage limit details
         if (shouldAttachLogs && sessionId) {
@@ -1030,7 +1030,7 @@ try {
             // Build Claude CLI resume command
             const tool = argv.tool || 'claude';
             const resumeCmd = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
-            const waitingComment = `⏳ **Usage Limit Reached - Waiting to Continue**\n\nThe AI tool has reached its usage limit. Auto-continue is enabled with \`--auto-continue-on-limit-reset\`.\n\n**Reset time:** ${global.limitResetTime}\n**Wait time:** ${formatWaitTime(waitMs)} (days:hours:minutes:seconds)\n\nThe session will automatically resume when the limit resets.\n\nSession ID: \`${sessionId}\`${resumeCmd ? `\n\nTo resume manually:\n\`\`\`bash\n${resumeCmd}\n\`\`\`` : ''}`;
+            const waitingComment = `⏳ **Usage Limit Reached - Waiting to Continue**\n\nThe AI tool has reached its usage limit. Auto-resume is enabled with \`--auto-resume-on-limit-reset\`.\n\n**Reset time:** ${global.limitResetTime}\n**Wait time:** ${formatWaitTime(waitMs)} (days:hours:minutes:seconds)\n\nThe session will automatically resume when the limit resets.\n\nSession ID: \`${sessionId}\`${resumeCmd ? `\n\nTo resume manually:\n\`\`\`bash\n${resumeCmd}\n\`\`\`` : ''}`;
 
             const commentResult = await $`gh pr comment ${prNumber} --repo ${owner}/${repo} --body ${waitingComment}`;
             if (commentResult.code === 0) {
@@ -1044,9 +1044,9 @@ try {
     }
   }
 
-  // Handle failure cases, but skip exit if limit reached with auto-continue enabled
+  // Handle failure cases, but skip exit if limit reached with auto-resume enabled
   // This allows the code to continue to showSessionSummary() where autoContinueWhenLimitResets() is called
-  const shouldSkipFailureExitForAutoLimitContinue = limitReached && argv.autoContinueOnLimitReset;
+  const shouldSkipFailureExitForAutoLimitContinue = limitReached && argv.autoResumeOnLimitReset;
 
   if (!success && !shouldSkipFailureExitForAutoLimitContinue) {
     // Show claude resume command only for --tool claude (or default) on failure

package/src/solve.repository.lib.mjs

@@ -1171,7 +1171,7 @@ export const checkoutPrBranch = async (tempDir, branchName, prForkRemote, prFork
 // Cleanup temporary directory
 export const cleanupTempDirectory = async (tempDir, argv, limitReached) => {
   // Determine if we should skip cleanup
-  const shouldKeepDirectory = !argv.autoCleanup || argv.resume || limitReached || (argv.autoContinueOnLimitReset && global.limitResetTime);
+  const shouldKeepDirectory = !argv.autoCleanup || argv.resume || limitReached || (argv.autoResumeOnLimitReset && global.limitResetTime);
 
   if (!shouldKeepDirectory) {
     try {

package/src/solve.results.lib.mjs

@@ -27,7 +27,7 @@ import { safeExit } from './exit-handler.lib.mjs';
 const githubLib = await import('./github.lib.mjs');
 const { sanitizeLogContent, attachLogToGitHub } = githubLib;
 
-// Import auto-continue functions
+// Import continuation functions (session resumption, PR detection)
 const autoContinue = await import('./solve.auto-continue.lib.mjs');
 const { autoContinueWhenLimitResets } = autoContinue;
 
@@ -354,7 +354,6 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
   if (sessionId) {
     await log(`✅ Session ID: ${sessionId}`);
     // Always use absolute path for log file display
-    const path = await use('path');
     const absoluteLogPath = path.resolve(getLogFile());
     await log(`✅ Complete log file: ${absoluteLogPath}`);
 
@@ -376,8 +375,8 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
     if (limitReached) {
       await log('⏰ LIMIT REACHED DETECTED!');
 
-      if (argv.autoContinueOnLimitReset && global.limitResetTime) {
-        await log(`\n🔄 AUTO-CONTINUE ON LIMIT RESET ENABLED - Will resume at ${global.limitResetTime}`);
+      if (argv.autoResumeOnLimitReset && global.limitResetTime) {
+        await log(`\n🔄 AUTO-RESUME ON LIMIT RESET ENABLED - Will resume at ${global.limitResetTime}`);
         await autoContinueWhenLimitResets(issueUrl, sessionId, argv, shouldAttachLogs);
       } else {
         if (global.limitResetTime) {
@@ -402,7 +401,12 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
 
     // Don't show log preview, it's too technical
   } else {
-    await log('❌ No session ID extracted');
+    // For agent tool, session IDs may not be meaningful for resuming, so don't show as error
+    if (argv.tool !== 'agent') {
+      await log('❌ No session ID extracted');
+    } else {
+      await log('ℹ️  Agent tool completed (session IDs not used for resuming)');
+    }
     // Always use absolute path for log file display
     const logFilePath = path.resolve(getLogFile());
     await log(`📁 Log file available: ${logFilePath}`);