internaltool-mcp 1.6.29 → 1.6.31

package/index.js

@@ -760,8 +760,20 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
       }
 
       if (!confirmed) {
+        // Include any project-level decomposition templates as hints
+        const projectRes = task.project?._id || task.project
+        let decompositionTemplates = []
+        try {
+          const projRes = await apiWithRetry(() => api.get(`/api/projects/${projectRes}`))
+          decompositionTemplates = projRes?.data?.project?.agentConfig?.decompositionTemplates || []
+        } catch { /* non-fatal */ }
+
         return text({
           decomposition: executionPlan,
+          decompositionTemplates: decompositionTemplates.length > 0 ? {
+            note: 'These project templates may match your task. Use them as a starting point for subtaskPlan.',
+            templates: decompositionTemplates,
+          } : null,
           warnings: [
             !executionPlan.scoutReportPresent ? '⚠️  No scout report on this task. Consider running a scout agent first to map the codebase before builders start.' : null,
             !executionPlan.readmePresent ? '⚠️  No implementation plan (README). Builders need a spec to work from.' : null,
@@ -798,8 +810,8 @@ Call confirmed=false to preview the decomposition, confirmed=true to save it.`,
         subtasksCreated: subtaskPlan.length,
         message: `Decomposition saved. ${subtaskPlan.length} subtask(s) added to the board.`,
         nextStep: parallelGroups.length > 0
-          ? `⚡ COORDINATOR: Call get_parallel_kickoffs with taskId="${taskId}" NOW. It returns ready-to-paste prompts for each builder window. DO NOT implement code yourself — your job is to coordinate only.`
-          : `Call get_parallel_kickoffs with taskId="${taskId}" to get the builder prompt. DO NOT implement code yourself.`,
+          ? `⚡ COORDINATOR: Call get_parallel_kickoffs with taskId="${taskId}" NOW. It writes Cursor Background Agent files for each parallel builder automatically. Then tell the user to open Background Agents panel (⌘⇧J) and click Start. DO NOT implement code yourself.`
+          : `Call get_parallel_kickoffs with taskId="${taskId}". It writes a Cursor Background Agent file for the builder. Tell the user to open Background Agents panel (⌘⇧J) and start it.`,
       })
     }
   )
@@ -927,17 +939,32 @@ Returns systemPrompt ready to use as a Claude system prompt.`,
         } catch { /* non-fatal */ }
       }
 
+      // Suggest relevant skills based on role and available project skills
+      const availableSkills = ctx.project?.agentConfig?.skills || []
+      const suggestedSkills = availableSkills.length > 0
+        ? availableSkills.map(s => ({
+            name: s.name,
+            description: s.description,
+            path: `.cursor/skills/${s.name}.md`,
+          }))
+        : effectiveRole === 'builder'
+          ? [{ name: 'run-tests', description: 'How to run and validate tests', path: '.cursor/skills/run-tests.md' }]
+          : effectiveRole === 'scout'
+            ? [{ name: 'scout-codebase', description: 'How to systematically explore and map the codebase', path: '.cursor/skills/scout-codebase.md' }]
+            : []
+
       return text({
-        role:           effectiveRole,
-        taskKey:        ctx.taskKey,
-        taskTitle:      ctx.taskTitle,
-        systemPrompt:   parts.join('\n\n'),
-        allowedTools:   ctx.customAllowedTools || null,
-        claimedFiles:   ctx.task?.claimedFiles || [],
-        warnings:       ctx.warnings || [],
-        task:           ctx.task,
-        project:        ctx.project,
-        usage: 'Use systemPrompt as your Claude system prompt. If allowedTools is set, restrict your MCP tool calls to that list.',
+        role:            effectiveRole,
+        taskKey:         ctx.taskKey,
+        taskTitle:       ctx.taskTitle,
+        systemPrompt:    parts.join('\n\n'),
+        allowedTools:    ctx.customAllowedTools || null,
+        claimedFiles:    ctx.task?.claimedFiles || [],
+        warnings:        ctx.warnings || [],
+        suggestedSkills,
+        task:            ctx.task,
+        project:         ctx.project,
+        usage: 'Use systemPrompt as your Claude system prompt. If allowedTools is set, restrict your MCP tool calls to that list. Read and follow each skill in suggestedSkills before starting work.',
       })
     }
   )
