@claudetools/tools 0.3.8 → 0.4.0

package/dist/helpers/tasks.js

@@ -2,7 +2,7 @@
 // Task Management System
 // =============================================================================
 import { apiRequest } from './api-client.js';
-import { matchTaskToWorker } from './workers.js';
+import { matchTaskToWorker, buildWorkerPrompt } from './workers.js';
 export function parseJsonArray(value) {
     if (!value)
         return [];
@@ -90,14 +90,57 @@ export async function heartbeatTask(userId, projectId, taskId, agentId, extendMi
 // -----------------------------------------------------------------------------
 // Orchestration Functions
 // -----------------------------------------------------------------------------
+// Configuration: Default maximum parallel tasks
+export const DEFAULT_MAX_PARALLEL = 5;
+/**
+ * Get count of currently active tasks
+ * Returns both in_progress and claimed (locked) task counts
+ */
+export async function getActiveTaskCount(userId, projectId, epicId) {
+    // Get all in_progress tasks
+    const inProgressResult = await listTasks(userId, projectId, {
+        status: 'in_progress',
+        parent_id: epicId,
+        limit: 100,
+    });
+    let inProgressCount = 0;
+    let claimedCount = 0;
+    if (inProgressResult.success && inProgressResult.data.length > 0) {
+        const now = new Date();
+        for (const task of inProgressResult.data) {
+            inProgressCount++;
+            // Check if task is also claimed (has valid lock)
+            if (task.assigned_to && task.lock_expires_at) {
+                const lockExpires = new Date(task.lock_expires_at);
+                if (lockExpires > now) {
+                    claimedCount++;
+                }
+            }
+        }
+    }
+    return {
+        inProgress: inProgressCount,
+        claimed: claimedCount,
+        total: inProgressCount,
+    };
+}
 /**
  * Get all tasks ready for parallel dispatch
  * - Filters for 'ready' status
  * - Excludes already claimed tasks
  * - Resolves dependencies (only returns unblocked tasks)
  * - Matches each to appropriate expert worker
+ * - Respects max parallel limit by considering currently active tasks
  */
-export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = 5) {
+export async function getDispatchableTasks(userId, projectId, epicId, maxParallel = DEFAULT_MAX_PARALLEL) {
+    // Get current active task count
+    const activeCount = await getActiveTaskCount(userId, projectId, epicId);
+    // Calculate remaining capacity
+    const remainingCapacity = maxParallel - activeCount.total;
+    if (remainingCapacity <= 0) {
+        // No capacity available, return empty array
+        return [];
+    }
     // Get all tasks with 'ready' status
     const result = await listTasks(userId, projectId, {
         status: 'ready',
@@ -152,7 +195,8 @@ export async function getDispatchableTasks(userId, projectId, epicId, maxParalle
             parentContext: taskData.parent,
             dependencies: [],
         });
-        if (dispatchable.length >= maxParallel) {
+        // Only dispatch tasks that fit within remaining capacity
+        if (dispatchable.length >= remainingCapacity) {
             break;
         }
     }
@@ -184,46 +228,29 @@ export async function getExecutionContext(userId, projectId, taskId) {
             siblingTasks = siblingResult.data.filter(t => t.id !== taskId);
         }
     }
-    // Build system prompt
-    let systemPrompt = worker.promptTemplate + '\n\n';
-    systemPrompt += `# Task: ${task.title}\n\n`;
-    if (task.description) {
-        systemPrompt += `## Description\n${task.description}\n\n`;
-    }
-    // Add acceptance criteria
-    const criteria = parseJsonArray(task.acceptance_criteria);
-    if (criteria.length > 0) {
-        systemPrompt += `## Acceptance Criteria\n`;
-        criteria.forEach((c, i) => {
-            systemPrompt += `${i + 1}. ${c}\n`;
-        });
-        systemPrompt += '\n';
-    }
-    // Add parent context
-    if (taskData.parent) {
-        systemPrompt += `## Epic Context\n`;
-        systemPrompt += `**Epic:** ${taskData.parent.title}\n`;
-        if (taskData.parent.description) {
-            systemPrompt += `**Goal:** ${taskData.parent.description}\n`;
-        }
-        systemPrompt += '\n';
-    }
-    // Add attached context
-    if (taskData.context.length > 0) {
-        systemPrompt += `## Attached Context\n`;
-        for (const ctx of taskData.context) {
-            systemPrompt += `### ${ctx.context_type.toUpperCase()}${ctx.source ? ` (${ctx.source})` : ''}\n`;
-            systemPrompt += `${ctx.content}\n\n`;
-        }
-    }
-    // Add sibling task awareness
-    if (siblingTasks && siblingTasks.length > 0) {
-        systemPrompt += `## Related Tasks (for awareness)\n`;
-        for (const sibling of siblingTasks.slice(0, 5)) {
-            systemPrompt += `- ${sibling.title} [${sibling.status}]\n`;
-        }
-        systemPrompt += '\n';
-    }
+    // Build structured system prompt using the template system
+    const systemPrompt = buildWorkerPrompt({
+        task: {
+            id: task.id,
+            title: task.title,
+            description: task.description || undefined,
+            acceptance_criteria: task.acceptance_criteria,
+        },
+        worker,
+        epicContext: taskData.parent ? {
+            title: taskData.parent.title,
+            description: taskData.parent.description || undefined,
+        } : undefined,
+        attachedContext: taskData.context.map(ctx => ({
+            type: ctx.context_type,
+            content: ctx.content,
+            source: ctx.source || undefined,
+        })),
+        siblingTasks: siblingTasks?.slice(0, 5).map(s => ({
+            title: s.title,
+            status: s.status,
+        })),
+    });
     return {
         task,
         worker,
@@ -234,20 +261,20 @@ export async function getExecutionContext(userId, projectId, taskId) {
     };
 }
 /**
- * Find newly unblocked tasks after a completion
+ * Find newly unblocked tasks after a completion and update their status to ready
  */
 export async function resolveTaskDependencies(userId, projectId, completedTaskId, epicId) {
-    // Get all tasks that might be blocked by the completed task
-    const result = await listTasks(userId, projectId, {
-        status: 'ready', // or 'blocked'
+    // Get all blocked tasks that might be unblocked by the completed task
+    const blockedResult = await listTasks(userId, projectId, {
+        status: 'blocked',
         parent_id: epicId,
         limit: 50,
     });
-    if (!result.success) {
+    if (!blockedResult.success) {
         return [];
     }
     const newlyUnblocked = [];
-    for (const task of result.data) {
+    for (const task of blockedResult.data) {
         const blockedBy = parseJsonArray(task.blocked_by);
         // Check if this task was blocked by the completed task
         if (blockedBy.includes(completedTaskId)) {
@@ -265,10 +292,79 @@ export async function resolveTaskDependencies(userId, projectId, completedTaskId
                     }
                 }
             }
+            // If all blockers are complete, update task status to ready
             if (allBlockersComplete) {
-                newlyUnblocked.push(task);
+                const updateResult = await updateTaskStatus(userId, projectId, task.id, 'ready');
+                if (updateResult.success) {
+                    newlyUnblocked.push(updateResult.data);
+                }
             }
         }
     }
     return newlyUnblocked;
 }
+/**
+ * Get epic status with progress tracking
+ * Auto-completes epic if all child tasks are done
+ */
+export async function getEpicStatus(userId, projectId, epicId) {
+    // Get the epic
+    const epicResult = await getTask(userId, projectId, epicId);
+    if (!epicResult.success) {
+        throw new Error(`Epic not found: ${epicId}`);
+    }
+    const epic = epicResult.data;
+    // Verify it's an epic
+    if (epic.type !== 'epic') {
+        throw new Error(`Task ${epicId} is not an epic (type: ${epic.type})`);
+    }
+    // Get all child tasks
+    const tasksResult = await listTasks(userId, projectId, {
+        parent_id: epicId,
+        limit: 100,
+    });
+    if (!tasksResult.success) {
+        return {
+            epic,
+            totalTasks: 0,
+            byStatus: {},
+            percentComplete: 0,
+            allComplete: false,
+            autoCompleted: false,
+        };
+    }
+    const tasks = tasksResult.data;
+    const totalTasks = tasks.length;
+    // Count by status
+    const byStatus = {
+        backlog: 0,
+        ready: 0,
+        in_progress: 0,
+        blocked: 0,
+        review: 0,
+        done: 0,
+        cancelled: 0,
+    };
+    for (const task of tasks) {
+        byStatus[task.status] = (byStatus[task.status] || 0) + 1;
+    }
+    // Calculate progress
+    const doneCount = byStatus.done || 0;
+    const percentComplete = totalTasks > 0 ? Math.round((doneCount / totalTasks) * 100) : 0;
+    const allComplete = totalTasks > 0 && doneCount === totalTasks;
+    // Auto-complete epic if all tasks done and epic not already done
+    let autoCompleted = false;
+    if (allComplete && epic.status !== 'done') {
+        await updateTaskStatus(userId, projectId, epicId, 'done', 'system:auto-complete');
+        epic.status = 'done';
+        autoCompleted = true;
+    }
+    return {
+        epic,
+        totalTasks,
+        byStatus,
+        percentComplete,
+        allComplete,
+        autoCompleted,
+    };
+}

package/dist/helpers/workers.d.ts

@@ -7,6 +7,31 @@ export interface ExpertWorker {
     promptTemplate: string;
 }
 export declare const EXPERT_WORKERS: Record<string, ExpertWorker>;
+/**
+ * Build a structured worker prompt that includes task context, protocol, error handling
+ */
+export declare function buildWorkerPrompt(params: {
+    task: {
+        id: string;
+        title: string;
+        description?: string;
+        acceptance_criteria?: string | string[];
+    };
+    worker: ExpertWorker;
+    epicContext?: {
+        title: string;
+        description?: string;
+    };
+    attachedContext?: Array<{
+        type: string;
+        content: string;
+        source?: string;
+    }>;
+    siblingTasks?: Array<{
+        title: string;
+        status: string;
+    }>;
+}): string;
 /**
  * Match a task to the best expert worker based on domain patterns
  */

package/dist/helpers/workers.js

@@ -92,6 +92,86 @@ When complete, provide a concise summary of integrations configured.`,
 When complete, provide a concise summary of work done.`,
     },
 };
+/**
+ * Build a structured worker prompt that includes task context, protocol, error handling
+ */
+export function buildWorkerPrompt(params) {
+    const { task, worker, epicContext, attachedContext, siblingTasks } = params;
+    let prompt = '';
+    // Worker domain introduction
+    prompt += `${worker.promptTemplate}\n\n`;
+    prompt += `---\n\n`;
+    // Task header
+    prompt += `## Task: ${task.title}\n`;
+    prompt += `**Task ID:** ${task.id}\n\n`;
+    // Task description
+    if (task.description) {
+        prompt += `## Description\n${task.description}\n\n`;
+    }
+    // Acceptance criteria
+    const criteria = Array.isArray(task.acceptance_criteria)
+        ? task.acceptance_criteria
+        : (task.acceptance_criteria ? [task.acceptance_criteria] : []);
+    if (criteria.length > 0) {
+        prompt += `## Acceptance Criteria\n`;
+        criteria.forEach((criterion, index) => {
+            prompt += `${index + 1}. ${criterion}\n`;
+        });
+        prompt += '\n';
+    }
+    // Epic context
+    if (epicContext) {
+        prompt += `## Epic Context\n`;
+        prompt += `**Epic:** ${epicContext.title}\n`;
+        if (epicContext.description) {
+            prompt += `**Goal:** ${epicContext.description}\n`;
+        }
+        prompt += '\n';
+    }
+    // Attached context
+    if (attachedContext && attachedContext.length > 0) {
+        prompt += `## Attached Context\n`;
+        for (const ctx of attachedContext) {
+            prompt += `### ${ctx.type.toUpperCase()}${ctx.source ? ` (${ctx.source})` : ''}\n`;
+            prompt += `${ctx.content}\n\n`;
+        }
+    }
+    // Related tasks
+    if (siblingTasks && siblingTasks.length > 0) {
+        prompt += `## Related Tasks (for awareness)\n`;
+        for (const sibling of siblingTasks.slice(0, 5)) {
+            prompt += `- ${sibling.title} [${sibling.status}]\n`;
+        }
+        prompt += '\n';
+    }
+    // Protocol instructions
+    prompt += `## Protocol\n`;
+    prompt += `You MUST follow this protocol:\n\n`;
+    prompt += `1. **Start the task:** Call \`task_start(task_id="${task.id}", agent_id="<your-agent-id>")\` to claim this task\n`;
+    prompt += `2. **Complete the work:** Implement the requirements described above\n`;
+    prompt += `3. **Complete the task:** Call \`task_complete(task_id="${task.id}", summary="<detailed-summary>")\` with:\n`;
+    prompt += `   - What you implemented\n`;
+    prompt += `   - Files modified or created\n`;
+    prompt += `   - Any important decisions made\n`;
+    prompt += `   - Testing performed (if applicable)\n\n`;
+    // Error handling
+    prompt += `## Error Handling\n`;
+    prompt += `If you encounter blocking errors or issues:\n\n`;
+    prompt += `1. **Log the error:** Call \`task_add_context(task_id="${task.id}", context_type="work_log", content="ERROR: <description>", added_by="<your-agent-id>")\`\n`;
+    prompt += `2. **Release the task:** Call \`task_release(task_id="${task.id}", agent_id="<your-agent-id>", new_status="blocked", work_log="<summary-of-issue>")\`\n`;
+    prompt += `3. **Do NOT mark the task as complete** if the work is not finished\n\n`;
+    // Result format
+    prompt += `## Result Format\n`;
+    prompt += `When calling task_complete, your summary should include:\n\n`;
+    prompt += `- **Implementation:** What you built/changed\n`;
+    prompt += `- **Files:** List of modified files with paths\n`;
+    prompt += `- **Decisions:** Any architectural or design choices\n`;
+    prompt += `- **Testing:** How the changes were verified\n`;
+    prompt += `- **Notes:** Any caveats, limitations, or follow-up needed\n\n`;
+    prompt += `---\n\n`;
+    prompt += `**Begin work now. Remember to call task_start first!**\n`;
+    return prompt;
+}
 /**
  * Match a task to the best expert worker based on domain patterns
  */

package/dist/setup.js

@@ -589,7 +589,16 @@ CWD=$(pwd)
 PROJECT_ID=""
 PROJECT_NAME=""
 
-if [ -f "$PROJECTS_FILE" ]; then
+# Priority 1: Check .claude/CLAUDE.md for project ID (from claudetools init)
+CLAUDE_MD="$CWD/.claude/CLAUDE.md"
+if [ -f "$CLAUDE_MD" ]; then
+  # Extract project ID from format: **Project ID:** \\\`local_xxx\\\` or \\\`proj_xxx\\\`
+  # Use sed to extract text between backticks after "Project ID"
+  PROJECT_ID=$(grep "Project ID" "$CLAUDE_MD" 2>/dev/null | sed -n "s/.*\\\`\\([a-z0-9_]*\\)\\\`.*/\\1/p" | head -1)
+fi
+
+# Priority 2: Fall back to projects.json cache
+if [ -z "$PROJECT_ID" ] && [ -f "$PROJECTS_FILE" ]; then
   # Find project by path prefix match (use variable binding for jq startswith)
   # Use -c for compact output so head -1 gets complete JSON object
   PROJECT_DATA=$(jq -c --arg cwd "$CWD" '
@@ -684,12 +693,19 @@ API_KEY=$(jq -r '.apiKey // empty' "$CONFIG_FILE")
 
 if [ -z "$API_KEY" ]; then exit 0; fi
 
-# Get current project from projects.json
+# Get current project - check CLAUDE.md first, then projects.json
 PROJECT_FILE="$HOME/.claudetools/projects.json"
 CWD=$(pwd)
 PROJECT_ID=""
 
-if [ -f "$PROJECT_FILE" ]; then
+# Priority 1: Check .claude/CLAUDE.md for project ID (from claudetools init)
+CLAUDE_MD="$CWD/.claude/CLAUDE.md"
+if [ -f "$CLAUDE_MD" ]; then
+  PROJECT_ID=$(grep "Project ID" "$CLAUDE_MD" 2>/dev/null | sed -n "s/.*\\\`\\([a-z0-9_]*\\)\\\`.*/\\1/p" | head -1)
+fi
+
+# Priority 2: Fall back to projects.json cache
+if [ -z "$PROJECT_ID" ] && [ -f "$PROJECT_FILE" ]; then
   # Try to find project by path prefix (use variable binding for jq startswith)
   PROJECT_ID=$(jq -r --arg cwd "$CWD" '
     .bindings[]? | select(.local_path) |

package/dist/templates/claude-md.d.ts

@@ -5,7 +5,7 @@ export declare const PROJECT_SECTION_END = "<!-- CLAUDETOOLS:PROJECT:END -->";
 /**
  * Global CLAUDE.md content - added to ~/.claude/CLAUDE.md
  */
-export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system via the `claudetools_memory` MCP server. Use it to remember context across sessions.\n\n## Memory Tools\n\n### Searching Memory\n```\nmemory_search(query: \"authentication patterns\")\n```\nSearch for relevant facts, entities, and past context. Use this when:\n- Starting work on a feature to recall past decisions\n- Looking for patterns or conventions used before\n- Finding related code or architectural context\n\n### Storing Facts\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts as relationships between entities. Use for:\n- Architectural decisions\n- Code patterns and conventions\n- Dependencies and relationships\n- User preferences learned during conversation\n\n### Context Injection\nContext is automatically injected at the start of each session based on the current project. Check `~/.claudetools/session-context.md` for project-specific context.\n\n## Task Management\n\n### Creating Work Plans\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks.\n\n### Starting Tasks\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed.\n\n## Codebase Intelligence\n\n### Finding Code\n```\ncodebase_map()           # Get overview of project structure\ncodebase_find(\"UserService\")  # Find symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\n```\n\n### Impact Analysis\n```\nanalyze_impact(function_name: \"validateToken\")\n```\nSee what would be affected by changing a function.\n\n## Best Practices\n\n1. **Search before implementing** - Check memory for existing patterns\n2. **Store decisions** - Save architectural choices as facts\n3. **Use task tracking** - Break complex work into tasks\n4. **Complete tasks** - Always mark tasks done with summaries\n<!-- CLAUDETOOLS:END -->\n";
+export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system via the `claudetools_memory` MCP server. Use it to remember context across sessions.\n\n## Memory Tools\n\n### Searching Memory\n```\nmemory_search(query: \"authentication patterns\")\n```\nSearch for relevant facts, entities, and past context. Use this when:\n- Starting work on a feature to recall past decisions\n- Looking for patterns or conventions used before\n- Finding related code or architectural context\n\n### Storing Facts\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts as relationships between entities. Use for:\n- Architectural decisions\n- Code patterns and conventions\n- Dependencies and relationships\n- User preferences learned during conversation\n\n### Context Injection\nContext is automatically injected at the start of each session based on the current project. Check `~/.claudetools/session-context.md` for project-specific context.\n\n## Task Management\n\n### Creating Work Plans with Auto-Dispatch\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks. **Tasks are automatically set to `ready` status.**\n\nAfter `task_plan` completes, you will receive Task tool invocations to spawn parallel agents.\n**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.\n\n### Parallel Agent Workflow\n1. User describes work needed\n2. Call `task_plan_draft` to present the plan\n3. User says \"go\" to approve\n4. Call `task_plan` - tasks created in `ready` status\n5. Execute the provided Task tool calls in ONE message\n6. Agents work in parallel, each calling `task_complete` when done\n\n### Manual Task Start (Sequential)\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it. Use for sequential execution.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed. **Always call this when a task is finished.**\n\n## Codebase Intelligence\n\n### Finding Code\n```\ncodebase_map()           # Get overview of project structure\ncodebase_find(\"UserService\")  # Find symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\n```\n\n### Impact Analysis\n```\nanalyze_impact(function_name: \"validateToken\")\n```\nSee what would be affected by changing a function.\n\n## Best Practices\n\n1. **Search before implementing** - Check memory for existing patterns\n2. **Store decisions** - Save architectural choices as facts\n3. **Use task tracking** - Break complex work into tasks\n4. **Complete tasks** - Always mark tasks done with summaries\n<!-- CLAUDETOOLS:END -->\n";
 /**
  * Project-level CLAUDE.md content - added to .claude/CLAUDE.md
  */

package/dist/templates/claude-md.js

@@ -47,7 +47,7 @@ Context is automatically injected at the start of each session based on the curr
 
 ## Task Management
 
-### Creating Work Plans
+### Creating Work Plans with Auto-Dispatch
 \`\`\`
 task_plan(
   goal: "Add user authentication",
@@ -55,19 +55,30 @@ task_plan(
   tasks: [...]
 )
 \`\`\`
-Break down complex work into tracked tasks.
+Break down complex work into tracked tasks. **Tasks are automatically set to \`ready\` status.**
 
-### Starting Tasks
+After \`task_plan\` completes, you will receive Task tool invocations to spawn parallel agents.
+**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.
+
+### Parallel Agent Workflow
+1. User describes work needed
+2. Call \`task_plan_draft\` to present the plan
+3. User says "go" to approve
+4. Call \`task_plan\` - tasks created in \`ready\` status
+5. Execute the provided Task tool calls in ONE message
+6. Agents work in parallel, each calling \`task_complete\` when done
+
+### Manual Task Start (Sequential)
 \`\`\`
 task_start(task_id: "task_xxx")
 \`\`\`
-Claim a task before working on it.
+Claim a task before working on it. Use for sequential execution.
 
 ### Completing Tasks
 \`\`\`
 task_complete(task_id: "task_xxx", summary: "Implemented JWT auth with refresh tokens")
 \`\`\`
-Mark tasks done with a summary of work completed.
+Mark tasks done with a summary of work completed. **Always call this when a task is finished.**
 
 ## Codebase Intelligence