@@ -1541,16 +1568,15 @@ The log is visible in InternalTool under the task's Session tab — gives the hu
   // ── get_parallel_kickoffs ─────────────────────────────────────────────────────
   server.tool(
     'get_parallel_kickoffs',
-    `Read the decomposition plan and return ready-to-paste Cursor Agent prompts for the next group of parallel subtasks.
+    `Read the decomposition plan, write Cursor Background Agent files for each parallel subtask, and return instructions.
 
 COORDINATOR WORKFLOW:
 1. Call decompose_task to create the plan
-2. Call get_parallel_kickoffs to get one paste-ready prompt per parallel subtask
-3. Tell the user exactly how many new Cursor Agent windows to open
-4. Give them each prompt to paste — one window per subtask
+2. Call get_parallel_kickoffs — it writes .cursor/agents/builder-N.md files automatically
+3. Open the Cursor Background Agents panel (⌘⇧J or ⌘⇧P → "Background Agents")
+4. Click "Start" for each builder agent — they run in parallel in the background
 
-Cursor cannot spawn agent windows automatically. This tool generates the prompts;
-the human opens the windows. Each builder agent then runs independently.`,
+The agent files are fully self-contained: each builder knows exactly what MCP tools to call.`,
     {
       taskId: z.string().describe("Task's MongoDB ObjectId"),
     },
@@ -1635,15 +1661,19 @@ the human opens the windows. Each builder agent then runs independently.`,
           ``,
           `Do these steps immediately in order — do not ask for confirmation, do not skip any step:`,
           ``,
-          `1. Call kickoff_task with taskId "${taskId}", agentRole "builder", confirmed true`,
-          `2. Call claim_files with taskId "${taskId}" and files [${filesArg}]`,
-          `3. Call get_agent_context with taskId "${taskId}" to read the full task plan`,
-          `4. Implement the subtask: ${st.description || st.title}`,
+          `1. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} started: ${st.title}"`,
+          `2. Call kickoff_task with taskId "${taskId}", agentRole "builder", confirmed true`,
+          `3. Call claim_files with taskId "${taskId}" and files [${filesArg}]`,
+          `4. Call get_agent_context with taskId "${taskId}" to read the full task plan and suggested skills`,
+          `5. Implement the subtask: ${st.description || st.title}`,
           `   - You may ONLY modify these files: ${fileListPlain}`,
           `   - Do NOT touch any other file`,
-          `5. Run npm test — all tests must pass before continuing`,
-          `6. Call commit_helper with taskId "${taskId}"`,
-          `7. Call update_task with taskId "${taskId}" and mark the subtask "${st.title}" as done`,
+          `   - Follow any skills listed in get_agent_context suggestedSkills`,
+          `6. Run npm test — all tests must pass before continuing`,
+          `7. Call commit_helper with taskId "${taskId}"`,
+          `8. Call update_task with taskId "${taskId}" and mark the subtask "${st.title}" as done`,
+          `9. Call resume_task with taskId "${taskId}", agentRole "reviewer", confirmed true — transition to reviewer role`,
+          `10. Call log_session_event with taskId "${taskId}", type "subagent", name "builder-${i + 1}", summary "Builder ${i + 1} finished: ${st.title}"`,
           ``,
           `You are builder ${i + 1} of ${parallelCount} running in parallel. Another builder is working on different files at the same time.`,
         ].join('\n')
@@ -1651,19 +1681,45 @@ the human opens the windows. Each builder agent then runs independently.`,
         return { subtask: st.title, role: st.role || 'builder', files: st.files || [], prompt }
       })
 
+      // Write each builder prompt as a Cursor Background Agent file in .cursor/agents/
+      // Cursor Background Agents panel reads these files and lets you start each one independently.
+      const repoRoot = process.cwd()
+      const agentsDir = join(repoRoot, '.cursor', 'agents')
+      mkdirSync(agentsDir, { recursive: true })
+
+      const writtenFiles = []
+      kickoffs.forEach((k, i) => {
+        const safeName = k.subtask.replace(/[^a-zA-Z0-9-_]/g, '-').replace(/-+/g, '-').slice(0, 40)
+        const fileName = `builder-${i + 1}-${safeName}.md`
+        const filePath = join(agentsDir, fileName)
+
+        const agentFileContent = [
+          `---`,
+          `description: Builder ${i + 1} of ${parallelCount} — ${k.subtask} (${task.key})`,
+          `---`,
+          ``,
+          k.prompt,
+        ].join('\n')
+
+        writeFileSync(filePath, agentFileContent, 'utf8')
+        writtenFiles.push({ index: i + 1, file: `.cursor/agents/${fileName}`, subtask: k.subtask })
+      })
+
       // Build the human-facing instruction block
-      const howToOpen = [
-        `In Cursor, open ${parallelCount} new Agent windows:`,
-        `  • Mac:     Cmd+Shift+P → "New Agent" (or click "+" in the Composer panel)`,
-        `  • Windows: Ctrl+Shift+P → "New Agent"`,
+      const howToStart = [
+        `✅ ${parallelCount} builder agent file(s) written to .cursor/agents/`,
+        ``,
+        `TO START PARALLEL BUILDERS IN CURSOR:`,
+        `  1. Open Background Agents panel: ⌘⇧J  (or ⌘⇧P → "Background Agents")`,
+        `  2. You'll see ${parallelCount} new builder agent(s) listed`,
+        `  3. Click "Start" for each one — they run in parallel automatically`,
         ``,
-        ...kickoffs.map((k, i) => `Window ${i + 1}: paste the prompt for subtask "${k.subtask}"`),
+        ...writtenFiles.map(f => `  • Builder ${f.index}: "${f.subtask}"  →  ${f.file}`),
         ``,
-        `Each window will independently call kickoff_task → claim_files → implement → commit.`,
-        `They run at the same time — you don't need to wait for one to finish before starting the other.`,
+        `Each builder calls kickoff_task → claim_files → implements → runs tests → commits.`,
+        `They work on different files simultaneously — no need to wait for one before starting the other.`,
         ``,
-        `After BOTH windows finish and commit, come back to this coordinator window and call:`,
-        `  get_parallel_kickoffs(taskId="${taskId}")`,
+        `After all builders finish, come back here and call get_parallel_kickoffs again`,
         `to get the next group's prompts.`,
       ].join('\n')
 
@@ -1672,17 +1728,104 @@ the human opens the windows. Each builder agent then runs independently.`,
         totalGroups:   execOrder.length,
         isParallel,
         parallelCount,
-        READ_THIS_FIRST: '👇 READ THIS BEFORE DOING ANYTHING',
+        READ_THIS_FIRST: '⚡ BUILDER AGENT FILES WRITTEN — SEE INSTRUCTIONS BELOW',
         COORDINATOR_INSTRUCTION: isParallel
-          ? `⚡ GROUP ${nextGroupIndex} of ${execOrder.length}: ${parallelCount} subtasks run IN PARALLEL.\n\n${howToOpen}`
-          : `GROUP ${nextGroupIndex} of ${execOrder.length}: 1 sequential subtask.\nOpen 1 new Agent window and paste the prompt below.`,
-        kickoffs: kickoffs.map((k, i) => ({
-          window:  i + 1,
-          subtask: k.subtask,
-          role:    k.role,
-          files:   k.files,
-          PASTE_THIS_IN_NEW_AGENT_WINDOW: k.prompt,
-        })),
+          ? `⚡ GROUP ${nextGroupIndex} of ${execOrder.length}: ${parallelCount} builders written as Cursor Background Agents.\n\n${howToStart}`
+          : `GROUP ${nextGroupIndex} of ${execOrder.length}: 1 sequential builder written as a Cursor Background Agent.\n\n${howToStart}`,
+        agentFilesWritten: writtenFiles,
+      })
+    }
+  )
+
+  // ── wait_for_group ─────────────────────────────────────────────────────────────
+  server.tool(
+    'wait_for_group',
+    `Poll until all subtasks in a decomposition group are marked done. Use after get_parallel_kickoffs.
+
+COORDINATOR WORKFLOW:
+1. Call get_parallel_kickoffs — writes builder agent files, user starts them
+2. Call wait_for_group with the groupIndex returned — blocks until all builders finish
+3. Call get_parallel_kickoffs again for the next group
+
+Polls every 10 s, times out after 30 min by default. Returns immediately if already done.`,
+    {
+      taskId:        z.string().describe("Task's MongoDB ObjectId"),
+      groupIndex:    z.number().int().min(1).describe('1-based group number to wait for (matches group from get_parallel_kickoffs)'),
+      pollIntervalMs: z.number().optional().default(10000).describe('Poll interval in ms (default 10 s)'),
+      timeoutMs:      z.number().optional().default(1800000).describe('Max wait in ms (default 30 min)'),
+    },
+    async ({ taskId, groupIndex, pollIntervalMs = 10000, timeoutMs = 1800000 }) => {
+      trackTaskActivity(taskId, 'wait_for_group', { summary: `Waiting for Group ${groupIndex}` })
+      const deadline = Date.now() + timeoutMs
+      let attempts   = 0
+
+      while (Date.now() < deadline) {
+        attempts++
+        const taskRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+        if (!taskRes?.success) return errorText('Task not found')
+        const task = taskRes.data.task
+
+        if (!task.decomposition?.trim()) return errorText('No decomposition found. Call decompose_task first.')
+        let dec
+        try { dec = JSON.parse(task.decomposition) } catch {
+          return errorText('Decomposition JSON is malformed.')
+        }
+
+        const execOrder  = dec.executionOrder || []
+        const targetGroup = execOrder[groupIndex - 1]
+        if (!targetGroup) return errorText(`Group ${groupIndex} does not exist. Decomposition has ${execOrder.length} group(s).`)
+
+        const boardSubtasks = task.subtasks || []
+        const isDone = (title) => boardSubtasks.some(s => s.done && (s.title === title || s.title.endsWith(title)))
+
+        const doneTitles    = targetGroup.filter(t => isDone(t))
+        const pendingTitles = targetGroup.filter(t => !isDone(t))
+
+        if (pendingTitles.length === 0) {
+          return text({
+            done:     true,
+            group:    groupIndex,
+            subtasks: targetGroup,
+            done_count: doneTitles.length,
+            attempts,
+            message: `✅ All ${targetGroup.length} subtask(s) in Group ${groupIndex} are done after ${attempts} poll(s).`,
+            nextStep: groupIndex < execOrder.length
+              ? `Call get_parallel_kickoffs with taskId="${taskId}" to get Group ${groupIndex + 1}'s builder prompts.`
+              : 'All groups complete. Run final tests then call raise_pr.',
+          })
+        }
+
+        // Log progress every 6 polls (~1 min)
+        if (attempts % 6 === 0) {
+          trackTaskActivity(taskId, 'wait_for_group', {
+            summary: `Still waiting for Group ${groupIndex}: ${pendingTitles.length} pending (${doneTitles.length}/${targetGroup.length} done)`,
+          })
+        }
+
+        if (Date.now() + pollIntervalMs < deadline) {
+          await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+        } else {
+          break
+        }
+      }
+
+      // Timed out — fetch final state
+      const finalRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+      const finalTask = finalRes?.data?.task
+      let finalDec
+      try { finalDec = JSON.parse(finalTask?.decomposition || '{}') } catch { finalDec = {} }
+      const finalGroup   = (finalDec.executionOrder || [])[groupIndex - 1] || []
+      const finalBoard   = finalTask?.subtasks || []
+      const finalIsDone  = (t) => finalBoard.some(s => s.done && (s.title === t || s.title.endsWith(t)))
+      const stillPending = finalGroup.filter(t => !finalIsDone(t))
+
+      return text({
+        timedOut:   true,
+        group:      groupIndex,
+        pending:    stillPending,
+        attempts,
+        message:    `⏱ Timed out after ${attempts} poll(s). ${stillPending.length} subtask(s) still pending: ${stillPending.join(', ')}`,
+        hint:       'Check the Background Agents panel — a builder may have crashed. Call wait_for_group again to resume waiting, or proceed manually.',
       })
     }
   )
@@ -3009,11 +3152,18 @@ You are a COORDINATOR agent. Your behavioral constraints for this session:
 - Bypass the decomposition step — always decompose before builders start
 - Start coding without a scout report when the codebase is unfamiliar
 
+**PARALLEL BUILDER WORKFLOW:**
+1. Call decompose_task — creates subtasks with file ownership
+2. Call get_parallel_kickoffs — writes .cursor/agents/builder-N.md files automatically
+3. Tell the user: "Open Background Agents panel (⌘⇧J) and click Start for each builder"
+4. Wait for builders to finish, then call get_parallel_kickoffs again for the next group
+
 **WORK STYLE:**
 - Start with decompose_task to get the structured execution plan
 - Ensure no two builder subtasks claim the same file
 - Scout report must exist before builders begin
-- Each builder subtask must have explicit file ownership and a clear scope`,
+- Each builder subtask must have explicit file ownership and a clear scope
+- NEVER implement code yourself — your job ends after get_parallel_kickoffs writes the agent files`,
 }
 
 /** Write task-specific cursor rules to .cursor/rules/<taskKey>.mdc in the local repo root.
@@ -4528,6 +4678,19 @@ branchAction values (only needed when current branch ≠ task branch):
         ...unsafeUntracked.map(f => `⚠️ SKIP:   ${f}  ← do not commit this`),
       ]
 
+      // ── Claims validation ─────────────────────────────────────────────────────
+      // If this task has claimed files, warn if staged changes include unclaimed files.
+      let claimsViolations = []
+      if (taskId) {
+        try {
+          const claimRes = await apiWithRetry(() => api.get(`/api/tasks/${taskId}`))
+          const claimedFiles = claimRes?.data?.task?.claimedFiles || []
+          if (claimedFiles.length > 0) {
+            claimsViolations = changedFilesList.filter(f => !claimedFiles.some(cf => f.endsWith(cf) || cf.endsWith(f)))
+          }
+        } catch { /* non-fatal */ }
+      }
+
       // ── Block if task is parked — prevent Dev A pushing after handoff ────────
       if (task) {
         const isParked      = !!(task.parkNote?.parkedAt)
@@ -4640,6 +4803,11 @@ branchAction values (only needed when current branch ≠ task branch):
             : null,
           commands: [addCmd, `git commit -m "${commitMsg}"`, pushCmd].filter(Boolean),
           requiresConfirmation: true,
+          claimsViolations: claimsViolations.length > 0 ? {
+            warning: `⚠️ ${claimsViolations.length} file(s) in your staged changes are NOT in your claimed files list. You may only edit claimed files.`,
+            unclaimed: claimsViolations,
+            claimedFiles: changedFilesList.filter(f => !claimsViolations.includes(f)),
+          } : null,
           message: `Suggested: "${commitMsg}". Call commit_helper again with confirmed=true to get the final commands.`,
         })
       }
@@ -4706,6 +4874,10 @@ branchAction values (only needed when current branch ≠ task branch):
         unsafeUntrackedWarning: unsafeUntracked.length
           ? `These were excluded from git add — add them to .gitignore: ${unsafeUntracked.join(', ')}`
           : null,
+        claimsViolations: claimsViolations.length > 0 ? {
+          warning: `⚠️ ${claimsViolations.length} file(s) modified that are NOT in your claimed files. Review before committing.`,
+          unclaimed: claimsViolations,
+        } : null,
         message:  `Copy-paste these commands in order.`,
         nextStep: taskBranch && !branchMismatch ? `After pushing, call raise_pr to open the pull request.` : null,
       })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "internaltool-mcp",
-  "version": "1.6.29",
+  "version": "1.6.31",
   "description": "MCP server for InternalTool — connect AI assistants (Claude Code, Cursor) to your project and task management platform",
   "type": "module",
   "main": "index.js",